@sema-agent/core 7.5.2 → 7.6.1

package/dist/core/tool-policy.d.ts

@@ -1,3 +1,5 @@
+import type { AskOrigin } from "./ask-origin.js";
+import type { Settlement } from "./gate-outcome.js";
 /** A tool call presented to a policy before it executes. */
 export interface ToolCallRequest {
     toolName: string;
@@ -80,55 +82,17 @@ export interface ToolCallRequest {
  *     spelling this word is minted from). */
 declare const DECISION_REASONS: readonly ["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable"];
 export type DecisionReason = (typeof DECISION_REASONS)[number];
-/**
- * WHO (or what) ENDED an approval — the machine-readable twin of a settlement's human-readable text,
- * so a consumer tells "a person decided this" from "nobody answered" without prose-matching a sentence.
- * The sibling axis of {@link DecisionReason}, which says which LAYER produced a verdict; this one says
- * what ended the WAIT.
- *
- *  - `"human"` — a person, or the approver acting for one, returned a final verdict (allow or deny).
- *  - `"timeout"` — an approval window elapsed with no answer.
- *  - `"aborted"` — every other NON-HUMAN end: the task aborted, the approver threw or reported nobody
- *    reachable, the decision arrived out of contract, a store or transport gave way, retries ran out.
- *
- * **Which windows `"timeout"` speaks for** (#114①, 2026-08-09 — the promise this note used to make was
- * wider than the code): the engine stamps it at the waits IT owns — `createApprovalPolicy`'s
- * `approvalTimeoutMs` window, the durable park's TTL, and (#548) the denial-limit fallback ask's
- * auto-deny window. The SYNCHRONOUS `onAsk` leg is otherwise not one of them: there the deployment owns
- * the window (the engine starts no timer for a callback it does not schedule), so an unanswered card and
- * a refused one arrive as the same `false` and the engine records
- * `"human"` rather than inventing a cause it did not observe. A host that DOES time its own card out
- * can say so — {@link AskOutcome}'s object arm carries an optional `settledBy` for exactly this — but a
- * host that does not is indistinguishable, by construction. Read an absent `"timeout"` as "no window
- * the engine owns elapsed", never as "nobody's window elapsed".
- *
- * **The one `onAsk` exception** (#548): a classifier DENIAL-LIMIT fallback ask — the ask that carries
- * `denialLimitFallback`, minted when the auto-mode classifier reaches its consecutive/total bound —
- * IS timed by the engine over the synchronous leg, because that ask exists to bound a classifier that
- * would otherwise deny without end, and an unbounded wait would only move the "without end" onto the
- * person. Its window elapsing produces an engine-stamped `settledBy: "timeout"` with
- * `resolution: "window_expired"` and `autoDenied: true` on the deny — that last bit is the
- * discriminator between core's window and a host self-report ({@link AskOutcome}'s object arm has no
- * `autoDenied` seat, so a host cannot claim the word).
- * `autoDenyAfterMs: 0` (or an ask with no fallback member) arms nothing, which is every other ask.
- *
- * The three words are exhaustive and mutually exclusive over the ways an approval can end, and the
- * minimum discrimination a consumer needs — someone refused vs nobody answered — is `"human"` vs the
- * other two.
- *
- * **Fill it AT the settlement site.** Each site knows its own cause and names it; deriving the value
- * afterwards from whatever outcome happens to be at hand is exactly how a window that elapsed comes to
- * be reported as a person's refusal.
- *
- * ABSENT means this settlement named no source: an older caller that predates the field, or a verdict
- * that settled no wait at all (a policy POSTURE — headless auto-deny, a blanket circumvention — where nobody
- * was ever asked). A consumer MUST NOT read a semantic out of the absence; render the text instead.
- */
-export type ApprovalSettledBy = "human" | "timeout" | "aborted";
-/** The closed set above, for runtime domain checks at the seams that accept a caller-supplied value. */
-export declare const APPROVAL_SETTLED_BY_VALUES: readonly ApprovalSettledBy[];
-/** True iff `v` is one of the three {@link ApprovalSettledBy} words. */
-export declare function isApprovalSettledBy(v: unknown): v is ApprovalSettledBy;
+/** Read the engine-attested settlement off a funneled decision FOR the named call (the gate's exit is the
+ *  one consumer): an attestation bound to a different call is a replayed object and answers absence.
+ *  Exported for the gate module only — deliberately NOT re-exported from `src/index.ts` (an internal seam
+ *  between engine modules, not a facility deployments call). */
+export declare function engineSettlementOf(d: unknown, call: {
+    toolCallId: string;
+    toolName: string;
+}): {
+    settlement: Settlement;
+    origin: AskOrigin;
+} | undefined;
 /**
  * design/252 G-7 — how long an approver-attribution identifier may be.
  *
@@ -176,10 +140,10 @@ export declare function screenApproverAttribution(v: unknown): {
  *  - `deny` blocks the call.
  * Human-readable text is `message`; read it via {@link decisionText}.
  *
- * The two TERMINAL arms may also carry {@link ApprovalSettledBy} as `settledBy` — what ended the wait,
- * when this verdict ended one. It is on `allow`/`deny` and deliberately NOT on `ask`: an `ask` has
- * settled nothing yet, so a source there would name a decider who has not decided. A layer that never
- * waited for anyone omits it (see the type's ABSENT clause).
+ * NO arm carries a settlement: what ended a wait is not a policy's to state. The engine's own settlement
+ * sites attest it through a module-private seat ({@link engineSettlementOf}) and the gate's exit mints the
+ * one settlement record ({@link import("./gate-outcome.js").GateOutcome}); a policy that puts a `settledBy`
+ * or `approver` member on its verdict is putting an unread property on it.
  * RB-479-B① (ruled 2026-08-02): the legacy `reason` field is REMOVED — one name for one thing.
  *
  * How far the TYPE carries that retirement (measured 2026-08-03, correcting this note's earlier claim
@@ -200,8 +164,6 @@ export type PermissionResult = {
     updatedInput?: unknown;
     message?: string;
     decisionReason?: DecisionReason;
-    settledBy?: Extract<ApprovalSettledBy, "human">;
-    approver?: string;
 } | {
     action: "ask";
     updatedInput?: unknown;
@@ -297,8 +259,6 @@ export type PermissionResult = {
     updatedInput?: unknown;
     message?: string;
     decisionReason?: DecisionReason;
-    settledBy?: ApprovalSettledBy;
-    approver?: string;
 };
 /**
  * design/252 G-2 — WHY a piece of rule-provenance evidence is not on an ask.
@@ -1204,7 +1164,7 @@ export interface AskRequest {
      *  {@link PermissionResult} ask-arm member of the same name): the counts that tripped the bound and
      *  this ask's own auto-deny window. Two readers: a card renders it as a countdown; {@link resolveAsk}
      *  arms its deadline from `autoDenyAfterMs` (> 0 ⇒ an unanswered function approver auto-denies at
-     *  that deadline — `settledBy:"timeout"`, `resolution:"window_expired"`, `autoDenied:true`). Filled
+     *  that deadline — the `denial_limit_window_expired` settlement on the gate record). Filled
      *  by the gate from the decision, never a caller/worker-settable field. This is the ARMED type: the
      *  decision's member carries the counts alone, and the only two ways to reach this one are the route
      *  stations — `AutoModeDenialTracker.armTimedWindow` (a hand-out to a live function approver, the one
@@ -1349,9 +1309,8 @@ export type OnAsk = "deny" | "allow" | ((req: AskRequest, signal?: AbortSignal)
  * the fallback exists to bound a classifier that would otherwise deny without end. When it elapses
  * the approver's promise is DETACHED (design/384: the wait is released, not cancelled — an approver
  * that answers afterwards is not consulted, and an `allow` it returns late becomes the
- * `task.late_approval` notice), and the engine's own deny carries `settledBy: "timeout"`,
- * `resolution: "window_expired"` and `autoDenied: true`. See {@link ApprovalSettledBy} for how a
- * consumer tells that window from the host's.
+ * `task.late_approval` notice), and the engine's own deny settles as `denial_limit_window_expired`
+ * (the host's own elapsed window settles as `approval_window_expired` with `who.party: "host"`).
  *
  * `reason` — the SYNCHRONOUS leg's seat for a model-readable reason attached to a deny, the exact
  * counterpart of the durable leg's `ResumeOutcome` `policy_ask` `reason` ("Model-readable reason
@@ -1387,7 +1346,7 @@ export type OnAsk = "deny" | "allow" | ((req: AskRequest, signal?: AbortSignal)
 export type AskOutcome = boolean | "unavailable" | {
     allow: boolean;
     updatedInput?: unknown;
-    settledBy?: Extract<ApprovalSettledBy, "human" | "timeout">;
+    settledBy?: "human" | "timeout";
     reason?: string;
     approver?: string;
 };
@@ -1473,90 +1432,35 @@ export declare function tryCloneArgs<T>(v: T): {
  * text they let through. Not part of the package's public surface.
  */
 export declare function describeThrown(err: unknown): string;
-/**
- * The deny-arm classification a {@link resolveAsk} refusal carries — MINTED at the composing arm
- * (the minter reports the fact; no consumer re-derives it from message text, which is exactly the
- * inference this closed set exists to end). One word per family of arms:
- *  - `"human_refused"` — a person answered no (the boolean false fold and the object arm's
- *    allow-false, noted or bare — the note fact rides {@link ResolvedAsk.humanRefusalNote});
- *  - `"window_expired"` — the approver's own window elapsed (the timeout-settled deny);
- *  - `"no_approver"` — headless auto-deny (no approver wired, or the deny posture string);
- *  - `"blanket_allow_refused"` — a blanket allow posture met a `requiresRealApproval` ask;
- *  - `"approver_unavailable"` — the approver answered the ROUTING question "nobody reachable"
- *    (the G1 marker's fail-closed carry — the gate may re-route it to a durable park instead);
- *  - `"task_aborted"` — the wait's abort signal ended it (pre-wait, mid-wait and race arms). The
- *    signal is the run's own end AND, since design/384, any turn-level interrupt composed into the
- *    wait (a bare user halt, a steer-now boundary cut): one abort family, one word — a consumer
- *    that must tell the sources apart reads the run's own terminal facts, not this classification;
- *  - `"presentation_failed"` — the args/edit could not be safely presented or adopted (unclonable);
- *  - `"approver_error"` — the approver callback threw;
- *  - `"approver_contract"` — the approver returned something outside the contract (non-boolean
- *    allow, out-of-vocabulary settlement word, unreadable members, a timeout-settled allow, a
- *    non-string or unreadable reason, an out-of-contract truthy, a refused attribution).
- */
-export type AskDenyResolution = "human_refused" | "window_expired" | "no_approver" | "blanket_allow_refused" | "approver_unavailable" | "task_aborted" | "presentation_failed" | "approver_error" | "approver_contract";
-/** The closed set above, for runtime domain checks at the seams that accept a caller-supplied value
- *  (the `APPROVAL_SETTLED_BY_VALUES` precedent: the word crosses process boundaries on `tool_end`,
- *  so a consumer enumerating or validating it must not hand-roll the vocabulary). */
-export declare const ASK_DENY_RESOLUTION_VALUES: readonly AskDenyResolution[];
-/** Closed-vocabulary guard for {@link AskDenyResolution} — the screen every carrier runs before it
- *  files or forwards the word (a policy layer could self-declare the member on its own deny; an
- *  out-of-vocabulary word is dropped by the carriers, never coerced or forwarded). */
-export declare function isAskDenyResolution(v: unknown): v is AskDenyResolution;
-/** #548: the engine-attested auto-deny marker off a funneled decision, bound to the named call like
- *  {@link coreMintedResolutionOf} (absent ⇒ not an attested auto-deny of THIS call). */
-export declare function coreMintedAutoDeniedOf(d: unknown, call: {
-    toolCallId: string;
-    toolName: string;
-}): boolean;
-/** Read the engine-attested resolution off a funneled decision (the gate's single deny exit is the
- *  one consumer), FOR the named call: an attestation bound to a different toolCallId/toolName is a
- *  replayed object, not this call's settlement — the reader answers absence (the safe direction; the
- *  public `settledBy`/message on such an object were always the policy's own to state). A present
- *  word is an engine settlement site's own attestation for THIS object and THIS call — no foreign
- *  policy can reach the sidecar. The vocabulary screen is a belt (the typed stamp is the only
- *  writer). Exported for the gate module only — deliberately NOT re-exported from `src/index.ts`
- *  (the {@link refuseOutOfContractDecision} precedent: an internal seam between engine modules, not
- *  a facility deployments call). */
-export declare function coreMintedResolutionOf(d: unknown, call: {
-    toolCallId: string;
-    toolName: string;
-}): AskDenyResolution | undefined;
 /**
  * A {@link resolveAsk} result: always a TERMINAL `allow`/`deny` (never `ask`). `approverUnavailable`
  * is the out-of-band G1 three-value marker: the live approver returned `"unavailable"` for this ask —
  * the carried `deny` is the FAIL-CLOSED FALLBACK, and the gate may instead re-route the ask onto the
  * durable park leg (the only consumer; everywhere else the result reads as a plain deny).
  */
-export type ResolvedAsk = PermissionResult & {
-    approverUnavailable?: true;
-    /** The EXACT data snapshot the approver was shown (the `structuredClone` of the
-     *  presented args). On a plain approval (no edit) the gate EXECUTES this snapshot, not the original
-     *  object: a stateful getter or an external alias must not be able to make the executed action
-     *  differ from the approved one (shown == executed, by construction). Set only on the
-     *  function-approver path (string modes present nothing). */
+export type ResolvedAsk = (Extract<PermissionResult, {
+    action: "allow";
+}> & {
+    /** Present exactly when a PERSON approved (`human_allowed`, with the channel's attribution when it
+     *  reported one); absent on the posture allows (a blanket `"allow"`, a reused grant) — nobody was
+     *  asked, so nothing was settled. */
+    settlement?: Settlement;
+    /** The EXACT data snapshot the approver was shown (the `structuredClone` of the presented args). On
+     *  a plain approval (no edit) the gate EXECUTES this snapshot, not the original object: a stateful
+     *  getter or an external alias must not be able to make the executed action differ from the
+     *  approved one (shown == executed, by construction). Set only on the function-approver path
+     *  (string modes present nothing). */
     presentedInput?: unknown;
-    /** Present exactly when this deny is a PERSON's refusal (`settledBy: "human"`) that carried the
-     *  decider's own note (the object arm's `reason`, screened and non-empty). Its ABSENCE on a human
-     *  deny is the structural fact that the refusal was BARE — a "no" with no direction attached —
-     *  which is the arm the runner treats as a control-flow boundary for the issuing batch (a bare
-     *  "no" on the parent thread halts the remaining same-message tool calls; a refusal WITH a note
-     *  gives the model direction to adapt to, so the turn continues). Never derived from message
-     *  text; stamped only at the composing arm. Not stamped on the timeout deny (nobody answered)
-     *  or on any engine-produced fail-closed refusal. */
-    humanRefusalNote?: true;
-    /** #548 — present exactly when this deny is the classifier denial-limit fallback's AUTO-DENY: the
-     *  ask's own window (`AskRequest.denialLimitFallback.autoDenyAfterMs`, CC `AKe`) elapsed with no
-     *  answer. Rides beside `settledBy:"timeout"` / `resolution:"window_expired"` (the established approval
-     *  factory's deadline arm speaks the same two words, so a consumer classifying on them needs no new
-     *  branch) and says WHOSE window it was: core's, not the host's. Stamped only at the composing arm. */
-    autoDenied?: true;
-    /** The deny-arm classification (see {@link AskDenyResolution}) — present on every deny this
-     *  resolver composes, absent on every allow. Carried by the gate to its block exit, the
-     *  permission-denied observer payload and the settlement sideband (thence the call's `tool_end`
-     *  frame), so a consumer classifies a refusal by code instead of parsing its text. */
-    resolution?: AskDenyResolution;
-};
+    approverUnavailable?: never;
+}) | (Extract<PermissionResult, {
+    action: "deny";
+}> & {
+    /** What ended the wait — composed at the arm that ended it, one of the refusal kinds. A deny this
+     *  resolver composes ALWAYS names its settlement: there is no unclassified refusal. */
+    settlement: Settlement;
+    presentedInput?: unknown;
+    approverUnavailable?: true;
+});
 /**
  * Does any string reachable in `value` carry a {@link BIDI_CONTROL_RE} member? Bounded, cycle-safe,
  * and never throwing — every caller is on an approval/projection path, where a scan that failed must