sessionmem 1.4.0 → 1.5.0

package/dist/cli/commands/ui.js

@@ -0,0 +1,67 @@
+import BetterSqlite3 from "better-sqlite3";
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { createMemoryCoreService } from "../../core/api/memoryCoreService.js";
+import { deriveProjectId } from "../projectId.js";
+import { resolveDbPath } from "../context.js";
+import { inspectMigrations } from "../../core/schema/runMigrations.js";
+import { parseUiPort, startUiServer } from "../../ui/server.js";
+/** Open the OS browser without a shell or an additional runtime dependency. */
+export function openBrowser(url) {
+    const command = process.platform === "win32" ? "rundll32.exe" : process.platform === "darwin" ? "open" : "xdg-open";
+    const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
+    const child = spawn(command, args, { stdio: "ignore", detached: true, windowsHide: true });
+    const failed = () => console.error("Could not open a browser. Open the printed URL manually.");
+    child.once("error", failed);
+    child.once("exit", code => { if (code)
+        failed(); });
+    child.unref();
+}
+export async function uiCommand(options = {}) {
+    const port = parseUiPort(options.port);
+    // Unlike the normal CLI context, a viewer must not create, migrate or write the store.
+    let db;
+    try {
+        db = new BetterSqlite3(resolveDbPath(), { readonly: true, fileMustExist: true });
+    }
+    catch {
+        throw new Error("Cannot open the memory store. Run sessionmem ping first, or check SESSIONMEM_DB_PATH.");
+    }
+    try {
+        db.pragma("query_only = ON");
+        db.pragma("busy_timeout = 5000");
+        const migrations = inspectMigrations(db);
+        if (migrations.unknown.length) {
+            throw new Error("The memory store uses an unrecognized schema. Use the sessionmem version that created it.");
+        }
+        if (migrations.pending.length) {
+            throw new Error("The memory store needs an upgrade. Run sessionmem ping first to apply pending migrations.");
+        }
+        const viewer = await startUiServer({ db, service: createMemoryCoreService({ db }), projectId: deriveProjectId() }, port);
+        let stopping = false;
+        const stop = () => {
+            if (stopping)
+                return;
+            stopping = true;
+            void viewer.close().catch(error => {
+                console.error(error instanceof Error ? error.message : String(error));
+                process.exitCode = 1;
+            });
+        };
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+        try {
+            const closed = once(viewer.server, "close");
+            console.log(`sessionmem viewer: ${viewer.url}\nRead-only. Press Ctrl-C to stop.`);
+            openBrowser(viewer.url);
+            await closed;
+        }
+        finally {
+            process.removeListener("SIGINT", stop);
+            process.removeListener("SIGTERM", stop);
+        }
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/cli/commands/watch.js

@@ -0,0 +1,48 @@
+import { setTimeout } from "node:timers/promises";
+import { createCliContext } from "../context.js";
+import { printSweepSummary, sweepTranscripts } from "../transcriptSweep.js";
+export async function watchCommand(options = {}, ctx) {
+    const interval = Number(options.interval ?? 5);
+    if (!Number.isFinite(interval) || interval <= 0 || interval > 86400) {
+        throw new Error("--interval must be a number greater than 0 and at most 86400 seconds");
+    }
+    const context = ctx ?? createCliContext();
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    let firstSweep = true;
+    try {
+        do {
+            try {
+                const summary = await sweepTranscripts(context, options);
+                if (firstSweep || options.once || summary.sessionsImported || summary.errors) {
+                    printSweepSummary("watch", summary);
+                }
+                firstSweep = false;
+                if (options.once && summary.errors)
+                    process.exitCode = 1;
+            }
+            catch (error) {
+                if (options.once)
+                    throw error;
+                console.error(`[sessionmem] watch: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (options.once || controller.signal.aborted)
+                break;
+            try {
+                await setTimeout(interval * 1000, undefined, { signal: controller.signal });
+            }
+            catch (error) {
+                if (!controller.signal.aborted)
+                    throw error;
+            }
+        } while (!controller.signal.aborted);
+    }
+    finally {
+        process.removeListener("SIGINT", stop);
+        process.removeListener("SIGTERM", stop);
+        if (!ctx)
+            context.db.close();
+    }
+}

package/dist/cli/index.js

@@ -5,6 +5,7 @@ import { runMcpServer } from "./commands/run.js";
 import { sessionStartCommand } from "./commands/sessionStart.js";
 import { sessionEndCommand } from "./commands/sessionEnd.js";
 import { installCommand } from "./commands/install.js";
+import { doctorCommand } from "./commands/doctor.js";
 import { uninstallCommand } from "./commands/uninstall.js";
 import { pingCommand } from "./commands/ping.js";
 import { searchCommand } from "./commands/search.js";
@@ -24,6 +25,11 @@ import { reEmbedCommand } from "./commands/reEmbed.js";
 import { ingestHookCommand } from "./commands/ingestHook.js";
 import { dedupeCommand } from "./commands/dedupe.js";
 import { browseCommand } from "./commands/browse.js";
+import { scanCommand } from "./commands/scan.js";
+import { watchCommand } from "./commands/watch.js";
+import { entitiesCommand } from "./commands/entities.js";
+import { historyCommand } from "./commands/history.js";
+import { uiCommand } from "./commands/ui.js";
 // Source the version from package.json (single source of truth) so `--version`
 // never drifts from the published manifest. createRequire + resolveJsonModule
 // reads the manifest relative to this module; from dist/cli/index.js the
@@ -35,6 +41,11 @@ program
     .command("run")
     .description("Start the sessionmem MCP server")
     .action(runMcpServer);
+program
+    .command("ui")
+    .description("Open a local read-only web viewer for the memory store")
+    .option("--port <N>", "Local port (default: 3777; 0 selects a free port)")
+    .action((options) => uiCommand(options));
 program
     .command("session-start")
     .description("Print prior memory context for the current project as Claude Code SessionStart hook output (invoked automatically by the hook installed during `sessionmem install`)")
@@ -47,11 +58,28 @@ program
     .command("ingest-hook")
     .description("Process a Claude Code PostToolUse hook payload from stdin and store it as a session event (invoked automatically by the hook installed during `sessionmem install`)")
     .action(() => ingestHookCommand());
+program
+    .command("scan")
+    .description("Import existing Claude Code transcripts using local capture and summarization")
+    .option("--transcripts-dir <path>", "Transcript directory (default: ~/.claude/projects)")
+    .action(async (options) => { await scanCommand(options); });
+program
+    .command("watch")
+    .description("Poll Claude Code transcripts and capture new or updated sessions offline")
+    .option("--transcripts-dir <path>", "Transcript directory (default: ~/.claude/projects)")
+    .option("--once", "Run one sweep and exit")
+    .option("--interval <seconds>", "Seconds between sweeps", "5")
+    .action((options) => watchCommand(options));
 program
     .command("install")
-    .description("Install sessionmem into the current MCP host")
+    .description("Install sessionmem into every detected agent host")
     .option("--adapter <name>", "Force a host adapter instead of auto-detecting (claude-code, cursor, windsurf, cline, codex, antigravity, qcoder, generic)")
     .action((options) => installCommand(options));
+program
+    .command("doctor")
+    .description("Check the local store, schema, hooks, adapter wiring, and recall offline")
+    .option("--adapter <name>", "Check a specific host instead of installed-host detection")
+    .action(async (options) => { await doctorCommand(options); });
 program
     .command("uninstall")
     .description("Remove sessionmem from the current MCP host")
@@ -75,11 +103,24 @@ program
     .command("search <query>")
     .description("Search memories by semantic query")
     .option("--limit <n>", "Maximum number of results (1-100)", "10")
+    .option("--include-history", "Include superseded facts")
     .action((query, options) => searchCommand(query, options));
 program
     .command("list")
     .description("List up to 200 recent memories for the current project")
     .action(() => listCommand());
+program
+    .command("entities")
+    .description("List extracted entities, typed relations, and source memory IDs for a project")
+    .option("--project <id>", "Project ID (default: current project)")
+    .option("--json", "Output entities and relations as JSON")
+    .action((options) => entitiesCommand(options));
+program
+    .command("history")
+    .description("List supersession chains, source memory IDs, and timestamps")
+    .option("--project <id>", "Project ID (default: current project)")
+    .option("--json", "Output supersession links as JSON")
+    .action((options) => historyCommand(options));
 program
     .command("show <id>")
     .description("Show memory details by ID (content capped at 2000 characters)")

package/dist/cli/projectId.js

@@ -92,7 +92,7 @@ export function projectIdFromCwd(cwd) {
  * bucket. The id is unchanged for anyone already running at the repo root,
  * since the root IS the cwd in that case.
  */
-export function deriveProjectId() {
+export function deriveProjectId(cwd = process.cwd()) {
     const envProjectId = process.env.SESSIONMEM_PROJECT_ID;
     if (envProjectId && envProjectId.trim() !== "") {
         // Sanitize the operator-supplied id to prevent path traversal: the id is
@@ -110,6 +110,5 @@ export function deriveProjectId() {
             return sanitized;
         }
     }
-    const cwd = process.cwd();
     return projectIdFromCwd(findProjectRoot(cwd) ?? cwd);
 }

package/dist/cli/transcriptSweep.js

@@ -0,0 +1,182 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { homedir } from "node:os";
+import { buildToolEvent } from "../core/capture/toolEvent.js";
+import { handleSessionEndConfigSchema, MAX_INGEST_EVENTS } from "../core/api/contracts.js";
+import { expandTilde } from "./context.js";
+import { deriveProjectId } from "./projectId.js";
+function object(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value : undefined;
+}
+function stableId(...parts) {
+    return `transcript-${createHash("sha256").update(JSON.stringify(parts)).digest("hex")}`;
+}
+/** Translate the transcript envelope; tool normalization stays shared with ingest-hook. */
+async function readTranscript(path) {
+    const result = {
+        cwd: undefined,
+        sessionId: basename(path, ".jsonl"),
+        events: [],
+        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 record;
+            try {
+                record = object(JSON.parse(line.replace(/^\uFEFF/, "")));
+            }
+            catch {
+                result.malformed = true;
+                continue;
+            }
+            if (!record)
+                continue;
+            if (!result.cwd && typeof record.cwd === "string" && record.cwd.trim()) {
+                result.cwd = record.cwd;
+            }
+            // Subagent files share their parent's sessionId; retain their own filename.
+            if (!basename(path).startsWith("agent-") && typeof record.sessionId === "string") {
+                result.sessionId = record.sessionId;
+            }
+            if (record.type !== "user" && record.type !== "assistant")
+                continue;
+            const message = object(record.message);
+            const content = message?.content;
+            const blocks = typeof content === "string" ? [{ type: "text", text: content }]
+                : Array.isArray(content) ? content : [];
+            for (const [blockIndex, rawBlock] of blocks.entries()) {
+                const block = object(rawBlock);
+                if (!block)
+                    continue;
+                const key = typeof record.uuid === "string" ? record.uuid : `line-${index}`;
+                const timestamp = typeof record.timestamp === "string" ? Date.parse(record.timestamp) : NaN;
+                const createdAt = Number.isFinite(timestamp) ? new Date(timestamp).toISOString() : undefined;
+                if (block.type === "tool_use" && typeof block.name === "string") {
+                    const event = buildToolEvent(block.name, object(block.input), result.cwd);
+                    if (event)
+                        result.events.push({
+                            id: typeof block.id === "string" ? `tool-${block.id}` : `${key}-${blockIndex}`,
+                            ...event,
+                            createdAt,
+                        });
+                }
+                else if (block.type === "text" && typeof block.text === "string" && block.text.trim()) {
+                    result.events.push({
+                        id: `${key}-${blockIndex}`,
+                        eventType: `message:${record.type}`,
+                        createdAt,
+                        payloadJson: JSON.stringify({ text: block.text.slice(0, 4000) }),
+                    });
+                }
+            }
+        }
+    }
+    finally {
+        lines.close();
+        input.destroy();
+    }
+    return result;
+}
+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;
+    }
+}
+async function fingerprint(path) {
+    const info = await stat(path, { bigint: true });
+    return `${process.env.SESSIONMEM_PROJECT_ID ?? ""}:${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}`;
+}
+export async function sweepTranscripts(context, options = {}) {
+    const directory = resolve(expandTilde(options.transcriptsDir ?? join(homedir(), ".claude", "projects")));
+    const summary = { filesFound: 0, sessionsImported: 0, memoriesCreated: 0, skipped: 0, errors: 0 };
+    const importedSessions = new Set();
+    const checkpoint = context.db.prepare("SELECT fingerprint FROM transcript_checkpoints WHERE path = ?");
+    const saveCheckpoint = context.db.prepare("INSERT OR REPLACE INTO transcript_checkpoints (path, fingerprint) VALUES (?, ?)");
+    for await (const path of transcriptFiles(directory)) {
+        summary.filesFound++;
+        try {
+            const before = await fingerprint(path);
+            if (checkpoint.get(path)?.fingerprint === before) {
+                summary.skipped++;
+                continue;
+            }
+            const transcript = await readTranscript(path);
+            if (!transcript.cwd || transcript.events.length === 0) {
+                summary.skipped++;
+                if (!transcript.malformed)
+                    saveCheckpoint.run(path, before);
+                else
+                    throw new Error("malformed or incomplete JSONL; will retry");
+                continue;
+            }
+            const projectId = deriveProjectId(transcript.cwd);
+            const sessionId = transcript.sessionId;
+            for (let offset = 0; offset < transcript.events.length; offset += MAX_INGEST_EVENTS) {
+                const result = await context.service.call("ingestSessionEvents", {
+                    projectId,
+                    sessionId,
+                    events: transcript.events.slice(offset, offset + MAX_INGEST_EVENTS).map(event => ({
+                        ...event, id: stableId(projectId, sessionId, event.id),
+                    })),
+                });
+                if (!result.ok)
+                    throw new Error(result.error.message);
+            }
+            const existing = context.db.prepare("SELECT id FROM memories WHERE project_id = ? AND session_id = ? AND kind = 'summary' LIMIT 1")
+                .get(projectId, sessionId);
+            // The pipeline upserts by project/session; keep existing hook summary IDs.
+            const memoryId = existing?.id ?? stableId(projectId, sessionId, "summary");
+            const result = await context.service.call("handleSessionEnd", {
+                projectId,
+                sessionId,
+                memoryId,
+                sourceAdapter: "claude-code",
+                config: handleSessionEndConfigSchema.parse({ minimumEventThreshold: 1, allowCloudSummarization: false }),
+            });
+            if (!result.ok)
+                throw new Error(result.error.message);
+            if (result.status !== "stored")
+                throw new Error(`summary ${result.status}; will retry`);
+            importedSessions.add(JSON.stringify([projectId, sessionId]));
+            summary.sessionsImported = importedSessions.size;
+            if (!existing)
+                summary.memoriesCreated++;
+            if (transcript.malformed)
+                throw new Error("malformed or incomplete JSONL; will retry");
+            // Never mark concurrent appends as processed. The next sweep replays safely.
+            if (await fingerprint(path) === before)
+                saveCheckpoint.run(path, before);
+        }
+        catch (error) {
+            summary.errors++;
+            process.stderr.write(`[sessionmem] ${path}: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+    }
+    return summary;
+}
+export function printSweepSummary(command, summary) {
+    console.log(`sessionmem ${command}: files found: ${summary.filesFound}; sessions imported: ${summary.sessionsImported}; memories created: ${summary.memoriesCreated}; skipped: ${summary.skipped}; errors: ${summary.errors}`);
+}

package/dist/core/api/contracts.js

@@ -160,6 +160,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

@@ -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,82 @@
+// 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) {
+    const full = JSON.stringify({
+        tool: toolName,
+        text,
+        input: shrinkValue(input),
+        cwd,
+    });
+    if (full.length <= MAX_HOOK_PAYLOAD_CHARS)
+        return full;
+    return JSON.stringify({ tool: toolName, text, cwd, 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),
+    };
+}