loopengine 0.0.17 → 0.0.20

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

@@ -0,0 +1,168 @@
+import type { CheckResult } from 'contextclip';
+import type { RecoveryAction } from 'reflowkit';
+import type { Decision, PendingApproval } from 'actauth';
+import type { PendingQuestion } from './system-tools/index.js';
+/** ContextClipper'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 contextclip's own CheckResult actually
+ * contains. */
+export type ContextClipCheckEvent = {
+    type: 'contextclip:check';
+} & CheckResult;
+/** ContextClip 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
+ * reflow.call onPromptTooLong hook. */
+export interface ReflowRecoverEvent {
+    type: 'reflow:recover';
+    from: number;
+    to: number;
+}
+/** Ordered log of whatever reflowkit's own Reflow.call had to do to get a
+ * usable response this turn (prompt-too-long retries, truncation
+ * retries, ...) — empty-array case never fires this event at all (see
+ * run-agent.ts: only logged when recoveries.length > 0). */
+export interface ReflowRecoveriesEvent {
+    type: 'reflow:recoveries';
+    recoveries: RecoveryAction[];
+}
+/** 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 — not gated by ActAuth (see run-agent.ts's own comment on
+ * why Skill invocation isn't a real tool call). */
+export interface SkillGardenInvokeEvent {
+    type: 'skillgarden:invoke';
+    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 = ContextClipCheckEvent | ReflowRecoverEvent | ReflowRecoveriesEvent | AssistantTextEvent | ActauthDecisionEvent | ToolStartedEvent | ToolResultEvent | ToolLaneResultEvent | SkillGardenInvokeEvent | 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/core/run-agent.d.ts

@@ -0,0 +1,182 @@
+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. */
+    text?: string;
+    /** tool_use blocks: this call's own id (referenced by a later tool_result). */
+    id?: string;
+    /** tool_use blocks. */
+    name?: string;
+    /** tool_use blocks. */
+    input?: Record<string, unknown>;
+    /** tool_result blocks: id of the tool_use block this result answers. */
+    tool_use_id?: string;
+    /** tool_result blocks: the tool's output (or denial/error message). */
+    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
+ * `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
+ * (`tool_use_id`) instead of being flattened into prose. Plain-string
+ * content (a user's message, a skill's injected body, a synthetic
+ * compaction note) is just as valid — nothing requires every message to
+ * be block-structured. */
+export interface Message {
+    role: string;
+    content: string | ModelContentBlock[];
+}
+/** 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) —
+     * 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
+     * per request and passes the result here. Default `'default'`, same as
+     * 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. */
+    text: string;
+    /** Full conversation so far, including this turn — pass back in as
+     * `history` on the next call to continue the conversation. Opaque to
+     * 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
+     * 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 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,
+ * unchanged — see loadYamlRules for why only the YAML form gets the
+ * agent segment auto-appended); omitted entirely defaults to
+ * `agents/<name>/actauth.yml`, this repo's own folder-form convention.
+ * Unlike skillsDirs, a missing *default* file falls back to an empty
+ * ruleset rather than propagating the raw ENOENT — permissions failing
+ * shouldn't crash the whole call. That fallback defaults to `'deny'`, not
+ * the inline-array form's `'ask'`: no `actauth.yml` at all means this
+ * agent's permission story was never actually written, which is a
+ * stricter unknown than "written, but this one tool has no rule" — 'ask'
+ * still runs an Approver that could auto-approve, while 'deny' refuses
+ * outright until real rules exist. `defaultDecision`, if set, still wins
+ * over that. An *explicitly* given path that doesn't exist is a real
+ * configuration bug, though, and still throws — only the silent, implicit
+ * default gets this forgiveness.
+ *
+ * Exported (alongside loadDefaultTools below) so adapters/http.ts's
+ * GET /agents/:name/config route can show the same rules runAgent() would
+ * actually enforce, not a re-derived guess at them. */
+export declare function loadRules(config: AgentConfig): RuleSet;
+export declare function loadDefaultTools(config: AgentConfig): Promise<ToolDefinition[]>;
+/** Auto-loads agents/<name>/subagents/<child>/index.{ts,js} — each one a
+ * full AgentConfig, wrapped with agentAsTool and merged into `config`'s
+ * own tools, no import or AgentConfig.tools edit required. Unlike
+ * loadDefaultTools, this always runs regardless of whether `config.tools`
+ * was left to its own default or set explicitly — see AgentConfig.tools's
+ * own doc comment for why subagents are a distinct concern from
+ * hand-written tools. A missing subagents/ folder is just `[]`, same
+ * missing-is-fine treatment tools/ and skills/ get; a subdirectory with
+ * neither index.ts nor index.js is skipped, same as resolveModulePath's
+ * own handling in discover-agents.ts.
+ *
+ * Each subagent is loaded via loadAgentModule — the same per-module
+ * resolution discoverAgents itself uses — then patched by
+ * resolveSubagentConfig (see its own doc comment for why) before being
+ * wrapped. Its own `config` goes through this exact same function again
+ * the next time *it* runs (inside agentAsTool's execute, via runAgent).
+ * That's what makes nesting (a subagent with its own subagents/ folder)
+ * work with no extra recursion code: it's just this function being
+ * called again, one level down. A folder can't be its own ancestor, so
+ * this can't cycle the way a hand-wired agentAsTool(getEntry(...)) call
+ * 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>;