@sema-agent/core 5.20.0 → 5.21.0

package/dist/core/task-notification.d.ts

@@ -1,79 +1,281 @@
+/** design/135 G2: `"event"` is the ONE non-terminal member — a Monitor batch notification (new stdout
+ *  lines from a still-running watch). Everything else is a terminal completion notification. */
 export type TaskNotificationStatus = "completed" | "failed" | "killed" | "cancelled" | "event";
 export type SystemInjectionPriority = "now" | "next" | "later";
 export interface TaskNotificationPayload {
     task_id: string;
+    /** design/144 §2: `"external"` is CORE-MINTED ONLY — `TaskStream.notify()` casts it onto every
+     *  externally injected event, and the input type ({@link ExternalNotificationInput}) deliberately has
+     *  no `task_type` field, so an outside producer can never wear an internal lane's type (a forged
+     *  "background_bash completed" impersonating a real child). */
     task_type: "background_bash" | "workflow" | "background_agent" | "monitor" | "external";
     toolUseId?: string;
     status: TaskNotificationStatus;
+    /** design/135 G2 (Monitor): the batched stdout lines of ONE `status:"event"` notification (lines that
+     *  arrived within the same batch window). `result` carries the same text joined/clipped for the model;
+     *  this structured mirror is for SDK/UI consumers. */
     lines?: string[];
+    /** Per-task monotonically increasing counter. Load-bearing for dedup — {@link taskNotificationDedupKey}
+     *  folds it in, so successive notifications of the same task_id+status don't collapse into one queue
+     *  entry. Its SEMANTICS are per-task_type (design/144 §1.1):
+     *   - `monitor`: the `status:"event"` BATCH counter (design/135 G2) — one per stdout batch window;
+     *     terminal notifications omit it (one per status, as before).
+     *   - `background_agent`: the STOP-CYCLE number. First settle (spawn stop) = 1; every successful
+     *     SendMessage/resume wake bumps it, so the resumed run's settle notifies with 2, 3, … — the
+     *     stop→wake→stop second-cycle frame is no longer swallowed by the `task_id:status` dedup key.
+     *     The cycle number rides whenever it is KNOWABLE, from either carrier: the retain ledger's
+     *     `cycleSeq`, or — on a tier-3 cross-process revival / a parked resume, which deliberately carry
+     *     no retain entry — the durable row's own `seq`. ABSENT only when neither exists (retain OFF on a
+     *     store-less spawn, an expired ledger with no durable row, the fork lane): the cycle count is not
+     *     knowable there, and an honest downgrade to the old single-cycle key beats a forged period
+     *     number. So `seq` present does NOT imply a retain entry exists.
+     *   - `external`: caller-supplied verbatim ({@link ExternalNotificationInput.seq}) — the injector's
+     *     own dedup discriminator across same-task_id+status events.
+     *  Consumers (server inbox fold / shell render) key `taskId:status[:seq]` — a frame WITHOUT seq keeps
+     *  the old two-part key (single-cycle semantics), by contract. */
     seq?: number;
+    /** design/144 §2 (external lane only): WHO sent this event — a deployment-provided attribution label
+     *  (e.g. a webhook origin). UNTRUSTED: rendered into the `<task-notification … from="…">` header via
+     *  `inlineUntrusted` + attribute-escaping, never as authority. Absent on every internal lane. */
     source?: string;
+    /** design/134 §3.3: only on `status:"killed"` — who stopped it. MIRROR of task-registry `StopSource`
+     *  (the single source; inlined here to avoid an import cycle — task-registry imports this module;
+     *  third mirror: types.ts `BackgroundChildEvent.stoppedBy` — keep all three in sync). OPEN ENUM:
+     *  consumers must tolerate unknown values (a future "timeout" etc. is not breaking) and fall back
+     *  to default copy. */
     stoppedBy?: "user" | "parent" | "system" | (string & {});
     summary: string;
+    /** RB-386① ([2090]) — the failure reason DIGEST on a `status:"failed"` terminal notification
+     *  (background_agent lanes): the same bounded text the settle stored as the registry row's `error`
+     *  (the completed frame carries the full `result`; the failed frame used to carry NOTHING machine-
+     *  readable — consumers had to parse the summary prose, which pre-fix didn't even include the
+     *  reason). UNTRUSTED (child/provider-influenceable text) — render-fence before display. Absent on
+     *  every non-failed frame and on pre-RB-386 producers. */
     error?: string;
+    /** RB-386① — the machine-readable failure code beside {@link error}, when one is known: the child's
+     *  `TaskResult.errorCode` taxonomy (brain `[code]` prefixes via extractErrorCode, `limit.*`,
+     *  `budget.*`, …). Engine-minted, never model text. Absent when the failure carried no code. */
     errorCode?: string;
+    /** Structured exit code of a background command's terminal notification (bash lane): the process
+     *  exited on its own with this code. Lets consumers branch on success/failure without parsing the
+     *  summary wording. Absent when the process never exited by itself (killed / spawn-failed lanes). */
     exitCode?: number;
     result?: string;
+    /** Present (`true`) only on a `status:"killed"` notification that carries a `result` slice: the text
+     *  was produced BEFORE the stop won the status race, so it is the child's partial work — the same
+     *  semantics as the poll face's `partial_result` flag (one meaning across both surfaces). Absent on
+     *  every other notification (a completed result is never flagged). */
     partial?: boolean;
     output_file?: string;
     usage?: unknown;
+    /** [1409] CC `<diagnostics>` parity: ENGINE-MINTED teaching text for the "result is empty/unexpected —
+     *  now what" moment (per-agent read route / journal coordinate / resume command). Producers must mint it
+     *  from engine values only (ids, store locators) — never from model-influenceable text. */
     diagnostics?: string;
+    /** The child run's SESSION id, when known. A shell keys its fleet/footer rows by its own
+     *  local ids; the a* task_id alone can be unmappable on its side — sessionId is the stable cross-system
+     *  anchor (the same handle TaskResult.sessionId / fleet rows carry). Optional: bash lane has none. */
     sessionId?: string;
+    /** Residual lane A — the child's last ≤10 completed tool steps, so the parent can write a precise resume
+     *  prompt for a killed/stopped child without reading the transcript. Rendered as a compact block.
+     *  Background-agent lane only; bounded upstream. */
     recentSteps?: import("../agents/subagent-steps.js").SubagentStep[];
+    /** Residual lane D (core half) — files the child mutated with edit counts. Background-agent lane only. */
     editedFiles?: import("../agents/subagent-steps.js").SubagentEditedFile[];
+    /** Residual lane E — `true` when the child can be revived via SendMessage (retained + not user-stopped).
+     *  Lets the parent decide continue-vs-restart without trial-and-error. Background-agent lane only. */
     resumable?: boolean;
+    /** P1-3(黑板 [1920]/[1921]/[1924]/[1925], cli/server 商定项) — a cross-channel correlation key for
+     *  ONE completion event. The same task's completion fans out across several independent read faces
+     *  today (this live notification frame, a durable inbox entry, and the `TaskOutput` poll projection)
+     *  — a consumer previously had to reconstruct "are these the same completion?" from weaker signals
+     *  (task_id + status + timing). Minted ONCE per completion, fill-once (first writer wins), on the
+     *  same task-registry handle/record every read face serves from — see
+     *  {@link "./task-registry.js".UnifiedTaskOutput.completionId} for the shared contract (open-shape
+     *  `string`, absent until terminal settle, absent on a pre-P1-3 core build). Deliberately ABSENT on
+     *  the `"external"` lane (`TaskStream.notify()`) — that lane has its own caller-supplied `seq`
+     *  correlation key ([1837]/[1925] cross-repo confirmed posture) and no registry-side settle point to
+     *  mint this from; core-minting one there would create two competing correlation keys on the same
+     *  frame. */
     completionId?: string;
+    /** design/176 — the peer-message marker + hop-chain carrier, present ONLY on payloads minted by
+     *  the SendMessage delivery legs (the engine's single peer-carrier producer). Three uses: it
+     *  carries the forwarding chain (engine-read side channel — never rendered to the model face),
+     *  it marks the payload as peer-class for the consumption-boundary chain recording, and it keys
+     *  the discipline-block pairing. Deliberately NOT on {@link ExternalNotificationInput}: an
+     *  outside caller can neither mint a chain nor wear the peer class. */
     peer?: {
         hopChain: string[];
     };
 }
+/**
+ * design/144 §2 — the caller-facing input of `TaskStream.notify()`: a STRUCTURED external event to inject
+ * into the running task's notification lane (same delivery machinery as background_bash/monitor/agent
+ * completions: SystemInjectionQueue dedup → steer/followUp/idle-park three-state delivery).
+ *
+ * Deliberately a SUBSET of {@link TaskNotificationPayload}: NO `task_type` (core mints `"external"` — a
+ * caller can never impersonate an internal lane) and none of the internal-lane fields (lines/stoppedBy/
+ * usage/…). Every field is treated as UNTRUSTED data on the model face (the XML renderer sanitizes) —
+ * transport, inbound authn, and idle-session durable park are the DEPLOYMENT half (design/43: no
+ * daemon/webhook semantics in core; core only takes "a structured event that already reached this
+ * process" into THIS run's injection queue).
+ */
 export interface ExternalNotificationInput {
+    /** The caller's correlation id for the event source (free-form; part of the dedup key). */
     task_id: string;
     status: TaskNotificationStatus;
     summary: string;
     result?: string;
+    /** Caller-side dedup discriminator: successive events of the same task_id+status need distinct `seq`s
+     *  or the queue's dedup key swallows the repeats (same contract as every internal lane). */
     seq?: number;
+    /** Attribution label rendered into the `from="…"` header (untrusted; sanitized). */
     source?: string;
 }
 export interface SystemInjection<TPayload = unknown> {
     kind: "task_notification";
+    /** design/116 §7, re-anchored 2026-08-05 (CC 2.1.221): EVERY priority delivers at the NEXT turn
+     *  boundary via harness.steer(), mid-work included — CC's queued task-notification inputs are
+     *  unconditionally deliverable at the boundary, and the old later→followUp mapping (deliver only
+     *  when the agent would otherwise stop) starved busy models of the very completion they were told
+     *  not to poll for. Delivery is ARRIVAL order (consecutive frames batch); `priority` affects only the park/uplink
+     *  path. A delivery that races the agent going idle parks on PendingSessionNotifications for the
+     *  session's next run. `drain()` serves that parked lane. */
     priority: SystemInjectionPriority;
     dedupKey: string;
     payload: TPayload;
+    /** S2b codex R2-F2' — resolved with the ACTUAL injection outcome by the runner's subscribe
+     *  listener: "queued" once the boundary steer accepted, "parked" when the idle tail-race (or the
+     *  engine-note backlog cap) rejected and the payload was pended per session. Absent =
+     *  fire-and-forget producer (no receipt to honor). */
     onDisposition?: (d: "queued" | "parked") => void;
 }
 export declare function taskNotificationDedupKey(n: Pick<TaskNotificationPayload, "task_id" | "task_type" | "status" | "seq">): string;
+/**
+ * RB-142 — the lane-scoped identity of a task, extracted from {@link taskNotificationDedupKey} so every
+ * place that treats "same task" as one bucket applies the SAME lane rule.
+ *
+ * The dedup key had the lane segment from the start; three other sites did not — the pending store's
+ * per-task quota, its eviction victim predicate, and its drop ledger key were all the bare `task_id`.
+ * The lane segment exists because `task_id` is caller-supplied free-form on the external lane, so an
+ * external injector that picks a real child's id landed in the child's quota, evicted the child's frames,
+ * and merged into one ledger row carrying ONE `taskType` — the exact impersonation direction this
+ * module's header says cannot happen. One rule, one helper, one place to change it.
+ */
 export declare function taskNotificationLaneKey(n: Pick<TaskNotificationPayload, "task_id" | "task_type">): string;
+/** Attribute-context escape for the external `from="…"` header: the value already went through
+ *  `inlineUntrusted` (one-line, capped, sanitized), but a `"` would still close the attribute — escape
+ *  the XML structural chars so the header can never be broken out of. Exported for the design/171
+ *  human-input projection, which renders the same kind of untrusted attribution label — one escape
+ *  implementation, never a per-renderer copy. */
 export declare function attrEscape(value: string): string;
+/** Max rendered length of an untrusted attribution label (the external `from="…"` header and the
+ *  design/171 speaker envelope share it — same concern: a display label, not a payload). */
 export declare const EXTERNAL_SOURCE_MAX = 120;
 export declare function renderTaskNotificationXml(n: TaskNotificationPayload): string;
+/**
+ * The BETWEEN-TURNS pending lane. A task notification born while NO turn is
+ * live (the run's notification lane is torn down, or the harness rejected the injection because the agent
+ * was already idle) used to be silently unreachable: the Monitor main use-case (long-watch events between
+ * turns) and the stoppedBy notifications (a killed-evicted child whose registry row is already gone)
+ * both land exactly in that window. This store parks them PER SESSION; the session's next run drains it at
+ * start and rides the payloads down the SAME notification lane (steer at the next turn boundary), so
+ * in-turn and between-turn events keep one shape.
+ *
+ * Bounds (1.254 F4 家族纪律): per-task cap + per-session cap + session-count cap, oldest dropped first —
+ * preferring NON-terminal victims (an exit/killed terminal is the single most load-bearing notification of
+ * a watch and dies only when nothing else can) — and every drop is counted per task and DISCLOSED on
+ * delivery ({@link discloseDroppedPending}), never silent.
+ *
+ * Dedup (design/144 X4): `pend` drops a payload whose {@link taskNotificationDedupKey} is already parked
+ * for the session — the ended-run park leg honors the same key contract as the live queue's enqueue
+ * (before this, a repeat external notify() after the run ended would deliver DUPLICATE frames on the next
+ * run's drain, violating the notify contract). HONEST WINDOW LIMIT: the dedup set lives and dies with one
+ * session's parked batch — it does NOT span the live queue (a key delivered live and then pended after
+ * teardown is a fresh domain) and it resets at `drain` (a repeat arriving after the next run drained is
+ * deliverable again — same posture as the queue, whose drain also releases keys). A bound-evicted victim
+ * releases its key (mirror of SystemInjectionQueue cap eviction), so the set is bounded by the item caps.
+ *
+ * NOT checkpointed (durable-resume ruling, recorded): the registry itself (`defaultTaskRegistry`) is
+ * process-local — a cross-process durable resume cannot reconnect a monitor's watcher/process anyway, so a
+ * pending queue that outlives the process would advertise events for handles that no longer exist. Same-
+ * process resume legs share this store via the Runner and drain normally.
+ */
 export declare const MAX_PENDING_EVENTS_PER_TASK = 50;
 export declare const MAX_PENDING_EVENTS_PER_SESSION = 200;
 export declare const MAX_PENDING_SESSIONS = 100;
+/**
+ * RB-375 A2 (ruled 2026-08-03) — is this frame the TERMINAL of a delegated background agent?
+ *
+ * It is the one notification class whose audience is the whole DELEGATION TREE rather than the
+ * session that produced it: the frame answers "the work you delegated is over", and the party that
+ * asked for the work is the conversation at the root of the tree, not necessarily the run that
+ * happened to issue the spawn call. Every other class (a shell completion, a Monitor batch, a
+ * SendMessage delivery, an external `notify()` event) is addressed to THIS session and stays there.
+ *
+ * Reuses {@link TERMINAL_STATUSES} — the same terminal-vs-event rule the pending store's eviction
+ * preference applies, so "terminal" can never mean two things in this module.
+ */
 export declare function isDelegatedAgentTerminal(n: Pick<TaskNotificationPayload, "task_type" | "status">): boolean;
 export interface DrainedPendingNotifications {
+    /** Chronological (pend order) payloads still held when the session's next run drained. */
     items: TaskNotificationPayload[];
+    /** task_id → notifications evicted by the bounds while pending (never delivered). `taskType` remembers
+     *  the victim's lane so a survivors-none disclosure can still render an honest synthetic payload. */
+    /** RB-142: keyed by {@link taskNotificationLaneKey}, NOT the bare `task_id` — the external lane's ids are
+     *  caller-supplied, so one bare-id row could cover two lanes and name only one of their types. `taskId`
+     *  carries the victim's real id back out (the lane key is process-internal and must never be rendered). */
     dropped: Map<string, {
         count: number;
         taskType: TaskNotificationPayload["task_type"];
         taskId: string;
     }>;
+    /**
+     * RB-114 (2026-07-25, defect probe): notifications lost when this whole SESSION was evicted by the
+     * session-count cap, kept OUT of `dropped`. RB-91 folded them in under a `"(evicted-session)"` string
+     * key, which put a session-level fact into a per-task ledger and broke twice for it: the key could
+     * collide with a real, free-form external `task_id` (merging two unrelated counts and mislabelling the
+     * lane — design/144 X1 already ruled that the external lane needs its own key space), and the
+     * survivors-none renderer told the model to call `TaskOutput("(evicted-session)")`, an instruction with
+     * nothing behind it. The count is a session fact; it now has a session field.
+     */
     droppedWholeSession?: number;
 }
 export declare class PendingSessionNotifications {
     private readonly sessions;
+    /** Whole sessions evicted by {@link MAX_PENDING_SESSIONS} (their pendings were never delivered). */
     droppedSessions: number;
+    /**
+     * RB-91 (2026-07-25, red probe): a TOMBSTONE per whole-session eviction, so that session's next drain
+     * can still say what it lost. The two item-level caps disclose their drops per task (they mutate a
+     * surviving session's `dropped` map), but the session-count cap deleted the whole record and only
+     * bumped a global, unattributed counter — from the evicted session's point of view its next drain
+     * returned `undefined`, which is exactly what "nothing ever happened" looks like. The class contract
+     * says every drop is disclosed on delivery and never silent; this arm was the exception.
+     * Bounded like the sessions map itself (a tombstone is two numbers and a lane tag).
+     */
     private readonly evictedSessions;
+    /** RB-143: whole-session losses whose tombstone was itself evicted — the count survives, the attribution
+     *  does not. Surfaced on the next session-level disclosure so it is never simply forgotten. */
     private unattributedDrops;
     pend(sessionId: string, n: TaskNotificationPayload): void;
+    /** Remove and return the session's pendings (one-shot — the next run consumes them exactly once). */
     drain(sessionId: string): DrainedPendingNotifications | undefined;
     get size(): number;
 }
+/**
+ * Delivery-side overflow disclosure: fold the per-task drop counts into the drained payloads. The first
+ * surviving payload of a task that lost events gets a `[task_id]`-prefixed disclosure line prepended to its
+ * summary (backgroundTasks 同规: the id keeps the loss addressable via TaskOutput). A task whose EVERY
+ * pending item was evicted still gets one honest synthetic `event` payload saying so — a fully silent loss
+ * is never allowed.
+ */
 export declare function discloseDroppedPending(drained: DrainedPendingNotifications): TaskNotificationPayload[];
 export declare class SystemInjectionQueue<TPayload = TaskNotificationPayload> {
     private readonly queues;
     private readonly dedup;
     private readonly listeners;
+    /** F4 observability: how many queued items were evicted by the retention cap (never delivered). */
     droppedOldest: number;
     enqueue(item: SystemInjection<TPayload>): boolean;
     drain(priority?: SystemInjectionPriority): Array<SystemInjection<TPayload>>;

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

@@ -1,26 +1,79 @@
+/**
+ * design/73 §1 v1 — **TaskOutcome 反馈账本(薄 seam)**。core 的唯一职责 = 在有客观 oracle 的终态发射
+ * 一条结构化事实;聚合(keyed by `(taskSignature, model)`)、路由/预算策略、bandit 全在 service 侧
+ * ledger(§7.2)。seam 形态照 `RunnerDeps.tracer` / `RunnerDeps.onError` 先例:fire-and-forget、
+ * swallow-guarded(throwing sink 绝不影响 run)。
+ *
+ * 🔴 红线(design/73 §1.2/§4 + makereal-corpus §4 交叉验证裁决,逐条钉死):
+ *  ① **只发 mechanical tier** — `verificationKind` 被类型钉成字面量 `"mechanical"`,且
+ *    {@link emitTaskOutcome} 对运行时混入的非 mechanical 值 FAIL-CLOSED 丢弃。llm_assisted /
+ *    self-report(reviewer 判定、supervisor approval、模型自报)绝不进 v1 —— 那是 service 侧
+ *    仪表盘 metadata,绝不等权驱动变更(绝不自评闭环)。
+ *  ② **必须带 `oracleHadRedRun`** — "同一个机械 oracle 曾观察到 RED" 是最强 grounded 信号
+ *    (防 vacuous oracle:一个从来没红过的 oracle 证明不了任何东西)。
+ *  ③ **单发射点** — `runGoal` 终态一次(goal 模式的 `doneCheck` = 天然机械 oracle)+ 有真 oracle 的
+ *    harness/service 显式调 {@link emitTaskOutcome}。替掉散落 console.log 的污染源(console 刮出来的
+ *    数字 = 内存叙事,零 durable 产物)。
+ *  ④ **core 只发事实** — 本模块无任何聚合/持久化/策略;n=1-per-signature 阶段消费侧只准做只读
+ *    ledger/仪表盘,自动策略变更 flag-off(§7.4 回测门)。
+ */
 import type { RunnerDeps } from "./types.js";
+/**
+ * One mechanical-tier outcome fact for a finished task/goal run. Real-data shape reference: the nightly
+ * matrix ledger (60-row summary.jsonl) — `oracle` stays free-form on purpose (each harness has its own
+ * mechanical fields: behaviorPass/typesClean/…) with `green` as the single required derived bit.
+ */
 export interface TaskOutcome {
+    /** Aggregation key — stable across runs of the "same task" (service aggregates by `(taskSignature, model)`). */
     taskSignature: string;
+    /** This run's identity (the taskId of the final task leg, or the goal's sessionId). */
     runId: string;
+    /** Effective model id that served the run (resolved `Model.id`), when known. */
     model?: string;
+    /** 🔴 Red line ①: core emits ONLY the mechanical tier. Literal type — no other value exists in v1. */
     verificationKind: "mechanical";
+    /** Terminal status of the run (e.g. a `GoalStatus` or `TaskStatus` — "achieved"/"completed"/"failed"/…). */
     status: string;
+    /** Machine-readable failure code when the terminal status carried one. */
     errorCode?: string;
+    /**
+     * The mechanical oracle's result — free-form per harness (pass/fail counts, typesClean, exit codes, …)
+     * but ALWAYS with the derived `green` bit: did the objective oracle pass at the end?
+     */
     oracle: {
         green: boolean;
         [k: string]: unknown;
     };
+    /**
+     * 🔴 Red line ②: did the SAME mechanical oracle observe a RED (failing) state during this run — the
+     * strongest grounded signal (an oracle that never ran red proves nothing about its own substance).
+     * In `runGoal` this is derived: any `doneCheck` verdict with `done:false` before the terminal state.
+     */
     oracleHadRedRun: boolean;
+    /** Raw inputs a service-side signature derivation can use (§7.3) — optional in v1. */
     signatureInputs?: {
         toolset?: string[];
         objectiveHash?: string;
         targetLang?: string;
         moduleCount?: number;
     };
+    /** Total tokens spent (own + nested). */
     tokens?: number;
+    /** Total cost in integer micro-USD (own + nested). */
     costMicroUsd?: number;
+    /** Total model turns (own + nested). */
     turns?: number;
+    /** Wall-clock duration of the whole run, ms. */
     wallMs?: number;
+    /** Harness-specific extras (cacheHitRate, compactions, chaos lane, …). Facts only — never judgments. */
     extra?: Record<string, unknown>;
 }
+/**
+ * Fire the deployment's `onTaskOutcome` sink with one outcome fact — the SINGLE emission chokepoint
+ * (red line ③). Fire-and-forget + swallow-guarded (tracer/onError posture): a throwing sink never
+ * affects the caller. FAIL-CLOSED on tier: anything not `verificationKind:"mechanical"` (runtime cast
+ * around the literal type) is dropped, never forwarded (red line ①). Exported for harnesses/services
+ * that have a REAL mechanical oracle outside goal mode; plain `runTask` never auto-emits (no objective
+ * oracle → nothing to ground a fact in — we do not guess).
+ */
 export declare function emitTaskOutcome(deps: Pick<RunnerDeps, "onTaskOutcome">, outcome: TaskOutcome): void;