fix: preserve library cards in compact chat rows (raphaeltm#1524)

simple-agent-manager[bot] · raphaeltm · web-flow · commit c07886a9fab2 · 2026-07-06T23:01:55.000Z
Co-authored-by: Raphaël Titsworth-Morin &lt;raphael@raphaeltm.com&gt;
diff --git a/apps/api/.env.example b/apps/api/.env.example
@@ -436,6 +436,7 @@ BASE_DOMAIN=workspaces.example.com
 # Project Data Durable Object limits
 # MAX_SESSIONS_PER_PROJECT=10000
 # MAX_MESSAGES_PER_SESSION=100000
+# DOCUMENT_CARD_RAW_OUTPUT_MAX_BYTES=16384
 # MESSAGE_SIZE_THRESHOLD=102400
 # ACTIVITY_RETENTION_DAYS=90
 # SESSION_IDLE_TIMEOUT_MINUTES=60
diff --git a/apps/api/src/durable-objects/project-data/index.ts b/apps/api/src/durable-objects/project-data/index.ts
@@ -149,7 +149,8 @@ export class ProjectData extends DurableObject<Env> {
   }
 
   async getMessages(sessionId: string, limit: number = 1000, before: number | null = null, roles?: string[], compact: boolean = false, order: 'asc' | 'desc' = 'desc') {
-    return messages.getMessages(this.sql, sessionId, limit, before, roles, compact, order);
+    const compactOptions = compact ? messages.resolveCompactMessageOptions(this.env) : undefined;
+    return messages.getMessages(this.sql, sessionId, limit, before, roles, compact, order, compactOptions);
   }
 
   async getMessageToolContent(sessionId: string, messageId: string): Promise<unknown[] | null> {
diff --git a/apps/api/src/durable-objects/project-data/messages.ts b/apps/api/src/durable-objects/project-data/messages.ts
@@ -4,6 +4,8 @@
 import { buildSafeFtsQuery } from '../../lib/fts5';
 import { log } from '../../lib/logger';
 import {
+  type CompactMessageOptions,
+  DEFAULT_DOCUMENT_CARD_RAW_OUTPUT_MAX_BYTES,
   parseChatMessageRow,
   parseChatMessageRowCompact,
   parseCount,
@@ -35,6 +37,16 @@ function resolveMaxMessagesPerSession(env: Env): number {
   return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_MESSAGES_PER_SESSION;
 }
 
+export function resolveCompactMessageOptions(env: Env): CompactMessageOptions {
+  const parsed = Number.parseInt(env.DOCUMENT_CARD_RAW_OUTPUT_MAX_BYTES || '', 10);
+  return {
+    documentCardRawOutputMaxBytes:
+      Number.isFinite(parsed) && parsed > 0
+        ? parsed
+        : DEFAULT_DOCUMENT_CARD_RAW_OUTPUT_MAX_BYTES,
+  };
+}
+
 /**
  * Returns the next monotonic sequence number for a session's messages.
  */
@@ -335,7 +347,8 @@ export function getMessages(
   before: number | null = null,
   roles?: string[],
   compact: boolean = false,
-  order: 'asc' | 'desc' = 'desc'
+  order: 'asc' | 'desc' = 'desc',
+  compactOptions?: CompactMessageOptions
 ): { messages: Record<string, unknown>[]; hasMore: boolean } {
   let query =
     'SELECT id, session_id, role, content, tool_metadata, created_at, sequence FROM chat_messages WHERE session_id = ?';
@@ -386,10 +399,11 @@ export function getMessages(
 
   const trimmedRows = candidateRows.slice(0, safeCount);
 
-  const rowParser = compact ? parseChatMessageRowCompact : parseChatMessageRow;
   const orderedRows = order === 'desc' ? trimmedRows.reverse() : trimmedRows;
   return {
-    messages: orderedRows.map((row) => rowParser(row)),
+    messages: orderedRows.map((row) =>
+      compact ? parseChatMessageRowCompact(row, compactOptions) : parseChatMessageRow(row)
+    ),
     hasMore,
   };
 }
diff --git a/apps/api/src/durable-objects/project-data/row-schemas.ts b/apps/api/src/durable-objects/project-data/row-schemas.ts
@@ -36,6 +36,8 @@ export {
 export { parseInboxMessageRow, parseMailboxMessageRow } from './row-schemas/mailbox';
 export { parseMaterializationCheck, parseMaterializationToken, parseRowid, parseSessionId } from './row-schemas/materialization';
 export {
+  type CompactMessageOptions,
+  DEFAULT_DOCUMENT_CARD_RAW_OUTPUT_MAX_BYTES,
   parseChatMessageRow,
   parseChatMessageRowCompact,
   parseSearchResultRow,
diff --git a/apps/api/src/durable-objects/project-data/row-schemas/messages.ts b/apps/api/src/durable-objects/project-data/row-schemas/messages.ts
@@ -44,7 +44,13 @@ export function parseChatMessageRow(row: unknown): {
  * tool_metadata and replaces it with a `contentSize` byte count.
  * This dramatically reduces RPC payload size for tool-heavy sessions.
  */
-export function parseChatMessageRowCompact(row: unknown): {
+export type CompactMessageOptions = {
+  documentCardRawOutputMaxBytes?: number;
+};
+
+export const DEFAULT_DOCUMENT_CARD_RAW_OUTPUT_MAX_BYTES = 16 * 1024;
+
+export function parseChatMessageRowCompact(row: unknown, options?: CompactMessageOptions): {
   id: string;
   sessionId: string;
   role: string;
@@ -55,7 +61,7 @@ export function parseChatMessageRowCompact(row: unknown): {
 } {
   const r = parseRow(ChatMessageRowSchema, row, 'chat_message');
   const parsed = safeParseJson(r.tool_metadata);
-  const toolMetadata = parsed === null ? null : stripToolMetadataContent(parsed);
+  const toolMetadata = parsed === null ? null : stripToolMetadataContent(parsed, options);
   return {
     id: r.id,
     sessionId: r.session_id,
@@ -73,18 +79,135 @@ export function parseChatMessageRowCompact(row: unknown): {
  * Preserves all other metadata fields (toolCallId, title, kind, status, locations).
  */
 const textEncoder = new TextEncoder();
+const DOCUMENT_CARD_TOOLS = new Set([
+  'upload_to_library',
+  'replace_library_file',
+  'display_from_library',
+]);
+const TOOL_NAME_SEPARATORS = /__|\/|\.|:/;
+
+function resolveDocumentCardRawOutputMaxBytes(options?: CompactMessageOptions): number {
+  const configured = options?.documentCardRawOutputMaxBytes;
+  return typeof configured === 'number' && Number.isFinite(configured) && configured > 0
+    ? Math.floor(configured)
+    : DEFAULT_DOCUMENT_CARD_RAW_OUTPUT_MAX_BYTES;
+}
+
+function normalizeToolName(toolName: unknown): string | undefined {
+  if (typeof toolName !== 'string' || !toolName) return undefined;
+  const segments = toolName.split(TOOL_NAME_SEPARATORS).filter(Boolean);
+  return segments.length > 0 ? segments[segments.length - 1] : toolName;
+}
+
+function isDocumentCardTool(meta: Record<string, unknown>): boolean {
+  const base = normalizeToolName(meta.toolName) ?? normalizeToolName(meta.title);
+  return Boolean(base && DOCUMENT_CARD_TOOLS.has(base));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function parseDocumentPayloadCandidate(
+  value: string,
+  maxBytes: number
+): Record<string, unknown> | undefined {
+  const trimmed = value.trim();
+  if (!trimmed || textEncoder.encode(trimmed).byteLength > maxBytes) {
+    return undefined;
+  }
+
+  const candidates = [trimmed];
+  const firstBrace = trimmed.indexOf('{');
+  const lastBrace = trimmed.lastIndexOf('}');
+  if (firstBrace >= 0 && lastBrace > firstBrace) {
+    candidates.push(trimmed.slice(firstBrace, lastBrace + 1));
+  }
+
+  for (const candidate of candidates) {
+    try {
+      const parsed: unknown = JSON.parse(candidate);
+      if (isRecord(parsed) && isDocumentResultPayload(parsed)) {
+        return parsed;
+      }
+    } catch {
+      // Try the next candidate.
+    }
+  }
+
+  return undefined;
+}
+
+function isDocumentResultPayload(payload: Record<string, unknown>): boolean {
+  if (typeof payload.fileId === 'string' || typeof payload.id === 'string') return true;
+  if (isRecord(payload.existingFile)) return true;
+  return payload.error === 'FILE_NOT_FOUND' || payload.error === 'FILE_EXISTS';
+}
+
+function findDocumentPayload(
+  value: unknown,
+  maxBytes: number,
+  depth = 0
+): Record<string, unknown> | undefined {
+  if (depth > 6 || value === null || value === undefined) return undefined;
+
+  if (typeof value === 'string') {
+    return parseDocumentPayloadCandidate(value, maxBytes);
+  }
+
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      const found = findDocumentPayload(entry, maxBytes, depth + 1);
+      if (found) return found;
+    }
+    return undefined;
+  }
+
+  if (!isRecord(value)) return undefined;
+
+  for (const key of ['text', 'output', 'content', 'result', 'message']) {
+    const found = findDocumentPayload(value[key], maxBytes, depth + 1);
+    if (found) return found;
+  }
+
+  return undefined;
+}
+
+function extractDocumentCardRawOutput(
+  meta: Record<string, unknown>,
+  contentArray: unknown[],
+  maxBytes: number
+): Array<{ type: 'text'; text: string }> | undefined {
+  if (!isDocumentCardTool(meta)) return undefined;
+  if (meta.rawOutput !== undefined && meta.rawOutput !== null) return undefined;
+
+  const payload = findDocumentPayload(contentArray, maxBytes);
+  if (!payload) return undefined;
+
+  const text = JSON.stringify(payload);
+  if (textEncoder.encode(text).byteLength > maxBytes) {
+    return undefined;
+  }
+
+  return [{ type: 'text', text }];
+}
 
-export function stripToolMetadataContent(meta: unknown): unknown {
+export function stripToolMetadataContent(meta: unknown, options?: CompactMessageOptions): unknown {
   if (!meta || typeof meta !== 'object') return meta;
   const obj = expectJsonRecord(meta, 'project-data.tool_metadata');
   const contentArray = obj.content;
   if (!Array.isArray(contentArray) || contentArray.length === 0) return meta;
 
   const contentJson = JSON.stringify(contentArray);
   const contentSize = textEncoder.encode(contentJson).byteLength;
+  const rawOutput = extractDocumentCardRawOutput(
+    obj,
+    contentArray,
+    resolveDocumentCardRawOutputMaxBytes(options)
+  );
 
   const rest = Object.fromEntries(Object.entries(obj).filter(([k]) => k !== 'content'));
-  return { ...rest, contentSize };
+  return rawOutput ? { ...rest, rawOutput, contentSize } : { ...rest, contentSize };
 }
 
 /** Search result row (message + session join) */
diff --git a/apps/api/src/durable-objects/project-data/types.ts b/apps/api/src/durable-objects/project-data/types.ts
@@ -8,6 +8,7 @@ export type Env = {
   DO_SUMMARY_SYNC_DEBOUNCE_MS?: string;
   MAX_SESSIONS_PER_PROJECT?: string;
   MAX_MESSAGES_PER_SESSION?: string;
+  DOCUMENT_CARD_RAW_OUTPUT_MAX_BYTES?: string;
   ACTIVITY_RETENTION_DAYS?: string;
   SESSION_IDLE_TIMEOUT_MINUTES?: string;
   IDLE_CLEANUP_RETRY_DELAY_MS?: string;
diff --git a/apps/api/src/env.ts b/apps/api/src/env.ts
@@ -271,6 +271,7 @@ export interface Env {
   CACHED_COMMANDS_MAX_DESC_LENGTH?: string;
   MAX_SESSIONS_PER_PROJECT?: string;
   MAX_MESSAGES_PER_SESSION?: string;
+  DOCUMENT_CARD_RAW_OUTPUT_MAX_BYTES?: string; // Max document-card rawOutput bytes preserved in compact message metadata (default: 16384)
   MESSAGE_SIZE_THRESHOLD?: string;
   ACTIVITY_RETENTION_DAYS?: string;
   SESSION_IDLE_TIMEOUT_MINUTES?: string;
diff --git a/apps/api/tests/unit/durable-objects/compact-mode.test.ts b/apps/api/tests/unit/durable-objects/compact-mode.test.ts
@@ -87,6 +87,76 @@ describe('stripToolMetadataContent', () => {
     expect(result.contentSize).toBeGreaterThan(100_000);
     expect(result.toolCallId).toBe('tc-big');
   });
+
+  it('preserves a document-card rawOutput payload while stripping compact content', () => {
+    const payload = {
+      fileId: '01KWV8QZ0PM59JS9YQSPVTCMCJ',
+      filename: 'sam-architecture-comprehensive.html',
+      mimeType: 'text/html; charset=utf-8',
+      sizeBytes: 51849,
+      caption: 'Newest comprehensive SAM architecture webpage.',
+    };
+    const meta = {
+      toolCallId: 'tc-display',
+      title: 'sam-mcp/display_from_library',
+      kind: 'other',
+      status: 'completed',
+      content: [
+        {
+          type: 'content',
+          content: { type: 'text', text: JSON.stringify(payload, null, 2) },
+        },
+      ],
+    };
+
+    const result = stripToolMetadataContent(meta) as Record<string, unknown>;
+
+    expect(result.content).toBeUndefined();
+    expect(result.contentSize).toBeGreaterThan(0);
+    expect(result.title).toBe('sam-mcp/display_from_library');
+    const rawOutput = result.rawOutput as Array<{ type: string; text: string }>;
+    expect(rawOutput).toHaveLength(1);
+    expect(rawOutput[0]?.type).toBe('text');
+    expect(JSON.parse(rawOutput[0]?.text ?? '{}')).toEqual(payload);
+  });
+
+  it('does not synthesize rawOutput for non-document tool content', () => {
+    const meta = {
+      toolCallId: 'tc-shell',
+      title: 'exec_command',
+      kind: 'other',
+      status: 'completed',
+      content: [{ type: 'content', text: '{"fileId":"not-a-library-card"}' }],
+    };
+
+    const result = stripToolMetadataContent(meta) as Record<string, unknown>;
+
+    expect(result.content).toBeUndefined();
+    expect(result.contentSize).toBeGreaterThan(0);
+    expect(result.rawOutput).toBeUndefined();
+  });
+
+  it('honors the document-card rawOutput byte budget', () => {
+    const meta = {
+      toolCallId: 'tc-display',
+      title: 'sam-mcp/display_from_library',
+      status: 'completed',
+      content: [
+        {
+          type: 'content',
+          text: '{"fileId":"01KWV8QZ0PM59JS9YQSPVTCMCJ","filename":"sam-architecture-comprehensive.html"}',
+        },
+      ],
+    };
+
+    const result = stripToolMetadataContent(meta, {
+      documentCardRawOutputMaxBytes: 16,
+    }) as Record<string, unknown>;
+
+    expect(result.content).toBeUndefined();
+    expect(result.contentSize).toBeGreaterThan(0);
+    expect(result.rawOutput).toBeUndefined();
+  });
 });
 
 describe('parseChatMessageRowCompact', () => {
diff --git a/apps/www/src/content/docs/docs/reference/configuration.md b/apps/www/src/content/docs/docs/reference/configuration.md
@@ -261,15 +261,16 @@ SAM loads OpenCode Zen and OpenCode Go model choices through the authenticated m
 
 ## Durable Object Limits
 
-| Variable                       | Default  | Description                        |
-| ------------------------------ | -------- | ---------------------------------- |
-| `MAX_SESSIONS_PER_PROJECT`     | `10000`  | Max chat sessions per project      |
-| `MAX_MESSAGES_PER_SESSION`     | `100000` | Max messages per chat session      |
-| `MESSAGE_SIZE_THRESHOLD`       | `102400` | Max message size in bytes          |
-| `ACTIVITY_RETENTION_DAYS`      | `90`     | Days to retain activity events     |
-| `SESSION_IDLE_TIMEOUT_MINUTES` | `60`     | Idle session timeout               |
-| `SESSION_ACTIVITY_STALE_THRESHOLD_MS` | `300000` (5 min) | Evidence threshold before stale working activity can be healed to idle |
-| `DO_SUMMARY_SYNC_DEBOUNCE_MS`  | `5000`   | Debounce for DO-to-D1 summary sync |
+| Variable                                  | Default            | Description                                                               |
+| ----------------------------------------- | ------------------ | ------------------------------------------------------------------------- |
+| `MAX_SESSIONS_PER_PROJECT`                | `10000`            | Max chat sessions per project                                             |
+| `MAX_MESSAGES_PER_SESSION`                | `100000`           | Max messages per chat session                                             |
+| `DOCUMENT_CARD_RAW_OUTPUT_MAX_BYTES`      | `16384`            | Max compact metadata bytes preserved for library document cards           |
+| `MESSAGE_SIZE_THRESHOLD`                  | `102400`           | Max message size in bytes                                                 |
+| `ACTIVITY_RETENTION_DAYS`                 | `90`               | Days to retain activity events                                            |
+| `SESSION_IDLE_TIMEOUT_MINUTES`            | `60`               | Idle session timeout                                                      |
+| `SESSION_ACTIVITY_STALE_THRESHOLD_MS`     | `300000` (5 min)   | Evidence threshold before stale working activity can be healed to idle    |
+| `DO_SUMMARY_SYNC_DEBOUNCE_MS`             | `5000`             | Debounce for DO-to-D1 summary sync                                        |
 
 ## Durable Object Retry
 

Original file line number	Diff line number	Diff line change
`@@ -149,7 +149,8 @@ export class ProjectData extends DurableObject<Env> {`
`149`	`149`	`}`
`150`	`150`
`151`	`151`	`async getMessages(sessionId: string, limit: number = 1000, before: number \| null = null, roles?: string[], compact: boolean = false, order: 'asc' \| 'desc' = 'desc') {`
`152`		`- return messages.getMessages(this.sql, sessionId, limit, before, roles, compact, order);`
	`152`	`+ const compactOptions = compact ? messages.resolveCompactMessageOptions(this.env) : undefined;`
	`153`	`+ return messages.getMessages(this.sql, sessionId, limit, before, roles, compact, order, compactOptions);`
`153`	`154`	`}`
`154`	`155`
`155`	`156`	`async getMessageToolContent(sessionId: string, messageId: string): Promise<unknown[] \| null> {`