@dex-ai/sdk 0.1.30

package/README.md

@@ -0,0 +1,308 @@
+# @dex-ai/sdk
+
+An agent SDK for TypeScript + Bun. One package: interfaces, `Agent.create()`, and the generate loop.
+
+## Layout
+
+The SDK lives in its own repo (`dex-ai-sdk`). Provider implementations live in a sibling monorepo (`dex-ai-providers`):
+
+```
+workplace/
+├── dex-ai-sdk/                           (this repo — @dex-ai/sdk)
+│   ├── src/                              # types + define* helpers + Agent.create + generate loop
+│   ├── examples/                         # 8 runnable .ts examples
+│   └── docs/                             # SVG diagrams
+└── dex-ai-providers/                     (separate repo — providers monorepo)
+    └── providers/
+        └── openai/                       # @dex-ai/openai — OpenAI Chat Completions
+```
+
+`@dex-ai/openai` is referenced from `examples/package.json` via `file:../../dex-ai-providers/providers/openai`. Clone both side by side for local dev.
+
+## Usage
+
+```ts
+import { Agent, Tool } from '@dex-ai/sdk';
+import { openai } from '@dex-ai/openai';
+import { z } from 'zod';
+
+const getWeather = Tool.define({
+  name: 'get_weather',
+  description: 'Look up current weather.',
+  parameters: z.object({ city: z.string() }),
+  async execute({ city }) {
+    return { type: 'json', value: { city, tempC: 18 } };
+  },
+});
+
+const agent = await Agent.create({
+  name: 'demo',
+  provider: openai({ modelId: 'gpt-4.1' }),
+  extensions: [{ name: 'tools', tools: [getWeather] }],
+});
+
+// Non-streaming:
+const r = await agent.generate({
+  input: [{ role: 'user', content: [{ type: 'text', text: 'Weather in Paris?' }] }],
+}).result;
+
+// Streaming:
+const h = agent.generate({ input: [/* ... */] });
+for await (const part of h) {
+  if (part.type === 'text-delta') process.stdout.write(part.delta);
+  if (part.type === 'message-committed') saveToDb(part.message);
+}
+const result = await h.result;
+```
+
+## Design decisions
+
+### One package, two shapes
+
+`@dex-ai/sdk` ships both the *types* (so third-party providers and extensions can depend on only the type surface via `import type`) and the *runtime* (`Agent.create` + the loop). There is no separate types-only package.
+
+### Content model (flat, ai-sdk aligned)
+
+```ts
+type Content =
+  | { type: 'text'; text }
+  | { type: 'image'; image: string|Uint8Array|URL; mediaType? }
+  | { type: 'file';  data: string|Uint8Array|URL; mediaType; name? }
+  | { type: 'reasoning'; text }
+  | { type: 'tool-call'; toolCallId; toolName; input }
+  | { type: 'tool-result'; toolCallId; toolName; output: ToolOutput };
+
+type ToolOutput =
+  | { type: 'content';    value: ContentPayload[] }   // text / image / file
+  | { type: 'json';       value: unknown }
+  | { type: 'text';       value: string }
+  | { type: 'error-text'; value: string }
+  | { type: 'error-json'; value: unknown };
+```
+
+### Two contexts, two lifetimes
+
+`AgentContext` is persistent — created by `Agent.create()`, owns `messages: Message[]`, dies with `agent.dispose()`. `GenerateContext` is fresh per `generate()` call, owns the in-flight assistant `content: Content[]`, lives across all iterations of one generate.
+
+### One `generate()` method
+
+`agent.generate(opts)` returns an `AgentStream`: async-iterable AND has a `.result: Promise<GenerateResult>`. Same run drives both.
+
+### Approval via `onToolCall`
+
+No dedicated approval surface. An approver extension implements `onToolCall`: return a `ToolResult` (with `error-text`) to reject, a rewritten `ToolCall` to modify, or `void` to pass through. Rejections flow back to the LLM as data.
+
+### Schema-agnostic
+
+`Tool.parameters` takes any [Standard Schema](https://standardschema.dev) implementation — zod, valibot, arktype. The provider converts to JSON Schema.
+
+## Core Loop Architecture
+
+The generate loop is event-driven. Extensions subscribe to events via `ext.on['event-name']`. The loop orchestrates model calls, tool dispatch, and context injection purely through events.
+
+### Agent Creation (`Agent.create`)
+
+1. Collect extensions from options
+2. Run `ext.init(actx)` on each extension (registration order)
+3. Set up tool result cache (if configured)
+4. Assemble system prompt into a single system message:
+   - `opts.systemPrompt` (base identity/instructions)
+   - **Skills** from extensions: evaluate `skill.when()`, render `skill.content`, build catalog
+   - **`session-start`** event: extensions yield `AsyncIterable<Content>` for system prompt
+5. Reorder messages: system first, then conversation history
+6. Append seed messages
+
+### Generate Loop Phases
+
+Each `agent.generate(opts)` call runs:
+
+#### Phase A: Input Processing
+
+| Step | Action | Event |
+|------|--------|-------|
+| A1 | Extensions augment input messages | `generate-input` |
+| A2 | Commit input to `actx.messages` | `message-committed` (stream) |
+| A3 | Collect ephemeral turn context | `generate-start` → `AsyncIterable<Content>` |
+| A4 | Build ephemeral context message (step 0 only, never persisted) | — |
+
+#### Phase B: Iteration Loop (one model call + tool execution)
+
+| Step | Action | Event |
+|------|--------|-------|
+| B1 | Build `ModelRequest` (messages + tools + params) | — |
+| B2 | Inject ephemeral context (step 0 only) | — |
+| B3 | Extensions transform the request (reducer) | `model-start` → `ModelRequest \| void` |
+| B4 | Compute cache breakpoints (Anthropic-style) | — |
+| B5 | Iteration begins | `message-start` |
+| B6 | Stream from model — consume `model.stream(req)` | `text-delta`, `reasoning-delta`, `tool-call-delta`, `tool-call`, `message-stop`, `finish` |
+| B7 | Commit assistant message | `message-committed` (stream) |
+| B8 | Assistant output finalized | `message-stop` |
+| B9 | Update `actx.tokenCount` | — |
+| B10 | Model call complete | `model-stop` |
+
+#### Phase C: Tool Dispatch (per tool call)
+
+| Step | Action | Event |
+|------|--------|-------|
+| C1 | Extensions intercept/modify/short-circuit | `tool-start` → `ToolCall \| ToolResult \| void` |
+| C2 | Validate input against tool schema | — |
+| C3 | Execute tool (raced with timeout + abort) | `tool-execute-start` (stream) |
+| C4 | Extensions transform result (reducer) | `tool-stop` → `ToolResult \| void` |
+| C5 | Commit tool-result message | `tool-execute-finish` + `message-committed` (stream) |
+
+#### Phase D: Continue or Stop
+
+```
+shouldContinue = finishReason == "tool-calls"
+                 && pendingToolCalls > 0
+                 && step + 1 < maxSteps
+```
+
+If continuing → increment step, go back to Phase B.
+
+#### Phase E: Finalization
+
+| Step | Action | Event |
+|------|--------|-------|
+| E1 | Turn complete | `generate-stop` (always fires, even on error) |
+| E2 | Build `GenerateResult` | — |
+| E3 | Close stream | `generate-finish` (stream) |
+
+### Event Hook Summary
+
+```
+┌─ Session Lifecycle ─────────────────────────────────────────────┐
+│  session-start     → yield Content for system prompt            │
+│  session-stop      → cleanup on agent.dispose()                 │
+└─────────────────────────────────────────────────────────────────┘
+
+┌─ Per generate() call ───────────────────────────────────────────┐
+│  generate-input    → augment input messages                     │
+│  generate-start    → yield ephemeral turn context               │
+│                                                                 │
+│  ┌─ Per iteration (model call) ──────────────────────────────┐  │
+│  │  model-start       → transform ModelRequest (reducer)     │  │
+│  │  message-start     → observe                              │  │
+│  │  text-delta        → observe streaming text               │  │
+│  │  reasoning-delta   → observe reasoning tokens             │  │
+│  │  tool-call-delta   → observe tool JSON streaming          │  │
+│  │  message-stop      → observe committed message            │  │
+│  │  model-stop        → observe                              │  │
+│  │                                                           │  │
+│  │  ┌─ Per tool call ─────────────────────────────────────┐  │  │
+│  │  │  tool-start  → intercept / modify / short-circuit   │  │  │
+│  │  │  tool-stop   → transform result (reducer)           │  │  │
+│  │  └─────────────────────────────────────────────────────┘  │  │
+│  └───────────────────────────────────────────────────────────┘  │
+│                                                                 │
+│  generate-stop     → finalize (always fires)                    │
+└─────────────────────────────────────────────────────────────────┘
+
+┌─ Cross-cutting ─────────────────────────────────────────────────┐
+│  error             → observe any error + ErrorSource context    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Extension Interaction Patterns
+
+| Pattern | Events | Description |
+|---------|--------|-------------|
+| **Reducer** | `model-start`, `tool-start`, `tool-stop` | Return transformed value or void (no-op) |
+| **Observer** | `text-delta`, `message-stop`, `generate-stop` | Observe but don't modify |
+| **Context injection** | `session-start`, `generate-start`, `generate-input` | Yield content for system prompt or turn context |
+| **Short-circuit** | `tool-start` | Return a `ToolResult` to skip tool execution |
+| **Ephemeral context** | `generate-start` | Content injected into step 0 request but never persisted |
+
+### Stream Parts
+
+The `AgentStream` merges **provider parts** with **loop-synthesized parts**:
+
+- **Provider**: `response-start`, `text-delta`, `reasoning-delta`, `tool-call-delta`, `tool-call`, `message-stop`, `finish`, `response-stop`, `error`, `abort`
+- **Loop**: `generate-start`, `generate-finish`, `iteration-start`, `iteration-finish`, `tool-execute-start`, `tool-execute-finish`, `message-committed`, `extension-info`
+
+### Message Integrity (`Messages` class)
+
+The conversation history is protected by the `Messages` class — a guarded container that prevents extensions from corrupting the message sequence.
+
+#### The problem
+
+Extensions previously cast `actx.messages as Message[]` to bypass the `ReadonlyArray` type and directly mutate the array (splice, push, etc.). This caused multiple corruption bugs where tool-calls had no matching tool-results, or role alternation was violated.
+
+#### The solution
+
+`actx.messages` is now backed by a **Proxy** that traps all direct mutations at runtime:
+
+```ts
+// These all throw at runtime — even with `as any` casts:
+actx.messages.push(msg);        // ❌ "Direct .push() is not allowed"
+actx.messages.splice(0, 1);     // ❌ "Direct .splice() is not allowed"
+actx.messages[0] = msg;         // ❌ "Direct index assignment is not allowed"
+actx.messages.length = 0;       // ❌ "Direct array mutation is not allowed"
+```
+
+Extensions MUST use `actx.messageStore` for controlled mutations:
+
+```ts
+const store = actx.messageStore;
+
+// Append (validates after)
+store.append(message);
+
+// Splice with validation
+store.splice(start, deleteCount, ...replacements);
+
+// Replace a range
+store.replaceRange(start, end, newMessages);
+
+// Replace single message
+store.replace(index, newMessage);
+
+// Batch mode — defer validation for multi-step mutations
+store.batch();
+store.splice(0, 10, ...compressed);
+store.append(summary);
+store.commit(); // validates here, throws if invalid
+
+// Or use transaction() for auto-commit:
+store.transaction(() => {
+  store.splice(warmStart, warmCount, ...summarized);
+});
+```
+
+#### Invariants enforced
+
+Every mutation (or `commit()` in batch mode) validates:
+
+1. **System messages at front** — contiguous prefix only
+2. **First non-system is `user`** — conversation must start with a user turn
+3. **Role alternation** — `user` → `assistant` → `tool`* → `user` (tool only after assistant)
+4. **Tool-call/tool-result pairing** — every `tool-call` in an assistant message must have a matching `tool-result`
+5. **No orphaned tool-results** — every `tool-result` must reference a preceding `tool-call`
+
+Violations throw with a detailed error listing the indices and what went wrong.
+
+### Error Handling
+
+- **`reportError(err, source)`** — structured logging + emits `extension-info` error part + calls `ext.on['error']` on all extensions
+- **Orphaned tool-call repair** — if the loop throws mid-tool-dispatch, synthesizes error `tool-result` messages so history stays valid
+- **`generate-stop` always fires** — even in catch path, so session persistence can flush
+
+## Diagrams
+
+| File | Shows |
+|------|-------|
+| `docs/architecture.svg` | Top-level layers: App → Agent → {Provider, Extensions → Tools}. |
+| `docs/packages.svg` | Package graph: @dex-ai/sdk, @dex-ai/openai, examples, deps. |
+| `docs/interfaces.svg` | Every exported interface on one canvas. |
+| `docs/contexts.svg` | AgentContext vs GenerateContext — lifetimes, mutation, integrity. |
+| `docs/core-loop-sequence.svg` | Sequence diagram of one `generate()` call with hook fire points. |
+| `docs/extension-interface.svg` | All hooks grouped by lifetime and kind. |
+| `docs/stream-parts.svg` | `AgentStreamPart` timeline: provider + loop-synthesized parts. |
+
+## Dev
+
+```bash
+bun install
+bun run typecheck
+bun run examples/01-non-streaming.ts
+```

package/dist/agent.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Agent — the interface AND the core loop.
+ *
+ * One method: generate(). It always returns an AgentStream: an object
+ * that is BOTH an AsyncIterable<AgentStreamPart> AND carries a
+ * .result: Promise<GenerateResult>. Callers pick the consumption mode.
+ *
+ *   // non-streaming
+ *   const r = await agent.generate(opts).result;
+ *
+ *   // streaming
+ *   const h = agent.generate(opts);
+ *   for await (const part of h) render(part);
+ *   const r = await h.result;
+ *
+ * The loop runs exactly once per generate() call regardless of which
+ * consumer drives it. Both .result and the iterator reflect the same run.
+ *
+ * Each generate() call:
+ *   1. appends input messages to agent.context.messages
+ *   2. creates a fresh GenerateContext
+ *   3. runs the loop: request → stream → tool dispatch → repeat
+ *   4. commits the final assistant Message to agent.context.messages
+ *   5. resolves .result with GenerateResult
+ */
+import type { Message } from "./message";
+import type { StreamPart, FinishReason, Usage } from "./provider";
+import type { ToolCall, ToolResult } from "./tool";
+import type { Extension } from "./extension";
+import type { AgentContext } from "./context";
+import type { ThinkingLevel } from "./model";
+import type { ToolResultCacheConfig } from "./tool-result-cache";
+/**
+ * Loop-synthesized parts. Not emitted by the Provider; emitted by the
+ * Agent around the provider stream. Let stream consumers observe the
+ * loop lifecycle without subscribing to hooks.
+ */
+export interface GenerateStartPart {
+    readonly type: "generate-start";
+    readonly maxSteps: number;
+    readonly startedAt: number;
+    readonly generateId: string;
+}
+export interface GenerateFinishPart {
+    readonly type: "generate-finish";
+    readonly result: GenerateResult;
+}
+export interface IterationStartPart {
+    readonly type: "iteration-start";
+    readonly step: number;
+    readonly startedAt: number;
+}
+export interface IterationFinishPart {
+    readonly type: "iteration-finish";
+    readonly step: number;
+    readonly endedAt: number;
+    readonly finishReason: FinishReason;
+    readonly usage: Usage;
+}
+export interface ToolExecuteStartPart {
+    readonly type: "tool-execute-start";
+    readonly call: ToolCall;
+    readonly startedAt: number;
+}
+export interface ToolExecuteFinishPart {
+    readonly type: "tool-execute-finish";
+    readonly call: ToolCall;
+    readonly result: ToolResult;
+    readonly startedAt: number;
+    readonly endedAt: number;
+}
+/**
+ * Emitted when the loop commits a message to AgentContext.messages.
+ * Fires for every committed message: tool-result messages (mid-loop)
+ * and the final assistant message (end of loop).
+ */
+export interface MessageCommittedPart {
+    readonly type: "message-committed";
+    readonly message: Message;
+    /** Index of the committed message in AgentContext.messages. */
+    readonly index: number;
+}
+/** Emitted by extensions via emit() for display-only info. Never enters model context. */
+export interface ExtensionInfoPart {
+    readonly type: "extension-info";
+    readonly extension: string;
+    readonly level: "debug" | "info" | "warn" | "error";
+    readonly text: string;
+}
+export type LoopStreamPart = GenerateStartPart | GenerateFinishPart | IterationStartPart | IterationFinishPart | ToolExecuteStartPart | ToolExecuteFinishPart | MessageCommittedPart | ExtensionInfoPart;
+/**
+ * The unified stream-part union exposed through agent.generate().
+ * Superset of provider StreamPart with loop-synthesized parts.
+ */
+export type AgentStreamPart = StreamPart | LoopStreamPart;
+export interface CreateAgentOptions {
+    readonly name?: string;
+    /** Provider extension name (must match an extension with models). */
+    readonly provider: string;
+    /** Model ID within the provider. */
+    readonly model: string;
+    readonly extensions?: ReadonlyArray<Extension>;
+    /** System prompt — prepended as a system message. */
+    readonly systemPrompt?: string;
+    /** Optional seed conversation (priming, restored history). */
+    readonly messages?: ReadonlyArray<Message>;
+    readonly signal?: AbortSignal;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    /** Configuration for caching large tool results to disk. */
+    readonly toolResultCache?: ToolResultCacheConfig;
+}
+/**
+ * input: typically a single user turn, but an array so callers can
+ * prime a conversation with synthetic messages. All messages are
+ * appended to agent.context.messages in order, before iter 1.
+ */
+export interface GenerateOptions {
+    readonly input: ReadonlyArray<Message>;
+    readonly maxSteps?: number;
+    readonly toolConcurrency?: number;
+    readonly signal?: AbortSignal;
+    readonly temperature?: number;
+    readonly topP?: number;
+    readonly maxTokens?: number;
+    readonly stopSequences?: ReadonlyArray<string>;
+    readonly seed?: number;
+    readonly providerOptions?: Readonly<Record<string, unknown>>;
+    /** Override provider for this call (matches extension name). */
+    readonly provider?: string;
+    /** Override model for this call (matches model id within the provider). */
+    readonly model?: string;
+    /** Tool execution timeout in ms. Default: 120000 (2 min). */
+    readonly toolTimeoutMs?: number;
+    /**
+     * Enable extended thinking / chain-of-thought reasoning.
+     * Pass a ThinkingLevel or `{ budgetTokens: N }` for explicit budget.
+     * The provider maps levels to token budgets.
+     */
+    readonly thinking?: ThinkingLevel | {
+        readonly budgetTokens: number;
+    };
+}
+export interface GenerateResult {
+    /** Unique identifier for this generate() call. All committed messages share this ID. */
+    readonly generateId: string;
+    /** The assistant message produced by this generate (also committed to history). */
+    readonly message: Message;
+    /** Tool-result messages committed during this generate, in order. */
+    readonly toolResultMessages: ReadonlyArray<Message>;
+    readonly usage: Usage;
+    readonly finishReason: FinishReason;
+    /** Number of iterations executed (>= 1). */
+    readonly steps: number;
+}
+/**
+ * The return value of agent.generate().
+ *
+ * AsyncIterable<AgentStreamPart> — yields every provider part plus
+ * loop-synthesized parts live, in order.
+ * .result — Promise resolving to the final GenerateResult. Resolves
+ * whether or not anyone iterates; rejects on unrecovered error.
+ *
+ * Implementations in dex-core drive the loop once, then fan out to
+ * both the iterator and the .result promise.
+ */
+export interface AgentStream extends AsyncIterable<AgentStreamPart> {
+    readonly result: Promise<GenerateResult>;
+}
+export interface Agent {
+    readonly context: AgentContext;
+    /** Run the loop. Returns a handle that supports both streaming and awaited-result consumption. */
+    generate(opts: GenerateOptions): AgentStream;
+    /** Release long-lived resources. Calls dispose() on every extension in reverse order. */
+    dispose(): Promise<void>;
+}
+/** Signature for Agent.create. Useful when passing the factory around. */
+export type CreateAgent = (opts: CreateAgentOptions) => Promise<Agent>;
+export declare const Agent: {
+    create: (opts: CreateAgentOptions) => Promise<Agent>;
+};
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

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

package/dist/agent.js

@@ -0,0 +1,41 @@
+/**
+ * Agent — the interface AND the core loop.
+ *
+ * One method: generate(). It always returns an AgentStream: an object
+ * that is BOTH an AsyncIterable<AgentStreamPart> AND carries a
+ * .result: Promise<GenerateResult>. Callers pick the consumption mode.
+ *
+ *   // non-streaming
+ *   const r = await agent.generate(opts).result;
+ *
+ *   // streaming
+ *   const h = agent.generate(opts);
+ *   for await (const part of h) render(part);
+ *   const r = await h.result;
+ *
+ * The loop runs exactly once per generate() call regardless of which
+ * consumer drives it. Both .result and the iterator reflect the same run.
+ *
+ * Each generate() call:
+ *   1. appends input messages to agent.context.messages
+ *   2. creates a fresh GenerateContext
+ *   3. runs the loop: request → stream → tool dispatch → repeat
+ *   4. commits the final assistant Message to agent.context.messages
+ *   5. resolves .result with GenerateResult
+ */
+/**
+ * Agent namespace — the factory for creating agent instances.
+ *
+ * Use `Agent.create({...})` to wire a Provider + extensions into a
+ * running Agent. Async because extensions can have async `init` hooks.
+ *
+ * Unlike the `*.define()` helpers (which are pure declarations), this
+ * allocates a running thing with a lifecycle — call `agent.dispose()`
+ * when done.
+ */
+import { createAgentImpl } from "./create-agent";
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export const Agent = {
+    create: (opts) => createAgentImpl(opts),
+};
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAoMH;;;;;;;;;GASG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,2DAA2D;AAC3D,MAAM,CAAC,MAAM,KAAK,GAAG;IACpB,MAAM,EAAE,CAAC,IAAwB,EAAkB,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC;CAC3E,CAAC"}

package/dist/context.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Two contexts, two lifetimes.
+ *
+ * AgentContext — the agent-wide, persistent carrier.
+ * GenerateContext — the per-generate carrier.
+ */
+import type { Message, Content } from "./message";
+import type { Usage } from "./provider";
+import type { Extension } from "./extension";
+import type { Model } from "./model";
+import type { AgentStreamPart } from "./agent";
+import type { Messages } from "./messages";
+export interface AgentContext {
+    /** Stable identifier for the agent. */
+    readonly name: string;
+    /** Registered extensions in registration order. */
+    readonly extensions: ReadonlyArray<Extension>;
+    /** Conversation history. Read-only view — use appendMessage() or messageStore to mutate. */
+    readonly messages: ReadonlyArray<Message>;
+    /**
+     * The guarded Messages instance. Use this for controlled mutations
+     * (splice, replaceRange, replace). Direct array mutation on `messages`
+     * will throw at runtime.
+     */
+    readonly messageStore: Messages;
+    /** Total tokens (input + output) accumulated across all generate turns in the session. Updated by the generate loop. */
+    tokenCount: number;
+    /** Agent-wide per-extension scratchpad. Keyed by extension name. */
+    readonly state: Map<string, unknown>;
+    /** Optional agent-level abort signal. */
+    readonly signal?: AbortSignal;
+    /** Optional metadata supplied at createAgent time. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    /** Active provider extension name. Mutable — can be changed mid-session. */
+    providerName: string;
+    /** Active model ID within the provider. Mutable — can be changed mid-session. */
+    modelId: string;
+    /** The resolved active model. Call model.stream(req) for LLM access. */
+    readonly model: Model;
+    /** Append message(s) to conversation history. Assigns ID if missing. */
+    appendMessage(message: Message | ReadonlyArray<Message>): void;
+    /**
+     * Emit an event part to the caller's stream.
+     * TODO: Wire up in create-agent.ts — needs reference to the PushStream.
+     */
+    emit?(part: AgentStreamPart): void;
+}
+export interface GenerateContext {
+    /** Upward reference to the agent-wide context. */
+    readonly agent: AgentContext;
+    /** Unique identifier for this generate() call. All messages committed during this call share this ID. */
+    readonly generateId: string;
+    /**
+     * Assistant output being built up over the course of this generate.
+     */
+    readonly content: Content[];
+    /** Per-generate per-extension scratchpad. Keyed by extension name. */
+    readonly state: Map<string, unknown>;
+    /** 0-indexed step counter. */
+    readonly stepCount: number;
+    /** Upper bound on steps within this generate. */
+    readonly maxSteps: number;
+    /** Accumulated usage across all provider calls in this generate. */
+    usage: Usage;
+    /** Per-generate abort signal (merged with AgentContext.signal). */
+    readonly signal?: AbortSignal;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAM3C,MAAM,WAAW,YAAY;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IAC9C,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC;IAChC,wHAAwH;IACxH,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,yCAAyC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEtD,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAEhB,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAEtB,wEAAwE;IACxE,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAE/D;;;OAGG;IACH,IAAI,CAAC,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC;CACnC;AAMD,MAAM,WAAW,eAAe;IAC/B,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,yGAAyG;IACzG,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,8BAA8B;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,KAAK,EAAE,KAAK,CAAC;IACb,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC9B"}

package/dist/context.js

@@ -0,0 +1,8 @@
+/**
+ * Two contexts, two lifetimes.
+ *
+ * AgentContext — the agent-wide, persistent carrier.
+ * GenerateContext — the per-generate carrier.
+ */
+export {};
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/create-agent.d.ts

@@ -0,0 +1,7 @@
+/** createAgentImpl — wires extensions into an Agent instance. */
+import type { Agent as AgentType, CreateAgentOptions } from "./agent";
+import type { Extension } from "./extension";
+import type { Model } from "./model";
+export declare function resolveModel(extensions: ReadonlyArray<Extension>, providerName: string, modelId: string): Model;
+export declare function createAgentImpl(opts: CreateAgentOptions): Promise<AgentType>;
+//# sourceMappingURL=create-agent.d.ts.map

package/dist/create-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-agent.d.ts","sourceRoot":"","sources":["../src/create-agent.ts"],"names":[],"mappings":"AAAA,iEAAiE;AAEjE,OAAO,KAAK,EAAE,KAAK,IAAI,SAAS,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGtE,OAAO,KAAK,EAAE,SAAS,EAAS,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AASrC,wBAAgB,YAAY,CAC3B,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,EACpC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,GACb,KAAK,CAOP;AAED,wBAAsB,eAAe,CACpC,IAAI,EAAE,kBAAkB,GACtB,OAAO,CAAC,SAAS,CAAC,CA8MpB"}