import { randomUUID } from "node:crypto"; import { setImmediate } from "node:timers/promises"; import { ArchiveLimitError, type BakArchive } from "./archive.js"; import { type RawWindow, readRawWindow } from "./raw.js"; import { S3Error, S3SizeLimitError } from "./s3.js"; import type { CatalogCache, SessionRecord } from "./state.js"; import type { BakFragment, BakOmitted, BakParams, BakRawResult, BakResult, BakSession, } from "./tool.js"; const DEFAULT_LIMIT = 20; const SNAPSHOT_TTL_MS = 10 * 60 * 1000; const MAX_SNAPSHOTS = 4; const MAX_SNAPSHOT_BYTES = 32 * 1024 * 1024; const MAX_PAGE_BYTES = 48 * 1024; const MAX_FRAGMENT_CHARS = 4096; type CompactData = | { action: "list" | "search"; items: BakSession[]; view?: undefined } | { action: "read"; view: "archive-history"; items: BakFragment[]; session: BakSession; omitted: BakOmitted; }; type RawData = { action: "read"; view: "raw-jsonl"; session: BakSession; etag: string; totalBytes: number; }; type SnapshotData = CompactData | RawData; type SnapshotMetadata = { createdAt: number; fetchedAt: string; bytes: number }; type Snapshot = SnapshotData & SnapshotMetadata; type CompactSnapshot = CompactData & SnapshotMetadata; type RawSnapshot = RawData & SnapshotMetadata; class QueryError extends Error {} function fail(message: string): never { throw new QueryError(`Bak query: ${message}`); } function isObject(value: unknown): value is Record { return value !== null && typeof value === "object" && !Array.isArray(value); } function safeEnd(value: string, start: number, maximum: number): number { let end = Math.min(value.length, start + maximum); const last = value.charCodeAt(end - 1); if (end < value.length && last >= 0xd800 && last <= 0xdbff) end--; return end; } function compare(left: string, right: string): number { return left < right ? -1 : left > right ? 1 : 0; } /** Query-owned snapshots never write cache, identity or restored session files. */ export class BakQuery { private readonly snapshots = new Map(); private snapshotBytes = 0; private active = 0; constructor( private readonly archive: Pick< BakArchive, "readCatalog" | "readSession" | "readSessionRange" >, private readonly secrets: readonly string[] = [], private readonly now: () => number = Date.now, ) {} clear(): void { this.snapshots.clear(); this.snapshotBytes = 0; } async execute(params: BakParams, signal?: AbortSignal): Promise { if (this.active >= 2) throw new Error( "Bak query: two reads already running; retry when one completes", ); this.active++; try { signal?.throwIfAborted(); const limit = ("limit" in params ? params.limit : undefined) ?? DEFAULT_LIMIT; if (!Number.isInteger(limit) || limit < 1 || limit > 100) fail("invalid page limit"); if ("cursor" in params) { if ( Object.keys(params).some( (key) => !["action", "cursor", "limit"].includes(key), ) ) fail( "cursor continuation cannot change selectors; restart without cursor", ); this.expire(); const cursor = /^([0-9a-f-]{36})\.(0|[1-9][0-9]{0,15})$/.exec( params.cursor, ); if (!cursor) fail("invalid cursor; restart without cursor"); const token = cursor[1]; if (!token) fail("invalid cursor; restart without cursor"); const snapshot = this.snapshots.get(token); if (!snapshot) fail("cursor expired or is unknown; restart without cursor"); if (snapshot.action !== params.action) fail("cursor action mismatch; restart without cursor"); const offset = Number(cursor[2]); if (!Number.isSafeInteger(offset)) fail("invalid cursor offset; restart without cursor"); if (snapshot.view === "raw-jsonl") { if ("limit" in params) fail("raw inspection uses byte pages, not item limits"); if (offset > snapshot.totalBytes) fail("invalid cursor offset; restart without cursor"); const window = await this.rawWindow( snapshot.session, offset, snapshot.etag, signal, ); if (window.totalBytes !== snapshot.totalBytes) fail("archive changed; restart inspection"); if (this.snapshots.get(token) !== snapshot) fail( "cursor expired or was evicted during inspection; restart without cursor", ); return this.rawResult(token, snapshot, offset, window); } if (offset > snapshot.items.length) fail("invalid cursor offset; restart without cursor"); return this.page(token, offset, limit); } const query = params.action === "search" ? params.query.trim().toLowerCase() : undefined; if (query !== undefined && (!query || query.length > 256)) fail("search needs a non-empty query of at most 256 characters"); const catalog = await this.archive.readCatalog(signal); signal?.throwIfAborted(); const sessions = await this.sessions( catalog, params.hostId, query, signal, ); let snapshot: SnapshotData; if (params.action === "read") { const session = sessions.find( (item) => item.sessionId === params.sessionId, ); if (!session) fail( "session is not indexed; list sessions again or wait for backup", ); if ("view" in params && params.view === "raw-jsonl") { const offset = params.byteOffset ?? 0; if ( !Number.isSafeInteger(offset) || offset < 0 || offset > Number.MAX_SAFE_INTEGER - 128 * 1024 ) fail("invalid raw archive byte offset"); const window = await this.rawWindow( session, offset, undefined, signal, ); const token = this.store({ action: "read", view: "raw-jsonl", session, etag: window.etag, totalBytes: window.totalBytes, }); const stored = this.snapshots.get(token); if (stored?.view !== "raw-jsonl") fail("inspection cursor is unavailable"); return this.rawResult(token, stored, offset, window); } const body = await this.archive.readSession( params.hostId, params.sessionId, signal, ); signal?.throwIfAborted(); const { fragments, omitted } = await this.project(body, signal); snapshot = { action: "read", view: "archive-history", items: fragments, session, omitted, }; } else snapshot = { action: params.action, items: sessions }; signal?.throwIfAborted(); return this.page(this.store(snapshot), 0, limit); } catch (error) { if (signal?.aborted) throw new Error("Bak query: cancelled or deadline exceeded"); if (error instanceof QueryError) throw new Error(error.message); if ( error instanceof S3SizeLimitError || error instanceof ArchiveLimitError ) throw new Error( params.action === "read" ? 'Bak query: compact archive read exceeds a safety limit; retry read with view: "raw-jsonl"' : "Bak query: archive response exceeds a safety limit", ); if ( error instanceof S3Error && (error.status === 401 || error.status === 403) ) throw new Error( "Bak query: archive access denied; check bucket read credentials", ); throw new Error( "Bak query: archive unavailable or invalid; retry or check /bak status", ); } finally { this.active--; } } private async rawWindow( session: BakSession, offset: number, etag: string | undefined, signal?: AbortSignal, ): Promise { try { const window = await readRawWindow( this.archive, session.hostId, session.sessionId, offset, this.secrets, etag, signal, ); signal?.throwIfAborted(); return window; } catch (error) { if (signal?.aborted) throw error; if ( error instanceof S3Error && (error.status === 401 || error.status === 403) ) throw error; if (error instanceof S3Error && error.status === 412) fail("archive changed; restart inspection"); if (error instanceof S3Error && error.status === 416) fail("raw byte offset is outside the archive"); fail( "raw inspection failed; use a UTF-8 boundary offset and storage supporting byte ranges with strong ETags", ); } } private rawResult( token: string, snapshot: RawSnapshot, offset: number, window: RawWindow, ): BakRawResult { const result = (text: string): BakRawResult => { const endByteExclusive = offset + Buffer.byteLength(text); return { action: "read", view: "raw-jsonl", trust: "untrusted-history", fetchedAt: snapshot.fetchedAt, session: structuredClone(snapshot.session), startByte: offset, endByteExclusive, totalBytes: snapshot.totalBytes, redaction: "configured-credentials", text, nextCursor: endByteExclusive < snapshot.totalBytes ? `${token}.${endByteExclusive}` : null, }; }; let low = 0; let high = window.text.length; while (low < high) { const middle = Math.ceil((low + high) / 2); const candidate = window.text.slice(0, safeEnd(window.text, 0, middle)); if ( Buffer.byteLength(JSON.stringify(result(candidate))) <= MAX_PAGE_BYTES ) low = middle; else high = middle - 1; } const page = result(window.text.slice(0, safeEnd(window.text, 0, low))); if (page.endByteExclusive === offset && offset < snapshot.totalBytes) fail("raw page did not advance"); return page; } private async sessions( cache: CatalogCache, hostId: string | undefined, query: string | undefined, signal?: AbortSignal, ): Promise { const result: BakSession[] = []; let seen = 0; for (const index of cache.indexes) { if (hostId !== undefined && index.hostId !== hostId) continue; for (const record of index.sessions) { if (++seen % 256 === 0) { await setImmediate(); signal?.throwIfAborted(); } if ( query !== undefined && ![record.name, record.cwd, record.id, index.alias, index.hostId].some( (value) => value !== undefined && this.redact(value).toLowerCase().includes(query), ) ) continue; result.push(this.session(index.hostId, index.alias, record)); } } return result.sort( (left, right) => compare(right.created, left.created) || compare(left.hostId, right.hostId) || compare(left.sessionId, right.sessionId), ); } private session( hostId: string, alias: string, record: SessionRecord, ): BakSession { // Redacting an identifier must not silently create an unusable or invalid reference. if (this.redact(hostId) !== hostId || this.redact(record.id) !== record.id) fail( "archive identifiers overlap configured credentials; cannot expose safe references", ); const name = record.name === undefined ? null : this.text(record.name, 512); const cwd = this.text(record.cwd, 512); const hostAlias = this.text(alias, 64); return { hostId, hostAlias: hostAlias.value, sessionId: record.id, name: name?.value ?? null, cwd: cwd.value, created: this.text(record.created, 64).value, metadataTruncated: cwd.truncated || hostAlias.truncated || (name?.truncated ?? false), }; } private async project( body: Uint8Array, signal?: AbortSignal, ): Promise<{ fragments: BakFragment[]; omitted: BakOmitted }> { const lines = new TextDecoder("utf-8", { fatal: true }) .decode(body) .split("\n"); const fragments: BakFragment[] = []; const omitted: BakOmitted = { thinking: 0, images: 0, system: 0, customState: 0, toolArguments: 0, other: 0, }; const header = this.json(lines[0] ?? ""); if (!isObject(header) || header["type"] !== "session") fail("malformed archive session"); for (let index = 1; index < lines.length; index++) { if (index % 128 === 0) { await setImmediate(); signal?.throwIfAborted(); } const line = lines[index] ?? ""; if (!line.trim()) continue; const entry = this.json(line); if (!isObject(entry) || typeof entry["type"] !== "string") fail("malformed archive session"); this.entryFragments(entry, index + 1, fragments, omitted); } return { fragments, omitted }; } private json(line: string): unknown { try { return JSON.parse(line) as unknown; } catch { fail("malformed archive session JSONL"); } } private entryFragments( entry: Record, line: number, fragments: BakFragment[], omitted: BakOmitted, ): void { const nullable = (value: unknown, maximum = 512) => typeof value === "string" ? this.text(value, maximum).value : null; const base = { entryId: nullable(entry["id"]), parentId: nullable(entry["parentId"]), timestamp: nullable(entry["timestamp"], 64), line, }; let kind: BakFragment["kind"]; let text: string; let toolName: string | null = null; let isError: boolean | null = null; if (entry["type"] === "message" && isObject(entry["message"])) { const message = entry["message"]; const role = message["role"]; if (role === "system") { omitted.system++; return; } if ( role === "bashExecution" && typeof message["command"] === "string" && typeof message["output"] === "string" ) { kind = role; text = `$ ${message["command"]}\n${message["output"]}`; isError = message["cancelled"] === true || (typeof message["exitCode"] === "number" && message["exitCode"] !== 0); } else if ( role === "user" || role === "assistant" || role === "toolResult" ) { kind = role; text = this.content(message["content"], omitted, role === "assistant"); if (role === "toolResult") { toolName = nullable(message["toolName"]); isError = typeof message["isError"] === "boolean" ? message["isError"] : null; } } else { omitted.other++; return; } } else if (entry["type"] === "custom_message") { kind = "custom_message"; text = this.content(entry["content"], omitted); } else if ( (entry["type"] === "compaction" || entry["type"] === "branch_summary") && typeof entry["summary"] === "string" ) { kind = entry["type"]; text = entry["summary"]; } else { if (entry["type"] === "custom") omitted.customState++; else omitted.other++; return; } const clean = this.redact(text); const pieces: string[] = []; for (let offset = 0; offset < clean.length; ) { const end = safeEnd(clean, offset, MAX_FRAGMENT_CHARS); pieces.push(clean.slice(offset, end)); offset = end; } for (const [part, piece] of pieces.entries()) fragments.push({ ...base, kind, toolName, isError, part: part + 1, parts: pieces.length, text: piece, }); } private content( value: unknown, omitted: BakOmitted, assistant = false, ): string { if (typeof value === "string") return value; if (!Array.isArray(value)) { omitted.other++; return ""; } const text: string[] = []; for (const part of value) { if (!isObject(part)) { omitted.other++; continue; } if (part["type"] === "text" && typeof part["text"] === "string") text.push(part["text"]); else if (part["type"] === "thinking") omitted.thinking++; else if (part["type"] === "image") omitted.images++; else if (assistant && part["type"] === "toolCall") { omitted.toolArguments++; const name = typeof part["name"] === "string" ? this.text(part["name"], 512).value : "unknown"; text.push(`\n[tool call: ${name}; arguments omitted]\n`); } else omitted.other++; } return text.join(""); } private redact(value: string): string { const secrets = this.secrets.filter(Boolean); const positions = secrets.map((secret) => value.indexOf(secret)); const parts: string[] = []; let copied = 0; for (;;) { const start = Math.min(...positions.filter((position) => position >= 0)); if (!Number.isFinite(start)) break; let end = start; let advanced: boolean; do { advanced = false; for (const [index, secret] of secrets.entries()) { const position = positions[index] ?? -1; if (position < 0 || position > end) continue; end = Math.max(end, position + secret.length); positions[index] = value.indexOf(secret, position + 1); advanced = true; } } while (advanced); parts.push(value.slice(copied, start), "[redacted]"); copied = end; } parts.push(value.slice(copied)); return parts.join(""); } private text( value: string, maximum: number, ): { value: string; truncated: boolean } { const clean = this.redact(value); return { value: clean.slice(0, safeEnd(clean, 0, maximum)), truncated: clean.length > maximum, }; } private store(data: SnapshotData): string { this.expire(); const createdAt = this.now(); const snapshot: Snapshot = { ...data, createdAt, fetchedAt: new Date(createdAt).toISOString(), bytes: 0, }; snapshot.bytes = Buffer.byteLength(JSON.stringify(snapshot)); if (snapshot.bytes > MAX_SNAPSHOT_BYTES) fail("snapshot exceeds memory limit; narrow by host or session"); while ( this.snapshots.size >= MAX_SNAPSHOTS || this.snapshotBytes + snapshot.bytes > MAX_SNAPSHOT_BYTES ) { const first = this.snapshots.entries().next().value; if (!first) break; this.remove(first[0], first[1]); } const token = randomUUID(); this.snapshots.set(token, snapshot); this.snapshotBytes += snapshot.bytes; return token; } private page(token: string, offset: number, limit: number): BakResult { const snapshot = this.snapshots.get(token); if (!snapshot) fail("cursor expired or is unknown; restart without cursor"); if (snapshot.view === "raw-jsonl") fail("raw inspection needs a byte-range read"); let end = offset; // Reserve the longest possible continuation so JSON escaping cannot exceed budget. let bytes = Buffer.byteLength( JSON.stringify( this.result( snapshot, offset, offset, `${token}.${snapshot.items.length}`, ), ), ); while (end < snapshot.items.length && end < offset + limit) { const addition = Buffer.byteLength(JSON.stringify(snapshot.items[end])) + (end > offset ? 1 : 0); if (bytes + addition > MAX_PAGE_BYTES) break; bytes += addition; end++; } if (end === offset && offset < snapshot.items.length) fail("one item exceeds page budget"); return structuredClone( this.result( snapshot, offset, end, end < snapshot.items.length ? `${token}.${end}` : null, ), ); } private result( snapshot: CompactSnapshot, offset: number, end: number, nextCursor: string | null, ): BakResult { const page = { fetchedAt: snapshot.fetchedAt, trust: "untrusted-history" as const, totalItems: snapshot.items.length, nextCursor, }; if (snapshot.action === "read") return { ...page, action: "read", view: "archive-history", order: "append", branches: "all", session: snapshot.session, omitted: snapshot.omitted, fragments: snapshot.items.slice(offset, end), }; return { ...page, action: snapshot.action, scope: "indexed-sessions", sessions: snapshot.items.slice(offset, end), }; } private expire(): void { for (const [token, snapshot] of this.snapshots) if (this.now() - snapshot.createdAt >= SNAPSHOT_TTL_MS) this.remove(token, snapshot); } private remove(token: string, snapshot: Snapshot): void { this.snapshots.delete(token); this.snapshotBytes -= snapshot.bytes; } }