@ax-llm/ax 22.0.8 → 23.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ax-llm/ax",
-  "version": "22.0.8",
+  "version": "23.0.0",
   "type": "module",
   "description": "The best library to work with LLMs",
   "repository": {

package/skills/ax-agent-context.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-context
 description: This skill helps an LLM pick the right AxAgent context tool for a job - contextMap for recurring corpora, contextPolicy presets for within-run trajectory compaction, agent.optimize for offline GEPA instruction/demo tuning, agent.playbook for an evolving context playbook (offline evolve + online update), and recall/memories + skills for per-turn retrieval. Use when the user asks "which context feature should I use", confuses contextMap with contextPolicy or memory, or wants a decision guide for long-context agents. For contextPolicy/contextMap codegen use ax-agent-rlm; for recall/skills use ax-agent-memory-skills; for agent.optimize or agent.playbook use ax-agent-optimize.
-version: "22.0.8"
+version: "23.0.0"
 ---
 
 # AxAgent Context Selection (@ax-llm/ax)
@@ -25,6 +25,7 @@ Use this skill to route a context-management need to the right AxAgent tool, the
 - Evolve a context playbook -> `agent.playbook(...)` (offline from examples, or online from live feedback).
 - Tune instructions/demos offline -> `agent.optimize(...)` (GEPA).
 - Fetch facts or guides on demand -> `recall(...)` for memories, `discover({ skills })` for skill guides.
+- A single oversized input value (a pasted doc, a big JSON blob) -> do nothing; `autoUpgrade` (ON by default) keeps it runtime-only with a prompt preview. Reach for `contextFields` only when you want a specific inline policy or the value is a large required non-string field. See `ax-agent-rlm`.
 
 ## Anti-Patterns
 

package/skills/ax-agent-memory-skills.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-memory-skills
-description: This skill helps an LLM generate correct AxAgent memory retrieval, context-map, and dynamic skill-loading code using @ax-llm/ax. Use when the user asks about contextMap, AxAgentContextMap, onMemoriesSearch, recall(...), inputs.memories, onLoadedMemories, onUsedMemories, onSkillsSearch, discover({ skills }), onLoadedSkills, onUsedSkills, preloaded skills, loaded memory/skill IDs, or carrying memories across forward() calls.
-version: "22.0.8"
+description: This skill helps an LLM generate correct AxAgent memory retrieval, context-map, and dynamic skill-loading code using @ax-llm/ax. Use when the user asks about contextMap, AxAgentContextMap, onMemoriesSearch, memoriesCatalog, recall(...), inputs.memories, onLoadedMemories, onUsedMemories, onSkillsSearch, skillsCatalog, AxAgentCatalogSkill, discover({ skills }), onLoadedSkills, onUsedSkills, preloaded skills, preloading memories at forward time, relevanceRanking hints, loaded memory/skill IDs, or carrying memories across forward() calls.
+version: "23.0.0"
 ---
 
 # AxAgent Memory And Skills Rules (@ax-llm/ax)
@@ -10,11 +10,12 @@ Use this skill when an agent needs a persistent context map, task-relevant memor
 
 ## Use These Defaults
 
-- Use `onMemoriesSearch` when the agent should pull relevant context from an external store instead of stuffing everything into the prompt upfront.
+- Use a static `skillsCatalog` / `memoriesCatalog` when the skill guides or memories fit in a plain array — Ax then backs `discover({ skills })` / `recall(...)` with a built-in deterministic local search and no host search code is needed.
+- Use `onSkillsSearch` / `onMemoriesSearch` when retrieval needs a real backend (vector DB, BM25 service, KV). A host callback always takes precedence over the catalog's built-in search.
 - Use `contextMap` when repeated runs inspect the same long external context and should accumulate a small orientation cache automatically.
-- Use `onSkillsSearch` when the agent should load usage guides, runbooks, or domain conventions into the executor prompt on demand.
-- `recall(...)` is available to distiller and executor stages when `onMemoriesSearch` is set.
-- `discover({ skills })` is available to the executor when `onSkillsSearch` is set.
+- `recall(...)` is available to distiller and executor stages when `onMemoriesSearch` or a non-empty `memoriesCatalog` is set.
+- `discover({ skills })` is available to the executor when `onSkillsSearch` or a non-empty `skillsCatalog` is set.
+- With `skillsCatalog`, the executor prompt also gains a static `### Available Skills` index (id + name + description), so skill discovery is targeted instead of blind.
 - Both `recall(...)` and `discover({ skills })` return `void`. The loaded content appears on the next turn.
 - Use `onLoadedMemories` / `onLoadedSkills` to observe what got loaded.
 - Use `onUsedMemories` / `onUsedSkills` to track what the actor says it actually relied on.
@@ -112,6 +113,37 @@ type AxAgentMemoryResult = {
 };
 ```
 
+### Static catalog (no callback)
+
+If the memory set fits in a plain array, skip the callback entirely: pass `memoriesCatalog` and Ax backs `recall(...)` with a built-in deterministic local search (idf-weighted token overlap over `id` + content; not regex, not embeddings). The `alreadyLoaded` contract is preserved — entries already on `inputs.memories` are excluded before ranking.
+
+```typescript
+const myAgent = agent('task:string -> answer:string', {
+  contextFields: [],
+  memoriesCatalog: [
+    { id: 'deploy-window', content: 'Prod deploys only on Tuesday afternoons.' },
+    { id: 'user-prefs', content: 'User prefers concise answers.' },
+  ],
+});
+```
+
+Rules:
+
+- If both `memoriesCatalog` and `onMemoriesSearch` are set, the host callback handles all `recall(...)` searches; the catalog still powers the advisory `relevanceRanking` hint.
+- Catalog content is NOT preloaded into the prompt; entries load only when recalled.
+- The built-in search is lexical. For semantic retrieval over large stores, supply `onMemoriesSearch` instead.
+
+### Preloading memories at forward time
+
+To seed specific memories for one run (no recall round-trip), pass them as the `memories` input value. They render on `inputs.memories` from the first turn and merge with anything recalled later (deduped by `id`).
+
+```typescript
+await myAgent.forward(ai, {
+  task: 'Plan the deploy',
+  memories: [{ id: 'deploy-window', content: 'Prod deploys only on Tuesday afternoons.' }],
+});
+```
+
 ### Actor usage
 
 ```javascript
@@ -170,12 +202,12 @@ const myAgent = agent('task:string -> answer:string', {
 
 Use `onSkillsSearch` when the agent needs to load skill guides such as usage instructions, runbooks, or domain conventions into the executor's system prompt on demand. The actor decides which skills to fetch and when, so you do not pre-render every skill into every prompt.
 
-When `onSkillsSearch` is set, the executor stage gains:
+When `onSkillsSearch` is set, the distiller and executor stages gain:
 
 1. A "Loaded Skills" section in the system prompt that renders matched skill bodies with stable `ID:` values sorted by `id`.
 2. A `discover({ skills })` path the actor `await`s to load more skills. Loaded entries appear in the next turn's prompt. `discover(...)` returns nothing.
 
-The distiller and responder do not see skills. Only the executor.
+Skills the distiller loads carry over to the executor automatically. The responder does not see skills.
 
 ### Enabling
 
@@ -210,6 +242,43 @@ type AxAgentSkillResult = {
 };
 ```
 
+### Static catalog (no callback)
+
+If the skill set fits in a plain array, skip the callback entirely: pass `skillsCatalog` and Ax backs `discover({ skills })` with a built-in deterministic local search (idf-weighted token overlap over `id` + `name`×2 + `description`×2 + the first 600 chars of `content`; not regex, not embeddings). The executor prompt also gains a static, cache-stable `### Available Skills` index (id + name + description, sorted by id), so the actor searches by known ids instead of guessing.
+
+```typescript
+import type { AxAgentCatalogSkill } from '@ax-llm/ax';
+
+const catalog: AxAgentCatalogSkill[] = [
+  {
+    id: 'release-checklist',
+    name: 'Release checklist',
+    description: 'Steps for shipping a package release safely', // high-signal for matching
+    content: '1. Bump version\n2. Run tests\n3. Tag and publish',
+  },
+];
+
+const myAgent = agent('task:string -> answer:string', {
+  contextFields: [],
+  skillsCatalog: catalog,
+});
+```
+
+```typescript
+type AxAgentCatalogSkill = {
+  id: string;
+  name: string;
+  description?: string;
+  content: string;
+};
+```
+
+Rules:
+
+- If both `skillsCatalog` and `onSkillsSearch` are set, the host callback handles all `discover({ skills })` searches; the catalog still powers the `### Available Skills` index and the advisory `relevanceRanking` hint.
+- Catalog content is NOT preloaded into the prompt (unlike `skills`); entries load only when matched. Use `skills` for guides that must always be in context, `skillsCatalog` for a larger set loaded on demand.
+- The built-in search is lexical. For semantic retrieval over large stores, supply `onSkillsSearch` instead.
+
 ### Actor usage
 
 ```javascript
@@ -270,6 +339,29 @@ await releaseAgent.forward(
 
 You can use `skills` without setting `onSkillsSearch` at all. That is useful for static guides where the actor never needs to fetch more.
 
+## Advisory Relevance Hints (`relevanceRanking`)
+
+`relevanceRanking` is ON by default — leave it unset; set `relevanceRanking: false` to opt out. The default was flipped after its A/B gate passed (substance-judged, 49 runs per variant per model: small-model first-lookup precision 24%→90% and answer accuracy 14%→29%; frontier-model control accuracy 63%→88% with fewer turns). The generated language ports implement the same advisory hint contract through AxIR Core.
+
+When enabled, a deterministic local ranker scores the agent's discoverable capabilities against the task once per `forward(...)` and injects a short advisory `### Likely Relevant` shortlist into the executor turn — modules (needs `functionDiscovery`), catalog skills (needs `skillsCatalog`), and catalog memories (needs `memoriesCatalog`). The hint is non-authoritative: the full lists still apply and the actor may `discover`/`recall` anything else.
+
+```typescript
+const myAgent = agent('task:string -> answer:string', {
+  contextFields: [],
+  functionDiscovery: true,
+  skillsCatalog: catalog,
+  relevanceRanking: true, // or { topK: 3, minScore: 0.08 }
+});
+```
+
+Rules:
+
+- Default is ON across TypeScript and generated language ports; domains still self-gate on their prerequisites (`functionDiscovery` for modules, catalogs for skills/memories), so agents without those see no change. Everything else in this skill (catalog search, the Available Skills index) is independent of the flag.
+- The shortlist rides a dynamic, non-cached prompt field; the cached system prompt stays byte-stable across tasks.
+- On low confidence the ranker emits nothing rather than guessing.
+- Memory hint entries include an ~80-char content snippet; very short memories may be usable from the hint alone without a `recall(...)` (such use is not visible to `onUsedMemories`).
+- Observe outcomes via the `relevance_ranking` context event (see `ax-agent-observability`).
+
 ## Loaded And Used Tracking
 
 `onLoadedMemories` reports what `recall(...)` loaded. `onLoadedSkills` reports what `discover({ skills })` loaded. To track what the actor says it actually relied on, use `onUsedMemories` / `onUsedSkills`.
@@ -318,6 +410,9 @@ onUsedSkills?: (
 
 contextMap?: AxAgentContextMapConfig;
 skills?: readonly AxAgentSkillResult[];
+skillsCatalog?: readonly AxAgentCatalogSkill[];
+memoriesCatalog?: readonly AxAgentMemoryResult[];
+relevanceRanking?: boolean | { topK?: number; minScore?: number };
 ```
 
 ## Examples
@@ -331,10 +426,13 @@ Fetch this for full working code:
 
 - Do not assign the result of `await recall(...)` or `await discover(...)`; both return `void`.
 - Do not call `recall()` from the responder stage.
-- Do not call `discover({ skills })` from the distiller or responder stages.
+- Do not call `discover({ skills })` from the responder stage.
 - Do not loop `recall()` calls or wrap them in `Promise.all(...)`.
 - Do not loop `discover()` calls or wrap them in `Promise.all(...)`.
 - Do not assume child agents inherit `onMemoriesSearch` or `onSkillsSearch`.
 - Do not pass `onMemoriesSearch` results via shared fields as a workaround; use `recall(...)`.
 - Do not assume `inputs.memories` persists across `.forward()` calls.
 - Do not use `onLoadedMemories` / `onLoadedSkills` as proof that the actor relied on an item; use `onUsedMemories` / `onUsedSkills` for actual-use tracking.
+- Do not write an `onSkillsSearch` / `onMemoriesSearch` callback that just scans a static array; pass the array as `skillsCatalog` / `memoriesCatalog` instead.
+- Do not rely on the built-in catalog search for semantic matching over large stores; it is lexical token overlap — supply a host callback for embeddings/vector search.
+- Do not confuse `skills` (always preloaded into the prompt) with `skillsCatalog` (searchable, loaded on demand).

package/skills/ax-agent-observability.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-observability
 description: This skill helps an LLM generate correct AxAgent observability code using @ax-llm/ax. Use when the user asks about actorTurnCallback, onContextEvent, agentStatusCallback, onFunctionCall, reportSuccess, reportFailure, getChatLog(), getUsage(), resetUsage(), debug traces, progress updates, or telemetry for AxAgent runs.
-version: "22.0.8"
+version: "23.0.0"
 ---
 
 # AxAgent Observability Rules (@ax-llm/ax)
@@ -153,6 +153,10 @@ 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
+- `relevance_ranking`: emitted once per ranked domain per forward when `relevanceRanking` is enabled; carries `domain` (`'modules' | 'skills' | 'memories'`), the `shortlist` (`{ id, score }[]`, most relevant first), and `suppressed` (true when the low-confidence guard emitted no hint)
+- `field_auto_promoted`: emitted once per field per run when `autoUpgrade` keeps an oversized undeclared input value runtime-only; carries `fieldName`, `originalChars`, and `promptPreviewChars` (undefined when no inline preview was kept)
+
+To measure whether the advisory hint helps, join per forward: `relevance_ranking.shortlist` ids against what the actor then loaded — for modules the internal `discover` calls (`onFunctionCall` with `kind: 'internal'`, `name: 'discover'`, `args.request`) plus the module part of external `qualifiedName`s; for skills `onLoadedSkills` / `used(id)`; for memories `onLoadedMemories` / `used(id)`.
 
 Rules:
 

package/skills/ax-agent-optimize.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-optimize
 description: This skill helps an LLM generate correct AxAgent tuning and evaluation code using @ax-llm/ax. Use when the user asks about agent.optimize(...), judgeOptions, eval datasets, optimization targets, saved optimizedProgram artifacts, or agent optimization guidance.
-version: "22.0.8"
+version: "23.0.0"
 ---
 
 # AxAgent Optimize Codegen Rules (@ax-llm/ax)
@@ -30,6 +30,7 @@ Your job is to help the model choose a good optimization setup for the user's ac
 - Save artifacts with `axSerializeOptimizedProgram(result.optimizedProgram!)`, then restore with `axDeserializeOptimizedProgram(saved)` and `agent.applyOptimization(...)`.
 - For browser-safe persistence, let the caller store the serialized JSON anywhere they want such as localStorage, IndexedDB, or a backend.
 - If `bootstrap` is enabled, bootstrapped demos are persisted inside `result.optimizedProgram.demos`; raw failed traces are not saved in v1.
+- Auto-promoted context fields (large undeclared inputs kept runtime-only by `autoUpgrade`) appear in captured traces/demos as their truncated preview string, not the full value — same as declared truncate-style `contextFields`. This is expected; do not treat the shortened value as a bug in the saved demos.
 - For first examples, pass a plain task array instead of splitting into `train` and `validation` unless the user already has a holdout set.
 - GEPA-backed `agent.optimize(...)` now optimizes generic components exposed by the selected target programs; `target: 'actor'` only tunes actor components, `target: 'responder'` only tunes responder components, and `target: 'all'` broadens the component set.
 - `result.optimizedProgram.componentMap` is the canonical saved artifact for agent GEPA runs. It may include actor instructions, descriptions, tool descriptions/names, templates, or runtime primitives depending on what the selected target exposes.

package/skills/ax-agent-rlm.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-rlm
 description: This skill helps an LLM generate correct AxAgent RLM/runtime code using @ax-llm/ax. Use when the user asks about RLM code execution, AxJSRuntime, contextFields, contextPolicy, liveRuntimeState, promptLevel, stage prompt controls, executorModelPolicy, maxRuntimeChars, agent.test(...), llmQuery(...), recursionOptions, or long-running agent runtime behavior.
-version: "22.0.8"
+version: "23.0.0"
 ---
 
 # AxAgent RLM Runtime Rules (@ax-llm/ax)
@@ -12,6 +12,7 @@ Use this skill for code-runtime agents and `llmQuery(...)` semantic-helper behav
 
 - Use `agent(...)`, not `new AxAgent(...)`.
 - In stdout-mode RLM, use one observable `console.log(...)` step per non-final actor turn.
+- Rely on `autoUpgrade` (ON by default) for oversized inputs you did not declare in `contextFields`: any input value over ~8k serialized chars is kept runtime-only automatically, with a 1,200-char prompt preview plus a `contextMetadata` line, while the full value stays live in the runtime as `inputs.<field>`. Declare a field in `contextFields` only when you want a specific inline policy (`promptMaxChars` / `keepInPromptChars`) or need a large required non-string field kept out of the prompt (those are left inline by auto-upgrade).
 - 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.
 - Use `contextMap` for recurring long-context corpora when the distiller should start future runs with a small persisted orientation cache.
@@ -31,9 +32,17 @@ 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 runtime-language code in a multi-turn loop, then calls the runtime-exposed `final(request, evidence)` primitive. The request becomes the executor's `inputs.executorRequest`; it must be self-contained and restate the concrete action, target, and constraints, not vague wording like "do it". 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.**
-- **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 distilled evidence, and reports actual tool results or failures.
+- **executor** runs unless the distiller skipped it (below). It receives non-context inputs plus `inputs.executorRequest`, a compact `distilledContextSummary` prompt field, and the real evidence live as `inputs.distilledContext` from the distiller's `final(request, evidence)` payload. Declared or auto-promoted context fields stay runtime-readable as `inputs.<field>` when `contextMetadata` lists them, but their raw contents are not pasted into the executor prompt. The executor owns tool use, decides whether to call its available functions or finish directly from 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.
 
+### Direct respond (executor skip)
+
+With `directResponse: 'auto'` (the default), the distiller can end the run with the `respond(task, evidence)` primitive when the task needs no user-provided functions — the executor stage is skipped entirely (zero executor model calls) and the responder synthesizes straight from the distiller's evidence. Unlike `final`, whose evidence stays live in the shared session by reference, `respond`'s evidence crosses into the responder prompt (budgeted by `maxEvidenceChars`), and the distiller's runtime variables are exported as the cross-run state exactly as the executor's would have been.
+
+- **Static agents** (no `functions`, no child agents) run respond-only: `final` is not offered to the distiller and every run is distiller → responder.
+- **Agents with functions** get `respond` alongside `final` under a conservative covenant: only for tasks answered purely by reading/synthesizing provided context, never when a listed function/module domain covers the need, never for current/live/fresh-state asks (context may be stale — tools are the source of truth for "now"), never for side effects. Landing-gate eval (both pinned models, 3 repeats): 0 false skips on tool-required tasks including a stale-context trap, 100% skip recall on pure context Q&A.
+- `directResponse: 'off'` removes the primitive from the prompt and the runtime, and the pipeline rejects a respond payload outright.
+
 Treat both actor stages as long-running code runtime sessions that the actor steers over multiple turns, not as fresh script generators on every turn. `AxJSRuntime` is the default; custom runtimes set `language` so the actor code field becomes `<language>Code` such as `pythonCode` while JavaScript keeps the legacy `javascriptCode`.
 
 - Successful code leaves variables, functions, imports, and computed values available in the runtime session.
@@ -142,6 +151,7 @@ Use these top-level controls consistently:
 - `contextPolicy`: replay/checkpointing/compression policy.
 - `contextMap`: optional persistent orientation cache injected into the distiller and updated once after each successful run. `AxAgentContextMap` evolves indefinitely by default; use `{ infiniteEvolve: false, evolveSteps: N }` on the map object for finite warmup followed by reuse.
 - `contextOptions`: distiller-stage forward options.
+- `autoUpgrade`: smart defaults, ON by default. Auto-enables `functionDiscovery` for large tool catalogs and keeps oversized undeclared input values runtime-only with a truncated prompt preview. Set `false` to opt out, or tune per side: `{ functionDiscovery?: boolean | { aboveFunctionDocChars }, contextFields?: boolean | { promoteAboveChars, previewChars } }`. Explicit `functionDiscovery` and declared `contextFields` always win.
 - `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.
@@ -250,7 +260,7 @@ Prompt/cache shape:
 
 - Actor turns are compact observable turns, not replayed chat transcripts.
 - Stable system prompt: role/stage rules, primitive descriptions, static module list, always-included callable signatures, output contract, and field definitions.
-- Cached working inputs: task inputs, inline context, `contextMetadata`, `contextMap`, `memories`, `executorRequest`, `distilledContext`, `discoveredToolDocs`, `loadedSkills`, and `summarizedActorLog`.
+- Cached working inputs: task inputs, inline context, `contextMetadata`, `contextMap`, `memories`, `executorRequest`, `distilledContextSummary`, `discoveredToolDocs`, `loadedSkills`, and `summarizedActorLog`.
 - Dynamic turn tail: `guidanceLog`, `actionLog`, `liveRuntimeState`, and `contextPressure`.
 - Prefer one compact inspection per non-final turn. Never combine inspection output with `final(...)` or `askClarification(...)`.
 
@@ -476,6 +486,7 @@ Flagship real-world long-agents (also ported to Python, Go, Rust, Java, and C++
 - [Incident Log Forensics](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/typescript/long-agents/incident-log-forensics.ts) - large-context log forensics over `contextFields` (Gemini)
 - [Codebase Peek Map](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/typescript/long-agents/codebase-peek-map.ts) - Peek-paper context-map orientation over a large repo snapshot
 - [Data Analyst with Tools](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/typescript/long-agents/data-analyst-with-tools.ts) - large data dictionary in `contextFields` + typed warehouse tools the model queries instead of inlining
+- [Smart Defaults Agent](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/typescript/long-agents/smart-defaults-agent.ts) - oversized undeclared context auto-promoted runtime-only, with relevance hints and runtime tools
 - [Self-Improving Lab](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/typescript/long-agents/self-improving-lab.ts) - many-tool agent that runs experiments, grades them with an independent verifier, and distills verified rules into memory
 
 ## Do Not Generate

package/skills/ax-agent.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent
 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: "22.0.8"
+version: "23.0.0"
 ---
 
 # AxAgent Codegen Rules (@ax-llm/ax)
@@ -45,6 +45,8 @@ Map user intent to agent shape before writing code:
 - 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 discovery is enabled, call `discover(...)` before using callables whose docs are not already in the prompt.
+- `autoUpgrade` is ON by default: large tool catalogs auto-enable discovery, and oversized undeclared input values are auto-kept runtime-only with a truncated prompt preview. Explicit `functionDiscovery` and declared `contextFields` always win; set `autoUpgrade: false` to opt out.
+- `directResponse` is ON by default (`'auto'`): when a task needs no user-provided functions, the distiller ends the run with `respond(task, evidence)` and the executor stage is skipped (zero executor model calls). Function-less agents run respond-only every time; agents with functions offer `respond` under a conservative covenant (no live/fresh-state asks, no side effects, nothing a listed function/module domain covers). Set `directResponse: 'off'` to always run the executor.
 - If a host-side `AxAgentFunction` needs to end the current actor turn, use `extra.protocol.final(...)` or `extra.protocol.askClarification(...)`.
 - 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(...)`.
@@ -260,6 +262,7 @@ 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.
+- `relevanceRanking` (default ON — set `false` to opt out): a deterministic local ranker that injects an advisory `### Likely Relevant` shortlist into the executor turn (dynamic, non-cached field — the cached prompt stays byte-stable). Enabled by default after its A/B gate passed on both small and frontier models and implemented in the generated language ports through AxIR Core. Details in `ax-agent-memory-skills`; outcomes observable via the `relevance_ranking` context event (`ax-agent-observability`).
 - 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, child agents, and `toFunction()` providers directly.
@@ -525,6 +528,7 @@ agent(signature, {
   contextFields,
   functions,
   functionDiscovery,
+  autoUpgrade,
   ...agentOptions,
 });
 ```
@@ -552,6 +556,26 @@ Each `contextFields` entry is either a plain field name string or an object cont
 
 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.
 
+### Auto-upgrade defaults
+
+`autoUpgrade` is ON by default: the agent applies both knobs above on the user's behalf based on character counts, so forgetting them no longer floods prompts.
+
+- Function discovery: when `functionDiscovery` is left unset and the estimated inline docs of discoverable functions exceed ~10k chars, discovery is enabled automatically. An explicit `functionDiscovery: true | false` always wins.
+- Context fields: per run, an undeclared input value whose serialized size exceeds 8k chars is kept runtime-only like a declared context field — the prompt gets a 1,200-char truncated preview plus a `contextMetadata` entry, while the full value stays addressable as `inputs.<field>` in the code runtime (the responder stage gets the same preview). Fields declared in `contextFields` keep their declared config.
+
+```typescript
+autoUpgrade?: boolean | {
+  functionDiscovery?: boolean | { aboveFunctionDocChars?: number };  // default 10_000
+  contextFields?: boolean | { promoteAboveChars?: number; previewChars?: number };  // 8_000 / 1_200
+}
+```
+
+Rules:
+
+- Set `autoUpgrade: false` (or disable one side) to restore fully manual behavior.
+- Values in required non-string fields (arrays, objects, numbers, media) are never auto-promoted — declare those in `contextFields` explicitly when they can be large.
+- Each promotion emits a `field_auto_promoted` context event (`onContextEvent`) with the field name, original size, and preview size; use it to observe what was kept out of the prompt.
+
 ## Public Surface
 
 Use these method groups as the compact AxAgent surface map:
@@ -590,6 +614,7 @@ Fetch these for full working code:
 - [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
+- [Smart Defaults Agent](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/typescript/long-agents/smart-defaults-agent.ts) - auto-upgrade context promotion, relevance hints, and runtime tools
 
 RLM examples are listed in `ax-agent-rlm`. Memory/skills examples are listed in `ax-agent-memory-skills`.
 

package/skills/ax-ai.md

@@ -1,7 +1,7 @@
 ---
 name: ax-ai
 description: This skill helps an LLM generate correct AI provider setup and configuration code using @ax-llm/ax. Use when the user asks about ai(), providers, models, presets, embeddings, batch audio with ai.transcribe() or ai.speak(), extended thinking, context caching, or mentions OpenAI/Anthropic/Google/Azure/DeepSeek/Mistral/Cohere/Reka/Grok with @ax-llm/ax.
-version: "22.0.8"
+version: "23.0.0"
 ---
 
 # AI Provider Codegen Rules (@ax-llm/ax)

package/skills/ax-audio.md

@@ -1,7 +1,7 @@
 ---
 name: ax-audio
 description: This skill helps an LLM generate correct audio code with @ax-llm/ax. Use when the user asks about ai.transcribe(), ai.speak(), signature audio inputs or outputs, agent audio behavior, .chat() conversational audio, OpenAI audio or realtime models, Gemini Live native audio, Grok Voice Agent models, voices, formats, transcripts, or how audio fits with structured outputs.
-version: "22.0.8"
+version: "23.0.0"
 ---
 
 # Audio I/O Codegen Rules (@ax-llm/ax)

package/skills/ax-flow.md

@@ -1,7 +1,7 @@
 ---
 name: ax-flow
 description: This skill helps an LLM generate correct AxFlow workflow code using @ax-llm/ax. Use when the user asks about flow(), AxFlow, workflow orchestration, parallel execution, DAG workflows, conditional routing, map/reduce patterns, or multi-node AI pipelines.
-version: "22.0.8"
+version: "23.0.0"
 ---
 
 # AxFlow Codegen Rules (@ax-llm/ax)

package/skills/ax-gen.md

@@ -1,7 +1,7 @@
 ---
 name: ax-gen
 description: This skill helps an LLM generate correct AxGen code using @ax-llm/ax. Use when the user asks about ax(), AxGen, generators, forward(), streamingForward(), validation, assertions, streaming assertions, field processors, step hooks, self-tuning, or structured outputs.
-version: "22.0.8"
+version: "23.0.0"
 ---
 
 # AxGen Codegen Rules (@ax-llm/ax)

package/skills/ax-gepa.md

@@ -1,7 +1,7 @@
 ---
 name: ax-gepa
 description: This skill helps an LLM generate correct AxGEPA optimization code using @ax-llm/ax. Use when the user asks about AxGEPA, GEPA, Pareto optimization, multi-objective prompt tuning, reflective prompt evolution, validationExamples, maxMetricCalls, or optimizing a generator, flow, or agent tree.
-version: "22.0.8"
+version: "23.0.0"
 ---
 
 # GEPA Optimization Codegen Rules (@ax-llm/ax)

package/skills/ax-llm.md

@@ -1,7 +1,7 @@
 ---
 name: ax-llm
 description: This skill helps with using the @ax-llm/ax TypeScript library for building LLM applications. Use when the user asks about ax(), ai(), f(), s(), agent(), flow(), AxGen, AxAgent, AxFlow, signatures, streaming, or mentions @ax-llm/ax.
-version: "22.0.8"
+version: "23.0.0"
 ---
 
 # Ax Library (@ax-llm/ax) Quick Reference

package/skills/ax-playbook.md

@@ -1,7 +1,7 @@
 ---
 name: ax-playbook
 description: This skill helps an LLM generate correct playbook code using @ax-llm/ax. Use when the user asks about playbook(), AxPlaybook, context playbooks, evolving context, ACE / Agentic Context Engineering, agent.playbook(), or growing/applying task knowledge offline and online with evolve() and update().
-version: "22.0.8"
+version: "23.0.0"
 ---
 
 # Playbook Codegen Rules (@ax-llm/ax)

package/skills/ax-refine.md

@@ -1,7 +1,7 @@
 ---
 name: ax-refine
 description: Use this skill when writing or reviewing Ax bestOfN/refine code, reward functions, thresholds, native sample selection, serial attempts, generated advice, and attempt diagnostics.
-version: "22.0.8"
+version: "23.0.0"
 ---
 
 # Ax Refine And BestOfN

package/skills/ax-signature.md

@@ -1,7 +1,7 @@
 ---
 name: ax-signature
 description: This skill helps an LLM generate correct DSPy signature code using @ax-llm/ax. Use when the user asks about signatures, s(), f(), field types, string syntax, fluent builder API, validation constraints, or type-safe inputs/outputs.
-version: "22.0.8"
+version: "23.0.0"
 ---
 
 # Ax Signature Reference