loopengine 0.0.21 → 0.1.3

package/dist/core/run-agent.d.ts

@@ -1,5 +1,5 @@
 import { RuleSet, type Approver } from 'actauth';
-import type { AgentConfig, ToolDefinition, ToolSchema } from '#core/agent-config.js';
+import type { AgentConfig, ApproverChannel, QuestionHandler, ToolDefinition, ToolSchema } from '#core/agent-config.js';
 import { type PendingQuestion } from './system-tools/index.js';
 import type { LoopEvent } from './loop-events.js';
 export { systemTools } from './system-tools/index.js';
@@ -8,7 +8,18 @@ export declare const systemSkillsDir: string;
 export declare function dedupeToolsByName(list: ToolDefinition[]): ToolDefinition[];
 export interface ModelContentBlock {
     type: string;
-    /** text blocks. */
+    /** text blocks, and thinking blocks (a model's own chain-of-thought,
+     * e.g. DeepSeek's `reasoning_content` sibling field, or — if a
+     * model-calls/* adapter ever opts into it — Anthropic's own `thinking`
+     * content block). Reuses this same field rather than adding a
+     * thinking-only one, since both are just "a string of the model's own
+     * words." Carried opaquely: loopengine never reads or reasons about
+     * this text itself, only round-trips it back verbatim on the next
+     * request that includes this message — some reasoning-mode providers
+     * (DeepSeek's thinking mode, confirmed live; Anthropic's extended
+     * thinking, documented the same way) reject the request outright if a
+     * prior turn's reasoning gets silently dropped on the way back in,
+     * once the conversation has tool_calls in it. */
     text?: string;
     /** tool_use blocks: this call's own id (referenced by a later tool_result). */
     id?: string;
@@ -73,15 +84,32 @@ export interface RunAgentOptions {
      * pending question can't be session-scoped — still fine, it's still
      * agent-scoped either way. */
     sessionId?: string;
-    /** Default Approver for this call's 'ask' decisions, when
-     * AgentConfig.approver isn't set — the seam an adapter uses to pick
-     * whichever approver actually fits its own channel (ConsoleApprover for
-     * a real terminal, a web-based one for an HTTP-served conversation,
-     * ...) without every agent needing to hardcode one itself. An explicit
-     * AgentConfig.approver still wins outright over this when the agent
-     * author set one on purpose — same as it always has (see Gate
-     * construction below) — this only fills in when that's absent. Default,
-     * if neither is given: actauth's own ConsoleApprover, same as always. */
+    /** Which channel this call is on — checked below against `'http'`,
+     * the only value `AgentConfig.httpNotifier` ever matches (see that
+     * field's own doc comment). Omitted (a standalone script, a bespoke
+     * dispatcher with no fixed channel identity) means `httpNotifier` is
+     * never consulted at all — `approver` below is the only thing that
+     * applies. */
+    channel?: ApproverChannel;
+    /** This call's own default Approver for 'ask' decisions, when
+     * `AgentConfig.httpNotifier` doesn't supply one (only possible on the
+     * `http` channel, and only when it lists `'approval'`) — the seam an
+     * adapter uses to pick whichever approver actually fits its own channel
+     * (ConsoleApprover for a real terminal, a fresh WebchatApprover per
+     * streamed turn, a WebhookApprover for a background dispatcher,
+     * ...) without every agent needing to hardcode one itself. `http`'s own
+     * `httpNotifier`, if it covers `'approval'`, still wins outright over
+     * this — the agent author's own explicit choice *for that channel*
+     * beats whatever the adapter would otherwise default to (see Gate
+     * construction below) — `cli`/`http_stream` have no such override at
+     * all, so this is the only thing that ever applies there. Default, if
+     * neither is given: actauth's own ConsoleApprover, same as always.
+     *
+     * Can be a DurableApprover (WebhookApprover, ...) instead of a live
+     * one — see HUMAN_IN_THE_LOOP.md. A background/cron dispatcher calling
+     * runAgent() directly is exactly this same kind of caller, and should
+     * pass its own durable default here the same way adapters/http.ts's
+     * stream route passes a fresh WebchatApprover. */
     approver?: Approver;
     /** Fired the instant the system ask_user tool registers a new pending
      * question — this is the seam that decides between a real, answerable
@@ -100,6 +128,30 @@ export interface RunAgentOptions {
      * that genuinely has an answering mechanism (adapters/http.ts, for both
      * its routes) should pass this. */
     onQuestionPending?: (question: PendingQuestion) => void;
+    /** This call's own default QuestionHandler — question-side sibling of
+     * `approver` above, same precedence (`AgentConfig.httpNotifier`, when it
+     * covers `'question'` on the `http` channel, still wins outright over
+     * this) and the same `LiveQuestionHandler | DurableQuestionHandler`
+     * union `approver` itself is, duck-typed the same way (see
+     * `isDurableQuestionHandler`). Default, if neither this nor
+     * `httpNotifier` supplies one: `new CliQuestionHandler()` — same role
+     * `new ConsoleApprover()` plays for `approver`.
+     *
+     * One real, current asymmetry versus `approver`: only the *durable*
+     * half of this union is actually wired into the loop below — a
+     * `system_ask_user` call only ever consults this field to decide
+     * live-vs-durable; the live case still always falls through to
+     * `onQuestionPending`/the tool's own independent live resolution
+     * (unchanged from before this field existed), never actually calling
+     * a live `QuestionHandler` resolved here. See HUMAN_IN_THE_LOOP.md's
+     * "Durable questions" section for why: fully wiring the live half too
+     * would mean moving system_ask_user's answer-collection inline into
+     * this loop (changing today's batching semantics — right now a
+     * pending question is deferred past the whole tool_use batch scan,
+     * unlike a live approval) and a breaking change to createAskUserTool's
+     * own signature — deliberately deferred rather than done half-carefully
+     * here. */
+    questionHandler?: QuestionHandler;
 }
 export interface RunAgentResult {
     /** Final assistant text for this turn. */
@@ -132,8 +184,62 @@ export interface RunAgentResult {
      * model requested in the same turn, even one already approved, never
      * runs either (see the loop's own body); it gets a "skipped", not a
      * "denied", tool_result, since it was never evaluated against its own
-     * rule. */
-    stopReason?: 'max_turns' | 'denied';
+     * rule.
+     *
+     * 'pending_approval' / 'pending_question': at least one requested tool
+     * call is durably pending a DurableApprover decision, or at least one
+     * `system_ask_user` call is durably pending a DurableQuestionHandler
+     * answer (see HUMAN_IN_THE_LOOP.md) — same "the whole batch stops here"
+     * shape as 'denied', except this isn't a rejection: any already-run
+     * sibling call in the same batch still ran (see the loop's own
+     * bucket-then-execute), captured in `pending.resultsSoFar`, and the
+     * turn resumes later via resumeAgent() once every pendingId in
+     * `pending.outstanding` is resolved — not by sending another message
+     * the way 'denied' recovers. A batch can mix both kinds (a gated tool
+     * call and an `system_ask_user` call in the same model response) — both
+     * land in the same `pending.outstanding`, since the one dangling
+     * assistant tool_use message can only ever get one completing
+     * tool_result message; `stopReason` reports 'pending_approval' for that
+     * mixed case too (only a batch with *no* approval items at all reports
+     * 'pending_question'). `newMessages` ends at the dangling assistant
+     * tool_use message, same crash-recovery shape session-store.ts's own
+     * hasUnresolvedToolCall already detects — entered on purpose here,
+     * not by accident. runAgent() does no I/O (see this module's own
+     * header comment): turning `pending` into a durable TurnCheckpoint
+     * (core/durable-approvals.ts) is the caller's job. */
+    stopReason?: 'max_turns' | 'denied' | 'pending_approval' | 'pending_question';
+    /** Set only when stopReason is 'pending_approval' or 'pending_question'. */
+    pending?: {
+        /** tool_result blocks already computed this batch — safely
+         * auto-allowed calls that ran immediately despite a gated/asked
+         * sibling still being outstanding. Not yet pushed into `newMessages`/
+         * `history`: incomplete until every outstanding item below is
+         * resolved too, and a real model API expects one complete
+         * tool_result message per assistant tool_use message, not a partial
+         * one now and a follow-up later. */
+        resultsSoFar: ModelContentBlock[];
+        /** One entry per tool call still awaiting a durable decision, keyed
+         * by the pendingId its DurableApprover/DurableQuestionHandler handed
+         * out — what an incoming resolution actually names. `kind`
+         * distinguishes which of the two this is — for 'question', `args` is
+         * `{ question, options }` and `reason` is the question text itself
+         * (there's no separate ActAuth "reason" for a question the way there
+         * is for a gated tool call's decision). */
+        outstanding: PendingItem[];
+    };
+}
+/** One requested call still awaiting a durable decision — either a gated
+ * tool call (`kind: 'approval'`) or a `system_ask_user` call (`kind:
+ * 'question'`), unified into one array so a batch mixing both shares
+ * exactly one checkpoint (see RunAgentResult.stopReason's own doc
+ * comment for why that has to be true). */
+export interface PendingItem {
+    kind: 'approval' | 'question';
+    toolUseId: string;
+    tool: string;
+    args: Record<string, unknown>;
+    pendingId: string;
+    reason: string;
 }
 /** Resolves AgentConfig.rules the same way skillsDirs resolves its own
  * default: an inline array is used as-is (full 3-segment scopePattern,
@@ -180,3 +286,25 @@ export declare function loadDefaultTools(config: AgentConfig): Promise<ToolDefin
  * elsewhere could. */
 export declare function loadSubagentAsTools(config: AgentConfig): Promise<ToolDefinition[]>;
 export declare function runAgent(config: AgentConfig, modelCall: ModelCall, userMessage: string, history?: Message[], options?: RunAgentOptions): Promise<RunAgentResult>;
+/** Continues a turn durably paused on RunAgentResult.stopReason ===
+ * 'pending_approval' — see HUMAN_IN_THE_LOOP.md for the full design.
+ * `history` is durable session history including the dangling assistant
+ * tool_use message the pause left behind (exactly what a caller's
+ * SessionStore.getHistory/withSession already returns — this needs no
+ * special resumed-session handling, since that message is real, already
+ * on disk). `resolution` is the *complete* set of tool_result blocks
+ * answering that message — every entry from a resolved TurnCheckpoint's
+ * own resultsSoFar, once its outstanding is empty; assembling that is the
+ * caller's job (core/durable-approvals.ts's own CheckpointStore only
+ * stores it, it doesn't execute tools or know when a batch is complete —
+ * see that module's own doc comment), not something this function
+ * derives on its own.
+ *
+ * Pushes `resolution` as the completing message and picks the loop back
+ * up from there — a fresh model call, now with the full picture, exactly
+ * like a synchronous 'ask' would have continued if it hadn't needed to
+ * pause at all. Can itself return with stopReason 'pending_approval'
+ * again (the model's next round of tool calls hits another durably-gated
+ * one), 'denied', 'max_turns', or a genuine finish — runLoop handles all
+ * of those uniformly regardless of how this turn started. */
+export declare function resumeAgent(config: AgentConfig, modelCall: ModelCall, history: Message[], resolution: ModelContentBlock[], options?: RunAgentOptions): Promise<RunAgentResult>;