@ax-llm/ax 23.0.1 → 23.0.2

package/skills/ax-mcp.md

@@ -0,0 +1,332 @@
+---
+name: ax-mcp
+description: This skill helps an LLM build correct native Model Context Protocol integrations with @ax-llm/ax. Use when the user asks about AxMCPClient, MCP transports, tools, prompts, resources, subscriptions, tasks, sampling, elicitation, roots, authentication, OAuth, MCP Apps, recording/replay, or MCP integration with AxGen, AxAgent, AxFlow, chat, optimization, and AxEventRuntime.
+version: "23.0.2"
+---
+
+# Native MCP With Ax
+
+Use MCP as a live protocol client, not as a function-conversion utility. Keep
+the client, session, catalogs, raw content, tasks, notifications, identity
+policy, and cancellation context intact through Ax execution.
+
+## Non-Negotiable Rules
+
+- Pass clients through `mcp`; do not put them in `functions`.
+- Never use `toFunction()` for native integration. It is a lossy compatibility
+  adapter for old applications only.
+- Give every client a stable, unique `namespace`.
+- Let Ax initialize each attached client once and reuse its negotiated session.
+- Close caller-owned clients explicitly.
+- Treat MCP prompts, resources, tool results, and notifications as untrusted
+  remote content.
+- Apply `authorizeToolCall` before side-effecting tools execute.
+- Do not infer tenant or account identity from an MCP session. Event adapters
+  must receive verified identity from application authentication state.
+- Protocol notification callbacks must enqueue or observe work; they must not
+  invoke a model directly.
+- Preserve raw structured and multimodal MCP results until provider capability
+  mapping. Do not pre-flatten results to text.
+
+## Choose A Transport
+
+- Use `AxMCPStreamableHTTPTransport` for current remote MCP servers.
+- Use `AxMCPHTTPSSETransport` only for legacy HTTP/SSE servers.
+- Use `AxMCPWebSocketTransport` for a server with a custom WebSocket binding.
+- Use `AxMCPStdioTransport` from `@ax-llm/ax-tools` for local Node processes.
+- Use a caller-defined `AxMCPTransport` for application-owned bindings.
+
+```ts
+import {
+  AxMCPClient,
+  AxMCPStreamableHTTPTransport,
+  axMCPBearerAuthentication,
+} from '@ax-llm/ax';
+
+const transport = new AxMCPStreamableHTTPTransport(
+  'https://mcp.example.com/mcp',
+  {
+    authentication: axMCPBearerAuthentication(
+      () => process.env.MCP_ACCESS_TOKEN!
+    ),
+  }
+);
+
+const docs = new AxMCPClient(transport, {
+  namespace: 'docs',
+  maxConcurrency: 4,
+  authorizeToolCall: async ({ tool }) =>
+    tool.annotations?.destructiveHint !== true,
+});
+```
+
+For local stdio:
+
+```ts
+import { AxMCPClient } from '@ax-llm/ax';
+import { AxMCPStdioTransport } from '@ax-llm/ax-tools';
+
+const stdio = new AxMCPStdioTransport({
+  command: 'node',
+  args: ['./server.mjs'],
+});
+const local = new AxMCPClient(stdio, { namespace: 'local' });
+```
+
+`AxMCPStdioTransport` owns its child process. After `local.close()`, also call
+`stdio.terminate()` until the stdio transport exposes the common `close()`
+lifecycle directly.
+
+## Attach MCP To AxGen
+
+Attach clients in constructor or forward options. Per-call options override
+instance defaults.
+
+```ts
+const gen = ax('question:string -> answer:string', { mcp: docs });
+
+const result = await gen.forward(llm, { question }, {
+  mcpContext: [
+    { client: 'docs', resource: { uri: 'docs://guide' } },
+  ],
+});
+```
+
+`mcpContext` resolves selected prompts or resources before the first model
+call and adds attributed, untrusted context. Native tool calls retain client
+identity and raw MCP results in memory. `streamingForward()` keeps Ax output
+streaming separate from MCP progress and task events.
+
+## Attach MCP To AxAgent
+
+```ts
+const assistant = agent('query:string -> answer:string', {
+  mcp: [docs, search],
+  mcpInheritance: 'all',
+  functionDiscovery: true,
+  contextFields: [],
+});
+```
+
+Agents expose native modules under `mcp.<namespace>`:
+
+```text
+mcp.docs.tools.<tool>
+mcp.docs.prompts.list()
+mcp.docs.prompts.get(name, args)
+mcp.docs.resources.list()
+mcp.docs.resources.templates()
+mcp.docs.resources.read(uri)
+mcp.docs.resources.subscribe(uri)
+mcp.docs.resources.unsubscribe(uri)
+mcp.docs.tasks.list()
+mcp.docs.tasks.get(taskId)
+mcp.docs.tasks.result(taskId)
+mcp.docs.tasks.cancel(taskId)
+mcp.docs.complete(...)
+```
+
+Use `mcpInheritance: 'all'`, `'none'`, or a namespace allowlist. The resulting
+live execution context propagates through Agent stages, `llmQuery`, RLM, and
+child programs. Large catalogs participate in Agent discovery; do not copy
+their tools into an inline `functions` array.
+
+## AxFlow And High-Level Chat
+
+Pass `mcp` in Flow defaults or forward options. Nested nodes inherit the same
+execution context unless `mcpInheritance` restricts it. Parallel nodes share
+the client while respecting its concurrency limit and abort signal.
+
+Use `axMCPChat(ai, request, { mcp })` for a high-level non-streaming native MCP
+tool loop. Do not build a second ad-hoc tool dispatcher around `ai.chat()`.
+
+## Catalogs And Raw Operations
+
+An endpoint is only the server address. The server owns tool names, prompt
+names, resource names, resource URIs, and URI templates. Discover one cloned
+snapshot before asking users to configure identifiers:
+
+```ts
+const catalog = await docs.inspectCatalog();
+
+console.log(catalog.tools);
+console.log(catalog.prompts);
+console.log(catalog.resources);
+console.log(catalog.resourceTemplates);
+
+const prompt = await docs.getPrompt('review', { topic: 'MCP' });
+const resource = await docs.readResource('docs://guide');
+const completion = await docs.complete(reference, argument);
+```
+
+`inspectCatalog({ refresh: true })` forces fresh bounded pagination. Snapshot
+mutation cannot change the live client. List-change notifications refresh the
+catalog revision, and native Ax model steps rebuild tool definitions when that
+revision changes. Concrete resources can be selected immediately. URI
+templates are discoverable but never expanded automatically; applications
+construct an authorized concrete URI and may use MCP completion to suggest
+argument values.
+
+## Tasks, Progress, And Cancellation
+
+Use task-aware calls when the server advertises tasks:
+
+```ts
+const created = await docs.callToolTask('reindex', { scope: 'all' });
+const task = await docs.getTask(created.task.taskId);
+await docs.cancelTask(task.taskId);
+```
+
+Use `subscribeTaskStatus` or `subscribeEvents` for observation. Keep polling
+available because task notifications are optional. Pass Ax abort signals
+through program execution; never blindly replay a tool call after an uncertain
+post-side-effect failure.
+
+## Subscriptions And Event-Driven Agents
+
+Use `AxMCPEventSource` with `AxEventRuntime`. A subscription callback only
+publishes an event into the inbox. Explicit routes decide whether to observe,
+invalidate, wake, or resume.
+
+```ts
+const source = new AxMCPEventSource({
+  client: docs,
+  resourceSubscriptions: {
+    select: (resource) =>
+      resource.mimeType === 'text/markdown' &&
+      resource.name === 'Engineering guide',
+  },
+  identity: { tenantId: 'tenant-1' },
+  trust: 'authenticated',
+});
+
+const runtime = eventRuntime({
+  allowVolatile: true,
+  sources: [source],
+  routes: [
+    ...axMCPEventRoutes({ client: docs }),
+    eventRoute('guide-updated')
+      .types('mcp.resource.updated')
+      .authenticated()
+      .wake(
+        eventTarget('reviewer')
+          .program(reviewer)
+          .ai(llm)
+          .input((input) =>
+            input.field('uri', eventPath.data('uri'))
+          )
+          .build()
+      )
+      .build(),
+  ],
+});
+```
+
+Safe defaults are:
+
+- omitted resource policy -> subscribe to no resources
+- `'all'` -> explicitly subscribe to all discovered concrete resources
+- URI array -> explicitly subscribe to application-constructed concrete URIs
+- selector -> choose concrete resources by name, URI, description, MIME type,
+  annotations, or the surrounding catalog
+- catalog changes -> `invalidate`
+- progress and logging -> `observe`
+- resource updates -> no implicit wake
+- `input_required` and terminal task states -> resume the owning continuation
+
+The signature-aware input plan is the data boundary. Raw event data remains in
+`eventContext`; only fields selected with segment-safe `eventPath` descriptors
+become program inputs. Use multiple matching routes to fan one notification out
+to multiple Agents with independent authorization and run records.
+
+Managed sources refresh and diff their selection after
+`notifications/resources/list_changed`. They keep the prior selection if a
+selector throws, retain successful wire transitions after a partial failure,
+and retry incomplete work on the next change or reconnect. The client tracks a
+separate logical owner for manual subscriptions, every source, and restored
+intent: only the first owner sends `resources/subscribe`, and only the last
+release sends `resources/unsubscribe`. Closing a source cannot break another
+owner. Closing the client terminates all ownership and transport state.
+
+For the detailed lifecycle and troubleshooting guide, read
+`docs/MCP_SUBSCRIPTIONS.md` and use the checked-in six-language MCP examples.
+
+## Server-Initiated Requests
+
+Configure handlers on `AxMCPClient` when advertising the corresponding client
+capability:
+
+- `sampling` for `sampling/createMessage`
+- `elicitation` for form or URL elicitation
+- `roots` for `roots/list`
+- `onProgress`, `onLoggingMessage`, and `onTaskStatus` for observation
+
+Do not advertise a client capability without a working host handler and policy.
+
+## Authentication And OAuth
+
+For simple authentication, compose `axMCPBearerAuthentication`,
+`axMCPBasicAuthentication`, `axMCPAPIKeyAuthentication`,
+`axMCPHMACAuthentication`, or a caller-defined strategy in the HTTP transport.
+
+Use the transport `oauth` option for protected-resource discovery, PKCE,
+client metadata or dynamic registration, refresh, challenge-driven scope
+step-up, DPoP, PAR/JAR/RAR, mTLS, revocation, introspection, client credentials,
+or enterprise-managed authorization. Supply persistent token and registration
+stores in distributed deployments. Never serialize tokens into Ax program or
+event state.
+
+Keep SSRF protection enabled for remote discovery and redirect handling. Relax
+loopback or HTTP restrictions only for controlled local development.
+
+For checked-in Streamable HTTP examples, set `AX_MCP_ENDPOINT`. A localhost
+TypeScript demo must opt in explicitly with
+`ssrfProtection: { allowHTTP: true, allowLoopback: true }`; never copy that
+configuration to a remote endpoint. Generated examples use their equivalent
+`requireHttps` / `allowLocalhost` / `allowPrivateNetworks` fields only for
+`127.0.0.1`.
+
+For a real local check, run `src/examples/mcp-event-demo-server.ts`, set
+`AX_MCP_ENDPOINT=http://127.0.0.1:3001/mcp`, and trigger
+`/control/resource` or `/control/task/complete`. The mandatory credential-free
+matrix is `npm run test:mcp-events:generated`; provider-backed examples are
+advisory and require their documented API key.
+
+## MCP Apps And Extensions
+
+Negotiate official extensions through client capabilities. Use
+`AxMCPAppBridge` for MCP App resources and host messages; enforce CSP,
+permissions, visibility, allowed tools, and untrusted model-context policy.
+Do not render arbitrary HTML returned from a normal tool result as an MCP App.
+
+## Recording, Replay, And Evaluation
+
+Wrap a real transport with `AxMCPRecordingTransport` to capture deterministic
+protocol interactions. Use `AxMCPReplayTransport` for tests, optimization, and
+evaluation. Live MCP evaluation is rejected by default because repeated model
+runs could repeat external side effects; opt in only deliberately.
+
+## Testing Checklist
+
+- Use a local deterministic protocol server or replay transport.
+- Assert namespace and tool collisions fail before model execution.
+- Test raw text, image, audio, resource-link, embedded-resource, metadata,
+  task, and error results.
+- Test catalog changes during a multi-step run.
+- Test authorization denial before transport execution.
+- Test subscription reconnect and logical resubscription.
+- Test anonymous events cannot match authenticated routes.
+- Test terminal task events resume only the owning identity and correlation.
+- Test cancellation and uncertain outcomes without duplicate side effects.
+- Close clients, listening handles, runtimes, and local servers in `finally`.
+
+Generated transports supervise real long-lived GET/SSE connections and resume
+with `Last-Event-ID` when available. Generated event runtimes remain
+host-driven: schedule delayed work with `nextDueAt()` and `runDue()`. Rust hosts
+also call `AxMCPEventSource.poll()` to drain protocol callbacks on the host
+thread. Close the source/runtime before the caller-owned client so unsubscribe
+and cancellation messages can still be sent.
+
+For generic inbox, continuation, store, and sink behavior, use the
+`ax-event-runtime` skill. For program-specific behavior, combine this skill with
+`ax-gen`, `ax-agent`, or `ax-flow`.

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: "23.0.1"
+version: "23.0.2"
 ---
 
 # Playbook Codegen Rules (@ax-llm/ax)
@@ -29,7 +29,10 @@ Use this skill to generate context-playbook code. A playbook grows an evolving b
 - `applyTo()` injects a `## Context Playbook` block into the program description; calling it repeatedly recomposes from the original base (no stacking).
 - Keep the offline `metric` deterministic and cheap, like a GEPA metric.
 - A playbook is plain JSON. Persist `pb.toJSON()` and `load(...)` it into a fresh program for production.
-- This is a TypeScript feature; do not suggest it for the generated (Python/Go/Rust/Java/C++) packages yet.
+- The playbook engine, construction-time agent attachment, failure harvesting,
+  and verified agent evolution are available in TypeScript and the generated
+  Python, Java, C++, Go, and Rust packages. Use each package's native casing and
+  callback types.
 
 ## Offline Pattern (evolve)
 
@@ -86,6 +89,23 @@ const result = await apb.evolve(
 
 The agent-level `evolve(dataset, options)` is distinct from the program-level `pb.evolve(examples, metric)` above: it takes an `AxAgentEvalDataset` plus options, runs the whole pipeline, and returns baseline/final held-in & held-out with per-bullet outcomes (no `{ bestScore }`). For full-pipeline tuning of agent instructions and demos (not the playbook) use `agent.optimize(...)` (GEPA).
 
+Generated packages expose that same agent-bound loop with language-shaped APIs:
+
+| Language | Agent-bound evolve call |
+|---|---|
+| Python | `agent.playbook().evolve(dataset, options)` |
+| Java | `agent.playbook(null).evolve(dataset, options)` |
+| C++ | `agent.get_playbook()->evolve(dataset, options)` |
+| Go | `agent.GetPlaybook().EvolveAgent(ctx, dataset, options)` |
+| Rust | `playbook.evolve_agent(&mut agent, client, dataset, options)` |
+
+All five generated packages thread structured `failureSignals` through agent
+evaluation predictions. The default verify gate accepts a proposed bullet only
+when held-in score improves and held-out score stays within `epsilon`; rejection
+restores the exact prior snapshot. Scoring is host-shaped: TypeScript uses its
+metric, Python/Java/Go can accept a metric callback, and all generated ports can
+use task `score`/`scores` values plus the agent evaluation result.
+
 ## Playbook vs optimize()
 
 - `playbook(...)` — accumulate reusable, evolving task knowledge; the only path that also learns online via `update(...)`.

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: "23.0.1"
+version: "23.0.2"
 ---
 
 # 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: "23.0.1"
+version: "23.0.2"
 ---
 
 # Ax Signature Reference
@@ -41,6 +41,113 @@ Date, datetime, and range fields are AI-friendly but strict. They accept ISO-sty
 'problem:string -> reasoning!:string, solution:string'  // internal with !
 ```
 
+## Extended String Grammar (Modifier Bags + Nested Objects)
+
+The string form is constraint-complete: everything the fluent API expresses
+(except Standard Schema fields) can be written in the string. A type takes an
+optional comma-separated, order-free **modifier bag** in parentheses, and
+objects declare structured fields inline.
+
+```typescript
+`userAge:number(min 0, max 120), contactEmail:string(format email, cache), codeSnippet:code(python)
+ -> userName:string(pattern "^[a-z_]+$" "lowercase name"), tagList:string(item "a short tag")[] "all tags",
+    profileList:object{ fullName:string, userAge?:number(min 0) }[] "matched profiles"`
+```
+
+| Modifier | Applies to | Effect |
+|----------|-----------|--------|
+| `min N` / `max N` | `string`, `number` | String length bounds / numeric value bounds |
+| `format email\|uri\|date\|date-time` | `string` | Format validation |
+| `pattern "regex" ["desc"]` | `string` | Regex validation with optional description |
+| `cache` | top-level input | Prefix-cache breakpoint |
+| `item "desc"` | arrays | Per-item description: `tags:string(item "a tag")[]` |
+| `<language>` | `code` | Language of the snippet: `snippet:code(python)` |
+
+- `object{ field:type, opt?:type }` nests recursively; append `[]` for an array of objects.
+- Optional goes on the **name** (`userAge?:number`), never after the type.
+- The string API is **strict**: a modifier that does not apply to its type (e.g. `min` on a boolean) is a parse error, where the fluent API silently ignores it.
+- Inside `object{ ... }`, the `!` internal marker, media types, `cache`, and `item` are rejected (they only apply at the top level).
+- In quoted values, backslashes are doubled — a regex `\d` is written `pattern "\\d+"`.
+- `AxSignature.toString()` renders every construct back to this grammar losslessly, so a signature round-trips — this is what lets a whole flow serialize its node contracts into mermaid `%%ax` directives (see the ax-flow skill).
+
+## Signature Gallery
+
+Real-world contracts, one line each — every entry below parses with `s()` as written (`#` lines are captions, not part of the signature):
+
+```text
+# Support triage: several class outputs plus a capped reply draft
+ticketText:string -> priorityClass:class "p0, p1, p2", sentimentClass:class "angry, neutral, happy", replyDraft:string(max 500)
+
+# Invoice extraction: regex-validated id, bounded totals, structured line items
+invoiceText:string -> invoiceNumber:string(pattern "^INV-\\d+$" "INV- then digits"), totalAmount:number(min 0), lineItems:object{ description:string, quantity:number(min 1), unitPrice:number }[]
+
+# Contact enrichment: optional format-validated outputs
+bioText:string -> contactEmail?:string(format email), websiteUrl?:string(format uri), birthDate?:string(format date)
+
+# RAG: cached corpus input plus per-item described citations
+corpusText:string(cache), userQuestion:string -> answerText:string, citedChunks:string(item "verbatim quote")[]
+
+# Code generation: language-tagged code outputs
+taskBrief:string -> pythonScript:code(python), testCases:code(python), riskNotes?:string
+
+# Chain of thought: internal reasoning stripped from the result
+problemText:string -> reasoning!:string, solutionText:string
+
+# Resume parsing: nested objects inside nested arrays
+resumeText:string -> candidateProfile:object{ fullName:string, yearsExperience:number(min 0), skillList:string[], education:object{ schoolName:string, degreeName?:string }[] }
+
+# Lead scoring: signature-level description, bounded score, class next step
+"Score sales leads" leadNotes:string -> fitScore:number(min 0, max 100) "0-100 fit", nextStep:class "call, email, drop"
+
+# Multimodal: top-level image input with an optional question
+productPhoto:image, question?:string -> productDescription:string, detectedObjects:string[]
+
+# Meeting audio: audio input, capped summary, per-item action list
+meetingAudio:audio -> meetingSummary:string(max 1000), actionItems:string(item "one action item")[]
+
+# Moderation: class verdict plus structured flagged spans
+postText:string -> moderationVerdict:class "allow, review, block", flaggedSpans:object{ spanText:string, reasonNote:string }[]
+
+# Translation: optional locale input
+sourceText:string, targetLocale?:string -> translatedText:string, glossaryHits:string[]
+
+# Text-to-SQL: cached schema plus SQL-tagged output
+schemaText:string(cache), questionText:string -> sqlQuery:code(sql), queryNotes?:string(max 200)
+
+# Calendar extraction: datetime fields and an optional end
+emailText:string -> eventTitle:string, startsAt:datetime, endsAt?:datetime, attendeeNames:string[]
+
+# Booking window: date range, bounded party size, and flexibility flag
+requestText:string -> stayWindow:dateRange, partySize:number(min 1, max 12), flexibleDates:boolean
+
+# Contract dates: date fields plus bounded notice period
+contractText:string -> effectiveDate:date, expiryDate?:date, autoRenews:boolean, noticeDays?:number(min 0)
+
+# Link audit: URL arrays and an optional primary URL
+pageText:string -> referencedUrls:url[], primaryUrl?:url
+
+# Config generation: JSON output plus per-item warnings
+requirementsText:string -> serviceConfig:json, setupWarnings:string(item "one warning")[]
+
+# Claims gate: cached policy, bounded confidence, and optional citation
+claimText:string, policyText:string(cache) -> isCovered:boolean, confidenceScore:number(min 0, max 1), citedClause?:string
+
+# Earnings extraction: structured period data plus a class outlook
+filingText:string(cache) -> revenueByPeriod:object{ periodLabel:string, amountUsd:number }[], guidanceTone:class "raise, hold, cut"
+
+# Pull request review: diff code, cached guide, structured comments, and verdict
+diffText:code(diff), styleGuide?:string(cache) -> reviewComments:object{ filePath:string, lineNumber:number(min 1), commentText:string(max 300) }[], overallVerdict:class "approve, revise"
+
+# Incident triage: severity class, optional service, and per-item runbook steps
+alertLog:string -> incidentSeverity:class "sev1, sev2, sev3", suspectedService?:string, runbookSteps:string(item "one step")[]
+
+# Product listing: image and file inputs with constrained listing outputs
+productPhoto:image, priceSheet?:file -> listingTitle:string(max 80), bulletPoints:string(item "one selling point")[], priceUsd?:number(min 0)
+
+# Study cards: nested object array with an optional difficulty tag
+chapterText:string -> flashCards:object{ questionText:string, answerText:string, difficultyTag?:string }[]
+```
+
 ## Four Ways to Create Signatures
 
 ### 1. String-Based (Recommended for simple cases)
@@ -280,12 +387,20 @@ Bad: `text`, `data`, `input`, `output`, `a`, `x`, `val` (too generic), `1field`
 // Data Extraction
 'invoiceText:string -> invoiceNumber:string, totalAmount:number, lineItems:json[]'
 
+// Constrained string form (no fluent builder needed)
+'reviewText:string(max 2000) -> rating:number(min 1, max 5), themes:string(item "a theme")[]'
+
+// Nested object output in the string form
+'profileText:string -> profile:object{ fullName:string, age?:number(min 0) }'
+
 // With description
 '"Answer TypeScript questions" question:string -> answer:string, confidence:number'
 ```
 
 ## Critical Rules
 
+- The string form is constraint-complete: reach for modifier bags (`string(max 500)`, `number(min 0, max 10)`, `string(format email)`) and inline `object{ ... }` before switching to fluent/zod just for constraints. Reserve fluent/Standard Schema for zod/valibot-backed fields.
+- The string API is strict — a modifier that does not apply to its type is a parse error (the fluent API silently ignores it).
 - Use `f()` fluent builder, NOT nested `f.array(f.string())` -- those are removed.
 - Field names must be descriptive (not generic like `text`, `data`, `input`).
 - Image/file media types are input-only, top-level only; audio may also be a single top-level output.