@roj-ai/kompjutr-platform 0.0.0 → 0.2.10

package/src/fs.ts

@@ -0,0 +1,232 @@
+/**
+ * `FileSystem` port over a kompjutr workspace.
+ *
+ * kompjutr ships a node:fs-shaped shim (`NodeFsCompat`) over its own bulk-first
+ * `Filesystem`, and the shim already answers the port's optional verbs in the
+ * shape the port asks for. So most of this file forwards. What it does not
+ * forward is what the shim does not do, or does with different semantics than
+ * the port states — `appendFile`, a recursive `cp`, and a walk's symlink sizes.
+ */
+
+import type { Filesystem, NodeFsCompat, Stat } from '@kompjutr/do'
+import type { FileSystem, ReadableFileHandle, ReadFilesEntry, WalkEntry, WalkOptions, WriteFilesEntry, WriteFilesOptions } from '@roj-ai/sdk/platform'
+
+/** Pages a subtree scan. kompjutr caps a page at 1,000 rows. */
+const SCAN_PAGE = 1_000
+
+/** What `Filesystem.copyFiles` accepts in one call. */
+const COPY_BATCH = 1_000
+
+export interface KompjutrFileSystemOptions {
+	/** The node:fs-shaped shim. `Workspace.fs`. */
+	compat: NodeFsCompat
+	/** The bulk API underneath it, over the same database. `Workspace.filesystem`. */
+	filesystem: Filesystem
+}
+
+function toBytes(data: string | Uint8Array): Uint8Array {
+	return typeof data === 'string' ? new TextEncoder().encode(data) : data
+}
+
+function fileError(code: string, path: string, message: string): Error {
+	return Object.assign(new Error(`${message}: ${path}`), { code, path })
+}
+
+/** The port's `type`, which names a directory in full and admits things kompjutr cannot produce. */
+function walkType(type: Stat['type']): WalkEntry['type'] {
+	if (type === 'dir') return 'directory'
+	return type
+}
+
+export function createKompjutrFileSystem(options: KompjutrFileSystemOptions): FileSystem {
+	const { compat, filesystem } = options
+
+	/** Every path under `root`, parents before children. Excludes `root` itself. */
+	const scanSubtree = (root: string): string[] => {
+		const paths: string[] = []
+		let after: string | undefined
+		for (;;) {
+			const page = filesystem.scan(root, { after, limit: SCAN_PAGE })
+			if (page.length === 0) return paths
+			for (const entry of page) paths.push(entry.path)
+			if (page.length < SCAN_PAGE) return paths
+			after = page[page.length - 1]?.path
+		}
+	}
+
+	/** Copies inside SQLite, so file bytes never enter the isolate. */
+	const copyEntries = (entries: { source: string; destination: string }[], force = true): void => {
+		let pending = entries.filter(({ source, destination }) => {
+			const sourceStat = filesystem.stat(source)
+			const destinationStat = filesystem.stat(destination)
+			if (sourceStat !== null && destinationStat !== null && sourceStat.ino === destinationStat.ino) {
+				throw fileError('ERR_FS_CP_EINVAL', destination, 'source and destination are the same file')
+			}
+			if (sourceStat?.type === 'dir' && destinationStat !== null && destinationStat.type !== 'dir') {
+				throw fileError('ERR_FS_CP_DIR_TO_NON_DIR', destination, 'cannot overwrite a non-directory with a directory')
+			}
+			if (sourceStat?.type !== 'dir' && destinationStat?.type === 'dir') {
+				throw fileError('ERR_FS_CP_NON_DIR_TO_DIR', destination, 'cannot overwrite a directory with a non-directory')
+			}
+			return force || destinationStat === null || sourceStat?.type === 'dir'
+		})
+		while (pending.length > 0) {
+			const batch = filesystem.copyFiles(pending.slice(0, COPY_BATCH), {
+				parents: true,
+			})
+			const deferred = [...batch.remaining, ...pending.slice(COPY_BATCH)]
+			if (deferred.length >= pending.length) throw fileError('EIO', pending[0]?.source ?? '', 'copy made no progress')
+			pending = deferred
+		}
+	}
+
+	const remove = (path: string, rmOptions?: { recursive?: boolean; force?: boolean }): void => {
+		if (!rmOptions?.recursive && filesystem.stat(path)?.type === 'dir') {
+			throw fileError('ERR_FS_EISDIR', path, 'is a directory')
+		}
+		compat.rmSync(path, rmOptions)
+	}
+
+	return {
+		// Every method here is `async`, and deliberately so: kompjutr's shim reaches
+		// its synchronous core through `Promise.resolve(xSync(...))`, so a failure
+		// throws where the port says it rejects. `async` puts that back.
+		readFile: (async (path: string, encoding?: 'utf-8' | 'utf8') =>
+			encoding ? compat.readFileSync(path, { encoding }) : compat.readFileSync(path)) as FileSystem['readFile'],
+
+		writeFile: async (path, data) => {
+			compat.writeFileSync(path, data)
+		},
+
+		// The shim's own appendFile is ENOSYS; write at the current end instead.
+		appendFile: async (path, data) => {
+			const stat = filesystem.statTarget(path)
+			if (stat === null) {
+				compat.writeFileSync(path, data)
+				return
+			}
+			filesystem.writeRange(path, toBytes(data), stat.size)
+		},
+
+		mkdir: async (path, mkdirOptions) => {
+			compat.mkdirSync(path, mkdirOptions)
+		},
+
+		readdir: (async (path: string, readdirOptions?: { withFileTypes: true }) =>
+			readdirOptions?.withFileTypes ? compat.readdirSync(path, { withFileTypes: true }) : compat.readdirSync(path)) as FileSystem['readdir'],
+
+		stat: async (path) => compat.statSync(path),
+		lstat: async (path) => compat.lstatSync(path),
+		access: async (path, mode) => {
+			compat.accessSync(path, mode)
+		},
+
+		unlink: async (path) => {
+			compat.unlinkSync(path)
+		},
+
+		rm: async (path, rmOptions) => {
+			remove(path, rmOptions)
+		},
+
+		cp: async (source, dest, cpOptions) => {
+			const stat = filesystem.stat(source)
+			if (stat === null) throw fileError('ENOENT', source, 'no such file or directory')
+			if (stat.type !== 'dir') {
+				copyEntries([{ source, destination: dest }], cpOptions?.force)
+				return
+			}
+			if (!cpOptions?.recursive) throw fileError('EISDIR', source, 'is a directory')
+			const root = filesystem.realpath(source)
+			copyEntries(
+				[
+					{ source: root, destination: dest },
+					...scanSubtree(root).map((path) => ({
+						source: path,
+						destination: `${dest}${path.slice(root.length)}`,
+					})),
+				],
+				cpOptions?.force,
+			)
+		},
+
+		// The shim exposes fds, not handles; wrap one in the read subset the port uses.
+		open: async (path, flags): Promise<ReadableFileHandle> => {
+			const fd = compat.openSync(path, flags ?? 'r')
+			return {
+				stat: async () => compat.fstatSync(fd),
+				read: async (buffer, offset, length, position) => ({
+					bytesRead: compat.readSync(fd, buffer, offset, length, position),
+					buffer,
+				}),
+				close: async () => {
+					compat.closeSync(fd)
+				},
+			}
+		},
+
+		exists: async (path) => compat.existsSync(path),
+		realpath: async (path) => compat.realpathSync(path),
+
+		walk: async (dir: string, walkOptions?: WalkOptions): Promise<WalkEntry[]> => {
+			const entries = await compat.walk(dir, walkOptions)
+			return entries.map((entry) => ({
+				path: entry.path,
+				type: walkType(entry.type),
+				// The shim reports a symlink's own size; the port wants the target's,
+				// because the readdir-and-stat loop it replaces follows the link.
+				size: entry.type === 'symlink' ? (filesystem.statTarget(entry.path)?.size ?? 0) : entry.size,
+				mtime: entry.mtime,
+			}))
+		},
+
+		readFiles: async (paths: readonly string[]): Promise<ReadFilesEntry[]> => {
+			try {
+				const entries = await compat.readFiles(paths)
+				return entries.map((entry, index) => ({
+					path: paths[index] ?? entry.path,
+					...(entry.content === undefined ? {} : { content: Buffer.from(entry.content) }),
+					...(entry.error === undefined ? {} : { error: entry.error }),
+				}))
+			} catch (error) {
+				if (!(error instanceof Error) || !('code' in error) || (error.code !== 'ENOTDIR' && error.code !== 'ELOOP')) throw error
+				// Path resolution can abort the upstream batch before it reports individual failures.
+				return Promise.all(
+					paths.map(async (path): Promise<ReadFilesEntry> => {
+						try {
+							const [entry] = await compat.readFiles([path])
+							if (!entry) throw new Error('readFiles returned no entry')
+							return {
+								path,
+								...(entry.content === undefined ? {} : { content: Buffer.from(entry.content) }),
+								...(entry.error === undefined ? {} : { error: entry.error }),
+							}
+						} catch (entryError) {
+							if (entryError instanceof Error && 'code' in entryError && typeof entryError.code === 'string') {
+								return { path, error: entryError.code }
+							}
+							throw entryError
+						}
+					}),
+				)
+			}
+		},
+
+		// The bulk primitive replaces final links; resolve them as single writes do.
+		writeFiles: async (entries: readonly WriteFilesEntry[], writeOptions?: WriteFilesOptions) => {
+			filesystem.writeFiles(
+				entries.map((entry) => ({
+					path: filesystem.realpath(entry.path),
+					bytes: toBytes(entry.content),
+				})),
+				{ parents: writeOptions?.createParents ?? false },
+			)
+		},
+
+		rmFiles: async (paths: readonly string[], rmOptions?: { recursive?: boolean; force?: boolean }) => {
+			for (const path of paths) remove(path, rmOptions)
+		},
+
+		scopeReads: (fn) => filesystem.withReadScope(fn),
+	}
+}

package/src/git.ts

@@ -0,0 +1,74 @@
+/**
+ * `GitClient` port over kompjutr's git runtime.
+ *
+ * The port names four questions `git-status` asks, and kompjutr answers each
+ * one directly rather than by walking a tree: status reads its index tracker,
+ * and `divergence` counts both sides of a fork in one call. Two of the four had
+ * no honest answer over the binding this replaces.
+ */
+
+import type { GitClient, GitCommit, GitCountAheadOptions, GitLogOptions, GitRepoOptions, GitStatusEntry } from '@roj-ai/sdk/platform'
+import type { Git, StatusEntry } from '@kompjutr/do'
+
+/**
+ * kompjutr's ordinary codes are already the port's alphabet. Three are not:
+ * a rename is an add at the new path, an unmerged path is a modification, and
+ * an ignored one is not a change anybody asked about.
+ */
+function toStatusEntry(entry: StatusEntry): GitStatusEntry | undefined {
+	if (entry.index === '!' || entry.worktree === '!') return undefined
+	const index = entry.index === 'R' ? 'A' : entry.index === 'U' ? 'M' : entry.index
+	const worktree = entry.worktree === 'U' ? 'M' : entry.worktree
+	return { path: entry.path, index, worktree }
+}
+
+export function createKompjutrGitClient(git: Git): GitClient {
+	return {
+		async status(options: GitRepoOptions): Promise<GitStatusEntry[]> {
+			const entries = await git.status({ dir: options.dir })
+			return entries.map(toStatusEntry).filter((entry): entry is GitStatusEntry => entry !== undefined)
+		},
+
+		async log(options: GitLogOptions): Promise<GitCommit[]> {
+			const commits = await git.log({
+				dir: options.dir,
+				ref: options.ref,
+				depth: options.depth,
+			})
+			return commits.map((commit) => ({
+				oid: commit.oid,
+				message: commit.message,
+				// Git counts seconds; every SDK timestamp is milliseconds.
+				committedAt: commit.committer.timestamp * 1000,
+			}))
+		},
+
+		async countAhead(options: GitCountAheadOptions): Promise<number> {
+			if (options.missingBase === 'all' && (await git.tryRevParse({ dir: options.dir, ref: options.base })) === undefined) {
+				const commits = await git.log({ dir: options.dir, ref: options.ref ?? 'HEAD' })
+				return commits.length
+			}
+			const result = await git.divergence({
+				dir: options.dir,
+				current: options.ref ?? 'HEAD',
+				upstream: options.base,
+			})
+			return result.ahead
+		},
+
+		async defaultBranch(options: GitRepoOptions): Promise<string | undefined> {
+			try {
+				const ref = await git.readRef({
+					dir: options.dir,
+					ref: 'refs/remotes/origin/HEAD',
+				})
+				if (ref.kind !== 'symbolic') return undefined
+				const prefix = 'refs/remotes/origin/'
+				return ref.target.startsWith(prefix) ? ref.target.slice(prefix.length) || undefined : undefined
+			} catch {
+				// "undefined means unknown, so the caller applies its own default."
+				return undefined
+			}
+		},
+	}
+}

package/src/index.ts

@@ -0,0 +1,83 @@
+/**
+ * Platform adapter backed by a kompjutr workspace.
+ *
+ * Lets `@roj-ai/sdk` run against a filesystem and git runtime that are SQLite
+ * rows rather than files on a disk — inside a Durable Object, or anywhere else
+ * that can hand kompjutr a SQL storage.
+ */
+
+import type { Platform, Scheduler } from '@roj-ai/sdk/platform'
+import { createTimerScheduler } from '@roj-ai/sdk/platform'
+import type { Git, Workspace } from '@kompjutr/do'
+import { KompjutrEventStore } from './event-store.js'
+import { createKompjutrFileSystem } from './fs.js'
+import { createKompjutrGitClient } from './git.js'
+import { KompjutrLLMCallLog } from './llm-call-log.js'
+import type { KompjutrLLMCallLogOptions } from './llm-call-log.js'
+import { createUnsupportedProcessRunner } from './process.js'
+import { KompjutrSessionLog } from './session-log.js'
+import { createKompjutrShellRunner } from './shell.js'
+
+export interface KompjutrPlatformOptions {
+	/** Scratch directory, created if it is not there. Defaults to `/tmp`. */
+	tmpDir?: string
+	/**
+	 * Drives the agent loop's re-entry. Defaults to timers, which is correct
+	 * while the process lives and lost when it does not. A Durable Object passes
+	 * an alarm-backed scheduler so a wake survives its isolate.
+	 */
+	scheduler?: Scheduler
+	/** Retention and column ceiling for the LLM call log. */
+	llmCallLog?: KompjutrLLMCallLogOptions
+	/** How the workspace itself is isolated. Defaults to `none`. */
+	shellConfinement?: 'host' | 'none'
+}
+
+export function createKompjutrPlatform(workspace: Workspace, options: KompjutrPlatformOptions = {}): Platform {
+	const tmpDir = options.tmpDir ?? '/tmp'
+	// A fresh workspace holds only `/`, and the port promises tmpDir is there.
+	workspace.filesystem.mkdir(tmpDir, { recursive: true })
+
+	const git = workspaceGit(workspace)
+
+	return {
+		fs: createKompjutrFileSystem({
+			compat: workspace.fs,
+			filesystem: workspace.filesystem,
+		}),
+		process: createUnsupportedProcessRunner(),
+		shell: createKompjutrShellRunner({
+			filesystem: workspace.filesystem,
+			git,
+			confinement: options.shellConfinement,
+		}),
+		git: git && createKompjutrGitClient(git),
+		// Omit fsRevision: kompjutr 0.1.2 does not bump it for Git-only mutations.
+		// Rows, not files: both logs live in the same database as the filesystem,
+		// and an append there is one statement against a ranged write through it.
+		sessionLog: new KompjutrSessionLog(workspace.db),
+		llmCallLog: new KompjutrLLMCallLog(workspace.db, options.llmCallLog),
+		scheduler: options.scheduler ?? createTimerScheduler(),
+		tmpDir,
+	}
+}
+
+/** The getter throws unless `WorkspaceOptions.git` was set — the only signal a workspace gives. */
+function workspaceGit(workspace: Workspace): Git | undefined {
+	try {
+		return workspace.git
+	} catch {
+		return undefined
+	}
+}
+
+export { KompjutrEventStore } from './event-store.js'
+export { createKompjutrFileSystem } from './fs.js'
+export type { KompjutrFileSystemOptions } from './fs.js'
+export { createKompjutrGitClient } from './git.js'
+export { KompjutrLLMCallLog } from './llm-call-log.js'
+export type { KompjutrLLMCallLogOptions } from './llm-call-log.js'
+export { createUnsupportedProcessRunner } from './process.js'
+export { KompjutrSessionLog } from './session-log.js'
+export { createKompjutrShellRunner } from './shell.js'
+export type { KompjutrShellRunnerOptions } from './shell.js'

package/src/llm-call-log.ts

@@ -0,0 +1,204 @@
+import type { SqlDatabase } from '@kompjutr/do'
+import type { LLMCallOutcome, LLMCallPage, LLMCallRow, LLMCallStatus, LLMCallStore } from '@roj-ai/sdk/platform'
+import { LLMCallPayloads, storedNumber, storedString } from './llm-call-payloads.js'
+
+const CALLS_TABLE = 'roj_llm_call'
+const PAYLOAD_FORMAT = 1
+const DEFAULT_MAX_CALLS_PER_SESSION = 200
+
+export interface KompjutrLLMCallLogOptions {
+	/** Calls retained per session. Default 200; `0` keeps every call. */
+	maxCallsPerSession?: number
+	/** Opt-in caller request clamp in UTF-8 bytes; undefined or <= 0 disables it. Does not control storage chunk size. */
+	maxBlobBytes?: number
+}
+
+interface CallRecord {
+	call_rowid: unknown
+	payload_format: unknown
+	call_id: unknown
+	agent_id: unknown
+	created_at: unknown
+	status: unknown
+	model: unknown
+	request: unknown
+	completed_at: unknown
+	duration_ms: unknown
+	provider_request_id: unknown
+	response: unknown
+	metrics: unknown
+	error: unknown
+}
+
+const COLUMNS = 'call_id, agent_id, created_at, status, model, request, completed_at, duration_ms, provider_request_id, response, metrics, error'
+const READ_COLUMNS = `rowid AS call_rowid, payload_format, ${COLUMNS}`
+
+function toStatus(value: unknown): LLMCallStatus {
+	if (value === 'running' || value === 'success' || value === 'error') return value
+	throw new Error('Invalid LLM call status')
+}
+
+function optionalString(value: unknown): string | undefined {
+	return value === null ? undefined : storedString(value)
+}
+
+function optionalNumber(value: unknown): number | undefined {
+	return value === null ? undefined : storedNumber(value)
+}
+
+function format(value: unknown): number {
+	if (value === 0 || value === PAYLOAD_FORMAT) return value
+	throw new Error('Unsupported LLM call payload format')
+}
+
+export class KompjutrLLMCallLog implements LLMCallStore {
+	readonly maxBlobBytes: number | undefined
+	readonly #maxCallsPerSession: number
+	readonly #payloads: LLMCallPayloads
+
+	constructor(
+		private readonly db: SqlDatabase,
+		options: KompjutrLLMCallLogOptions = {},
+	) {
+		this.#maxCallsPerSession = options.maxCallsPerSession ?? DEFAULT_MAX_CALLS_PER_SESSION
+		this.maxBlobBytes = options.maxBlobBytes !== undefined && options.maxBlobBytes > 0 ? options.maxBlobBytes : undefined
+		this.#payloads = this.db.transactionSync(() => {
+			this.db.run(`CREATE TABLE IF NOT EXISTS ${CALLS_TABLE} (
+				session_id TEXT NOT NULL, call_id TEXT NOT NULL, agent_id TEXT NOT NULL, created_at INTEGER NOT NULL,
+				status TEXT NOT NULL, model TEXT NOT NULL, request TEXT NOT NULL, completed_at INTEGER, duration_ms INTEGER,
+				provider_request_id TEXT, response TEXT, metrics TEXT, error TEXT, payload_format INTEGER NOT NULL DEFAULT 0
+			)`)
+			const columns = this.db.all<{ name: unknown }>(`PRAGMA table_info(${CALLS_TABLE})`)
+			if (!columns.some((column) => storedString(column.name) === 'payload_format')) {
+				this.db.run(`ALTER TABLE ${CALLS_TABLE} ADD COLUMN payload_format INTEGER NOT NULL DEFAULT 0`)
+			}
+			this.db.run(`CREATE UNIQUE INDEX IF NOT EXISTS ${CALLS_TABLE}_by_id ON ${CALLS_TABLE} (session_id, call_id)`)
+			return new LLMCallPayloads(db)
+		})
+	}
+
+	async create(sessionId: string, row: LLMCallRow): Promise<void> {
+		this.db.transactionSync(() => {
+			const record = this.db.one<{ call_rowid: unknown }>(
+				`INSERT INTO ${CALLS_TABLE} (session_id, ${COLUMNS}, payload_format)
+				 VALUES (?, ?, '', ?, ?, '', '', ?, ?, NULL, NULL, NULL, NULL, ?) RETURNING rowid AS call_rowid`,
+				sessionId,
+				row.callId,
+				row.createdAt,
+				row.status,
+				row.completedAt ?? null,
+				row.durationMs ?? null,
+				PAYLOAD_FORMAT,
+			)
+			if (record === undefined) throw new Error('Missing inserted LLM call')
+			const rowid = storedNumber(record.call_rowid)
+			this.#writeRequest(rowid, row)
+			this.#writeOutcome(rowid, row)
+			this.#trim(sessionId)
+		})
+	}
+
+	async complete(sessionId: string, callId: string, outcome: LLMCallOutcome): Promise<void> {
+		this.db.transactionSync(() => {
+			const record = this.db.one<{ call_rowid: unknown; payload_format: unknown }>(
+				`SELECT rowid AS call_rowid, payload_format FROM ${CALLS_TABLE} WHERE session_id = ? AND call_id = ?`,
+				sessionId,
+				callId,
+			)
+			if (record === undefined) return
+			const rowid = storedNumber(record.call_rowid)
+			if (format(record.payload_format) === 0) {
+				const legacy = this.#get(sessionId, callId)
+				if (legacy === null) throw new Error('Missing legacy LLM call')
+				this.#writeRequest(rowid, legacy)
+				this.db.run(`UPDATE ${CALLS_TABLE} SET agent_id = '', model = '', request = '' WHERE rowid = ?`, rowid)
+			}
+			this.#writeOutcome(rowid, outcome)
+			this.db.run(
+				`UPDATE ${CALLS_TABLE} SET status = ?, completed_at = ?, duration_ms = ?, payload_format = ?,
+				 provider_request_id = NULL, response = NULL, metrics = NULL, error = NULL WHERE rowid = ?`,
+				outcome.status,
+				outcome.completedAt,
+				outcome.durationMs,
+				PAYLOAD_FORMAT,
+				rowid,
+			)
+		})
+	}
+
+	async get(sessionId: string, callId: string): Promise<LLMCallRow | null> {
+		return this.db.transactionSync(() => this.#get(sessionId, callId))
+	}
+
+	async list(sessionId: string, options: { limit: number; offset: number }): Promise<LLMCallPage> {
+		return this.db.transactionSync(() => {
+			const records = this.db.all<CallRecord>(
+				`SELECT ${READ_COLUMNS} FROM ${CALLS_TABLE} WHERE session_id = ? ORDER BY call_id DESC LIMIT ? OFFSET ?`,
+				sessionId,
+				options.limit,
+				options.offset,
+			)
+			return { calls: records.map((record) => this.#toRow(record)), total: this.#count(sessionId) }
+		})
+	}
+
+	async delete(sessionId: string): Promise<number> {
+		return this.db.transactionSync(() => {
+			const calls = this.#count(sessionId)
+			this.db.run(`DELETE FROM ${CALLS_TABLE} WHERE session_id = ?`, sessionId)
+			return calls
+		})
+	}
+
+	#get(sessionId: string, callId: string): LLMCallRow | null {
+		const record = this.db.one<CallRecord>(`SELECT ${READ_COLUMNS} FROM ${CALLS_TABLE} WHERE session_id = ? AND call_id = ?`, sessionId, callId)
+		return record === undefined ? null : this.#toRow(record)
+	}
+
+	#toRow(record: CallRecord): LLMCallRow {
+		const rowid = storedNumber(record.call_rowid)
+		const chunked = format(record.payload_format) === PAYLOAD_FORMAT
+		return {
+			callId: storedString(record.call_id),
+			agentId: storedString(chunked ? this.#payloads.read(rowid, 'agent_id') : record.agent_id),
+			createdAt: storedNumber(record.created_at),
+			status: toStatus(record.status),
+			model: storedString(chunked ? this.#payloads.read(rowid, 'model') : record.model),
+			request: storedString(chunked ? this.#payloads.read(rowid, 'request') : record.request),
+			completedAt: optionalNumber(record.completed_at),
+			durationMs: optionalNumber(record.duration_ms),
+			providerRequestId: chunked ? this.#payloads.read(rowid, 'provider_request_id') : optionalString(record.provider_request_id),
+			response: chunked ? this.#payloads.read(rowid, 'response') : optionalString(record.response),
+			metrics: chunked ? this.#payloads.read(rowid, 'metrics') : optionalString(record.metrics),
+			error: chunked ? this.#payloads.read(rowid, 'error') : optionalString(record.error),
+		}
+	}
+
+	#writeRequest(rowid: number, row: LLMCallRow): void {
+		this.#payloads.write(rowid, 'agent_id', row.agentId)
+		this.#payloads.write(rowid, 'model', row.model)
+		this.#payloads.write(rowid, 'request', row.request)
+	}
+
+	#writeOutcome(rowid: number, outcome: Pick<LLMCallOutcome, 'providerRequestId' | 'response' | 'metrics' | 'error'>): void {
+		this.#payloads.write(rowid, 'provider_request_id', outcome.providerRequestId)
+		this.#payloads.write(rowid, 'response', outcome.response)
+		this.#payloads.write(rowid, 'metrics', outcome.metrics)
+		this.#payloads.write(rowid, 'error', outcome.error)
+	}
+
+	#trim(sessionId: string): void {
+		if (this.#maxCallsPerSession <= 0) return
+		this.db.run(
+			`DELETE FROM ${CALLS_TABLE} WHERE session_id = ?
+			 AND call_id < (SELECT call_id FROM ${CALLS_TABLE} WHERE session_id = ? ORDER BY call_id DESC LIMIT 1 OFFSET ?)`,
+			sessionId,
+			sessionId,
+			this.#maxCallsPerSession - 1,
+		)
+	}
+
+	#count(sessionId: string): number {
+		return storedNumber(this.db.scalar(`SELECT COUNT(*) FROM ${CALLS_TABLE} WHERE session_id = ?`, sessionId))
+	}
+}

package/src/llm-call-payloads.ts

@@ -0,0 +1,95 @@
+import type { SqlDatabase } from '@kompjutr/do'
+
+const CHUNK_BYTES = 256 * 1024
+const encoder = new TextEncoder()
+const decoder = new TextDecoder('utf-8', { fatal: true })
+
+type PayloadField = 'agent_id' | 'model' | 'request' | 'provider_request_id' | 'response' | 'metrics' | 'error'
+
+export function storedString(value: unknown): string {
+	if (typeof value !== 'string') throw new Error('Invalid LLM call string')
+	return value
+}
+
+export function storedNumber(value: unknown): number {
+	if (typeof value !== 'number' || !Number.isFinite(value)) throw new Error('Invalid LLM call number')
+	return value
+}
+
+function storedInteger(value: unknown): number {
+	const number = storedNumber(value)
+	if (!Number.isSafeInteger(number) || number < 0) throw new Error('Invalid LLM payload integer')
+	return number
+}
+
+export class LLMCallPayloads {
+	constructor(private readonly db: SqlDatabase) {
+		db.run(`CREATE TABLE IF NOT EXISTS roj_llm_payload (
+			call_rowid INTEGER NOT NULL, field TEXT NOT NULL, chunk_count INTEGER NOT NULL, byte_length INTEGER,
+			PRIMARY KEY (call_rowid, field)
+		) WITHOUT ROWID`)
+		db.run(`CREATE TABLE IF NOT EXISTS roj_llm_payload_chunk (
+			call_rowid INTEGER NOT NULL, field TEXT NOT NULL, chunk_index INTEGER NOT NULL, data BLOB NOT NULL,
+			PRIMARY KEY (call_rowid, field, chunk_index)
+		) WITHOUT ROWID`)
+		// Explicit cleanup also works when the host leaves SQLite foreign keys disabled.
+		db.run(`CREATE TRIGGER IF NOT EXISTS roj_llm_call_payload_delete AFTER DELETE ON roj_llm_call BEGIN
+			DELETE FROM roj_llm_payload_chunk WHERE call_rowid = OLD.rowid;
+			DELETE FROM roj_llm_payload WHERE call_rowid = OLD.rowid;
+		END`)
+	}
+
+	write(rowid: number, field: PayloadField, value: string | undefined): void {
+		// JSON string encoding preserves even lone UTF-16 surrogates through UTF-8 storage.
+		const bytes = value === undefined ? undefined : encoder.encode(JSON.stringify(value))
+		const count = bytes === undefined ? 0 : Math.ceil(bytes.byteLength / CHUNK_BYTES)
+		this.db.run('DELETE FROM roj_llm_payload_chunk WHERE call_rowid = ? AND field = ?', rowid, field)
+		this.db.run(
+			'INSERT OR REPLACE INTO roj_llm_payload (call_rowid, field, chunk_count, byte_length) VALUES (?, ?, ?, ?)',
+			rowid,
+			field,
+			count,
+			bytes?.byteLength ?? null,
+		)
+		if (bytes === undefined) return
+		for (let index = 0; index < count; index++) {
+			this.db.run(
+				'INSERT INTO roj_llm_payload_chunk (call_rowid, field, chunk_index, data) VALUES (?, ?, ?, ?)',
+				rowid,
+				field,
+				index,
+				bytes.slice(index * CHUNK_BYTES, (index + 1) * CHUNK_BYTES).buffer,
+			)
+		}
+	}
+
+	read(rowid: number, field: PayloadField): string | undefined {
+		const metadata = this.db.one<{ chunk_count: unknown; byte_length: unknown }>(
+			'SELECT chunk_count, byte_length FROM roj_llm_payload WHERE call_rowid = ? AND field = ?',
+			rowid,
+			field,
+		)
+		if (metadata === undefined) throw new Error(`Missing LLM payload metadata: ${field}`)
+		const count = storedInteger(metadata.chunk_count)
+		const length = metadata.byte_length === null ? null : storedInteger(metadata.byte_length)
+		if (count !== (length === null ? 0 : Math.ceil(length / CHUNK_BYTES)) || length === 0) throw new Error(`Invalid LLM payload size: ${field}`)
+		const chunks = this.db.all<{ chunk_index: unknown; data: unknown }>(
+			'SELECT chunk_index, data FROM roj_llm_payload_chunk WHERE call_rowid = ? AND field = ? ORDER BY chunk_index',
+			rowid,
+			field,
+		)
+		if (chunks.length !== count) throw new Error(`Missing or extra LLM payload chunks: ${field}`)
+		if (length === null) return undefined
+		const bytes = new Uint8Array(length)
+		for (const [index, chunk] of chunks.entries()) {
+			if (storedInteger(chunk.chunk_index) !== index) throw new Error(`Invalid LLM payload order: ${field}`)
+			const data = chunk.data instanceof ArrayBuffer ? new Uint8Array(chunk.data) : chunk.data
+			if (!(data instanceof Uint8Array) || data.byteLength !== Math.min(CHUNK_BYTES, length - index * CHUNK_BYTES)) {
+				throw new Error(`Invalid LLM payload chunk: ${field}`)
+			}
+			bytes.set(data, index * CHUNK_BYTES)
+		}
+		const value: unknown = JSON.parse(decoder.decode(bytes))
+		return storedString(value)
+	}
+}