@aeye/core 0.6.0 → 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,8 +31,9 @@ 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). `GOOGLE_STRICT`/`GOOGLE_NON_STRICT` declare 40, a MEASURED response to a real provider rejection; every other built-in declares none — see below. |
@@ -97,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
@@ -130,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`).
@@ -155,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
 
@@ -190,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.