@sema-agent/core 5.19.0 → 5.21.0

package/dist/orchestration/workflow-types.d.ts

@@ -1,15 +1,29 @@
 import type { TaskResult, TaskStatus, ToolActivity } from "../core/types.js";
 export type WorkflowRunStatus = "running" | "completed" | "failed";
+/** Status of one phase / agent-run within a workflow. */
 export type WorkflowItemStatus = "running" | "completed" | "failed";
 export interface WorkflowPhase {
     title: string;
+    /** F7/B7 (CC pretty.js:446478): a phase PRE-REGISTERED from `meta.phases` starts as `"pending"` — the plan
+     *  is visible before execution. The first `phase()` call with the SAME title adopts it (→ running). A phase
+     *  still pending at the run's terminal was planned but never reached (left pending, honestly). */
     status: WorkflowItemStatus | "pending";
+    /** meta.phases[].detail, when pre-registered. */
     detail?: string;
+    /** meta.phases[].model (CC card :448042) — display-only phase model note. */
     model?: string;
+    /** Number of agents grouped under this phase whose record ended `"failed"` (every non-`completed`
+     *  terminal — failed/blocked/timeout — folds to that record status). Stamped when the phase settles,
+     *  only when > 0 (absent = no failures). ADDITIVE observation field: a phase whose BODY returned
+     *  normally stays `"completed"` even when agents inside it failed — the script owns control flow —
+     *  but the partial failure must be visible on the phase box, not only per agent row. */
     agentFailures?: number;
+    /** For a pre-registered phase this is the ADOPTION time (0 while pending — it hasn't started). */
     startedAt: number;
     endedAt?: number;
 }
+/** design/97 CORE-3: one nested `ctx.workflow` sub-group. The tree is reconstructed from `parentGroupId`
+ *  (undefined = a child of the root) + the agents/phases that carry this `groupId`. */
 export interface WorkflowGroup {
     groupId: string;
     parentGroupId?: string;
@@ -18,33 +32,80 @@ export interface WorkflowGroup {
     endedAt?: number;
 }
 export interface WorkflowAgentRun {
+    /** Display label (caller-supplied via opts.label, else an auto `agent-N`). */
     label: string;
+    /** design/97 CORE-1: the STABLE deterministic identity of this `ctx.agent` call ({@link workflowAgentCallKey}
+     *  = `ordinal:specIdentityHash`). The resume journal (CORE-7) keys a cached result on it. */
     callKey: string;
+    /** design/97 CORE-1: the nesting GROUP this agent ran under — `undefined` = top-level (root); a nested
+     *  `ctx.workflow` (CORE-3) sets a sub-group id so the observe/UI can render the agent tree. */
     groupId?: string;
+    /** The phase this agent ran under, if any (opts.phase, else the enclosing `phase()` title). */
     phase?: string;
+    /** design/97 CORE-8 (①): the model display label (`spec.model` id/name) — for a CC-style "Opus 4.8" per-agent row. */
     model?: string;
+    /** design/97 CORE-4 (#5 observability): what the worker was ASKED — its objective (+ systemPrompt), redacted
+     *  + size-bounded. NOT fenced at rest; a consumer feeding it to an LLM must fence (untrustedEgressForHuman). */
     prompt?: string;
+    /** design/97 CORE-4 (#5 observability): the worker's final OUTPUT (structuredOutput or result text), redacted
+     *  + size-bounded. Same fencing caveat as `prompt`. Set on a completed/returned run (absent on a thrown one). */
     output?: string;
+    /** design/97 CORE-8 (②): total tool calls the worker made (from `TaskResult.stats.toolCalls`). */
     toolCalls?: number;
+    /** design/97 CORE-8 (③): the worker's tool-call ACTIVITY — bounded to the LAST {@link MAX_ACTIVITY} beats (a
+     *  CC-style "last N of M tool calls"; M is `toolCalls`). Structural only (name/phase/ids), no args/output. */
     activity?: ToolActivity[];
     status: WorkflowItemStatus;
+    /** [1238](B) — the failed task's machine code + bounded human message, surfaced ON THE RECORD
+     *  (runs.jsonl / monitor rows / agent_end) so a dead agent is diagnosable without re-running.
+     *  Previously only the script's return value carried them and every display face showed "". */
     errorCode?: string;
     errorMessage?: string;
+    /** The underlying task's terminal {@link TaskStatus} (a non-`completed` status maps to `failed` above). */
     taskStatus?: TaskStatus;
+    /** design/99 MF-W (design-review DoR ⑥): when this agent was ENQUEUED (the `ctx.agent`/`ctx.agentStream` call,
+     *  before it waited on the concurrency semaphore). Always set. A record with `queuedAt` set but `startedAt`
+     *  ABSENT is QUEUED (waiting for a slot) — `deriveAgentDisplayStatus` projects that to `"queued"`. */
     queuedAt: number;
+    /** When the agent ACTUALLY started running — set AFTER it acquired a concurrency slot (post-queue). ABSENT
+     *  while queued, or if it was aborted/the-run-finalized before it ever ran. So `durationMs` (`endedAt -
+     *  startedAt`) excludes the queue wait (the DoR fix: a queued agent no longer reports a wrong running duration). */
     startedAt?: number;
     endedAt?: number;
+    /** This agent's OWN (root) usage — nested/delegated usage rolls into the run's {@link WorkflowRunStats.nested}. */
     stats?: {
         tokens: number;
         turns: number;
         costMicroUsd?: number;
     };
+    /** design/97 CORE-7: set when this agent's result was REPLAYED from a resume journal (cached, no live runTask)
+     *  rather than freshly run. Its stats count toward `run.stats` (total work) but not `ctx.budget.spent()`. */
     replayed?: boolean;
+    /** F5/B4: total attempts this call made (set only when > 1 — stall/throttle retries happened). The record's
+     *  `stats` are the FINAL attempt's; burned retry spend rolls into `run.stats`/budget (CC semantics). */
     attempts?: number;
+    /** F5/B4: why the LAST retry happened — "stalled" (progress watchdog) or "throttled" (degraded response). */
     lastAttemptReason?: string;
+    /** design/114 — the session id of this agent's run (= its `TaskResult.sessionId`). Surfaces the conversation
+     *  handle to the observation layer so an external initiator can WARM-resume a failed/timed-out agent
+     *  (`fork(sessionId)→runTask`, or `runTask({sessionId})`) instead of a fresh re-run. An opaque id (not
+     *  content) → scope-gated via `getWorkflowRun`, no redaction needed. Absent for a stub run that minted none. */
     sessionId?: string;
+    /** RB-393① (黑板 [2107]②/[2113]) — the WORKTREE directory this agent ran in, present ONLY for an
+     *  `isolation: "worktree"` agent whose worktree the engine actually minted (reported by the runner's
+     *  workspace-observation seam and folded on while the agent is still RUNNING, so an interrupted run's
+     *  recovery path has the coordinate instead of enumerating the worktrees directory and guessing). ABSENCE
+     *  means the agent ran in the SHARED working tree — never "unknown": the shared root is deliberately not
+     *  written here, so a consumer acting on this path (diff / merge / remove, the userland half of the
+     *  isolate-only contract) can never be handed a tree it must not touch. A host path, not content → same
+     *  scope-gated, unredacted posture as {@link sessionId}. */
     worktreeDir?: string;
 }
+/**
+ * Cumulative workflow usage. `own` (top-level) and `nested` (each agent's delegated sub-agents) are kept
+ * SEPARATE — never folded — mirroring `TaskResult.stats` (R-5): a consumer adds them. Total spend =
+ * `tokens + nested.tokens`.
+ */
 export interface WorkflowRunStats {
     tokens: number;
     turns: number;
@@ -59,25 +120,72 @@ export interface WorkflowRunStats {
 export interface WorkflowRun {
     id: string;
     scope: string;
+    /** design/99 MF-W (workflow monitor header): the workflow's display name + one-line description, from the
+     *  script's `export const meta = {...}` (the run_workflow tool passes them in). Absent for a direct
+     *  `runWorkflow` call that supplies no name. */
     name?: string;
     description?: string;
+    /** design/114 #3 (service) — the HOST task id that started this workflow (the `RunWorkflow` tool's source
+     *  task). Lets a crash-recovered consumer rebuilding from `getWorkflowRun` re-associate the run with its
+     *  initiator: the live notify path carries it, but the recovery path can't otherwise recover it (it rebuilds
+     *  from the persisted `WorkflowRun`, which until now dropped it). Absent for a direct `runWorkflow` call. */
     sourceTaskId?: string;
+    /** The ORIGINATING session id, recorded like {@link sourceTaskId} so crash-recovery
+     *  rebuilds a completion payload symmetric with the live notify (which carries it since 1.208). */
     originatingSessionId?: string;
+    /** design/140 §6 1a — the MERGED effective args the script actually received (call-time args over the
+     *  registration's defaultArgs), snapshotted at RESOLVE time (parse-time discipline, design/140 §2).
+     *  OBSERVATION-ONLY (a /workflows viewer / recovery consumer reads what the run got) — never a gate input,
+     *  never re-read by the engine; a resume's identity is carried by the journal callKeys, not this field.
+     *  Absent for a direct `runWorkflow` call or an argless invocation. */
     effectiveArgs?: unknown;
     status: WorkflowRunStatus;
+    /** Number of agent-runs that ended `"failed"` (failed/blocked/timeout terminals) across the whole run.
+     *  Stamped at the run's terminal, only when > 0 (absent = every agent completed). ADDITIVE observation
+     *  field: a run whose script body returned normally is still `status: "completed"` even when agents
+     *  inside it failed (the script's return value is the source of truth) — this surfaces the
+     *  "completed, with failures" outcome WITHOUT extending {@link WorkflowRunStatus}, which is a wire
+     *  contract (store status filters, terminal checks like `isTerminalWorkflowStatus`, monitor rows all
+     *  switch on the closed enum — a new enum value would break them; an optional field cannot). */
     agentFailures?: number;
     phases: WorkflowPhase[];
     agents: WorkflowAgentRun[];
+    /** design/97 CORE-3: nested `ctx.workflow` sub-groups (the persisted group tree). Empty when the script
+     *  used no nesting. Agents/phases reference a group via their `groupId`. */
     groups: WorkflowGroup[];
     stats: WorkflowRunStats;
     startedAt: number;
     endedAt?: number;
     createdAt: number;
+    /** Optimistic-concurrency revision for the store (S1b); unset for a pure in-memory run. */
     rev?: number;
+    /** Set when `status === "failed"`: the error the script threw. */
     error?: string;
+    /** The script's RETURN VALUE, bounded + redacted at completion time (same egress
+     *  discipline as the notifier `result`), so a terminal `TaskOutput` poll can hand the
+     *  model the result instead of sending it in poll circles. Absent on failed runs and runs recorded by
+     *  older engine versions. */
     result?: string;
+    /** NH-1: the FULL return value (redacted, capped at {@link WORKFLOW_RESULT_FULL_MAX}), set ONLY
+     *  when `result` above was truncated by its display bound. Terminal poll replies inline this instead of the
+     *  truncated `result`, so the generic large-tool-result offload (design/30) persists it under a REAL
+     *  `read_tool_result` ref — previously the `…[+N chars]` tail dead-ended (no retrieval path; models tried
+     *  the runId as a ref and hit the store-miss message). Display/notify surfaces keep using `result`. */
     resultFull?: string;
+    /** P1-3(黑板 [1920]/[1921]/[1924]/[1925]) — the cross-channel completion correlation id, minted
+     *  fill-once at this run's terminal transition (see {@link "../core/task-registry.js".UnifiedTaskOutput.completionId}
+     *  for the shared cross-lane contract). Persisted alongside `status`/`endedAt` so a store round-trip
+     *  (restart / crash recovery) replays the exact same id — there is no second mint point downstream of
+     *  this field ever being set. Absent while `status === "running"`, or on a run recorded by an older
+     *  engine version. */
     completionId?: string;
+    /** RB-243 ([1937]): what this run's `resumeFromRunId` actually yielded — ADDITIVE observation (same
+     *  contract as {@link agentFailures}: never a gate input; absent on non-resume runs, on runs recorded by
+     *  older engines, and on a column-mapped store that doesn't project it). Previously a resume whose journal
+     *  loaded ZERO entries (unknown/pruned runId, cross-scope, unreadable record) re-ran everything live with
+     *  no trace that nothing replayed. `fromRunId` is charset-clamped (the raw id is LLM-controlled).
+     *  `divergedAtOrdinal`/`divergedReason` record the FIRST replay stop only; under `parallel` the ordinal is
+     *  best-effort. */
     resume?: {
         fromRunId: string;
         journalEntries: number;
@@ -85,6 +193,9 @@ export interface WorkflowRun {
         divergedAtOrdinal?: number;
         divergedReason?: string;
     };
+    /** RB-243 ([1937]): how many agent results were NOT journaled because they exceeded the per-entry size
+     *  cap ({@link MAX_JOURNAL_RESULT_BYTES}) — each skip also logs and journals a tombstone. Additive
+     *  observation; absent when 0. */
     journalSkips?: number;
 }
 export type WorkflowEvent = {
@@ -164,22 +275,58 @@ export type WorkflowEvent = {
     agentFailures?: number;
     ts: number;
 };
+/** Thrown by `ctx.agent` once the workflow's cumulative token spend reaches the budget (design/96 G#4: a
+ *  hard ceiling, typed error in v1; durable suspend is left to a future slice). */
 export declare class WorkflowBudgetExceededError extends Error {
     readonly spent: number;
     readonly total: number;
     readonly code = "workflow.budget_exceeded";
     constructor(spent: number, total: number);
 }
+/**
+ * Thrown by `runWorkflow`/`startWorkflow` when a workflow is started INSIDE another workflow — nesting is
+ * capped at ONE level (design/97 §H.1, the S8 prerequisite). A workflow's agent (a `runner.runTask` child)
+ * cannot itself start a workflow: the LLM-facing `run_workflow` tool hits this guard, and so does a
+ * trusted-dev nested `runWorkflow(...)` call. The depth is read from the TRUSTED
+ * {@link WorkflowInternals.workflowDepth} first (the cross-process channel — a worker/script cannot forge it,
+ * it is not a `TaskSpec` field) then the in-process {@link workflowDepthStore} (AsyncLocalStorage), so neither
+ * a spec field nor a tool param can defeat it (design/98 §0.1 BLOCKER3).
+ */
 export declare class WorkflowNestingError extends Error {
     readonly code = "workflow.nesting";
     constructor();
 }
+/**
+ * Thrown by `ctx.agent(spec, { schema })` (design/98 §0.2, strict mode) when the sub-agent **completed but
+ * produced no `structuredOutput`** — i.e. the model answered in PROSE, which core's `outputSchema` path
+ * permits by default (types.ts: "may still answer in prose"). A workflow script that asked for a structured
+ * result must not silently receive `undefined`; it fails loud here instead. A task that ended NON-`completed`
+ * (failed / blocked / timeout) is returned as-is (the script checks `result.status`) and never turned into
+ * this error — that path already carries its own signal.
+ */
 export declare class WorkflowAgentSchemaError extends Error {
     readonly label: string;
+    /** The agent's completed-but-prose TaskResult (when available). The prose was paid for and may still be
+     *  useful as a degraded fallback — a caller that catches this error can consume `result.result` instead
+     *  of losing the output entirely. The throw itself stays the strict-mode signal. */
     readonly result?: TaskResult | undefined;
     readonly code = "workflow.agent_schema";
-    constructor(label: string, result?: TaskResult | undefined);
+    constructor(label: string, 
+    /** The agent's completed-but-prose TaskResult (when available). The prose was paid for and may still be
+     *  useful as a degraded fallback — a caller that catches this error can consume `result.result` instead
+     *  of losing the output entirely. The throw itself stays the strict-mode signal. */
+    result?: TaskResult | undefined);
 }
+/**
+ * Thrown by `ctx.agent` when the progress watchdog aborted EVERY attempt (stall-retry exhaustion). The throw
+ * is the terminal contract (stall exhaustion throws; `null` is not the stall terminal), but the LAST attempt
+ * may still have produced a real `TaskResult` — partial text, burned spend, and the warm-resume `sessionId`.
+ * That result rides on the error as {@link lastResult} so a caller can salvage the partial output or resume
+ * the session instead of losing paid-for work; the engine also backfills the run record and journal entry
+ * from it. `lastResult` is absent when the aborted attempt rejected without returning a result. Its `status`
+ * is never `"completed"` (a completed attempt ends the retry loop), so a journaled entry is never replayed
+ * on a resume — the call retries live.
+ */
 export declare class WorkflowAgentStalledError extends Error {
     readonly attempts: number;
     readonly stallMs: number;
@@ -187,14 +334,34 @@ export declare class WorkflowAgentStalledError extends Error {
     readonly code = "workflow.agent_stalled";
     constructor(attempts: number, stallMs: number, lastResult?: TaskResult | undefined);
 }
+/** Machine code stamped on the agent record (and its journal entry / `agent_end` frame) when the spawn
+ *  review refused to start a child. Deliberately the SAME string the delegation-tool lane returns for a
+ *  refused sub-agent, so one code covers "a child the classifier did not let start", whichever lane. */
 export declare const WORKFLOW_SPAWN_BLOCKED_ERROR_CODE = "autoMode.spawn_blocked";
+/**
+ * Thrown by `ctx.agent` / `ctx.agentStream` when the pre-spawn review refused the child — either the
+ * auto-mode classifier returned a `block` verdict over the finalized objective/toolset/output-schema, or the
+ * child's requested output schema could not be presented to the classifier at all (non-serializable, or
+ * larger than the review cap: an unclassifiable schema is refused rather than waved through).
+ *
+ * The child never starts. The refusal is NOT silent: the engine records the agent as `failed` with
+ * {@link WORKFLOW_SPAWN_BLOCKED_ERROR_CODE}, emits `agent_end`, and (on the `ctx.agent` lane) journals a
+ * synthetic failed entry at the call's true ordinal, so a resume retries the call live rather than replaying
+ * a refusal. `category` is the classifier's matched rule name (`""` for the schema-cap refusal).
+ */
 export declare class WorkflowAgentBlockedError extends Error {
     readonly label: string;
     readonly category: string;
+    /** Human-readable cause, already bounded + redacted by the engine (classifier text is model output). */
     readonly reason: string;
     readonly code = "workflow.agent_blocked";
-    constructor(label: string, category: string, reason: string);
+    constructor(label: string, category: string, 
+    /** Human-readable cause, already bounded + redacted by the engine (classifier text is model output). */
+    reason: string);
 }
+/** design/98 §D.6 hard cap: thrown by `ctx.agent` once the workflow has spawned `max` agents (a runaway
+ *  LLM-authored script is bounded, not trusted — budget alone is checked only pre-spawn, so a concurrent
+ *  fan-out can overshoot it; this counts cumulative spawns). */
 export declare class WorkflowMaxAgentsError extends Error {
     readonly max: number;
     readonly code = "workflow.max_agents";