loopengine 0.0.18 → 0.0.21

package/dist/core/loop-events.d.ts

@@ -0,0 +1,175 @@
+import type { CheckResult } from './budget.js';
+import type { Decision, PendingApproval } from 'actauth';
+import type { PendingQuestion } from './system-tools/index.js';
+/** BudgetTracker's own read-only budget check, run once per loop turn
+ * before the model call — reported unchanged (spread, not renamed) so
+ * this never drifts from whatever budget.ts's own CheckResult actually
+ * contains. */
+export type BudgetCheckEvent = {
+    type: 'budget:check';
+} & CheckResult;
+/** compaction.ts's own recovery kicked in because the prompt was rejected as
+ * too large — `from`/`to` are message-array lengths (this turn's own
+ * newMessages included), not token counts; see run-agent.ts's own
+ * recovery.call onPromptTooLong hook. Named after *what triggered it and
+ * what happened* (the prompt was too long, so it got compacted), not
+ * after which module did the work — "compaction:recover" still didn't
+ * say this only ever fires for the prompt-too-long case specifically,
+ * same problem contextclip:check's own rename from a package name was
+ * fixing in the first place.
+ *
+ * No sibling event for recovery.ts's other two failure modes
+ * (media-too-large, truncated output) — neither has an onMediaTooLarge/
+ * onTruncated hook actually wired up in run-agent.ts today, so neither
+ * can currently fire at all. A prior 'recovery:summary' aggregate event
+ * covering all three was removed for being ~100% redundant with this one
+ * while that's true; it can come back once a second real recovery type
+ * exists to aggregate. */
+export interface PromptCompactionEvent {
+    type: 'prompt:compaction';
+    from: number;
+    to: number;
+}
+/** The model's own "I'll do X" preamble alongside a tool_use request —
+ * the only *live* signal of assistant text mid-turn (the final answer
+ * only ever arrives via 'loop:done'/'done', once, at the very end). */
+export interface AssistantTextEvent {
+    type: 'assistant:text';
+    text: string;
+}
+/** One ActAuth Gate.evaluate() outcome per requested tool call — 'allow'
+ * here can still mean a human was asked interactively and said yes (see
+ * run-agent.ts's own wasAskedInteractively); this event fires regardless,
+ * the interactive case just also gets its own approval:pending. */
+export interface ActauthDecisionEvent {
+    type: 'actauth:decision';
+    tool: string;
+    decision: Decision;
+    reason: string;
+}
+/** A tool call's decision is in and it's about to run (or, for a system
+ * tool, already bypassed the gate entirely) — fired the instant that's
+ * known, not once execution finishes, so a live caller can show
+ * "Running…" immediately instead of a silent gap. Matched to its later
+ * 'tool:result' by `id` (the model's own tool_use id). */
+export interface ToolStartedEvent {
+    type: 'tool:started';
+    id: string;
+    tool: string;
+    args: Record<string, unknown>;
+    detailText: string;
+}
+/** A tool call's resolution — auto-allowed, interactively approved,
+ * denied, or skipped alike. `args`/`detailText` are omitted for some
+ * skipped/denied paths that never had them resolved (see run-agent.ts's
+ * own call sites). */
+export interface ToolResultEvent {
+    type: 'tool:result';
+    id: string;
+    tool: string;
+    args?: Record<string, unknown>;
+    detailText?: string;
+    statusText: string;
+}
+/** ToolLane's own raw fulfil/reject outcome, logged alongside (not
+ * instead of) the richer 'tool:result' above — kept as its own event
+ * since it's toollane's own vocabulary (`summary`, not `statusText`), not
+ * reshaped to match. */
+export interface ToolLaneResultEvent {
+    type: 'toollane:result';
+    name: string;
+    summary: string;
+}
+/** A `Skill` tool_use block was resolved to a real skill body via
+ * SkillGarden's own lazy "index-now-load-later" design — not gated by
+ * ActAuth (see run-agent.ts's own comment on why Skill invocation isn't
+ * a real tool call). Named after what happened (the skill's full body
+ * got loaded), not after which library method was called — same
+ * reasoning budget:check's own rename from contextclip:check used. */
+export interface SkillLoadEvent {
+    type: 'skill:loaded';
+    skill: string;
+}
+/** An approved call never ran because a sibling call in the same turn's
+ * batch was denied — the whole batch cancels together (see
+ * RunAgentResult.stopReason's own doc comment). */
+export interface LoopSkippedEvent {
+    type: 'loop:skipped';
+    name: string;
+    deniedTools: string[];
+}
+/** Hit config.maxTurns without the model producing a final answer. */
+export interface LoopMaxTurnsEvent {
+    type: 'loop:max_turns';
+    maxTurns: number;
+}
+/** A human denied at least one requested tool call this turn — the whole
+ * turn stops right there (see RunAgentResult.stopReason). */
+export interface LoopDeniedEvent {
+    type: 'loop:denied';
+    deniedTools: string[];
+}
+/** The loop's own final answer — the model produced text with no more
+ * tool_use blocks. Distinct from the adapter-level 'done' below: this
+ * only ever means a genuine finish, never a synthetic max_turns/denied
+ * notice (see adapters/http.ts's own 'done', which covers all three). */
+export interface LoopDoneEvent {
+    type: 'loop:done';
+    text: string;
+}
+/** Every event runAgent() itself can emit via RunAgentOptions.onEvent —
+ * not the adapter-synthesized ones below, which no caller of runAgent()
+ * itself ever produces. */
+export type RunAgentLoopEvent = BudgetCheckEvent | PromptCompactionEvent | AssistantTextEvent | ActauthDecisionEvent | ToolStartedEvent | ToolResultEvent | ToolLaneResultEvent | SkillLoadEvent | LoopSkippedEvent | LoopMaxTurnsEvent | LoopDeniedEvent | LoopDoneEvent;
+/** adapters/http.ts echoing back which session id this turn used — first
+ * event of every streamed turn, so a caller that omitted sessionId can
+ * capture what got generated. Not something runAgent() itself knows
+ * (session ids are resolved per-request by the adapter, before runAgent
+ * is even called). */
+export interface SessionEvent {
+    type: 'session';
+    sessionId: string;
+}
+/** A tool call needs a human 'ask' decision, live — spreads actauth's own
+ * PendingApproval verbatim (id/tool/args/scope/reason/requestedAt)
+ * alongside `type`, so this never drifts from whatever that package
+ * actually returns. */
+export type ApprovalPendingEvent = {
+    type: 'approval:pending';
+} & PendingApproval;
+/** The system ask_user tool raised a genuinely ambiguous question — same
+ * spread-verbatim reasoning as ApprovalPendingEvent above, against
+ * system-tools/ask_user.ts's own PendingQuestion. */
+export type QuestionPendingEvent = {
+    type: 'question:pending';
+} & PendingQuestion;
+/** The turn is over — covers a genuine finish and both synthetic
+ * stopReasons (max_turns/denied) alike, the one event every caller can
+ * treat as "nothing more is coming" regardless of which of the three it
+ * was (see RunAgentResult.stopReason's own doc comment). */
+export interface DoneEvent {
+    type: 'done';
+    text: string;
+    stopReason?: 'max_turns' | 'denied';
+}
+/** Something failed after the response was already committed (SSE
+ * headers sent, or a background turn already running) — surfaced in-band
+ * rather than as an HTTP status code, since it's too late for one. */
+export interface ErrorEvent {
+    type: 'error';
+    error: string;
+}
+/** Synthesized by adapters/http.ts around a turn — session ids and
+ * HTTP-level errors aren't things runAgent() itself produces, but they're
+ * still part of the same lifecycle a caller observes end to end. */
+export type AdapterLoopEvent = SessionEvent | ApprovalPendingEvent | QuestionPendingEvent | DoneEvent | ErrorEvent;
+/** The full wire vocabulary — what run-agent.ts emits via onEvent, plus
+ * what adapters/http.ts (and, in --json mode, adapters/cli.ts) layers
+ * around it. This is "the standard output" every channel adapter is a
+ * projection of: adapters/http.ts's SSE stream writes one of these per
+ * frame; its plain /messages route collects the whole array into an
+ * `events` response field; adapters/cli.ts's --json mode writes one per
+ * NDJSON line; web/playground.ts is just a UI rendering whichever of
+ * those two HTTP routes it's talking to. */
+export type LoopEvent = RunAgentLoopEvent | AdapterLoopEvent;
+export type LoopEventType = LoopEvent['type'];

package/dist/core/loop-events.js

@@ -0,0 +1 @@
+export {};

package/dist/{model-calls → core/model-calls}/anthropic-model-call.d.ts

@@ -1,5 +1,5 @@
 import Anthropic from '@anthropic-ai/sdk';
-import type { ModelCall } from '#run-agent.js';
+import type { ModelCall } from '#core/run-agent.js';
 export interface AnthropicModelCallOptions {
     /** Defaults to the ANTHROPIC_API_KEY env var, same as the SDK itself. */
     apiKey?: string;

package/dist/{model-calls → core/model-calls}/deepseek-model-call.d.ts

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import type { ModelCall } from '#run-agent.js';
+import type { ModelCall } from '#core/run-agent.js';
 export interface DeepSeekModelCallOptions {
     /** Defaults to the DEEPSEEK_API_KEY env var. */
     apiKey?: string;

package/dist/{model-calls → core/model-calls}/openai-model-call.d.ts

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import type { Message, ModelCall, ModelResponse } from '#run-agent.js';
+import type { Message, ModelCall, ModelResponse } from '#core/run-agent.js';
 type ChatMessage = OpenAI.Chat.Completions.ChatCompletionMessageParam;
 export interface OpenAIModelCallOptions {
     /** Defaults to the OPENAI_API_KEY env var, same as the SDK itself. */

package/dist/{model-calls → core/model-calls}/openai-model-call.js

@@ -13,7 +13,7 @@
 //
 // stop_reason is normalized to the vocabulary anthropic-model-call.ts
 // already established ('end_turn' / 'tool_use' / 'max_tokens') rather than
-// passed through as OpenAI's own finish_reason strings — reflowkit's
+// passed through as OpenAI's own finish_reason strings — recovery.ts's
 // defaultIsTruncated checks a translated ModelResponse for stop_reason ===
 // 'max_tokens', so a provider-agnostic caller wiring up onTruncated later
 // gets the same behavior regardless of which ModelCall is plugged in.

package/dist/{run-agent.d.ts → core/run-agent.d.ts}

@@ -1,5 +1,11 @@
-import { RuleSet } from 'actauth';
-import type { AgentConfig, ToolDefinition, ToolSchema } from '#agent-config.js';
+import { RuleSet, type Approver } from 'actauth';
+import type { AgentConfig, 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';
+export type * from './loop-events.js';
+export declare const systemSkillsDir: string;
+export declare function dedupeToolsByName(list: ToolDefinition[]): ToolDefinition[];
 export interface ModelContentBlock {
     type: string;
     /** text blocks. */
@@ -16,13 +22,20 @@ export interface ModelContentBlock {
     content?: string;
     /** tool_result blocks: true if the tool call failed or was denied. */
     is_error?: boolean;
+    /** tool_result blocks: the actauth decision's own reason this call was
+     * allowed (e.g. "matched rule '...'"). Extra metadata riding alongside
+     * `content`, not folded into it — every model-calls/* adapter
+     * explicitly whitelists which fields it forwards to a real model API,
+     * so this never reaches the model, only a caller (the playground)
+     * inspecting stored history directly. */
+    reason?: string;
 }
 export interface ModelResponse {
     stop_reason: string;
     content: ModelContentBlock[];
 }
 /** loopengine's own conversation-message type — a superset of
- * ContextClip's `{role, content: string}`: `content` can also be a
+ * budget.ts's own `{role, content: string}`: `content` can also be a
  * `ModelContentBlock[]`, the same block shape `ModelResponse.content`
  * already used, so a model's tool_use requests and this loop's
  * tool_result replies round-trip with real per-call identity
@@ -37,8 +50,10 @@ export interface Message {
 /** Swap the Anthropic SDK in here — this is the only seam a real API call needs. */
 export type ModelCall = (messages: Message[], system: string, tools: ToolSchema[]) => Promise<ModelResponse>;
 export interface RunAgentOptions {
-    /** Emitted at each loop step for callers that want visibility (logging, UI, tests). Default: no-op. */
-    onEvent?: (event: string, detail: unknown) => void;
+    /** Emitted at each loop step for callers that want visibility (logging, UI, tests) —
+     * see loop-events.ts's own header comment for why this is a single typed
+     * union rather than a string name plus untyped detail. Default: no-op. */
+    onEvent?: (event: LoopEvent) => void;
     /** The ActAuth tenant this call runs as — feeds the Gate's scope, so it
      * governs which rules apply. runAgent() never sees a request, so it
      * can't call AgentConfig.tenantFor itself; adapters/http.ts resolves it
@@ -46,6 +61,45 @@ export interface RunAgentOptions {
      * omitting it — every standalone/CLI caller (which never has a request
      * to resolve tenantFor from) gets that default automatically. */
     tenant?: string;
+    /** This call's own session id (the *raw* one — see adapters/http.ts's
+     * own rawSessionId/storageSessionId distinction, this is the former),
+     * if the caller has one. runAgent() never sees a request or a
+     * SessionStore itself, so it can't derive this on its own — passed
+     * through purely so a pending ask_user question can be tagged with
+     * which session raised it (see system-tools/ask_user.ts's own
+     * PendingQuestion.sessionId), letting a caller list/answer questions
+     * scoped to one conversation instead of every one this process has ever
+     * seen. Omitted (a standalone script, most CLI usage) just means a
+     * 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. */
+    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
+     * pending question (something adapters/http.ts's own /questions REST
+     * endpoints, or an SSE push, can resolve later) and a blocking terminal
+     * prompt with nowhere else to go (see system-tools/ask_user.ts's own
+     * promptOnConsole).
+     *
+     * Deliberately its own option, not inferred from onEvent above —
+     * onEvent means "please tell me about loop events" (adapters/cli.ts
+     * passes one purely to log them), not "I have a way to actually answer
+     * a question later." Conflating the two was a real bug: it made a
+     * plain `loopengine run` hang forever registering an unanswerable
+     * question instead of just prompting in the terminal it's already
+     * attached to — confirmed live before this existed. Only an adapter
+     * that genuinely has an answering mechanism (adapters/http.ts, for both
+     * its routes) should pass this. */
+    onQuestionPending?: (question: PendingQuestion) => void;
 }
 export interface RunAgentResult {
     /** Final assistant text for this turn. */
@@ -55,17 +109,31 @@ export interface RunAgentResult {
      * the caller: store/transmit it, don't inspect or mutate it. */
     history: Message[];
     /** Exactly what this turn added — safe to durably append regardless of
-     * whether ContextClip recovery reshaped `history` mid-turn. A caller
+     * whether compaction.ts's own recovery reshaped `history` mid-turn. A caller
      * that persists conversations (see session-store.ts) should use this
      * instead of diffing `history` by length against what it loaded: that
      * only works if `history` only ever grows, which stops being true the
      * moment recovery can shrink/rewrite it, not just extend it. */
     newMessages: Message[];
-    /** Set to 'max_turns' if the loop stopped because it hit
-     * config.maxTurns, not because the model produced a final answer with
-     * no more tool_use blocks — `text` in that case is a synthetic notice,
-     * not something the model said. Absent on a normal finish. */
-    stopReason?: 'max_turns';
+    /** Set when the loop stopped for a reason other than the model
+     * producing a final answer with no more tool_use blocks — `text` in
+     * either case is a synthetic notice, not something the model said.
+     * Absent on a normal finish.
+     *
+     * 'max_turns': hit config.maxTurns without a final answer.
+     *
+     * 'denied': a human denied at least one requested tool call this turn
+     * (see actauth's own 'ask'/'deny' decisions) — the loop stops right
+     * there instead of feeding "denied: ..." back to the model and letting
+     * it keep going on its own, the same way Claude Code itself stops an
+     * entire pending batch rather than quietly carrying out the parts you
+     * didn't object to. A denial cancels the *whole* turn's batch, not
+     * just the call(s) that were themselves denied — any other call the
+     * 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';
 }
 /** Resolves AgentConfig.rules the same way skillsDirs resolves its own
  * default: an inline array is used as-is (full 3-segment scopePattern,