sessionmem 1.4.0 → 1.6.0

package/dist/cli/transcripts/cursor.js

@@ -0,0 +1,295 @@
+import BetterSqlite3 from "better-sqlite3";
+import { copyFile, mkdtemp, readFile, readdir, rm, stat } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createdAt, object, unsupported } from "./types.js";
+export function cursorUserDirectory(platform = process.platform) {
+    if (platform === "darwin")
+        return join(homedir(), "Library", "Application Support", "Cursor", "User");
+    if (platform === "win32")
+        return join(process.env.APPDATA || join(homedir(), "AppData", "Roaming"), "Cursor", "User");
+    return join(homedir(), ".config", "Cursor", "User");
+}
+async function fileStamp(path) {
+    try {
+        const info = await stat(path, { bigint: true });
+        return `${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}`;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+/** Never give SQLite a connection to the source, including its WAL/SHM files. */
+async function snapshot(path, read) {
+    const temp = await mkdtemp(join(tmpdir(), "sessionmem-cursor-"));
+    try {
+        const target = join(temp, "state.vscdb");
+        // Copy the WAL too: immutable connections to a live database ignore it and
+        // would silently miss recently committed messages. Detect checkpoints and
+        // concurrent writes during the copy, then retry on a later sweep if busy.
+        const suffixes = ["", "-wal", "-journal"];
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const before = await Promise.all(suffixes.map(suffix => fileStamp(path + suffix)));
+            if (!before[0])
+                throw new Error(`Cursor database disappeared: ${path}`);
+            try {
+                for (const [index, suffix] of suffixes.entries()) {
+                    await rm(target + suffix, { force: true });
+                    if (before[index])
+                        await copyFile(path + suffix, target + suffix);
+                }
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    continue;
+                throw error;
+            }
+            const after = await Promise.all(suffixes.map(suffix => fileStamp(path + suffix)));
+            if (JSON.stringify(before) !== JSON.stringify(after))
+                continue;
+            let db;
+            try {
+                // better-sqlite3 normally compiles with SQLITE_USE_URI=0. Try immutable
+                // only on a copy without sidecars; otherwise use a read-only temp copy
+                // where SQLite can reconstruct its private WAL index safely.
+                if (!before[1] && !before[2]) {
+                    try {
+                        db = new BetterSqlite3(`${pathToFileURL(target).href}?mode=ro&immutable=1`, { readonly: true, fileMustExist: true });
+                    }
+                    catch { /* URI opens are unavailable in the bundled SQLite build. */ }
+                }
+                db ??= new BetterSqlite3(target, { readonly: true, fileMustExist: true, timeout: 0 });
+                return read(db);
+            }
+            finally {
+                db?.close();
+            }
+        }
+        throw new Error("Cursor database changed while copying; will retry");
+    }
+    finally {
+        await rm(temp, { recursive: true, force: true });
+    }
+}
+function json(value, label) {
+    if (Buffer.isBuffer(value))
+        value = value.toString("utf8");
+    if (typeof value !== "string")
+        unsupported("cursor", `${label} is not JSON text`);
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        unsupported("cursor", `invalid JSON in ${label}`);
+    }
+}
+function requireTable(db, table) {
+    const columns = db.prepare(`PRAGMA table_info(${table})`).all();
+    if (!["key", "value"].every(name => columns.some(column => column.name === name))) {
+        unsupported("cursor", `missing ${table} table or key/value columns`);
+    }
+}
+function item(db, key) {
+    const row = db.prepare("SELECT value FROM ItemTable WHERE key = ?").get(key);
+    return row ? json(row.value, key) : undefined;
+}
+function workspacePath(value) {
+    const uri = object(value);
+    if (typeof uri?.fsPath === "string" && isAbsolute(uri.fsPath))
+        return uri.fsPath;
+    if (typeof value === "string" && isAbsolute(value))
+        return value;
+    if (typeof value === "string" && value.startsWith("file:")) {
+        try {
+            return fileURLToPath(value);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    // URI components are used in some workspaceIdentifier entries.
+    if (uri?.scheme === "file" && typeof uri.path === "string") {
+        try {
+            return fileURLToPath(`file://${typeof uri.authority === "string" ? uri.authority : ""}${uri.path}`);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+function composers(value, key) {
+    const entries = Array.isArray(value) ? value : object(value)?.allComposers;
+    if (!Array.isArray(entries))
+        unsupported("cursor", `${key} needs an array of composers`);
+    return entries.map(entry => {
+        const composer = object(entry);
+        if (!composer || typeof composer.composerId !== "string" || !composer.composerId.trim() || composer.composerId.length > 200) {
+            unsupported("cursor", `invalid composerId in ${key}`);
+        }
+        return composer;
+    });
+}
+/** Resolve a User directory or a global/workspace state.vscdb override. */
+export async function cursorDatabasePath(directory) {
+    try {
+        if ((await stat(directory)).isFile()) {
+            if (basename(dirname(dirname(directory))) === "workspaceStorage") {
+                return join(dirname(dirname(dirname(directory))), "globalStorage", "state.vscdb");
+            }
+            return directory;
+        }
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const path = join(directory, "globalStorage", "state.vscdb");
+    return await fileStamp(path) ? path : undefined;
+}
+function parseBubble(value, id) {
+    const bubble = object(json(value, `bubble ${id}`));
+    if (!bubble)
+        unsupported("cursor", `invalid bubble ${id}`);
+    // Cursor uses 1=user and 2=assistant. Tool, system and internal bubbles are
+    // not conversation messages. Never stringify code, tool results or context.
+    const role = bubble.type === 1 || bubble.type === "user" ? "user"
+        : bubble.type === 2 || bubble.type === "assistant" ? "assistant" : undefined;
+    if (!role) {
+        if (bubble.type === undefined)
+            unsupported("cursor", `missing message type in bubble ${id}`);
+        return undefined;
+    }
+    if (bubble.text === undefined || bubble.text === null)
+        return undefined;
+    if (typeof bubble.text !== "string")
+        unsupported("cursor", `invalid text in bubble ${id}`);
+    if (!bubble.text.trim())
+        return undefined;
+    const timestamp = typeof bubble.createdAt === "number" && Number.isFinite(bubble.createdAt)
+        ? new Date(bubble.createdAt).toISOString() : createdAt(bubble.createdAt);
+    return { role, text: bubble.text.slice(0, 4000), timestamp };
+}
+export async function readCursorTranscripts(path) {
+    const global = await snapshot(path, db => {
+        requireTable(db, "cursorDiskKV");
+        // Older layouts only need ItemTable in the workspace databases.
+        const hasHeadersTable = !!db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'ItemTable'").get();
+        if (hasHeadersTable)
+            requireTable(db, "ItemTable");
+        const headers = hasHeadersTable ? item(db, "composer.composerHeaders") : undefined;
+        // Materialize only the relevant rows, one value at a time. Large tool and
+        // code fields are discarded immediately rather than retained in memory.
+        const metadata = new Map();
+        const bubbles = new Map();
+        for (const row of db.prepare("SELECT key, value FROM cursorDiskKV WHERE key GLOB 'composerData:*' OR key GLOB 'bubbleId:*' ORDER BY key").iterate()) {
+            if (row.key.startsWith("composerData:")) {
+                const data = object(json(row.value, row.key));
+                if (!data)
+                    unsupported("cursor", `invalid ${row.key}`);
+                metadata.set(row.key.slice("composerData:".length), data);
+            }
+            else {
+                const parts = row.key.split(":");
+                if (parts.length !== 3 || !parts[1] || !parts[2])
+                    unsupported("cursor", `invalid bubble key ${row.key}`);
+                const entries = bubbles.get(parts[1]) ?? [];
+                entries.push({ id: parts[2], message: parseBubble(row.value, parts[2]) });
+                bubbles.set(parts[1], entries);
+            }
+        }
+        return { headers, metadata, bubbles };
+    });
+    const index = new Map();
+    const add = (composer, cwd) => {
+        const id = composer.composerId;
+        if (!cwd)
+            unsupported("cursor", `missing workspace path for composer ${id}`);
+        if (index.has(id) && resolve(index.get(id)) !== resolve(cwd))
+            unsupported("cursor", `conflicting workspaces for composer ${id}`);
+        index.set(id, cwd);
+    };
+    let foundIndex = global.headers !== undefined;
+    if (foundIndex) {
+        for (const composer of composers(global.headers, "composer.composerHeaders")) {
+            add(composer, workspacePath(object(composer.workspaceIdentifier)?.uri));
+        }
+    }
+    const workspaces = join(dirname(dirname(path)), "workspaceStorage");
+    let directories;
+    try {
+        directories = await readdir(workspaces, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        directories = [];
+    }
+    for (const entry of directories.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isDirectory())
+            continue;
+        const workspace = join(workspaces, entry.name);
+        const database = join(workspace, "state.vscdb");
+        if (!await fileStamp(database))
+            continue;
+        const legacy = await snapshot(database, db => {
+            requireTable(db, "ItemTable");
+            return item(db, "composer.composerData");
+        });
+        if (legacy === undefined)
+            continue;
+        foundIndex = true;
+        const entries = composers(legacy, "composer.composerData");
+        if (!entries.length)
+            continue;
+        let info;
+        try {
+            info = object(json(await readFile(join(workspace, "workspace.json"), "utf8"), "workspace.json"));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                unsupported("cursor", "missing workspace.json for composer index");
+            throw error;
+        }
+        for (const composer of entries) {
+            // Current central headers take precedence over stale workspace indexes.
+            if (!index.has(composer.composerId))
+                add(composer, workspacePath(info?.folder ?? info?.workspace));
+        }
+    }
+    if (!foundIndex)
+        unsupported("cursor", "missing composer.composerHeaders and workspace composer.composerData indexes");
+    const transcripts = [];
+    for (const [sessionId, cwd] of index) {
+        const metadata = global.metadata.get(sessionId);
+        if (!metadata)
+            unsupported("cursor", `missing composerData:${sessionId}`);
+        const headers = metadata.fullConversationHeadersOnly ?? metadata.conversation;
+        if (headers !== undefined && !Array.isArray(headers))
+            unsupported("cursor", `invalid conversation headers for ${sessionId}`);
+        const order = new Map();
+        const entries = global.bubbles.get(sessionId) ?? [];
+        const bubbleIds = new Set(entries.map(bubble => bubble.id));
+        for (const [position, raw] of (Array.isArray(headers) ? headers : []).entries()) {
+            const header = object(raw);
+            if (typeof header?.bubbleId !== "string")
+                unsupported("cursor", `invalid conversation header for ${sessionId}`);
+            order.set(header.bubbleId, position);
+            if (!bubbleIds.has(header.bubbleId)) {
+                unsupported("cursor", `missing bubbleId:${sessionId}:${header.bubbleId}`);
+            }
+        }
+        entries.sort((a, b) => (order.get(a.id) ?? Infinity) - (order.get(b.id) ?? Infinity)
+            || (a.message?.timestamp ?? "").localeCompare(b.message?.timestamp ?? "") || a.id.localeCompare(b.id));
+        transcripts.push({ host: "cursor", cwd, sessionId, malformed: false,
+            events: entries.flatMap(({ id, message }) => message ? [{
+                    id: `bubble-${id}`, eventType: `message:${message.role}`, payloadJson: JSON.stringify({ text: message.text }), createdAt: message.timestamp,
+                }] : []),
+        });
+    }
+    return transcripts;
+}

package/dist/cli/transcripts/index.js

@@ -0,0 +1,118 @@
+import { createReadStream } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { expandTilde } from "../context.js";
+import { isClaudeRecord, parseClaudeTranscript } from "./claudeCode.js";
+import { parseCodexTranscript } from "./codex.js";
+import { cursorDatabasePath, cursorUserDirectory, readCursorTranscripts } from "./cursor.js";
+import { object } from "./types.js";
+export const TRANSCRIPT_HOSTS = ["claude-code", "codex", "cursor"];
+const parsers = { "claude-code": parseClaudeTranscript, codex: parseCodexTranscript };
+export function transcriptDirectory(host) {
+    if (host === "cursor")
+        return cursorUserDirectory();
+    return join(homedir(), host === "codex" ? ".codex" : ".claude", host === "codex" ? "sessions" : "projects");
+}
+export function transcriptSources(options) {
+    const host = options.host;
+    if (host && !TRANSCRIPT_HOSTS.includes(host)) {
+        throw new Error(`Unsupported transcript host: ${host}. Choose ${TRANSCRIPT_HOSTS.join(" or ")}`);
+    }
+    const selected = host;
+    if (options.transcriptsDir)
+        return [{ directory: resolve(expandTilde(options.transcriptsDir)), host: selected }];
+    return (selected ? [selected] : TRANSCRIPT_HOSTS).map(host => ({ directory: transcriptDirectory(host), host }));
+}
+export async function* transcriptFiles(directory) {
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory())
+            yield* transcriptFiles(path);
+        else if (entry.isFile() && entry.name.endsWith(".jsonl"))
+            yield path;
+    }
+}
+/** Recognize Cursor overrides without changing JSONL directory overrides. */
+export async function isCursorSource(directory) {
+    try {
+        if ((await stat(directory)).isFile())
+            return directory.endsWith(".vscdb");
+        return !!await cursorDatabasePath(directory);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export async function readTranscript(path, claimedHost) {
+    if (claimedHost === "cursor")
+        throw new Error("unsupported format for cursor: expected a User directory or state.vscdb database");
+    const records = [];
+    let malformed = false;
+    const input = createReadStream(path);
+    const lines = createInterface({ input, crlfDelay: Infinity });
+    let lineIndex = 0;
+    try {
+        for await (const line of lines) {
+            const index = lineIndex++;
+            if (!line.trim())
+                continue;
+            let value;
+            try {
+                value = object(JSON.parse(line.replace(/^\uFEFF/, "")));
+            }
+            catch {
+                malformed = true;
+                continue;
+            }
+            if (!value)
+                throw new Error(`unsupported format${claimedHost ? ` for ${claimedHost}` : ""}: record on line ${index + 1} is not an object`);
+            records.push({ value, line: index });
+        }
+    }
+    finally {
+        lines.close();
+        input.destroy();
+    }
+    const host = claimedHost ?? (records.some(({ value }) => value.type === "session_meta") ? "codex"
+        : records.some(({ value }) => isClaudeRecord(value)) ? "claude-code" : undefined);
+    if (!host && records.length)
+        throw new Error("unsupported format: expected Claude Code transcripts or Codex CLI rollouts");
+    const result = parsers[host ?? "claude-code"](path, records);
+    return { ...result, malformed };
+}
+/** Read-only doctor probe: enumerate history and validate one sample per host. */
+export async function inspectTranscriptDiscovery(host) {
+    const directory = transcriptDirectory(host);
+    if (host === "cursor") {
+        const path = await cursorDatabasePath(directory);
+        if (!path)
+            return `No transcripts found (${directory})`;
+        const transcripts = await readCursorTranscripts(path);
+        return `${transcripts.length} composer(s) found (${path}); parsed as cursor`;
+    }
+    let count = 0;
+    let sample;
+    for await (const path of transcriptFiles(directory)) {
+        count++;
+        sample ??= path;
+    }
+    if (!sample)
+        return `No transcripts found (${directory})`;
+    const transcript = await readTranscript(sample, host);
+    if (transcript.malformed)
+        throw new Error(`malformed or incomplete JSONL (${sample})`);
+    return `${count} transcript file(s) found (${directory}); sample parsed as ${host}`;
+}

package/dist/cli/transcripts/types.js

@@ -0,0 +1,15 @@
+import { createHash } from "node:crypto";
+export function object(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value : undefined;
+}
+export function stableId(...parts) {
+    return `transcript-${createHash("sha256").update(JSON.stringify(parts)).digest("hex")}`;
+}
+export function createdAt(value) {
+    const timestamp = typeof value === "string" ? Date.parse(value) : NaN;
+    return Number.isFinite(timestamp) ? new Date(timestamp).toISOString() : undefined;
+}
+export function unsupported(host, detail) {
+    throw new Error(`unsupported format for ${host}: ${detail}`);
+}

package/dist/core/api/contracts.js

@@ -90,6 +90,9 @@ export const ingestSessionEventSchema = z.object({
 export const ingestSessionEventsRequestSchema = z.object({
     projectId: z.string().min(1),
     sessionId: z.string().min(1).max(200),
+    // Mutable transcript hosts can refresh an existing event without changing
+    // its identity, order or original timestamp. Other callers remain append-only.
+    replaceExisting: z.boolean().optional(),
     events: z.array(ingestSessionEventSchema).min(1).max(MAX_INGEST_EVENTS),
 });
 export const summarizeSessionToMemoryRequestSchema = z.object({
@@ -160,6 +163,7 @@ export const retrieveMemoriesRequestSchema = z.object({
     limit: z.number().int().min(1).max(100).default(20),
     mode: z.enum(["auto", "on-demand"]).default("auto"),
     depth: z.enum(["default", "deep"]).default("default"),
+    includeHistory: z.boolean().optional(),
     tags: z.array(z.string().min(1).max(50)).max(10).optional(),
 });
 export const listMemoriesRequestSchema = z.object({

package/dist/core/api/memoryCoreService.js

@@ -208,7 +208,7 @@ export function createMemoryCoreService(deps) {
                         event_type: event.eventType,
                         payload_json: redactedPayload,
                         created_at: event.createdAt,
-                    });
+                    }, parsed.replaceExisting);
                 }
                 return written;
             });
@@ -265,6 +265,7 @@ export function createMemoryCoreService(deps) {
                 redactionEnabled: resolveRedactionEnabled(parsed.redactionEnabled),
             });
             const embedding = deterministicEmbed(redaction.text, dimension);
+            const capturedAt = deps.now?.().toISOString();
             // Per-session write soft limit: warn the caller when the session has
             // already accumulated SESSION_WRITE_SOFT_LIMIT memories so the agent
             // gets feedback to stop storing excessively. The write still proceeds.
@@ -291,6 +292,8 @@ export function createMemoryCoreService(deps) {
                 origin_project_id: null,
                 tags: JSON.stringify(parsed.tags ?? null),
                 expires_at: parsed.expiresAt ?? null,
+                created_at: capturedAt,
+                updated_at: capturedAt,
             });
             const inserted = getMemoryRecordById(db, parsed.projectId, parsed.memoryId);
             if (!inserted) {
@@ -315,7 +318,9 @@ export function createMemoryCoreService(deps) {
                 db,
                 projectId: parsed.projectId,
                 queryText: parsed.query,
+                includeHistory: parsed.includeHistory,
                 limit,
+                now: deps.now?.(),
             });
             // Optional tag filter: keep a memory only when its stored tags contain ALL
             // requested tags. The semantic candidate projection omits tags, so re-read
@@ -694,6 +699,7 @@ export function createMemoryCoreService(deps) {
                                 redactionEnabled: resolveRedactionEnabled(item.redactionEnabled),
                             });
                             const embedding = deterministicEmbed(redaction.text, dimension);
+                            const capturedAt = deps.now?.().toISOString();
                             insertMemory(db, {
                                 id: item.memoryId,
                                 project_id: parsed.projectId,
@@ -710,6 +716,8 @@ export function createMemoryCoreService(deps) {
                                 origin_project_id: null,
                                 tags: JSON.stringify(item.tags ?? null),
                                 expires_at: item.expiresAt ?? null,
+                                created_at: capturedAt,
+                                updated_at: capturedAt,
                             });
                             const inserted = getMemoryRecordById(db, parsed.projectId, item.memoryId);
                             if (!inserted) {

package/dist/core/api/sessionLifecycleService.js

@@ -6,6 +6,8 @@ import { insertSummarizationFailure } from "../storage/summarizationFailuresRepo
 import { summarizeWithCloud } from "../summarize/cloudSummarizer.js";
 import { summarizeLocalSessionEvents, } from "../summarize/localSummarizer.js";
 import { resolveSummarizerMode } from "../summarize/strategySelector.js";
+import { extractEventText } from "../summarize/summaryShape.js";
+import { extractKnowledge } from "../extract/knowledge.js";
 const DEFAULT_EMBEDDING_DIMENSION = 32;
 const CLOUD_RETRY_CONFIG = {
     retries: 2,
@@ -58,7 +60,7 @@ function storeSummaryMemory(db, embeddingDimension, input) {
         // Session summaries are locally authored.
         author: input.author,
         origin_project_id: null,
-    });
+    }, input.knowledge, input.factSource);
 }
 function buildMemoryId(request) {
     return request.memoryId ?? `${request.sessionId}-summary`;
@@ -160,6 +162,10 @@ export function createSessionLifecycleService(deps) {
         }
         const mode = resolveSummarizerMode(request.config);
         const memoryId = buildMemoryId(request);
+        // Extract from the same event text as the summarizer, before its line/token
+        // caps. This remains deterministic even when cloud summaries are opted in.
+        const factSource = events.map(event => ({ text: extractEventText(event), observedAt: event.created_at }));
+        const knowledge = extractKnowledge(factSource.map(source => source.text).join("\n"));
         const baseInput = {
             events,
             summaryTokenCap: request.config.summaryTokenCap,
@@ -179,6 +185,8 @@ export function createSessionLifecycleService(deps) {
                     sourceAdapter: request.sourceAdapter,
                     summary: cloudResult.summary,
                     author,
+                    knowledge,
+                    factSource,
                 });
                 runLightPrune(request.projectId);
                 return {
@@ -215,6 +223,8 @@ export function createSessionLifecycleService(deps) {
                     sourceAdapter: request.sourceAdapter,
                     summary: fallbackResult.summary,
                     author,
+                    knowledge,
+                    factSource,
                 });
                 runLightPrune(request.projectId);
                 return {
@@ -269,6 +279,8 @@ export function createSessionLifecycleService(deps) {
                 sourceAdapter: request.sourceAdapter,
                 summary: localResult.summary,
                 author,
+                knowledge,
+                factSource,
             });
             runLightPrune(request.projectId);
             return {

package/dist/core/capture/toolEvent.js

@@ -0,0 +1,94 @@
+// High-signal tool types that we capture as session events.
+const CAPTURED_TOOL_TYPES = new Set(["Bash", "Edit", "Write", "MultiEdit"]);
+// Max payload size stored per hook event (chars). The full hook payload can be
+// large (file diffs); cap it so a single tool use can't bloat session_events.
+const MAX_HOOK_PAYLOAD_CHARS = 4000;
+// Per-field cap applied BEFORE serialization. Truncating the serialized JSON
+// instead would produce a string that is no longer valid JSON, which the
+// `payloadJson` contract rejects (it parses the value) — the event would then be
+// dropped, silently, by the catch-all below. Trim the inputs, not the output.
+const MAX_FIELD_CHARS = 1200;
+// One-line human summary shown in session summaries (summaryShape reads `text`).
+const MAX_TEXT_CHARS = 300;
+function truncate(value, max) {
+    return value.length > max ? `${value.slice(0, max)}…` : value;
+}
+/**
+ * Shorten every string in a tool input to MAX_FIELD_CHARS, recursively. Keeps
+ * the object's shape (so it still serializes to valid JSON) while bounding the
+ * size contributed by large fields such as a Write tool's `content` or an Edit
+ * tool's replacement text.
+ */
+function shrinkValue(value, depth = 0) {
+    if (typeof value === "string")
+        return truncate(value, MAX_FIELD_CHARS);
+    if (depth >= 4)
+        return undefined;
+    if (Array.isArray(value)) {
+        return value.slice(0, 20).map((item) => shrinkValue(item, depth + 1));
+    }
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [key, inner] of Object.entries(value)) {
+            out[key] = shrinkValue(inner, depth + 1);
+        }
+        return out;
+    }
+    // Numbers/booleans/null pass through; functions/undefined/symbols drop out.
+    return value === undefined || typeof value === "function" || typeof value === "symbol"
+        ? undefined
+        : value;
+}
+/**
+ * A short human-readable line describing the tool use. Stored alongside the
+ * structured input as `text`, which the local summarizer prefers over the raw
+ * payload — so session summaries read as prose instead of dumped JSON.
+ */
+function describeToolUse(toolName, input) {
+    const str = (key) => typeof input?.[key] === "string" ? input[key] : "";
+    if (toolName === "Bash") {
+        const command = str("command").replace(/\s+/g, " ").trim();
+        return truncate(command ? `Ran: ${command}` : "Ran a shell command", MAX_TEXT_CHARS);
+    }
+    const filePath = str("file_path") || str("path") || str("notebook_path");
+    const verb = toolName === "Write" ? "Wrote" : "Edited";
+    return truncate(filePath ? `${verb} ${filePath}` : `${verb} a file`, MAX_TEXT_CHARS);
+}
+/**
+ * Serialize the event payload, guaranteeing valid JSON within
+ * MAX_HOOK_PAYLOAD_CHARS. Per-field shrinking handles the common case; if the
+ * result is still over budget (many fields, or one huge key set), drop the
+ * structured input and keep only the human-readable summary rather than
+ * emitting truncated — and therefore unparseable — JSON.
+ */
+function buildPayloadJson(toolName, text, input, cwd, callId) {
+    const full = JSON.stringify({
+        tool: toolName,
+        text,
+        input: shrinkValue(input),
+        cwd,
+        ...(callId ? { call_id: callId } : {}),
+    });
+    if (full.length <= MAX_HOOK_PAYLOAD_CHARS)
+        return full;
+    return JSON.stringify({ tool: toolName, text, cwd, ...(callId ? { call_id: callId } : {}), truncated: true });
+}
+export function buildToolEvent(toolName, input, cwd) {
+    if (!CAPTURED_TOOL_TYPES.has(toolName))
+        return undefined;
+    return {
+        eventType: `tool_use:${toolName.toLowerCase()}`,
+        payloadJson: buildPayloadJson(toolName, describeToolUse(toolName, input), input, cwd),
+    };
+}
+/** Codex function calls retain their native name and call ID. */
+export function buildFunctionCallEvent(name, input, callId, cwd) {
+    const command = input.command ?? input.cmd;
+    const text = ["exec_command", "shell_command", "shell"].includes(name)
+        ? describeToolUse("Bash", { command: Array.isArray(command) ? command.join(" ") : command })
+        : CAPTURED_TOOL_TYPES.has(name) ? describeToolUse(name, input) : truncate(`Called ${name}`, MAX_TEXT_CHARS);
+    return {
+        eventType: `tool_use:${name.toLowerCase()}`,
+        payloadJson: buildPayloadJson(name, text, input, cwd, callId),
+    };
+}