@agentic-kit/run-log-gate 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# @agentic-kit/run-log-gate
+
+Tool approvals over the run log. The request, the human's answer and every
+settled gate decision are entries in the run's log — `agent_event` rows once
+the store is the platform's — so a desktop run, a cloud pi Job and the agentic
+lane all ask in one place and are answered from any surface that projects the
+log (`RunsPanel`, `pendingApprovals` → `resolveApproval`).
+
+## Three pieces
+
+- `runLogApprovals` — an `ApprovalChannel` for `@agentic-kit/harness`'s
+  `RunGate`. Submits a `constructive.approval.request` entry and polls the log
+  for the matching `constructive.approval.resolution`. The request entry's id
+  is derived from the tool call id, so a retried submit is the same entry and
+  the store's idempotency drops it instead of asking a human twice.
+  `resolveApproval` is the other end for a local run and the tests.
+- `runLogGateDecisions` — an `onDecision` sink that appends every settled
+  decision as a `constructive.gate.decision` entry (audit: which calls the gate
+  refused, on whose authority) and a `flush()` that rethrows the first write
+  that failed.
+- `createRunLogGateHost` — the harness's `GateHost` (what `createConfirmGate`
+  and `createGatedToolset` drive) built on the two above: `confirmTool` asks in
+  the log and returns what the log settled on, `notifyToolSkipped` files the
+  skipped repeat as a denial, `drain()` surfaces a lost write.
+
+Nothing here executes on the strength of a click: the decision is the record
+that was persisted and read back. A host may mirror a concise notice into a
+conversation thread, but the thread is never the authority.
+
+## Consumers
+
+In constructive-db: `pi-job-host` (the cloud pi Job — `RunGate` over
+`runLogApprovals` + `runLogGateDecisions`), the `code_task` agentic lane and
+`ui/desktop`'s capability gate (`createRunLogGateHost`).
+
+## Testing
+
+`pnpm test` — the store (`MemoryRunLogStore`), the clock and the sleep are all
+injectable, so every path is covered without a database or a network.
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pglite-test](https://github.com/constructive-io/constructive/tree/main/postgres/pglite-test): **🪶 Drop-in pgsql-test replacement backed by PGlite** — in-process Postgres, no server required, instance-per-suite isolation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+### 📚 Documentation & Skills
+
+* [constructive-skills](https://github.com/constructive-io/constructive-skills): **📖 Platform documentation and AI agent skills** — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.
+
+Install skills for AI coding agents:
+
+```bash
+# All platform skills (security, blueprints, codegen, billing, etc.)
+npx skills add constructive-io/constructive-skills
+
+# Individual repo skills (pgpm, testing, CLI, search, etc.)
+npx skills add https://github.com/constructive-io/constructive --skill pgpm
+npx skills add https://github.com/constructive-io/constructive --skill constructive-testing
+```
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/approvals.d.ts

@@ -0,0 +1,52 @@
+import type { ApprovalChannel, ApprovalRequest } from '@agentic-kit/harness';
+import type { ApprovalResolutionInput, RunLogStore } from '@agentic-kit/run-log';
+export interface RunLogApprovalsOptions {
+    store: RunLogStore;
+    runId: string;
+    /** Poll delay while a request is outstanding. */
+    intervalMs?: number;
+    /** Give up after this long; omit to wait as long as a human takes. */
+    timeoutMs?: number;
+    /** Verdict on timeout. The gate defaults it to `deny`. */
+    onTimeout?: 'deny' | 'allow';
+    /** Records per read while polling. */
+    pageLimit?: number;
+    /**
+     * The text a human is shown for a request. Defaults to the tool's name and
+     * the policy's reason; a host that already composed a title and a message
+     * for the call passes them through here.
+     */
+    prompt?: (request: ApprovalRequest) => string;
+    now?: () => Date;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * The entry id an approval request is written under.
+ *
+ * Deterministic on the tool call, so a retried submit is the same entry and the
+ * store's own idempotency drops the duplicate instead of asking a human twice.
+ */
+export declare const approvalEntryId: (toolCallId: string) => string;
+/**
+ * An `ApprovalChannel` whose request and answer are both records in the run's
+ * log.
+ */
+export declare function runLogApprovals(options: RunLogApprovalsOptions): ApprovalChannel;
+/**
+ * Answer a pending request by appending the resolution.
+ *
+ * The UI writes this through the API; a local run and the tests write it here.
+ * Either way it is one more entry in the same log, which is what makes "approve a
+ * cloud agent from a browser tab" nothing more than an insert.
+ */
+export declare function resolveApproval(store: RunLogStore, runId: string, input: ApprovalResolutionInput, clock?: {
+    now?: () => Date;
+}): Promise<void>;
+/**
+ * The log's last entry id — the parent an out-of-band entry hangs from, so the
+ * rehydrated session file stays one tree rather than gaining a second root.
+ *
+ * Exported for the other writers of out-of-band entries (gate decisions), not
+ * for the package's consumers.
+ */
+export declare function leafId(store: RunLogStore, runId: string, pageLimit?: number): Promise<string | null>;

package/approvals.js

@@ -0,0 +1,152 @@
+"use strict";
+// Approvals over the run log.
+//
+// The gate needs a human, and a Job has no socket to one: it writes the request
+// into the log and reads the answer back out of it. Both directions are rows, so
+// a browser hours later still sees the pending request — the log *is* the
+// approval UI's state — and the run resumes the moment the resolution lands.
+//
+// `@agentic-kit/harness` already owns the waiting (`pollingApprovalChannel`);
+// this is only its two ends bound to a `RunLogStore`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.approvalEntryId = void 0;
+exports.runLogApprovals = runLogApprovals;
+exports.resolveApproval = resolveApproval;
+exports.leafId = leafId;
+const harness_1 = require("@agentic-kit/harness");
+const run_log_1 = require("@agentic-kit/run-log");
+/**
+ * The entry id an approval request is written under.
+ *
+ * Deterministic on the tool call, so a retried submit is the same entry and the
+ * store's own idempotency drops the duplicate instead of asking a human twice.
+ */
+const approvalEntryId = (toolCallId) => `approval-${toolCallId}`;
+exports.approvalEntryId = approvalEntryId;
+/**
+ * An `ApprovalChannel` whose request and answer are both records in the run's
+ * log.
+ */
+function runLogApprovals(options) {
+    const { store, runId } = options;
+    const now = options.now ?? (() => new Date());
+    const prompt = options.prompt ?? defaultPrompt;
+    // Where reading resumed from last time: an approval may take hours, and
+    // re-reading the whole run per poll would grow with the transcript.
+    let cursor = run_log_1.START;
+    // Resolutions seen so far, kept across pages: an answer can land many pages
+    // after the request it answers.
+    const resolved = new Map();
+    const refresh = async () => {
+        const page = await store.read(runId, cursor, options.pageLimit);
+        if (page.records.length === 0)
+            return;
+        cursor = page.cursor;
+        for (const record of page.records) {
+            const outcome = resolutionOf(record);
+            if (outcome)
+                resolved.set(outcome.toolCallId, outcome.outcome);
+        }
+    };
+    const channelOptions = {
+        submit: async (request) => {
+            const parentId = await leafId(store, runId, options.pageLimit);
+            const entry = {
+                type: 'message',
+                id: (0, exports.approvalEntryId)(request.toolCallId),
+                parentId,
+                timestamp: now().toISOString(),
+                message: (0, run_log_1.approvalRequestMessage)({
+                    toolCallId: request.toolCallId,
+                    prompt: prompt(request)
+                })
+            };
+            await store.append(runId, [entry]);
+        },
+        poll: async (request) => {
+            await refresh();
+            return resolved.get(request.toolCallId);
+        },
+        // One clock for both the entry timestamps and the timeout, so a suite that
+        // fakes time fakes all of it.
+        now: () => now().getTime(),
+        ...(options.intervalMs === undefined ? {} : { intervalMs: options.intervalMs }),
+        ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+        ...(options.onTimeout === undefined ? {} : { onTimeout: options.onTimeout }),
+        ...(options.sleep === undefined ? {} : { sleep: options.sleep })
+    };
+    return (0, harness_1.pollingApprovalChannel)(channelOptions);
+}
+/**
+ * Answer a pending request by appending the resolution.
+ *
+ * The UI writes this through the API; a local run and the tests write it here.
+ * Either way it is one more entry in the same log, which is what makes "approve a
+ * cloud agent from a browser tab" nothing more than an insert.
+ */
+async function resolveApproval(store, runId, input, clock = {}) {
+    const now = clock.now ?? (() => new Date());
+    const parentId = await leafId(store, runId);
+    const entry = {
+        type: 'message',
+        id: `resolution-${input.toolCallId}`,
+        parentId,
+        timestamp: now().toISOString(),
+        message: (0, run_log_1.approvalResolutionMessage)(input)
+    };
+    await store.append(runId, [entry]);
+}
+/**
+ * A record read as an approval answer, or `undefined` when it is anything else.
+ *
+ * The projectors surface a resolution only alongside the tool call it belongs
+ * to, and a Job polling for its own answer has not necessarily logged that call
+ * yet, so the answer is read straight off the record.
+ */
+function resolutionOf(record) {
+    // This gate answers a pi session, so a record another harness wrote is not
+    // its answer to read.
+    if (record.transcriptFormat !== run_log_1.PI_TRANSCRIPT_FORMAT)
+        return undefined;
+    const entry = (0, run_log_1.assertPiSessionEntry)(record.entry);
+    if (!(0, run_log_1.isPiMessageEntry)(entry))
+        return undefined;
+    const message = entry.message;
+    if (message.role !== 'custom' || message.customType !== run_log_1.APPROVAL_RESOLUTION_TYPE) {
+        return undefined;
+    }
+    const details = typeof message.details === 'object' && message.details !== null
+        ? message.details
+        : {};
+    const toolCallId = details.toolCallId;
+    if (typeof toolCallId !== 'string' || toolCallId.length === 0) {
+        throw new Error(`approval resolution at seq ${String(record.seq)} carries no toolCallId — the ` +
+            'gate cannot tell which tool call it answers');
+    }
+    const { reason, actorId } = details;
+    return {
+        toolCallId,
+        outcome: {
+            decision: details.decision === 'approved' ? 'allow' : 'deny',
+            ...(typeof reason === 'string' ? { reason } : {}),
+            ...(typeof actorId === 'string' ? { actorId } : {})
+        }
+    };
+}
+const defaultPrompt = ({ toolName, reason }) => reason ? `${toolName}: ${reason}` : `${toolName} needs approval`;
+/**
+ * The log's last entry id — the parent an out-of-band entry hangs from, so the
+ * rehydrated session file stays one tree rather than gaining a second root.
+ *
+ * Exported for the other writers of out-of-band entries (gate decisions), not
+ * for the package's consumers.
+ */
+async function leafId(store, runId, pageLimit) {
+    const records = await (0, run_log_1.readAll)(store, runId, run_log_1.START, pageLimit);
+    for (let index = records.length - 1; index >= 0; index -= 1) {
+        const entry = records[index].entry;
+        if (typeof entry.id === 'string' && entry.id.length > 0)
+            return entry.id;
+    }
+    return null;
+}

package/esm/approvals.d.ts

@@ -0,0 +1,52 @@
+import type { ApprovalChannel, ApprovalRequest } from '@agentic-kit/harness';
+import type { ApprovalResolutionInput, RunLogStore } from '@agentic-kit/run-log';
+export interface RunLogApprovalsOptions {
+    store: RunLogStore;
+    runId: string;
+    /** Poll delay while a request is outstanding. */
+    intervalMs?: number;
+    /** Give up after this long; omit to wait as long as a human takes. */
+    timeoutMs?: number;
+    /** Verdict on timeout. The gate defaults it to `deny`. */
+    onTimeout?: 'deny' | 'allow';
+    /** Records per read while polling. */
+    pageLimit?: number;
+    /**
+     * The text a human is shown for a request. Defaults to the tool's name and
+     * the policy's reason; a host that already composed a title and a message
+     * for the call passes them through here.
+     */
+    prompt?: (request: ApprovalRequest) => string;
+    now?: () => Date;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * The entry id an approval request is written under.
+ *
+ * Deterministic on the tool call, so a retried submit is the same entry and the
+ * store's own idempotency drops the duplicate instead of asking a human twice.
+ */
+export declare const approvalEntryId: (toolCallId: string) => string;
+/**
+ * An `ApprovalChannel` whose request and answer are both records in the run's
+ * log.
+ */
+export declare function runLogApprovals(options: RunLogApprovalsOptions): ApprovalChannel;
+/**
+ * Answer a pending request by appending the resolution.
+ *
+ * The UI writes this through the API; a local run and the tests write it here.
+ * Either way it is one more entry in the same log, which is what makes "approve a
+ * cloud agent from a browser tab" nothing more than an insert.
+ */
+export declare function resolveApproval(store: RunLogStore, runId: string, input: ApprovalResolutionInput, clock?: {
+    now?: () => Date;
+}): Promise<void>;
+/**
+ * The log's last entry id — the parent an out-of-band entry hangs from, so the
+ * rehydrated session file stays one tree rather than gaining a second root.
+ *
+ * Exported for the other writers of out-of-band entries (gate decisions), not
+ * for the package's consumers.
+ */
+export declare function leafId(store: RunLogStore, runId: string, pageLimit?: number): Promise<string | null>;

package/esm/approvals.js

@@ -0,0 +1,145 @@
+// Approvals over the run log.
+//
+// The gate needs a human, and a Job has no socket to one: it writes the request
+// into the log and reads the answer back out of it. Both directions are rows, so
+// a browser hours later still sees the pending request — the log *is* the
+// approval UI's state — and the run resumes the moment the resolution lands.
+//
+// `@agentic-kit/harness` already owns the waiting (`pollingApprovalChannel`);
+// this is only its two ends bound to a `RunLogStore`.
+import { pollingApprovalChannel } from '@agentic-kit/harness';
+import { APPROVAL_RESOLUTION_TYPE, approvalRequestMessage, approvalResolutionMessage, assertPiSessionEntry, isPiMessageEntry, PI_TRANSCRIPT_FORMAT, readAll, START } from '@agentic-kit/run-log';
+/**
+ * The entry id an approval request is written under.
+ *
+ * Deterministic on the tool call, so a retried submit is the same entry and the
+ * store's own idempotency drops the duplicate instead of asking a human twice.
+ */
+export const approvalEntryId = (toolCallId) => `approval-${toolCallId}`;
+/**
+ * An `ApprovalChannel` whose request and answer are both records in the run's
+ * log.
+ */
+export function runLogApprovals(options) {
+    const { store, runId } = options;
+    const now = options.now ?? (() => new Date());
+    const prompt = options.prompt ?? defaultPrompt;
+    // Where reading resumed from last time: an approval may take hours, and
+    // re-reading the whole run per poll would grow with the transcript.
+    let cursor = START;
+    // Resolutions seen so far, kept across pages: an answer can land many pages
+    // after the request it answers.
+    const resolved = new Map();
+    const refresh = async () => {
+        const page = await store.read(runId, cursor, options.pageLimit);
+        if (page.records.length === 0)
+            return;
+        cursor = page.cursor;
+        for (const record of page.records) {
+            const outcome = resolutionOf(record);
+            if (outcome)
+                resolved.set(outcome.toolCallId, outcome.outcome);
+        }
+    };
+    const channelOptions = {
+        submit: async (request) => {
+            const parentId = await leafId(store, runId, options.pageLimit);
+            const entry = {
+                type: 'message',
+                id: approvalEntryId(request.toolCallId),
+                parentId,
+                timestamp: now().toISOString(),
+                message: approvalRequestMessage({
+                    toolCallId: request.toolCallId,
+                    prompt: prompt(request)
+                })
+            };
+            await store.append(runId, [entry]);
+        },
+        poll: async (request) => {
+            await refresh();
+            return resolved.get(request.toolCallId);
+        },
+        // One clock for both the entry timestamps and the timeout, so a suite that
+        // fakes time fakes all of it.
+        now: () => now().getTime(),
+        ...(options.intervalMs === undefined ? {} : { intervalMs: options.intervalMs }),
+        ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+        ...(options.onTimeout === undefined ? {} : { onTimeout: options.onTimeout }),
+        ...(options.sleep === undefined ? {} : { sleep: options.sleep })
+    };
+    return pollingApprovalChannel(channelOptions);
+}
+/**
+ * Answer a pending request by appending the resolution.
+ *
+ * The UI writes this through the API; a local run and the tests write it here.
+ * Either way it is one more entry in the same log, which is what makes "approve a
+ * cloud agent from a browser tab" nothing more than an insert.
+ */
+export async function resolveApproval(store, runId, input, clock = {}) {
+    const now = clock.now ?? (() => new Date());
+    const parentId = await leafId(store, runId);
+    const entry = {
+        type: 'message',
+        id: `resolution-${input.toolCallId}`,
+        parentId,
+        timestamp: now().toISOString(),
+        message: approvalResolutionMessage(input)
+    };
+    await store.append(runId, [entry]);
+}
+/**
+ * A record read as an approval answer, or `undefined` when it is anything else.
+ *
+ * The projectors surface a resolution only alongside the tool call it belongs
+ * to, and a Job polling for its own answer has not necessarily logged that call
+ * yet, so the answer is read straight off the record.
+ */
+function resolutionOf(record) {
+    // This gate answers a pi session, so a record another harness wrote is not
+    // its answer to read.
+    if (record.transcriptFormat !== PI_TRANSCRIPT_FORMAT)
+        return undefined;
+    const entry = assertPiSessionEntry(record.entry);
+    if (!isPiMessageEntry(entry))
+        return undefined;
+    const message = entry.message;
+    if (message.role !== 'custom' || message.customType !== APPROVAL_RESOLUTION_TYPE) {
+        return undefined;
+    }
+    const details = typeof message.details === 'object' && message.details !== null
+        ? message.details
+        : {};
+    const toolCallId = details.toolCallId;
+    if (typeof toolCallId !== 'string' || toolCallId.length === 0) {
+        throw new Error(`approval resolution at seq ${String(record.seq)} carries no toolCallId — the ` +
+            'gate cannot tell which tool call it answers');
+    }
+    const { reason, actorId } = details;
+    return {
+        toolCallId,
+        outcome: {
+            decision: details.decision === 'approved' ? 'allow' : 'deny',
+            ...(typeof reason === 'string' ? { reason } : {}),
+            ...(typeof actorId === 'string' ? { actorId } : {})
+        }
+    };
+}
+const defaultPrompt = ({ toolName, reason }) => reason ? `${toolName}: ${reason}` : `${toolName} needs approval`;
+/**
+ * The log's last entry id — the parent an out-of-band entry hangs from, so the
+ * rehydrated session file stays one tree rather than gaining a second root.
+ *
+ * Exported for the other writers of out-of-band entries (gate decisions), not
+ * for the package's consumers.
+ */
+export async function leafId(store, runId, pageLimit) {
+    const records = await readAll(store, runId, START, pageLimit);
+    for (let index = records.length - 1; index >= 0; index -= 1) {
+        const entry = records[index].entry;
+        if (typeof entry.id === 'string' && entry.id.length > 0)
+            return entry.id;
+    }
+    return null;
+}

package/esm/gate-decisions.d.ts

@@ -0,0 +1,27 @@
+import type { RunGateDecisionRecord } from '@agentic-kit/harness';
+import type { RunLogStore } from '@agentic-kit/run-log';
+export interface RunLogGateDecisionsOptions {
+    store: RunLogStore;
+    runId: string;
+    /** Records per read while looking up the parent entry. */
+    pageLimit?: number;
+}
+export interface RunLogGateDecisions {
+    /** Hand this to the gate as its `onDecision`. */
+    onDecision: (record: RunGateDecisionRecord) => void;
+    /**
+     * Wait for the queued writes and throw the first failure. A host calls this
+     * before it settles the run: a decision that never reached the log is a hole
+     * in the audit trail, not a detail.
+     */
+    flush(): Promise<void>;
+}
+/**
+ * The entry id a decision is written under.
+ *
+ * Deterministic on the tool call, so a retried execution that re-evaluates the
+ * same call writes the same entry and the store's idempotency drops the
+ * duplicate instead of logging the decision twice.
+ */
+export declare const gateDecisionEntryId: (toolCallId: string) => string;
+export declare function runLogGateDecisions(options: RunLogGateDecisionsOptions): RunLogGateDecisions;

package/esm/gate-decisions.js

@@ -0,0 +1,70 @@
+// Gate decisions into the run log.
+//
+// An `ask` verdict is already durable — the request and its answer are records
+// (see `approvals.ts`). A *policy* verdict is not: a rule that denies `bash`
+// blocks the call, tells the model why, and leaves no trace, so "which tool
+// calls did the gate block, and on whose authority" is unanswerable after the
+// run. The gate already offers every settled decision through `onDecision`; this
+// binds that callback to the log, which makes the transcript the audit trail for
+// refusals as well as for approvals.
+//
+// The callback is synchronous and an append is not, so writes are queued onto one
+// chain: ordering is preserved, the agent loop is never blocked on a log write,
+// and the first failure is re-thrown from `flush()` rather than vanishing into an
+// unhandled rejection.
+import { gateDecisionMessage } from '@agentic-kit/run-log';
+import { leafId } from './approvals';
+/**
+ * The entry id a decision is written under.
+ *
+ * Deterministic on the tool call, so a retried execution that re-evaluates the
+ * same call writes the same entry and the store's idempotency drops the
+ * duplicate instead of logging the decision twice.
+ */
+export const gateDecisionEntryId = (toolCallId) => `gate-${toolCallId}`;
+export function runLogGateDecisions(options) {
+    const { store, runId } = options;
+    let queue = Promise.resolve();
+    let failure;
+    const append = async (record) => {
+        const parentId = await leafId(store, runId, options.pageLimit);
+        const entry = {
+            type: 'message',
+            id: gateDecisionEntryId(record.toolCallId),
+            parentId,
+            timestamp: record.decidedAt,
+            message: gateDecisionMessage({
+                toolCallId: record.toolCallId,
+                toolName: record.toolName,
+                verdict: record.verdict.decision,
+                decision: record.decision,
+                ...(record.reason === undefined ? {} : { reason: record.reason }),
+                ...(record.actorId === undefined ? {} : { actorId: record.actorId }),
+                decidedAt: record.decidedAt
+            })
+        };
+        await store.append(runId, [entry]);
+    };
+    return {
+        onDecision: (record) => {
+            queue = queue.then(async () => {
+                try {
+                    await append(record);
+                }
+                catch (error) {
+                    // Keep the first failure: it is the one with the cause, and a later
+                    // write failing for the same reason would only bury it.
+                    failure ??= error;
+                }
+            });
+        },
+        flush: async () => {
+            await queue;
+            if (failure !== undefined) {
+                const error = failure;
+                failure = undefined;
+                throw error;
+            }
+        }
+    };
+}

package/esm/gate-host.d.ts

@@ -0,0 +1,32 @@
+import type { GateHost } from '@agentic-kit/harness';
+import type { RunLogApprovalsOptions } from './approvals';
+export interface RunLogGateRequest {
+    toolCallId: string;
+    title: string;
+    message: string;
+}
+export interface RunLogGateDecision {
+    toolCallId: string;
+    allowed: boolean;
+    reason?: string;
+    actorId?: string;
+}
+export interface RunLogGateHostOptions extends Omit<RunLogApprovalsOptions, 'prompt'> {
+    /** Told when a request is pending, so a host with a window can surface it. */
+    onRequested?: (request: RunLogGateRequest) => void;
+    /** Told what the log settled on, so a host can stop asking. */
+    onDecided?: (decision: RunLogGateDecision) => void;
+}
+export interface RunLogGateHost extends GateHost {
+    /**
+     * Wait for the queued writes and throw the first failure. Awaited once the
+     * turn ends: a decision that never reached the log is a hole in the audit
+     * trail, not a detail.
+     */
+    drain(): Promise<void>;
+}
+/** The text a human sees: the harness's title, then its message. */
+export declare const gatePrompt: (title: string, message: string) => string;
+/** Reason filed for a repeat of a declined call the gate skipped without asking. */
+export declare const SKIPPED_REASON = "skipped: a repeat of a tool call the user already declined";
+export declare function createRunLogGateHost(options: RunLogGateHostOptions): RunLogGateHost;

package/esm/gate-host.js

@@ -0,0 +1,91 @@
+// The harness's `GateHost`, with the run log as its UI.
+//
+// `createConfirmGate` asks a host to confirm a call and tells it when a repeat
+// of a declined call was skipped. Here both are records: the request goes into
+// the run's log as a `constructive.approval.request` entry, the answer is read
+// back as the `constructive.approval.resolution` a human wrote — from any
+// surface that projects the log — and the outcome is filed as a
+// `constructive.gate.decision`, the same audit entry a policy verdict leaves.
+// So a desktop run, a cloud Job and the agentic lane ask and are answered in the
+// one place, and nothing executes on the strength of a click: the decision is
+// what was persisted and read back.
+//
+// `notifyToolSkipped` returns void, so its write is queued and `drain()` —
+// awaited when the turn ends — rethrows the first failure rather than losing it.
+import { runLogApprovals } from './approvals';
+import { runLogGateDecisions } from './gate-decisions';
+/** The text a human sees: the harness's title, then its message. */
+export const gatePrompt = (title, message) => `${title}\n\n${message}`;
+/** Reason filed for a repeat of a declined call the gate skipped without asking. */
+export const SKIPPED_REASON = 'skipped: a repeat of a tool call the user already declined';
+export function createRunLogGateHost(options) {
+    const { onRequested, onDecided, ...channelOptions } = options;
+    const { store, runId } = options;
+    const now = options.now ?? (() => new Date());
+    // Prompts are composed per call and the channel writes one per request, so
+    // the title and message travel by tool call id rather than through the
+    // channel's request shape.
+    const prompts = new Map();
+    const channel = runLogApprovals({
+        ...channelOptions,
+        prompt: (request) => prompts.get(request.toolCallId) ?? request.toolName
+    });
+    const decisions = runLogGateDecisions({
+        store,
+        runId,
+        ...(options.pageLimit === undefined ? {} : { pageLimit: options.pageLimit })
+    });
+    return {
+        hasUI: true,
+        async confirmTool(toolCallId, title, message) {
+            prompts.set(toolCallId, gatePrompt(title, message));
+            onRequested?.({ toolCallId, title, message });
+            try {
+                const outcome = await channel.request({
+                    runId,
+                    toolCallId,
+                    toolName: title,
+                    input: {},
+                    reason: message,
+                    requestedAt: now().toISOString()
+                });
+                decisions.onDecision({
+                    runId,
+                    toolCallId,
+                    toolName: title,
+                    input: {},
+                    verdict: { decision: 'ask' },
+                    decision: outcome.decision,
+                    ...(outcome.reason === undefined ? {} : { reason: outcome.reason }),
+                    ...(outcome.actorId === undefined ? {} : { actorId: outcome.actorId }),
+                    decidedAt: now().toISOString()
+                });
+                onDecided?.({
+                    toolCallId,
+                    allowed: outcome.decision === 'allow',
+                    ...(outcome.reason === undefined ? {} : { reason: outcome.reason }),
+                    ...(outcome.actorId === undefined ? {} : { actorId: outcome.actorId })
+                });
+                return outcome.decision === 'allow';
+            }
+            finally {
+                prompts.delete(toolCallId);
+            }
+        },
+        notifyToolSkipped(toolCallId) {
+            // The harness names only the call, and the tool it repeats is in the
+            // transcript beside it; the projector attributes the entry by call id.
+            decisions.onDecision({
+                runId,
+                toolCallId,
+                toolName: '',
+                input: {},
+                verdict: { decision: 'deny', reason: SKIPPED_REASON },
+                decision: 'deny',
+                reason: SKIPPED_REASON,
+                decidedAt: now().toISOString()
+            });
+        },
+        drain: () => decisions.flush()
+    };
+}

package/esm/index.d.ts

@@ -0,0 +1,6 @@
+export type { RunLogApprovalsOptions } from './approvals';
+export { approvalEntryId, resolveApproval, runLogApprovals } from './approvals';
+export type { RunLogGateDecisions, RunLogGateDecisionsOptions } from './gate-decisions';
+export { gateDecisionEntryId, runLogGateDecisions } from './gate-decisions';
+export type { RunLogGateDecision, RunLogGateHost, RunLogGateHostOptions, RunLogGateRequest } from './gate-host';
+export { createRunLogGateHost, gatePrompt, SKIPPED_REASON } from './gate-host';

package/esm/index.js

@@ -0,0 +1,3 @@
+export { approvalEntryId, resolveApproval, runLogApprovals } from './approvals';
+export { gateDecisionEntryId, runLogGateDecisions } from './gate-decisions';
+export { createRunLogGateHost, gatePrompt, SKIPPED_REASON } from './gate-host';

package/gate-decisions.d.ts

@@ -0,0 +1,27 @@
+import type { RunGateDecisionRecord } from '@agentic-kit/harness';
+import type { RunLogStore } from '@agentic-kit/run-log';
+export interface RunLogGateDecisionsOptions {
+    store: RunLogStore;
+    runId: string;
+    /** Records per read while looking up the parent entry. */
+    pageLimit?: number;
+}
+export interface RunLogGateDecisions {
+    /** Hand this to the gate as its `onDecision`. */
+    onDecision: (record: RunGateDecisionRecord) => void;
+    /**
+     * Wait for the queued writes and throw the first failure. A host calls this
+     * before it settles the run: a decision that never reached the log is a hole
+     * in the audit trail, not a detail.
+     */
+    flush(): Promise<void>;
+}
+/**
+ * The entry id a decision is written under.
+ *
+ * Deterministic on the tool call, so a retried execution that re-evaluates the
+ * same call writes the same entry and the store's idempotency drops the
+ * duplicate instead of logging the decision twice.
+ */
+export declare const gateDecisionEntryId: (toolCallId: string) => string;
+export declare function runLogGateDecisions(options: RunLogGateDecisionsOptions): RunLogGateDecisions;

package/gate-decisions.js

@@ -0,0 +1,75 @@
+"use strict";
+// Gate decisions into the run log.
+//
+// An `ask` verdict is already durable — the request and its answer are records
+// (see `approvals.ts`). A *policy* verdict is not: a rule that denies `bash`
+// blocks the call, tells the model why, and leaves no trace, so "which tool
+// calls did the gate block, and on whose authority" is unanswerable after the
+// run. The gate already offers every settled decision through `onDecision`; this
+// binds that callback to the log, which makes the transcript the audit trail for
+// refusals as well as for approvals.
+//
+// The callback is synchronous and an append is not, so writes are queued onto one
+// chain: ordering is preserved, the agent loop is never blocked on a log write,
+// and the first failure is re-thrown from `flush()` rather than vanishing into an
+// unhandled rejection.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gateDecisionEntryId = void 0;
+exports.runLogGateDecisions = runLogGateDecisions;
+const run_log_1 = require("@agentic-kit/run-log");
+const approvals_1 = require("./approvals");
+/**
+ * The entry id a decision is written under.
+ *
+ * Deterministic on the tool call, so a retried execution that re-evaluates the
+ * same call writes the same entry and the store's idempotency drops the
+ * duplicate instead of logging the decision twice.
+ */
+const gateDecisionEntryId = (toolCallId) => `gate-${toolCallId}`;
+exports.gateDecisionEntryId = gateDecisionEntryId;
+function runLogGateDecisions(options) {
+    const { store, runId } = options;
+    let queue = Promise.resolve();
+    let failure;
+    const append = async (record) => {
+        const parentId = await (0, approvals_1.leafId)(store, runId, options.pageLimit);
+        const entry = {
+            type: 'message',
+            id: (0, exports.gateDecisionEntryId)(record.toolCallId),
+            parentId,
+            timestamp: record.decidedAt,
+            message: (0, run_log_1.gateDecisionMessage)({
+                toolCallId: record.toolCallId,
+                toolName: record.toolName,
+                verdict: record.verdict.decision,
+                decision: record.decision,
+                ...(record.reason === undefined ? {} : { reason: record.reason }),
+                ...(record.actorId === undefined ? {} : { actorId: record.actorId }),
+                decidedAt: record.decidedAt
+            })
+        };
+        await store.append(runId, [entry]);
+    };
+    return {
+        onDecision: (record) => {
+            queue = queue.then(async () => {
+                try {
+                    await append(record);
+                }
+                catch (error) {
+                    // Keep the first failure: it is the one with the cause, and a later
+                    // write failing for the same reason would only bury it.
+                    failure ??= error;
+                }
+            });
+        },
+        flush: async () => {
+            await queue;
+            if (failure !== undefined) {
+                const error = failure;
+                failure = undefined;
+                throw error;
+            }
+        }
+    };
+}

package/gate-host.d.ts

@@ -0,0 +1,32 @@
+import type { GateHost } from '@agentic-kit/harness';
+import type { RunLogApprovalsOptions } from './approvals';
+export interface RunLogGateRequest {
+    toolCallId: string;
+    title: string;
+    message: string;
+}
+export interface RunLogGateDecision {
+    toolCallId: string;
+    allowed: boolean;
+    reason?: string;
+    actorId?: string;
+}
+export interface RunLogGateHostOptions extends Omit<RunLogApprovalsOptions, 'prompt'> {
+    /** Told when a request is pending, so a host with a window can surface it. */
+    onRequested?: (request: RunLogGateRequest) => void;
+    /** Told what the log settled on, so a host can stop asking. */
+    onDecided?: (decision: RunLogGateDecision) => void;
+}
+export interface RunLogGateHost extends GateHost {
+    /**
+     * Wait for the queued writes and throw the first failure. Awaited once the
+     * turn ends: a decision that never reached the log is a hole in the audit
+     * trail, not a detail.
+     */
+    drain(): Promise<void>;
+}
+/** The text a human sees: the harness's title, then its message. */
+export declare const gatePrompt: (title: string, message: string) => string;
+/** Reason filed for a repeat of a declined call the gate skipped without asking. */
+export declare const SKIPPED_REASON = "skipped: a repeat of a tool call the user already declined";
+export declare function createRunLogGateHost(options: RunLogGateHostOptions): RunLogGateHost;

package/gate-host.js

@@ -0,0 +1,96 @@
+"use strict";
+// The harness's `GateHost`, with the run log as its UI.
+//
+// `createConfirmGate` asks a host to confirm a call and tells it when a repeat
+// of a declined call was skipped. Here both are records: the request goes into
+// the run's log as a `constructive.approval.request` entry, the answer is read
+// back as the `constructive.approval.resolution` a human wrote — from any
+// surface that projects the log — and the outcome is filed as a
+// `constructive.gate.decision`, the same audit entry a policy verdict leaves.
+// So a desktop run, a cloud Job and the agentic lane ask and are answered in the
+// one place, and nothing executes on the strength of a click: the decision is
+// what was persisted and read back.
+//
+// `notifyToolSkipped` returns void, so its write is queued and `drain()` —
+// awaited when the turn ends — rethrows the first failure rather than losing it.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKIPPED_REASON = exports.gatePrompt = void 0;
+exports.createRunLogGateHost = createRunLogGateHost;
+const approvals_1 = require("./approvals");
+const gate_decisions_1 = require("./gate-decisions");
+/** The text a human sees: the harness's title, then its message. */
+const gatePrompt = (title, message) => `${title}\n\n${message}`;
+exports.gatePrompt = gatePrompt;
+/** Reason filed for a repeat of a declined call the gate skipped without asking. */
+exports.SKIPPED_REASON = 'skipped: a repeat of a tool call the user already declined';
+function createRunLogGateHost(options) {
+    const { onRequested, onDecided, ...channelOptions } = options;
+    const { store, runId } = options;
+    const now = options.now ?? (() => new Date());
+    // Prompts are composed per call and the channel writes one per request, so
+    // the title and message travel by tool call id rather than through the
+    // channel's request shape.
+    const prompts = new Map();
+    const channel = (0, approvals_1.runLogApprovals)({
+        ...channelOptions,
+        prompt: (request) => prompts.get(request.toolCallId) ?? request.toolName
+    });
+    const decisions = (0, gate_decisions_1.runLogGateDecisions)({
+        store,
+        runId,
+        ...(options.pageLimit === undefined ? {} : { pageLimit: options.pageLimit })
+    });
+    return {
+        hasUI: true,
+        async confirmTool(toolCallId, title, message) {
+            prompts.set(toolCallId, (0, exports.gatePrompt)(title, message));
+            onRequested?.({ toolCallId, title, message });
+            try {
+                const outcome = await channel.request({
+                    runId,
+                    toolCallId,
+                    toolName: title,
+                    input: {},
+                    reason: message,
+                    requestedAt: now().toISOString()
+                });
+                decisions.onDecision({
+                    runId,
+                    toolCallId,
+                    toolName: title,
+                    input: {},
+                    verdict: { decision: 'ask' },
+                    decision: outcome.decision,
+                    ...(outcome.reason === undefined ? {} : { reason: outcome.reason }),
+                    ...(outcome.actorId === undefined ? {} : { actorId: outcome.actorId }),
+                    decidedAt: now().toISOString()
+                });
+                onDecided?.({
+                    toolCallId,
+                    allowed: outcome.decision === 'allow',
+                    ...(outcome.reason === undefined ? {} : { reason: outcome.reason }),
+                    ...(outcome.actorId === undefined ? {} : { actorId: outcome.actorId })
+                });
+                return outcome.decision === 'allow';
+            }
+            finally {
+                prompts.delete(toolCallId);
+            }
+        },
+        notifyToolSkipped(toolCallId) {
+            // The harness names only the call, and the tool it repeats is in the
+            // transcript beside it; the projector attributes the entry by call id.
+            decisions.onDecision({
+                runId,
+                toolCallId,
+                toolName: '',
+                input: {},
+                verdict: { decision: 'deny', reason: exports.SKIPPED_REASON },
+                decision: 'deny',
+                reason: exports.SKIPPED_REASON,
+                decidedAt: now().toISOString()
+            });
+        },
+        drain: () => decisions.flush()
+    };
+}

package/index.d.ts

@@ -0,0 +1,6 @@
+export type { RunLogApprovalsOptions } from './approvals';
+export { approvalEntryId, resolveApproval, runLogApprovals } from './approvals';
+export type { RunLogGateDecisions, RunLogGateDecisionsOptions } from './gate-decisions';
+export { gateDecisionEntryId, runLogGateDecisions } from './gate-decisions';
+export type { RunLogGateDecision, RunLogGateHost, RunLogGateHostOptions, RunLogGateRequest } from './gate-host';
+export { createRunLogGateHost, gatePrompt, SKIPPED_REASON } from './gate-host';

package/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKIPPED_REASON = exports.gatePrompt = exports.createRunLogGateHost = exports.runLogGateDecisions = exports.gateDecisionEntryId = exports.runLogApprovals = exports.resolveApproval = exports.approvalEntryId = void 0;
+var approvals_1 = require("./approvals");
+Object.defineProperty(exports, "approvalEntryId", { enumerable: true, get: function () { return approvals_1.approvalEntryId; } });
+Object.defineProperty(exports, "resolveApproval", { enumerable: true, get: function () { return approvals_1.resolveApproval; } });
+Object.defineProperty(exports, "runLogApprovals", { enumerable: true, get: function () { return approvals_1.runLogApprovals; } });
+var gate_decisions_1 = require("./gate-decisions");
+Object.defineProperty(exports, "gateDecisionEntryId", { enumerable: true, get: function () { return gate_decisions_1.gateDecisionEntryId; } });
+Object.defineProperty(exports, "runLogGateDecisions", { enumerable: true, get: function () { return gate_decisions_1.runLogGateDecisions; } });
+var gate_host_1 = require("./gate-host");
+Object.defineProperty(exports, "createRunLogGateHost", { enumerable: true, get: function () { return gate_host_1.createRunLogGateHost; } });
+Object.defineProperty(exports, "gatePrompt", { enumerable: true, get: function () { return gate_host_1.gatePrompt; } });
+Object.defineProperty(exports, "SKIPPED_REASON", { enumerable: true, get: function () { return gate_host_1.SKIPPED_REASON; } });

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@agentic-kit/run-log-gate",
+  "version": "0.2.0",
+  "author": "Constructive <developers@constructive.io>",
+  "description": "Tool approvals over the run log — the request, the human's answer and every settled gate decision are run-log entries, so desktop, cloud pi and agentic hosts ask and are answered on one surface",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "keywords": [
+    "agentic-kit",
+    "pi",
+    "coding-agent",
+    "run-log",
+    "approvals",
+    "constructive"
+  ],
+  "peerDependencies": {
+    "@agentic-kit/harness": "^0.15.0",
+    "@agentic-kit/run-log": "^0.6.0"
+  },
+  "gitHead": "2f450e5771ba241885e46cfe47bf7292d64203e7"
+}