agent-control-plane-core 0.6.4 → 0.8.0

package/types/control-plane.d.mts

@@ -136,6 +136,7 @@ export function readonlySet(values: Iterable<string>): ReadonlySet<string>;
  * @property {(native: any) => ToolCallEvent} parse
  * @property {(verdict: Verdict, event: ToolCallEvent, options?: { soleGate?: boolean }) => NativeResponse} render
  * @property {Record<string, string|undefined>} [NATIVE_EVENT_FOR] the native event name this host uses for each {@link EventKind}, for a conformance probe of a kind no fixture produced. Optional: a kind absent here (`unknown` always, plus any kind this transport does not carry) is probed with a marker name, which takes the adapter's unrecognized-event branch. Never read at runtime — `parse` stamps the real name on `meta.native_event`.
+ * @property {boolean} NATIVE_ASK_TIER whether this host's transport carries a DISTINCT "ask the human" tier that the host honours. `true` ⇒ a rendered `ask` suspends the call in front of a person (Claude Code's `permissionDecision: "ask"`, Amp's exit 1). `false` ⇒ the host has no such tier, so `render` collapses `ask` onto another signal (Gemini CLI writes its advisory `decision: "deny"`) and an un-escalated ask lets the tool run. A consumer that must not let an ask through reads this to decide where to escalate `ask` to `deny`, instead of keeping its own hand-typed list of agent ids. It is about the HOST, not the verdict: `ask` never renders as `enforced` on any adapter, and the tier it names is the PRE-TOOL gate — once a tool has run there is nothing left to suspend, so every host renders a post-tool `ask` as its block. The conformance harness probes the real `render` against it — a `true` whose ask renders as the host's abstaining allow fails, and so does a `false` whose ask differs from its own advisory deny.
  * @property {Record<string, ReadonlySet<string>|undefined>} UNRENDERED_FIELDS per-event-kind set of {@link VERDICT_CONTENT_FIELDS} this host has no native channel for, so `render` drops them. EVERY {@link EventKind} carries a row, including one this adapter's `parse` cannot emit — an omission would otherwise read as "every content field reaches a channel here", the reverse of the truth on a transport that carries none. The value type still admits `undefined` so a consumer handles a lookup miss rather than indexing straight into `.has(...)`; the conformance harness refuses a missing row. SCOPE — a row describes the ALLOW path only. An enforceable deny may drop more: Gemini's exit-2 System Block returns no stdout at all, so a deny there carries no `additional_context` whatever the row says. Do not read this map to infer what a deny delivers. The conformance harness fails an adapter whose renders disagree with its declaration either way, so a stale entry cannot survive.
  */
 /**
@@ -278,9 +279,11 @@ export function nativeResponse({ transport, exit_code, enforced, stdout, stderr,
  * Dependency-free on purpose, so a fail-closed hook can import it without
  * dragging in eager config-file reads.
  *
- * VERSIONING — this module IS the frozen contract (its own SSOT, no parallel
- * schema file to drift). Adapters and guardrail consumers are built against it
- * in parallel, so its shapes are stable: {@link EventKind}, {@link Decision},
+ * VERSIONING — this module IS the frozen contract and its own SSOT. The JSON
+ * Schema documents under `schema/` are GENERATED from it by `pnpm gen:schema`
+ * and byte-compared in `json-schema.test.mjs`, so they are output rather than a
+ * second contract; never hand-edit one. Adapters and guardrail consumers are
+ * built against this module in parallel, so its shapes are stable: {@link EventKind}, {@link Decision},
  * {@link MODELED_TOOLS}, and {@link TOOL_ALIASES} are frozen, and
  * {@link SCHEMA_VERSION} / {@link CONTROL_PLANE_SCHEMA} are pinned
  * (control-plane.test.mjs asserts the exact values, so any shape change is a
@@ -293,9 +296,10 @@ export function nativeResponse({ transport, exit_code, enforced, stdout, stderr,
  * {@link Adapter} interface an integrator implements. A new REQUIRED adapter
  * member breaks every third-party adapter while every event on the wire stays
  * byte-identical, so it is a package-semver break and leaves
- * {@link CONTROL_PLANE_SCHEMA} alone. `UNRENDERED_FIELDS` is one: adding it is
- * a one-line change per adapter, and the conformance harness names the member
- * and the migration rather than throwing from inside itself.
+ * {@link CONTROL_PLANE_SCHEMA} alone. `UNRENDERED_FIELDS` is one and
+ * `NATIVE_ASK_TIER` is the second: adding either is a one-line change per
+ * adapter, and the conformance harness names the member and the migration
+ * rather than throwing from inside itself.
  */
 /** Wire identifier for this schema version; bump on a breaking shape change. */
 export const CONTROL_PLANE_SCHEMA: "control-plane/v1";
@@ -515,6 +519,10 @@ export type Adapter = {
      * the native event name this host uses for each {@link EventKind}, for a conformance probe of a kind no fixture produced. Optional: a kind absent here (`unknown` always, plus any kind this transport does not carry) is probed with a marker name, which takes the adapter's unrecognized-event branch. Never read at runtime — `parse` stamps the real name on `meta.native_event`.
      */
     NATIVE_EVENT_FOR?: Record<string, string | undefined> | undefined;
+    /**
+     * whether this host's transport carries a DISTINCT "ask the human" tier that the host honours. `true` ⇒ a rendered `ask` suspends the call in front of a person (Claude Code's `permissionDecision: "ask"`, Amp's exit 1). `false` ⇒ the host has no such tier, so `render` collapses `ask` onto another signal (Gemini CLI writes its advisory `decision: "deny"`) and an un-escalated ask lets the tool run. A consumer that must not let an ask through reads this to decide where to escalate `ask` to `deny`, instead of keeping its own hand-typed list of agent ids. It is about the HOST, not the verdict: `ask` never renders as `enforced` on any adapter, and the tier it names is the PRE-TOOL gate — once a tool has run there is nothing left to suspend, so every host renders a post-tool `ask` as its block. The conformance harness probes the real `render` against it — a `true` whose ask renders as the host's abstaining allow fails, and so does a `false` whose ask differs from its own advisory deny.
+     */
+    NATIVE_ASK_TIER: boolean;
     /**
      * per-event-kind set of {@link VERDICT_CONTENT_FIELDS} this host has no native channel for, so `render` drops them. EVERY {@link EventKind} carries a row, including one this adapter's `parse` cannot emit — an omission would otherwise read as "every content field reaches a channel here", the reverse of the truth on a transport that carries none. The value type still admits `undefined` so a consumer handles a lookup miss rather than indexing straight into `.has(...)`; the conformance harness refuses a missing row. SCOPE — a row describes the ALLOW path only. An enforceable deny may drop more: Gemini's exit-2 System Block returns no stdout at all, so a deny there carries no `additional_context` whatever the row says. Do not read this map to infer what a deny delivers. The conformance harness fails an adapter whose renders disagree with its declaration either way, so a stale entry cannot survive.
      */

package/types/json-schema.d.mts

@@ -0,0 +1,77 @@
+/**
+ * Assert every content field the contract models has a schema above. Throws
+ * (fail loud) on the first that does not: `additionalProperties: false` makes an
+ * undeclared field a REJECTION rather than an omission, so a consumer would
+ * refuse a verdict this library produces. Called at import against the live
+ * {@link VERDICT_CONTENT_FIELDS}; exported so a test can drive both branches.
+ * @param {readonly string[]} fields
+ * @param {Record<string, unknown>} declared
+ */
+export function assertVerdictFieldsDeclared(fields: readonly string[], declared: Record<string, unknown>): void;
+/**
+ * The document describing a normalized {@link ToolCallEvent}.
+ *
+ * `additionalProperties: false` is honest here rather than strict: `makeEvent`
+ * builds every event, and the unmodelled remainder of a native payload lands in
+ * `meta.passthrough`, so an extra key at the root is a hand-rolled event, not a
+ * newer library's.
+ * @returns {Record<string, unknown>}
+ */
+export function toolCallEventSchema(): Record<string, unknown>;
+/**
+ * The document describing a normalized {@link Verdict}. Only `decision` is
+ * required; `normalizeVerdict` emits the optional fields only when present.
+ * @returns {Record<string, unknown>}
+ */
+export function verdictSchema(): Record<string, unknown>;
+/**
+ * Every generated file, keyed by its package-relative path — the SSOT the
+ * generator writes and the freshness test reads, so neither carries its own
+ * list of filenames. The two `.schema.json` entries are JSON Schema documents;
+ * `tool-input-keys.json` is the data map {@link TOOL_INPUT_KEYS_FILE} describes.
+ * @returns {Record<string, Record<string, unknown>>}
+ */
+export function jsonSchemaDocuments(): Record<string, Record<string, unknown>>;
+/**
+ * The bytes a generated file is written as: 2-space JSON with a trailing newline.
+ * This is NOT Prettier's rendering — Prettier collapses a short array onto one
+ * line — so `schema/` is in `.prettierignore` and this function owns the bytes
+ * the freshness test compares. A formatter allowed to rewrite them would red
+ * that test on a change to nothing.
+ * @param {Record<string, unknown>} document
+ * @returns {string}
+ */
+export function serializeSchema(document: Record<string, unknown>): string;
+/**
+ * Package-relative directory the generated files live in, versioned by the WIRE
+ * version. A breaking shape change bumps {@link CONTROL_PLANE_SCHEMA} and so
+ * writes a new directory, leaving the previous one in place for a consumer
+ * still on it.
+ *
+ * A document is THIS RELEASE's rendering of that wire version, not a statement
+ * about every release that will carry it. Adding an optional field is
+ * backward-compatible and stays at v1 (see the README's Versioning section), so
+ * the next release's document may carry a property this one does not. That is
+ * why the files ship inside the package: a consumer reads the schema from the
+ * same installed version that produced the event, and the two move together.
+ * Validate against the installed file, never a copy pinned by hand.
+ *
+ * Neither document carries an `$id`. A URL naming a mutable branch would resolve
+ * to whatever the contract says LATER, and two installed versions declaring one
+ * `$id` collide inside a single validator instance. `$ref` here is
+ * document-relative, so nothing needs one.
+ */
+export const SCHEMA_DIR: "schema/control-plane/v1";
+/** Basename of each generated document, keyed by the shape it describes. */
+export const SCHEMA_FILES: Readonly<{
+    ToolCallEvent: "tool-call-event.schema.json";
+    Verdict: "verdict.schema.json";
+}>;
+/**
+ * Basename of the per-tool input-key map, published as plain DATA rather than
+ * inside the event document. A vendor keyword there (`x-modeled-tool-input-keys`)
+ * is legal JSON Schema, but ajv refuses an unknown keyword under its default
+ * options, so the document a JavaScript consumer installed would not compile
+ * until that consumer registered a vocabulary it has no reason to know about.
+ */
+export const TOOL_INPUT_KEYS_FILE: "tool-input-keys.json";

package/types/runtime.d.mts

@@ -0,0 +1,79 @@
+/**
+ * Read all of stdin to a string.
+ * @returns {Promise<string>}
+ */
+export function readStdin(): Promise<string>;
+/**
+ * The DEMO policy standing in for a real guardrail judge: deny any command
+ * matching /rm -rf/, allow everything else. A real deployment swaps this for its
+ * own judge over the normalized {@link ToolCallEvent}.
+ * @param {import("./control-plane.mjs").ToolCallEvent} event
+ * @returns {import("./control-plane.mjs").Verdict}
+ */
+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
+ * 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.
+ * `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).
+ * @param {import("./control-plane.mjs").Adapter} adapter
+ * @param {string} rawInput
+ * @param {import("./control-plane.mjs").NativeResponse} onFailure
+ * @param {(event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict} [judge]
+ * @returns {import("./control-plane.mjs").NativeResponse}
+ */
+export function renderHookResponse(adapter: import("./control-plane.mjs").Adapter, rawInput: string, onFailure: import("./control-plane.mjs").NativeResponse, judge?: (event: import("./control-plane.mjs").ToolCallEvent) => import("./control-plane.mjs").Verdict): import("./control-plane.mjs").NativeResponse;
+/**
+ * Whether a failed `writeSync` is the one recoverable case: EAGAIN, meaning the
+ * non-blocking pipe is momentarily full because the host has not drained it
+ * yet. The caller sleeps 1ms and retries — the same wait a blocking write would
+ * have done in the kernel. Every other errno (EPIPE, EBADF, ...) propagates.
+ *
+ * A non-Error throw is NOT retryable, and is checked separately rather than
+ * left to the `code` comparison: a plain object carrying `code: "EAGAIN"` is
+ * not a write that the kernel asked us to repeat, and retrying one forever is a
+ * hang rather than a short write. Exported so a test can drive every branch —
+ * the real `writeSync` only ever throws an Error.
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isRetryableWriteError(err: unknown): boolean;
+/**
+ * Write `text` to `fd` IN FULL, looping until every byte lands.
+ *
+ * A single `writeSync` is not enough. When the host captures the hook, fd 1/2 is
+ * a pipe, and libuv puts that pipe in NON-BLOCKING mode the moment anything
+ * initializes `process.stdout`/`process.stderr` (a `console.log` in a judge, the
+ * fail-safe stderr diagnostic in {@link renderHookResponse}). A non-blocking
+ * `write(2)` returns a SHORT COUNT once the kernel pipe buffer fills — measured
+ * at ~143 KiB here — so a deny body larger than that (a long `reason`, a big
+ * `mutated_input`) was silently truncated and the process still exited 0/2 with
+ * a half-written JSON the host cannot parse: an enforced deny degrading to a
+ * run. Looping restores the blocking-write semantics the caller assumes.
+ *
+ * Exported so a test can drive the propagation path against a real closed
+ * descriptor; {@link emit} is the only caller a consumer needs.
+ * @param {number} fd
+ * @param {string} text
+ */
+export function writeAllSync(fd: number, text: string): void;
+/**
+ * Emit a {@link NativeResponse} to the host: write the native stdout body when
+ * the transport has one, then exit with the transport's exit code.
+ * @param {import("./control-plane.mjs").NativeResponse} response
+ * @returns {never}
+ */
+export function emit(response: import("./control-plane.mjs").NativeResponse): never;