approval-md 0.2.0 → 0.3.0

package/dist/src/codex/broker.d.ts

@@ -0,0 +1,229 @@
+/**
+ * The policy-bound Codex workspace change broker (APRV-325.2).
+ *
+ * APRV-325.1 shipped preparation, APRV-325.2.1 shipped the read-only planner,
+ * and this module is the thing both were for: the ONLY way a change reaches a
+ * canonical workspace in a constrained Codex session. It is deliberately not a
+ * mode of `src/mcp/server.ts`. That server publishes the whole agent verb
+ * catalog, including `run`, and a broker that lived inside it would be one
+ * unchecked flag away from the surface it exists to replace.
+ *
+ * ## What the caller may say, and what it may not
+ *
+ * A caller supplies exactly two things: a bounded list of typed operations, and
+ * the SHA-256 it believes the policy currently has. Everything else — the
+ * acting identity, the workspace root, the policy file, the log, the schema
+ * directory, the classes, the reversibility, the sandbox posture — comes from
+ * the installation manifest, which lives under a root-owned install root that
+ * no agent principal can write (`codex/manifest.ts`, `codex/trust.ts`).
+ * {@link parseBrokerInput} refuses an unknown key rather than ignoring it, so a
+ * caller that tries to name its own actor is told no instead of being quietly
+ * overridden, and {@link BROKER_TOOLS} is a POSITIVE allowlist of one: a name
+ * not on it is refused whether or not any surface advertised it.
+ *
+ * ## One action per class, never collapsed
+ *
+ * The planner returns one action leg per distinct path class, and this module
+ * registers, requests, starts and closes each of them separately. Collapsing
+ * four classes into one "workspace write" would lose exactly what the policy
+ * is for: the class is what the operator's roster, budget and autonomy are
+ * keyed to, and an action that reports a cheaper class than it performs is the
+ * self-reporting SPEC.md §11.1 invariant 4 forbids.
+ *
+ * ## The order, and why every step of it is load-bearing
+ *
+ * Read policy once and hash those exact bytes → check attestation against
+ * VERIFIED records → refuse if the caller's expected digest differs → plan →
+ * register the legs → authorize EVERY leg (policy, or a real grant token) →
+ * start EVERY leg → take custody → revalidate the plan UNDER custody → commit
+ * durably → read the workspace back → close every leg with what the reading
+ * said.
+ *
+ * Two of those orderings are the hard-won ones from the 2026-09-09 handover.
+ * **Every leg starts before any byte moves**, so a leg that refuses at start
+ * leaves a workspace that is untouched by construction rather than by cleanup;
+ * the already-started legs are closed `execution.failed` and the filesystem was
+ * never entered. And **revalidation happens under custody**, after the last
+ * start, because a revalidation that precedes the lock proves only what was
+ * true before another writer could act.
+ *
+ * ## Outcomes are read, not remembered
+ *
+ * `codex/workspace-commit.ts` classifies the workspace by reading it back
+ * against the journal. All-after closes every leg `execution.completed`;
+ * all-before closes every leg `execution.failed`; anything else — a partial
+ * apply, a failed rollback, an endpoint that could not be read — closes every
+ * leg `execution.indeterminate` with reason `workspace-commit-unknown`, the
+ * reason this task added to SPEC.md §8's closed set. Nothing here converts an
+ * indeterminate outcome into either of the others; that stays human-owned
+ * (`approval execution reconcile`).
+ */
+import type { ClockOptions } from "../core/clock.js";
+import type { AppendOptions } from "../core/log.js";
+import type { CodexInstanceManifest } from "./manifest.js";
+import { type CustodyReport, type WorkspaceState } from "./workspace-commit.js";
+export declare const BROKER_VERSION: "approval.codex.broker.v1";
+/**
+ * The positive server-side tool allowlist: one name, and nothing is reachable
+ * by any other.
+ *
+ * A deny list would have to name every verb the runtime grows next; this names
+ * the one a constrained Codex session may call, so anything added tomorrow is
+ * unreachable here until somebody decides otherwise. Fail closed, SPEC.md §11.
+ */
+export declare const BROKER_TOOLS: ReadonlySet<string>;
+/** The indeterminate reason a mixed or unreadable commit records (SPEC.md §8). */
+export declare const WORKSPACE_COMMIT_UNKNOWN: "workspace-commit-unknown";
+/**
+ * Everything the broker is, derived from the manifest and from nothing a caller
+ * said. Constructed by {@link brokerInstallation}; there is no other maker.
+ */
+export interface BrokerInstallation {
+    instanceId: string;
+    /** `agent:codex-<instance_id>`, fixed by the installation. */
+    actor: string;
+    /** The canonical workspace root, absolute and normalized. */
+    root: string;
+    policyPath: string;
+    logPath: string;
+}
+/** Derive the fixed context from a validated instance manifest. */
+export declare function brokerInstallation(manifest: CodexInstanceManifest): BrokerInstallation;
+/** The whole of what a caller may say. */
+export interface BrokerInput {
+    operations: unknown;
+    expected_policy_sha256: string;
+}
+export type BrokerInputResult = {
+    ok: true;
+    input: BrokerInput;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Accept `{operations, expected_policy_sha256}` and refuse everything else.
+ *
+ * An unknown key is a refusal rather than a silent drop for the reason the MCP
+ * server refuses `--as`: a caller that named an actor, a root, a class or a
+ * token meant something by it, and the something they meant is not available
+ * here. Being told so is the only way they learn that.
+ */
+export declare function parseBrokerInput(value: unknown): BrokerInputResult;
+/**
+ * Every way the broker can say no. Frozen public API in the sense SPEC.md
+ * §11.1 invariant 6 means: each fires for exactly one condition, they are
+ * distinct from one another, and `tests/codex-broker.test.ts` pins the union.
+ */
+export declare const BROKER_REFUSAL_CODES: readonly [
+/** The tool name is not on {@link BROKER_TOOLS}. */
+"tool-not-allowed", 
+/** The caller's object is not `{operations, expected_policy_sha256}`. */
+"input-invalid", 
+/** The workspace root is not an absolute normalized path. */
+"installation-invalid", 
+/** The log could not be read, is torn, or does not verify. */
+"log-unavailable", 
+/** The policy file could not be read or parsed. */
+"policy-unavailable", 
+/** The live policy bytes are not the attested ones. */
+"policy-not-attested", 
+/** The caller's expected digest is not the live attested digest. */
+"attestation-drift", 
+/** An endpoint names the broker's own reserved transaction paths. */
+"reserved-path", 
+/** A replace whose after-image equals its preimage: nothing to approve. */
+"no-op-operation", 
+/** The planner refused. `detail` carries its own code verbatim. */
+"plan-refused", 
+/** The log already declares this task or key under different bytes. */
+"replay", 
+/** Registration refused for any other gate reason. */
+"register-refused", 
+/** Intake refused for any gate reason. */
+"request-refused", 
+/** A leg needs a human's grant and no token for it was presented. */
+"approval-required", 
+/** A leg's `execution.started` refused. Nothing was written to the workspace. */
+"start-refused", 
+/** Another transaction holds the workspace lock. */
+"custody-contended", 
+/** The lock or staging directory could not be created. */
+"custody-unavailable", 
+/** The installation requires OS-exclusive custody and the host cannot prove it. */
+"custody-insufficient", 
+/** The plan no longer validates against the workspace under custody. */
+"workspace-drift", 
+/** Staging failed; the workspace is untouched by construction. */
+"stage-failed", 
+/** The commit was attempted and did not take. Every leg is `execution.failed`. */
+"commit-not-applied", 
+/** The commit was attempted and nobody knows. Every leg is indeterminate. */
+"commit-unknown"];
+export type BrokerRefusalCode = (typeof BROKER_REFUSAL_CODES)[number];
+export interface BrokerRefusal {
+    ok: false;
+    code: BrokerRefusalCode;
+    message: string;
+    /** The underlying layer's own code, when this refusal wraps one. */
+    detail?: string;
+    /** The action keys a human must decide, when `code` is `approval-required`. */
+    pending?: readonly string[];
+    /** Present once a commit was attempted: what reading the workspace proved. */
+    state?: WorkspaceState;
+}
+export interface BrokerOptions extends ClockOptions {
+    /**
+     * Grant tokens, keyed by CLASS, for the legs whose policy resolves manual.
+     *
+     * Keyed by class rather than by action key because the class is the thing a
+     * human decided about and the key is derived; a caller cannot use this map to
+     * reach a leg it did not register, because every key is recomputed here.
+     */
+    tokens?: Readonly<Record<string, string>>;
+    /**
+     * Refuse unless the host proves OS-exclusive write custody (APRV-325.3 sets
+     * it). Absent, the broker still REPORTS which custody it got: the claim never
+     * silently softens, only the refusal is optional.
+     */
+    requireExclusiveCustody?: boolean;
+    schemaDir?: string;
+    append?: AppendOptions;
+    /** Forwarded verbatim to the commit's test seam. See `CommitOptions.onStep`. */
+    onStep?: (step: number) => void;
+    /** Test seam: called once after the last start and before custody is taken. */
+    afterStart?: () => void;
+}
+/** One class's leg through the gate. */
+export interface BrokerLeg {
+    class: string;
+    actionKey: string;
+    /** How it was authorized: `policy` (no token exists) or `token` (a real grant). */
+    mode: "policy" | "token";
+}
+export interface BrokerSuccess {
+    ok: true;
+    version: typeof BROKER_VERSION;
+    task: string;
+    payload_hash: string;
+    policy_sha256: string;
+    legs: readonly BrokerLeg[];
+    custody: CustodyReport;
+    /** Always `"after"`: a success is a workspace that was read back as applied. */
+    state: "after";
+}
+export type BrokerResult = BrokerSuccess | BrokerRefusal;
+/** The task id one proposal's bytes always produce. Deterministic, so a replay collides. */
+export declare function brokerTaskId(instanceId: string, payloadHash: string): string;
+/** The action key one class's leg always produces under that task. */
+export declare function brokerActionKey(task: string, cls: string): string;
+/**
+ * Apply one bounded typed proposal to the canonical workspace, or say exactly
+ * why not.
+ *
+ * `tool` is checked against {@link BROKER_TOOLS} first, before the input is
+ * even parsed: a surface that published nothing still refuses a name it does
+ * not serve, which is the defence in depth `src/mcp/server.ts` keeps for
+ * `mcp-guest-restricted`.
+ */
+export declare function applyWorkspaceChange(tool: string, installation: BrokerInstallation, rawInput: unknown, options?: BrokerOptions): BrokerResult;