@ax-llm/ax 23.0.1 → 23.0.2

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: "23.0.1"
+version: "23.0.2"
 ---
 
 # AxFlow Codegen Rules (@ax-llm/ax)
@@ -93,6 +93,21 @@ flow.node('extractor', 'documentText:string -> entities:string[]');
 flow.n('processor', 'input:string -> output:string');
 ```
 
+### Rich Node Contracts (String Grammar)
+
+Node signatures accept the full extended string grammar — constraint bags, class decisions, optional fields, and nested objects (full modifier table in the ax-signature skill):
+
+```typescript
+flow
+  .node('triage', 'ticketText:string -> ticketClass:class "bug, billing, question", severityScore:number(min 1, max 5)')
+  .node('draft', 'ticketText:string, ticketClass:string, severityScore:number -> replyText:string(max 400)')
+  .node('audit', 'replyText:string -> approved:boolean, flaggedSpans:object{ spanText:string, reasonNote:string }[]');
+```
+
+- `class` is output-only: a downstream node consuming the decision declares it `:string`.
+- Optional marks go on the name (`note?:string`), never after the type.
+- `toString()` serializes these contracts losslessly into `%%ax` directives, so rich contracts survive the diagram round-trip.
+
 ## Extended Nodes (nx)
 
 Add fields to a base signature without rewriting it:
@@ -417,11 +432,204 @@ Common errors:
 - `"merge() without matching branch()"` -- every `.branch()` needs `.merge()`.
 - `"Label 'x' not found"` -- define `.label()` before `.feedback()` references it.
 
+## Native MCP/UCP
+
+Use `ax-mcp` for MCP client construction, transport/authentication policy,
+subscriptions, tasks, event routing, and replay. This section covers how Flow
+inherits and coordinates the resulting live execution context.
+
+Set `mcp`/`ucp` on the flow or a node. Sequential nodes reuse sessions; parallel nodes multiplex through each client's concurrency policy. Branch cancellation and flow aborts propagate to outstanding requests and newly created remote tasks. Structured protocol values stay structured in flow state.
+
+```typescript
+const wf = flow({ mcp: [inventory], ucp: [merchant] })
+  .node('lookup', lookupProgram)
+  .node('checkout', checkoutProgram, { mcpInheritance: ['merchant'] });
+```
+
+## Mermaid Source (Author or Serialize Flows)
+
+A whole flow can be written as (or exported to) a mermaid flowchart. Pass the
+diagram string straight to `flow()` — a string argument compiles the AxFlow
+mermaid dialect into a runnable flow (an options object still constructs an
+empty builder). `String(wf)` / `wf.toString()` renders any flow back, so
+`flow(String(wf))` round-trips.
+
+```typescript
+import { flow } from '@ax-llm/ax';
+
+const wf = flow<{ documentText: string }, { finalReport: string }>(`
+flowchart TD
+  %%ax summarize: documentText:string -> summaryText:string(max 500)
+  %%ax check: summaryText:string -> verdict:class "pass, fail", note?:string
+  %%ax format: summaryText:string, note?:string -> finalReport:string
+
+  summarize[Summarize document] --> check{verdict}
+  check -->|pass| format
+  check -->|fail, max 3| summarize
+`);
+
+const { finalReport } = await wf.forward(llm, { documentText });
+console.log(String(wf)); // render back to the same dialect
+```
+
+Dialect:
+- `%%ax nodeId: <signature>` comment directives carry node contracts (mermaid renderers ignore them); the full string-signature grammar applies (`?` optional on the name, constraint bags, `object{ ... }`).
+- Data auto-wires by field name: each node input binds to the nearest upstream node that outputs that field; a field no node produces becomes a flow input.
+- A diamond `nodeId{field}` names a `class` decision; its labeled out-edges (`-->|pass|`) become branches. A back-edge is a loop: `-->|label, max N|` is feedback, `-->|while cond, max N|` is a while loop.
+
+Render options and bindings:
+- `wf.toString({ direction: 'LR' })` when you need render options; bare `String(wf)` uses defaults (`flowchart TD`).
+- `bindings` supplies closures the dialect can't inline: `{ nodes: { normalize: (s) => ({...}) }, conditions: { keepGoing: (s) => ... } }` for map steps and `while` conditions.
+
+### Flow Gallery
+
+Every diagram below compiles with `flow(text)` as written (the while loop additionally needs its `conditions` binding).
+
+Linear pipeline — three nodes auto-wired by field name:
+
+```text
+flowchart TD
+  %%ax extract: contractText:string -> parties:string[], effectiveDate?:string(format date)
+  %%ax summarize: contractText:string, parties:string[] -> summaryText:string(max 300)
+  %%ax redline: summaryText:string -> riskNotes:string(item "one risk")[]
+
+  extract --> summarize --> redline
+```
+
+Decision branch — a class diamond routes to per-branch responders, then re-joins:
+
+```text
+flowchart TD
+  %%ax classify: requestText:string -> routeClass:class "support, sales"
+  %%ax supportReply: requestText:string -> replyText:string(max 300)
+  %%ax salesReply: requestText:string -> replyText:string(max 300)
+  %%ax send: replyText:string -> deliveredReply:string
+
+  classify{routeClass}
+  classify -->|support| supportReply
+  classify -->|sales| salesReply
+  supportReply --> send
+  salesReply --> send
+```
+
+Retry loop — a reviewer sends drafts back with a capped revise edge:
+
+```text
+flowchart TD
+  %%ax draft: briefText:string -> articleText:string(max 800)
+  %%ax review: articleText:string -> verdict:class "publish, revise", editorNote?:string
+  %%ax publish: articleText:string, editorNote?:string -> finalPost:string
+
+  draft --> review{verdict}
+  review -->|publish| publish
+  review -->|revise, max 2| draft
+```
+
+Fan-out / fan-in — two perspectives run in parallel, then a judge joins them:
+
+```text
+flowchart TD
+  %%ax outline: topicText:string -> questionText:string
+  %%ax proponent: questionText:string -> proArgument:string
+  %%ax skeptic: questionText:string -> conArgument:string
+  %%ax judge: proArgument:string, conArgument:string -> verdictSummary:string
+
+  outline --> proponent & skeptic
+  proponent & skeptic --> judge
+```
+
+While loop — repeat until a host-owned condition says stop (`flow(text, { conditions: { keepPolishing } })`):
+
+```text
+flowchart TD
+  %%ax polish: draftText:string -> polishedText:string
+  %%ax grade: polishedText:string -> qualityScore:number(min 0, max 1)
+
+  polish --> grade
+  grade -->|while keepPolishing, max 5| polish
+```
+
+Three-way branch and re-join — triage routes to one of three handlers before delivery:
+
+```text
+flowchart TD
+  %%ax triage: ticketText:string -> ticketClass:class "bug, billing, question"
+  %%ax bugHandler: ticketText:string -> replyText:string(max 300)
+  %%ax billingHandler: ticketText:string -> replyText:string(max 300)
+  %%ax questionHandler: ticketText:string -> replyText:string(max 300)
+  %%ax send: replyText:string -> deliveredReply:string
+
+  triage{ticketClass}
+  triage -->|bug| bugHandler
+  triage -->|billing| billingHandler
+  triage -->|question| questionHandler
+  bugHandler --> send
+  billingHandler --> send
+  questionHandler --> send
+```
+
+Judge panel — three independent drafts fan out, then converge on one verdict:
+
+```text
+flowchart TD
+  %%ax outline: topicText:string -> outlineText:string
+  %%ax draftA: outlineText:string -> draftAText:string
+  %%ax draftB: outlineText:string -> draftBText:string
+  %%ax draftC: outlineText:string -> draftCText:string
+  %%ax judge: draftAText:string, draftBText:string, draftCText:string -> verdictText:string
+
+  outline --> draftA & draftB & draftC
+  draftA & draftB & draftC --> judge
+```
+
+Escalation ladder — a quality gate either sends the first answer or falls back to level two:
+
+```text
+flowchart TD
+  %%ax l1Answer: ticketText:string -> answerText:string
+  %%ax qualityGate: answerText:string -> verdict:class "pass, escalate"
+  %%ax l2Answer: ticketText:string -> answerText:string
+  %%ax send: answerText:string -> deliveredAnswer:string
+
+  l1Answer --> qualityGate{verdict}
+  qualityGate -->|pass| send
+  qualityGate -->|escalate| l2Answer --> send
+```
+
+Itinerary planner — rich contracts stay attached to a simple linear graph:
+
+```text
+flowchart TD
+  %%ax parse: requestText:string -> destinationName:string, stayWindow:dateRange, travelerCount:number(min 1, max 12), budgetUsd?:number(min 0)
+  %%ax plan: destinationName:string, stayWindow:dateRange, travelerCount:number, budgetUsd?:number -> itineraryItems:object{ dayNumber:number(min 1), activityText:string }[]
+  %%ax price: itineraryItems:object{ dayNumber:number, activityText:string }[], travelerCount:number -> estimatedTotalUsd:number(min 0), bookingNotes?:string(max 300)
+
+  parse --> plan --> price
+```
+
+Fan-out with capped revision — two sections join, then review can send the assembly back twice:
+
+```text
+flowchart TD
+  %%ax outline: briefText:string -> outlineText:string
+  %%ax sectionA: outlineText:string -> sectionAText:string
+  %%ax sectionB: outlineText:string -> sectionBText:string
+  %%ax assemble: sectionAText:string, sectionBText:string -> articleText:string
+  %%ax review: articleText:string -> verdict:class "approve, revise", reviewNote?:string
+  %%ax publish: articleText:string, reviewNote?:string -> publishedArticle:string
+
+  outline --> sectionA & sectionB
+  sectionA & sectionB --> assemble --> review{verdict}
+  review -->|approve| publish
+  review -->|revise, max 2| assemble
+```
+
 ## Examples
 
 Fetch these for full working code:
 
 - [Flow](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/ax-flow.ts) — complete flow usage
+- [Mermaid Flow](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/ax-flow-mermaid.ts) — author/serialize a flow as a mermaid diagram
 - [Auto-Parallel](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/ax-flow-auto-parallel.ts) — auto-parallelization
 - [Async Map](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/ax-flow-async-map.ts) — async map transforms
 - [Enhanced Demo](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/ax-flow-enhanced-demo.ts) — instance-based nodes
@@ -429,6 +637,38 @@ Fetch these for full working code:
 - [Fluent Builder](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/fluent-flow-example.ts) — fluent builder pattern
 - [Load Balancing](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/balancer.ts) — load balancing
 
+## Event-Triggered Flows
+
+An AxFlow is an `AxProgrammable` event target. The runtime maps an event into
+the Flow's typed initial state and propagates `eventContext`, cancellation, and
+idempotency metadata to every node. Abandoned branches still use normal Flow
+cancellation semantics.
+
+Task-backed MCP tools called by a Flow node register a continuation on the
+shared event context. `axMCPEventRoutes` observes progress and resumes the Flow
+on input-required or terminal task notifications.
+
+For resource-driven wake, discover the endpoint with `inspectCatalog()` and
+give `AxMCPEventSource` an explicit `resourceSubscriptions` policy. Managed
+subscriptions reconcile list changes and reconnect separately from the Flow;
+subscription alone never starts or resumes a Flow.
+
+UCP lifecycle webhooks use the same continuation boundary through
+`AxUCPWebhookEventSource`. Correlate on `ucp.checkout` or `ucp.order` only after
+the signed request has been verified and mapped to application identity.
+
+Use `eventTarget('id').program(flow).wakeInput(...).resumeInput(...)` when wake
+and resume events have different shapes. Segment-safe `eventPath` mappings are
+validated against the Flow signature before any node executes; a declarative
+`.waitFor(kind, path)` creates the owned continuation consumed by the resume
+route.
+
+Reusable `eventInput()` plans are the preferred callback-free boundary.
+Callback `mapInput` is normalized against the Flow signature before any node
+runs. In generated hosts, immediate publications dispatch inline; the host uses
+`nextDueAt()` and `runDue()` for delayed retries, debounce, and continuation
+expiry.
+
 ## Do Not Generate
 
 - Do not use `new AxFlow(...)` for new code.

package/skills/ax-gen.md

@@ -1,13 +1,16 @@
 ---
 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: "23.0.1"
+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. For MCP clients, transports, prompts, resources, tasks, subscriptions, or authentication use ax-mcp alongside this skill.
+version: "23.0.2"
 ---
 
 # AxGen Codegen Rules (@ax-llm/ax)
 
 Use this skill to generate `AxGen` code. Prefer short, modern, copyable patterns. Do not write tutorial prose unless the user explicitly asks for explanation.
 
+Use the `ax-mcp` skill when AxGen attaches native MCP clients or consumes MCP
+prompts, resources, tools, tasks, subscriptions, authentication, or events.
+
 ## Use These Defaults
 
 - Use `ax(...)` factory, not `new AxGen(...)`.
@@ -485,6 +488,51 @@ Fetch these for full working code:
 - [Extraction](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/extract.ts) — information extraction
 - [Multi-Sampling](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/sample-count.ts) — sample count usage
 
+## Native MCP/UCP
+
+Use `ax-mcp` for client construction, transports, authentication, catalog and
+task APIs, subscriptions, event routing, and recording/replay. This section
+only covers the AxGen attachment boundary.
+
+Pass live clients directly to constructor or forward options:
+
+```typescript
+const gen = ax('question:string -> answer:string', { mcp: [docs, search] });
+const result = await gen.forward(llm, { question }, {
+  mcpContext: [
+    { client: 'docs', resource: { uri: 'docs://guide' } },
+  ],
+});
+```
+
+The model receives native tool definitions. Structured, image, audio, resource-link, embedded-resource, metadata, task, and error results are preserved until the provider adapter maps supported content. Streaming keeps MCP progress/task events separate from Ax output. Never call `toFunction()` for native integration.
+
+Use `client.inspectCatalog()` when an endpoint is the only configuration. It
+discovers server-owned tool/prompt names, concrete resource URIs, and URI
+templates. Event sources require an explicit none/all/URI/selector resource
+subscription policy and never create a wake route implicitly.
+
+Under an event target, a required task-backed MCP tool registers the owning
+`namespace:taskId` continuation automatically. Use `AxMCPEventSource` plus
+`axMCPEventRoutes` to observe progress and resume the target on
+`input_required` or a terminal state.
+
+## Event Targets
+
+Wrap an AxGen with
+`eventTarget('id').program(gen).ai(ai).input(...).build()` to invoke it from an
+explicit `wake` or `resume` route. Use segment-safe `eventPath` selectors;
+projection and explicit fields are validated against the AxGen signature before
+invocation. Use `.wakeInput()` and `.resumeInput()` for different action
+contracts. Streaming targets persist each chunk before optional chunk sinks and
+persist the final result before final sinks.
+
+Use a reusable `eventInput().project(...).field(...)` plan when mapping should
+be callback-free. Callback `mapInput` remains available, but its result is
+cloned, stripped to declared AxGen inputs, and signature-validated before the
+first model call; mapper exceptions become non-retryable
+`event_input_invalid` deliveries.
+
 ## Do Not Generate
 
 - Do not use `new AxGen(...)` for new code unless explicitly required.

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: "23.0.1"
+version: "23.0.2"
 ---
 
 # 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: "23.0.1"
+version: "23.0.2"
 ---
 
 # Ax Library (@ax-llm/ax) Quick Reference
@@ -238,6 +238,9 @@ axGlobals.meter = openTelemetryMeter;
 
 ## MCP Integration
 
+Use the `ax-mcp` skill for the complete native client, transport,
+authentication, catalog, task, subscription, event, and replay workflow.
+
 ```typescript
 import { AxMCPClient, agent } from '@ax-llm/ax';
 import { AxMCPStdioTransport } from '@ax-llm/ax-tools';
@@ -248,47 +251,49 @@ const transport = new AxMCPStdioTransport({
   args: ['-y', '@modelcontextprotocol/server-memory'],
 });
 
-const mcpClient = new AxMCPClient(transport, { debug: false });
-await mcpClient.init();
+const mcpClient = new AxMCPClient(transport, { namespace: 'memory' });
 
-// Use with agent under a namespace
+// Native MCP context is initialized once and inherited by all agent stages.
 const myAgent = agent('userMessage:string -> response:string', {
-  functions: [
-    {
-      namespace: 'memory',
-      title: 'Memory MCP',
-      description: 'Memory server tools',
-      selectionCriteria: 'Use for persistent memory lookup and updates.',
-      functions: [mcpClient],
-    },
-  ],
+  mcp: mcpClient,
   functionDiscovery: true,
   contextFields: [],
 });
+
+const result = await myAgent.forward(llm, { userMessage: 'Remember this.' });
+await mcpClient.close(); // caller-owned clients remain caller-owned
 ```
 
 ### HTTP Transport (Remote MCP)
 
 ```typescript
-import { AxMCPStreambleHTTPTransport } from '@ax-llm/ax/mcp/transports/httpStreamTransport.js';
+import { AxMCPStreamableHTTPTransport } from '@ax-llm/ax';
 
-const transport = new AxMCPStreambleHTTPTransport('https://remote.mcp.pipedream.net', {
+const transport = new AxMCPStreamableHTTPTransport('https://remote.example/mcp', {
   headers: { 'x-pd-project-id': projectId },
   authorization: `Bearer ${accessToken}`,
 });
 ```
 
-### MCP Capabilities
+### Native MCP and UCP behavior
 
-| Capability | Prefix | Description |
-|---|---|---|
-| Tools | *(none)* | Function calls |
-| Prompts | `prompt_` | Prompt templates |
-| Resources | `resource_` | File/data access |
+- Pass `mcp` and `ucp` to AxGen, streaming AxGen, chat, AxAgent, AxFlow, optimization, or evaluation options.
+- Use `mcpContext` to inject attributed prompts/resources before the first model call.
+- Use `mcpInheritance: 'all' | 'none' | string[]` to restrict child programs.
+- Tool calls retain raw MCP content, metadata, errors, tasks, and protocol provenance in memory.
+- AxAgent exposes native modules as `mcp.<namespace>` and `ucp.<namespace>`.
+- `inspectCatalog()` discovers tool/prompt names, concrete resources, and URI
+  templates from only an endpoint. Resource event sources default to no
+  subscriptions and require an explicit all/URI/selector policy.
+- `toFunction()` remains a compatibility adapter only; native Ax execution never uses it.
+- Live optimization is rejected by default. Use recording/replay or explicitly opt into live MCP evaluation.
 
 ```typescript
-const caps = mcpClient.getCapabilities();
-const functions = mcpClient.toFunction();
+const catalog = await mcpClient.inspectCatalog();
+const tools = catalog.tools;
+const prompts = await mcpClient.listPrompts();
+const resource = await mcpClient.readResource('docs://guide');
+const tasks = await mcpClient.listTasks();
 ```
 
 ### Function Overrides
@@ -329,6 +334,13 @@ class AxFlow<IN, OUT> {
 }
 ```
 
+## Event-Driven Programs
+
+Use `eventRuntime()` when notifications, webhooks, timers, or remote tasks
+should wake or resume an Ax program. Sources publish into an inbox; explicit
+routes choose `observe`, `invalidate`, `wake`, or `resume`. Event payloads are
+never inserted as user messages automatically. See `ax-event-runtime.md`.
+
 ## Examples
 
 Fetch these for full working code: