approval-md 0.0.1 → 0.2.0

package/dist/src/core/loop.d.ts

@@ -0,0 +1,274 @@
+/**
+ * Loop safety (SPEC.md §10.2): "three consecutive `execution.failed` events for
+ * one task escalate to `manual` regardless of policy".
+ *
+ * This is a **pure projection over the log** and nothing else. It reads records,
+ * counts, and returns; it never appends, never reads the clock, and never
+ * consults the policy. Two very different consumers need the same answer and
+ * must not be allowed to disagree about it:
+ *
+ * - `core/gate.ts` refuses to admit a *new* non-manual request for an escalated
+ *   task (the `loop-escalated` refusal);
+ * - `core/execute.ts` refuses to *start* a supervised/autonomous execution for
+ *   one, directing the caller to the manual path.
+ *
+ * It lives in its own module rather than inside `core/execute.ts` for a boring
+ * structural reason: `execute.ts` imports the gate, so the gate cannot import
+ * `execute.ts` back without a cycle. `core/execute.ts` re-exports these names, so
+ * the documented home of the projection is still the execution module.
+ *
+ * ## What "consecutive" means here, stated exactly
+ *
+ * The streak is **per task**, not per action key — SPEC.md §10.2 says "for one
+ * task", and an agent that fails three different actions of the same task in a
+ * row is exactly the runaway loop the rule exists to stop.
+ *
+ * Only two event types move the counter:
+ *
+ * - `execution.failed` increments it;
+ * - `execution.completed` resets it to zero.
+ *
+ * Everything else — `execution.started`, approvals, budget events, another
+ * task's failures — is transparent. In particular a *retry* is not a reset: a
+ * failed action that is started again and fails again is two consecutive
+ * failures, which is the entire point. Only a successful completion is evidence
+ * that the loop broke, so only a completion clears the count.
+ *
+ * ## Escalation is a floor, never a ban
+ *
+ * An escalated task is escalated **to manual**, not to refused. Its manual
+ * actions still request, still grant, and still execute with a token — a human
+ * is now in the loop for every one of them, which is what "escalate to manual"
+ * means. Escalation is also **not** cleared by a human decision, only by an
+ * `execution.completed`: the log records the recovery, or the escalation stands.
+ *
+ * ## The harness scopes (APRV-145)
+ *
+ * Everything above is the per-task streak of SPEC.md §10.2 and is unchanged. A
+ * harness adapter (§10.1) mints a fresh task id for every tool call, so that
+ * streak cannot leave zero on that surface however wedged the session is. The
+ * amended §10.2 answers it with two more streaks, both derived here and both
+ * counted in TOOL CALLS rather than in events:
+ *
+ * - the **session**, `hook:<session id>`, which is a real prefix of every task
+ *   id the adapter mints, so the scope is recovered from a string the runtime
+ *   itself wrote rather than from a field an agent hands the gate;
+ * - the **actor**, the identity the adapter runs as, because a session id is
+ *   authored by the party under oversight and a scope key the subject can
+ *   rotate is a streak the subject can clear (§11.1 invariant 4).
+ *
+ * A command is escalated when EITHER reaches {@link LOOP_ESCALATION_THRESHOLD}.
+ *
+ * ## Only side effects accrue (APRV-280, amended SPEC.md §10.2)
+ *
+ * The streak counts failed executions of classes that DO something. A
+ * `read.*` command that exits non-zero has not failed a side effect: a `grep`
+ * that matches nothing and an `ls` of a path that is not there both exit 1, and
+ * that exit IS the command's answer. Counting those escalated whole sessions to
+ * manual over nothing, which is the incident APRV-280 was filed on: forty-eight
+ * requests queued in an hour behind three failed greps.
+ *
+ * The predicate is {@link isSideEffectingClass} and it is stated once. What it
+ * does NOT do is let a read clear anything: a tool call whose classes are all
+ * reads is transparent to the streak in both directions, so a failing write
+ * streak is not cleared by a successful `ls` in between. The strict direction is
+ * kept everywhere else too — a class this projection cannot resolve from the log
+ * counts as side-effecting, because "we could not establish what this was" is
+ * not "this was harmless".
+ *
+ * The class is read from the `execution.started` record the RUNTIME wrote for
+ * the action key (its `payload.class`), never from anything the reporter said
+ * (§11.1 invariants 1 and 4). The report chooses the outcome; it does not get to
+ * choose the bucket.
+ *
+ * ## Escalation raises scrutiny on side effects only (APRV-297, amended §10.2)
+ *
+ * APRV-280 above says what a read does not ACCRUE. This says what a tripped
+ * floor does not ROUTE, and it is the same sentence read forward: a tool call
+ * whose classes are all `read.*` is answered by the policy under a tripped floor
+ * exactly as it is under a clear one.
+ *
+ * The floor bounds a harm a read cannot cause. It exists to stop an agent
+ * retrying a side effect that keeps failing, so routing a `grep` to a phone buys
+ * no safety at all, and it costs the thing the floor is spending: a human's
+ * attention, once per read, plus the wait the agent spends before it is refused.
+ * On 2026-09-06/07 a floor tripped and a session that could not get an answer
+ * could not read a file either, which is the state this removes.
+ *
+ * Two edges, both narrow. A MIXED tool call is routed whole, as one question,
+ * because the side-effecting half of it is exactly what the floor is for; its
+ * read classes are neither counted nor separately raised, so the approver sees
+ * one prompt for the command's effects and none for its looking. And the
+ * exemption is about ROUTING alone: a read still clears nothing, so a session
+ * cannot read its way out from under a floor.
+ *
+ * This module states the fact; the two surfaces that apply it are the harness
+ * adapter's verdict (`cli/hook.ts`) and the write boundary that re-checks it
+ * (`core/gate.ts`'s `startHarnessExecution`), and both use
+ * {@link isSideEffectingClass} so neither can drift from the other.
+ */
+import type { EventRecord } from "./log.js";
+/**
+ * Consecutive failures that force a task to manual (SPEC.md §10.2). Three, and
+ * the number is spelled here once so the gate, the executor, and the CLI cannot
+ * hold three opinions about it.
+ */
+export declare const LOOP_ESCALATION_THRESHOLD = 3;
+/**
+ * Does an action in this class have a side effect the loop rule is about?
+ * (APRV-280, amended SPEC.md §10.2.)
+ *
+ * THE PREDICATE, exactly: a class is side-effecting unless it is `read` itself
+ * or sits under the `read.` namespace. Everything else — `files.write.*`,
+ * `files.delete.*`, `vcs.*`, `deps.*`, `network.*`, `communicate.*`,
+ * `policy.*`, `log.*`, a routed `policy.edit.*`, and any class this build has
+ * never heard of — is side-effecting. The unknown falls on the strict side by
+ * construction, which is the whole reason the predicate is written as a
+ * carve-OUT of `read.*` rather than as a list of the namespaces that act.
+ *
+ * `core/command-class.ts` already reads `read.*` this way when it decides which
+ * command substitutions may run unattended, and this is deliberately the same
+ * sentence: one reading of "this command only looks at things", used by the
+ * classifier and by loop safety alike.
+ */
+export declare function isSideEffectingClass(cls: string): boolean;
+/** One task's loop state, derived from the log. */
+export interface TaskLoopState {
+    task: string;
+    /** Failures since the last `execution.completed` for this task. */
+    consecutiveFailures: number;
+    /** `consecutiveFailures >= LOOP_ESCALATION_THRESHOLD`. */
+    escalated: boolean;
+    /** The seq of the failure that opened the current streak, or `null`. */
+    streakStartSeq: number | null;
+    /** The seq of the most recent failure in the streak, or `null`. */
+    lastFailureSeq: number | null;
+}
+/**
+ * Loop state for every task that has recorded an execution outcome.
+ *
+ * Returned sorted by task id so the projection is byte-stable: two runs over
+ * the same log produce the same list in the same order, which is what lets
+ * `approval status --json` be pinned by a `deepEqual` test.
+ *
+ * Tasks with side-effecting executions but no failures are included with
+ * `consecutiveFailures: 0` — a caller rendering health wants to know the task
+ * was seen and is clean, and filtering is the caller's business, not this
+ * function's.
+ *
+ * APRV-280: outcomes of `read.*` actions are skipped entirely, so a task whose
+ * every execution was a read appears here not at all. That is the transparency
+ * the amended §10.2 asks for, read in both directions: a failed read accrues
+ * nothing, and a completed read clears nothing either.
+ */
+export declare function loopEscalation(records: EventRecord[]): TaskLoopState[];
+/** Is `task` escalated to manual by loop safety right now? */
+export declare function isLoopEscalated(records: EventRecord[], task: string): boolean;
+/** The prefix every harness adapter task id carries (`src/cli/hook.ts`). */
+export declare const HARNESS_TASK_PREFIX = "hook:";
+/**
+ * The bucket every unreadable session identifier lands in.
+ *
+ * ONE shared bucket, not a fresh one per unreadable id, and the difference is
+ * the whole rule: absence must accrue FASTER and never slower. `parseHookInput`
+ * already substitutes this literal for an absent `session_id`, so the two halves
+ * of the runtime spell it the same way.
+ */
+export declare const UNKNOWN_SESSION = "unknown-session";
+/**
+ * The session scope key of a harness task id, or `null` for a task no harness
+ * adapter minted.
+ *
+ * DERIVED, never declared. The id is `hook:<session>:<tool-use id>` and this
+ * reads its middle segment back out; nothing here reads a scope an agent named.
+ * A `hook:` task that does not split into exactly three colon-separated parts is
+ * an id this runtime cannot read, so it lands in {@link UNKNOWN_SESSION} with
+ * every other unreadable one.
+ */
+export declare function harnessSessionOf(task: string): string | null;
+/** Which derivation produced a {@link HarnessLoopState}'s key. */
+export type HarnessScope = "session" | "actor";
+/** One harness scope's loop state, derived from the log. */
+export interface HarnessLoopState {
+    scope: HarnessScope;
+    /** `hook:<session id>` for a session, the actor identity for an actor. */
+    key: string;
+    /** Consecutive failed TOOL CALLS since the last completed one. */
+    consecutiveFailures: number;
+    /** `consecutiveFailures >= LOOP_ESCALATION_THRESHOLD`. */
+    escalated: boolean;
+    /** The seq that opened the current streak, or `null`. */
+    streakStartSeq: number | null;
+    /** The seq of the most recent failure in the streak, or `null`. */
+    lastFailureSeq: number | null;
+}
+/**
+ * Loop state for every harness session and every harness actor the log has seen
+ * an outcome for.
+ *
+ * Sorted by scope then key so the projection is byte-stable, exactly as
+ * {@link loopEscalation} is, which is what lets `approval status --json` be
+ * pinned by a `deepEqual` test.
+ *
+ * What resets a streak is unchanged and deliberately not widened: only an
+ * `execution.completed` in the same scope, of a SIDE-EFFECTING class since
+ * APRV-280. A hook timeout, a deny, a withdrawn request, a granted approval, a
+ * fresh tool call, a successful `grep`, a restarted process and elapsed time all
+ * leave the streak where they found it. Silence is not evidence of recovery, and
+ * neither is a command that did nothing.
+ */
+export declare function harnessLoopEscalation(records: EventRecord[]): HarnessLoopState[];
+/**
+ * The harness scope that escalated this tool call, or `null` for a command no
+ * streak has floored.
+ *
+ * EITHER scope escalates (amended SPEC.md §10.2). The session is the smallest
+ * scope a runaway actually runs away in; the actor is the backstop, because the
+ * session id is authored by the party under oversight and a scope it can rotate
+ * is a streak it can shed. The session is reported in preference to the actor
+ * where both are tripped, because it is the narrower fact and names the run an
+ * operator has to go and look at.
+ */
+export declare function harnessLoopFloor(records: EventRecord[], task: string, actor: string): HarnessLoopState | null;
+/**
+ * What clears this streak, in one sentence, for the surface that has to say so
+ * (APRV-280).
+ *
+ * Written here rather than at each call site because three surfaces print it —
+ * the gate's `loop-escalated` refusals, the hook's denies, and `approval
+ * status` — and three copies of a sentence about how to get out of a floor are
+ * three chances to tell an operator something that is not true. Everything in
+ * it is a fact of this module: a completion of a SIDE-EFFECTING class in the
+ * same scope, and nothing else, resets the counter.
+ *
+ * The gate window is named for the harness scopes only, because that is the
+ * surface it reaches: an open window routes every gated tool call through the
+ * bypass path before the floor is ever consulted (SPEC.md §5.2, APRV-214). It is
+ * named as the human's ceremony, which is what it is — it needs a terminal and a
+ * typed `understood`, and an agent may not run it.
+ *
+ * The harness sentence also states the routing exemption of APRV-297, and states
+ * it here for the same reason the clearance is here: the operator reading it in
+ * `approval status` and the agent reading it in a deny need the same account of
+ * what a floor does and does not reach, and two copies would eventually give two.
+ */
+export declare function loopClearance(scope: "task" | HarnessScope, key: string): string;
+/** Is this harness tool call floored to manual by either scope right now? */
+export declare function isHarnessLoopEscalated(records: EventRecord[], task: string, actor: string): boolean;
+/** How many harness starts carry an outcome, and how many do not (§10.2). */
+export interface HarnessOutcomeCoverage {
+    started: number;
+    reported: number;
+    unreported: number;
+}
+/**
+ * Coverage of the completion counterpart, for `approval status`.
+ *
+ * INFORMATIONAL. It moves no health verdict and no exit code, for the reason
+ * §8's timestamp anomalies move neither: it is a coverage measurement rather
+ * than an integrity verdict, and a control an operator learns to silence is
+ * worse than one that reports beside the verdict. A persistently high
+ * `unreported` is how an operator learns the post-execution hook is not
+ * installed or not firing.
+ */
+export declare function harnessOutcomeCoverage(records: EventRecord[]): HarnessOutcomeCoverage;