@aeye/core 0.3.8 → 0.3.9

package/README.md

@@ -424,17 +424,116 @@ const adaptivePrompt = new Prompt({
 | `tools` | Function/tool calling |
 | `json` | JSON output mode |
 | `structured` | Structured outputs with schemas |
+| `toolsStrict` | Strict-mode tool input schemas (auto-derived; see [Strict Mode](#strict-mode)) |
 | `reasoning` | Extended chain-of-thought reasoning |
 | `zdr` | Zero data retention |
 
+## Strict Mode
+
+Each LLM provider that supports strict mode does so with its own JSON Schema dialect. `@aeye/core` reconciles them under a single `FormatDescriptor` so a Zod schema authored once works against any of them.
+
+### `strict` on Tool / Prompt
+
+`Tool.strict` and `Prompt.strict` are `boolean | number`:
+
+| Value | Meaning |
+|---|---|
+| `true` | **Require** strict. `@aeye/ai` filters selection down to models that declare strict support; the request 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 numbers win when there are more strict-requesting items than the chosen model's per-request budget allows. |
+| omitted | Treated as `1`. |
+
+```typescript
+new Tool({ name: 'must',     /* default 1 */                schema: z.object({...}) }); // best-effort
+new Tool({ name: 'critical', strict: true,                  schema: z.object({...}) }); // hard require
+new Tool({ name: 'meh',      strict: false,                 schema: z.object({...}) }); // never strict
+new Tool({ name: 'top',      strict: 100,                   schema: z.object({...}) }); // high priority
+```
+
+Default `1` keeps "it just works" against unannotated models — strict where the chosen model supports it, lenient elsewhere. Set `true` only when strict is non-negotiable.
+
+### Native format descriptors
+
+Seven descriptors ship out of the box:
+
+| Descriptor | 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 / numeric range constraints, per-request slot budgets (20 strict tools / 24 optional params / 16 union types). |
+| `GOOGLE_STRICT` | google / strict | `prefixItems`, `$ref: '#'` recursion, `propertyOrdering` emitted, restricted format whitelist. |
+| `LENIENT` | lenient / non-strict | No rewrites, all features pass 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. |
+
+```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()),
+});
+
+// Same Zod, different wire shapes:
+toJSONSchema(schema, OPENAI_STRICT);                    // tags → array of {key, value}
+toJSONSchema(schema, ANTHROPIC_STRICT);                 // tags → array of {key, value} (open records unsupported)
+toJSONSchema(schema, getDescriptor('google', true));    // tags → standard additionalProperties
+
+// Backward-compat overloads still work:
+toJSONSchema(schema, true);   // === OPENAI_STRICT
+toJSONSchema(schema, false);  // === LENIENT
+```
+
+### Registering a custom descriptor
+
+You can ship your own descriptor for a provider or dialect that isn't supported natively. Define it as a `FormatDescriptor` value and register it with `registerDescriptor(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',                   // or 'anthropic' | 'google' | 'lenient'
+  // Override only the fields that differ from the baseline:
+  recordEncoding: 'open-record',      // your provider supports additionalProperties: <schema>
+  tupleEncoding: 'prefix-items',
+  supportsRecursion: true,
+};
+
+registerDescriptor(MY_PROVIDER_STRICT);
+```
+
+Once registered:
+
+- Provider code can pass the descriptor to `toJSONSchema(schema, MY_PROVIDER_STRICT)` and `strictify(schema, MY_PROVIDER_STRICT)`.
+- The Prompt's validation roundtrip (which looks up descriptors by id from the request) will resolve `'my-provider-strict'` correctly.
+- A custom `Provider` implementation can return this descriptor from its `getStrictFormat`-equivalent helper.
+
+The descriptor's full field list is exported as the `FormatDescriptor` interface — every flag is documented inline. Common adjustments:
+
+| Field | Controls |
+|---|---|
+| `objectAllFieldsRequired` | Whether every property must appear in `required[]`. |
+| `objectClosedByDefault` | Whether every object emits `additionalProperties: false`. |
+| `recordEncoding` | `'array-of-pairs'` vs `'open-record'`. |
+| `tupleEncoding` | `'object-numeric-keys'` vs `'prefix-items'` vs `'items-union'`. |
+| `allowAllOf` / `allowAnyOf` / `allowOneOf` | JSON-Schema combinator support. |
+| `supportedStringFormats` | `'all'` or a `Set<string>` whitelist (`'date-time'`, `'email'`, etc.). |
+| `optionalAsNullable` | Whether `optional` fields are emitted as `T \| null` (OpenAI strict) vs omitted from `required[]`. |
+| `supportsRecursion` | Whether `$ref` self-reference works under this dialect. |
+| `maxStrictTools` / `maxStrictOptionalParams` / `maxStrictUnionTypes` | Per-request budget caps; `undefined` means no documented limit. |
+
+You don't need to set every field — spread an existing descriptor and override deltas. Tested via `analyzeSchema` + the schema test suite; see the strict-mode guide in `@aeye/docs` for end-to-end examples.
+
 ## API Reference
 
 ### Prompt
 
 ```typescript
-class Prompt<TContext, TMetadata, TName extends string, TInput extends object, TOutput extends object | string, TTools extends Tuple<ToolCompatible<TContext, TMetadata>>>
+class Prompt<TContext, TMetadata, TName extends string, TInput extends object, TOutput extends object | string, TTools extends Tuple<ToolCompatible<TContext, TMetadata>>, TDecoded extends unknown = TOutput>
 ```
 
+`TDecoded` is the type a custom `parse` produces from the model's structured output (e.g. a built AST/class instance); it types `validate` and the decoded output. It defaults to `TOutput` (the wire type) when no custom `parse` is supplied — `schema` always stays the wire type.
+
 **Constructor Options (`PromptInput`):**
 - `name: string` - Unique identifier
 - `description: string` - Purpose description
@@ -461,9 +560,11 @@ class Prompt<TContext, TMetadata, TName extends string, TInput extends object, T
 ### Tool
 
 ```typescript
-class Tool<TContext, TMetadata, TName extends string, TParams extends object, TOutput, TRefs extends Tuple<ComponentCompatible<TContext, TMetadata>>>
+class Tool<TContext, TMetadata, TName extends string, TParams extends object, TOutput, TRefs extends Tuple<ComponentCompatible<TContext, TMetadata>>, TDecoded extends unknown = TParams>
 ```
 
+`TDecoded` is the type a custom `parse` produces from the raw wire args (e.g. a built class instance); it types `call`, `validate`, and `metadataFn`. It defaults to `TParams` (the wire type) when no custom `parse` is supplied — `schema` always stays the wire type.
+
 **Constructor Options (`ToolInput`):**
 - `name: string` - Unique identifier (shown to the AI model)
 - `description: string` - What the tool does (shown to the AI model)

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`).