@sema-agent/core 5.19.0 → 5.21.0

package/dist/engine/llm/validation.d.ts

@@ -1,4 +1,7 @@
 import type { Tool, ToolCall } from "./types.js";
+/** Finds the target tool and validates/coerces a model-emitted tool call. */
 export declare function validateToolCall(tools: Tool[], toolCall: ToolCall): unknown;
+/** VENDORED EDIT (design/115 P0): resolve canonical tool names first, then legacy aliases. */
 export declare function findToolByName<T extends Tool>(tools: readonly T[] | undefined, name: string): T | undefined;
+/** Validates tool arguments against TypeBox or plain JSON-schema parameters. */
 export declare function validateToolArguments(tool: Tool, toolCall: ToolCall): unknown;

package/dist/engine/loop/agent-loop.d.ts

@@ -1,8 +1,73 @@
 import { type AgentCoreStreamRuntimeDeps } from "./runtime-deps.js";
 import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types.js";
+/** Callback used by synchronous loop runners to publish agent lifecycle events. */
 export type AgentEventSink = (event: AgentEvent) => Promise<void> | void;
-export type LoopContinueReason = "next_turn" | "steer_injected" | "follow_up_injected" | "reactive_compact_retry" | "max_output_tokens_recovery" | "malformed_tool_use_retry" | "thinking_only_retry" | "midstream_partial_recovery" | "degenerate_output_recovery";
-export type LoopTerminalReason = "completed" | "aborted_before_stream" | "assistant_error" | "stop_requested" | "malformed_tool_use_exhausted" | "truncated_output_exhausted";
+/** Named reasons the loop goes around again. Assertable in tests via the trace sink. */
+export type LoopContinueReason = 
+/** A turn finished with executable tool calls (or injected messages) still driving work. */
+"next_turn"
+/** Drain point A (mid-work boundary): steering messages were injected after a turn. */
+ | "steer_injected"
+/** Drain point B (agent would otherwise stop): follow-up messages were injected. */
+ | "follow_up_injected"
+/** ④b recovery: a prompt-too-long failure was recovered (compacted context) and retried in-turn. */
+ | "reactive_compact_retry"
+/** ④b recovery: a `length`-stopped answer triggered a synthetic continue nudge for another turn. */
+ | "max_output_tokens_recovery"
+/** S2 recovery (design/119): a `toolUse` stop with ZERO parseable tool calls got a retry nudge. */
+ | "malformed_tool_use_retry"
+/** S2 recovery (design/119): a thinking-only turn (no visible text, no tools) got a retry nudge. */
+ | "thinking_only_retry"
+/** design/124 tier A: a partially-finalized "stop" (mid-stream cut promoted to content) got a
+ *  bounded continue nudge so an unattended run doesn't book the cut as an incomplete success. */
+ | "midstream_partial_recovery"
+/** T1-4 recovery: a degenerate-repetition cutoff got a bounded "different approach" continue. */
+ | "degenerate_output_recovery";
+/** Named reasons the loop exits. Assertable in tests via the trace sink. */
+export type LoopTerminalReason = 
+/** Natural end: no tool calls, no steering, no follow-ups. */
+"completed"
+/** A-1 layer ② guard: the abort signal was already set before the next provider request. */
+ | "aborted_before_stream"
+/** The assistant message itself ended with stopReason "error" or "aborted". */
+ | "assistant_error"
+/** `shouldStopAfterTurn` requested a clean stop at the turn boundary (mod #16 one-shot). */
+ | "stop_requested"
+/** RB-206(形态一续批,黑板 [1870] 归因;CC 220 対位 @400176-400230, `Bxs` @397652-397674 buckets it
+ *  with budget_exhausted/api_error/model_error/turn_setup_failed, explicitly NOT `"completed"`): every
+ *  tool call in the turn was dropped as malformed AND the bounded `malformed_tool_use_retry` nudge
+ *  budget is used up — the model believes it acted, nothing ran, and there is no more recovery budget
+ *  left to try again. Before this reason existed, this case fell through to the generic no-more-work
+ *  path and was reported as a plain `"completed"`, indistinguishable from a turn that genuinely had
+ *  nothing left to do.
+ *
+ *  独立复审(视角一)提醒:`malformedToolUseRetries` 是**整个 run 生命周期内的绝对计数**,恢复成功后不
+ *  回退(与 `staticReasoningCutRecoveries` 同一姿势,非本次改动引入)——"exhausted" 说的是"这个 run 从
+ *  开始到现在总共用掉的重试次数已达上限",不是"刚刚连续失败了 maxRetries 次"。一次早于此刻很久、且已
+ *  成功恢复过的畸形调用,和刚刚才第一次触发畸形调用但恰好撞上早已用尽的预算,在这个 reason 面前不可
+ *  区分;调用方若需要"最近是否连续失败"这类更细的语义,需要自行在更高层维护窗口计数,这个 reason 只
+ *  承诺"预算耗尽"这一件事。 */
+ | "malformed_tool_use_exhausted"
+/** RB-258([1948] RB-206 口径追查的衍生发现;RB-206 的同族对仗):the model kept ending its turn on the
+ *  provider's output cap (`length`) with no tool calls, and the bounded truncated-output continue
+ *  budget (`recovery.truncatedOutput.maxContinues`, default 3) is used up — every further nudge would
+ *  buy another cut-off fragment. Before this reason existed, this case fell through to the generic
+ *  no-more-work path and was reported as a plain `"completed"`, indistinguishable from an answer that
+ *  actually finished — the same defect RB-206 fixed in the malformed lane, on the shape production
+ *  hits MORE often ([1948]: 1/89 real questions reached the precondition).
+ *
+ *  Scope notes (deliberate, mirroring the malformed lane):
+ *  - Only the CONFIGURED lane reports it. With `recovery.truncatedOutput` absent (the loop default
+ *    is OFF) there is no budget to exhaust, so a `length` stop still ends as a plain `completed` —
+ *    the pre-④b behavior, unchanged.
+ *  - `truncatedOutputContinues` counts CONSECUTIVE nudges and RESETS on any non-`length` turn (unlike
+ *    `malformedToolUseRetries`, which is absolute per run). So this reason means "the model just ended
+ *    `length` maxContinues+1 times in a row", not "this run has burnt N recoveries in total".
+ *  - Like every other terminal, it stops the loop BEFORE drain point B — a follow-up queue / Stop-hook
+ *    continuation no longer gets consulted on this path. That is the point (a stop-gate rescue would
+ *    re-enter the same wall with a spent budget), and queued follow-ups stay queued for the next
+ *    `prompt()` rather than being dropped. */
+ | "truncated_output_exhausted";
 export type LoopStep = {
     kind: "continue";
     reason: LoopContinueReason;
@@ -10,7 +75,27 @@ export type LoopStep = {
     kind: "terminal";
     reason: LoopTerminalReason;
 };
+/**
+ * Optional per-transition observer, for tests that assert WHICH path ran.
+ * Attribution notes: `reactive_compact_retry` is traced IN-TURN at each retry (a turn may trace
+ * several); the turn's boundary then traces at most ONE more Continue by priority — a recovery
+ * reason (`max_output_tokens_recovery` / `midstream_partial_recovery` / `malformed_tool_use_retry` /
+ * `thinking_only_retry`, mutually exclusive by stopReason/flag) wins, then `steer_injected` (masking the same turn's
+ * `next_turn`), then `next_turn`. Don't read the trace as a complete enumeration of concurrent causes.
+ */
 export type LoopTraceSink = (step: LoopStep) => void;
+/** Run a prompt-started loop and emit events through a caller-owned sink. */
 export declare function runAgentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, emit: AgentEventSink, signal?: AbortSignal, streamFn?: StreamFn, runtime?: AgentCoreStreamRuntimeDeps, trace?: LoopTraceSink): Promise<AgentMessage[]>;
+/**
+ * How many tool names an unknown-tool miss spells out. A miss is a NAME problem: seeing a couple of dozen
+ * real names is what lets a model spot the one it meant, while a full listing grows with the deployment
+ * (a large roster turned every typo into a multi-kilobyte result) and buys no extra recovery.
+ */
 export declare const ROSTER_LISTING_MAX = 25;
+/**
+ * The disclosure-search tool's wire name, kept as a literal here because this module is in the engine
+ * layer and must not import the runner's tool definitions. A unit test asserts it equals the exported
+ * `TOOL_SEARCH_NAME`, so the two cannot silently diverge (the `BRAIN_FLAT_CODES` arrangement in
+ * core/tool-errors.ts, same reason).
+ */
 export declare const ROSTER_SEARCH_HINT_NAME = "ToolSearch";

package/dist/engine/loop/runtime-deps.d.ts

@@ -1,9 +1,16 @@
 import type { CompleteSimpleFn, StreamFn } from "../llm/index.js";
+/** Runtime functions injected by host packages so agent-core stays provider-agnostic. */
 export interface AgentCoreRuntimeDeps {
+    /** Streaming completion implementation used for normal agent turns. */
     streamSimple: StreamFn;
+    /** Non-streaming completion implementation used by summarization helpers. */
     completeSimple: CompleteSimpleFn;
 }
+/** Runtime dependency subset required by streaming agent loops. */
 export type AgentCoreStreamRuntimeDeps = Pick<AgentCoreRuntimeDeps, "streamSimple">;
+/** Runtime dependency subset required by summarization helpers. */
 export type AgentCoreCompletionRuntimeDeps = Pick<AgentCoreRuntimeDeps, "completeSimple">;
+/** Resolve the stream function, preferring an explicit override over injected runtime deps. */
 export declare function resolveAgentCoreStreamFn(runtime: AgentCoreStreamRuntimeDeps | undefined, streamFn?: StreamFn): StreamFn;
+/** Resolve the completion function used by non-streaming helper flows. */
 export declare function resolveAgentCoreCompleteFn(runtime: AgentCoreCompletionRuntimeDeps | undefined): CompleteSimpleFn;