@venturekit-pro/ai 0.0.48 → 0.0.50

package/README.md

@@ -33,6 +33,11 @@ npm install @pinecone-database/pinecone
 - **Vector stores** — store and query vectors with Pinecone, pgvector, or in-memory
 - **RAG pipelines** — chunking, retrieval, and context building for retrieval-augmented generation
 - **Agents** — AI agents with tool use via OpenAI function calling
+- **`generate`** — one provider-neutral model call (Anthropic, OpenAI, Gemini, Perplexity's Agent API): function tools, native web search with citations, structured output, file inputs, prompt caching, streaming (Perplexity: one-shot only)
+- **LLM gateway** — the single call path: routing (tiers, fallbacks), catalog prices, policies, credentials, retries, cost ledger and audit trail
+- **Agent loop** — a bounded tool-use loop on the gateway (`runAgent`)
+- **Harness** — durable, versioned graphs of nodes on Postgres: retries, gates, map nodes, cancellation, budgets, events
+- **Tracing** — OpenTelemetry GenAI spans through any tracer you pass
 
 ## Embeddings
 
@@ -135,6 +140,193 @@ console.log(result.output, result.usage, result.cost);
 Pair with `withFallback` / `retryWithBackoff` from the fallback module to add
 primary→backup routing or exponential-backoff retries.
 
+## LLM Gateway
+
+Every text-model call of an app goes through one gateway, which, per call:
+routes (`[model, ...fallbacks]`, or a `tier` mapped by `route`) → resolves
+the catalog key (prices, max tokens, timeout) → runs the policies (a denial
+skips to the next candidate; a policy that throws denies) → gets the API key
+(platform or the tenant's own) → calls with retries on 429 / 5xx, then falls
+back → records one ledger row per billed call and one audit row per call.
+
+```typescript
+import { createLlmGateway, createPostgresGatewaySinks, budgetPolicy, tierRoute } from '@venturekit-pro/ai';
+
+const gateway = createLlmGateway({
+  catalog: { find: (key) => catalog.get(key) }, // ModelDescriptor by catalog key
+  credentials: ({ context, model }) => ({ apiKey: keyFor(context.tenantId, model.provider), source: 'platform' }),
+  policies: [budgetPolicy({ check: async (ctx) => ({ allowed: await hasCredits(ctx.tenantId) }) })],
+  sinks: createPostgresGatewaySinks(query, { retentionDays: 90 }),
+  route: tierRoute({ resolve: ({ tier, context }) => tierKeys(context.tenantId, tier) }),
+});
+
+const answer = await gateway.generate(
+  { tenantId, feature: 'support-reply', correlationId: `ticket:${ticketId}` },
+  {
+    model: 'claude-sonnet', // a catalog key — or `tier: 'balanced'`
+    fallbacks: ['gpt-mini'],
+    messages: [
+      { role: 'system', content: KERNEL_AND_BRAND, cache: true }, // cache the stable prefix
+      { role: 'user', content: question },
+    ],
+    webSearch: { maxUses: 3 },
+    responseFormat: { type: 'json_schema', name: 'reply', schema: replySchema },
+  },
+);
+// answer.text / .json / .toolCalls / .citations / .usage / .cost / .attempts
+```
+
+- **Streaming** — `gateway.stream(context, request)` yields `text`, `tool_call`
+  and `search` events, then one `done` with the priced, recorded result.
+  Retries and fallbacks only happen before the first event.
+- **Prompt caching** — `cache: true` on a message marks the end of the stable
+  prefix (Anthropic `cache_control`, 5 minutes or `cache: { ttl: '1h' }`);
+  OpenAI and Gemini cache prefixes on their own (`cache: { key }` becomes
+  OpenAI's `prompt_cache_key`). Cache reads and writes come back in the usage
+  and are priced from the catalog (`cost_per_1k_cached_input`,
+  `cost_per_1k_cache_write`, `cost_per_1k_cache_write_1h`).
+- `listLlmCalls(query, { correlationId })` reads the audit trail of an
+  operation; `purgeExpiredLlmCalls(query)` deletes rows past their retention.
+
+## Agent Loop
+
+A bounded tool loop on the gateway: the model calls tools (and native web
+search) until it answers or a step / tool-call / cost / time limit makes it
+wrap up with one last call.
+
+```typescript
+import { runAgent, defineAgentTool, toolResult } from '@venturekit-pro/ai';
+
+const lookup = defineAgentTool<{ query: string }>({
+  definition: { name: 'lookup', description: 'Search our articles', inputSchema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] } },
+  parse: (args) => ({ query: String(args.query) }),
+  execute: async ({ query }) => toolResult({ content: await searchArticles(query), data: { query } }),
+});
+
+const result = await runAgent({
+  client: gateway.client({ tenantId, feature: 'research' }),
+  request: { model: 'claude-sonnet', webSearch: { maxUses: 5 } },
+  messages: [{ role: 'user', content: 'What changed in EV charging prices this year?' }],
+  tools: [lookup],
+  limits: { maxSteps: 10, maxToolCalls: 12, timeoutMs: 5 * 60_000 },
+  stream: true, // emits `text.delta` events
+  onEvent: (event) => log(event),
+});
+// result.text, .stopReason ('done' | 'budget' | 'length'), .steps, .toolCalls, .usage, .cost
+```
+
+A tool that spends itself (a model call, a paid API) reports it with
+`toolResult({ content, cost, usage })`: it counts in the agent's totals and
+cost limit, and is reported apart as `result.toolCost`.
+
+### One tool registry for agents and MCP
+
+Define each tool once — input schema (Zod, or anything with `safeParse`),
+optional output schema, a token-efficient `format`, a permission class
+(`pure` · `read_tenant` · `read_untrusted` · `write_paid`; nothing that
+approves, publishes or messages) — and serve it to both:
+
+```typescript
+import { createToolRegistry, defineRegistryTool } from '@venturekit-pro/ai';
+import { zodToJsonSchema, handleMcpRequest } from '@venturekit/mcp';
+import { z, type ZodType } from 'zod';
+
+const search = defineRegistryTool({
+  name: 'corpus.search',
+  description: 'Search the published articles',
+  permission: 'read_tenant',
+  input: z.object({ query: z.string() }),
+  format: (out: Hit[]) => out.map((h) => h.title),
+  run: (args, ctx: { tenantId: string }) => searchCorpus(ctx.tenantId, args.query),
+});
+const registry = createToolRegistry([search], {
+  toJsonSchema: (schema) => zodToJsonSchema(schema as ZodType),
+});
+
+registry.forAgent({ tenantId }, { permissions: ['read_tenant'] }); // AgentTool[] — names become `corpus_search`
+const mcpTools = registry.forMcp<ZodType>();                      // McpToolRegistry for @venturekit/mcp
+```
+
+The tenant scope is the caller's context — the harness or the MCP server's
+`createContext` — never an argument the model supplies.
+
+## Harness
+
+Durable, versioned graphs. One queue message per node attempt: lease → run →
+one atomic commit (output, next node, events) → schedule the next task. Gates
+wait with nothing in flight; map nodes checkpoint each item; failed attempts
+retry with backoff; `sweep()` re-sends lost tasks and recovers dead workers;
+`cancel()` aborts a running node through `ctx.signal`.
+
+```typescript
+import { createHarness, createPostgresHarnessStore, defineGraph, defineNode } from '@venturekit-pro/ai';
+
+const article = defineGraph({
+  key: 'article.write',
+  version: 1,
+  start: 'draft',
+  nodes: [
+    defineNode({
+      id: 'draft',
+      kind: 'agent',
+      label: 'Writing the draft',
+      tier: 'best',
+      retry: { maxAttempts: 2 },
+      next: 'review',
+      run: async (ctx) => (await ctx.runAgent({ request: {}, messages: draftPrompt(ctx.input()) })).text,
+    }),
+    defineNode({ id: 'review', kind: 'gate', label: 'Ready for you', decisions: ['approve', 'reject'], next: ({ output }) => ((output as { decision: string }).decision === 'approve' ? 'publish' : null) }),
+    defineNode({ id: 'publish', kind: 'emit', label: 'Publishing', retry: { maxAttempts: 1 }, run: (ctx) => publish(ctx.require<string>('draft')) }),
+  ],
+});
+
+const harness = createHarness({
+  store: createPostgresHarnessStore(query), // migration vk_ai_cost_0005
+  scheduler: { enqueue: (task, opts) => queue.send(task, opts?.delayMs) }, // your queue → harness.execute(task)
+  graphs: [article],
+  gateway,
+});
+
+const run = await harness.start({ graph: 'article.write', input: { topic }, context: { tenantId } });
+await harness.resume(run.id, { decision: 'approve' });
+```
+
+In a node, `ctx.generate` / `ctx.stream` / `ctx.runAgent` go through the
+gateway with the run's context, an idempotency key per attempt and the run's
+spend; tool calls become `tool.called` events; `ctx.progress()` feeds live
+status, and `ctx.state(s)` records the node's state with its
+`detail(s)` line ("3 of 8 sources"). `harness.events(runId, { afterSeq })`
+reads the timeline. `meta` carries app data with a node (artifact contracts,
+tool lists); the harness ignores it.
+
+- **Which failures retry** — `retry: { maxAttempts: 3, on: ['rate_limit', 'timeout', 'schema'] }`
+  (or a predicate). Categories come from `retryCategory(err)`: 429 →
+  `rate_limit`, 5xx → `server`, timeouts, network failures, and errors
+  thrown with `category: 'schema'` (an answer that broke its contract).
+  Fatal errors (`NodeFatalError`, policy denials, 4xx) never retry.
+- **Fan-out** — a map node with `dispatch: 'tasks'` sends one queue message
+  per item (`{ runId, step, attempt, item }`, at most `concurrency` in
+  flight). Each item has its own lease, timeout, retries and checkpoint;
+  the join counter makes exactly one item — the last — commit the node,
+  with the outputs in item order and the items' spend. A failed item fails
+  the run; `retry()` redoes only the items not done; `sweep()` re-sends lost
+  item tasks and recovers dead item workers (migration `vk_ai_cost_0007`).
+  Items and outputs must be JSON. The default, `dispatch: 'inline'`, runs
+  the items inside the node attempt.
+
+## Tracing
+
+Pass any OpenTelemetry tracer — `trace.getTracer('venturekit-ai')` from
+`@opentelemetry/api` fits as is — as `tracer` to the gateway, `runAgent` or
+the harness. `otelTracer()` returns the tracer of the SDK registered in the
+process (the AWS Lambda layer that `lambda.otel` in `@venturekit/infra`
+adds registers one), or `undefined`, without importing anything. Spans: `harness.node <graph>/<node>` per node attempt,
+`invoke_agent <name>`, `execute_tool <tool>`, and `chat <model>` per gateway
+call with the GenAI semantic-convention attributes (`gen_ai.provider.name`,
+`gen_ai.usage.*` with cache reads and writes, finish reasons, time to first
+chunk) plus `vk.ai.*` (cost, call id, tenant, feature, fallback).
+`createRecordingTracer()` keeps spans in memory for tests.
+
 ## Image Generation
 
 Provider-neutral text-to-image (currently Google Imagen), returning raw image

package/dist/agent-loop/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Agent loop — a bounded, provider-neutral tool-use loop. See `./run-agent.ts`.
+ */
+export { runAgent, AgentRunError } from './run-agent.js';
+export { defineAgentTool, toolResult, isToolResult } from './tools.js';
+export { createToolRegistry, defineRegistryTool, toModelName } from './registry.js';
+export type { ToolPermission, ToolSchema, ToolSchemaOutput, ToolRunContext, RegistryTool, RegistryMcpTool, ToolFilter, ToolRegistry, } from './registry.js';
+export type { AgentToolContext, ToolSpend, ToolResult, AgentTool, AgentLimits, AgentLimitHit, AgentStopReason, AgentStepResult, AgentToolCallResult, AgentEvent, RunAgentOptions, AgentRunResult, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/agent-loop/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent-loop/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACpF,YAAY,EACV,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,UAAU,EACV,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,gBAAgB,EAChB,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,aAAa,EACb,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/agent-loop/index.js

@@ -0,0 +1,7 @@
+/**
+ * Agent loop — a bounded, provider-neutral tool-use loop. See `./run-agent.ts`.
+ */
+export { runAgent, AgentRunError } from './run-agent.js';
+export { defineAgentTool, toolResult, isToolResult } from './tools.js';
+export { createToolRegistry, defineRegistryTool, toModelName } from './registry.js';
+//# sourceMappingURL=index.js.map

package/dist/agent-loop/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent-loop/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/agent-loop/registry.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Tool registry — one definition per tool, served to internal agents
+ * (`forAgent`) and to an MCP server (`forMcp`, the `@venturekit/mcp`
+ * `McpTool` shape).
+ *
+ * Every tool has an input schema (any schema with Zod's `safeParse` —
+ * Zod fits as is), an optional output schema checked before anyone sees
+ * the result, a token-efficient `format` for models, and a permission
+ * class. The tenant scope is the caller's context, bound by the harness
+ * or the MCP server — never an argument the model supplies.
+ *
+ * There is deliberately no class that approves, publishes, schedules,
+ * deletes or messages externally: those are gates or system graphs.
+ */
+import type { AgentTool } from './types.js';
+/**
+ * `pure` (no I/O) · `read_tenant` (the tenant's own data) ·
+ * `read_untrusted` (the open web — results are untrusted input) ·
+ * `write_paid` (creates something that costs money, e.g. an image).
+ */
+export type ToolPermission = 'pure' | 'read_tenant' | 'read_untrusted' | 'write_paid';
+/** Any schema with Zod's `safeParse`. */
+export interface ToolSchema<T> {
+    safeParse(value: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            message: string;
+        };
+    };
+}
+export type ToolSchemaOutput<S> = S extends ToolSchema<infer T> ? T : never;
+/** What a registry tool runs with: the caller's context plus the call's signal. */
+export type ToolRunContext<C> = C & {
+    signal: AbortSignal;
+    /** Who is calling: an internal agent or an MCP client. */
+    via: 'agent' | 'mcp';
+};
+export interface RegistryTool<S extends ToolSchema<any> = ToolSchema<any>, O = unknown, C = unknown> {
+    /** `[a-zA-Z0-9_.-]`, ≤ 64 chars. Dots become `_` for model providers (`web.read` → `web_read`). */
+    name: string;
+    description: string;
+    permission: ToolPermission;
+    input: S;
+    output?: ToolSchema<O>;
+    /** The result as models should read it (shorter, no internal ids). Default: the result. */
+    format?(output: O): unknown;
+    /** Per-call timeout for agents. Default 60 s. */
+    timeoutMs?: number;
+    run(args: ToolSchemaOutput<S>, ctx: ToolRunContext<C>): Promise<O>;
+}
+/** Declare a registry tool; keeps the input type from the schema to `run`. */
+export declare function defineRegistryTool<S extends ToolSchema<any>, O, C>(tool: RegistryTool<S, O, C>): RegistryTool<S, O, C>;
+/** The `@venturekit/mcp` `McpTool` shape (structural: no dependency on the package). */
+export interface RegistryMcpTool<S, C> {
+    name: string;
+    description: string;
+    inputSchema: S;
+    run(args: unknown, ctx: C): Promise<unknown>;
+}
+export interface ToolFilter {
+    names?: string[];
+    permissions?: ToolPermission[];
+}
+export interface ToolRegistry<C> {
+    readonly tools: ReadonlyArray<RegistryTool<ToolSchema<any>, any, C>>;
+    get(name: string): RegistryTool<ToolSchema<any>, any, C> | undefined;
+    /** Agent tools bound to `ctx` (the tenant scope). */
+    forAgent(ctx: C, filter?: ToolFilter): AgentTool[];
+    /**
+     * MCP tools keyed by name; the MCP server's `createContext` supplies
+     * `ctx`. Name your schema type so the result fits `McpToolRegistry`:
+     * `registry.forMcp<ZodType>()`.
+     */
+    forMcp<S = ToolSchema<any>>(filter?: ToolFilter): Record<string, RegistryMcpTool<S, C>>;
+}
+export declare function createToolRegistry<C>(tools: Array<RegistryTool<any, any, C>>, options: {
+    /** Input schema → JSON Schema for the model (e.g. `zodToJsonSchema` from `@venturekit/mcp`). */
+    toJsonSchema(schema: ToolSchema<unknown>): object;
+}): ToolRegistry<C>;
+/** Provider tool names allow `[a-zA-Z0-9_-]` only. */
+export declare function toModelName(name: string): string;
+//# sourceMappingURL=registry.d.ts.map

package/dist/agent-loop/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/agent-loop/registry.ts"],"names":[],"mappings":"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"}

package/dist/agent-loop/registry.js

@@ -0,0 +1,100 @@
+/**
+ * Tool registry — one definition per tool, served to internal agents
+ * (`forAgent`) and to an MCP server (`forMcp`, the `@venturekit/mcp`
+ * `McpTool` shape).
+ *
+ * Every tool has an input schema (any schema with Zod's `safeParse` —
+ * Zod fits as is), an optional output schema checked before anyone sees
+ * the result, a token-efficient `format` for models, and a permission
+ * class. The tenant scope is the caller's context, bound by the harness
+ * or the MCP server — never an argument the model supplies.
+ *
+ * There is deliberately no class that approves, publishes, schedules,
+ * deletes or messages externally: those are gates or system graphs.
+ */
+import { isToolResult, toolResult } from './tools.js';
+const PERMISSIONS = [
+    'pure',
+    'read_tenant',
+    'read_untrusted',
+    'write_paid',
+];
+/** Declare a registry tool; keeps the input type from the schema to `run`. */
+export function defineRegistryTool(tool) {
+    return tool;
+}
+const NAME = /^[a-zA-Z0-9_.-]{1,64}$/;
+export function createToolRegistry(tools, options) {
+    const byName = new Map();
+    const modelNames = new Set();
+    for (const tool of tools) {
+        if (!NAME.test(tool.name))
+            throw new Error(`[ai/tools] '${tool.name}' is not a valid tool name ([a-zA-Z0-9_.-], ≤ 64)`);
+        if (byName.has(tool.name))
+            throw new Error(`[ai/tools] tool '${tool.name}' is registered twice`);
+        if (!PERMISSIONS.includes(tool.permission))
+            throw new Error(`[ai/tools] tool '${tool.name}' has an unknown permission class '${String(tool.permission)}'`);
+        const modelName = toModelName(tool.name);
+        if (modelNames.has(modelName))
+            throw new Error(`[ai/tools] '${tool.name}' clashes with another tool as '${modelName}'`);
+        modelNames.add(modelName);
+        byName.set(tool.name, tool);
+    }
+    const select = (filter) => [...byName.values()].filter((t) => (!filter?.names || filter.names.includes(t.name)) &&
+        (!filter?.permissions || filter.permissions.includes(t.permission)));
+    const parse = (tool, args) => {
+        const parsed = tool.input.safeParse(args);
+        if (!parsed.success)
+            throw new Error(`Invalid arguments for ${tool.name}: ${parsed.error.message}`);
+        return parsed.data;
+    };
+    const finish = (tool, out) => {
+        const value = isToolResult(out) ? out.content : out;
+        if (tool.output) {
+            const checked = tool.output.safeParse(value);
+            if (!checked.success)
+                throw new Error(`${tool.name} returned an invalid result: ${checked.error.message}`);
+        }
+        const formatted = tool.format ? tool.format(value) : value;
+        return isToolResult(out) ? toolResult({ ...out, content: formatted }) : formatted;
+    };
+    return {
+        tools: [...byName.values()],
+        get: (name) => byName.get(name),
+        forAgent(ctx, filter) {
+            return select(filter).map((tool) => ({
+                definition: {
+                    name: toModelName(tool.name),
+                    description: tool.description,
+                    inputSchema: options.toJsonSchema(tool.input),
+                },
+                parse: (args) => parse(tool, args),
+                ...(tool.timeoutMs !== undefined ? { timeoutMs: tool.timeoutMs } : {}),
+                execute: async (args, toolCtx) => finish(tool, await tool.run(args, { ...ctx, signal: toolCtx.signal, via: 'agent' })),
+            }));
+        },
+        forMcp(filter) {
+            return Object.fromEntries(select(filter).map((tool) => [
+                tool.name,
+                {
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: tool.input,
+                    run: async (args, ctx) => {
+                        const out = finish(tool, await tool.run(parse(tool, args), {
+                            ...ctx,
+                            signal: new AbortController().signal,
+                            via: 'mcp',
+                        }));
+                        return isToolResult(out) ? out.content : out;
+                    },
+                },
+            ]));
+        },
+    };
+}
+/** Provider tool names allow `[a-zA-Z0-9_-]` only. */
+export function toModelName(name) {
+    return name.replace(/\./g, '_');
+}
+//# sourceMappingURL=registry.js.map

package/dist/agent-loop/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/agent-loop/registry.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,37 @@
+/**
+ * `runAgent` — a bounded tool-use loop on the gateway's `generate`.
+ *
+ *   each step: model call (tools + native web search) → run the function
+ *   tools it asked for, in order → answer them → next step
+ *
+ * Limits are soft: when steps, tool calls, cost or time run out, the
+ * model gets one last call without tool use and is told to answer from
+ * what it has (`stopReason: 'budget'`). A hard stop (cancellation, the
+ * wall clock passing its limit mid-call, a gateway error) throws an
+ * `AgentRunError` carrying the conversation and spend so far.
+ *
+ * Every step is one gateway call with a stable idempotency key
+ * (`<key>:s<step>`); tool errors go back to the model as error results
+ * instead of failing the run.
+ */
+import type { GenerateMessage, GenerateUsage } from '../generate/types.js';
+import type { AgentRunResult, RunAgentOptions } from './types.js';
+type Cost = {
+    costUsd: number;
+    costMicroUsd: number;
+};
+/** A hard stop, with the conversation and spend so far. `name` stays `AbortError` on cancellation. */
+export declare class AgentRunError extends Error {
+    readonly snapshot: {
+        messages: GenerateMessage[];
+        usage: GenerateUsage;
+        cost: Cost | null;
+        toolCost: Cost | null;
+        steps: number;
+        toolCalls: number;
+    };
+    constructor(message: string, cause: unknown, snapshot: AgentRunError['snapshot']);
+}
+export declare function runAgent(options: RunAgentOptions): Promise<AgentRunResult>;
+export {};
+//# sourceMappingURL=run-agent.d.ts.map

package/dist/agent-loop/run-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-agent.d.ts","sourceRoot":"","sources":["../../src/agent-loop/run-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAEV,eAAe,EACf,aAAa,EAGd,MAAM,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAGV,cAAc,EAId,eAAe,EAChB,MAAM,YAAY,CAAC;AAepB,KAAK,IAAI,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD,sGAAsG;AACtG,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,EAAE,eAAe,EAAE,CAAC;QAC5B,KAAK,EAAE,aAAa,CAAC;QACrB,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;QAClB,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;QACtB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;gBAEU,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC;CAMjF;AAED,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CA8BhF"}