loopengine 0.0.18 → 0.0.20

package/dist/core/discover-agents.d.ts

@@ -0,0 +1,45 @@
+import type { AgentConfig, AgentModelConfig } from '#core/agent-config.js';
+import type { ModelCall } from '#core/run-agent.js';
+export interface AgentModule {
+    config: AgentConfig;
+    /** Factory, not a shared instance — a fresh ModelCall per request/session. */
+    createModelCall: () => ModelCall;
+}
+/** Builds a lazy, memoized createModelCall from AgentConfig.model, for a
+ * module that doesn't export its own — see that field's own doc comment.
+ * The provider's SDK module is imported here, eagerly, but that's cheap
+ * and safe with no API key at all: importing model-calls/*.ts only
+ * defines functions, it never constructs a client at module top level
+ * (see e.g. createAnthropicModelCall's own body) — so this can't fail
+ * discovery the way eagerly building the actual client would. The real
+ * client is only built the first time the returned function is actually
+ * called, and reused after that, the same "don't crash the whole server
+ * over one agent's missing API key, don't rebuild per call" reasoning
+ * agents/customer-service/index.ts's own hand-written createModelCall
+ * used before this existed.
+ *
+ * Exported so a caller updating an *already-registered* agent's model
+ * (see agent-file-admin.ts's editAgentFile, applied live via
+ * core/agent-registry.ts's updateAgent) can rebuild just this one closure
+ * without re-importing the whole module — Node's ESM loader caches an
+ * already-imported module forever, so there's no supported way to
+ * re-import a changed agent file's own createModelCall directly; this is
+ * the one piece of it that's meaningfully regenerable on its own. */
+export declare function synthesizeCreateModelCall(model: AgentModelConfig): Promise<() => ModelCall>;
+/** Imports one agent module at `path` and resolves it to an AgentModule —
+ * the single-file version of what discoverAgents does over a whole
+ * directory, factored out so run-agent.ts's subagent loader (see
+ * agent-as-tool.ts / loadSubagentAsTools) can load one `subagents/<name>/
+ * index.ts` at a time without duplicating this resolution logic.
+ * `label` is only used in error messages — discoverAgents passes
+ * `'<file> in <dir>'`, callers loading a single known path can just pass
+ * that path. */
+export declare function loadAgentModule(path: string, label: string): Promise<AgentModule>;
+/** Scans `dir` for agent modules — direct `.ts`/`.js` files, or
+ * subdirectories with an `index.ts`/`index.js` (see resolveModulePath) —
+ * each expected to export `config`, and either its own `createModelCall`
+ * or a `config.model` for one to be synthesized from (see
+ * AgentModelConfig's own doc comment). Throws, rather than skipping, on a
+ * module that doesn't match that shape or a duplicate AgentConfig.name —
+ * both are almost always a bug, not something to silently ignore. */
+export declare function discoverAgents(dir: string): Promise<Map<string, AgentModule>>;

package/dist/{discover-agents.js → core/discover-agents.js}

@@ -1,7 +1,7 @@
 // Scans a directory for agent modules and builds a name -> module map from
 // it — the thing that makes "drop a new file in agents/" enough to
 // register an agent, no hand-written import-and-add-one-line edit needed
-// anywhere else. See agent-registry.ts for the one place this repo's own
+// anywhere else. See core/agent-registry.ts for the one place this repo's own
 // reference app actually calls it.
 //
 // Keyed by AgentConfig.name, not the filename — that's the same identity
@@ -28,8 +28,16 @@ function isRawAgentModule(mod) {
  * called, and reused after that, the same "don't crash the whole server
  * over one agent's missing API key, don't rebuild per call" reasoning
  * agents/customer-service/index.ts's own hand-written createModelCall
- * used before this existed. */
-async function synthesizeCreateModelCall(model) {
+ * used before this existed.
+ *
+ * Exported so a caller updating an *already-registered* agent's model
+ * (see agent-file-admin.ts's editAgentFile, applied live via
+ * core/agent-registry.ts's updateAgent) can rebuild just this one closure
+ * without re-importing the whole module — Node's ESM loader caches an
+ * already-imported module forever, so there's no supported way to
+ * re-import a changed agent file's own createModelCall directly; this is
+ * the one piece of it that's meaningfully regenerable on its own. */
+export async function synthesizeCreateModelCall(model) {
     let cached;
     if (model.provider === 'anthropic') {
         const { createAnthropicModelCall } = await import('./model-calls/anthropic-model-call.js');

package/dist/{gateway-tools.d.ts → core/gateway-tools.d.ts}

@@ -1,5 +1,10 @@
 import type { Decision } from 'actauth';
 import type { ToolDefinition } from './agent-config.js';
+export interface ResolvedGatewayTool {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
 export interface ComposioGatewayToolEntry {
     provider: 'composio';
     /** Namespaces every tool this source produces (`${name}_${slug}`,
@@ -10,6 +15,18 @@ export interface ComposioGatewayToolEntry {
     /** Override for a non-default binary name, or a stand-in script in
      * tests — see ComposioSourceOptions.cliCommand. Defaults to 'composio'. */
     cliCommand?: string;
+    /** {name, description, input_schema} per slug, once resolved — see
+     * connectEntry/describeGatewayTools. Populated lazily (a slug just
+     * added via addGatewayTool has no entry here yet) and persisted back
+     * into this same file (see persistResolvedTools), not held in memory —
+     * so a schema, once resolved, survives a server restart instead of
+     * costing another ~3s Composio round trip on the next load. Keyed by
+     * slug, not by the derived tool name (`${name}_${slug}`), since the
+     * slug is what's stable if this source were ever renamed. Hand-editing
+     * this is never expected — treat it as generated, the same as
+     * describeGatewayTools' own in-memory result used to be before this
+     * existed. */
+    resolved?: Record<string, ResolvedGatewayTool>;
 }
 export type GatewayToolEntry = ComposioGatewayToolEntry;
 /** A top-level agent's real folder — exported so callers resolving other
@@ -103,11 +120,26 @@ export interface GatewayToolStatus {
  * function surfaces it explicitly, per source, since an operator looking
  * at this page needs to know *which* source is broken and why — where
  * loadGatewayToolsFromDir just logs and drops it, since runAgent() has no
- * structured place to hand a per-source error to. Deliberately bypasses
- * loadGatewayToolsFromDir's mtime cache — this is an occasional,
- * deliberate operator action, not a per-turn hot path, so "always
- * current" is worth more here than "cheap." */
-export declare function describeGatewayTools(agentName: string): Promise<GatewayToolStatus[]>;
+ * structured place to hand a per-source error to.
+ *
+ * No in-memory cache here (or anywhere in this file, for this) — the
+ * cache *is* gateway-tools.yml's own `resolved` field (see
+ * ComposioGatewayToolEntry's own doc comment and connectEntry, which this
+ * shares that field with), so it survives a restart instead of being
+ * lost on one. Only genuinely-unresolved slugs pay for a live fetch, and
+ * for those this still enriches with Composio's real catalog description
+ * (see withRealComposioDescriptions) before persisting — unlike
+ * connectEntry, which doesn't (see that function's own reasoning), this
+ * is an occasional operator action, not runAgent()'s hot path, so paying
+ * for the better description once, at resolution time, is worth it here.
+ * Pass `force: true` (the admin page's own "Refresh" button) to treat
+ * every slug as unresolved and overwrite their persisted entries with a
+ * fresh live check — e.g. after reconnecting an account, or on the rare
+ * chance a schema changed upstream without gateway-tools.yml itself
+ * changing. */
+export declare function describeGatewayTools(agentName: string, options?: {
+    force?: boolean;
+}): Promise<GatewayToolStatus[]>;
 /** Resolves agents/<name>/gateway-tools.yml (or the equivalent nested path
  * for a subagent — see readGatewayToolsFromDir) into real ToolDefinitions,
  * for run-agent.ts to merge into the rest of an agent's tools. Missing
@@ -190,5 +222,5 @@ export declare function getComposioAuthStatus(cliCommand?: string): Promise<Comp
  * Composio's own documented path is plain, interactive `composio login`
  * (opens a browser) after installing the CLI — not something a web
  * request can drive, so the Gateways panel shows that as instructions
- * instead of a form; see its own comment in adapters/global-config-page.ts. */
+ * instead of a form; see its own comment in web/global-config-page.ts. */
 export declare function disconnectComposioAccount(cliCommand?: string): Promise<void>;

package/dist/{gateway-tools.js → core/gateway-tools.js}

@@ -15,12 +15,13 @@ import { promisify } from 'node:util';
 import { parse as parseYaml, parseDocument, stringify as stringifyYaml } from 'yaml';
 import { connectComposioSource } from 'mcpplug';
 const execFileAsync = promisify(execFile);
-// Same "next to this file, not process.cwd()" reasoning run-agent.ts's
-// own agentsRootDir uses — real code (an actauth.yml write, a
-// gateway-tools.yml write) needs to land in the same place a built dist/
-// would look for it, not wherever the process happened to be launched
-// from.
-const agentsRootDir = join(dirname(fileURLToPath(import.meta.url)), 'agents');
+// Same "one level up from this file, not process.cwd()" reasoning
+// run-agent.ts's own agentsRootDir uses (this file lives in core/
+// alongside it, with agents/ one level up at repo root either way) — real
+// code (an actauth.yml write, a gateway-tools.yml write) needs to land in
+// the same place a built dist/ would look for it, not wherever the
+// process happened to be launched from.
+const agentsRootDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'agents');
 function gatewayToolsPath(dir) {
     return join(dir, 'gateway-tools.yml');
 }
@@ -56,6 +57,28 @@ function writeGatewayToolsFile(dir, sources) {
     mkdirSync(dir, { recursive: true });
     writeFileSync(gatewayToolsPath(dir), stringifyYaml({ sources }));
 }
+// Re-reads and writes gateway-tools.yml fresh, not off whatever snapshot
+// the caller (connectEntry/describeGatewayTools) originally read — a
+// live resolution can take real seconds (mcpplug's per-slug CLI round
+// trips), long enough for an admin-UI edit (add/remove a slug) to land
+// in between. Merged into the source's existing `resolved`, not
+// replaced, so two overlapping resolutions of different slug subsets
+// (e.g. connectEntry resolving one newly-added slug while
+// describeGatewayTools resolves another) don't clobber each other.
+// Silently a no-op if the source itself is gone by the time this runs —
+// nothing left to persist onto.
+function persistResolvedTools(dir, sourceName, newlyResolved) {
+    if (!Object.keys(newlyResolved).length)
+        return;
+    const sources = readGatewayToolsFromDir(dir);
+    const index = sources.findIndex((s) => s.name === sourceName);
+    if (index === -1)
+        return;
+    const existing = sources[index];
+    const updated = [...sources];
+    updated[index] = { ...existing, resolved: { ...existing.resolved, ...newlyResolved } };
+    writeGatewayToolsFile(dir, updated);
+}
 export class GatewayToolExistsError extends Error {
 }
 export class GatewayToolNotFoundError extends Error {
@@ -304,21 +327,86 @@ export function removeGatewayToolSlug(agentName, sourceName, slug) {
         throw new GatewayToolNotFoundError(`No gateway tool '${slug}' registered under '${sourceName}' for '${agentName}'.`);
     }
     const remainingSlugs = sources[index].slugs.filter((s) => s !== slug);
+    // Drops the removed slug's own resolved entry too — leaving it behind
+    // would just be dead weight (nothing in `slugs` references it anymore,
+    // so it can never be read back), and would silently reappear if the
+    // exact same slug were ever re-added later, skipping what should be a
+    // fresh resolution. Omitted entirely (not `resolved: {}`) once empty —
+    // a source that never had any resolved slugs shouldn't gain a stray
+    // empty field just because one was removed from it.
+    const { [slug]: _removed, ...remainingResolved } = sources[index].resolved ?? {};
     const updated = remainingSlugs.length === 0
         ? sources.filter((_, i) => i !== index)
-        : sources.map((s, i) => (i === index ? { ...s, slugs: remainingSlugs } : s));
+        : sources.map((s, i) => {
+            if (i !== index)
+                return s;
+            const next = { ...s, slugs: remainingSlugs };
+            if (Object.keys(remainingResolved).length)
+                next.resolved = remainingResolved;
+            else
+                delete next.resolved;
+            return next;
+        });
     writeGatewayToolsFile(dir, updated);
     removeAutoAddedActauthRules(dir, [`${sources[index].name}_${slug}`]);
 }
-async function connectEntry(entry) {
+// Builds a ToolDefinition straight from gateway-tools.yml's own persisted
+// `resolved` entry — no CLI call at all for the schema/description, since
+// those are exactly what's already cached. execute() itself still always
+// shells out fresh (mirrors mcpplug's composio-source.ts own execute
+// closure exactly — resolving *what a tool is* is cacheable, actually
+// *running* it never is).
+function toolFromResolved(slug, resolved, cliCommand) {
+    return {
+        name: resolved.name,
+        description: resolved.description,
+        input_schema: resolved.input_schema,
+        execute: async (input) => {
+            const result = (await runComposioCli(cliCommand ?? 'composio', ['execute', slug, '-d', JSON.stringify(input)]));
+            if (result.successful === false || result.error) {
+                throw new Error(`composio tool ${slug} failed: ${JSON.stringify(result.error ?? result)}`);
+            }
+            return result.data ?? result;
+        },
+    };
+}
+// The only thing that still needs mcpplug/a live Composio round trip —
+// slugs with no persisted resolution yet (just registered, or a `force`
+// re-check). Returns [] without touching the CLI at all when there's
+// nothing left to resolve, which is the common case once a source's
+// slugs have all been resolved once.
+async function fetchUnresolvedSlugs(entry, slugs) {
+    if (!slugs.length)
+        return [];
+    const source = await connectComposioSource(entry.name, { slugs, cliCommand: entry.cliCommand });
+    try {
+        return await source.loadTools();
+    }
+    finally {
+        await source.close();
+    }
+}
+/** Resolves `entry` into real ToolDefinitions for run-agent.ts to merge
+ * in, preferring gateway-tools.yml's own persisted `resolved` data (see
+ * ComposioGatewayToolEntry's own doc comment) over asking Composio again —
+ * mcpplug's connectComposioSource (and the ~3s-per-slug CLI round trip it
+ * costs) is only ever invoked for slugs that aren't resolved yet. Newly
+ * resolved slugs are persisted back before returning, so the *next* call
+ * (even after a restart) skips the live fetch entirely too. */
+async function connectEntry(entry, dir) {
     if (entry.provider === 'composio') {
-        const source = await connectComposioSource(entry.name, { slugs: entry.slugs, cliCommand: entry.cliCommand });
-        try {
-            return await source.loadTools();
-        }
-        finally {
-            await source.close();
+        const resolved = entry.resolved ?? {};
+        const cachedTools = entry.slugs.filter((slug) => resolved[slug]).map((slug) => toolFromResolved(slug, resolved[slug], entry.cliCommand));
+        const unresolvedSlugs = entry.slugs.filter((slug) => !resolved[slug]);
+        const freshTools = await fetchUnresolvedSlugs(entry, unresolvedSlugs);
+        if (freshTools.length) {
+            const newlyResolved = {};
+            freshTools.forEach((tool, i) => {
+                newlyResolved[unresolvedSlugs[i]] = { name: tool.name, description: tool.description, input_schema: tool.input_schema };
+            });
+            persistResolvedTools(dir, entry.name, newlyResolved);
         }
+        return [...cachedTools, ...freshTools];
     }
     // Unreachable while GatewayToolEntry is a union of one — the check (and
     // the cast it needs) starts earning its keep the moment a second
@@ -334,9 +422,10 @@ async function connectEntry(entry) {
  * <toolkit>`) has a genuinely useful one instead (e.g. "Tool to abort a
  * repository migration that is queued or in progress. Use when you need
  * to cancel an ongoing migration operation.") — worth fetching for
- * describeGatewayTools specifically (see its own "always current worth
- * more than cheap" doc comment), an occasional, deliberate admin action.
- * Deliberately *not* applied inside connectEntry itself, even though
+ * describeGatewayTools specifically — only paid once per slug, right
+ * before persisting it (see ComposioGatewayToolEntry's own `resolved`
+ * doc comment), not on every load. Deliberately *not* applied inside
+ * connectEntry itself, even though
  * that would also improve what the model actually sees at runtime —
  * connectEntry is loadGatewayToolsFromDir's hot path, and that function's
  * own doc comment already explicitly rejects paying any extra
@@ -378,18 +467,41 @@ async function withRealComposioDescriptions(tools, slugs, cliCommand) {
  * function surfaces it explicitly, per source, since an operator looking
  * at this page needs to know *which* source is broken and why — where
  * loadGatewayToolsFromDir just logs and drops it, since runAgent() has no
- * structured place to hand a per-source error to. Deliberately bypasses
- * loadGatewayToolsFromDir's mtime cache — this is an occasional,
- * deliberate operator action, not a per-turn hot path, so "always
- * current" is worth more here than "cheap." */
-export async function describeGatewayTools(agentName) {
+ * structured place to hand a per-source error to.
+ *
+ * No in-memory cache here (or anywhere in this file, for this) — the
+ * cache *is* gateway-tools.yml's own `resolved` field (see
+ * ComposioGatewayToolEntry's own doc comment and connectEntry, which this
+ * shares that field with), so it survives a restart instead of being
+ * lost on one. Only genuinely-unresolved slugs pay for a live fetch, and
+ * for those this still enriches with Composio's real catalog description
+ * (see withRealComposioDescriptions) before persisting — unlike
+ * connectEntry, which doesn't (see that function's own reasoning), this
+ * is an occasional operator action, not runAgent()'s hot path, so paying
+ * for the better description once, at resolution time, is worth it here.
+ * Pass `force: true` (the admin page's own "Refresh" button) to treat
+ * every slug as unresolved and overwrite their persisted entries with a
+ * fresh live check — e.g. after reconnecting an account, or on the rare
+ * chance a schema changed upstream without gateway-tools.yml itself
+ * changing. */
+export async function describeGatewayTools(agentName, options = {}) {
+    const dir = agentDir(agentName);
     const entries = readGatewayTools(agentName);
     return Promise.all(entries.map(async (entry) => {
         try {
-            const rawTools = await connectEntry(entry);
-            // See withRealComposioDescriptions' own doc comment for why this
-            // enrichment happens here, not inside connectEntry itself.
-            const tools = entry.provider === 'composio' ? await withRealComposioDescriptions(rawTools, entry.slugs, entry.cliCommand) : rawTools;
+            const resolved = entry.resolved ?? {};
+            const cachedTools = options.force ? [] : entry.slugs.filter((slug) => resolved[slug]).map((slug) => toolFromResolved(slug, resolved[slug], entry.cliCommand));
+            const unresolvedSlugs = options.force ? entry.slugs : entry.slugs.filter((slug) => !resolved[slug]);
+            const rawFreshTools = await fetchUnresolvedSlugs(entry, unresolvedSlugs);
+            const freshTools = entry.provider === 'composio' ? await withRealComposioDescriptions(rawFreshTools, unresolvedSlugs, entry.cliCommand) : rawFreshTools;
+            if (freshTools.length) {
+                const newlyResolved = {};
+                freshTools.forEach((tool, i) => {
+                    newlyResolved[unresolvedSlugs[i]] = { name: tool.name, description: tool.description, input_schema: tool.input_schema };
+                });
+                persistResolvedTools(dir, entry.name, newlyResolved);
+            }
+            const tools = [...cachedTools, ...freshTools];
             return { entry, status: 'ok', tools: tools.map((t) => ({ name: t.name, description: t.description })) };
         }
         catch (err) {
@@ -435,7 +547,7 @@ export async function loadGatewayToolsFromDir(dir) {
     const entries = readGatewayToolsFromDir(dir);
     const resolved = await Promise.all(entries.map(async (entry) => {
         try {
-            return await connectEntry(entry);
+            return await connectEntry(entry, dir);
         }
         catch (err) {
             console.error(`[gateway-tools] source '${entry.name}' (${entry.provider}) failed to load, skipping: ${err instanceof Error ? err.message : String(err)}`);
@@ -542,7 +654,7 @@ export async function getComposioAuthStatus(cliCommand = 'composio') {
  * Composio's own documented path is plain, interactive `composio login`
  * (opens a browser) after installing the CLI — not something a web
  * request can drive, so the Gateways panel shows that as instructions
- * instead of a form; see its own comment in adapters/global-config-page.ts. */
+ * instead of a form; see its own comment in web/global-config-page.ts. */
 export async function disconnectComposioAccount(cliCommand = 'composio') {
     await execFileAsync(cliCommand, ['logout']);
 }

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. */