@aeye/core 0.3.7 → 0.3.9

package/aeye-core-prompts.md

@@ -0,0 +1,171 @@
+# @aeye/core — Prompt
+
+`Prompt` (`src/prompt.ts`) generates an AI response from a Handlebars-templated message, optionally calls tools in a loop, and validates structured output against a Zod schema with automatic re-prompting.
+
+```typescript
+class Prompt<TContext = {}, TMetadata = {}, TName extends string = string,
+  TInput extends object = {}, TOutput extends object | string = string,
+  TTools extends Tuple<ToolCompatible<TContext, TMetadata>> = [],
+  TDecoded extends unknown = TOutput>
+  implements Component<...>
+```
+
+`TDecoded` is the decoded type a custom `parse` produces from the model's structured output — **any** value (a built AST/class instance, a number, an array, …), not just an object or string; it types `validate` and the decoded output. It defaults to the wire `TOutput` when no custom `parse` is supplied — `schema` always stays the wire type.
+
+A `Prompt` only does real work when the context supplies `execute` and/or `stream` (see [types doc](./aeye-core-types.md)). Without them, get/run yields nothing.
+
+## `PromptInput` (constructor config)
+
+| Field | Type | Notes |
+|------|------|-------|
+| `name` | `string` | Unique identifier. |
+| `description` | `string` | Informational. |
+| `content` | `string` | Handlebars template. `{{tools}}` is auto-appended (wrapped in `<tools>`) when tools exist and you didn't include it. |
+| `input?` | `Fn<Record<string,any>, [TInput?, ctx]>` | Maps raw input → template variables. |
+| `schema?` | `Fn<ZodType<TOutput> \| false, [TInput?, ctx]>` | Output schema. `false` → plain-text output. Omitted → text. |
+| `parse?` | `(raw, ctx) => TDecoded \| Error \| Promise<…>` | **Custom output parser that REPLACES Zod.** Receives the structured value **already wire-decoded to the conceptual shape** — core first applies the request's `FormatDescriptor` decode (`decodeWire`: array-of-pairs→record, null→undefined for optionals, numeric-key→tuple, …) so your parser is provider-agnostic and never sees a model family's wire quirks — and fully owns turning it into the decoded `TDecoded`; return (or throw) an `Error` to reject it — routed through the same `outputRetries` channel a Zod failure would, surfacing the error's own `.message` (no Zod vocabulary, since Zod never runs). Lets a caller (e.g. `@aeye/query`'s parser) return a built AST plus compiler-style diagnostics. Only runs where Zod validation runs today (a structured, non-`ZodString` `schema` is present); `schema` is still required and still drives the model wire format. Absent ⇒ unchanged Zod path. |
+| `strict?` | `boolean \| number` | Strict-mode policy, default `1`. See [schema doc](./aeye-core-schema.md). |
+| `config?` | `Fn<Partial<Request> \| false, [TInput?, ctx]>` | Per-request overrides (temperature, model, toolChoice, …). `false` ⇒ prompt not compatible. |
+| `reconfig?` | `(stats: PromptReconfigInput, ctx) => PromptReconfig` | Adapt config after each iteration based on runtime stats. |
+| `tools?` | `TTools` | Tools the model may call. |
+| `toolExecution?` | `'sequential' \| 'parallel' \| 'immediate'` | Default `immediate`. |
+| `toolRetries?` | `number` | Retry failed tool calls. Default 2. |
+| `toolIterations?` | `number` | Max tool-calling loop iterations. Default 3. |
+| `toolsMax?` | `number` | Stop sending tools after this many successes. |
+| `toolsOnly?` | `boolean` | Only call tools, don't generate text. |
+| `toolsComplete?` | `boolean` | Auto-synthesize tool results for unpaired `tool_calls` (abort/interrupt). Default `true`. |
+| `outputRetries?` | `number` | Retries to get valid structured output. Defaults to ctx (2). |
+| `forgetRetries?` | `number` | Context-trimming retries. Defaults to ctx (1). |
+| `validationErrorMaxLength?` | `number` | Truncate validation errors fed back to the model. Default 4096. |
+| `retool?` | `Fn<RetoolResult, [TInput?, ctx]>` | Dynamically select tools (by name or object), or `false` if incompatible. |
+| `dynamic?` | `boolean` | Re-resolve input/content/config/schema/tools each iteration; `undefined` ends the loop. |
+| `excludeMessages?` | `boolean` | Don't include `ctx.messages` when rendering. |
+| `onToolResult?` | `(event: ToolResultEvent<TContext, TMetadata, TTools>) => unknown \| Promise<unknown>` | Intercept each tool's **success** result before the model sees it; the return value is what's presented (serialized like any tool result). Model-facing only. See [Tool result transformer](#tool-result-transformer). |
+| `metadata?` / `metadataFn?` | `TMetadata` / fn | Execution metadata (model, requirements). |
+| `validate?` | `(output, ctx) => void \| Promise<void>` | Post-parse hook; throw to re-prompt. |
+| `applicable?` | `(ctx) => boolean \| Promise<boolean>` | Availability check. |
+
+`PromptReconfigInput` stats include: `iteration`, `maxIterations`, `toolParseErrors`, `toolCallErrors`, `tools` (names), `toolSuccesses`, and remaining `toolRetries` / `outputRetries` / `forgetRetries`. `PromptReconfig` lets you return `{ config?, maxIterations?, toolRetries?, outputRetries?, forgetRetries? }`.
+
+## Methods
+
+```typescript
+get(mode?: PromptGetType, input?: TInput, ctx?: Context): PromptGet<mode, TOutput, TTools>
+run(input?: TInput, ctx?: Context): AsyncGenerator<PromptEvent<TOutput, TTools>, TOutput | undefined>
+applicable(ctx?: Context): Promise<boolean>
+metadata(input?, ctx?): TMetadata | Promise<TMetadata>
+```
+
+### `get()` modes
+
+| Mode (default `'result'`) | Returns |
+|------|---------|
+| `'result'` | `Promise<TOutput \| undefined>` — final structured output |
+| `'tools'` | `Promise<PromptToolOutput<TTools>[] \| undefined>` — `{ tool, result }[]` |
+| `'stream'` | `AsyncGenerator<PromptEvent, TOutput \| undefined>` — all events |
+| `'streamTools'` | `AsyncGenerator<PromptToolOutput, TOutput \| undefined>` |
+| `'streamContent'` | `AsyncGenerator<string, TOutput \| undefined>` — text deltas only |
+
+`run()` is equivalent to `get('stream', …)`.
+
+```typescript
+// Structured result
+const r = await prompt.get('result', { text: 'hi' }, { execute, messages: [] });
+
+// Stream text deltas
+for await (const chunk of prompt.get('streamContent', { text: 'hi' }, { stream, messages: [] })) {
+  process.stdout.write(chunk);
+}
+
+// Stream all events
+for await (const e of prompt.get('stream', { text: 'hi' }, { stream, messages: [] })) {
+  if (e.type === 'textPartial') process.stdout.write(e.content);
+  else if (e.type === 'toolStart') console.log('tool:', e.tool.name);
+  else if (e.type === 'toolOutput') console.log('result:', e.result);
+  else if (e.type === 'complete') console.log('output:', e.output);
+}
+```
+
+## `PromptEvent` union
+
+Every event carries `request: Request`. Types:
+
+- `request` (`+ iterations`), `textPartial`, `text`, `textComplete`, `textReset` (`+ reason?`)
+- `refusal`, `reason` / `reasonPartial` (reasoning trace)
+- `toolParseName`, `toolParseArguments` (`+ args`), `toolArgRepairAttempt` (`+ fields, success`)
+- tool lifecycle: `toolStart`, `toolOutput` (`+ result` raw, `+ toModel` presented value), `toolInterrupt`, `toolSuspend`, `toolError` (`+ error, rawArgs?`) — each carries `tool` + `args`
+- `message` (`+ message`), `suspend`, `complete` (`+ output`)
+- `requestUsage`, `responseTokens`, `usage` (`+ usage`)
+
+## Prompt with tools
+
+```typescript
+const advisor = new Prompt({
+  name: 'travelAdvisor',
+  description: 'Plans a trip',
+  content: 'Plan a trip to {{destination}}. Use getWeather to check conditions.',
+  input: (i: { destination: string }) => ({ destination: i.destination }),
+  tools: [getWeather],                 // see aeye-core-tools.md
+  toolExecution: 'parallel',
+  toolIterations: 3,
+  schema: z.object({
+    recommendations: z.array(z.string()),
+    packingList: z.array(z.string()),
+  }),
+});
+
+const advice = await advisor.get('result', { destination: 'Paris' }, { execute, messages: [] });
+```
+
+## Tool result transformer
+
+`onToolResult` intercepts each tool's **successful** result *before* it's handed to the model and returns what the model sees instead. It's fully type-safe: `event` is a discriminated union over the prompt's tools, so **narrowing on `event.tool` types both `event.result` and `event.args`** for that tool. The default (unmatched) branch is the catch-all.
+
+```typescript
+const prompt = new Prompt({
+  name: 'searcher',
+  description: 'Searches and answers',
+  content: 'Answer using search.',
+  tools: [searchTool, mathTool],       // searchTool → { hits, ids }, mathTool → number
+  onToolResult: (event) => {
+    if (event.tool === 'search') {
+      // event.result is the search result; event.args is { query }
+      return `Found ${event.result.hits} hits for "${event.args.query}"`;
+    }
+    // catch-all: here event is the `math` member (event.result: number)
+    return event.result;              // pass-through
+  },
+});
+```
+
+- **The return value is what's presented.** It's serialized exactly like an untransformed result — a `string` is used verbatim, anything else is `JSON.stringify`-d — into the `role: 'tool'` message. To pass through unchanged, `return event.result`.
+- **Model-facing only.** `get('tools')`, `streamTools`, and the `toolOutput` event's `result` field always report the RAW result. The presented value is additionally exposed on the `toolOutput` event as `toModel` (equal to `result` when no handler is set).
+- **v1 = success results only.** Errored / suspended / interrupted / synthetic (`toolsComplete`) tool slots BYPASS the handler and keep their existing content. (A future v2 could add a `status: 'success' | 'error'` discriminant so handlers can transform errors too.)
+- **A handler that throws** is treated as a tool error for that slot — the model sees the error content — so the `tool_call` ↔ `role: 'tool'` pairing guarantee still holds. The raw result stays available on `get('tools')`/`streamTools`.
+- `async` handlers are awaited.
+
+Compile-time safety: referencing a non-existent tool name, or accessing a field not on the narrowed tool's `result`/`args`, fails to compile.
+
+## Token / context-window management
+
+When the rendered messages plus reserved output tokens exceed the window, the prompt trims older messages and retries (`forgetRetries`). Supply `estimateUsage` for accuracy:
+
+```typescript
+await prompt.get('result', { text }, {
+  execute, messages: history,
+  maxOutputTokens: 2048,
+  estimateUsage: (m) => ({ text: { input: Math.ceil(String(m.content).length / 4) } }),
+});
+```
+
+## Suspend / resume (human-in-the-loop)
+
+A tool can `throw new PromptSuspend(...)` to stop the loop *without* writing a tool result. The caller receives a `suspend` event whose `request.messages` includes the assistant message with the pending tool call. Persist those messages, do the external work (approval, etc.), append the `role: 'tool'` result message, then re-run the prompt with the combined messages as `ctx.messages`. `PromptSuspend` is never auto-paired even with `toolsComplete: true`.
+
+## Gotchas
+
+- Default `get` mode is `'result'`; pass the mode explicitly when streaming.
+- `schema` returning `false` disables structured output — output is the raw text string.
+- `config`/`retool` returning `false` marks the prompt incompatible with the context.
+- `toolsMax` is a soft cap unless `toolsOneAtATime` (request flag) is set — it stops *offering* tools after the threshold.
+- Validation errors (Zod / JSON / `validate`) are truncated to `validationErrorMaxLength` before being shown to the model.

package/aeye-core-schema.md

@@ -0,0 +1,117 @@
+# @aeye/core — Schema & strict mode
+
+`src/schema.ts` converts Zod schemas to provider-correct JSON Schema. Each LLM provider implements strict structured output / strict tool args with its *own* JSON-Schema dialect; a `FormatDescriptor` captures one dialect, so a single Zod schema can target all of them. Most apps never call these directly — `@aeye/ai` selects and applies a descriptor per request — but provider authors and advanced users do.
+
+## The `strict` policy (tri-state)
+
+`Tool.strict` and `Prompt.strict` (and `ToolDefinition.strict` / `ResponseFormat.strict`) are `boolean | number`:
+
+| Value | Meaning |
+|------|---------|
+| `true` | **Require** strict. `@aeye/ai` filters model selection to strict-capable models; fails if none qualify. |
+| `false` | **Force** lenient. Standard JSON Schema, no `strict: true` on the wire. |
+| `number > 0` (default `1`) | **Prefer** strict, accept fallback. Higher number = higher priority when more strict items are requested than the model's per-request budget allows. |
+| omitted | Treated as `1`. |
+
+Default `1` keeps things working against unannotated models. Use `true` only when strict is non-negotiable.
+
+## `FormatDescriptor`
+
+A descriptor (see `src/schema.ts` line ~26 for the fully documented interface) describes how to emit JSON Schema for one dialect. Key fields:
+
+| Field | Controls |
+|------|----------|
+| `id` | Unique id; pinned onto `request.responseFormat.descriptor` / `ToolDefinition.descriptor` so the validator can re-resolve it. |
+| `family` | `'openai' \| 'anthropic' \| 'google' \| (string & {})`. |
+| `objectAllFieldsRequired` | Whether every property must appear in `required[]`. |
+| `objectClosedByDefault` | Whether objects emit `additionalProperties: false`. |
+| `recordEncoding` | `'array-of-pairs'` vs `'open-record'`. |
+| `tupleEncoding` | `'object-numeric-keys'` vs `'prefix-items'` vs `'items-union'`. |
+| `optionalAsNullable` | Emit optionals as `T \| null` (OpenAI strict) vs drop from `required[]`. |
+| `allowAllOf` / `allowAnyOf` / `allowOneOf` | Combinator support. |
+| `supportedStringFormats` | `'all'` or a `Set<string>` whitelist. |
+| `supportsRecursion` | Whether `$ref` self-reference works. |
+| `maxStrictTools` / `maxStrictOptionalParams` / `maxStrictUnionTypes` | Per-request slot budgets (`undefined` = no documented limit). |
+
+## Built-in descriptors
+
+Seven ship frozen and pre-registered:
+
+| Export | Family / Strict | Notes |
+|------|------|-------|
+| `OPENAI_STRICT` | openai / strict | records→array-of-pairs, tuples→numeric-key objects, `optional → T \| null`, closed objects, restricted format whitelist. |
+| `ANTHROPIC_STRICT` | anthropic / strict | closed objects, no recursion, no length/range constraints; budgets 20 tools / 24 optional params / 16 unions. |
+| `GOOGLE_STRICT` | google / strict | `prefixItems`, `$ref: '#'` recursion, `propertyOrdering`, restricted format whitelist. |
+| `LENIENT` | lenient / non-strict | No rewrites; everything passes through. Default for unannotated models. |
+| `OPENAI_NON_STRICT`, `ANTHROPIC_NON_STRICT`, `GOOGLE_NON_STRICT` | family / non-strict | Aliased to `LENIENT` but tagged with the family for diagnostics. |
+
+## Functions
+
+```typescript
+toJSONSchema(schema: z.ZodType,
+  options: ToJSONSchemaOptions | boolean | FormatDescriptor): JSONSchema
+strictify<S extends z.ZodType>(schema: S, descriptor?: FormatDescriptor): S   // default OPENAI_STRICT
+analyzeSchema(schema): SchemaFeatures
+registerDescriptor(descriptor: FormatDescriptor): void
+getDescriptor(family: DescriptorFamily, strict: boolean): FormatDescriptor
+getDescriptorById(id: string | undefined): FormatDescriptor
+hasDescriptorFamily(family: string | undefined): boolean
+resolveDescriptor(options: ToJSONSchemaOptions | boolean | FormatDescriptor): FormatDescriptor
+strictestOf(a, b): FormatDescriptor
+strictPriority(requested: boolean | number | undefined): number
+```
+
+- `toJSONSchema` accepts a descriptor, a `ToJSONSchemaOptions` object, or a boolean (back-compat: `true` ⇒ `OPENAI_STRICT`, `false` ⇒ `LENIENT`).
+- `strictify` rewrites a Zod schema in place per the descriptor (results cached in a WeakMap; same OOM-safe pattern as `analyzeSchema`).
+- `analyzeSchema` returns `SchemaFeatures`: `{ hasRecursion, optionalParameterCount, unionTypeCount, recordCount, tupleCount }` — cached per schema.
+
+```typescript
+import { OPENAI_STRICT, ANTHROPIC_STRICT, getDescriptor, toJSONSchema } from '@aeye/core';
+
+const schema = z.object({
+  name: z.string(),
+  tags: z.record(z.string(), z.string()),
+});
+
+toJSONSchema(schema, OPENAI_STRICT);                 // tags → array of {key, value}
+toJSONSchema(schema, ANTHROPIC_STRICT);              // tags → array of {key, value}
+toJSONSchema(schema, getDescriptor('google', true)); // tags → standard additionalProperties
+toJSONSchema(schema, true);                          // === OPENAI_STRICT
+toJSONSchema(schema, false);                         // === LENIENT
+```
+
+## `SchemaBudget`
+
+`new SchemaBudget(descriptor)` allocates strict "slots" across a single request when a descriptor has per-request limits (e.g. Anthropic). Providers call:
+
+```typescript
+budget.allocateTool(schema, requested): FormatDescriptor   // returns strict or LENIENT, decrements
+budget.allocateOutput(schema, requested): FormatDescriptor // output schema; consumes param/union budget, not a tool slot
+```
+
+It returns `LENIENT` when `requested === false`, when the schema uses an unrepresentable feature, or when a positive-number request can't fit the remaining budget (priority order; `true` always wins subject to feasibility).
+
+## Registering a custom descriptor
+
+```typescript
+import { registerDescriptor, type FormatDescriptor, OPENAI_STRICT } from '@aeye/core';
+
+const MY_PROVIDER_STRICT: FormatDescriptor = {
+  ...OPENAI_STRICT,                 // start from a known-good baseline
+  id: 'my-provider-strict',
+  family: 'openai',
+  recordEncoding: 'open-record',    // override only the deltas
+  tupleEncoding: 'prefix-items',
+  supportsRecursion: true,
+};
+
+registerDescriptor(MY_PROVIDER_STRICT);
+```
+
+Once registered, `toJSONSchema(schema, MY_PROVIDER_STRICT)` / `strictify(...)` work, and the Prompt/Tool validation roundtrip resolves `'my-provider-strict'` by id from the request.
+
+## Gotchas
+
+- `ToolDefinition.parameters` and `ResponseFormat.type` stay **raw Zod**. The matching `strictify` is applied *lazily* by the provider once it knows the model's descriptor, then pinned via `descriptor` id so the validator (`Tool.parse` / Prompt output validation) matches the exact wire shape the model saw.
+- Strict dialects drop features they can't represent (Anthropic: no recursion, no numeric ranges). If a feature matters, check `analyzeSchema` against the descriptor or force `strict: false`.
+- The `JSONSchema` / `JSONSchemaType` / `ToJSONSchemaOptions` / `DescriptorFamily` types are exported for tooling.

package/aeye-core-tools.md

@@ -0,0 +1,177 @@
+# @aeye/core — Tool & Agent
+
+Both are `Component`s. A **Tool** is a single callable function exposed to the model (or invoked directly). An **Agent** is plain orchestration code that composes other components — no LLM loop of its own.
+
+## Tool
+
+```typescript
+class Tool<TContext = {}, TMetadata = {}, TName extends string = string,
+  TParams extends object = {}, TOutput = string,
+  TRefs extends Tuple<ComponentCompatible<TContext, TMetadata>> = [],
+  TDecoded extends unknown = TParams>
+  implements Component<...>
+```
+
+`TDecoded` is the decoded type a custom `parse` produces from the raw wire args — **any** value (a built class instance, a number, a `Date`, …), not just an object; it types `call`, `validate`, and `metadataFn`. It defaults to the wire `TParams` when no custom `parse` is supplied — `schema` always stays the wire type.
+
+### `ToolInput` (constructor config)
+
+| Field | Type | Notes |
+|------|------|-------|
+| `name` | `TName` | Shown to the model; unique per request. |
+| `description` | `string` | Shown to the model. |
+| `descriptionFn?` | `Fn<string, [ctx]>` | Refine description from context. |
+| `instructions?` | `string` | Handlebars usage instructions. |
+| `instructionsFn?` | `Fn<string, [ctx]>` | Context-derived instructions. |
+| `input?` | `Fn<Record<string,any>, [ctx]>` | Variables for the instructions template. |
+| `schema` | `Fn<ZodType<TParams> \| undefined, [ctx]>` | **Required.** Param schema; may depend on ctx. `undefined` ⇒ unavailable. |
+| `strict?` | `boolean \| number` | Strict-mode policy, default `1`. See [schema doc](./aeye-core-schema.md). |
+| `refs?` | `TRefs` | Components passed positionally to `call`. |
+| `call` | `(input: TParams, refs: TRefs, ctx) => TOutput` | **Required.** Implementation (sync or async). |
+| `validate?` | `(input, ctx) => void \| Promise<void>` | Runs after Zod parse; throw to re-prompt. |
+| `maxArgsLength?` | `number` | Reject raw args string over N chars before `JSON.parse` (guards against providers that corrupt large tool args). |
+| `applicable?` | `(ctx) => boolean \| Promise<boolean>` | Availability check. |
+| `metadata?` / `metadataFn?` | `TMetadata` / fn | Execution metadata. |
+
+### Methods
+
+```typescript
+run(input?: TParams, ctx?: Context): TOutput                 // call directly
+compile(ctx): Promise<readonly [string, ToolDefinition] | undefined>  // build AI tool def
+parse(ctx, args, schema?, descriptor?, onRepairAttempt?): Promise<...> // validate raw JSON args
+applicable(ctx?): Promise<boolean>
+metadata(input?, ctx?): TMetadata | Promise<TMetadata>
+```
+
+`compile` returns `undefined` when the tool isn't applicable / has no schema for the context. `parse` validates the model's JSON `arguments` string against the (descriptor-strictified) schema and runs `validate`; it tolerates one provider misbehavior — top-level JSON-stringified fields are re-parsed and `onRepairAttempt` fires for telemetry. When a custom `parse` is supplied (it REPLACES Zod validation), core first wire-decodes the args to the conceptual shape with the request's `FormatDescriptor` (`decodeWire` — array-of-pairs→record, null→undefined, numeric-key→tuple, …), so a custom parser is provider-agnostic and never sees a model family's wire quirks.
+
+### Basic tool
+
+```typescript
+import { Tool } from '@aeye/core';
+import z from 'zod';
+
+const getWeather = new Tool({
+  name: 'getWeather',
+  description: 'Get current weather for a location',
+  instructions: 'Use this to look up weather for {{location}}.',
+  schema: z.object({
+    location: z.string().describe('City name'),
+    units: z.enum(['celsius', 'fahrenheit']).default('celsius'),
+  }),
+  call: async (input, _refs, _ctx) => {
+    const data = await fetchWeather(input.location, input.units);
+    return { temperature: data.temp, condition: data.condition };
+  },
+});
+
+// Direct invocation (no model needed):
+const w = await getWeather.run({ location: 'Paris' }, {});
+```
+
+### Context-aware schema & applicability
+
+```typescript
+const manageData = new Tool({
+  name: 'manageData',
+  description: 'Manage data records',
+  schema: (ctx: Context<MyCtx, {}>) =>
+    ctx.userRole === 'admin'
+      ? z.object({ action: z.enum(['read', 'write', 'delete']) })
+      : z.object({ action: z.enum(['read']) }),
+  applicable: (ctx) => ctx.isAuthenticated,
+  call: async (input, _refs, ctx) => ({ action: input.action, by: ctx.userRole }),
+});
+```
+
+### Business-logic validation
+
+```typescript
+const placeOrder = new Tool({
+  name: 'placeOrder',
+  description: 'Place a product order',
+  schema: z.object({ itemId: z.string(), quantity: z.number().int().min(1) }),
+  validate: async (input) => {
+    const inStock = await checkInventory(input.itemId);
+    if (inStock < input.quantity) throw new Error(`Only ${inStock} available.`);
+  },
+  call: async (input) => ({ orderId: crypto.randomUUID(), ...input }),
+});
+```
+
+### Control-flow errors
+
+- `ToolInterrupt(message?)` — stop the prompt loop and return control to the caller. With `toolsComplete` a synthetic `[interrupted]` result is paired so the next round-trip is valid.
+- `PromptSuspend(message?)` — suspend without writing a tool result, for human-in-the-loop. See [prompts doc](./aeye-core-prompts.md#suspend--resume-human-in-the-loop). Never auto-paired.
+
+```typescript
+import { PromptSuspend } from '@aeye/core';
+
+call: async (input, _refs, ctx) => {
+  if (await needsApproval(input)) throw new PromptSuspend('awaiting approval');
+  return performAction(input);
+}
+```
+
+Also exported: `AnyTool`, `ToolCompatible<TContext, TMetadata>`.
+
+## Agent
+
+```typescript
+class Agent<TContext = {}, TMetadata = {}, TName extends string = string,
+  TInput extends object = {}, TOutput = string,
+  TRefs extends Tuple<ComponentCompatible<TContext, TMetadata>> = []>
+  implements Component<...>
+```
+
+An Agent is just typed orchestration — its `call` receives the resolved `refs` tuple positionally and wires components together however you like.
+
+### `AgentInput`
+
+| Field | Type | Notes |
+|------|------|-------|
+| `name` | `TName` | Identifier. |
+| `description` | `string` | Informational. |
+| `refs` | `TRefs` | **Required.** Components this agent uses. |
+| `call` | `(input: TInput, refs: TRefs, ctx) => TOutput` | **Required.** Orchestration logic. |
+| `applicable?` | `(ctx) => boolean \| Promise<boolean>` | Defaults to "any ref is applicable" (or `true` when no refs). |
+| `metadata?` / `metadataFn?` | `TMetadata` / fn | Execution metadata. |
+
+### Methods
+
+```typescript
+run(input?: TInput, ctx?: Context): TOutput
+applicable(ctx?): Promise<boolean>
+metadata(input?, ctx?): TMetadata | Promise<TMetadata>
+```
+
+### Example
+
+```typescript
+import { Agent } from '@aeye/core';
+
+const researchAgent = new Agent({
+  name: 'researcher',
+  description: 'Researches a topic',
+  refs: [searchTool, summarizePrompt, analyzePrompt] as const,
+  call: async (input: { topic: string }, [search, summarize, analyze], ctx) => {
+    const results = await search.run({ query: input.topic, limit: 5 }, ctx);
+    const summaries: string[] = [];
+    for (const r of results.items) {
+      const s = await summarize.get('result', { text: r.content }, ctx);
+      summaries.push(s?.summary ?? '');
+    }
+    return await analyze.get('result', { topic: input.topic, sources: summaries }, ctx);
+  },
+});
+
+const out = await researchAgent.run({ topic: 'Quantum Computing' }, { execute, messages: [] });
+```
+
+## Gotchas
+
+- Pass `refs` `as const` to keep the tuple's element types (so destructuring is correctly typed).
+- An Agent does **no** AI on its own — any model calls come from the prompts/tools it invokes, which need `execute`/`stream` on the forwarded `ctx`.
+- Tool `schema` returning `undefined` (or `applicable` false) excludes the tool from `compile()` output, so the model never sees it for that context.
+- `call` can be sync or async; `TOutput` flows through `Resolved<>` where the framework awaits it (e.g. tool results in prompt events).
+- A tool's return value is what the model sees by default (strings verbatim, otherwise `JSON.stringify`-d). To transform per-prompt what a tool result looks like to the model without changing the tool, use the prompt's [`onToolResult`](./aeye-core-prompts.md#tool-result-transformer) transformer (model-facing only; the raw result stays on `get('tools')`/`streamTools`).

package/aeye-core-types.md

@@ -0,0 +1,178 @@
+# @aeye/core — Type model & utilities
+
+The shared, provider-agnostic type model (`src/types.ts`) plus helper functions (`src/common.ts`) and Node resource helpers (`src/to.ts`). All re-exported from `@aeye/core`.
+
+## Component interface
+
+Every primitive implements `Component`:
+
+```typescript
+interface Component<TContext = {}, TMetadata = {}, TName extends string = string,
+  TInput extends object = {}, TOutput = string,
+  TRefs extends Tuple<ComponentCompatible<TContext, TMetadata>> = []> {
+  kind: string;                 // 'prompt' | 'tool' | 'agent' (or custom)
+  name: TName;
+  description: string;
+  refs: TRefs;
+  run(...[input, ctx]: OptionalParams<[TInput, Context<...>]>): TOutput;
+  applicable(...[ctx]): Promise<boolean>;
+  metadata(): TMetadata;
+  metadata(input?, ctx?): TMetadata | Promise<TMetadata>;
+}
+```
+
+Useful generic helpers exported alongside it: `AnyComponent`, `ComponentCompatible<C,M>`, `ComponentTuple`, and extractors `ComponentContext<C>`, `ComponentMetadata<C>`, `ComponentInput<C>`, `ComponentOutput<C>`, `ComponentRefs<C>`, `ComponentsAll<C>` (transitive refs), `Names<T>`. Type plumbing: `Tuple<T>` (`[] | [T, ...T[]]`), `Simplify`, `Extend`, `Plus`, `RequiredKeys`, `OptionalParams` (makes trailing params optional when they have no required keys — why `run()`/`get()` can be called with no args).
+
+## Context
+
+`Context<TContext, TMetadata>` = your `TContext` intersected with core execution fields:
+
+```typescript
+type Context<TContext, TMetadata> = TContext & {
+  messages?: Message[];
+  execute?: Executor<TContext, TMetadata>;
+  stream?: Streamer<TContext, TMetadata>;
+  signal?: AbortSignal;
+  estimateUsage?: (message: Message) => Usage | undefined;
+  maxOutputTokens?: number;     // reserve tokens for the model's output
+  contextWindow?: number;       // override window size for trimming
+  outputRetries?: number;       // default 2
+  forgetRetries?: number;       // context-trim retries, default 1
+  toolRetries?: number;         // default 2
+  instance?: Instance<any>;     // current execution instance
+  runner?: Runner;              // override how components execute (see withEvents)
+  toolCallId?: string;          // set by the prompt loop before a tool's call()
+};
+```
+
+`Executor` / `Streamer` are the functions you must supply to actually run a prompt:
+
+```typescript
+type Executor<TContext, TMetadata> =
+  (request: Request, context, metadata?, signal?: AbortSignal) => Promise<Response>;
+
+type Streamer<TContext, TMetadata> =
+  (request: Request, context, metadata?, signal?: AbortSignal) => AsyncGenerator<Chunk, Response>;
+```
+
+## Messages & content
+
+```typescript
+type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+
+interface Message {
+  role: MessageRole;
+  content: string | MessageContent[];
+  tokens?: number;          // used for automatic context trimming
+  name?: string;
+  toolCallId?: string;      // role: 'tool' — links result to a ToolCall
+  toolCalls?: ToolCall[];   // role: 'assistant' — model wants to call tools
+  refusal?: string;
+  reasoning?: Reasoning;
+  cache?: Record<string, any>;
+}
+
+interface MessageContent {           // type: 'text' | 'image' | 'file' | 'audio'
+  type: MessageContentType;
+  content: Resource;                 // string | URL | Blob | Uint8Array | stream | ...
+  format?: string;                   // 'png', 'mp3', 'pdf', ...
+}
+
+interface ToolCall { id: string; name: string; arguments: string; } // arguments = JSON string
+interface ToolDefinition {
+  name: string; description?: string;
+  parameters: z.ZodType<object>;     // raw Zod; strictify applied lazily by provider
+  strict?: boolean | number;
+  descriptor?: string;               // FormatDescriptor id chosen at request build time
+}
+```
+
+## Request & Response
+
+```typescript
+interface Request extends BaseRequest {   // BaseRequest: { model?: ModelInput; extra?: ... }
+  name?: string;
+  messages: Message[];
+  temperature?: number;           // 0.0–2.0
+  maxTokens?: number;
+  topP?: number;                  // 0.0–1.0
+  frequencyPenalty?: number;      // -2.0–2.0
+  presencePenalty?: number;       // -2.0–2.0
+  stop?: string | string[];
+  logProbabilities?: boolean;
+  logitBias?: Record<string, number>;
+  tools?: ToolDefinition[];
+  toolsOneAtATime?: boolean;
+  toolChoice?: ToolChoice;        // 'auto' | 'none' | 'required' | { tool: string }
+  responseFormat?: ResponseFormat;// 'text' | 'json' | { type: ZodType, strict, descriptor? }
+  reason?: { effort?: 'low'|'medium'|'high'; maxTokens?: number };
+  cacheKey?: string;
+  userKey?: string;
+}
+
+interface Response extends BaseResponse {  // BaseResponse: { usage?, model, extra? }
+  content: string;
+  toolCalls?: ToolCall[];
+  finishReason: FinishReason;     // 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'refusal'
+  refusal?: string;
+  reasoning?: Reasoning;
+}
+
+interface Chunk extends BaseChunk {        // streaming delta
+  content?: string;
+  toolCallNamed?: ToolCall;       // name fully received
+  toolCallArguments?: ToolCall;   // args streaming
+  toolCall?: ToolCall;            // fully received
+  finishReason?: FinishReason;
+  refusal?: string;
+  reasoning?: Reasoning;
+}
+```
+
+## Usage
+
+`Usage` mirrors model pricing for cost tracking — per-modality token counts (`text`, `audio`, `image`, `reasoning`, `embeddings`) plus an optional `cost` in dollars. See `src/types.ts` for the full shape.
+
+## Instances & Events (lifecycle tracking)
+
+```typescript
+type InstanceStatus = 'pending' | 'running' | 'completed' | 'failed' | 'interrupted';
+
+interface Instance<C extends AnyComponent> {
+  parent?: Instance<AnyComponent>;
+  id: string; component: C; context; input; status: InstanceStatus;
+  started?; running?; completed?;       // timestamps (ms)
+  error?; output?; children?: Instance<...>[];
+}
+
+interface Events<TRoot extends AnyComponent> {
+  onStatus?: (node: Instance<...>) => void;
+  onChild?: (node, child) => void;
+  onPromptEvent?: (instance, event: PromptEvent<...>) => void;
+}
+```
+
+A `Runner` wraps every component execution. Use `withEvents(events)` to build one:
+
+```typescript
+import { withEvents } from '@aeye/core';
+
+const runner = withEvents({
+  onStatus: (i) => console.log(`${i.component.name}: ${i.status}`),
+  onPromptEvent: (_i, e) => { if (e.type === 'usage') console.log('tokens', e.usage); },
+});
+
+await prompt.get('result', { text: 'hi' }, { execute, messages: [], runner });
+```
+
+## `common.ts` utilities
+
+- `resolveFn(fn, reprocess?)` — normalizes a `Fn<R, A>` (value | promise | function) into `(...args) => Promise<R>`. The pattern behind every `schema`/`config`/`input`/`*Fn` field.
+- Usage helpers: `accumulateUsage(target, add)`, `getInputTokens`, `getOutputTokens`, `getTotalTokens`, `accumulateReasoning`, `getReasoningText`.
+- Conversion helpers: `getModel(input)`, `getResponseFromChunks(chunks, model?)`, `getChunksFromResponse(response)`.
+- Async helpers: `isPromise`, `isAsyncGenerator`, `isSettled`, `resolve`, `yieldAll`, `consumeAll`.
+- `Fn<R, A>`, `FnResult`, `FnArgs`, `FnResolved`, `Resolved<T>` type helpers.
+
+## `to.ts` resource helpers (Node only — excluded from the browser build)
+
+`getResourceFormat`, `toURL`, `toBase64`, `toText`, `toStream`, `toReadableStream`, `toFile` — convert a `Resource` (string, URL, Blob, Uint8Array, stream, file path, …) to the form a provider needs. Import these only in Node contexts; the browser entry omits them.