attention-manifest-protocol 0.4.2 → 0.4.4

package/lib/database/repository/hookRepository.d.ts

@@ -0,0 +1,67 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { HookRecorder, HookRunEntry } from "../../hook/types.js";
+import type { HookRunRow } from "../entity/hook.js";
+import type { SqlParameter } from "../sql/sql.js";
+import { BaseRepository } from "./base.js";
+/**
+ * Repository for `hook_runs`.
+ */
+export declare class HookRepository extends BaseRepository<HookRunRow, string> {
+    /**
+     * Create the repository.
+     *
+     * @param db - Open SQLite connection.
+     */
+    constructor(db: DatabaseSync);
+    /**
+     * Append one hook run. The row is immutable afterwards; a retry is a new
+     * run with a new id, not an update of the old row.
+     *
+     * @param entry - Run entry produced by `Hook.run`.
+     */
+    append(entry: HookRunEntry & {
+        sessionId: string;
+    }): void;
+    /**
+     * Read one session's runs, newest first.
+     *
+     * @param sessionId - Session handle.
+     * @param limit - Maximum rows; zero is allowed and returns nothing.
+     * @returns Run rows.
+     */
+    list(sessionId: string, limit: number): HookRunRow[];
+    /**
+     * Count one session's runs. With no argument it counts the whole table.
+     * The trailing `params` keeps the inherited `count(clause, ...params)`
+     * behaviour available when a caller passes bound values; a lone string is
+     * interpreted as a session id because that is this repository's contract.
+     *
+     * @param sessionId - Session handle, empty for every row, or a WHERE clause
+     * when `params` is non-empty.
+     * @param params - Bound values for the inherited clause form.
+     * @returns Number of matching runs.
+     */
+    count(sessionId?: string, ...params: SqlParameter[]): number;
+}
+/**
+ * Hook recorder backed by a SQLite repository.
+ *
+ * A recorder instance owns one repository over the injected connection; it does
+ * not open, migrate or close the store. `record` never throws, by contract.
+ */
+export declare class SqliteHookRecorder implements HookRecorder {
+    private readonly repository;
+    /**
+     * Create a recorder.
+     *
+     * @param db - Open SQLite connection with the `hook_runs` table.
+     */
+    constructor(db: DatabaseSync);
+    /**
+     * Append one entry. A repository failure is swallowed so the hook result is
+     * unaffected.
+     *
+     * @param entry - Run entry.
+     */
+    record(entry: HookRunEntry): void;
+}

package/lib/database/repository/hookRepository.js

@@ -0,0 +1,150 @@
+/**
+ * SQLite repository and recorder for hook runs.
+ *
+ * Every `Hook.run` produces one `HookRunEntry`; `SqliteHookRecorder` writes it
+ * to `hook_runs` through {@link HookRepository}. The recorder is deliberately
+ * best-effort: `record` catches repository failures and returns, because an
+ * audit store that is temporarily unavailable must not turn a successful read
+ * or write into a failed hook result.
+ *
+ * `run_id` is `run.` plus 16 hex characters rather than an autoincrement, so a
+ * row can be identified before insert and two stores cannot confuse each
+ * other's ordering. `list` reads newest first by `started_at` and breaks ties on
+ * `run_id`, which keeps the order deterministic for runs in the same
+ * millisecond.
+ */
+import { randomBytes } from "node:crypto";
+import { HookRunTable } from "../entity/hook.js";
+import { assertSqlIdentifier } from "../sql/sql.js";
+import { BaseRepository } from "./base.js";
+/**
+ * Quote a column that is declared by the table metadata.
+ *
+ * @param meta - Table metadata.
+ * @param column - Column name.
+ * @returns Double-quoted column name.
+ */
+const quoted = (meta, column) => {
+    if (!meta.columns.includes(column)) {
+        throw new Error(`unknown column for ${meta.table}: ${column}`);
+    }
+    return `"${assertSqlIdentifier(column)}"`;
+};
+/**
+ * Build a bound `column = ?` conjunction from declared columns.
+ *
+ * @param meta - Table metadata.
+ * @param columns - Column names in bind order.
+ * @returns SQL fragment with one placeholder per column.
+ */
+const conditions = (meta, columns) => columns.map((column) => `${quoted(meta, column)} = ?`).join(" AND ");
+/**
+ * Generate a run id: `run.` plus 16 random hex characters.
+ *
+ * @returns Opaque run id.
+ */
+const newRunId = () => `run.${randomBytes(8).toString("hex")}`;
+/**
+ * Repository for `hook_runs`.
+ */
+export class HookRepository extends BaseRepository {
+    /**
+     * Create the repository.
+     *
+     * @param db - Open SQLite connection.
+     */
+    constructor(db) {
+        super(db, HookRunTable);
+    }
+    /**
+     * Append one hook run. The row is immutable afterwards; a retry is a new
+     * run with a new id, not an update of the old row.
+     *
+     * @param entry - Run entry produced by `Hook.run`.
+     */
+    append(entry) {
+        this.insert({
+            run_id: newRunId(),
+            session_id: entry.sessionId,
+            hook: entry.hook,
+            path: entry.path ?? null,
+            status: entry.status,
+            error: entry.error ?? null,
+            revision: entry.revision,
+            input_digest: entry.inputDigest,
+            output_digest: entry.outputDigest,
+            started_at: entry.startedAt,
+            duration_ms: entry.durationMs,
+            meta_json: "{}",
+        });
+    }
+    /**
+     * Read one session's runs, newest first.
+     *
+     * @param sessionId - Session handle.
+     * @param limit - Maximum rows; zero is allowed and returns nothing.
+     * @returns Run rows.
+     */
+    list(sessionId, limit) {
+        if (!Number.isInteger(limit) || limit < 0) {
+            throw new RangeError("limit must be a non-negative integer");
+        }
+        return this.queries.select({
+            where: conditions(HookRunTable, ["session_id"]),
+            params: [sessionId],
+            orderBy: `ORDER BY ${quoted(HookRunTable, "started_at")} DESC, ${quoted(HookRunTable, "run_id")} DESC`,
+            limit,
+        });
+    }
+    /**
+     * Count one session's runs. With no argument it counts the whole table.
+     * The trailing `params` keeps the inherited `count(clause, ...params)`
+     * behaviour available when a caller passes bound values; a lone string is
+     * interpreted as a session id because that is this repository's contract.
+     *
+     * @param sessionId - Session handle, empty for every row, or a WHERE clause
+     * when `params` is non-empty.
+     * @param params - Bound values for the inherited clause form.
+     * @returns Number of matching runs.
+     */
+    count(sessionId = "", ...params) {
+        if (params.length > 0) {
+            return super.count(sessionId, ...params);
+        }
+        if (sessionId.length === 0) {
+            return super.count();
+        }
+        return super.count(`${quoted(HookRunTable, "session_id")} = ?`, sessionId);
+    }
+}
+/**
+ * Hook recorder backed by a SQLite repository.
+ *
+ * A recorder instance owns one repository over the injected connection; it does
+ * not open, migrate or close the store. `record` never throws, by contract.
+ */
+export class SqliteHookRecorder {
+    repository;
+    /**
+     * Create a recorder.
+     *
+     * @param db - Open SQLite connection with the `hook_runs` table.
+     */
+    constructor(db) {
+        this.repository = new HookRepository(db);
+    }
+    /**
+     * Append one entry. A repository failure is swallowed so the hook result is
+     * unaffected.
+     *
+     * @param entry - Run entry.
+     */
+    record(entry) {
+        try {
+            this.repository.append(entry);
+        }
+        catch {
+            return;
+        }
+    }
+}

package/lib/database/repository/index.d.ts

@@ -18,3 +18,10 @@ export { OutboxRepository } from "./outboxRepository.js";
 export { RuntimeSessionRepository } from "./runtimeSessionRepository.js";
 export { RuntimeTurnRepository } from "./runtimeTurnRepository.js";
 export { RuntimeApprovalRepository } from "./runtimeApprovalRepository.js";
+export { WorkspaceSessionRepository } from "./workspaceSessionRepository.js";
+export { FileNodeRepository } from "./fileNodeRepository.js";
+export { FileAnnotationRepository } from "./fileAnnotationRepository.js";
+export { FileWriteRepository } from "./fileWriteRepository.js";
+export { FileOutlineRepository } from "./fileOutlineRepository.js";
+export { FileGraphRepository } from "./fileGraphRepository.js";
+export { HookRepository, SqliteHookRecorder } from "./hookRepository.js";

package/lib/database/repository/index.js

@@ -15,3 +15,10 @@ export { OutboxRepository } from "./outboxRepository.js";
 export { RuntimeSessionRepository } from "./runtimeSessionRepository.js";
 export { RuntimeTurnRepository } from "./runtimeTurnRepository.js";
 export { RuntimeApprovalRepository } from "./runtimeApprovalRepository.js";
+export { WorkspaceSessionRepository } from "./workspaceSessionRepository.js";
+export { FileNodeRepository } from "./fileNodeRepository.js";
+export { FileAnnotationRepository } from "./fileAnnotationRepository.js";
+export { FileWriteRepository } from "./fileWriteRepository.js";
+export { FileOutlineRepository } from "./fileOutlineRepository.js";
+export { FileGraphRepository } from "./fileGraphRepository.js";
+export { HookRepository, SqliteHookRecorder } from "./hookRepository.js";

package/lib/database/repository/workspaceSessionRepository.d.ts

@@ -0,0 +1,134 @@
+/**
+ * SQLite repository for workspace sessions, their authorized roots and their
+ * private context.
+ *
+ * The descriptor lives in `workspace_sessions`; roots are normalized into
+ * `session_roots` so an authorization query never parses JSON, and context
+ * entries use the deterministic `sessionId + "\0" + namespace + "\0" + key`
+ * entry id. Multi-row writes run in a transaction, so a reader never observes a
+ * session with half of its roots or a half-replaced context.
+ */
+import type { DatabaseSync } from "node:sqlite";
+import type { SessionContextEntry, SessionDescriptor, SessionId, SessionRoot } from "../../session/types.js";
+import type { WorkspaceSessionRow } from "../entity/workspaceSession.js";
+import { BaseRepository } from "./base.js";
+/**
+ * Repository for `workspace_sessions`, `session_roots` and `session_context`.
+ */
+export declare class WorkspaceSessionRepository extends BaseRepository<WorkspaceSessionRow, string> {
+    private readonly rootsSql;
+    private readonly contextSql;
+    /**
+     * Create the repository.
+     *
+     * @param db - Open SQLite connection.
+     */
+    constructor(db: DatabaseSync);
+    /**
+     * Insert or replace one session descriptor and its roots in one transaction.
+     *
+     * `permissions` and `metadata` are persisted as canonical JSON; `status` is
+     * validated before the write. Roots are replaced (delete, then insert) so a
+     * removed grant cannot survive a resave.
+     *
+     * @param descriptor - Public session record.
+     * @param tokenHash - `sha256:<hex>` bearer digest; never the token itself.
+     * @throws Error when the status is outside the closed lifecycle.
+     */
+    save(descriptor: SessionDescriptor, tokenHash: string): void;
+    /**
+     * Load one descriptor with its roots.
+     *
+     * @param sessionId - Session handle.
+     * @returns Descriptor, or `undefined` when the session is unknown.
+     */
+    load(sessionId: SessionId): SessionDescriptor | undefined;
+    /**
+     * Read the persisted bearer digest for authentication after a restart.
+     *
+     * @param sessionId - Session handle.
+     * @returns Token hash, or `undefined` when the session is unknown.
+     */
+    loadSecret(sessionId: SessionId): string | undefined;
+    /**
+     * Delete one session with its roots and context in one transaction.
+     *
+     * The boolean overload is the domain contract used by {@link SessionStore};
+     * the numeric overload mirrors `BaseRepository.delete` so the class remains
+     * substitutable for the generated CRUD base.
+     *
+     * @param sessionId - Session handle.
+     * @returns `true` when a session row was removed.
+     */
+    delete(sessionId: SessionId): boolean;
+    /**
+     * Base-repository compatible delete overload.
+     *
+     * @param id - Session handle.
+     * @returns Number of removed session rows.
+     */
+    delete(id: string): number;
+    /**
+     * List sessions, optionally narrowed to one agent.
+     *
+     * @param agentId - Optional host-assigned agent identity.
+     * @returns Descriptors ordered by creation time and id.
+     */
+    list(agentId?: string): SessionDescriptor[];
+    /**
+     * Read the authorized roots of one session.
+     *
+     * @param sessionId - Session handle.
+     * @returns Roots ordered by host path.
+     */
+    findRoots(sessionId: SessionId): SessionRoot[];
+    /**
+     * Read every context entry of one session.
+     *
+     * @param sessionId - Session handle.
+     * @returns Entries ordered by namespace and key.
+     */
+    loadContext(sessionId: SessionId): SessionContextEntry[];
+    /**
+     * Insert or replace one context entry.
+     *
+     * The value is stored as canonical JSON; `bytes` is the caller's canonical
+     * size and is persisted as given so quota accounting stays reproducible.
+     *
+     * @param sessionId - Session handle.
+     * @param entry - Context entry.
+     * @throws Error when the session id, namespace or key contains NUL.
+     * @throws RangeError when `bytes` is not a non-negative integer.
+     * @throws TypeError when the value cannot round-trip through canonical JSON.
+     */
+    putContext(sessionId: SessionId, entry: SessionContextEntry): void;
+    /**
+     * Delete one context entry.
+     *
+     * @param sessionId - Session handle.
+     * @param namespace - Context namespace.
+     * @param key - Namespace-local key.
+     * @returns `true` when an entry was removed.
+     */
+    deleteContext(sessionId: SessionId, namespace: string, key: string): boolean;
+    /**
+     * Delete every context entry of one session.
+     *
+     * @param sessionId - Session handle.
+     */
+    deleteContextSession(sessionId: SessionId): void;
+    /**
+     * Atomically replace the whole context of one session.
+     *
+     * @param sessionId - Session handle.
+     * @param entries - Complete new entry set.
+     */
+    replaceContext(sessionId: SessionId, entries: readonly SessionContextEntry[]): void;
+    /**
+     * Convert one row plus its roots into the public descriptor.
+     *
+     * @param row - Session row.
+     * @returns Descriptor; `parentId` is present only when the row has a parent.
+     */
+    private toDescriptor;
+}