@sema-agent/server 1.322.0 → 2.0.0

package/dist/runs.d.ts

@@ -7,6 +7,44 @@ import type { ElicitationCoordinator } from "./elicitation.js";
 import type { QuestionCoordinator } from "./question.js";
 import { type FleetRunPublisher } from "./fleet/fleet-bus.js";
 import { type WorkflowCompletionInbox } from "./orchestration/workflow-completion-inbox.js";
+/**
+ * stoppedBy (core 1.252): a service cancel is a USER stop — mark the run's still-running background
+ * children BEFORE core's teardown reaps them (bare abort = attribution falls back to "system"; core's own
+ * reap marks "parent", but first-marker-wins means our earlier "user" is the one that lands). Register this
+ * FIRST on the cancel signal so it runs ahead of any later-registered core listener (listener-order
+ * guarantee); one registration covers every abort route on that signal (same-replica fast path + the
+ * cross-replica flag poll). Advisory only — the cancel itself must never fail on attribution.
+ *
+ * Access = TASK-scoped children ONLY: owner = the parent taskId (on a RESUME leg: the sessionId — core's
+ * canonical taskId there), scope = `principal ?? "default"` (core registers children under
+ * `spec.principal ?? "default"`, so an anonymous run's children live in scope "default" and an access
+ * WITHOUT scope matched nothing). Session-scoped children are DELIBERATELY not marked: a cancelled parent
+ * does NOT take them down (CC Backgrounded semantics — core's teardown reaps with skipSessionScoped), so
+ * pre-marking them "user" would misattribute a stop that isn't happening.
+ *
+ * core 1.256: `markStopSourceForOwner` replaces the old `list()+markStopSource`
+ * per-row loop, closing BOTH documented holes — ① the EXPLICIT `sessionScoped` flag
+ * (`skipSessionScoped:true`) makes the resume leg safe (its owner key == sessionId COINCIDES with
+ * session-scoped children's; the old code couldn't tell them apart and took an honest degrade instead),
+ * ② a direct handle-map walk (no `list()` 500-row display cap under-marking >500-children runs). Covers
+ * core's full markable set (background_agent / background_bash / monitor); running-only +
+ * first-marker-wins guards live inside the seam.
+ */
+/** [1488]③(b) + codex R2: the bg agent-handle OUTPUT read, kind-gated BEFORE any poll. `pollTask` is the
+ *  generic registry face and polling is NOT side-effect-free for other kinds — a terminal workflow poll
+ *  fires `onServedTerminal` (acknowledges the completion as served → suppresses its notification) and a
+ *  bash poll advances the output cursor. `getAccessibleTask` is a pure lookup: resolve + access-check +
+ *  type-check FIRST; only a `background_agent` row is ever polled (non-blocking). Everything else returns
+ *  the registry's own not_found shape, indistinguishable from an unknown handle (the route 404s it).
+ *
+ *  1.250 durable arm (core 1.364, [1511] follow-up delivered): a FULL in-process miss (`!row`) falls
+ *  through to `pollTask(…, { agentStore })` — core's durable arm only fires for `a*`-shaped handles
+ *  (DURABLE_AGENT_HANDLE_RE) behind `canAccessAgentRecord`, and with NO in-process handle the live
+ *  workflow/bash branches are unreachable, so the kind-gate's reason (onServedTerminal / cursor advance)
+ *  cannot trigger. Terminal rows serve the durable snapshot cross-instance/post-restart; a foreign-writer
+ *  running row answers the honest "outcome unknown here"; anything else is core's own not_found (byte-same
+ *  route 404 as today). A row that IS in-process but of the wrong type stays a hard 404 — the process
+ *  knows the truth, falling back would sidestep the kind gate. */
 export declare function backgroundAgentOutput(registry: typeof defaultTaskRegistry, handle: string, access: {
     owner: string;
     scope: string;
@@ -23,6 +61,15 @@ export declare function taskHandleOutput(registry: typeof defaultTaskRegistry, h
     content: string;
     details: unknown;
 }>;
+/** [1499] CC TaskStop 人侧对位 — stop a background task handle (bash kill / monitor stop / agent abort).
+ *  Same kind gate as the read face (a workflow stops via its own cancel face, never this verb). stopTask is
+ *  idempotent on a terminal handle (the registry answers honestly); the stop is attributed "user" via the
+ *  registry's existing markStopSource machinery (an HTTP stop is the human's hand — parity with the shell's
+ *  TaskStop attribution). The pre-mark is first-write-wins and MUST come first (core's own stop path marks
+ *  "parent" internally — marking after would lose the attribution race on success, the common path); the
+ *  trade (codex R3) is that on a kill-that-didn't-land the pending "user" mark is not clearable through the
+ *  public registry face — the route surfaces that arm as 409 stop.not_landed, and the atomic fix (a `source`
+ *  option on stopTask) is a core ask. */
 export declare function taskHandleStop(registry: typeof defaultTaskRegistry, handle: string, access: {
     owner: string;
     scope: string;
@@ -32,36 +79,174 @@ export declare function taskHandleStop(registry: typeof defaultTaskRegistry, han
     details: unknown;
 }>;
 export declare function markChildrenStoppedByUserOnAbort(signal: AbortSignal, taskId: string, principal: string | null | undefined): void;
+/**
+ * A session CAS conflict is swallowed by core into a failed `TaskResult` (it is not thrown from
+ * `runTaskStream`), so detect it from the result. Prefer the structured `errorCode` (core ≥1.8); fall
+ * back to the conflict wording only for older results without one.
+ */
 export declare function isSessionConflictResult(result: {
     status: string;
     errorMessage?: string;
     errorCode?: string;
 }): boolean;
+/**
+ * E18 resume-at CALLER error → an HTTP 4xx. A bad/stale resume-at target (the resolved entryId is gone or is not a
+ * settled message boundary) surfaces as a FAILED TaskResult carrying a `resume_at.*` errorCode (core swallows the
+ * prepare-throw into the result, exactly like a session conflict — runtask catch → status:"failed"+errorCode). The
+ * sync path otherwise 200s a failed result; map these to 4xx so a caller mistake reads as one. `not_found` (the
+ * entry is genuinely absent) → 404; everything else (not_a_message / conflicts_resume / no_session) → 422.
+ *
+ * design/114 Phase3: `requireExistingSession` on a genuinely-missing/purged session ALSO surfaces as a failed result
+ * (core prepare-task maps the store's `not_found` → `resume.session_not_found`); map it to 404 (the session is gone),
+ * the same "caller mistake reads as a 4xx, not a silent 200 fresh run" discipline.
+ *
+ * [833] rewind exclusive mode (core 1.292 resumeAtMode:"before"): its two edge rejections ride the same `resume_at.*`
+ * prefix (before_target_not_user / before_root_unsupported → 422 via the existing branch, errorCode passed through
+ * UNCHANGED for the shell). `rewind_snapshot.unresolvable` (rewindFiles + "before": no snapshot at/above the branch
+ * point) is core's third rejection with a DIFFERENT prefix — same caller-mistake shape (prepare-throw, nothing
+ * billed), map it to 422 explicitly so it doesn't fall through to a 200-with-failed body.
+ */
 export declare function resumeAtHttpStatus(result: {
     status: string;
     errorCode?: string;
 }): number | undefined;
+/**
+ * E18 resume-at — per-turn anchor capture, shared by runInBackground AND the resume-leg driveResume so the (single,
+ * tricky) capture rule can't drift between the two stream-drain loops.
+ *
+ * A "turn" in core = ONE assistant message + its tool batch. resume-at is valid ONLY at a SETTLED rewindable boundary
+ * — core's prepare-task accepts "user messages or finished assistant-text turns" and REJECTS an assistant message that
+ * ends mid-tool-call (resume_at.not_a_message). So we capture an anchor ONLY for a turn that produced text AND ran NO
+ * tools: then the turn's leaf at turn_end IS that assistant-text message (the rewindable target). For a tool-using
+ * turn neither candidate works — at turn_end the leaf is the turn's LAST tool-result (core appends tool results before
+ * emitting turn_end; a tool-result is stored as a `message` so core would SILENTLY branch AFTER the tools ran), and
+ * the assistant message itself ends mid-tool-call so core would reject it. The shell still gets a per-message eventId
+ * handle on every text event (E2 identity); a rewind to a non-captured (tool-using) message simply 404s — honest,
+ * never a silent wrong-point branch. (The adversarial-review HIGH: capturing at turn_end unconditionally mis-anchored
+ * every tool-using turn — the common agentic shape — to the tool-result leaf.)
+ *
+ * Best-effort: a capture failure must NEVER fail the run (it only makes that one turn non-rewindable). `onCaptureFail`
+ * surfaces the degrade (a metric) so a SYSTEMATIC failure — e.g. an un-migrated DB missing `resume_anchor` — is
+ * observable instead of a silent feature outage.
+ */
 export declare class TurnAnchorCapture {
     private readonly capture;
     private readonly onCaptureFail?;
+    /** R8 (CC-parity rewind): capture a USER-message anchor straight from the
+     *  `message_committed{role:"user"}` event — its `entryId` is the persisted user-message `SessionTreeEntry.id`,
+     *  ALWAYS a valid `resumeAt` target (core accepts a user message; it rejects a tool-result / mid-tool-call
+     *  assistant). This is the CC rewind target ("rewind to the prompt" = the code-restore parity path — a code
+     *  change happens in a tool turn WITHIN a prompt's run, so rewinding to the prompt + rewindFiles undoes it).
+     *  Keyed by the run's taskId (the handle the shell already holds from the POST response — no eventId→entryId
+     *  side map / no `getLeafId` inference needed). The assistant-turn capture above stays as an additive bonus. */
     private readonly captureUser?;
+    /** The turn's FIRST text_delta eventId = the message's stable resume handle (also stamped on the durable text event). */
     firstTextEventId: string | undefined;
     private turnHadTool;
-    constructor(capture: ((eventId: string) => Promise<void>) | undefined, onCaptureFail?: (() => void) | undefined, captureUser?: ((entryId: string) => Promise<void>) | undefined);
+    constructor(capture: ((eventId: string) => Promise<void>) | undefined, onCaptureFail?: (() => void) | undefined, 
+    /** R8 (CC-parity rewind): capture a USER-message anchor straight from the
+     *  `message_committed{role:"user"}` event — its `entryId` is the persisted user-message `SessionTreeEntry.id`,
+     *  ALWAYS a valid `resumeAt` target (core accepts a user message; it rejects a tool-result / mid-tool-call
+     *  assistant). This is the CC rewind target ("rewind to the prompt" = the code-restore parity path — a code
+     *  change happens in a tool turn WITHIN a prompt's run, so rewinding to the prompt + rewindFiles undoes it).
+     *  Keyed by the run's taskId (the handle the shell already holds from the POST response — no eventId→entryId
+     *  side map / no `getLeafId` inference needed). The assistant-turn capture above stays as an additive bonus. */
+    captureUser?: ((entryId: string) => Promise<void>) | undefined);
+    /** A `message_committed` arrived — capture a USER-message rewind anchor (CC parity). Best-effort (a failure only
+     *  makes that one prompt non-rewindable). Only `role==="user"`; assistant/toolResult committed entries are handled
+     *  by the turn-text path (assistant) or deliberately not anchored (toolResult — `resumeAt` rejects them). */
     onMessageCommitted(role: string | undefined, entryId: string | undefined): Promise<void>;
+    /** A text_delta arrived — latch the first DEFINED eventId as the message handle (eventId is optional on the stream). */
     onText(eventId: string | undefined): void;
+    /** A tool ran this turn — mark it non-rewindable (its leaf will be a tool-result, not a settled assistant-text message). */
     onTool(): void;
+    /** turn_end — capture the anchor iff this was a settled assistant-TEXT turn, then reset for the next turn. */
     onTurnEnd(): Promise<void>;
 }
+/**
+ * Strip the durable-resume capability token from a result before it is persisted to the replayable event
+ * log / run row or returned to the submitter. The token IS the resume credential (token-as-auth, search
+ * [18] Q1b) and must never leave the service. Safe on any result (no-op when absent) — notably core maps a
+ * NESTED suspend under verify/cascade to status:"failed" + errorCode "unexpected.suspended" while still
+ * spreading `checkpointToken`, so that "failed" path (unlike the stream path's explicit suspend handling)
+ * would otherwise leak it into task_event / task_run.result / the sync 200 response. `checkpointGate` is
+ * non-secret and intentionally kept.
+ */
 export declare function stripCheckpointToken<T>(result: T): T;
+/** Evict a stale warm-cache entry after a cross-instance write conflict (broken-affinity backstop). */
 export declare function evictIfConflict(runner: Runner, sessionId: string | undefined, result: TaskResult): void;
+/**
+ * Drive a task to completion in the background, persisting its events to the durable run log (S2).
+ *
+ * Text deltas are coalesced into one `text` event per turn (the durable stream is turn-grained for
+ * text); tool/lifecycle events are recorded individually. Per-token live streaming stays on the
+ * synchronous `/v1/tasks/stream` endpoint. Never throws — failures are recorded on the run.
+ *
+ * Cancellation (POST /v1/runs/:id/cancel): the run registers an AbortController in `inflight` (same-replica
+ * fast path — the cancel handler aborts it directly) and its heartbeat tick polls the durable
+ * `cancel_requested` flag (cross-replica, ≤HEARTBEAT_MS lag). Either way the run settles to
+ * status "failed" + errorCode "cancelled" (metric label "cancelled"); the entry is removed in `finally`.
+ *
+ * Preemption (POST /v1/assistant/tasks/:id/preempt, design/80 seam #2): a SECOND, INDEPENDENT controller
+ * (`preemptCtrl`, registered in `preemptable`) carries the scheduler's graceful "yield this task" — when raised,
+ * core durably SUSPENDS the task at the next clean turn boundary (gate resource_limit, reason "preempt") so it is
+ * RESUMABLE, the opposite of cancel's kill. It is wired ONLY on the plain-stream path: the verify/cascade
+ * branches finalize with `setTerminal` unconditionally (no `setSuspended`), so a preempt-suspend there would write
+ * a non-terminal "suspended" as terminal and release the session lock — and preempt's contract is graceful, not a
+ * failure. Cross-replica via the `preempt_requested` flag (same heartbeat tick). Eligibility (resourceSuspend +
+ * durable store + durable tool-results + remote env) is core's call: an ineligible task's preemptSignal no-ops.
+ *
+ * Steering (POST /v1/runs/:id/steer, design/47): the live core `TaskStream` is registered in `steerable` so the
+ * HTTP route can inject a mid-task message via `stream.steer()` (drained at the next turn boundary). Same-replica
+ * only — a suspended run is steered durably via the checkpoint's `setPendingSteer` instead, and only the
+ * plain-stream path holds a steerable stream (the verify/cascade branches return a result, not a stream).
+ */
 export declare function runInBackground(runner: Runner, spec: TaskSpec, runStore: RunStore, taskId: string, metrics?: Metrics, principal?: string, verify?: {
     maxRounds: number;
     costCeilingMicroUsd?: number;
-}, cascade?: CascadeConfig, instrumentDegenerate?: (result: TaskResult) => void, planCacheProbe?: {
+}, // 快审 F1:number 参升整对象——cost 顶随传
+cascade?: CascadeConfig, instrumentDegenerate?: (result: TaskResult) => void, planCacheProbe?: {
     record: (scope: string | undefined, objective: string, completed: boolean) => void;
-}, persistThinking?: boolean, inflight?: Map<string, AbortController>, preemptable?: Map<string, AbortController>, steerable?: Map<string, TaskStream>, modelUsage?: ModelUsageTracker, elicitation?: ElicitationCoordinator, elicitOwner?: string | null, captureTurnAnchor?: (eventId: string) => Promise<void>, fleetPublisher?: FleetRunPublisher, captureUserMessageAnchor?: (entryId: string) => Promise<void>, question?: QuestionCoordinator, workflowCompletionInbox?: WorkflowCompletionInbox, subagentSteer?: {
+}, persistThinking?: boolean, inflight?: Map<string, AbortController>, preemptable?: Map<string, AbortController>, steerable?: Map<string, TaskStream>, modelUsage?: ModelUsageTracker, elicitation?: ElicitationCoordinator, 
+/** E23: the VERIFIED principal (gatedPrincipal) that may answer this run's elicitations — matches the respond
+ *  owner-gate's identity source (NOT the cost-attribution `principal`, which on a direct door is the spoofable
+ *  header → can be null while a JWT principal exists). Falls back to the run owner when not supplied. */
+elicitOwner?: string | null, 
+/** E18 resume-at: capture the turn's (firstTextEventId → leaf entryId) anchor at each turn_end. Built by the caller
+ *  closing over {sessionId, owner, sessionStore.getLeafId, resumeAnchorStore}; undefined ⇒ no anchor store wired. */
+captureTurnAnchor?: (eventId: string) => Promise<void>, 
+/** MF-Fleet (shell-host contract): the run-scoped fleet-row publisher. `onStart` adds the live row; `onEvent` accrues
+ *  tokens (turn_end) + subagent child rows (task_progress); `onTerminal` flips/removes it. Fired for ALL legs
+ *  (verify/cascade/plain-stream) so a background run TRANSITIONS its `GET /v1/fleet/stream` row exactly like the
+ *  sync leg. No-op when no fleet bus is wired (the publisher is a null-object). */
+fleetPublisher?: FleetRunPublisher, 
+/** R8 (CC-parity rewind): capture a USER-message anchor (keyed by this run's taskId) from `message_committed{role:"user"}`
+ *  — the CC "rewind to the prompt" target. undefined ⇒ no anchor store wired. */
+captureUserMessageAnchor?: (entryId: string) => Promise<void>, 
+/** §4④ : AskUserQuestion LIVE coordinator — establishes a per-run onQuestion ALS context (like `elicitation`)
+ *  so an AskUserQuestion tool call routes to this run's stream + owner-gated respond. undefined ⇒ headless default. */
+question?: QuestionCoordinator, 
+/** P1 ①② follow-on (core): the async-workflow completion inbox, drained at the START of this background
+ *  leg (parity with the sync stream-open drain) into durable `workflow_complete` events a tailing client replays.
+ *  Owner gate = `elicitOwner ?? owner` (the same verified-principal-with-run-owner-fallback the elicit/question
+ *  contexts use). undefined ⇒ no push half wired (the WorkflowStatus poll floor stands alone). */
+workflowCompletionInbox?: WorkflowCompletionInbox, 
+/** C2 (core 1.219): the replica-local Task-subagent steer-handle registry. When present, this leg
+ *  opts into core's `onSubagentSpawn` sink — each SYNC delegation's steer handle registers under THIS run's
+ *  taskId (auto-evicted on child settle) so POST /v1/runs/:id/subagents/:target/steer can route into it. */
+subagentSteer?: {
     register(runId: string, handle: SubagentSteerHandle): () => void;
-}, completionDiagLog?: (msg: string, meta?: Record<string, unknown>) => void, sendUserFile?: SendUserFileEmitter, promptManifests?: PromptManifestTracker): Promise<void>;
+}, 
+/** ask①: emit-target diagnostic sink for the completion-inbox drain below (route/connection/
+ *  deliveryLagMs per delivered `workflow_complete`). runs.ts has no logger of its own — the caller closes over
+ *  deps.logger. undefined ⇒ silent (behavior unchanged). */
+completionDiagLog?: (msg: string, meta?: Record<string, unknown>) => void, 
+/** SendUserFile(切片2):per-run file_link 帧发射 ALS(question/elicitation 同款)。emit=durable append。 */
+sendUserFile?: SendUserFileEmitter, 
+/** [998]② the shared prompt-manifest accumulator (tracer records at prepare; this leg drains the pending
+ *  record into a durable `prompt_assembled` event — turns/stream read it). undefined ⇒ not wired. */
+promptManifests?: PromptManifestTracker): Promise<void>;
+/** How often a running instance refreshes its run's updated_at (liveness, independent of events).
+ *  Must stay strictly below `runStaleSec` (asserted at startup) or the reaper would race live runs. */
 export declare const HEARTBEAT_MS = 30000;
 //# sourceMappingURL=runs.d.ts.map