@assethub/cli 0.1.30 → 0.1.32

package/dist/execution.js

@@ -1,4 +1,4 @@
-import { createHash, randomUUID } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
 import { stat } from 'node:fs/promises';
 import { isDeepStrictEqual } from 'node:util';
 import { join } from 'node:path';
@@ -35,8 +35,8 @@ export class CliExecutionError extends Error {
     operationId;
     execution;
     runId;
-    constructor(message, exitCode = 1, operationId, execution, runId = execution?.runId) {
-        super(message);
+    constructor(message, exitCode = 1, operationId, execution, runId = execution?.runId, options) {
+        super(message, options);
         this.exitCode = exitCode;
         this.operationId = operationId;
         this.execution = execution;
@@ -48,12 +48,6 @@ const MIN_POLL_INTERVAL_MS = 1_000;
 const POLL_JITTER_MS = 250;
 /** Kept only for SIGINT reporting; interrupting the client never cancels server work. */
 export const activeExecution = {};
-export const childOperationId = (parent, step) => {
-    const hash = createHash('sha256')
-        .update(JSON.stringify([parent, step]))
-        .digest('hex');
-    return `${hash.slice(0, 8)}-${hash.slice(8, 12)}-4${hash.slice(13, 16)}-8${hash.slice(17, 20)}-${hash.slice(20, 32)}`;
-};
 const operationPath = (stateDir, id) => {
     if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(id))
         throw new Error('Operation ID must be a UUID');
@@ -130,8 +124,11 @@ const submitSaved = async (session, saved, retryDelayMs = 250) => {
                 return { ...queued, execution: queued.execution };
             }
             catch (error) {
+                // The agent-run limit does not clear within a retry delay, and the
+                // server stores that rejection for this key: a retry only replays it.
                 const retryable = error instanceof TypeError ||
                     (error instanceof AssetHubApiError &&
+                        error.code !== 'AGENT_OWNER_LIMIT_EXCEEDED' &&
                         ([429, 502, 503, 504].includes(error.status) ||
                             error.code === 'IDEMPOTENCY_IN_PROGRESS'));
                 if (!retryable || attempt >= 2)
@@ -156,7 +153,7 @@ const submitSaved = async (session, saved, retryDelayMs = 250) => {
             (error.status < 500 ||
                 ['CANVAS_EXECUTION_UNAVAILABLE', 'EVALUATOR_UNAVAILABLE'].includes(error.code))
             ? 2
-            : 1, saved.operationId, activeExecution.execution, activeExecution.runId);
+            : 1, saved.operationId, activeExecution.execution, activeExecution.runId, { cause: error });
     }
 };
 export const executeRecorded = async (session, operation, body, options = {}) => {
@@ -164,12 +161,14 @@ export const executeRecorded = async (session, operation, body, options = {}) =>
         throw new CliExecutionError(`Canvas execution history unavailable: ${operation}`, 2);
     const operationId = options.operationId ?? randomUUID();
     const path = operationPath(session.stateDir, operationId);
-    const batchReserved = await stat(join(session.stateDir, 'node-batches', `${operationId}.json`)).then(() => true, error => {
+    const reservedBy = async (dir) => stat(join(session.stateDir, dir, `${operationId}.json`)).then(() => true, error => {
         if (error.code === 'ENOENT')
             return false;
         throw error;
     });
-    if (batchReserved)
+    if (await reservedBy('production-batches'))
+        throw new CliExecutionError('Operation ID belongs to a production batch; rerun production batch with it or use a new operation ID', 2, operationId);
+    if (await reservedBy('node-batches'))
         throw new CliExecutionError('Operation ID belongs to a different node batch; use runs resume or a new operation ID', 2, operationId);
     const saved = JSON.parse(JSON.stringify({
         operation,

package/dist/hooks/command.d.ts

@@ -0,0 +1,14 @@
+export type HooksCommandDeps = {
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    cliPath?: string;
+    readStdin?: () => Promise<string>;
+    write?: (text: string) => void;
+    fetchImpl?: typeof fetch;
+    now?: () => Date;
+    startUpload?: (sessionDir: string, profile?: string) => void;
+    startSweep?: (profile?: string) => void;
+};
+export declare const runHooksCommand: (argv: string[], deps?: HooksCommandDeps) => Promise<number>;
+//# sourceMappingURL=command.d.ts.map

package/dist/hooks/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/hooks/command.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;IACjC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;IAChB,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC5D,UAAU,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CACxC,CAAA;AA+CD,eAAO,MAAM,eAAe,GAC1B,MAAM,MAAM,EAAE,EACd,OAAM,gBAAqB,KAC1B,OAAO,CAAC,MAAM,CAiIhB,CAAA"}

package/dist/hooks/command.js

@@ -0,0 +1,181 @@
+// `assethub hooks <subcommand>` — the registration in src/index.ts just calls
+// runHooksCommand(argv).
+import { installHooks, sessionSaveDisclosure, uninstallHooks } from './install.js';
+import { listSessionDirs, readMeta } from './paths.js';
+import { saveSession } from './save.js';
+import { canUploadSessions, resolveUploadAuth, uploadPending, uploadSession } from './upload.js';
+const USAGE = 'Usage: assethub hooks <install|uninstall|save|upload|list|status> [--client claude|codex] [--json]\n' +
+    '  install|uninstall [--global]   (the current folder by default; --global for every project)\n' +
+    '  save [--client codex] [--transcript <path> --session-id <id>]   (reads hook JSON from stdin without flags)\n' +
+    '  upload [--session <dir> [--auto] [--sweep <n>]|--pending [--force] [--limit <n>]]\n' +
+    '         --auto and --pending wait out earlier failures (1h, 2h, 4h … up to a day); --force retries now';
+const parseFlags = (args) => {
+    const flags = {};
+    const rest = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (!arg.startsWith('--')) {
+            rest.push(arg);
+            continue;
+        }
+        const [name, inline] = arg.slice(2).split('=', 2);
+        if (inline !== undefined)
+            flags[name] = inline;
+        else if (args[i + 1] !== undefined && !args[i + 1].startsWith('--'))
+            flags[name] = args[++i];
+        else
+            flags[name] = true;
+    }
+    return { flags, rest };
+};
+const limitFlag = (value) => {
+    const n = typeof value === 'string' ? Number.parseInt(value, 10) : Number.NaN;
+    return Number.isSafeInteger(n) && n >= 0 ? n : undefined;
+};
+const defaultReadStdin = () => new Promise(resolve => {
+    if (process.stdin.isTTY)
+        return resolve('');
+    const chunks = [];
+    const timer = setTimeout(() => resolve(Buffer.concat(chunks).toString('utf8')), 2000);
+    process.stdin.on('data', chunk => chunks.push(Buffer.from(chunk)));
+    process.stdin.on('end', () => {
+        clearTimeout(timer);
+        resolve(Buffer.concat(chunks).toString('utf8'));
+    });
+    process.stdin.on('error', () => {
+        clearTimeout(timer);
+        resolve('');
+    });
+});
+export const runHooksCommand = async (argv, deps = {}) => {
+    const write = deps.write ?? ((text) => process.stdout.write(text));
+    const { flags, rest } = parseFlags(argv);
+    const json = flags.json === true;
+    const out = (human, data) => write(json ? `${JSON.stringify(data)}\n` : `${human}\n`);
+    const [sub] = rest;
+    const uploadOptions = {
+        home: deps.home,
+        env: deps.env,
+        fetchImpl: deps.fetchImpl,
+        now: deps.now,
+        profile: typeof flags.profile === 'string' ? flags.profile : undefined,
+    };
+    try {
+        switch (sub) {
+            case 'install':
+            case 'uninstall': {
+                const client = flags.client;
+                if (client !== 'claude' && client !== 'codex') {
+                    write('--client claude|codex is required\n');
+                    return 2;
+                }
+                // Sessions are saved only where the hooks are: this folder, unless --global.
+                const scope = flags.global === true ? {} : { projectDir: deps.cwd ?? process.cwd() };
+                const paths = { home: deps.home, codexHome: (deps.env ?? process.env).CODEX_HOME?.trim() || undefined };
+                if (sub === 'install') {
+                    // Only accounts that may upload sessions (internal for now) can turn
+                    // session saving on; for anyone else the hooks would only pile up.
+                    const auth = await resolveUploadAuth(uploadOptions);
+                    if (!auth || !(await canUploadSessions(auth, deps.fetchImpl))) {
+                        write('Session saving is not available for this account.\n');
+                        return 1;
+                    }
+                    const result = await installHooks({ ...scope, ...paths, client, cliPath: deps.cliPath });
+                    out(result.installed ? `${result.detail}\n${sessionSaveDisclosure(scope, client)}` : result.detail, result);
+                    return result.installed ? 0 : 1;
+                }
+                const result = await uninstallHooks({ ...scope, ...paths, client });
+                out(result.detail, result);
+                return 0;
+            }
+            case 'save': {
+                // A misspelt client must not be saved as Claude. Exit 1, not 2: a
+                // hook's exit 2 can block the agent.
+                if (flags.client !== undefined && flags.client !== 'claude' && flags.client !== 'codex') {
+                    write('Nothing saved: use --client claude or --client codex.\n');
+                    return 1;
+                }
+                let stdin;
+                let input;
+                if (typeof flags.transcript === 'string') {
+                    input = {
+                        session_id: typeof flags['session-id'] === 'string' ? flags['session-id'] : `manual-${Date.now()}`,
+                        transcript_path: flags.transcript,
+                        cwd: deps.cwd ?? process.cwd(),
+                        hook_event_name: 'Manual',
+                    };
+                }
+                else {
+                    stdin = await (deps.readStdin ?? defaultReadStdin)();
+                }
+                const result = await saveSession({
+                    stdin,
+                    input,
+                    client: flags.client === 'codex' ? 'codex' : 'claude',
+                    home: deps.home,
+                    env: deps.env,
+                    now: deps.now,
+                    upload: { profile: uploadOptions.profile },
+                    startUpload: deps.startUpload,
+                    startSweep: deps.startSweep,
+                });
+                // A hook must never fail the agent, so save always exits 0.
+                // Claude Code adds SessionStart hook output to the model's context, so
+                // that hook stays silent.
+                if (result.event !== 'SessionStart') {
+                    out(result.sessionDir ? `Saved ${result.sessionDir}` : `Nothing saved${result.skipped ? ` (${result.skipped})` : ''}`, result);
+                }
+                return 0;
+            }
+            case 'upload': {
+                if (typeof flags.session === 'string') {
+                    // A manual upload retries now; the detached SessionEnd upload (--auto)
+                    // honours the once-a-day limit after a no-upload-access answer.
+                    const outcome = await uploadSession(flags.session, { ...uploadOptions, force: flags.auto !== true });
+                    out(outcome.ok ? `Uploaded ${outcome.graphId}` : `Not uploaded: ${outcome.reason}`, outcome);
+                    // --sweep N: then retry up to N older pending sessions (SessionEnd does this).
+                    const sweep = limitFlag(flags.sweep);
+                    if (sweep !== undefined && sweep > 0) {
+                        await uploadPending({ ...uploadOptions, force: false, limit: sweep, exclude: flags.session });
+                    }
+                    return outcome.ok ? 0 : 1;
+                }
+                const results = await uploadPending({
+                    ...uploadOptions,
+                    force: flags.force === true,
+                    limit: limitFlag(flags.limit),
+                });
+                const failed = results.filter(r => !r.outcome.ok).length;
+                out(`${results.length - failed}/${results.length} pending sessions uploaded`, results);
+                return failed ? 1 : 0;
+            }
+            case 'list':
+            case 'status': {
+                const rows = [];
+                for (const dir of await listSessionDirs(deps.home)) {
+                    const meta = await readMeta(dir);
+                    if (meta)
+                        rows.push({ dir, sessionId: meta.sessionId, status: meta.status, lastEvent: meta.lastEvent, reason: meta.reason });
+                }
+                if (sub === 'status') {
+                    const counts = rows.reduce((acc, r) => {
+                        acc[r.status] = (acc[r.status] ?? 0) + 1;
+                        return acc;
+                    }, {});
+                    out(`${rows.length} sessions: ${JSON.stringify(counts)}`, { total: rows.length, counts });
+                }
+                else {
+                    out(rows.map(r => `${r.status.padEnd(15)} ${r.dir}${r.reason ? `  (${r.reason})` : ''}`).join('\n') || 'No saved sessions', rows);
+                }
+                return 0;
+            }
+            default:
+                write(`${USAGE}\n`);
+                return sub ? 2 : 0;
+        }
+    }
+    catch (error) {
+        write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+};

package/dist/hooks/graph.d.ts

@@ -0,0 +1,40 @@
+export declare const SESSION_GRAPH_FOLDER = "graph-folder";
+export declare const SESSION_GENERATOR = "assethub-cli:hooks.save";
+export declare const TRANSCRIPT_BLOB_MIME = "application/x-ndjson";
+/** Under the 4 MiB blob limit, with room to spare. */
+export declare const TRANSCRIPT_CHUNK_BYTES: number;
+/**
+ * Canonical bytes of the message and tool-call nodes kept in one snapshot. The
+ * push is refused over 4 MiB (CONTROL_MAX_PUSH_BYTES), and the edges, image
+ * and transcript nodes, manifest and envelope need the rest. A longer session
+ * keeps its newest messages in the index and records how many were left out;
+ * the transcript blobs still hold every one of them.
+ */
+export declare const MAX_MESSAGE_NODE_BYTES: number;
+/**
+ * Compaction after an upload failed for size or time. Each level halves the
+ * index budget and the per-message clips; from level 2 on images stay local.
+ * The transcript blobs are never dropped: they are the record.
+ */
+export declare const MAX_COMPACT_LEVEL = 4;
+type Limits = {
+    indexBytes: number;
+    textChars: number;
+    toolInputBytes: number;
+    images: boolean;
+};
+export declare const compactLimits: (level: number) => Limits;
+export declare const sessionGraphId: (sessionDirName: string) => string;
+/**
+ * Cut on line boundaries into pieces of at most `max` bytes. A single line
+ * longer than that (a base64 image inside the JSONL) is cut mid-line; the
+ * pieces still concatenate back to the original bytes.
+ */
+export declare const chunkTranscript: (bytes: Buffer, max?: number) => Buffer[];
+export declare const buildSessionGraphFolder: (sessionDir: string, options?: {
+    compactLevel?: number;
+}) => Promise<string>;
+/** Remove a previously built folder so stale blobs never linger. */
+export declare const resetSessionGraphFolder: (sessionDir: string) => Promise<void>;
+export {};
+//# sourceMappingURL=graph.d.ts.map

package/dist/hooks/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/hooks/graph.ts"],"names":[],"mappings":"AAkCA,eAAO,MAAM,oBAAoB,iBAAiB,CAAA;AAClD,eAAO,MAAM,iBAAiB,4BAA4B,CAAA;AAC1D,eAAO,MAAM,oBAAoB,yBAAyB,CAAA;AAC1D,sDAAsD;AACtD,eAAO,MAAM,sBAAsB,QAAkB,CAAA;AAIrD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,QAAoB,CAAA;AAIvD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAA;AAGlC,KAAK,MAAM,GAAG;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAC,CAAA;AAC9F,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,KAAG,MAQ7C,CAAA;AA4BD,eAAO,MAAM,cAAc,GAAI,gBAAgB,MAAM,KAAG,MAMvD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,EAAE,YAA4B,KAAG,MAAM,EAanF,CAAA;AAED,eAAO,MAAM,uBAAuB,GAClC,YAAY,MAAM,EAClB,UAAS;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAM,KACpC,OAAO,CAAC,MAAM,CAmLhB,CAAA;AAED,oEAAoE;AACpE,eAAO,MAAM,uBAAuB,GAAU,YAAY,MAAM,KAAG,OAAO,CAAC,IAAI,CAE9E,CAAA"}

package/dist/hooks/graph.js

@@ -0,0 +1,269 @@
+// Saved session -> `ag.graph-folder.v1` folder, using the same canonical
+// normalize/hash code the `runs upload` reader recomputes.
+//
+// The whole redacted transcript travels as content-addressed blobs of at most
+// TRANSCRIPT_CHUNK_BYTES, cut on line boundaries. A transcript only grows, so
+// every chunk but the last keeps its hash from one upload to the next and the
+// server already holds it: re-uploading a grown session sends only the tail.
+// The message, prompt and tool-call nodes are an index for browsing and for
+// building skills; the transcript blobs are the record.
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { canonicalGraphHash, canonicalJsonLine, normalizeArtifactGraph, } from '../runsUpload/artifactGraphModel.js';
+import { CONTROL_MAX_BLOB_BYTES } from '../runsUpload/controlEndpoints.js';
+import { EDGES_FILE_NAME, GRAPH_FOLDER_SCHEMA_VERSION, MANIFEST_FILE_NAME, NODES_FILE_NAME, deriveFlows, deriveStates, } from '../runsUpload/graphFolder.js';
+import { readMeta } from './paths.js';
+import { redactText } from './redact.js';
+import { parseTranscript } from './transcript.js';
+export const SESSION_GRAPH_FOLDER = 'graph-folder';
+export const SESSION_GENERATOR = 'assethub-cli:hooks.save';
+export const TRANSCRIPT_BLOB_MIME = 'application/x-ndjson';
+/** Under the 4 MiB blob limit, with room to spare. */
+export const TRANSCRIPT_CHUNK_BYTES = 3 * 1024 * 1024;
+const MAX_TOOL_INPUT_BYTES = 8 * 1024;
+const MAX_TEXT_CHARS = 16 * 1024;
+/**
+ * Canonical bytes of the message and tool-call nodes kept in one snapshot. The
+ * push is refused over 4 MiB (CONTROL_MAX_PUSH_BYTES), and the edges, image
+ * and transcript nodes, manifest and envelope need the rest. A longer session
+ * keeps its newest messages in the index and records how many were left out;
+ * the transcript blobs still hold every one of them.
+ */
+export const MAX_MESSAGE_NODE_BYTES = 2.5 * 1024 * 1024;
+/** Rough canonical size of the `continues` edge that links each kept message. */
+const EDGE_BYTES_ESTIMATE = 160;
+/**
+ * Compaction after an upload failed for size or time. Each level halves the
+ * index budget and the per-message clips; from level 2 on images stay local.
+ * The transcript blobs are never dropped: they are the record.
+ */
+export const MAX_COMPACT_LEVEL = 4;
+const SKIP_IMAGES_FROM_LEVEL = 2;
+export const compactLimits = (level) => {
+    const factor = 2 ** Math.max(0, Math.min(level, MAX_COMPACT_LEVEL));
+    return {
+        indexBytes: Math.floor(MAX_MESSAGE_NODE_BYTES / factor),
+        textChars: Math.max(1024, Math.floor(MAX_TEXT_CHARS / factor)),
+        toolInputBytes: Math.max(512, Math.floor(MAX_TOOL_INPUT_BYTES / factor)),
+        images: level < SKIP_IMAGES_FROM_LEVEL,
+    };
+};
+const pad = (n) => String(n).padStart(6, '0');
+const clip = (text, max) => text.length > max ? { text: text.slice(0, max), truncated: true } : { text };
+const redactedInput = (input, maxBytes) => {
+    const json = redactText(JSON.stringify(input ?? {}) ?? '{}');
+    if (Buffer.byteLength(json, 'utf8') <= maxBytes) {
+        try {
+            const parsed = JSON.parse(json);
+            if (parsed != null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                return parsed;
+            }
+            return { value: parsed };
+        }
+        catch {
+            // fall through to the preview form
+        }
+    }
+    return { truncated: true, preview: json.slice(0, maxBytes) };
+};
+const isoZ = (value, fallback) => {
+    const date = value ? new Date(value) : fallback;
+    return `${(Number.isNaN(date.getTime()) ? fallback : date).toISOString().slice(0, 19)}Z`;
+};
+export const sessionGraphId = (sessionDirName) => {
+    const slug = sessionDirName
+        .replace(/[^A-Za-z0-9._:-]+/g, '-')
+        .replace(/^[^A-Za-z0-9]+/, '')
+        .slice(0, 100);
+    return `import_session_${slug}`;
+};
+/**
+ * Cut on line boundaries into pieces of at most `max` bytes. A single line
+ * longer than that (a base64 image inside the JSONL) is cut mid-line; the
+ * pieces still concatenate back to the original bytes.
+ */
+export const chunkTranscript = (bytes, max = TRANSCRIPT_CHUNK_BYTES) => {
+    const chunks = [];
+    let start = 0;
+    while (start < bytes.length) {
+        let end = Math.min(start + max, bytes.length);
+        if (end < bytes.length) {
+            const newline = bytes.lastIndexOf(0x0a, end - 1);
+            if (newline >= start)
+                end = newline + 1;
+        }
+        chunks.push(bytes.subarray(start, end));
+        start = end;
+    }
+    return chunks;
+};
+export const buildSessionGraphFolder = async (sessionDir, options = {}) => {
+    const meta = await readMeta(sessionDir);
+    if (!meta)
+        throw new Error(`No meta.json in ${sessionDir}`);
+    const limits = compactLimits(options.compactLevel ?? 0);
+    // A session an older CLI saved has no client: it came from Claude Code.
+    const agentTag = `agent:${meta.client ?? 'claude'}`;
+    const transcriptBytes = await readFile(join(sessionDir, 'transcript.jsonl'));
+    const transcript = parseTranscript(transcriptBytes.toString('utf8'));
+    await resetSessionGraphFolder(sessionDir);
+    const folder = join(sessionDir, SESSION_GRAPH_FOLDER);
+    // The folder holds a full copy of the masked transcript: private like the rest.
+    await mkdir(join(folder, 'blobs'), { recursive: true, mode: 0o700 });
+    const savedAt = new Date(meta.savedAt);
+    const nodes = [];
+    const edges = [];
+    const edge = (from, to, kind) => {
+        edges.push({ id: `edge_${kind}_${from}_${to}`, from, to, kind, tags: [], metadata: {} });
+    };
+    const blobs = [];
+    const blobKeys = new Set();
+    const addBlob = async (bytes, mime, name) => {
+        const sha = createHash('sha256').update(bytes).digest('hex');
+        const key = `sha256:${sha}`;
+        if (!blobKeys.has(key)) {
+            blobKeys.add(key);
+            blobs.push({ key, mime, size: bytes.length, sha256: sha, name, file: `blobs/${sha}` });
+            await writeFile(join(folder, 'blobs', sha), bytes, { mode: 0o600 });
+        }
+        return { key, mime, size: bytes.length, sha256: sha, name };
+    };
+    const sessionNodeId = 'session';
+    // The record: the whole redacted transcript, chunked.
+    const transcriptParts = chunkTranscript(transcriptBytes);
+    for (const [index, part] of transcriptParts.entries()) {
+        const id = `transcript_${pad(index)}`;
+        const blobRef = await addBlob(part, TRANSCRIPT_BLOB_MIME, `transcript-${pad(index)}.jsonl`);
+        nodes.push({
+            id, artifactKind: 'file', semanticType: 'transcript', tags: ['session', agentTag],
+            metadata: { part: index, parts: transcriptParts.length },
+            payload: { blobRef },
+        });
+        edge(sessionNodeId, id, 'contains');
+    }
+    // The index: one node per prompt, reply and tool call.
+    const toolNodeById = [];
+    const ordered = [];
+    const messageNodes = [];
+    transcript.items.forEach((item, index) => {
+        const id = `${item.kind === 'tool' ? 'tool' : item.kind === 'prompt' ? 'prompt' : 'text'}_${pad(index)}`;
+        const createdAt = isoZ(item.timestamp, savedAt);
+        const node = item.kind === 'prompt'
+            ? {
+                id, artifactKind: 'json', semanticType: 'prompt', tags: ['session'],
+                metadata: { role: 'user', timestamp: createdAt },
+                payload: clip(redactText(item.text), limits.textChars),
+            }
+            : item.kind === 'assistant'
+                ? {
+                    id, artifactKind: 'text', tags: ['session', agentTag],
+                    metadata: { role: 'assistant', timestamp: createdAt },
+                    payload: clip(redactText(item.text), limits.textChars),
+                }
+                : {
+                    id, artifactKind: 'run', tags: ['session', agentTag, `tool:${item.toolName}`],
+                    metadata: { toolUseId: item.toolUseId, timestamp: createdAt },
+                    payload: { toolName: item.toolName, input: redactedInput(item.input, limits.toolInputBytes) },
+                };
+        messageNodes.push({ node, item });
+    });
+    // Keep the newest messages that fit the budget, in their original order.
+    let budget = limits.indexBytes;
+    let firstKept = messageNodes.length;
+    while (firstKept > 0) {
+        const cost = Buffer.byteLength(canonicalJsonLine(messageNodes[firstKept - 1].node), 'utf8') + EDGE_BYTES_ESTIMATE;
+        if (cost > budget)
+            break;
+        budget -= cost;
+        firstKept -= 1;
+    }
+    const droppedMessages = firstKept;
+    for (const { node, item } of messageNodes.slice(firstKept)) {
+        nodes.push(node);
+        ordered.push(node.id);
+        if (item.kind === 'tool')
+            toolNodeById.push({ id: node.id, item });
+    }
+    // Images: only those small enough for the blob limit, and none once compacted.
+    const imageNodes = [];
+    let skippedImages = 0;
+    for (const [index, image] of (meta.images ?? []).entries()) {
+        if (!limits.images) {
+            skippedImages += 1;
+            continue;
+        }
+        const file = join(sessionDir, 'images', image.file);
+        let bytes;
+        try {
+            if ((await stat(file)).size > CONTROL_MAX_BLOB_BYTES) {
+                skippedImages += 1;
+                continue;
+            }
+            bytes = await readFile(file);
+        }
+        catch {
+            skippedImages += 1;
+            continue;
+        }
+        const blobRef = await addBlob(bytes, image.mime, image.file.slice(0, 200));
+        const id = `image_${pad(index)}`;
+        nodes.push({
+            id, artifactKind: 'image', tags: ['session', agentTag],
+            metadata: { sourcePath: redactText(image.original) },
+            payload: { blobRef },
+        });
+        imageNodes.push({ id, original: image.original });
+    }
+    nodes.push({
+        id: sessionNodeId, artifactKind: 'console', semanticType: 'agent-session',
+        tags: ['session', agentTag],
+        metadata: {
+            sessionId: meta.sessionId, client: meta.client, lastEvent: meta.lastEvent,
+            messageCount: messageNodes.length, skippedImages,
+            transcriptParts: transcriptParts.length,
+            ...(droppedMessages > 0 ? { droppedMessages } : {}),
+            ...((options.compactLevel ?? 0) > 0 ? { compactLevel: options.compactLevel } : {}),
+            ...(meta.canvasId ? { canvasId: meta.canvasId } : {}),
+        },
+    });
+    // Chain: session -> first message, then each message -> the next.
+    let previous = sessionNodeId;
+    for (const id of ordered) {
+        edge(previous, id, 'continues');
+        previous = id;
+    }
+    // 'uses': the tool call that mentioned or produced an image -> the image.
+    for (const image of imageNodes) {
+        for (const { id, item } of toolNodeById) {
+            if (item.kind !== 'tool')
+                continue;
+            const inInput = JSON.stringify(item.input ?? {}).includes(image.original);
+            const inResult = transcript.resultImages.get(item.toolUseId)?.includes(image.original);
+            if (inInput || inResult)
+                edge(id, image.id, 'uses');
+        }
+    }
+    const graph = normalizeArtifactGraph({ nodes, edges });
+    const graphHash = canonicalGraphHash(graph);
+    const manifest = {
+        schemaVersion: GRAPH_FOLDER_SCHEMA_VERSION,
+        createdAt: `${savedAt.toISOString().slice(0, 19)}Z`,
+        generator: SESSION_GENERATOR,
+        selection: { kind: 'whole-graph' },
+        graph: { nodeCount: graph.nodes.length, edgeCount: graph.edges.length, graphHash },
+        flows: deriveFlows(graph),
+        states: deriveStates(graph),
+        blobs: blobs.sort((a, b) => (String(a.key) < String(b.key) ? -1 : 1)),
+        missingBlobs: [],
+        run: { sessionId: meta.sessionId, client: meta.client },
+    };
+    await writeFile(join(folder, MANIFEST_FILE_NAME), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+    await writeFile(join(folder, NODES_FILE_NAME), graph.nodes.map(node => `${canonicalJsonLine(node)}\n`).join(''), { mode: 0o600 });
+    await writeFile(join(folder, EDGES_FILE_NAME), graph.edges.map(e => `${canonicalJsonLine(e)}\n`).join(''), { mode: 0o600 });
+    return folder;
+};
+/** Remove a previously built folder so stale blobs never linger. */
+export const resetSessionGraphFolder = async (sessionDir) => {
+    await rm(join(sessionDir, SESSION_GRAPH_FOLDER), { recursive: true, force: true });
+};

package/dist/hooks/index.d.ts

@@ -0,0 +1,7 @@
+export { installHooks, uninstallHooks } from './install.js';
+export { saveSession, type SaveSessionOptions, type SaveSessionResult } from './save.js';
+export { buildSessionGraphFolder } from './graph.js';
+export { canUploadSessions, resolveUploadAuth, uploadSession, uploadPending, type UploadOptions } from './upload.js';
+export { runHooksCommand, type HooksCommandDeps } from './command.js';
+export { redactText, redactJsonl } from './redact.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAE,cAAc,EAAC,MAAM,cAAc,CAAA;AACzD,OAAO,EAAC,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAC,MAAM,WAAW,CAAA;AACtF,OAAO,EAAC,uBAAuB,EAAC,MAAM,YAAY,CAAA;AAClD,OAAO,EAAC,iBAAiB,EAAE,iBAAiB,EAAE,aAAa,EAAE,aAAa,EAAE,KAAK,aAAa,EAAC,MAAM,aAAa,CAAA;AAClH,OAAO,EAAC,eAAe,EAAE,KAAK,gBAAgB,EAAC,MAAM,cAAc,CAAA;AACnE,OAAO,EAAC,UAAU,EAAE,WAAW,EAAC,MAAM,aAAa,CAAA"}

package/dist/hooks/index.js

@@ -0,0 +1,6 @@
+export { installHooks, uninstallHooks } from './install.js';
+export { saveSession } from './save.js';
+export { buildSessionGraphFolder } from './graph.js';
+export { canUploadSessions, resolveUploadAuth, uploadSession, uploadPending } from './upload.js';
+export { runHooksCommand } from './command.js';
+export { redactText, redactJsonl } from './redact.js';

package/dist/hooks/install.d.ts

@@ -0,0 +1,58 @@
+import type { HookClient } from './types.js';
+export declare const HOOK_EVENTS: readonly ["SessionStart", "Stop", "SessionEnd", "PreCompact"];
+export declare const HOOK_TIMEOUT_SECONDS = 30;
+/**
+ * SessionEnd hooks share a 1.5 s budget that a longer per-hook `timeout` raises
+ * (up to 60 s). The save itself is local; the upload runs in a detached process.
+ */
+export declare const SESSION_END_TIMEOUT_SECONDS = 10;
+export declare const MAX_SETTINGS_BACKUPS = 3;
+/** Where the hooks go: one project folder, or every project when omitted (--global). */
+export type HookScope = {
+    projectDir?: string;
+};
+/** Where each client keeps its config, per project and for the user. */
+type ClientPaths = {
+    home?: string;
+    codexHome?: string;
+};
+/** What `hooks install` and `setup` must tell the user before recording starts. */
+export declare const sessionSaveDisclosure: (scope: HookScope, client?: HookClient) => string;
+export declare const isOurCommand: (command: unknown) => boolean;
+/** Codex hooks name their client, so the saved session is recorded as Codex. */
+export declare const hookCommand: (cliPath?: string, client?: HookClient) => string;
+/**
+ * A project install in the home folder would land in ~/.claude (or ~/.codex),
+ * which the client also reads for every project, so it is refused rather than
+ * silently global.
+ */
+export declare const hookScopeError: (home: string | undefined, scope: HookScope, client?: HookClient, codexHome?: string) => Promise<string | undefined>;
+type HookEntry = {
+    type: 'command';
+    command: string;
+    timeout: number;
+    async?: true;
+};
+/**
+ * SessionStart (sweep and retry), Stop (every turn) and PreCompact only mark or
+ * spawn work, and run in the background so they never delay Claude Code.
+ * SessionEnd stays synchronous, because Claude Code is exiting and a
+ * background hook could be cut off. Codex hooks all run synchronously; the
+ * work is the same few local file writes.
+ */
+export declare const hookEntry: (event: (typeof HOOK_EVENTS)[number], command: string, client?: HookClient) => HookEntry;
+export declare const installHooks: (options: HookScope & ClientPaths & {
+    client: HookClient;
+    cliPath?: string;
+}) => Promise<{
+    installed: boolean;
+    detail: string;
+}>;
+export declare const uninstallHooks: (options: HookScope & ClientPaths & {
+    client: HookClient;
+}) => Promise<{
+    removed: boolean;
+    detail: string;
+}>;
+export {};
+//# sourceMappingURL=install.d.ts.map