Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/memory/index.ts

Raw
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<typeof parameters>;

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<MemoryStore> | undefined;
	let generation = 0;

	async function database(ctx: ExtensionContext): Promise<MemoryStore> {
		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();
	});
}