@sema-agent/core 7.5.2 → 7.6.1

package/dist/core/gate-outcome.d.ts

@@ -0,0 +1,189 @@
+/**
+ * The settlement record and the gate outcome — the L0 vocabulary of what ONE tool-gate pass decided,
+ * what ask it settled and who asked. One structure, minted once (the gate's exit; the decide lane for a
+ * durable park) and projected three times without re-derivation: the `permissionDenied` observer's
+ * payload, the call's `tool_end` frame, and the durable row's resolved outcome. Lives beside
+ * `tool-policy.ts` rather than in it because it is a different concern from the permission verdict a
+ * policy composes: a policy says allow / ask / deny; this file says how the pass that consumed that
+ * verdict ended.
+ */
+import { type AskOrigin, type AssertAllKeysHandled } from "./ask-origin.js";
+/**
+ * How the wait an ask was in ENDED — the closed set. One word per way a wait can end; the `who` on the
+ * record says which party ended it and is fixed BY the word (see {@link Settlement}).
+ *  - `human_allowed` / `human_refused` — a person (or the approver acting for one) decided; the refusal's
+ *    own note, when the decider attached one, rides `note`.
+ *  - `approval_window_expired` — an approval window elapsed with no answer: the engine's own approval
+ *    factory window (`createApprovalPolicy.approvalTimeoutMs`), or a synchronous host approver that
+ *    reported its own window elapsed.
+ *  - `denial_limit_window_expired` — the classifier denial-limit fallback's auto-deny window (core's own
+ *    timer over the synchronous leg) elapsed with no answer.
+ *  - `park_sla_expired` — a DURABLE park's SLA deadline passed and the host's sweep resolved it as a deny
+ *    (FACET A). A store `expire`/`reap` produces no `tool_end` and therefore no settlement.
+ *  - `no_approver` — headless: no approver (or no question face) is wired, or the deny posture string.
+ *  - `approver_unavailable` — the approver (or an ancestor's frozen approver) answered the ROUTING question
+ *    "nobody reachable", and no park took the ask.
+ *  - `approver_error` — the approver threw.
+ *  - `approver_contract` — the approver answered outside its contract (a non-boolean verdict, an
+ *    unreadable member, a timeout-settled allow, a refused attribution…).
+ *  - `presentation_failed` — the args or the edit could not be safely presented/adopted (unclonable).
+ *  - `blanket_allow_refused` — a blanket `onAsk:"allow"` met a `requiresRealApproval` ask.
+ *  - `task_aborted` — the wait's abort signal ended it (the run's own end, or a turn-level interrupt).
+ */
+export declare const SETTLEMENT_KINDS: readonly ["human_allowed", "human_refused", "approval_window_expired", "denial_limit_window_expired", "park_sla_expired", "no_approver", "approver_unavailable", "approver_error", "approver_contract", "presentation_failed", "blanket_allow_refused", "task_aborted"];
+export type SettlementKind = (typeof SETTLEMENT_KINDS)[number];
+/** Membership test for {@link SettlementKind} — the word crosses process boundaries on `tool_end`, so a
+ *  consumer validating one it received must not hand-roll the set. */
+export declare function isSettlementKind(v: unknown): v is SettlementKind;
+/**
+ * The settlement record: WHAT ended the wait (`kind`), WHO ended it (`who` — its shape is decided by the
+ * word: the two human words carry a person, the window words say whose window, the park word the host,
+ * the fail-closed family nobody), WHEN (epoch ms, written at the settlement site), and for a person's
+ * refusal the decider's own NOTE when one was attached (a refusal WITHOUT a note is a bare "no", the arm
+ * the runner treats as a control-flow boundary for the issuing batch).
+ *
+ * It is a discriminated union and not a free product of `kind` × `who` on purpose: a free product can
+ * express "human_allowed, ended by the engine's window" — a structurally complete record that contradicts
+ * itself — and a consumer would then need the pairing rules this shape makes unwritable.
+ *
+ * @contract settlement.single_mint — every `Settlement` kind is composed by CORE at the site whose wait
+ * ended (the ask resolver's arms, the approval factory's arms, the decide lane over a host's decision
+ * FACTS). A host never mints a kind: a synchronous approver reports `"human"`/`"timeout"` on its outcome
+ * and a durable decide reports `hostDecision.decidedBy` (`"person"`/`"sla_timeout"`) — facts core turns
+ * into the word. Nothing on the caller-composable policy face (`PermissionResult`) carries a settlement,
+ * so a policy cannot self-declare one; the engine's own settlement sites that hand a settled decision
+ * back through a policy fold attest it through {@link engineSettlementOf}.
+ */
+export type Settlement = {
+    kind: "human_allowed" | "human_refused";
+    who: {
+        party: "person";
+        approver?: string;
+    };
+    when: number;
+    note?: string;
+} | {
+    kind: "approval_window_expired";
+    who: {
+        party: "engine";
+        window: "approval_factory";
+    } | {
+        party: "host";
+    };
+    when: number;
+} | {
+    kind: "denial_limit_window_expired";
+    who: {
+        party: "engine";
+        window: "denial_limit";
+    };
+    when: number;
+} | {
+    kind: "park_sla_expired";
+    who: {
+        party: "host";
+        approver?: string;
+    };
+    when: number;
+} | {
+    kind: "no_approver" | "approver_unavailable" | "approver_error" | "approver_contract" | "presentation_failed" | "blanket_allow_refused" | "task_aborted";
+    who: {
+        party: "none";
+    };
+    when: number;
+};
+/** Which settlement kinds are REFUSALS (the ask ended as a deny). Total over the closed set — the fence
+ *  below refuses a member without a row — so invariant I2 is a table lookup, not a list in a condition. */
+export declare const SETTLEMENT_IS_REFUSAL: {
+    readonly human_allowed: false;
+    readonly human_refused: true;
+    readonly approval_window_expired: true;
+    readonly denial_limit_window_expired: true;
+    readonly park_sla_expired: true;
+    readonly no_approver: true;
+    readonly approver_unavailable: true;
+    readonly approver_error: true;
+    readonly approver_contract: true;
+    readonly presentation_failed: true;
+    readonly blanket_allow_refused: true;
+    readonly task_aborted: true;
+};
+/** Compile-time fence: `never` while every settlement kind has a refusal row. */
+export type SettlementRefusalTableCoversEveryKind = AssertAllKeysHandled<Exclude<SettlementKind, keyof typeof SETTLEMENT_IS_REFUSAL>>;
+/**
+ * WHO REFUSED a call — the layer whose verdict is the deny. The other question a deny raises, "who ASKED",
+ * is answered by {@link GateOutcome.origin} (an {@link import("./ask-origin.js").AskOrigin}); the two used
+ * to share one seven-word list (`PermissionDeniedSource`) in which `classifier` meant both "the classifier
+ * asked" and "the classifier denied".
+ *  - `policy` — the deployment `ToolPolicy` denied (directly, or re-checking an approved edit), or the
+ *    approval-edit chain hit its round cap.
+ *  - `hook` — a PreToolUse hook denied, threw, or never answered (the engine's fail-closed block on a
+ *    hook that made no decision counts as the hook layer's refusal for attribution).
+ *  - `org` — an organization policy rule denied.
+ *  - `classifier` — the auto-mode classifier denied directly (its ASK-side role is `origin:
+ *    "denial_limit_fallback"`).
+ *  - `plan_mode` — plan mode's read-only block on a write tool.
+ *  - `compliance` — the compliance call-time lock.
+ *  - `write_protection` — an approved edit was rewritten by the restriction chain onto a write-protected
+ *    path that no approval covers.
+ *  - `ask_resolution` — the ask's own settlement is the refusal (a person said no, a window elapsed,
+ *    nobody could be asked…); the detail is on {@link GateOutcome.settlement}.
+ */
+export declare const DENIED_BY_VALUES: readonly ["policy", "hook", "org", "classifier", "plan_mode", "compliance", "write_protection", "ask_resolution"];
+export type DeniedBy = (typeof DENIED_BY_VALUES)[number];
+/** Membership test for {@link DeniedBy}. */
+export declare function isDeniedBy(v: unknown): v is DeniedBy;
+/** Which layers may VETO an approval a person already gave (invariant I3: a `human_allowed` settlement
+ *  beside a `denied` disposition names one of these). The approval-edit re-screen (hook), the policy and
+ *  org re-checks, and the write-protection re-judge run AFTER the person's yes; the classifier, plan mode
+ *  and compliance run before any ask exists, and `ask_resolution` IS the settlement, not a veto of it. */
+export declare const DENIED_BY_MAY_VETO: {
+    readonly policy: true;
+    readonly hook: true;
+    readonly org: true;
+    readonly classifier: false;
+    readonly plan_mode: false;
+    readonly compliance: false;
+    readonly write_protection: true;
+    readonly ask_resolution: false;
+};
+/** Compile-time fence: `never` while every deny layer has a veto row. */
+export type VetoTableCoversEveryDeniedBy = AssertAllKeysHandled<Exclude<DeniedBy, keyof typeof DENIED_BY_MAY_VETO>>;
+/** The final disposition of a gate pass. */
+export type GateDisposition = {
+    kind: "allowed";
+} | {
+    kind: "denied";
+    deniedBy: DeniedBy;
+};
+/**
+ * The WHOLE record of one tool-gate pass: the final disposition, plus — when this pass settled an ask —
+ * the settlement it consumed and the ask's origin. Minted ONCE (the gate's exit; the decide lane for a
+ * durable park) and projected three times without re-derivation: the `permissionDenied` observer's
+ * payload, the call's `tool_end` frame, and the durable row's resolved outcome. The three faces are the
+ * same object graph, so they cannot tell different stories.
+ *
+ * The three members are orthogonal but bound by four invariants ({@link screenGateOutcome}):
+ *  I1  `settlement` present ⇔ `origin` present (they describe the same ask);
+ *  I2  `disposition.deniedBy === "ask_resolution"` ⇒ `settlement` present and a refusal kind;
+ *  I3  `settlement.kind === "human_allowed"` ∧ `disposition.kind === "denied"` ⇒ `deniedBy` is a veto
+ *      layer ({@link DENIED_BY_MAY_VETO}) — a person approved, a later re-check refused; the approver stays
+ *      on the settlement (it is not the approver's refusal);
+ *  I4  `disposition.kind === "allowed"` ⇒ `settlement` absent or `human_allowed`.
+ * Nothing here is read out of an ABSENCE: an ordinary allow with no ask is `{ disposition: { kind: "allowed" } }`,
+ * a direct policy deny is `{ disposition: { kind: "denied", deniedBy: "policy" } }`, and neither carries a
+ * settlement because neither settled one.
+ */
+export interface GateOutcome {
+    disposition: GateDisposition;
+    settlement?: Settlement;
+    origin?: AskOrigin;
+}
+/**
+ * The one invariant screen for a {@link GateOutcome} (I1–I4 above, plus the shape of each member). Runs
+ * where an outcome enters a wire face — the engine's settlement sideband before the `tool_end` frame, and
+ * the decide lane before a durable row is resolved. Returns the defects as sentences (an empty list is a
+ * clean record); the caller decides the fail-loud form (report + withhold, or refuse), never silently
+ * repairs the record.
+ */
+export declare function screenGateOutcome(g: GateOutcome): string[];

package/dist/core/gate-outcome.js

@@ -0,0 +1,70 @@
+import { isAskOrigin } from "./ask-origin.js";
+export const SETTLEMENT_KINDS = [
+    "human_allowed",
+    "human_refused",
+    "approval_window_expired",
+    "denial_limit_window_expired",
+    "park_sla_expired",
+    "no_approver",
+    "approver_unavailable",
+    "approver_error",
+    "approver_contract",
+    "presentation_failed",
+    "blanket_allow_refused",
+    "task_aborted",
+];
+const SETTLEMENT_KIND_SET = new Set(SETTLEMENT_KINDS);
+export function isSettlementKind(v) {
+    return SETTLEMENT_KIND_SET.has(v);
+}
+export const SETTLEMENT_IS_REFUSAL = {
+    human_allowed: false,
+    human_refused: true,
+    approval_window_expired: true,
+    denial_limit_window_expired: true,
+    park_sla_expired: true,
+    no_approver: true,
+    approver_unavailable: true,
+    approver_error: true,
+    approver_contract: true,
+    presentation_failed: true,
+    blanket_allow_refused: true,
+    task_aborted: true,
+};
+export const DENIED_BY_VALUES = ["policy", "hook", "org", "classifier", "plan_mode", "compliance", "write_protection", "ask_resolution"];
+const DENIED_BY_SET = new Set(DENIED_BY_VALUES);
+export function isDeniedBy(v) {
+    return DENIED_BY_SET.has(v);
+}
+export const DENIED_BY_MAY_VETO = {
+    policy: true,
+    hook: true,
+    org: true,
+    classifier: false,
+    plan_mode: false,
+    compliance: false,
+    write_protection: true,
+    ask_resolution: false,
+};
+export function screenGateOutcome(g) {
+    const defects = [];
+    const d = g.disposition;
+    if (d.kind === "denied" && !isDeniedBy(d.deniedBy))
+        defects.push(`disposition.deniedBy "${String(d.deniedBy)}" is outside the closed set`);
+    const s = g.settlement;
+    if (s !== undefined && !isSettlementKind(s.kind))
+        defects.push(`settlement.kind "${String(s.kind)}" is outside the closed set`);
+    if (g.origin !== undefined && !isAskOrigin(g.origin))
+        defects.push(`origin "${String(g.origin)}" is outside the closed set`);
+    if ((s !== undefined) !== (g.origin !== undefined))
+        defects.push("I1: settlement and origin must be present together — they describe the same ask");
+    if (d.kind === "denied" && d.deniedBy === "ask_resolution" && (s === undefined || !isSettlementKind(s.kind) || !SETTLEMENT_IS_REFUSAL[s.kind])) {
+        defects.push("I2: deniedBy ask_resolution requires a settlement whose kind is a refusal");
+    }
+    if (s !== undefined && s.kind === "human_allowed" && d.kind === "denied" && isDeniedBy(d.deniedBy) && !DENIED_BY_MAY_VETO[d.deniedBy]) {
+        defects.push(`I3: a human_allowed settlement beside a deny must name a veto layer, not "${d.deniedBy}"`);
+    }
+    if (d.kind === "allowed" && s !== undefined && s.kind !== "human_allowed")
+        defects.push(`I4: an allowed disposition cannot carry a "${s.kind}" settlement`);
+    return defects;
+}

package/dist/core/hands-band.d.ts

@@ -0,0 +1,134 @@
+/**
+ * design/138 S2-C — the hands band's write-time CONTENT hook (single source; `src/tools/fs` re-exports
+ * these so its import surface is unchanged — moved here by design/141 件2 because `RunnerDeps.hands`
+ * carries the deployment-composable half of the hook). Called before EVERY `env.writeFile` in
+ * Write/Edit/NotebookEdit with the resolved containment key and the exact final text; `{ ok:false }`
+ * fails the tool with a structured error and NOTHING is written. A THROWING hook fails CLOSED.
+ */
+export interface BeforeWriteRequest {
+    tool: "Write" | "Edit" | "NotebookEdit";
+    /** The model-supplied path argument (for the error-message coordinate the model knows). */
+    path: string;
+    /** The resolved canonical containment key — what the hook should judge. */
+    key: string;
+    /** The FINAL full text about to be written (Edit/NotebookEdit: after application). */
+    content: string;
+}
+export type BeforeWriteResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: string;
+    reason: string;
+};
+export type BeforeWriteHook = (req: BeforeWriteRequest) => BeforeWriteResult | undefined | Promise<BeforeWriteResult | undefined>;
+/**
+ * design/381 — the hands band's FIRST-TOUCH HISTORY hook, called before EVERY file mutation in
+ * Write/Edit/NotebookEdit (after the `beforeWrite` content gate passed, immediately before the
+ * final env write) with the resolved canonical containment key. The Runner wires it to
+ * `FileHistoryStore.trackEdit` (backup-before-first-edit, the CC FileHistory trigger-point set
+ * minus the bash simulation arm sema does not have — DV-7); later calls for an already-tracked
+ * path are cheap store no-ops. `{ok:false}` carries the REFUSAL TEXT the tool must answer instead
+ * of writing (DV-14 default: no durable first-touch state ⇒ the edit is refused, typed and loud —
+ * any proceed-unprotected policy is resolved INSIDE the hook by the Runner, never by the band).
+ * A THROWING hook fails CLOSED (same posture as the write gate). Absent hook ⇒ byte-identical
+ * behavior (no history store wired).
+ */
+export interface TrackEditRequest {
+    tool: "Write" | "Edit" | "NotebookEdit";
+    /** The model-supplied path argument (for the error-message coordinate the model knows). */
+    path: string;
+    /** The resolved canonical containment key — the identity the history record is keyed on. */
+    key: string;
+    /** The tool call's abort signal, threaded into the store's env read. */
+    signal?: AbortSignal;
+}
+export type TrackEditResult = {
+    ok: true;
+    /**
+     * #491 — the compensating handle for the ordering the topology cannot avoid: the pre-image
+     * capture runs BEFORE the write, so a write that then FAILS (lost create race, ENOSPC,
+     * EACCES, read-only mount) would leave a first-touch record for an edit that never happened —
+     * and an `existed-not` record makes an untouched path a rewind DELETE target, removing bytes
+     * whoever writes them next (the user, a peer process) owns. Present ONLY when THIS call minted
+     * the record (an already-tracked path belongs to the edit that first touched it and must never
+     * be discarded); the band calls it on the write-failure arm of every mutation lane. `proof`
+     * says which retraction rule applies: `"proven"` = the write's own error code guarantees
+     * nothing was written, `"verify"` = ambiguous, so the history seat must re-read the path and
+     * retract only if it still matches what the first touch recorded. It never throws and never
+     * blocks the failure it accompanies — the original write error is the answer.
+     */
+    annul?: (proof: "proven" | "verify") => Promise<void>;
+} | {
+    ok: false;
+    refusal: string;
+};
+export type TrackFileEditHook = (req: TrackEditRequest) => Promise<TrackEditResult>;
+/**
+ * The hands band's MUTATION-EDITED observation seat — the counterpart of {@link TrackEditRequest},
+ * fired at the other end of the same lane. Called once per Write/Edit/NotebookEdit call whose FINAL
+ * env write did not PROVABLY write nothing, at the single point every mutation lane funnels through,
+ * under the same three-valued law as the first-touch record's own retraction:
+ *  - a call the argument checks, the read-before-edit gate, the write gate or the first-touch
+ *    history seat refused never fires it (nothing was written);
+ *  - a call whose write FAILED with a code whose contract says nothing was written never fires it;
+ *  - a call whose write failed AMBIGUOUSLY (a non-atomic env that truncated and then errored) or
+ *    THREW fires it — exactly the arm where the retraction KEEPS the first-touch record because the
+ *    file may really have changed. The two seats agree on purpose: a file whose baseline was kept
+ *    for a possible modification must also be listed as possibly modified;
+ *  - a `Bash` command that changed a file never fires it: bash does not run through this band's
+ *    write lanes at all, which is the whole reason this seat is not a tool-name table.
+ * PURE OBSERVATION: it returns nothing and it cannot refuse. A FAULT in it is contained in both
+ * shapes an observer can fail in — a synchronous throw, and (the return type is `void`, but an
+ * `async` function still type-checks there) a rejected promise, which is sunk rather than left
+ * unhandled. Neither is awaited: an observer must never turn a landed write into a failed tool
+ * answer, nor delay one.
+ */
+export interface FileEditedNotice {
+    tool: "Write" | "Edit" | "NotebookEdit";
+    /** The model-supplied path argument — the SAME coordinate the delegated-child projection's
+     *  `SubagentEditedFile.path` carries, so the two seats can be read side by side. */
+    path: string;
+    /** The resolved canonical containment key the bytes actually landed on. */
+    key: string;
+}
+export type FileEditedHook = (notice: FileEditedNotice) => void;
+/**
+ * design/141 件2 — the SAFE deployment-configurable subset of the hands toolkit ({@link RunnerDeps.hands}).
+ * Only fields whose injection is purely additive for a deployment are here; Runner-internal orchestration
+ * state (taskRegistry/detachHub/execClamp/cwdRef/mount coordination) is deliberately NOT configurable.
+ */
+export interface HandsBandOptions {
+    /** Override the `bash_readonly` command allowlist (read-only band). Default: the built-in read-only set. */
+    bashReadonlyAllow?: readonly string[];
+    /** Co-Authored-By trailer for the bash git protocol. Default NONE ([c209] BREAKING: attribution is a
+     *  deployment identity asset — the branded scenario sets `"Name <email>"`); `false` ≡ unset. */
+    commitCoAuthor?: string | false;
+    /** Read-tool image downsampler: inject your own, or `false` to force-disable (deterministic no-sharp).
+     *  Omitted ⇒ auto-detect sharp. Same contract as the MCP-side {@link import("./mcp.js").ImageDownsampler}. */
+    readImageDownsampler?: ((input: Buffer, mimeType: string) => Promise<import("./mcp.js").DownsampledImage | undefined>) | false;
+    /** Deployment write gate — COMPOSED with (never replacing) the engine's MemoryEngine write-scan gate:
+     *  this hook judges first (a rejection short-circuits), the engine gate then still runs in full. */
+    beforeWrite?: BeforeWriteHook;
+    /** RB-198 F1 (CC 220 `Zry`/`WZi.#m` parity): on a foreground Bash command's OWN timeout, an eligible
+     *  command (see `canAutoBackground` — no `git` anywhere in the command, not a `sleep`-first-word wait) is
+     *  adopted as a background task instead of being killed — CC's own posture ("received no response for
+     *  Nms" would otherwise force a wasteful blind re-run of a non-idempotent long command). Default `false`
+     *  (byte-compat): this is a deployment-level opt-in, deliberately NOT inferred from background-task
+     *  plumbing (`detachHub`/`taskRegistry`) merely being present, since the Runner wires those unconditionally
+     *  for every task — tying eligibility to their mere presence would silently flip the timeout outcome for
+     *  every existing caller with no explicit signal at all. */
+    autoBackgroundOnTimeout?: boolean;
+    /** Append the per-read content-safety reminder after a successful text read (the ~50-token
+     *  `<system-reminder>` the Read tool adds to a text body — the plain-text and notebook read paths;
+     *  PDF text extraction has its own result builder and has never carried the reminder, so this switch
+     *  does not govern it). Default TRUE, and an omitted field keeps
+     *  that default: a BYOM engine cannot assume its serving model carries that mitigation internally, and
+     *  the reminder only works because it sits next to the bytes it is about — not in a system prompt
+     *  hundreds of turns back.
+     *
+     *  Pass `false` to state that THIS deployment's serving model does carry it, and stop paying the
+     *  reminder's tokens on every text read for advice the model already applies. Absent and `false` are
+     *  deliberately different decisions: absent means "unknown, so assume not". */
+    readCyberReminder?: boolean;
+}

package/dist/core/hands-band.js

@@ -0,0 +1 @@
+export {};