@aeye/core 0.5.4 → 0.7.0

package/aeye-core-prompts.md

@@ -1,178 +1,179 @@
-# @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? }`.
-
-Four semantics of that hook are load-bearing and are not visible in the types:
-
-- **`PromptReconfig.maxIterations` is RELATIVE, not absolute.** The loop assigns `maxIterations = iterations + value`, so returning `N` means "this round plus `N - 1` more". Return `budget - stats.iteration` to set an absolute ceiling. Returning `0` **breaks out immediately** — and with no result parsed yet the run then throws its own generic `failed without a specified error`, so `0` is not a graceful stop.
-- **`PromptReconfigInput.maxIterations` is the ceiling as it stood BEFORE this call** — whatever the previous round set. A decision that must track a ceiling you are raising in the same call has to use your own value, not this field.
-- **The error/success counters are cumulative for the run**, not per round: `toolSuccesses` / `toolParseErrors` / `toolCallErrors` only ever grow, so "did THIS round make progress?" is a delta you keep yourself. `toolRetries` / `outputRetries` / `forgetRetries` are the opposite — they are the *remaining* allowances and count down.
-- **`reconfig` runs at the END of an iteration**, after tool dispatch and output parsing and before the `dynamic` re-resolve — so anything it changes takes effect on the NEXT model call.
-
-## 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.
+# @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, sent as the system message. `{{tools}}` is auto-appended (wrapped in `<tools>`) when tools exist and you didn't include it. |
+| `userTurn?` | `string` | User message added after the system message when there's no conversation (Anthropic, Bedrock and some OpenRouter hosts require one). Defaults to `ctx.userTurn`, then `DEFAULT_USER_TURN` (`'Begin.'`). |
+| `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? }`.
+
+Four semantics of that hook are load-bearing and are not visible in the types:
+
+- **`PromptReconfig.maxIterations` is RELATIVE, not absolute.** The loop assigns `maxIterations = iterations + value`, so returning `N` means "this round plus `N - 1` more". Return `budget - stats.iteration` to set an absolute ceiling. Returning `0` **breaks out immediately** — and with no result parsed yet the run then throws its own generic `failed without a specified error`, so `0` is not a graceful stop.
+- **`PromptReconfigInput.maxIterations` is the ceiling as it stood BEFORE this call** — whatever the previous round set. A decision that must track a ceiling you are raising in the same call has to use your own value, not this field.
+- **The error/success counters are cumulative for the run**, not per round: `toolSuccesses` / `toolParseErrors` / `toolCallErrors` only ever grow, so "did THIS round make progress?" is a delta you keep yourself. `toolRetries` / `outputRetries` / `forgetRetries` are the opposite — they are the *remaining* allowances and count down.
+- **`reconfig` runs at the END of an iteration**, after tool dispatch and output parsing and before the `dynamic` re-resolve — so anything it changes takes effect on the NEXT model call.
+
+## 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`, `toolCallId` (the model's call id, also on its `role: 'tool'` reply) and `args`. `onToolIntercept(tool, args, ctx, call)` gets the `ToolCall` too. A valid call left unrun because a sibling in the batch was invalid (an unknown tool) is answered `[not run: …; call it again]`
+- `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`). It removes whole groups, oldest first: a message with the `role: 'tool'` replies after it, so tool calls never lose their replies. System messages, the last user message and the most recent group stay; an agent's tool loop after the last user message is trimmed too. `forget` is `protected`, so a subclass can summarize instead of drop. 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

@@ -31,11 +31,12 @@ A descriptor (see `src/schema.ts` line ~26 for the fully documented interface) d
 | `allowAllOf` / `allowAnyOf` / `allowOneOf` | Combinator support. |
 | `allowRootRef` / `allowDefsRef` | Whether `$ref: '#'` / `$ref: '#/$defs/X'` are permitted. Under `allowDefsRef: false` the emitter never produces a `$defs` section at all: a shared node is **inlined** at each use site, and a non-root cycle takes the bounded placeholder (`supportsRecursion` alone does not license a `$ref` the descriptor cannot spell). |
 | `anyEncoding` | How `z.any()` / `z.unknown()` is emitted — see below. |
-| `supportedStringFormats` | `'all'` or a `Set<string>` whitelist. |
+| `supportedStringFormats` | `'all'` (every format JSON Schema 2020-12 defines) or a `Set<string>` whitelist. |
 | `supportsRecursion` | Whether `$ref` self-reference works. |
+| `structuredOutputAlwaysStrict` | The family has no non-strict structured output (Anthropic) — see [below](#structuredoutputalwaysstrict). |
 | `maxStrictTools` / `maxStrictOptionalParams` / `maxStrictUnionTypes` | Per-request slot budgets (`undefined` = no documented limit). |
 | `schemaSizeLimits` | Per-SCHEMA size ceilings — properties, nesting, total string characters, enum values (`undefined` = no documented limit) — see below. |
-| `maxEnumValues` | Opt-in ceiling on how many values ONE emitted `enum` may carry (`undefined` = no cap, and that is what every built-in declares) — see below. |
+| `maxEnumValues` | Opt-in ceiling on how many values ONE emitted `enum` may carry (`undefined` = no cap). `GOOGLE_STRICT`/`GOOGLE_NON_STRICT` declare 40, a MEASURED response to a real provider rejection; every other built-in declares none — see below. |
 
 ### `schemaSizeLimits` — how BIG one strict schema may be
 
@@ -60,7 +61,7 @@ Scope is Structured Outputs — a tool carrying `strict: true`, or a `json_schem
 
 The measurement is taken from the **Zod** schema rather than from the emitted JSON, so where an encoding is descriptor-dependent it counts the widest one (a record as its `{key, value}` pair form, a tuple as its numeric-key form). Over-counting costs strictness on a schema that would have fitted; under-counting costs an HTTP 400, so the rounding goes up. `$defs` entry names are not counted: they are generated at emit time, few, and short against a 120,000-character budget.
 
-### `maxEnumValues` — an opt-in dialect ceiling that WIDENS, and why no built-in sets one
+### `maxEnumValues` — an opt-in dialect ceiling that WIDENS, and why only Google sets one
 
 Some providers may reject a schema whose `enum` is simply too long. That is **not** one of the per-request budgets above: those are strict-mode allowances the `SchemaBudget` spends across a whole request, degrading an item that no longer fits to the family's non-strict descriptor, whereas this one would fire whatever the strictness, so it is enforced structurally at the point an `enum` is emitted.
 
@@ -75,15 +76,19 @@ Truncating would make the values past the cap **unreachable** — the wire schem
 
 The trade is enforcement: a widened node no longer rejects a value structurally, so whatever validates the model's output afterwards must. `Tool.parse` does — it runs against the ORIGINAL zod schema, whose `enum` is untouched — so a hallucinated member comes back as a normal, re-promptable validation error.
 
-**No built-in descriptor declares a cap, and that is a measured result.** The field exists because a large `enum` was believed to make Gemini answer `400 INVALID_ARGUMENT`. Measured against `google/gemini-3-flash-preview` through OpenRouter (2026-08-23), it does not: single-parameter enums at 50/64/72/80/96/128/256/512/1024/**2048** values (52 KB of tool schema) all returned HTTP 200 with the expected tool call, under `tool_choice` both `required` (which is what makes Gemini compile a decoding grammar) and `auto` — as did 96 values with 80-character members, 20 tools each carrying a 96-value enum in one request, a 96-value enum next to `strict: true` / `minItems` / `propertyOrdering` / a sibling `anyOf`, and a 2048-value enum inside a `response_format` schema. Reliability was compared too, since a cap's whole cost is losing the enum's can't-hallucinate guarantee: 10 trials each of `enum` vs plain-string-with-full-list, over confusable near-duplicate names, at 96 and again at 512 values — both picked the correct member 10/10 with zero off-list answers.
+**`GOOGLE_STRICT`/`GOOGLE_NON_STRICT` declare `maxEnumValues: 40`. Every other built-in declares no cap.** The field exists because a large `enum` was believed to make Gemini answer `400 INVALID_ARGUMENT`. An initial round of measurement against `google/gemini-3-flash-preview` through OpenRouter (2026-08-23) looked like it disproved that: single-parameter enums at 50/64/72/80/96/128/256/512/1024/**2048** SYNTHETIC values (`name_0`, `name_1`, …) all returned HTTP 200, as did an eleven-tool roster modelled on a real kind-authoring agent with a 96-value enum on one tool.
 
-A second pass answered the obvious objection — that an isolated probe is not what a real session sends. Same date and model, upstream **pinned to Google AI Studio** with fallbacks off (the upstream that served the production failures), an eleven-tool roster emitted through this library for a Google model and modelled on a real kind-authoring agent (`fn_load` / `fn_search` / `type_load` / `api_signature` / `api_set` / …, real descriptions, real system prompt): a 96-value enum on one of those tools returned 200 with the expected tool call under `tool_choice` `required` and `auto` alike, as did the same roster at 8 values and a tool carrying a bare typeless `{}` property.
+**That conclusion was wrong, because none of it used the CONTENT of a real session.** A third round replayed the exact wire bytes of an actual product request — `fn_load`'s `names` array, enum-constrained to a real session's 98 known component/fn names (`default_renderer`, `QueryWidget`, `ConfirmPrompt`, `list_widget_types`, …) — and it 400'd, reproducibly, twice, byte-for-byte identical to what was actually sent. Bisecting that real value list: 90 values passes, 93 fails. Bisecting what differs from the earlier synthetic probes: 98 SHORT synthetic values (284 total characters) pass; 206 short values matching the real list's total character count (714 characters) also pass; only the real, longer, identifier-shaped values fail, and only past ~92 of them. So the limit tracks neither raw member count nor total character/byte budget — most likely actual tokenized grammar-state count, which short repetitive synthetic strings compress far below what real identifier text does at the same count or character budget. This is why the first two rounds' synthetic and lightly-realistic probes never tripped it.
 
-The caveat that keeps that from being proof: the **control** — the recursive `$defs/Any` shape documented elsewhere in this file as 100% reproducible HTTP 400 — also returned 200, pinned and unpinned, forced and automatic, both hand-built and as the product's real 32 KB gin `api_set` schema. That failure class is not visible from this route today, so treat the numbers as evidence, not a verdict.
+The widen-to-string fallback this field triggers was verified against the exact failing real schema: dropping `enum` and putting the same 98 values into the `description` of a plain string field returned HTTP 200 with the expected tool call — confirming the fallback mechanism actually fixes the failure it exists for, not just a synthetic stand-in.
 
-One trap for whoever measures this next: at `max_tokens: 64` the `$defs/Any` tool answered `finish_reason: "length"` with no tool call and empty content, which reads exactly like a grammar that produced nothing. It is not — this model spends reasoning tokens first, and at 400 the identical request emitted a correct call in 28 output tokens. Give a forced-tool probe room before calling an empty completion a failure.
+`40` is not a measured edge — it is a conservative floor with roughly 2x margin under the real one (90 passes / 93 fails) measured on this one real value set. Given the failure tracks content, not just count, a different session's actual name list could plausibly fail at a different count; 40 was also the cap the product that surfaced this ran under in production for months, which is corroborating evidence it holds in practice, not just in this one measurement.
 
-So: **set this only against a measured provider rejection, and set it as high as the measurement allows.** An `enum` that fits is the more correct encoding, because it is the one the model cannot answer outside of.
+The reliability comparison from the earlier rounds still stands and is why a cap is preferable to leaving every enum uncapped "to be safe" at a much lower number: `enum` vs plain-string-with-full-list, 10 trials each over confusable near-duplicate names at 96 and 512 values, scored 10/10 on-target with zero off-list answers for BOTH encodings. So there is no reliability cost to raising this cap later if a higher safe value is measured — only downside risk to leaving it too high.
+
+One trap for whoever measures this next: with `max_tokens` at 64, a forced-tool probe can come back `finish_reason: "length"` with no tool call and empty content, which reads exactly like a grammar that produced nothing. It usually is not — this model spends reasoning tokens first. Give a forced-tool probe room before calling an empty completion a failure.
+
+So: **set this only where a provider is MEASURED to reject a large enum using the SESSION'S OWN real content, not synthetic stand-ins, and set it conservatively below the measured edge until more value sets are tested.** An `enum` that fits is the more correct encoding, because it is the one the model cannot answer outside of.
 
 ### `anyEncoding` — and what each mode requires
 
@@ -93,22 +98,42 @@ An open "any JSON value" slot has no single portable spelling, so each dialect p
 |------|------|------|
 | `'recursive-strict'` | `$defs/Any` with array-of-pairs records (OpenAI strict has no open objects) | `allowAnyOf`, `allowDefsRef`, `supportsRecursion` |
 | `'recursive-open'` | `$defs/Any` with `additionalProperties: <self>` | `allowAnyOf`, `allowDefsRef`, `supportsRecursion` |
-| `'flat'` | inline non-recursive `anyOf` over every JSON type | `allowAnyOf` |
+| `'flat'` | inline non-recursive `anyOf` over every JSON type (xAI strict) | `allowAnyOf` |
 | `'unconstrained'` | the empty schema `{}` (plus any `description`) | nothing |
+| `'none'` | no spelling exists (Anthropic strict) — the schema is not sent strict | nothing |
+
+`'none'` is for a dialect that rejects every spelling of "any": Anthropic strict answers 400 to `{}` ("Empty schema … is not supported"), a typeless schema, `additionalProperties: true` and a recursive `$defs/Any` alike. A schema containing `z.any()` / `z.unknown()`, or a recursion cycle (whose placeholder bottoms out at "any"), is therefore not sendable under it: `SchemaBudget` degrades such a tool to the family's non-strict descriptor (even under `strict: true`), and `canExpress` answers `false` so such an output goes as prompt text.
 
 `'unconstrained'` is the only mode available to a dialect that forbids combinators **and** named `$defs` (Google). Per JSON Schema a schema with no assertion keywords validates every instance, which is exactly what "any value" means — so it is lossless as a constraint, and the source schema's `description` still rides along as the human/model-facing signal.
 
+### `structuredOutputAlwaysStrict`
+
+Anthropic compiles every structured output to a grammar (`output_config.format` is strict by definition, and OpenRouter flags every `json_schema` bound for Claude), so an output "degraded" to the non-strict dialect still earns `too many optional parameters (30) … (limit: 24)`. A descriptor declaring `structuredOutputAlwaysStrict: true` (`ANTHROPIC_STRICT`) changes two things:
+
+- `canExpress` also requires the output schema to fit the strict limits **on its own** — the per-schema size limits and the per-request optional-parameter and union budgets. An output that doesn't fit is delivered as prompt text under `schemaDelivery: 'auto'`.
+- `SchemaBudget` never degrades an output to the non-strict variant; it keeps the strict dialect.
+
+## What every dialect emits
+
+A few emitter rules hold under every descriptor, `LENIENT` included:
+
+- **`z.nullable()` always admits `null`**, spelled as an `anyOf` branch (`anyOf: [T, { type: 'null' }]`) wherever the dialect has `anyOf`; a `["T", "null"]` type array is the spelling of last resort (o3's strict function validator rejects it). Earlier versions dropped the null outside OpenAI strict, so a grammar-constrained model could never answer it.
+- **Only real JSON Schema formats are emitted.** `'all'` means the formats JSON Schema 2020-12 defines (`date-time`, `email`, `uri`, `uuid`, …); Zod's own check names that share the field — `regex` from `.regex()`, `cuid`, `starts_with` — are never emitted (DeepInfra answers `Unknown format: regex`). A whitelisted descriptor emits only its list.
+- **Open records drop `propertyNames` for a plain string key**: it constrains nothing, and DeepInfra and Cloudflare reject the keyword (`Unimplemented keys: ["propertyNames"]`). A key schema with real constraints (an enum, a pattern) still emits it.
+- **`strictify` handles `.meta({ id })`.** The strictified clone carries the id as `aid` (zod's global registry refuses a second schema with the same `id`), and `aid` names the same `$defs` entry.
+
 ## Built-in descriptors
 
-Seven ship frozen and pre-registered:
+Nine 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. |
+| `ANTHROPIC_STRICT` | anthropic / strict | closed objects, no recursion, no length/range constraints; budgets 20 tools / 24 optional params / 16 unions; format whitelist `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `uri`, `ipv4`, `ipv6`, `uuid`; `anyEncoding: 'none'`; `structuredOutputAlwaysStrict`. |
 | `GOOGLE_STRICT` | google / strict | `prefixItems`, `$ref: '#'` recursion, `propertyOrdering`, restricted format whitelist, `z.any()` → `unconstrained` (Gemini forbids `anyOf` and named `$defs`). |
+| `XAI_STRICT` | xai / strict | `anyOf` and `oneOf`, non-circular `$defs`, `prefixItems` tuples, open records, format whitelist incl. `uri`, `pattern`, length/item/numeric bounds; no `allOf`; `z.any()` → `flat`. |
 | `LENIENT` | lenient / non-strict | No rewrites; everything passes through. Default for unannotated models. |
-| `OPENAI_NON_STRICT`, `ANTHROPIC_NON_STRICT` | family / non-strict | Aliased to `LENIENT` but tagged with the family for diagnostics. |
+| `OPENAI_NON_STRICT`, `ANTHROPIC_NON_STRICT`, `XAI_NON_STRICT` | family / non-strict | Aliased to `LENIENT` but tagged with the family for diagnostics. |
 | `GOOGLE_NON_STRICT` | google / non-strict | `LENIENT` **except** `anyEncoding: 'unconstrained'`. Gemini compiles a decoding grammar whenever a tool call is forced, and rejects a self-referencing `$defs/Any` when it does — which has nothing to do with a per-tool strict flag (Google's function-calling API has none), so the encoding belongs to the dialect. |
 
 ## Functions
@@ -126,6 +151,7 @@ hasDescriptorFamily(family: string | undefined): boolean
 resolveDescriptor(options: ToJSONSchemaOptions | boolean | FormatDescriptor): FormatDescriptor
 strictestOf(a, b): FormatDescriptor
 strictPriority(requested: boolean | number | undefined): number
+canExpress(schema, descriptor): boolean   // can it go out as structured output?
 ```
 
 - `toJSONSchema` accepts a descriptor, a `ToJSONSchemaOptions` object, or a boolean (back-compat: `true` ⇒ `OPENAI_STRICT`, `false` ⇒ `LENIENT`).
@@ -151,18 +177,18 @@ 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:
+`new SchemaBudget(tool, output = tool)` allocates strict "slots" across a single request when a descriptor has per-request limits (e.g. Anthropic). Tools are emitted through `tool` and the structured output through `output`; they differ when a model has strict structured output but no strict tools (gpt-audio, for one) or the reverse, so neither kind is sent `strict: true` the model can't take. Only the slot counters are shared, sized from the stricter of the two. `@aeye/ai`'s `buildSchemaBudget` builds it from the model's `'toolsStrict'` and `'structured'` capabilities. Providers call:
 
 ```typescript
 budget.allocateTool(schema, requested): FormatDescriptor   // returns strict or the family's non-strict, decrements
 budget.allocateOutput(schema, requested): FormatDescriptor // output schema; consumes param/union budget, not a tool slot
 ```
 
-It falls back when `requested === false`, when the schema uses an unrepresentable feature, when the schema exceeds the dialect's `schemaSizeLimits`, or when a positive-number request can't fit the remaining budget (priority order; `true` always wins subject to *budget*, never subject to feasibility or size).
+It falls back when `requested === false`, when the schema uses an unrepresentable feature, when the schema exceeds the dialect's `schemaSizeLimits`, when the schema's optional parameters or unions **alone** exceed the per-request budget (no other item can make it fit), or when a positive-number request can't fit the remaining budget (priority order; `true` always wins subject to *budget*, never subject to feasibility or size). An output under a `structuredOutputAlwaysStrict` descriptor is never degraded — `canExpress` already kept an unfitting one off the wire.
 
 **The fallback is the descriptor's own family, non-strict — never the family-blind `LENIENT`.** A dialect rule can outlive strict mode: `GOOGLE_NON_STRICT` exists for exactly one such rule, the `unconstrained` encoding of `z.any()`, because Gemini compiles a decoding grammar whenever a tool call is forced and no per-tool `strict` flag is involved. Degrading to `LENIENT` put the self-referencing `$defs/Any` that encoding was created to avoid straight back on the Google wire — and did so for *every* schema that degrades, which under `GOOGLE_STRICT` (`allowAnyOf: false`) is every recursive gin/query program schema there is. For the other families the change is behaviour-neutral by construction: `OPENAI_NON_STRICT` / `ANTHROPIC_NON_STRICT` are `LENIENT` with a family tag, and a family that registers no non-strict variant resolves to `LENIENT`. Only the `descriptor` id pinned on the tool differs, and it round-trips through `getDescriptorById`.
 
-"Unrepresentable" here means a **combinator the descriptor forbids** (`z.union` → `anyOf`, `z.intersection` → `allOf`), because nothing rewrites those away — a schema carrying one under `GOOGLE_STRICT` is a provider HTTP 400. **Recursion is not unrepresentable**: the emitter replaces any back-edge the descriptor cannot spell with a bounded placeholder, so a recursive schema stays strict (looser at the back-edge, never rejected). That is the difference between this check and `canExpress`, which additionally treats a widened back-edge as a reason to fall back — the right answer for a structured *output* (it can be delivered as prompt text instead) and the wrong one for a *tool* (it cannot).
+"Unrepresentable" here means a **combinator the descriptor forbids** (`z.union` → `anyOf`, `z.intersection` → `allOf`), because nothing rewrites those away — a schema carrying one under `GOOGLE_STRICT` is a provider HTTP 400. **Recursion is not unrepresentable**: the emitter replaces any back-edge the descriptor cannot spell with a bounded placeholder, so a recursive schema stays strict (looser at the back-edge, never rejected). The exception is an `anyEncoding: 'none'` dialect (Anthropic strict): the placeholder bottoms out at "any", which it cannot spell, so a cycle — like `z.any()` / `z.unknown()` — degrades the tool there. That is the difference between this check and `canExpress`, which additionally treats a widened back-edge as a reason to fall back — the right answer for a structured *output* (it can be delivered as prompt text instead) and the wrong one for a *tool* (it cannot).
 
 ## Registering a custom descriptor
 
@@ -186,5 +212,6 @@ Once registered, `toJSONSchema(schema, MY_PROVIDER_STRICT)` / `strictify(...)` w
 ## 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`.
+- Strict dialects drop features they can't represent (Anthropic: no numeric ranges, formats outside its whitelist). If a feature matters, check `analyzeSchema` against the descriptor or force `strict: false`.
+- Under Anthropic strict, `z.any()`, `z.unknown()` and recursive schemas never go out strict: such a tool degrades to non-strict and such an output is sent as prompt text.
 - The `JSONSchema` / `JSONSchemaType` / `ToJSONSchemaOptions` / `DescriptorFamily` types are exported for tooling.