agent-control-plane-core 0.8.2 → 0.9.1

package/types/conformance.d.mts

@@ -77,7 +77,8 @@ export function assertAliasedInputsCanonical(fixturesList: any[], assert: any):
  *      decision the contract requires every adapter to express.
  *   4. enforcement honesty: an enforceable deny (`rendered.enforced === true`)
  *      MUST carry a real block signal — a non-zero `exit_code` — not just a JSON
- *      body the agent is free to ignore. At least one enforced deny must appear,
+ *      body the agent is free to ignore — plus a non-empty reason on the
+ *      reason stream its {@link BLOCK_TRANSPORT} row names. At least one enforced deny must appear,
  *      so the honesty check is never vacuous.
  *   5. vetoability honesty, BOTH directions. When the parsed event's
  *      `this_call_vetoable` is false, EVERY render for that case must be

package/types/control-plane.d.mts

@@ -254,6 +254,40 @@ export function nativeResponse({ transport, exit_code, enforced, stdout, stderr,
     stdout?: unknown;
     stderr?: string;
 }): NativeResponse;
+/**
+ * The {@link BLOCK_TRANSPORT} row for `agent`. Throws for an agent with no row:
+ * a missing row would otherwise render an enforced block with no exit code.
+ * @param {string} agent
+ * @returns {Readonly<{ exit_code: number, reason_stream: "stderr", reason_required: boolean }>}
+ */
+export function blockTransportFor(agent: string): Readonly<{
+    exit_code: number;
+    reason_stream: "stderr";
+    reason_required: boolean;
+}>;
+/**
+ * `reason` when it holds visible text, else {@link DEFAULT_DENY_REASON}.
+ * @param {unknown} reason
+ * @returns {string}
+ */
+export function blockReason(reason: unknown): string;
+/**
+ * Build an adapter's {@link NativeResponse} from its {@link BLOCK_TRANSPORT}
+ * row. When `enforced`, the exit code is the row's and the reason (or the
+ * default) goes on the row's reason stream. Otherwise `unblocked_exit_code`
+ * stands and no reason stream is written: nothing was blocked, so the host
+ * reads the exit-0 (or ask) body instead.
+ * @param {string} agent
+ * @param {{ transport: string, enforced: boolean, unblocked_exit_code: number, stdout?: unknown, reason?: string }} parts
+ * @returns {NativeResponse}
+ */
+export function gatedResponse(agent: string, { transport, enforced, unblocked_exit_code, stdout, reason }: {
+    transport: string;
+    enforced: boolean;
+    unblocked_exit_code: number;
+    stdout?: unknown;
+    reason?: string;
+}): NativeResponse;
 /**
  * The vendor-neutral control-plane contract.
  *
@@ -440,7 +474,8 @@ export const CoverageStatus: Readonly<{
 /**
  * The result of rendering a {@link Verdict} for a specific agent's transport —
  * the ATTACH mechanism, not the decision. A caller applies whichever channels
- * are present: write `stdout`, exit with `exit_code`, or `throw`.
+ * are present: write `stdout`, write `stderr`, then exit with `exit_code`
+ * (`emit` in `agent-control-plane-core/runtime` does all three).
  * @typedef {object} NativeResponse
  * @property {"external_hook"|"in_process"|"observe_only"} transport
  * @property {number} exit_code process exit code carrying the decision (0 = proceed)
@@ -485,6 +520,22 @@ export const VERDICT_CONTENT_FIELDS: readonly string[];
  * ignores the key it was written into.
  */
 export const UNRENDERED_ON_UNKNOWN: ReadonlySet<string>;
+/**
+ * PROBLEM CLASS — an event marked vetoable on a path where the host can never
+ * veto it, so a deny reads downstream as a block that never happened.
+ *
+ * Each entry names a field (`path` into the {@link ToolCallEvent}) whose `value`
+ * makes `this_call_vetoable: true` a false claim. This is the ONE list:
+ * {@link makeEvent} refuses an event that breaks an entry, and the JSON-schema
+ * generator writes one `if`/`then` rule per entry, so the runtime and the
+ * published schema cannot hold different invariants.
+ * @type {ReadonlyArray<{ path: readonly string[], value: string, why: string }>}
+ */
+export const VETO_IMPOSSIBLE: ReadonlyArray<{
+    path: readonly string[];
+    value: string;
+    why: string;
+}>;
 /**
  * The optional {@link EventMeta} string fields a host may carry, and the SSOT
  * {@link baseMeta} reads off every native payload.
@@ -498,6 +549,33 @@ export const UNRENDERED_ON_UNKNOWN: ReadonlySet<string>;
  * no adapter carries an omission of its own.
  */
 export const STANDARD_META_FIELDS: readonly string[];
+/**
+ * The block reason a render writes when the judge gave none (or an empty one).
+ * Codex drops an enforced deny whose reason is empty and runs the tool, and on
+ * every host the model is refused with no rationale without one.
+ */
+export const DEFAULT_DENY_REASON: "blocked by monitor";
+/**
+ * PROBLEM CLASS — an enforced block whose reason never reaches the host, or
+ * whose exit code is not the one the host treats as a block, because each
+ * adapter hand-wired its own stderr and exit code.
+ *
+ * One row per agent, describing that host's ENFORCED block:
+ * - `exit_code`: the exit status the host treats as a block.
+ * - `reason_stream`: the stream the host reads the block reason from on that
+ *   exit. Every host here discards (or never gets) the stdout body on exit 2.
+ * - `reason_required`: the host drops a block whose reason is empty and runs
+ *   the tool, so every body field that carries the reason must be non-empty.
+ *
+ * {@link gatedResponse} derives each adapter's enforced render from its row,
+ * and the conformance harness holds every enforced render to the same row.
+ * @type {Readonly<Record<string, Readonly<{ exit_code: number, reason_stream: "stderr", reason_required: boolean }>>>}
+ */
+export const BLOCK_TRANSPORT: Readonly<Record<string, Readonly<{
+    exit_code: number;
+    reason_stream: "stderr";
+    reason_required: boolean;
+}>>>;
 /**
  * The translator for one agent's protocol. `parse` maps a native event to a
  * {@link ToolCallEvent} (never throwing on unmodelled input, stamping the
@@ -566,7 +644,8 @@ export type EventMeta = {
 /**
  * The result of rendering a {@link Verdict} for a specific agent's transport —
  * the ATTACH mechanism, not the decision. A caller applies whichever channels
- * are present: write `stdout`, exit with `exit_code`, or `throw`.
+ * are present: write `stdout`, write `stderr`, then exit with `exit_code`
+ * (`emit` in `agent-control-plane-core/runtime` does all three).
  */
 export type NativeResponse = {
     transport: "external_hook" | "in_process" | "observe_only";

package/types/index.d.mts

@@ -1,7 +1,7 @@
 export * from "./control-plane.mjs";
-export { codexAdapter } from "./adapters/codex.mjs";
 export { ampAdapter } from "./adapters/amp.mjs";
 export { claudeAdapter, HookEvent } from "./adapters/claude.mjs";
+export { codexAdapter, createCodexAdapter } from "./adapters/codex.mjs";
 export { geminiAdapter, GEMINI_TOOL_ALIASES, POST_TOOL_REDACTION_UNSUPPORTED } from "./adapters/gemini.mjs";
 export { ADAPTERS, AGENT_IDS, adapterFor, assertRegistryConsistent } from "./registry.mjs";
 export { runAdapterConformance, assertCoverageWellFormed, assertToolAliasesCovered, assertAliasedInputsCanonical } from "./conformance.mjs";

package/types/registry.d.mts

@@ -12,10 +12,15 @@ export function assertRegistryConsistent(adapters: Record<string, Adapter>): voi
  * selection signal that names no shipped adapter is a misconfiguration, not a
  * reason to silently fall back to a default agent (which would run the wrong
  * translator against the payloads and mis-render every verdict).
+ *
+ * `options` are the launcher's settings for that adapter (Codex:
+ * `{ version }`). Passing options to an adapter that takes none throws, so a
+ * setting the launcher believes it applied cannot be dropped in silence.
  * @param {string} id agent id (a {@link AGENT_IDS} member)
+ * @param {Record<string, unknown>} [options]
  * @returns {Adapter}
  */
-export function adapterFor(id: string): Adapter;
+export function adapterFor(id: string, options?: Record<string, unknown>): Adapter;
 /** @typedef {import("./control-plane.mjs").Adapter} Adapter */
 /**
  * Every shipped adapter. Adding an adapter to the package means adding it here —

package/types/runtime.d.mts

@@ -13,19 +13,22 @@ export function readStdin(): Promise<string>;
 export function demoJudge(event: import("./control-plane.mjs").ToolCallEvent): import("./control-plane.mjs").Verdict;
 /**
  * Run one host's parse→judge→render pipe over a raw stdin payload. If the payload
- * can't be parsed or the pipe throws, return `onFailure` — the host's OWN
+ * can't be parsed or the render throws, return `onFailure` — the host's OWN
  * fail-safe response — so a crashed hook degrades the way THAT host expects
  * (claude/codex fail OPEN = exit 0; amp fails to ASK = exit 1) instead of a
  * single shared default. This is the deliberate, necessary recovery the whole
  * per-host split exists for, not a blanket swallow.
  *
- * Before returning the fail-safe, the error is written to STDERR (never stdout,
- * which belongs to the host transport) so a regression that silently disables
- * enforcement leaves a greppable trace. Every host tolerates hook stderr:
- * claude/codex surface it only in verbose/debug on a 0 exit, amp forwards the
- * helper's stderr, and gemini reads stderr as a reason only on exit 2 — none of
- * these fail-safe exits is a 2 for a stdout-carrying transport, and amp's ask
- * (exit 1) shows the diagnostic alongside the prompt, which is the point.
+ * A judge that THROWS is not a malformed payload: the call parsed, and the judge
+ * failed to answer. That takes the same path as a judge that answers garbage —
+ * the clamp's `ask` (see below) — so a crashing guardrail puts the call in front
+ * of a human instead of taking an exit-0 fail-safe that runs it.
+ *
+ * Every error is written to STDERR (never stdout, which belongs to the host
+ * transport) so a regression that silently disables enforcement leaves a
+ * greppable trace. Every host tolerates hook stderr: claude/codex surface it
+ * only in verbose/debug on a 0 exit, amp forwards the helper's stderr, and
+ * gemini reads stderr as a reason only on exit 2.
  * `judge` is the seam a real deployment fills — {@link demoJudge} is a stand-in,
  * so the guardrail is supplied here rather than by forking this file. Whatever
  * it returns is treated as untrusted (see the clamp below).