@sumicom/quicksave 0.8.5 → 0.8.7

package/dist/ai/attachmentStore.js

@@ -0,0 +1,173 @@
+// SPDX-FileCopyrightText: 2026 King Young Technology
+// SPDX-License-Identifier: MIT
+// ============================================================================
+// Persistent attachment store on the agent.
+//
+// Once `attachmentStaging.consume(...)` materializes an `Attachment[]` for a
+// `claude:start` / `claude:resume`, the messageHandler also writes each
+// attachment to disk under
+//
+//   <state>/attachments/<sessionId>/<attachmentId>.bin    (base64-decoded bytes)
+//   <state>/attachments/<sessionId>/<attachmentId>.meta.json
+//
+// The PWA fetches bytes on demand via `attachment:fetch { sessionId, id }`,
+// caches them in `attachmentCache` (L1/L2), and renders chip thumbnails
+// without dragging the data through every card-history snapshot.
+//
+// Cleanup happens on session end-task: `removeSessionAttachments(sessionId)`
+// nukes the directory.
+// ============================================================================
+import { mkdir, readFile, writeFile, appendFile, rm, readdir, stat } from 'fs/promises';
+import { join } from 'path';
+import { getAttachmentsDir } from '../service/singleton.js';
+function dirFor(sessionId) {
+    return join(getAttachmentsDir(), sessionId);
+}
+function binPathFor(sessionId, attachmentId) {
+    return join(dirFor(sessionId), `${attachmentId}.bin`);
+}
+function metaPathFor(sessionId, attachmentId) {
+    return join(dirFor(sessionId), `${attachmentId}.meta.json`);
+}
+function turnManifestPathFor(sessionId) {
+    return join(dirFor(sessionId), 'turn-manifest.jsonl');
+}
+/**
+ * Persist a batch of resolved attachments under one session id. Idempotent
+ * per id — re-writing the same id overwrites both files.
+ */
+export async function persistAttachments(sessionId, attachments) {
+    if (attachments.length === 0)
+        return;
+    await mkdir(dirFor(sessionId), { recursive: true });
+    await Promise.all(attachments.map(async (a) => {
+        const bytes = Buffer.from(a.data, 'base64');
+        await writeFile(binPathFor(sessionId, a.id), bytes);
+        const meta = {
+            id: a.id,
+            kind: a.kind,
+            mimeType: a.mimeType,
+            name: a.name,
+            size: a.size,
+            storedAt: Date.now(),
+        };
+        await writeFile(metaPathFor(sessionId, a.id), JSON.stringify(meta));
+    }));
+    // Append a turn-manifest line so the cardBuilder can rebind on JSONL replay
+    // by exact UUID instead of falling back to fuzzy (kind+size+name) match.
+    // One line per attachment-bearing user turn, in send order.
+    const line = JSON.stringify({ ids: attachments.map((a) => a.id) }) + '\n';
+    await appendFile(turnManifestPathFor(sessionId), line);
+}
+/**
+ * Read the per-session attachment turn manifest in send order. Returns an
+ * empty array if no manifest exists yet (e.g. a session whose attachments
+ * predate this code), letting callers fall back to fuzzy rebind.
+ */
+export async function readTurnManifest(sessionId) {
+    let raw;
+    try {
+        raw = await readFile(turnManifestPathFor(sessionId), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && Array.isArray(parsed.ids) && parsed.ids.every((x) => typeof x === 'string')) {
+                out.push({ ids: parsed.ids });
+            }
+        }
+        catch {
+            // skip malformed line — don't break the whole replay
+        }
+    }
+    return out;
+}
+/**
+ * Read one attachment's bytes back, returning the wire `Attachment` shape
+ * (metadata + base64 data). Returns `null` if the attachment isn't on disk
+ * — e.g. session was end-tasked, or the JSONL had an attachment we didn't
+ * persist (cold-start session before this code shipped).
+ */
+export async function loadAttachment(sessionId, attachmentId) {
+    let metaRaw;
+    let bytes;
+    try {
+        [metaRaw, bytes] = await Promise.all([
+            readFile(metaPathFor(sessionId, attachmentId), 'utf8'),
+            readFile(binPathFor(sessionId, attachmentId)),
+        ]);
+    }
+    catch {
+        return null;
+    }
+    let meta;
+    try {
+        meta = JSON.parse(metaRaw);
+    }
+    catch {
+        return null;
+    }
+    return {
+        id: meta.id,
+        kind: meta.kind,
+        mimeType: meta.mimeType,
+        name: meta.name,
+        size: meta.size,
+        data: bytes.toString('base64'),
+    };
+}
+/** Drop every persisted attachment for one session (called on end-task). */
+export async function removeSessionAttachments(sessionId) {
+    try {
+        await rm(dirFor(sessionId), { recursive: true, force: true });
+    }
+    catch {
+        // best effort — orphaned files are tolerable, they're local-only
+    }
+}
+/**
+ * List metadata for every attachment persisted under a session id. Mainly
+ * for diagnostics / tests.
+ */
+export async function listSessionAttachments(sessionId) {
+    let entries;
+    try {
+        entries = await readdir(dirFor(sessionId));
+    }
+    catch {
+        return [];
+    }
+    const metas = [];
+    for (const name of entries) {
+        if (!name.endsWith('.meta.json'))
+            continue;
+        try {
+            const raw = await readFile(join(dirFor(sessionId), name), 'utf8');
+            metas.push(JSON.parse(raw));
+        }
+        catch {
+            // skip unreadable metas
+        }
+    }
+    return metas;
+}
+/** True if the meta+bin pair exist on disk — without reading the bytes. */
+export async function hasPersistedAttachment(sessionId, attachmentId) {
+    try {
+        await Promise.all([
+            stat(metaPathFor(sessionId, attachmentId)),
+            stat(binPathFor(sessionId, attachmentId)),
+        ]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=attachmentStore.js.map

package/dist/ai/attachmentStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachmentStore.js","sourceRoot":"","sources":["../../src/ai/attachmentStore.ts"],"names":[],"mappings":"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"}

package/dist/ai/cardBuilder.d.ts

@@ -1,4 +1,4 @@
-import type { Card, CardId, CardEvent, CardHistoryResponse, PendingInputAttachment } from '@sumicom/quicksave-shared';
+import type { Attachment, Card, CardId, CardEvent, CardHistoryResponse, PendingInputAttachment } from '@sumicom/quicksave-shared';
 /**
  * Load persisted card history for a memory-mode session.
  * Returns cards in insertion order, or empty array if none exist.
@@ -6,7 +6,6 @@ import type { Card, CardId, CardEvent, CardHistoryResponse, PendingInputAttachme
 export declare function loadPersistedCards(sessionId: string): Promise<Card[]>;
 export declare class StreamCardBuilder {
     private sessionId;
-    private streamId;
     private cwd;
     private seq;
     private cards;
@@ -23,10 +22,10 @@ export declare class StreamCardBuilder {
     /** Token identifying an in-flight deferred clear. A later call (new turn, cancel)
      * replaces this token, causing the pending polling task to bail out. */
     private _pendingClearToken;
-    constructor(sessionId: string, streamId: string, cwd: string);
+    constructor(sessionId: string, cwd: string);
     updateSessionId(sessionId: string): void;
-    /** Start a new turn: update streamId and reset per-turn state, keep accumulated cards. */
-    startNewTurn(streamId: string): void;
+    /** Start a new turn: reset per-turn state, keep accumulated cards. */
+    startNewTurn(): void;
     /** Clear all accumulated cards. Call after a turn completes and JSONL is flushed. */
     clearCards(): void;
     /**
@@ -68,7 +67,7 @@ export declare class StreamCardBuilder {
     private updateEvent;
     private appendTextEvent;
     private removeEvent;
-    userMessage(text: string): CardEvent;
+    userMessage(text: string, attachments?: readonly Attachment[]): CardEvent;
     thinkingBlock(text: string): CardEvent;
     /**
      * Append text to current assistant_text card, or create a new one.
@@ -107,6 +106,7 @@ export declare class StreamCardBuilder {
     subagentProgress(agentId: string, toolUseId: string | undefined, toolUseCount?: number, lastToolName?: string): CardEvent | null;
     subagentEnd(agentId: string, toolUseId: string | undefined, status: 'completed' | 'failed' | 'stopped', summary?: string): CardEvent | null;
     systemMessage(text: string, subtype?: 'compacted' | 'cost' | 'error' | 'info' | 'warning'): CardEvent;
+    recoverySuggested(reason: string, action: 'compact', label: string): CardEvent;
     errorMessage(text: string): CardEvent;
 }
 export declare function buildCardsFromHistory(sessionId: string, cwd: string, offset?: number, limit?: number, cutoffBytes?: number): Promise<CardHistoryResponse>;

package/dist/ai/cardBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cardBuilder.d.ts","sourceRoot":"","sources":["../../src/ai/cardBuilder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cardBuilder.d.ts","sourceRoot":"","sources":["../../src/ai/cardBuilder.ts"],"names":[],"mappings":"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"}

package/dist/ai/cardBuilder.js

@@ -4,6 +4,43 @@ import { createReadStream, existsSync } from 'fs';
 import { createInterface } from 'readline';
 import { homedir } from 'os';
 import { getCardHistoryDir } from '../service/singleton.js';
+import { listSessionAttachments, readTurnManifest } from './attachmentStore.js';
+/** Decoded byte length of a base64 string, accounting for `=` padding. */
+function decodedBase64Bytes(base64) {
+    if (typeof base64 !== 'string')
+        return 0;
+    const len = base64.length;
+    const padding = base64.endsWith('==') ? 2 : base64.endsWith('=') ? 1 : 0;
+    return Math.floor((len * 3) / 4) - padding;
+}
+/** Pool that lets us look up a persisted attachment by `(kind, size)` —
+ *  optionally name-tiebroken — and remove it so duplicates match correctly.
+ *  Used to recover the original upload UUIDs for attachments rebuilt from
+ *  JSONL (which doesn't carry our ids). */
+function makeAttachmentResolver(metas) {
+    const pool = new Map();
+    for (const m of metas) {
+        const key = `${m.kind}:${m.size}`;
+        const list = pool.get(key) ?? [];
+        list.push(m);
+        pool.set(key, list);
+    }
+    return function consume(kind, size, name) {
+        const list = pool.get(`${kind}:${size}`);
+        if (!list || list.length === 0)
+            return null;
+        let idx = 0;
+        if (name !== undefined) {
+            const named = list.findIndex((m) => m.name === name);
+            if (named >= 0)
+                idx = named;
+        }
+        const [matched] = list.splice(idx, 1);
+        if (list.length === 0)
+            pool.delete(`${kind}:${size}`);
+        return matched;
+    };
+}
 const TOOL_RESULT_TRUNCATE_LENGTH = 500;
 // ── Card history persistence (for memory-mode providers like Codex) ──
 function cardHistoryPath(sessionId) {
@@ -188,7 +225,6 @@ function extractToolResultText(content) {
 // ============================================================================
 export class StreamCardBuilder {
     sessionId;
-    streamId;
     cwd;
     seq = 0;
     cards = new Map();
@@ -205,17 +241,15 @@ export class StreamCardBuilder {
     /** Token identifying an in-flight deferred clear. A later call (new turn, cancel)
      * replaces this token, causing the pending polling task to bail out. */
     _pendingClearToken = null;
-    constructor(sessionId, streamId, cwd) {
+    constructor(sessionId, cwd) {
         this.sessionId = sessionId;
-        this.streamId = streamId;
         this.cwd = cwd;
     }
     updateSessionId(sessionId) {
         this.sessionId = sessionId;
     }
-    /** Start a new turn: update streamId and reset per-turn state, keep accumulated cards. */
-    startNewTurn(streamId) {
-        this.streamId = streamId;
+    /** Start a new turn: reset per-turn state, keep accumulated cards. */
+    startNewTurn() {
         this.currentTextCardId = null;
     }
     /** Clear all accumulated cards. Call after a turn completes and JSONL is flushed. */
@@ -344,11 +378,11 @@ export class StreamCardBuilder {
         this._jsonlCutoff = value;
     }
     nextId() {
-        return `${this.sessionId}:${this.streamId}:${++this.seq}`;
+        return `${this.sessionId}:${++this.seq}`;
     }
     addEvent(card, afterCardId) {
         this.cards.set(card.id, card);
-        return { type: 'add', streamId: this.streamId, sessionId: this.sessionId, card, afterCardId };
+        return { type: 'add', sessionId: this.sessionId, card, afterCardId };
     }
     updateEvent(cardId, patch) {
         const existing = this.cards.get(cardId);
@@ -365,23 +399,40 @@ export class StreamCardBuilder {
                     bag[key] = value;
             }
         }
-        return { type: 'update', streamId: this.streamId, sessionId: this.sessionId, cardId, patch };
+        return { type: 'update', sessionId: this.sessionId, cardId, patch };
     }
     appendTextEvent(cardId, text) {
         const existing = this.cards.get(cardId);
         if (existing && 'text' in existing) {
             existing.text += text;
         }
-        return { type: 'append_text', streamId: this.streamId, sessionId: this.sessionId, cardId, text };
+        return { type: 'append_text', sessionId: this.sessionId, cardId, text };
     }
     removeEvent(cardId) {
         this.cards.delete(cardId);
-        return { type: 'remove', streamId: this.streamId, sessionId: this.sessionId, cardId };
+        return { type: 'remove', sessionId: this.sessionId, cardId };
     }
     // ── Public: produce CardEvents from SDK data ────────────────────────────
-    userMessage(text) {
+    userMessage(text, attachments) {
         this.currentTextCardId = null;
-        const card = { type: 'user', id: this.nextId(), timestamp: Date.now(), text };
+        // UserCard.attachments only carries metadata — bytes are fetched on
+        // demand via `attachment:fetch`, not piped through every snapshot.
+        const metadata = attachments && attachments.length > 0
+            ? attachments.map((a) => ({
+                id: a.id,
+                kind: a.kind,
+                mimeType: a.mimeType,
+                name: a.name,
+                size: a.size,
+            }))
+            : undefined;
+        const card = {
+            type: 'user',
+            id: this.nextId(),
+            timestamp: Date.now(),
+            text,
+            ...(metadata ? { attachments: metadata } : {}),
+        };
         return this.addEvent(card);
     }
     thinkingBlock(text) {
@@ -553,6 +604,17 @@ export class StreamCardBuilder {
         const card = { type: 'system', id: this.nextId(), timestamp: Date.now(), text, subtype };
         return this.addEvent(card);
     }
+    recoverySuggested(reason, action, label) {
+        const card = {
+            type: 'recovery_suggested',
+            id: this.nextId(),
+            timestamp: Date.now(),
+            reason,
+            action,
+            label,
+        };
+        return this.addEvent(card);
+    }
     errorMessage(text) {
         return this.systemMessage(`Error: ${text}`, 'error');
     }
@@ -681,6 +743,20 @@ export async function buildCardsFromHistory(sessionId, cwd, offset = 0, limit =
             toolUseIdToAgentId.set(toolUseId, toolUseId);
         }
     }
+    // ── Load persisted attachment metas + turn manifest so we can rebind
+    //    synthetic `replay:N` ids in user blocks back to the real upload UUIDs
+    //    the PWA needs for `attachment:fetch`. Manifest gives an exact-UUID
+    //    match per turn (preferred); the fuzzy `(kind, size, name)` resolver is
+    //    the fallback for sessions whose attachments predate the manifest.
+    const [persistedMetas, turnManifest] = await Promise.all([
+        listSessionAttachments(sessionId).catch(() => []),
+        readTurnManifest(sessionId).catch(() => []),
+    ]);
+    const metaById = new Map();
+    for (const m of persistedMetas)
+        metaById.set(m.id, m);
+    const resolveAttachment = makeAttachmentResolver(persistedMetas);
+    let attachmentTurnCursor = 0;
     // ── Pass 2: Build Cards from sliced messages ───────────────────────────
     let seq = Math.max(0, total - offset - limit);
     const nextId = () => `${sessionId}:h:${++seq}`;
@@ -716,12 +792,84 @@ export async function buildCardsFromHistory(sessionId, cwd, offset = 0, limit =
                 continue;
             }
             if (Array.isArray(rawMessage.content)) {
+                // A user turn that came in with attachments is one logical card with
+                // image/document/text blocks in some order. We collapse all text
+                // blocks into a single `text` field and reconstruct AttachmentMetadata
+                // records from image/document blocks (no bytes — those live in the
+                // attachmentStore on disk and are fetched on demand). Pure text-only
+                // turns still produce one card per text block (back-compat).
+                //
+                // Replayed attachment ids do NOT round-trip through JSONL. We
+                // recover the original upload UUIDs by matching each block against
+                // the persisted-meta pool by `(kind, decoded byte size [, name])`;
+                // an unmatched block falls back to a synthetic `replay:<n>` id and
+                // its chip will render as "Unavailable" (bytes lost or not yet
+                // persistent).
+                const attachments = [];
+                const textParts = [];
+                let hasNonTextBlock = false;
+                // Pre-scan the block array for attachment blocks so we know whether
+                // to consume a manifest entry for this turn (an attachment-bearing
+                // user turn contributes exactly one manifest line, in send order).
+                const turnHasAttachment = rawMessage.content.some((b) => (b?.type === 'image' && b.source?.type === 'base64') ||
+                    (b?.type === 'document' && b.source?.type === 'base64' && b.source.media_type === 'application/pdf'));
+                const turnEntry = turnHasAttachment ? turnManifest[attachmentTurnCursor] : undefined;
+                if (turnHasAttachment)
+                    attachmentTurnCursor++;
+                let manifestIdx = 0;
                 for (const block of rawMessage.content) {
-                    if (block.type === 'text') {
-                        cards.push({ type: 'user', id: nextId(), timestamp: Date.now(), text: block.text });
+                    if (block?.type === 'image' && block.source?.type === 'base64') {
+                        hasNonTextBlock = true;
+                        const size = decodedBase64Bytes(block.source.data);
+                        const mimeType = typeof block.source.media_type === 'string' ? block.source.media_type : 'image/png';
+                        const manifestId = turnEntry?.ids[manifestIdx++];
+                        const exact = manifestId ? metaById.get(manifestId) : undefined;
+                        const matched = exact && exact.kind === 'image' && exact.size === size
+                            ? exact
+                            : resolveAttachment('image', size);
+                        attachments.push(matched
+                            ? { id: matched.id, kind: matched.kind, mimeType: matched.mimeType, name: matched.name, size: matched.size }
+                            : { id: `replay:${nextId()}`, kind: 'image', mimeType, name: 'attachment', size });
+                    }
+                    else if (block?.type === 'document' && block.source?.type === 'base64' && block.source.media_type === 'application/pdf') {
+                        hasNonTextBlock = true;
+                        const size = decodedBase64Bytes(block.source.data);
+                        const name = typeof block.title === 'string' && block.title.length > 0 ? block.title : 'document.pdf';
+                        const manifestId = turnEntry?.ids[manifestIdx++];
+                        const exact = manifestId ? metaById.get(manifestId) : undefined;
+                        const matched = exact && exact.kind === 'pdf' && exact.size === size
+                            ? exact
+                            : resolveAttachment('pdf', size, name);
+                        attachments.push(matched
+                            ? { id: matched.id, kind: matched.kind, mimeType: matched.mimeType, name: matched.name, size: matched.size }
+                            : { id: `replay:${nextId()}`, kind: 'pdf', mimeType: 'application/pdf', name, size });
+                    }
+                    else if (block?.type === 'text' && typeof block.text === 'string') {
+                        textParts.push(block.text);
                     }
                     // tool_result blocks are paired into ToolCallCard.result (handled below)
-                    // Skip them here — they don't need separate cards
+                    // Skip them here — they don't need separate cards.
+                }
+                if (hasNonTextBlock) {
+                    const card = {
+                        type: 'user',
+                        id: nextId(),
+                        timestamp: Date.now(),
+                        text: textParts.join('\n'),
+                        ...(attachments.length > 0 ? { attachments } : {}),
+                    };
+                    cards.push(card);
+                }
+                else {
+                    // No image/pdf — fall back to one card per text block, preserving
+                    // the older multi-card behavior for plain user turns (e.g. when a
+                    // tool_result block is present alongside a text block, and only
+                    // the text block makes a user card).
+                    for (const block of rawMessage.content) {
+                        if (block?.type === 'text' && typeof block.text === 'string') {
+                            cards.push({ type: 'user', id: nextId(), timestamp: Date.now(), text: block.text });
+                        }
+                    }
                 }
                 continue;
             }