@sema-agent/core 5.19.0 → 5.21.0

package/dist/agents/suspend-guard.d.ts

@@ -1,5 +1,34 @@
 import type { TaskResult } from "../core/types.js";
+/**
+ * design/45 §11 Q6 — the **durable-suspend hard boundary** (v1). A `status:"suspended"` result is only
+ * safe to handle at the **top-level `runTask`** boundary: the orchestrators (cascade / verify / teacher /
+ * team) run their work as *nested* `runTask`s, and none of them can drive a resume from the inside. If a
+ * nested task suspends on a durable approval gate, the orchestrator must **fail fast** — not silently
+ * treat it as an ordinary failure (which would escalate/re-run side effects) and not release its pinned
+ * session (which would orphan the checkpoint). It maps `suspended → failed` + `errorCode:
+ * "unexpected.suspended"` and **passes the `checkpointToken`/`checkpointGate` straight through** (via the
+ * spread) so the top-level caller can still resume.
+ *
+ * The structural prevention is upstream — an orchestrator should run nested tasks under a **non-durable**
+ * approval policy (e.g. the verifier already forces `handsReadOnly` + headless auto-deny, DESIGN#5) so a
+ * suspension can't arise. This mapping is the defense-in-depth the council made a must-fix: "write it as
+ * a hard boundary, or a deployment wires durable-suspend into verify and produces silent errors."
+ */
 export declare const UNEXPECTED_SUSPENDED = "unexpected.suspended";
+/** design/80 D-B: the `needs_review` durable-pause family (dry-run `needs_review` AND `plan_review`) hits the
+ *  SAME nested hard boundary as `suspended` — a distinct code so a caller can tell a review pause from an approval. */
 export declare const UNEXPECTED_NEEDS_REVIEW = "unexpected.needs_review";
+/**
+ * design/80 D-B: the durable-pause hard boundary covers BOTH `suspended` (an approval gate) AND `needs_review`
+ * (a dry-run review OR a `plan_review` plan-gate). Both persist a checkpoint + PIN their session
+ * (prepare-task.ts), and a nested orchestrator can't drive their resume — so it must surface the
+ * `checkpointToken` and NOT release the pinned session (releasing it orphans the checkpoint). The `types.ts`
+ * TaskStatus doc mandates orchestrators map an unexpected `needs_review` the same hard-boundary way as `suspended`.
+ */
 export declare function isDurablePause(status: TaskResult["status"]): boolean;
+/**
+ * If `result` durably paused (suspended OR needs_review), return it mapped to a `failed` result carrying the
+ * checkpoint token; otherwise return it unchanged. The orchestrator should also **stop** (not escalate/re-run)
+ * and **not release** the session when this maps a pause — the checkpoint still references that session.
+ */
 export declare function mapNestedSuspend(result: TaskResult): TaskResult;

package/dist/agents/teacher.d.ts

@@ -1,23 +1,59 @@
 import type { Runner } from "../core/runner/runtask.js";
 import type { StrategyStore } from "../core/strategy-store.js";
 import type { ModelRef, TaskResult, TaskSpec } from "../core/types.js";
+/**
+ * Teacher mode (escalation cascade): a cheap "student" does the work; a strong "teacher" is consulted
+ * only when the student is *detectably* stuck or wrong, then withdraws.
+ *
+ * APPLICABILITY — teacher mode assumes the task has a **decidable verify signal**: escalation only fires
+ * when we can tell the student is failing (Tier 0 same-tool/same-error stuck, Tier 1 rubric verifier on
+ * the final output, or a `blocked`/`failed` terminal). It pays off when "wrong" is observable.
+ *
+ * It does NOT fit **open-ended completeness/quality judgement** — e.g. code-review "find ALL the bugs",
+ * creative quality — because there is no oracle for *completeness*: the verifier can't know how many bugs
+ * the code has or which one was missed, so a student that finds one obvious issue passes the rubric while
+ * silently missing others, and the escalation machinery idles (verified in practice: 0 escalations, the
+ * verifier becomes pure added cost). Such tasks are solved by **breadth + adversarial debate** (a `team`
+ * council), not by **depth escalation** — the two are orthogonal. See design/12 §六 for the full reasoning.
+ */
+/** Default teacher (advisor) system prompt — returns ONLY structured JSON guidance. */
 export declare const TEACHER_PROMPT = "You are an expert advisor to a less-capable \"student\" agent that got stuck.\nYou receive the task and the student's recent failed attempts. Your job is to help the student RECOVER,\nnot to do the work for it.\n\nReturn ONLY one valid JSON object (no markdown, no prose outside it):\n{\n  \"strategy\": \"<general approach for this CLASS of problem, 1-2 sentences>\",\n  \"correction\": \"<specifically what the student did wrong>\",\n  \"nextStep\": \"<one concrete action the student should take now>\",\n  \"takeover\": <true ONLY if the student is hopelessly stuck and you must do it yourself>,\n  \"confidence\": <0=low .. 3=high, how sure you are this guidance is correct>\n}\n\nBe terse. Do NOT solve the whole task unless takeover=true. If you are unsure, set confidence=0 and takeover=false.";
 export interface TeacherConfig {
+    /** Teacher model (overrides the `advisor` role). Default: resolve the `advisor` role. */
     model?: ModelRef;
+    /** Cheap helper model for the stuck-monitor and verifier. Default: the student's own model. */
     helperModel?: ModelRef;
+    /** Max escalations per run. Default 3. */
     maxEscalations?: number;
+    /** Stop escalating once cumulative teacher tokens exceed this fraction of student tokens. Default 0.4. */
     teacherSpendRatioCap?: number;
+    /** Consecutive same-tool failures before "suspected stuck". Default 3. */
     stuckThreshold?: number;
+    /** Cumulative same-tool failures that force escalation regardless of the monitor. Default 5. */
     stuckHardOverride?: number;
+    /** Second-guess a suspected stall with a cheap stuck-monitor call. Default true. */
     useStuckMonitor?: boolean;
+    /** Run a rubric verifier on a completed student output. Default true. */
     verifyOutput?: boolean;
+    /** After this many corrections fail, the teacher takes over instead of correcting again. Default 2. */
     takeoverAfter?: number;
+    /** Prompt overrides (instruction text) for the teacher, the rubric verifier, and the stuck-monitor. */
     prompts?: {
         teacher?: string;
         verifier?: string;
         monitor?: string;
     };
+    /** Per-escalation progress callback. */
     onEscalation?: (e: EscalationRecord) => void;
+    /**
+     * Decoupled escalation decision (Intent-monitor pattern, design/15). Called after a trigger fires
+     * and the cost guards pass, but before actually consulting the teacher. Return `false` to **skip**
+     * this escalation (the current — unresolved — result is returned). Default: always escalate. A
+     * throw fails open (escalates), so a broken policy can't strand the student; but a policy that
+     * always vetoes makes *you* responsible for the task ever resolving. (No internal timeout — wrap
+     * your own if the policy may hang.) Use it to plug in a separate monitor (a cheap model or rules)
+     * that decides whether escalating is worth it.
+     */
     escalationPolicy?: (info: {
         trigger: EscalationTrigger;
         attempt: number;
@@ -25,11 +61,29 @@ export interface TeacherConfig {
         recent: string[];
         verifyReason?: string;
     }) => boolean | Promise<boolean>;
+    /**
+     * Self-consistency for the rubric verifier (design/15). When ≥2, the verifier runs this many times
+     * (cheap helper model) and **majority-votes** pass/fail — less noisy than a single call, so the
+     * verify-fail escalation decision is better-calibrated. Default 1.
+     */
     verifierSamples?: number;
+    /**
+     * Optional strategy repository (design/14). When set **with `scope`**, relevant past strategies are
+     * retrieved into the student's objective before the run, and the final escalation's strategy is
+     * stored on success — so similar problems can be solved without re-consulting the teacher.
+     */
     strategyStore?: StrategyStore;
+    /** Tenant/isolation scope for `strategyStore` (REQUIRED to enable it — strategies never cross scope). */
     scope?: string;
+    /**
+     * How many strategies to retrieve. Default 3. Must be a non-negative integer, or `Infinity` for "no
+     * cap" — the store refuses anything else (ruled 2026-08-04) instead of folding it into 0, which used
+     * to make a fumbled value look identical to "this scope has no strategies".
+     */
     retrieveK?: number;
+    /** Minimum teacher confidence to store a strategy. Default 2. */
     minConfidenceToStore?: number;
+    /** Inject retrieved strategies into the objective. Default true when a store+scope are set. */
     injectStrategies?: boolean;
 }
 export type EscalationTrigger = "stuck" | "blocked" | "failed" | "verify-fail";
@@ -39,6 +93,7 @@ export interface TeacherAdvice {
     nextStep?: string;
     takeover: boolean;
     confidence: number;
+    /** Raw text when the JSON could not be parsed. */
     raw?: string;
 }
 export interface EscalationRecord {
@@ -48,13 +103,33 @@ export interface EscalationRecord {
     tookOver: boolean;
 }
 export interface TeacherRunResult extends TaskResult {
+    /** Escalations that occurred during this run (empty if the student succeeded alone). */
     escalations: EscalationRecord[];
+    /** Usage spent on the teacher (advisor), separate from the student's `stats` (which includes the
+     *  cheap helper monitor/verifier calls). `tasks` = teacher runs (escalation asks + any takeover).
+     *  `humanReview` = the HITL-gate burden of the teacher's runs (notably a takeover that hit an approval
+     *  gate) — kept here, not in the student `stats`, since it is teacher work (mirrors the cost split). */
     teacherStats: {
         tokens: number;
         tasks: number;
         costMicroUsd?: number;
+        /** REF-D16: the CANONICAL burden shape from {@link TaskResult}, not a re-typed narrowing. The entries
+         *  pushed here are the teacher runs' own `stats.humanReview.gates` verbatim, so a locally declared
+         *  3-field element (the pre-fix shape) was a type-face NARROWER than the values actually present —
+         *  a consumer reading `gates[i].toolName` (design/99 MF-24) got a type error on a field that is there. */
         humanReview?: NonNullable<TaskResult["stats"]["humanReview"]>;
     };
 }
+/** Best-effort parse of the teacher's JSON advice; on failure, keep the raw text as a low-confidence correction. */
 export declare function parseTeacherAdvice(text: string): TeacherAdvice;
+/**
+ * Run a task with a cheap "student" model that escalates to a strong "teacher" (advisor) when it gets
+ * stuck or produces a wrong answer — the escalation cascade / teacher mode (design/13).
+ *
+ * The teacher runs in an isolated session (its dialogue is discarded; only its structured JSON advice
+ * is injected back into the student's session, so the student's prefix cache survives). Triggers:
+ * Tier 0 — repeated same-tool failures (aborts the stuck run early); Tier 1 — a rubric verifier on a
+ * completed output (catches "passes but semantically wrong"). Correction-then-takeover, with hard
+ * cost guards (escalation cap, teacher-spend ratio, bounded teacher turns).
+ */
 export declare function runWithTeacher(runner: Runner, studentSpec: TaskSpec, teacher?: TeacherConfig): Promise<TeacherRunResult>;

package/dist/agents/team.d.ts

@@ -1,19 +1,38 @@
 import type { Runner } from "../core/runner/runtask.js";
 import type { McpServerSpec, ModelRef, ModelRole, TaskResult, ToolSpec } from "../core/types.js";
 export interface TeamMember {
+    /** The member's role / specialty, e.g. "安全评审" or "performance". */
     role: string;
+    /** Optional per-member model (falls back to the team default). */
     model?: ModelRef;
+    /** Optional per-member model **role** (when `model` is omitted) — for per-member cost tiering, e.g.
+     *  a "researcher" on `"subagent"` (cheap) and a "critic" on `"default"`. Default `"team"`. */
     modelRole?: ModelRole;
+    /** Optional persona / standing instructions for this member. */
     systemPrompt?: string;
+    /**
+     * Tools this member may use mid-debate to **ground or verify** a claim against the real artifacts
+     * (e.g. a read-only repo tool) instead of speculating — tool-augmented debate (the "Tool-MAD"
+     * pattern). Falls back to the team's shared {@link TeamDiscussionOptions.tools}. A member's turn
+     * becomes a full agent loop, so it is bounded by `limits` (and core's default turn cap).
+     */
     tools?: ToolSpec[];
+    /**
+     * Per-member tool allow/deny (design/38 1A), applied to this member's resolved tools (own or the
+     * team default): `allowTools` keeps only the named tools (`["*"]` = all), then `denyTools` removes.
+     * Lets a "researcher" be read-only and an "implementer" carry write tools without separate roles.
+     */
     allowTools?: string[];
     denyTools?: string[];
+    /** Task-scoped MCP servers for this member; falls back to the team's shared `mcp`. */
     mcp?: McpServerSpec[];
 }
 export interface TeamTurn {
     round: number;
     role: string;
     text: string;
+    /** True when this member turn failed (retries exhausted). Surfaced in the result for visibility,
+     *  but **excluded from every prompt** so an `[unavailable]` marker can't pollute the discussion. */
     failed?: boolean;
 }
 export type TeamEvent = {
@@ -25,7 +44,10 @@ export type TeamEvent = {
     round: number;
     role: string;
     text: string;
-} | {
+}
+/** [571]③ budget axes: the cumulative team budget was exhausted after this member's turn settled —
+ *  remaining rounds/members are skipped and the discussion goes straight to synthesis. */
+ | {
     type: "budget_stop";
     axis: "maxTokens" | "maxCostUsd";
     round: number;
@@ -37,55 +59,152 @@ export type TeamEvent = {
 };
 export interface TeamDiscussionOptions {
     runner: Runner;
+    /** Default model for members / synthesizer without their own. If omitted, members resolve the
+     *  `team` role and the synthesizer the `synthesize` role (both fall back to `default`). */
     model?: ModelRef;
+    /** The participants. */
     members: TeamMember[];
+    /** What the team is discussing / deciding. */
     topic: string;
+    /** Number of discussion rounds before synthesis. Default 2. */
     rounds?: number;
+    /**
+     * Cap on the shared transcript embedded in each prompt. When the running transcript exceeds
+     * this many estimated tokens, the oldest statements are summarized into a running summary
+     * (keeping prompts bounded over many rounds). Omit to disable.
+     */
     maxTranscriptTokens?: number;
+    /**
+     * Default tools for members that don't declare their own — e.g. a read-only repo tool so the
+     * debate can **verify claims against the real artifacts** rather than argue over unseen code.
+     * Members without tools simply reason over the shared transcript (the convergence layer).
+     */
     tools?: ToolSpec[];
+    /** Default MCP servers for members without their own. */
     mcp?: McpServerSpec[];
+    /**
+     * Who synthesizes the conclusion (default: a neutral facilitator on the default model). The
+     * synthesizer may carry its own `tools`/`mcp` to spot-check a disputed point before deciding; by
+     * default it has none (it converges over the transcript, it doesn't re-explore).
+     */
     synthesizer?: {
         role?: string;
         model?: ModelRef;
         modelRole?: ModelRole;
         systemPrompt?: string;
+        /** Tools specific to the synthesizer; does NOT fall back to the team-level `opts.tools`. */
         tools?: ToolSpec[];
+        /** Per-agent tool allow/deny (design/38 1A), applied to the synthesizer's `tools`. */
         allowTools?: string[];
         denyTools?: string[];
         mcp?: McpServerSpec[];
     };
+    /** Progress callback. */
     onEvent?: (e: TeamEvent) => void;
+    /**
+     * `maxWalltimeMs`/`maxTurns` are PER-RUN caps forwarded to every member/summary/synthesizer run.
+     *
+     * `maxTokens`/`maxCostUsd` ([571]③, CollabTemplate.budget mid-flight enforcement) are CUMULATIVE
+     * team budgets over member + summary + synthesizer spend (nested/delegated spend included, same
+     * coordinate as the `stats` totals). Enforcement is checked after each member turn settles and is
+     * booked — the crossing member is never killed in flight — and once a budget is exhausted
+     * (running total ≥ budget) no further member turn or round is dispatched. The transcript produced
+     * so far still goes through the NORMAL synthesis close-out (money already spent must yield a
+     * conclusion), so the synthesizer always runs; its spend is booked but not gated. Attribution
+     * lands in {@link TeamResult.budgetStop} plus a `budget_stop` event. `maxCostUsd` is compared in
+     * integer micro-USD (the engine's `stats.costMicroUsd` coordinate — no float equality); runs that
+     * report no cost (no `model.cost`/pricing) book 0 toward it. Both optional — omitted ⇒ prior
+     * behavior byte-for-byte. The budget axes are NOT forwarded to the nested member specs (a
+     * member's own per-task budget is `TaskSpec.maxTokens`/`maxCostUsd`, a different contract).
+     */
     limits?: {
         maxWalltimeMs?: number;
         maxTurns?: number;
         maxTokens?: number;
         maxCostUsd?: number;
     };
+    /**
+     * External cancellation. When it aborts, in-flight member/synthesizer/summary runs are cancelled
+     * (each member turn is a nested `runTask` given this signal) — so a team abort cascades to members
+     * instead of each running to its own `timeoutSec`. Pass a parent tool's `ToolExecuteContext.signal`.
+     */
     signal?: AbortSignal;
+    /**
+     * Authenticated end-user {@link TaskSpec.principal} (design/62) propagated to every member / summarizer /
+     * synthesizer run, so their MCP tools carry the per-user identity. The orchestrator sets it from the trusted
+     * task context (a team is a control-plane composition, so it is set here rather than auto-inherited).
+     */
     principal?: string;
 }
 export interface TeamResult {
+    /**
+     * design/80 D-G data contract: the UNIFORM orchestrator-outcome projection. `team` was the only
+     * orchestrator exit whose result didn't expose `status`/`errorCode`/`result` (cascade/teacher/verify
+     * all `extends TaskResult`), forcing aggregators onto a special-case code path. These three projection
+     * fields close that gap so a consumer can read the SAME failure-class fields off every orchestrator exit
+     * (e.g. `errorClassOf(r.errorCode)`).
+     *
+     * This is a PROJECTION, not `extends TaskResult`: a team is a multi-member discussion with **no single**
+     * `taskId`/`sessionId`/`stats` shape (its `stats` is `{tokens,turns}` only, and the rich per-task
+     * `costMicroUsd`/`nested`/`humanReview` lines have no team-level meaning), so forcing those required
+     * TaskResult fields would invent semantically-wrong values. We project ONLY the three fields aggregators
+     * read. All are purely ADDITIVE — existing consumers (`conclusion`/`conclusionValid`/`transcript`/`stats`)
+     * are untouched.
+     *
+     * `status` is `"completed"` on a valid synthesis, `"failed"` when synthesis failed or a member durably
+     * paused; `result` mirrors `conclusion`; `errorCode` is set only on the durable-pause exit
+     * (`unexpected.suspended` / `unexpected.needs_review`, the same hard-boundary codes the other
+     * orchestrators use via {@link mapNestedSuspend}).
+     */
     status: "completed" | "failed";
+    /** Mirrors {@link conclusion} — the TaskResult-shaped `result` accessor for uniform aggregation. */
     result: string;
+    /** The failure CLASS code (foldable with `errorClassOf`); set only when a member durably paused
+     *  (`unexpected.suspended` / `unexpected.needs_review`). Undefined on a normal completion/synthesis fail. */
     errorCode?: string;
     conclusion: string;
+    /** False when the synthesizer failed and `conclusion` is an `[unavailable…]` marker, not a real
+     *  conclusion — so callers can tell a junk conclusion from a legitimate one. */
     conclusionValid: boolean;
     transcript: TeamTurn[];
+    /** `costMicroUsd` ([571]③): cumulative team LLM spend in integer micro-USD (member + summary +
+     *  synthesizer, nested included) — the same engine coordinate as `TaskResult.stats.costMicroUsd`.
+     *  Always set (0 when no run reported cost); optional only for type-level back-compat. */
     stats: {
         tokens: number;
         turns: number;
         costMicroUsd?: number;
     };
+    /**
+     * [571]③ budget-stop attribution: set when a cumulative budget axis was exhausted and the
+     * discussion stopped dispatching further members/rounds early. `round`/`role`/`memberIndex`
+     * identify the LAST member turn that ran (the one whose settled totals crossed the budget);
+     * everything scheduled after it was skipped and the transcript went straight to synthesis.
+     * NOT set when the budget was only crossed by the final scheduled member turn (nothing was
+     * skipped) or by the synthesizer itself — compare `stats` against the budget for that readout.
+     */
     budgetStop?: {
         axis: "maxTokens" | "maxCostUsd";
         round: number;
         role: string;
         memberIndex: number;
     };
+    /** Number of member/synth turns that failed even after a retry (surfaced, not silent). */
     failures: number;
+    /** How many times the shared transcript was summarized to stay under maxTranscriptTokens. */
     transcriptCompactions: number;
+    /** design/80 D-B (codex review): set when a member durably PAUSED (suspended/needs_review) on a HITL gate —
+     *  the discussion STOPS (no synthesis on a half-done team) and surfaces the resume capability so the caller
+     *  can resume the paused member via the token, then re-run. `conclusionValid` is false in this case. */
     durablePause?: boolean;
     checkpointToken?: TaskResult["checkpointToken"];
     checkpointGate?: TaskResult["checkpointGate"];
 }
+/**
+ * Run a multi-round team discussion across several role-specialized agents, then synthesize a conclusion.
+ *
+ * Each member is shown the shared transcript (quoted as data) plus an explicit instruction block stating
+ * the discussion context, its role, and who else is present. Members are stateless per round (the shared
+ * transcript carries continuity), which keeps the orchestration simple and isolated.
+ */
 export declare function runTeamDiscussion(opts: TeamDiscussionOptions): Promise<TeamResult>;

package/dist/agents/tool-filter.d.ts

@@ -1,3 +1,37 @@
 import type { ToolSpec } from "../core/types.js";
+/**
+ * Per-agent tool allow/deny (design/38 1A). Statically narrows a tool POOL to the subset a delegated
+ * sub-agent / team member may use — assembly-time filtering (the tool simply never appears in the
+ * child's `tools[]`), distinct from design/37's execution-time policy interception.
+ *
+ * Resolution order (council finding 6): `pool → ∩ allowTools → − denyTools`.
+ *  - `allowTools` undefined OR contains `"*"` → start from the whole pool; otherwise keep only the named
+ *    tools (an explicit allowlist; `[]` means "no work tools", which is intentional, not a mistake).
+ *  - `denyTools` then removes named tools from whatever remains (a denied tool always loses).
+ *
+ * Allowlist is the security-recommended shape (finding 5): a denylist-only config silently exposes any
+ * newly-added sensitive tool to every agent. Names not present in the pool are ignored (no error) — an
+ * allow/deny list is a filter over what's available, not an assertion that those tools exist.
+ *
+ * [901] anchor ruling (dual-leg verified, adversarially reviewed): this spawn-time item-level filter IS
+ * the upstream shape for allow entries — CC's resolveAgentTools partitions unknown names into an
+ * `invalidTools` bucket nobody consumes at runtime (88 readable source), and a live 2.1.207 probe shows
+ * the agent stays listed/delegable with the unknown item silently dropped, zero warnings. The [876]
+ * "rejected at startup" posture this replaced had no verbatim anchor and did not survive verification.
+ * The asymmetric prepare-time fail-loud for `TaskSpec.agents` DENY entries is a deliberate sema
+ * extension (no upstream deny-list exists): an allow-typo silently narrows (safe direction), a
+ * deny-typo silently widens (unacceptable) — each face follows its own failure direction.
+ *
+ * Note: `"*"` in `allowTools` is the "allow all" sentinel, so a tool literally NAMED `"*"` cannot be
+ * the sole allowed tool via this path (tool names are conventionally identifiers, so this is moot).
+ */
+/**
+ * Membership check for ONE tool name under the same allow/deny semantics as {@link resolveToolSubset}
+ * (canonicalized both sides; `"*"` allow sentinel; deny wins). Used by the delegation tool to decide
+ * whether a chosen agent DEFINITION may re-delegate: a per-agent allow/deny that excludes the delegation
+ * tool's own name suppresses the nested delegation tool (CC 2.1.198 parity — Explore/Plan
+ * `disallowedTools` include Agent, pretty.js:409189/486948; CC filters the Agent tool like any other).
+ * The TOOL-level allow/deny deliberately keeps its old semantics (delegation governed by `maxDepth`).
+ */
 export declare function toolNameAllowed(name: string, allowTools?: ReadonlyArray<string>, denyTools?: ReadonlyArray<string>): boolean;
 export declare function resolveToolSubset(pool: ReadonlyArray<ToolSpec>, allowTools?: ReadonlyArray<string>, denyTools?: ReadonlyArray<string>): ToolSpec[];