@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/__test-utils__/approval-contract/hook-commands.js

@@ -0,0 +1,87 @@
+/**
+ * The contract's hooks as real commands, shared by every substrate so both
+ * engines run the very same hooks: each logs what it reads on stdin, then
+ * answers as its behaviour says, in its format (Claude Code's JSON, or
+ * Cursor's `permission`), grouped into the turn's sources one per plugin
+ * and format.
+ */
+import { create } from "@bufbuild/protobuf";
+import { HookGroupSchema, HookHandlerSchema } from "@stigmer/apis/ai/stigmer/agentic/plugin/v1/hooks_pb";
+/** One word of a bash command, quoted. */
+export function shellWord(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+/**
+ * The bash command a contract hook runs: log its stdin, then answer as `does`
+ * says, in the hook's format (Claude Code's JSON, or Cursor's `permission`).
+ * Shared with the Cursor substrate, so both engines run the very same hooks.
+ */
+export function contractHookCommand(does, files, format, rewriteInput) {
+    const log = `cat >> ${shellWord(files.runs)}; echo >> ${shellWord(files.runs)}; `;
+    const print = (json) => `printf '%s' ${shellWord(JSON.stringify(json))}`;
+    const decide = (permissionDecision, extra = {}) => format === "cursor"
+        ? print({
+            permission: permissionDecision,
+            ...(extra.reason ? { agent_message: extra.reason } : {}),
+            ...(extra.updatedInput ? { updated_input: extra.updatedInput } : {}),
+            ...(extra.additionalContext ? { additional_context: extra.additionalContext } : {}),
+        })
+        : print({
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision,
+                ...(extra.reason ? { permissionDecisionReason: extra.reason } : {}),
+                ...(extra.updatedInput ? { updatedInput: extra.updatedInput } : {}),
+                ...(extra.additionalContext ? { additionalContext: extra.additionalContext } : {}),
+            },
+        });
+    if ("hang" in does)
+        return `${log}sleep 30`;
+    if ("exit" in does)
+        return `${log}printf '%s' ${shellWord(does.stderr ?? "")} >&2; exit ${does.exit}`;
+    if ("invalidJson" in does)
+        return `${log}printf '%s' 'this is not json'`;
+    if ("postBlock" in does) {
+        return log + print({
+            decision: "block",
+            reason: does.postBlock,
+            ...(does.context ? { hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: does.context } } : {}),
+        });
+    }
+    if (does.answer === "ask-then-deny") {
+        return `${log}if [ -e ${shellWord(files.state)} ]; then ${decide("deny", { reason: "asked once already" })}; ` +
+            `else : > ${shellWord(files.state)}; ${decide("ask")}; fi`;
+    }
+    return log + decide(does.answer, {
+        ...(does.reason ? { reason: does.reason } : {}),
+        ...(does.rewrite ? { updatedInput: rewriteInput(does.rewrite) } : {}),
+        ...(does.context ? { additionalContext: does.context } : {}),
+    });
+}
+/** The contract's hooks as the turn's sources: one per plugin and format, in first-seen order. */
+export function contractHookSources(hooks, files, pluginRoot, rewriteInput) {
+    const bySource = new Map();
+    for (const hook of hooks) {
+        const plugin = hook.plugin ?? "safety";
+        const format = hook.format ?? "claude-code";
+        const key = `${plugin}\n${format}`;
+        const source = bySource.get(key) ?? { plugin, format, groups: [] };
+        source.groups.push(create(HookGroupSchema, {
+            event: hook.event,
+            matcher: hook.matcher,
+            handlers: [create(HookHandlerSchema, {
+                    command: contractHookCommand(hook.does, files, format, rewriteInput),
+                    timeoutSeconds: "hang" in hook.does ? 1 : 0,
+                    condition: hook.condition ?? "",
+                    failClosed: hook.failClosed ?? false,
+                })],
+        }));
+        bySource.set(key, source);
+    }
+    return [...bySource.values()].map(({ plugin, format, groups }) => ({
+        source: { plugin, root: pluginRoot, data: pluginRoot, options: new Map() },
+        format,
+        groups,
+    }));
+}
+//# sourceMappingURL=hook-commands.js.map

package/dist/__test-utils__/approval-contract/hook-commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-commands.js","sourceRoot":"","sources":["../../../src/__test-utils__/approval-contract/hook-commands.ts"],"names":[],"mappings":"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"}

package/dist/__test-utils__/approval-contract/types.d.ts

@@ -0,0 +1,326 @@
+/**
+ * The substrate-agnostic seam for the HITL gateway Contract Test Kit.
+ *
+ * Stigmer enforces tool approval through two real substrates with very different
+ * mechanics:
+ * - the in-process deep-agent gate (a LangGraph middleware that IS the side
+ *   effect), and
+ * - the out-of-process Cursor deny-oracle (a bash preToolUse hook that allows or
+ *   denies a tool the agent runs inside cursor-agent).
+ *
+ * The safety invariants they must uphold are identical, so the contract describes
+ * them once and runs them against anything that implements {@link GatewaySubstrate}.
+ * A future substrate (another runner, say) joins the safety net by
+ * implementing this one interface — it does not get to redefine the invariants.
+ *
+ * This seam intentionally does NOT carry raw, harness-specific tool names. The
+ * two substrates name the same operation differently (the Cursor hook says
+ * `Write`/`Shell`/`Delete`; the deep-agent stream says `edit`/`shell`/`delete`),
+ * so the contract speaks in the abstract {@link ProposedAction} and each adapter
+ * translates it into its own taxonomy. Keeping the contract taxonomy-free is what
+ * makes "both substrates agree on the same logical action" a meaningful assertion.
+ */
+/**
+ * A logical action a model proposes, expressed independently of any harness
+ * taxonomy. Each adapter maps it to its substrate's concrete tool name and args.
+ */
+export interface ProposedAction {
+    /**
+     * The action's approval-relevant kind. `write`/`shell`/`delete` are the gated
+     * mutating categories; `read` is any non-mutating built-in; `mcp` is an
+     * MCP-server tool.
+     */
+    readonly kind: "write" | "shell" | "delete" | "read" | "mcp";
+    /**
+     * The resource the action acts on — the absolute file path for file actions,
+     * the command string for shell. Empty for `mcp` (MCP identity is name-scoped).
+     * This is the "salient" value the exact-resource lease binds to.
+     */
+    readonly resource: string;
+    /**
+     * The edit content for a `write` action — the body whose digest the
+     * content-exact grant binds to. Two `write`s to the same `resource` with
+     * DIFFERENT `content` are distinct identities (the sibling-isolation probe);
+     * omitted, a substrate uses a fixed placeholder. Ignored for non-write kinds.
+     */
+    readonly content?: string;
+    /** MCP server slug — required for `kind: "mcp"`, ignored otherwise. */
+    readonly mcpServerSlug?: string;
+    /** MCP tool name — required for `kind: "mcp"`, ignored otherwise. */
+    readonly mcpToolName?: string;
+    /**
+     * For `kind: "mcp"`: the tool's server marks it destructive (its MCP
+     * annotation `destructiveHint: true`, read live each turn), so the
+     * approval default asks.
+     */
+    readonly mcpDestructive?: boolean;
+    /**
+     * For `kind: "read"`: `resource` is a path under the platform's own content
+     * (the `.stigmer/` route that carries the agent's skills, inputs and plan),
+     * which each adapter places where its engine mounts it.
+     */
+    readonly platformContent?: boolean;
+}
+/** An agent's (or sub-agent's) two tool lists, in Claude Code's names. */
+export interface ContractToolLists {
+    readonly tools: readonly string[];
+    readonly disallowedTools: readonly string[];
+}
+/** How a lists drive runs the action. */
+export interface ListsDriveOptions {
+    /** The pre-armed "trust this whole run": the approval gate is absent. */
+    readonly autoApproveAll?: boolean;
+    /**
+     * Run the action inside a sub-agent carrying these lists, narrowed from the
+     * agent's. Driven only where {@link SubstrateCapabilities.enforcesSubAgentLists}.
+     */
+    readonly subAgent?: ContractToolLists;
+}
+/** The outcome of a lists drive: a {@link GatewayOutcome} plus whether the lists refused the call. */
+export interface ListsOutcome extends GatewayOutcome {
+    /**
+     * The agent's lists refused the call: it did not run, the model read the
+     * out-of-scope message, and no approval was asked.
+     */
+    readonly refused: boolean;
+}
+/**
+ * The decision applied to a proposed action.
+ * - `none`   — no decision yet: run the action up to the gate and stop (the
+ *              "what happens with no backing authorization" probe).
+ * - `approve`— authorize THIS action.
+ * - `skip` / `reject` / `unknown` — every non-approving outcome; none may execute.
+ */
+export type GatewayDecision = "none" | "approve" | "skip" | "reject" | "unknown";
+/**
+ * The observable result of putting one proposed action through a substrate.
+ */
+export interface GatewayOutcome {
+    /**
+     * Whether the side effect ran (or, for an out-of-process substrate, whether
+     * the substrate ALLOWED it to run). This is the safety-critical observable and
+     * is comparable across substrates.
+     */
+    readonly executed: boolean;
+    /**
+     * Whether the substrate withheld the action pending approval. Note the precise
+     * meaning is substrate-specific (the in-process gate "paused at an interrupt";
+     * the deny-oracle "denied this call"), so it is only compared across substrates
+     * for `none`-decision probes, where both mean "withheld".
+     */
+    readonly gated: boolean;
+    /**
+     * Exact number of times the side effect ran. Populated only when
+     * {@link SubstrateCapabilities.observesExecution} is true (an in-process
+     * substrate can count; an out-of-process one cannot observe execution at all).
+     */
+    readonly executionCount?: number;
+    /**
+     * The authorization provenance the gate attached when it withheld the action —
+     * the PolicySource union string (e.g. "builtin_category", "agent_override").
+     * Populated only when {@link SubstrateCapabilities.surfacesGatePolicySource} is
+     * true; empty/undefined otherwise. Lets the contract assert every gated side
+     * effect is provenance-tagged.
+     */
+    readonly policySource?: string;
+}
+/**
+ * Capability flags for invariants that legitimately differ by substrate, gated
+ * rather than forked — mirroring the conformance suite's `CapabilityFlags`.
+ */
+export interface SubstrateCapabilities {
+    /**
+     * True when the runner executes the tool in-process and can therefore observe
+     * (and count) the side effect directly. The deep-agent gate is in-process
+     * (`true`); the Cursor hook authorizes a tool that runs in another process
+     * (`false`, receipts are best-effort).
+     */
+    readonly observesExecution: boolean;
+    /**
+     * True when an approval is bound to the exact resource it was granted for, so
+     * approving one resource never authorizes another. The Cursor grant token binds
+     * the resource (`true`); the deep-agent gate re-checks every distinct call and
+     * relies on checkpoint replay for sameness, so per-resource lease isolation is
+     * not a property of that gate (`false`).
+     */
+    readonly enforcesExactResource: boolean;
+    /**
+     * True when an approval is bound to the exact CONTENT of the action, not just
+     * its resource — so approving one edit to a file never authorizes a DIFFERENT
+     * edit to the SAME file. The Cursor grant binds (category, path, contentDigest)
+     * (`true`); the deep-agent gate relies on checkpoint replay for sameness, so
+     * content isolation is not a property of that gate (`false`).
+     */
+    readonly enforcesExactContent: boolean;
+    /**
+     * True when the substrate honors a run-lifetime CLASS lease: an APPROVE_ALL on
+     * one action auto-approves later actions of the SAME class (built-in category)
+     * for the rest of the run, while a DIFFERENT class stays gated. Both production
+     * substrates enforce this (the deep-agent gate clears leased categories; the
+     * Cursor hook reads `leasedCategories` from its state file), so both set `true`
+     * and implement {@link GatewaySubstrate.authorizeUnderClassLease}.
+     */
+    readonly appliesRunLifetimeLease: boolean;
+    /**
+     * True when the substrate attaches authorization provenance
+     * (approval_policy_source) at the gate, so a withheld action's
+     * {@link GatewayOutcome.policySource} is populated. The deep-agent gate decides
+     * and stamps the source at interrupt time (`true`); the Cursor substrate's
+     * provenance is a reconstruction-time projection over the persisted tool call,
+     * not a property of the hook's deny decision, so it is `false` here and is
+     * covered instead by the translator, boundary-rows and corpus suites.
+     */
+    readonly surfacesGatePolicySource: boolean;
+    /**
+     * True when the substrate runs an agent's hooks, in either format, at its
+     * gate; the contract's hooks section runs only there. Both engines do: the
+     * native gate in process, the Cursor gate through the runner's hook server.
+     */
+    readonly runsHooks: boolean;
+    /**
+     * True when a hook can tell a sub-agent's call from the main agent's (its
+     * stdin carries `agent_id` and `agent_type`). The native gate knows which
+     * sub-agent graph made a call (`true`); Cursor's hook payload carries no
+     * sub-agent identity (live probe, 2026-10-05), so the Cursor engine's
+     * hooks run on a sub-agent's calls without it (`false`).
+     */
+    readonly hookSeesSubAgent: boolean;
+    /**
+     * True when a sub-agent's own tool lists are enforced inside the sub-agent.
+     * The native engine narrows each sub-agent graph (`true`); the Cursor hook
+     * cannot tell which sub-agent is calling, so the Cursor engine refuses a
+     * turn whose sub-agent carries lists at setup instead (`false`, pinned by
+     * that harness's own tests).
+     */
+    readonly enforcesSubAgentLists: boolean;
+}
+/**
+ * A real enforcement substrate, wired to its production code. Adapters translate
+ * abstract actions/decisions into substrate-specific drives and report a uniform
+ * {@link GatewayOutcome}; they never reimplement enforcement logic.
+ */
+export interface GatewaySubstrate {
+    /** Stable substrate name, used in suite titles and diagnostics. */
+    readonly name: string;
+    /** Honest per-substrate capability flags. */
+    readonly capabilities: SubstrateCapabilities;
+    /**
+     * Whether this substrate can run in the current environment (e.g. the Cursor
+     * deny-oracle needs `bash`). The contract skips its suite when `false`.
+     */
+    readonly available: boolean;
+    /**
+     * Put a single proposed action through the substrate under a decision and
+     * report what happened.
+     */
+    authorize(action: ProposedAction, decision: GatewayDecision): Promise<GatewayOutcome>;
+    /**
+     * Approve `granted`, then probe `probe` against that standing authorization —
+     * the lease-isolation drive. Implemented only when
+     * {@link SubstrateCapabilities.enforcesExactResource} is true.
+     */
+    authorizeAfterGrant?(granted: ProposedAction, probe: ProposedAction): Promise<GatewayOutcome>;
+    /**
+     * Grant a run-lifetime CLASS lease by choosing APPROVE_ALL on `leased`, then
+     * probe `probe` against that standing lease — the scoped-lease drive that
+     * proves "approving all of class A never auto-approves class B." `leased` must
+     * be a gated built-in (write/shell/delete). Implemented only when
+     * {@link SubstrateCapabilities.appliesRunLifetimeLease} is true.
+     */
+    authorizeUnderClassLease?(leased: ProposedAction, probe: ProposedAction): Promise<GatewayOutcome>;
+    /**
+     * Put one action through an agent carrying `lists`, with no approval
+     * decision (`none`), and report whether the lists refused it, the default
+     * gated it, or it ran.
+     */
+    authorizeUnderLists(lists: ContractToolLists, action: ProposedAction, options?: ListsDriveOptions): Promise<ListsOutcome>;
+    /**
+     * Put one action through an agent carrying `hooks` and report what the
+     * hooks and the gate made of it. Implemented only when
+     * {@link SubstrateCapabilities.runsHooks} is true.
+     */
+    authorizeUnderHooks?(hooks: readonly ContractHook[], action: ProposedAction, options?: HooksDriveOptions): Promise<HooksOutcome>;
+}
+/** What a contract hook's command does when it runs. */
+export type ContractHookBehaviour = 
+/** Answer with Claude Code's JSON: a decision, its reason, a rewritten action, and context for the model. */
+{
+    readonly answer: "allow" | "deny" | "ask";
+    readonly reason?: string;
+    /** Rewrite the call into this action (`updatedInput`). */
+    readonly rewrite?: ProposedAction;
+    readonly context?: string;
+}
+/** Ask on its first run and deny on every later one: the resume probe. */
+ | {
+    readonly answer: "ask-then-deny";
+}
+/** Exit with this code, writing `stderr`. */
+ | {
+    readonly exit: number;
+    readonly stderr?: string;
+}
+/** Never answer: outlive the hook's timeout. */
+ | {
+    readonly hang: true;
+}
+/** A PostToolUse hook that blocks on the result with this reason, beside optional context. */
+ | {
+    readonly postBlock: string;
+    readonly context?: string;
+}
+/** Print something that is not JSON and exit 0. */
+ | {
+    readonly invalidJson: true;
+};
+/** One command hook, in Claude Code's format or Cursor's. */
+export interface ContractHook {
+    /** Claude Code's `PreToolUse`/`PostToolUse`, or one of Cursor's tool events. */
+    readonly event: "PreToolUse" | "PostToolUse" | "preToolUse" | "beforeShellExecution" | "beforeMCPExecution" | "postToolUse";
+    /** The matcher: Claude Code's (`Bash`, `mcp__srv__search_issues`) or Cursor's (`Shell`, `MCP:search_issues`, a command pattern). */
+    readonly matcher: string;
+    /** The handler's `if` (Claude Code's format only). */
+    readonly condition?: string;
+    readonly does: ContractHookBehaviour;
+    /** The plugin the hook comes from; `""` is the agent's own hooks block. Default `safety`. */
+    readonly plugin?: string;
+    /** The format the hook is written in; Claude Code's when absent. */
+    readonly format?: "claude-code" | "cursor";
+    /** Cursor's `failClosed`: a run that fails refuses the call. */
+    readonly failClosed?: boolean;
+}
+/** How a hooks drive runs the action. */
+export interface HooksDriveOptions {
+    /** The decision a card gets, if one shows; default `none`. */
+    readonly decision?: GatewayDecision;
+    /** The pre-armed "trust this whole run". */
+    readonly autoApproveAll?: boolean;
+    /** The unattended approval mode: an ask resolves as a skip. */
+    readonly unattended?: boolean;
+    /** A held hook lease: `plugin`'s asks on `action`'s tool count as its allow. */
+    readonly hookLease?: {
+        readonly plugin: string;
+        readonly action: ProposedAction;
+    };
+    /** A held category lease. */
+    readonly categoryLease?: "write" | "shell";
+    /** Make the call inside a sub-agent of this type. */
+    readonly subAgent?: string;
+    /** The agent's tool lists, ahead of the hooks. */
+    readonly lists?: ContractToolLists;
+    /** The tool itself fails when it runs. */
+    readonly failTool?: boolean;
+}
+/** The outcome of a hooks drive. */
+export interface HooksOutcome extends GatewayOutcome {
+    /** Who refused the call, if anyone: a hook's deny, or the agent's tool lists. */
+    readonly refusedBy: "hook" | "lists" | undefined;
+    /** The plugin a withheld call's card names; undefined when no hook asked. */
+    readonly policyHook?: string;
+    /** What the model read back for the call. */
+    readonly modelRead: string;
+    /** What each hook run read on stdin, in run order. */
+    readonly hookRuns: readonly Record<string, unknown>[];
+    /** The files a write created, by the action's resource. */
+    readonly writtenPaths: readonly string[];
+}

package/dist/__test-utils__/approval-contract/types.js

@@ -0,0 +1,24 @@
+/**
+ * The substrate-agnostic seam for the HITL gateway Contract Test Kit.
+ *
+ * Stigmer enforces tool approval through two real substrates with very different
+ * mechanics:
+ * - the in-process deep-agent gate (a LangGraph middleware that IS the side
+ *   effect), and
+ * - the out-of-process Cursor deny-oracle (a bash preToolUse hook that allows or
+ *   denies a tool the agent runs inside cursor-agent).
+ *
+ * The safety invariants they must uphold are identical, so the contract describes
+ * them once and runs them against anything that implements {@link GatewaySubstrate}.
+ * A future substrate (another runner, say) joins the safety net by
+ * implementing this one interface — it does not get to redefine the invariants.
+ *
+ * This seam intentionally does NOT carry raw, harness-specific tool names. The
+ * two substrates name the same operation differently (the Cursor hook says
+ * `Write`/`Shell`/`Delete`; the deep-agent stream says `edit`/`shell`/`delete`),
+ * so the contract speaks in the abstract {@link ProposedAction} and each adapter
+ * translates it into its own taxonomy. Keeping the contract taxonomy-free is what
+ * makes "both substrates agree on the same logical action" a meaningful assertion.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/__test-utils__/approval-contract/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/__test-utils__/approval-contract/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG"}

package/dist/__test-utils__/approval-log.d.ts

@@ -0,0 +1,34 @@
+import { type SessionEvent } from "@stigmer/apis/ai/stigmer/agentic/session/v1/event_pb";
+import { type ApprovalAsk } from "../harness/approval-answers.js";
+import type { AgentMessage, ToolCall } from "../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+import { ApprovalAction } from "../gen/turn/ai/stigmer/runner/turn/v1/enum_pb.js";
+/**
+ * The events the server appends when a person answers `row` of run `runId`
+ * with `action` (and, for a deny, `denyMessage`), in order.
+ */
+export declare function answerEventsFor(args: {
+    readonly sessionId: string;
+    readonly runId: string;
+}, row: ToolCall, action: ApprovalAction, denyMessage?: string): SessionEvent[];
+/**
+ * The `stigmer.permission.asked` the runner's emitter writes for a row that
+ * asks (`harness/events/emitter.ts` `writeToolUse`): its policy source word,
+ * its hook and its content digest, as the row carried them at the ask.
+ */
+export declare function askedEventFor(args: {
+    readonly sessionId: string;
+    readonly runId: string;
+}, row: ToolCall): SessionEvent;
+/**
+ * What the runtime's door reads for `messages` when every root WAITING row
+ * whose `approvalAction` is set was asked as the emitter writes it and
+ * answered with that action: the unit tests' shorthand for "a person
+ * answered these rows", stated once. The rows' `approvalAction` stands for
+ * the answer here only; the reader under test never sees it.
+ */
+export declare function loggedApprovalsFor(runId: string, messages: readonly AgentMessage[]): {
+    readonly runId: string;
+    readonly decisions: ReadonlyMap<string, ApprovalAction>;
+    readonly asks: ReadonlyMap<string, ApprovalAsk>;
+    readonly denyMessages: ReadonlyMap<string, string>;
+};

package/dist/__test-utils__/approval-log.js

@@ -0,0 +1,126 @@
+/**
+ * What the server writes when a person answers a call that asked, as both
+ * test kits model it (the harness-contract `ExecutionDriver.decide` and the
+ * hermetic `ExecutionRecord.decideWaitingToolCalls`): the answer's session
+ * events, as the server's answer core commits them.
+ *
+ *  - a `user.tool_confirmation` naming the call's tool use id
+ *    (`harness/events/ids.ts` `toolUseEventId`): `allow` for APPROVE and
+ *    APPROVE_ALL, `deny` for REJECT and SKIP (a person's skip and reject
+ *    are one deny; a reason, when given, is its `deny_message`);
+ *  - for APPROVE_ALL, a `stigmer.permission.grant` on that call after it,
+ *    naming the lease the server derives from the call.
+ *
+ * The kits write nothing on the row: the runtime reads the answers from the
+ * log and its seed copies each onto its row's `approval_action` (APPROVE_ALL,
+ * APPROVE, or REJECT for any deny, a SKIP included).
+ *
+ * The ids follow the server's rule for an answer (`sevt_` and a hash of the
+ * tool use id), so a resent answer names the same event.
+ *
+ * The runtime reads the answers back through its one door
+ * (`harness/approval-answers.ts`), so a kit's answer reaches a turn only
+ * through the log, as a person's does. Beside them, the ask the runner's
+ * emitter writes for a row ({@link askedEventFor}), and the unit tests'
+ * shorthand for a transcript a person answered ({@link loggedApprovalsFor}).
+ */
+import { createHash } from "node:crypto";
+import { create } from "@bufbuild/protobuf";
+import { SessionEventSchema } from "@stigmer/apis/ai/stigmer/agentic/session/v1/event_pb";
+import { approvalAnswersOf } from "../harness/approval-answers.js";
+import { POLICY_SOURCE_WORDS } from "../harness/events/emitter.js";
+import { permissionAskedEventId, toolUseEventId } from "../harness/events/ids.js";
+import { deriveLeaseScope } from "../shared/approval-policy.js";
+import { ApprovalAction, ToolCallStatus } from "../gen/turn/ai/stigmer/runner/turn/v1/enum_pb.js";
+function hashed(prefix, toolUseId) {
+    return `${prefix}${createHash("sha256").update(toolUseId).digest("hex").slice(0, 40)}`;
+}
+/**
+ * The events the server appends when a person answers `row` of run `runId`
+ * with `action` (and, for a deny, `denyMessage`), in order.
+ */
+export function answerEventsFor(args, row, action, denyMessage = "") {
+    const toolUseId = toolUseEventId(args.runId, row.id);
+    const allow = action === ApprovalAction.APPROVE || action === ApprovalAction.APPROVE_ALL;
+    const events = [
+        create(SessionEventSchema, {
+            sessionId: args.sessionId,
+            runId: args.runId,
+            event: {
+                case: "userToolConfirmation",
+                value: {
+                    id: hashed("sevt_tc_", toolUseId),
+                    result: allow ? "allow" : "deny",
+                    toolUseId,
+                    denyMessage: allow ? "" : denyMessage,
+                },
+            },
+        }),
+    ];
+    const lease = action === ApprovalAction.APPROVE_ALL ? deriveLeaseScope(row) : undefined;
+    if (lease !== undefined) {
+        events.push(create(SessionEventSchema, {
+            sessionId: args.sessionId,
+            runId: args.runId,
+            event: {
+                case: "stigmerPermissionGrant",
+                value: {
+                    id: hashed("sevt_pg_", toolUseId),
+                    toolUseId,
+                    scope: "turn",
+                    lease: lease.kind === "hook"
+                        ? { category: "", server: lease.server, hook: lease.hook, tool: lease.tool }
+                        : lease.kind === "server"
+                            ? { category: "", server: lease.server, tool: "" }
+                            : { category: lease.category, server: "", tool: "" },
+                },
+            },
+        }));
+    }
+    return events;
+}
+/**
+ * The `stigmer.permission.asked` the runner's emitter writes for a row that
+ * asks (`harness/events/emitter.ts` `writeToolUse`): its policy source word,
+ * its hook and its content digest, as the row carried them at the ask.
+ */
+export function askedEventFor(args, row) {
+    const toolUseId = toolUseEventId(args.runId, row.id);
+    return create(SessionEventSchema, {
+        sessionId: args.sessionId,
+        runId: args.runId,
+        event: {
+            case: "stigmerPermissionAsked",
+            value: {
+                id: permissionAskedEventId(toolUseId),
+                toolUseId,
+                message: row.approvalMessage,
+                argsPreview: row.argsPreview,
+                policySource: POLICY_SOURCE_WORDS[row.approvalPolicySource],
+                policyHook: row.approvalPolicyHook,
+                contentDigest: row.approvalContentDigest,
+            },
+        },
+    });
+}
+/**
+ * What the runtime's door reads for `messages` when every root WAITING row
+ * whose `approvalAction` is set was asked as the emitter writes it and
+ * answered with that action: the unit tests' shorthand for "a person
+ * answered these rows", stated once. The rows' `approvalAction` stands for
+ * the answer here only; the reader under test never sees it.
+ */
+export function loggedApprovalsFor(runId, messages) {
+    const ids = { sessionId: "ses_logged", runId };
+    const log = [];
+    for (const message of messages) {
+        for (const row of message.toolCalls) {
+            if (row.status !== ToolCallStatus.TOOL_CALL_WAITING_APPROVAL || row.approvalAction === ApprovalAction.UNSPECIFIED)
+                continue;
+            log.push(askedEventFor(ids, row), ...answerEventsFor(ids, row, row.approvalAction));
+        }
+    }
+    const answers = approvalAnswersOf(runId, { messages }, log);
+    return { runId, decisions: answers.decisions, asks: answers.asks, denyMessages: answers.denyMessages };
+}
+//# sourceMappingURL=approval-log.js.map

package/dist/__test-utils__/approval-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-log.js","sourceRoot":"","sources":["../../src/__test-utils__/approval-log.ts"],"names":[],"mappings":"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"}