loopengine 0.0.18 → 0.0.20

package/README.md

@@ -4,7 +4,7 @@
 
 LoopEngine is a runtime for building AI agents: a persona, a set of tools,
 and permission rules, run through a transparent ReAct loop. No chain DSL,
-no hidden control flow — `run-agent.ts` is a single function you can read
+no hidden control flow — `core/run-agent.ts` is a single function you can read
 top to bottom. Run agents over a CLI, an HTTP API, or both.
 
 Once you define an agent, the loop turns it into something you can put in
@@ -37,7 +37,7 @@ npx create-loopengine@latest my-agents
 cd my-agents
 npm install
 cp .env.example .env   # fill in ANTHROPIC_API_KEY
-npm run dev             # HTTP server on :8787
+npm run dev             # HTTP server on :8787 — same as `npx loopengine dev`
 ```
 
 This scaffolds a standalone project — its own repo, with `loopengine` as
@@ -96,7 +96,7 @@ working examples.
 
 ### 1. The Loop
 
-`run-agent.ts` is the whole engine — a single, readable ReAct loop with no
+`core/run-agent.ts` is the whole engine — a single, readable ReAct loop with no
 hidden control flow: call the model, act on what it asks for, repeat.
 
 1. Call the model with the conversation so far.
@@ -338,6 +338,37 @@ starting an anonymous session). Without it, the caller just supplies a
 
 ## Running an agent
 
+`adapters/cli.ts` and `adapters/http.ts` are files your own scaffolded
+project owns (see "Quick start" above), not something hidden inside the
+`loopengine` package — run them directly with `tsx`, or through shorter
+`loopengine` commands that just call the same files for you:
+
+```bash
+npx loopengine run customer-service --session s1 "order A-1001 arrived broken"
+npx loopengine run customer-service --session s1 --input "order A-1001 arrived broken"
+npx loopengine serve   # HTTP server on :8787
+npx loopengine dev     # same server, restarts on file changes (tsx watch)
+```
+
+`--session <id>` is just an arbitrary string you pick — `s1` above isn't
+special, it's only a label. Omit it entirely for a fresh, one-off
+conversation each call; reuse the same value on a later call to continue
+that exact conversation (the id is printed to stderr if you omit it, so
+you can capture it for next time). `--input "<message>"` is an
+alternative to the trailing positional message, for scripts that build
+the argument list programmatically and would rather not depend on the
+message always being the last argument.
+
+`run`/`serve`/`dev` are thin wrappers, not a separate implementation —
+each shells out to your project's own `adapters/cli.ts` or
+`adapters/http.ts` via `npx tsx` (so it's always *your* copy that runs,
+edits included, resolved from your project's own `node_modules`), and
+fails with a clear message pointing at `create-loopengine` if that file
+doesn't exist yet. `.env` is loaded automatically for all three,
+equivalent to passing `--env-file-if-exists=.env` to `tsx` yourself.
+
+The same thing, spelled out without the wrapper:
+
 **CLI:**
 
 ```bash

package/core/system-skills/composio-large-outputs/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: composio-large-outputs
+description: How to retrieve a gateway tool's real output when its result says storedInFile is true instead of returning the data inline.
+---
+
+# Gateway tools with a large result
+
+Some gateway tools (Composio-sourced ones in particular) return a small
+pointer object instead of their real output when the actual result is
+too large to return inline:
+
+```
+{
+  "successful": true,
+  "storedInFile": true,
+  "tokenCount": 10234,
+  "outputFilePath": "/tmp/.../SOME_TOOL_OUTPUT_xxxxx.json"
+}
+```
+
+When you see `storedInFile: true` in a tool result, the real data is
+**not** in that object — it's in the file at `outputFilePath`. Call
+`system_read_file` with that exact path to retrieve the actual content
+before answering. Don't guess at an answer, summarize from the pointer
+alone, or claim you don't have the data — read the file first.

package/dist/{cli.d.ts → bin/cli.d.ts}

@@ -5,19 +5,39 @@ export declare class AgentExistsError extends Error {
 }
 export declare class AgentNotFoundError extends Error {
 }
-export declare function agentIndexTemplate(name: string): string;
+export declare class AgentModelError extends Error {
+}
+type Provider = 'anthropic' | 'openai' | 'deepseek';
+export interface AgentTemplateOptions {
+    systemPrompt?: string;
+    model?: {
+        provider: Provider;
+        model?: string;
+    };
+}
+/** Generates agents/<name>/index.ts's real content. `options` is
+ * entirely optional and defaults to exactly what this template always
+ * wrote before it existed ('You are ...', anthropic/claude-sonnet-5) —
+ * `loopengine add-agent <name>` (which never passes it) produces
+ * byte-identical output to before this existed. openai/deepseek have no
+ * default model (only anthropic's is optional — see AgentModelConfig's
+ * own doc comment), so scaffoldAgent validates a model name was given
+ * for those rather than this function silently writing a wrong one. */
+export declare function agentIndexTemplate(name: string, options?: AgentTemplateOptions, importSpecifier?: string): string;
 /** Same shape as agentIndexTemplate, plus `toolDescription` — the one
  * field a subagent needs that a top-level agent doesn't. run-agent.ts's
  * loadSubagentAsTools wraps this config with agentAsTool, which throws
  * without a real toolDescription: it's what the parent agent's model
  * reads to decide when to delegate here, and systemPrompt (instructions
  * for this agent itself) isn't a substitute. See agent-as-tool.ts. */
-export declare function subagentIndexTemplate(name: string): string;
+export declare function subagentIndexTemplate(name: string, importSpecifier?: string): string;
 /** Writes agents/<name>/index.ts under baseDir and returns its path.
  * Only that one file — tools, rules, and skillsDirs are left to their
  * smart defaults (see AgentConfig's own doc comments), the same as the
- * README's own "simplest possible agent" example. */
-export declare function scaffoldAgent(baseDir: string, name: string): Promise<string>;
+ * README's own "simplest possible agent" example. `options` (systemPrompt,
+ * model) is entirely optional — see agentIndexTemplate's own doc comment
+ * for the defaults used when omitted. */
+export declare function scaffoldAgent(baseDir: string, name: string, options?: AgentTemplateOptions): Promise<string>;
 /** Writes <parentDir>/subagents/<name>/index.ts under baseDir and
  * returns its path, where <parentDir> is `parent` resolved by
  * resolveParentDir — the folder convention run-agent.ts's
@@ -29,3 +49,4 @@ export declare function scaffoldAgent(baseDir: string, name: string): Promise<st
  * scaffoldAgent already covers. Nesting more than one level is just
  * `parent` itself being a path — see resolveParentDir. */
 export declare function scaffoldSubagent(baseDir: string, parent: string, name: string): Promise<string>;
+export {};

package/dist/{cli.js → bin/cli.js}

@@ -9,7 +9,7 @@
 // these stay thin wrappers around those files rather than a built-in
 // runner/server this package hides inside itself.
 import { realpathSync } from 'node:fs';
-import { access, mkdir, writeFile } from 'node:fs/promises';
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -20,13 +20,61 @@ export class AgentExistsError extends Error {
 }
 export class AgentNotFoundError extends Error {
 }
-export function agentIndexTemplate(name) {
-    return `import type { AgentConfig } from 'loopengine'
+export class AgentModelError extends Error {
+}
+const MODEL_ENV_VAR = {
+    anthropic: 'ANTHROPIC_API_KEY',
+    openai: 'OPENAI_API_KEY',
+    deepseek: 'DEEPSEEK_API_KEY',
+};
+// Escapes a value for safe interpolation into a single-quoted TS string
+// literal in generated code — an operator-supplied systemPrompt (from
+// the admin UI's Create new agent form, say) containing a literal quote
+// or backslash would otherwise produce invalid, or silently different,
+// generated TypeScript.
+function tsStringLiteral(value) {
+    return "'" + value.replace(/\\/g, '\\\\').replace(/'/g, "\\'") + "'";
+}
+/** 'loopengine' for a real consumer project — the only thing that ever
+ * resolves once this package is genuinely installed as a dependency. A
+ * checkout of this repo itself has no such install (see this repo's own
+ * git history around the reverted self-link attempt: pointing
+ * node_modules/loopengine back at itself collides with tsc trying to
+ * write dist/ while also reading it as an input), so a file scaffolded
+ * *into this repo* — an agent created via `loopengine dev`'s admin UI
+ * while hacking on loopengine itself, say — needs the same internal
+ * alias every hand-maintained demo agent here already uses instead.
+ * Detected by baseDir's own package.json name rather than a flag the
+ * caller has to remember to pass, so this can never drift out of sync
+ * with which project is actually being scaffolded into. */
+async function configImportSpecifier(baseDir) {
+    try {
+        const raw = await readFile(path.join(baseDir, 'package.json'), 'utf8');
+        const pkg = JSON.parse(raw);
+        return pkg.name === 'loopengine' ? '#core/agent-config.js' : 'loopengine';
+    }
+    catch {
+        return 'loopengine';
+    }
+}
+/** Generates agents/<name>/index.ts's real content. `options` is
+ * entirely optional and defaults to exactly what this template always
+ * wrote before it existed ('You are ...', anthropic/claude-sonnet-5) —
+ * `loopengine add-agent <name>` (which never passes it) produces
+ * byte-identical output to before this existed. openai/deepseek have no
+ * default model (only anthropic's is optional — see AgentModelConfig's
+ * own doc comment), so scaffoldAgent validates a model name was given
+ * for those rather than this function silently writing a wrong one. */
+export function agentIndexTemplate(name, options = {}, importSpecifier = 'loopengine') {
+    const systemPrompt = options.systemPrompt?.trim() || 'You are ...';
+    const provider = options.model?.provider ?? 'anthropic';
+    const modelName = options.model?.model?.trim() || (provider === 'anthropic' ? 'claude-sonnet-5' : '');
+    return `import type { AgentConfig } from '${importSpecifier}'
 
 export const config: AgentConfig = {
   name: '${name}',
-  systemPrompt: 'You are ...',
-  model: { provider: 'anthropic', model: 'claude-sonnet-5' }, // reads ANTHROPIC_API_KEY
+  systemPrompt: ${tsStringLiteral(systemPrompt)},
+  model: { provider: '${provider}', model: ${tsStringLiteral(modelName)} }, // reads ${MODEL_ENV_VAR[provider]}
 }
 `;
 }
@@ -36,8 +84,8 @@ export const config: AgentConfig = {
  * without a real toolDescription: it's what the parent agent's model
  * reads to decide when to delegate here, and systemPrompt (instructions
  * for this agent itself) isn't a substitute. See agent-as-tool.ts. */
-export function subagentIndexTemplate(name) {
-    return `import type { AgentConfig } from 'loopengine'
+export function subagentIndexTemplate(name, importSpecifier = 'loopengine') {
+    return `import type { AgentConfig } from '${importSpecifier}'
 
 export const config: AgentConfig = {
   name: '${name}',
@@ -50,18 +98,24 @@ export const config: AgentConfig = {
 /** Writes agents/<name>/index.ts under baseDir and returns its path.
  * Only that one file — tools, rules, and skillsDirs are left to their
  * smart defaults (see AgentConfig's own doc comments), the same as the
- * README's own "simplest possible agent" example. */
-export async function scaffoldAgent(baseDir, name) {
+ * README's own "simplest possible agent" example. `options` (systemPrompt,
+ * model) is entirely optional — see agentIndexTemplate's own doc comment
+ * for the defaults used when omitted. */
+export async function scaffoldAgent(baseDir, name, options = {}) {
     if (!NAME_PATTERN.test(name)) {
         throw new AgentNameError(`Agent name must be lowercase, alphanumeric, hyphen-separated (e.g. "weather-agent") — got "${name}"`);
     }
+    const provider = options.model?.provider ?? 'anthropic';
+    if (provider !== 'anthropic' && !options.model?.model?.trim()) {
+        throw new AgentModelError(`A model name is required for provider '${provider}' — only anthropic has a default (claude-sonnet-5).`);
+    }
     const dir = path.join(baseDir, 'agents', name);
     const indexPath = path.join(dir, 'index.ts');
     if (await pathExists(indexPath)) {
         throw new AgentExistsError(`agents/${name}/index.ts already exists — pick a different name or edit it directly.`);
     }
     await mkdir(dir, { recursive: true });
-    await writeFile(indexPath, agentIndexTemplate(name));
+    await writeFile(indexPath, agentIndexTemplate(name, options, await configImportSpecifier(baseDir)));
     return indexPath;
 }
 /** Resolves `parent` — a single agent name, or a `/`-joined path of
@@ -105,7 +159,7 @@ export async function scaffoldSubagent(baseDir, parent, name) {
         throw new AgentExistsError(`A subagent named '${name}' already exists under '${parent}' (${indexPath}) — pick a different name or edit it directly.`);
     }
     await mkdir(dir, { recursive: true });
-    await writeFile(indexPath, subagentIndexTemplate(name));
+    await writeFile(indexPath, subagentIndexTemplate(name, await configImportSpecifier(baseDir)));
     return indexPath;
 }
 async function pathExists(p) {
@@ -130,8 +184,32 @@ async function pathExists(p) {
 function runTsx(args) {
     return new Promise((resolve) => {
         const child = spawn('npx', ['tsx', ...args], { cwd: process.cwd(), stdio: 'inherit' });
-        child.on('exit', (code) => resolve(code ?? 1));
-        child.on('error', () => resolve(1));
+        // `stdio: 'inherit'` with no `detached` puts this child in the same
+        // foreground process group as this process itself — so a terminal's
+        // Ctrl+C delivers SIGINT to *both* at once, not just to this process
+        // for it to relay. Node's default disposition for an unhandled
+        // SIGINT/SIGTERM is to terminate immediately — without a listener,
+        // this process would die right then, before ever observing the
+        // child's own 'exit' below. That's a real bug, not cosmetic: this
+        // process is the shell's *direct* child, so the shell returns control
+        // as soon as it exits — but the child (tsx watch, itself possibly
+        // still killing *its* own child, adapters/http.ts) can still be alive
+        // for a moment after, orphaned but still attached to the same TTY.
+        // A plain no-op listener is enough to opt out of that default
+        // immediate-termination behavior — the child already gets the same
+        // signal directly (same process group), nothing needs forwarding —
+        // so this just keeps this process alive long enough to actually see
+        // the child finish, and exit in step with it instead of ahead of it.
+        const noop = () => { };
+        process.on('SIGINT', noop);
+        process.on('SIGTERM', noop);
+        function settle(result) {
+            process.off('SIGINT', noop);
+            process.off('SIGTERM', noop);
+            resolve(result);
+        }
+        child.on('exit', (code) => settle(code ?? 1));
+        child.on('error', () => settle(1));
     });
 }
 /** run/serve/dev all delegate to a file the *project* owns (created by
@@ -203,17 +281,38 @@ async function main() {
     // adapters/cli.ts's own contract (see its own header comment), not a
     // REPL. `rest` after `<agent>` is forwarded through as-is (--session,
     // the message, and any future flag that file grows), so this wrapper
-    // never needs to change in step with adapters/cli.ts's own arg parsing.
+    // never needs to change in step with adapters/cli.ts's own arg parsing
+    // — except --input, which is this wrapper's own convenience flag, not
+    // adapters/cli.ts's: that file only understands --agent/--session plus
+    // one trailing positional message (see its own parseArgs, which joins
+    // every non-flag arg back into one string), so --input's value is
+    // translated into that positional form before forwarding, rather than
+    // taught to adapters/cli.ts itself. Exists for callers building the
+    // arg list programmatically, where getting a trailing positional's
+    // exact position right (after --session, after --agent, ...) is easy
+    // to get wrong; an explicit flag has no position to get wrong.
     if (command === 'run') {
         const [agent, ...forward] = rest;
         if (!agent) {
             console.error('Usage: loopengine run <agent> [--session <id>] "<message>"');
+            console.error('       loopengine run <agent> [--session <id>] --input "<message>"');
             process.exitCode = 1;
             return;
         }
         if (!(await requireAdapterFile('adapters/cli.ts')))
             return;
-        process.exitCode = await runTsx(['--env-file-if-exists=.env', 'adapters/cli.ts', '--agent', agent, ...forward]);
+        let finalArgs = forward;
+        const inputIndex = forward.indexOf('--input');
+        if (inputIndex !== -1) {
+            const message = forward[inputIndex + 1];
+            if (message === undefined) {
+                console.error('--input requires a value.');
+                process.exitCode = 1;
+                return;
+            }
+            finalArgs = [...forward.slice(0, inputIndex), ...forward.slice(inputIndex + 2), message];
+        }
+        process.exitCode = await runTsx(['--env-file-if-exists=.env', 'adapters/cli.ts', '--agent', agent, ...finalArgs]);
         return;
     }
     // Serves every registered agent at once (adapters/http.ts has no
@@ -234,10 +333,26 @@ async function main() {
     // read fresh off disk every call regardless (no restart needed for
     // those even under plain `serve`) — this is for the TS source itself:
     // a new tool file, an edited AgentConfig, ...
+    //
+    // --include 'agents/*/index.ts' is deliberately narrow, not a blanket
+    // 'agents/**' — tsx watch on its own only tracks the actual ES module
+    // graph, so a *new* agents/<name>/index.ts (e.g. from the admin UI's
+    // "Create new agent," or from `loopengine add-agent`) wouldn't
+    // otherwise trigger a restart at all: core/agent-registry.ts discovers
+    // agents once via a top-level `readdirSync` (see discover-agents.ts),
+    // not an import, so tsx's watcher has no static edge to that new file
+    // until this flag adds one. A wider 'agents/**' would also match
+    // gateway-tools.yml/actauth.yml/skills/*.md — restarting the whole
+    // server (dropping in-flight sessions) on every admin-UI edit to
+    // those, which is exactly the "no restart needed" behavior this repo
+    // went out of its way to build for them elsewhere. Confirmed live
+    // (both directions) before landing this: editing gateway-tools.yml
+    // under this exact glob triggers no restart; adding a new
+    // agents/<name>/index.ts does.
     if (command === 'dev') {
         if (!(await requireAdapterFile('adapters/http.ts')))
             return;
-        process.exitCode = await runTsx(['watch', '--env-file-if-exists=.env', 'adapters/http.ts', ...rest]);
+        process.exitCode = await runTsx(['watch', '--include', 'agents/*/index.ts', '--env-file-if-exists=.env', 'adapters/http.ts', ...rest]);
         return;
     }
     console.error('Usage: loopengine add-agent <name>');

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

@@ -1,5 +1,5 @@
-import type { AgentConfig, ToolDefinition } from '#agent-config.js';
-import { type ModelCall } from '#run-agent.js';
+import type { AgentConfig, ToolDefinition } from '#core/agent-config.js';
+import { type ModelCall } from '#core/run-agent.js';
 /** `createModelCall` is a factory, not a shared instance — the same
  * `AgentModule.createModelCall` contract discover-agents.ts already
  * uses, so each call to the returned tool gets its own ModelCall rather

package/dist/{agent-as-tool.js → core/agent-as-tool.js}

@@ -1,4 +1,4 @@
-import { runAgent } from '#run-agent.js';
+import { runAgent } from '#core/run-agent.js';
 /** `createModelCall` is a factory, not a shared instance — the same
  * `AgentModule.createModelCall` contract discover-agents.ts already
  * uses, so each call to the returned tool gets its own ModelCall rather

package/dist/core/client.d.ts

@@ -0,0 +1,113 @@
+import type { LoopEvent } from './loop-events.js';
+import type { Message } from './run-agent.js';
+export interface RequestOptions {
+    /** Resumes an existing conversation — omit for a fresh one; see
+     * adapters/http.ts's own sessionIdFor for how the server derives one
+     * when omitted. */
+    sessionId?: string;
+    /** Extra headers on top of 'content-type: application/json' — e.g. HTTP
+     * Basic Auth (LOOPENGINE_ADMIN_AUTH) or an AgentConfig.tenantFor header. */
+    headers?: Record<string, string>;
+    /** Merged into the request body alongside `message`/`sessionId` — for an
+     * AgentConfig with its own sessionIdFor/tenantFor reading extra fields
+     * (see adapters/http.ts's own resolveTenant). */
+    body?: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+/** POST /agents/:name/messages's own 200 response — the turn finished,
+ * genuinely or via a synthetic stopReason (see loop-events.ts's own
+ * DoneEvent). `events` is every LoopEvent this turn produced, start to
+ * finish — the same array a streamed turn delivers frame-by-frame. */
+export interface SendMessageResult {
+    text: string;
+    sessionId: string;
+    events: LoopEvent[];
+    stopReason?: 'max_turns' | 'denied';
+}
+interface PendingResultBase {
+    pending: true;
+    id: string;
+    sessionId: string;
+    events: LoopEvent[];
+    /** GET this to rehydrate the conversation (and re-discover this same
+     * pending item) if the caller navigates away before deciding it. */
+    statusUrl: string;
+}
+/** POST /agents/:name/messages's own 202 response when the turn needs a
+ * human 'ask' decision before it can continue — resolve it with
+ * approveCall/denyCall below, both of which return this same
+ * MessageResult union, so a caller can treat approve/deny/answer and the
+ * original send as one uniform decide-or-finish loop. */
+export interface PendingApprovalResult extends PendingResultBase {
+    type: 'approval';
+    tool: string;
+    args: Record<string, unknown>;
+    scope: {
+        tenant: string;
+        environment: string;
+        agent: string;
+    };
+    reason: string;
+    approveUrl: string;
+    denyUrl: string;
+}
+/** Same as PendingApprovalResult, for the system ask_user tool's own
+ * open-ended question instead of a fixed allow/deny — resolve with
+ * answerQuestion below. */
+export interface PendingQuestionResult extends PendingResultBase {
+    type: 'question';
+    question: string;
+    options?: string[];
+    answerUrl: string;
+}
+export type PendingResult = PendingApprovalResult | PendingQuestionResult;
+export type MessageResult = SendMessageResult | PendingResult;
+/** The non-streaming half of the protocol — one request, one response,
+ * either done (SendMessageResult) or needing a decision (PendingResult).
+ * Reach for this over streamMessage() when the caller doesn't need live,
+ * frame-by-frame updates (a bot integration, a batch job, a callback-
+ * style webhook handler) — same underlying turn, same event vocabulary in
+ * `events`, just delivered all at once instead of incrementally. */
+export declare function sendMessage(baseUrl: string, agent: string, message: string, options?: RequestOptions): Promise<MessageResult>;
+export declare function approveCall(baseUrl: string, id: string, options?: RequestOptions): Promise<MessageResult>;
+export declare function denyCall(baseUrl: string, id: string, options?: RequestOptions): Promise<MessageResult>;
+export declare function answerQuestion(baseUrl: string, id: string, answer: string, options?: RequestOptions): Promise<MessageResult>;
+/** GET /agents/:name/sessions/:id — rehydrates a conversation's stored
+ * history, e.g. after a page reload lost whatever in-memory state a React/
+ * Vue app was holding (mirrors web/playground.ts's own resumeSession). */
+export declare function getSessionHistory(baseUrl: string, agent: string, sessionId: string, options?: Pick<RequestOptions, 'headers' | 'signal'>): Promise<{
+    sessionId: string;
+    history: Message[];
+}>;
+/** The streaming half of the protocol — an async generator yielding one
+ * LoopEvent per SSE frame as it arrives, always starting with `session`
+ * and ending with `done` or `error` (see loop-events.ts's own header
+ * comment). `for await` is the natural fit for a React effect or Vue
+ * composable driving off this directly:
+ *
+ *   for await (const event of streamMessage(baseUrl, agent, text, { signal })) {
+ *     setEvents((prev) => [...prev, event])
+ *     if (event.type === 'done' || event.type === 'error') break
+ *   }
+ *
+ * Pass an AbortController's signal to let the caller cancel mid-stream
+ * (a React effect's own cleanup, a Vue component's onUnmounted) — the
+ * underlying fetch is aborted and the generator simply stops yielding,
+ * same as any other AbortSignal-aware fetch call.
+ */
+export declare function streamMessage(baseUrl: string, agent: string, message: string, options?: RequestOptions): AsyncGenerator<LoopEvent, void, void>;
+export interface StreamMessageCallbacks {
+    onEvent?: (event: LoopEvent) => void;
+    onDone?: (event: Extract<LoopEvent, {
+        type: 'done';
+    }>) => void;
+    onError?: (event: Extract<LoopEvent, {
+        type: 'error';
+    }>) => void;
+}
+/** Callback-flavored wrapper over streamMessage() for a caller that would
+ * rather pass handlers into a `useEffect`/lifecycle hook than manage a
+ * `for await` loop and its own break condition by hand. Resolves once the
+ * stream ends (a 'done'/'error' event, or the connection just closing). */
+export declare function streamMessageWithCallbacks(baseUrl: string, agent: string, message: string, options: RequestOptions, callbacks: StreamMessageCallbacks): Promise<void>;
+export {};

package/dist/core/client.js

@@ -0,0 +1,123 @@
+async function postJson(url, body, options = {}) {
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...options.headers },
+        body: JSON.stringify(body),
+        signal: options.signal,
+    });
+    const parsed = (await res.json().catch(() => ({ error: `HTTP ${res.status}` })));
+    if (!res.ok)
+        throw new Error(parsed.error ?? `HTTP ${res.status}`);
+    return parsed;
+}
+function messageBody(message, options) {
+    return { message, ...(options.sessionId ? { sessionId: options.sessionId } : {}), ...options.body };
+}
+/** The non-streaming half of the protocol — one request, one response,
+ * either done (SendMessageResult) or needing a decision (PendingResult).
+ * Reach for this over streamMessage() when the caller doesn't need live,
+ * frame-by-frame updates (a bot integration, a batch job, a callback-
+ * style webhook handler) — same underlying turn, same event vocabulary in
+ * `events`, just delivered all at once instead of incrementally. */
+export function sendMessage(baseUrl, agent, message, options = {}) {
+    return postJson(`${baseUrl}/agents/${encodeURIComponent(agent)}/messages`, messageBody(message, options), options);
+}
+export function approveCall(baseUrl, id, options = {}) {
+    return postJson(`${baseUrl}/approvals/${encodeURIComponent(id)}/approve`, undefined, options);
+}
+export function denyCall(baseUrl, id, options = {}) {
+    return postJson(`${baseUrl}/approvals/${encodeURIComponent(id)}/deny`, undefined, options);
+}
+export function answerQuestion(baseUrl, id, answer, options = {}) {
+    return postJson(`${baseUrl}/questions/${encodeURIComponent(id)}/answer`, { answer }, options);
+}
+/** GET /agents/:name/sessions/:id — rehydrates a conversation's stored
+ * history, e.g. after a page reload lost whatever in-memory state a React/
+ * Vue app was holding (mirrors web/playground.ts's own resumeSession). */
+export async function getSessionHistory(baseUrl, agent, sessionId, options = {}) {
+    const res = await fetch(`${baseUrl}/agents/${encodeURIComponent(agent)}/sessions/${encodeURIComponent(sessionId)}`, {
+        headers: options.headers,
+        signal: options.signal,
+    });
+    const body = (await res.json());
+    if (!res.ok)
+        throw new Error(body.error ?? `HTTP ${res.status}`);
+    return body;
+}
+function parseSseFrame(frame) {
+    let dataLine = '';
+    for (const line of frame.split('\n')) {
+        if (line.startsWith('data: '))
+            dataLine = line.slice('data: '.length);
+    }
+    if (!dataLine)
+        return undefined;
+    try {
+        return JSON.parse(dataLine);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The streaming half of the protocol — an async generator yielding one
+ * LoopEvent per SSE frame as it arrives, always starting with `session`
+ * and ending with `done` or `error` (see loop-events.ts's own header
+ * comment). `for await` is the natural fit for a React effect or Vue
+ * composable driving off this directly:
+ *
+ *   for await (const event of streamMessage(baseUrl, agent, text, { signal })) {
+ *     setEvents((prev) => [...prev, event])
+ *     if (event.type === 'done' || event.type === 'error') break
+ *   }
+ *
+ * Pass an AbortController's signal to let the caller cancel mid-stream
+ * (a React effect's own cleanup, a Vue component's onUnmounted) — the
+ * underlying fetch is aborted and the generator simply stops yielding,
+ * same as any other AbortSignal-aware fetch call.
+ */
+export async function* streamMessage(baseUrl, agent, message, options = {}) {
+    const res = await fetch(`${baseUrl}/agents/${encodeURIComponent(agent)}/messages/stream`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...options.headers },
+        body: JSON.stringify(messageBody(message, options)),
+        signal: options.signal,
+    });
+    const contentType = res.headers.get('content-type') ?? '';
+    if (!contentType.includes('text/event-stream')) {
+        const body = (await res.json().catch(() => ({ error: `HTTP ${res.status}` })));
+        yield { type: 'error', error: body.error ?? `HTTP ${res.status}` };
+        return;
+    }
+    if (!res.body)
+        return;
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        let idx;
+        while ((idx = buffer.indexOf('\n\n')) !== -1) {
+            const frame = buffer.slice(0, idx);
+            buffer = buffer.slice(idx + 2);
+            const event = parseSseFrame(frame);
+            if (event)
+                yield event;
+        }
+    }
+}
+/** Callback-flavored wrapper over streamMessage() for a caller that would
+ * rather pass handlers into a `useEffect`/lifecycle hook than manage a
+ * `for await` loop and its own break condition by hand. Resolves once the
+ * stream ends (a 'done'/'error' event, or the connection just closing). */
+export async function streamMessageWithCallbacks(baseUrl, agent, message, options, callbacks) {
+    for await (const event of streamMessage(baseUrl, agent, message, options)) {
+        callbacks.onEvent?.(event);
+        if (event.type === 'done')
+            callbacks.onDone?.(event);
+        else if (event.type === 'error')
+            callbacks.onError?.(event);
+    }
+}