import type { ExtensionAPI, ExtensionContext, } from "@earendil-works/pi-coding-agent"; import { keyHint } from "@earendil-works/pi-coding-agent"; import { stripTerminalSequences, Text } from "@earendil-works/pi-tui"; import { type Static, Type } from "typebox"; import { Value } from "typebox/value"; import { closeDebug, dbg } from "./src/debug.ts"; import type { RunOptions } from "./src/exec.ts"; import { pruneSpills, runSql, type SqlOutcome } from "./src/exec.ts"; import { DEFAULT_TIMEOUT_MS, MAX_SQL_LENGTH, MAX_TIMEOUT_MS, SCHEMA_VERSION, } from "./src/guide.ts"; import { resolveSetting } from "./src/pi-ext-settings.ts"; import { DATABASE_SETTING, defaultDatabasePath } from "./src/settings.ts"; import type { MemoryStore } from "./src/store.ts"; const parameters = Type.Object( { sql: Type.String({ minLength: 1, maxLength: MAX_SQL_LENGTH, description: "One SQLite statement, or several separated by ';'. Full DDL/DML.", }), params: Type.Optional( Type.Array( Type.Union([Type.String(), Type.Number(), Type.Boolean(), Type.Null()]), { maxItems: 100, description: "Positional bind values for a single-statement call.", }, ), ), readonly: Type.Optional( Type.Boolean({ description: "Enforce a read-only connection. Writes fail cleanly instead of mutating.", }), ), timeoutMs: Type.Optional( Type.Integer({ minimum: 1000, maximum: MAX_TIMEOUT_MS, description: `Kill statements that run longer than this. Default ${DEFAULT_TIMEOUT_MS}.`, }), ), }, { additionalProperties: false }, ); const jsonValue = Type.Union([ Type.String(), Type.Number(), Type.Boolean(), Type.Null(), ]); const outputSchema = Type.Object({ status: Type.String(), rowCount: Type.Integer(), columns: Type.Array(Type.String()), rows: Type.Array(Type.Array(jsonValue)), truncated: Type.Boolean(), spillPath: Type.Union([Type.String(), Type.Null()]), changes: Type.Integer(), durationMs: Type.Integer(), tablesTouched: Type.Array(Type.String()), schemaChanged: Type.Boolean(), journalSeq: Type.Integer(), }); type MemoryArgs = Static; function validateArgs(value: unknown): MemoryArgs { if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("memory: expected object arguments with an 'sql' string"); if (!Value.Check(parameters, value)) { const error = Value.Errors(parameters, value)[0]; const field = error && "path" in error && typeof error.path === "string" ? error.path.split("/")[1] : "arguments"; throw new Error( `memory: invalid field ${field}: ${error?.message ?? "schema mismatch"}`, ); } return value; } function statusLine(outcome: SqlOutcome): string { if (outcome.schemaChanged) return `schema changed (${outcome.tablesTouched.join(", ") || "no table attributed"}); document it in _schema_docs`; if (outcome.changes > 0) return `${outcome.changes} row(s) written`; if (outcome.truncated) return `${outcome.rowCount} rows; first ${outcome.rows.length} inline, full set spilled to a temp file`; return `${outcome.rowCount} row(s)`; } export default function memoryExtension(pi: ExtensionAPI): void { let store: MemoryStore | undefined; let opening: Promise | undefined; let generation = 0; async function database(ctx: ExtensionContext): Promise { if (store) return store; if (opening) return opening; const setting = resolveSetting(pi, ctx, DATABASE_SETTING); if (!setting.ok) throw new Error(setting.error); const path = setting.source === "default" ? defaultDatabasePath() : setting.value; const token = generation; opening = (async () => { const { MemoryStore } = await import("./src/store.ts"); const next = await MemoryStore.open(path); if (generation !== token) { next.close(); throw new Error("Memory session closed during open"); } store = next; dbg?.("database.open", { outcome: "ok" }); return next; })(); try { return await opening; } catch (error) { dbg?.("database.open", { outcome: error instanceof Error && error.name === "V1DatabaseError" ? "refused" : "error", }); throw error; } finally { opening = undefined; } } pi.registerTool({ name: "memory", annotations: { readOnlyHint: false }, label: "Memory", description: `Your knowledge store: one local SQLite database whose schema you own and evolve with full SQL. Start by SELECT * FROM _guide (conventions) and _schema_docs (what each table means); INSERT a row into _schema_docs whenever you CREATE or ALTER a user table. Suggested shape: facts(entity, attribute, value, observed_at, source), append-only events(kind, subject, payload, occurred_at), edges(from_id, kind, to_id). Context is data: project/topic columns, not separate tables. readonly=true enforces a read-only connection. Reserved: _journal/_stats_samples/_health_runs are readable but not writable; ATTACH, VACUUM INTO, and PRAGMA application_id/user_version/journal_mode are blocked (single-file audit boundary). Results over ${50} rows are truncated with a temp NDJSON spill path; statements are killed at timeoutMs (default ${DEFAULT_TIMEOUT_MS / 1000}s). Never store secrets; keep transactions short.`, parameters, outputSchema, async execute(_id, args, signal, _onUpdate, ctx) { if (signal?.aborted) throw new Error("Memory operation aborted"); const parsed = validateArgs(args); const db = await database(ctx); if (signal?.aborted) throw new Error("Memory operation aborted"); let outcome: SqlOutcome; try { const options: RunOptions = { actor: "agent", readonly: parsed.readonly ?? false, params: parsed.params ?? [], }; if (parsed.timeoutMs !== undefined) options.timeoutMs = parsed.timeoutMs; outcome = await runSql(db, parsed.sql, options); } catch (error) { dbg?.("tool.call", { outcome: /was killed/u.test( error instanceof Error ? error.message : "", ) ? "timeout" : /blocked|reserved/u.test( error instanceof Error ? error.message : "", ) ? "denied" : "error", readonly: parsed.readonly ?? false, durationMs: 0, rowsReturned: 0, schemaChanged: false, }); throw error; } dbg?.("tool.call", { outcome: "ok", readonly: parsed.readonly ?? false, rowsReturned: outcome.rowCount, durationMs: outcome.durationMs, schemaChanged: outcome.schemaChanged, }); const data = { status: statusLine(outcome), rowCount: outcome.rowCount, columns: outcome.columns, rows: outcome.rows, truncated: outcome.truncated, spillPath: outcome.spillPath, changes: outcome.changes, durationMs: outcome.durationMs, tablesTouched: outcome.tablesTouched, schemaChanged: outcome.schemaChanged, journalSeq: outcome.journalSeq, }; return { content: [{ type: "text", text: JSON.stringify(data) }], details: data, structuredContent: data, }; }, renderCall(args, theme, context) { const summary = typeof args?.sql === "string" ? stripTerminalSequences(args.sql) .replaceAll(/\s+/gu, " ") .slice(0, 60) : "…"; const title = theme.fg("toolTitle", `memory ${summary}`); return new Text( context.expanded ? `${title}\n${stripTerminalSequences(JSON.stringify(args) ?? "")}` : `${title} · ${(context.keyHint ?? keyHint)("app.tools.expand", "to expand")}`, 0, 0, ); }, renderResult(result, { expanded }, theme, context) { const details = result.details; const status = details && typeof details === "object" && "status" in details ? String(details.status).slice(0, 120) : "result"; const body = expanded ? result.content .filter((c) => c.type === "text") .map((c) => c.text) .join("\n") : `${status} · ${(context.keyHint ?? keyHint)("app.tools.expand", "to expand")}`; return new Text( theme.fg("toolOutput", stripTerminalSequences(body)), 0, 0, ); }, }); pi.registerCommand("memory", { description: `Browse, query, and audit the agent knowledge store (SQLite v${SCHEMA_VERSION})`, async handler(args, ctx) { if (ctx.mode !== "tui") { ctx.ui.notify( "The memory viewer requires interactive TUI; the memory tool works headlessly.", "warning", ); return; } dbg?.("viewer.open", { outcome: "ok" }); try { const db = await database(ctx); const { viewer } = await import("./src/viewer.ts"); await viewer(pi, db, ctx, args.trim()); } catch (error) { ctx.ui.notify( error instanceof Error ? error.message : "Memory viewer failed", "error", ); } }, }); pi.on("session_start", (_event, _ctx) => { dbg?.("session.start"); if (!store) return; const db = store; void Promise.resolve() .then(() => { pruneSpills(new Date()); db.pruneRetention(new Date()); }) .catch(() => { // Retention is best effort; the journal simply grows this session. }); }); pi.on("session_shutdown", () => { generation++; store?.close(); store = undefined; dbg?.("session.shutdown"); closeDebug(); }); }