@ax-llm/ax 19.0.37 → 19.0.39

package/package.json

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

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 recursive optimization guidance.
-version: "19.0.37"
+version: "19.0.39"
 ---
 
 # AxAgent Optimize Codegen Rules (@ax-llm/ax)

package/skills/ax-agent.md

@@ -1,7 +1,7 @@
 ---
 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: "19.0.37"
+version: "19.0.39"
 ---
 
 # AxAgent Codegen Rules (@ax-llm/ax)
@@ -724,6 +724,7 @@ 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:
 
@@ -731,9 +732,20 @@ Good pattern:
 const supportAgent = agent('query:string -> answer:string', {
   contextFields: ['query'],
   runtime,
-  actorTurnCallback: ({ turn, code, result, output, thought, isError }) => {
+  actorTurnCallback: ({
+    turn,
+    actionLogEntryCount,
+    guidanceLogEntryCount,
+    code,
+    result,
+    output,
+    thought,
+    isError,
+  }) => {
     console.log({
       turn,
+      actionLogEntryCount,
+      guidanceLogEntryCount,
       isError,
       code,
       rawResult: result,
@@ -1137,6 +1149,8 @@ agentIdentity?: {
   actorFields?: string[];
   actorTurnCallback?: (turn: {
     turn: number;
+    actionLogEntryCount: number;
+    guidanceLogEntryCount: number;
     actorResult: Record<string, unknown>;
     code: string;
     result: unknown;
@@ -1186,6 +1200,82 @@ agentIdentity?: {
 - 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.
 
+## Observability: getChatLog() and getUsage()
+
+`AxAgent` exposes two sub-programs (Actor and Responder). Both `getChatLog()` and `getUsage()` return an object split by role — unlike `AxGen`, which returns a flat array.
+
+### getChatLog()
+
+Returns the full normalized chat history split by actor/responder after any `.forward()` call. Each entry is one `ai.chat()` round-trip. The actor accumulates one entry per turn; the responder typically has one.
+
+```typescript
+const log = myAgent.getChatLog();
+// { actor: AxChatLogEntry[], responder: AxChatLogEntry[] }
+
+for (const entry of log.actor) {
+  console.log('Actor model:', entry.model);
+  for (const msg of entry.messages) {
+    console.log(`[${msg.role}]`, msg.content);
+  }
+}
+
+for (const entry of log.responder) {
+  console.log('Responder model:', 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 = {
+  model: string;
+  messages: AxChatLogMessage[];
+  modelUsage?: AxProgramUsage;
+};
+```
+
+### 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);
+```
+
+### resetUsage()
+
+Resets both actor and responder usage at once:
+
+```typescript
+myAgent.resetUsage();
+```
+
+### Type signatures
+
+```typescript
+// AxAgent
+agent.getChatLog(): { actor: readonly AxChatLogEntry[]; responder: readonly AxChatLogEntry[] }
+agent.getUsage():   { actor: AxProgramUsage[]; responder: AxProgramUsage[] }
+agent.resetUsage(): void
+
+// AxGen (flat — no split)
+gen.getChatLog(): readonly AxChatLogEntry[]
+gen.getUsage():   AxProgramUsage[]
+```
+
 ## Examples
 
 Fetch these for full working code:

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, extended thinking, context caching, or mentions OpenAI/Anthropic/Google/Azure/Groq/DeepSeek/Mistral/Cohere/Together/Ollama/HuggingFace/Reka/OpenRouter with @ax-llm/ax.
-version: "19.0.37"
+version: "19.0.39"
 ---
 
 # AI Provider 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: "19.0.37"
+version: "19.0.39"
 ---
 
 # 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(), assertions, field processors, step hooks, self-tuning, or structured outputs.
-version: "19.0.37"
+version: "19.0.39"
 ---
 
 # AxGen Codegen Rules (@ax-llm/ax)
@@ -299,6 +299,58 @@ Rules:
 - `AxGenerateError` includes `details` with `model` and `signature` for debugging.
 - `AxAIServiceAbortedError` is thrown on cancellation via `stop()` or `abortSignal`.
 
+## Chat Log and Usage
+
+### getChatLog()
+
+After any `.forward()` or `streamingForward()` call, `gen.getChatLog()` returns the full normalized chat history — every `ai.chat()` round-trip, including the system prompt, all messages, and the model response. The log is reset at the start of each `.forward()` call. Multi-step generators (with function calls) produce one entry per step.
+
+```typescript
+await gen.forward(llm, { question: 'What is 2+2?' });
+
+for (const entry of gen.getChatLog()) {
+  console.log('model:', entry.model);
+  for (const msg of entry.messages) {
+    console.log(`[${msg.role}]`, msg.content);
+  }
+  console.log('tokens:', entry.modelUsage?.tokens);
+}
+```
+
+Message roles: `system`, `user`, `assistant`, `tool`. Assistant content uses inline XML:
+- `<think>...</think>` — reasoning/thinking tokens
+- `<tool_call>\n{...}\n</tool_call>` — tool invocations
+
+The system message includes a `<tools>` JSON block when functions are present.
+
+```typescript
+type AxChatLogMessage =
+  | { role: 'system'; content: string }
+  | { role: 'user'; content: string }
+  | { role: 'assistant'; content: string }
+  | { role: 'tool'; name: string; content: string };
+
+type AxChatLogEntry = {
+  model: string;
+  messages: AxChatLogMessage[];
+  modelUsage?: AxProgramUsage;
+};
+
+gen.getChatLog(): readonly AxChatLogEntry[]
+```
+
+### getUsage()
+
+Returns token usage aggregated by `(ai, model)` across all steps. Reset with `resetUsage()`.
+
+```typescript
+const usage = gen.getUsage(); // AxProgramUsage[]
+console.log(usage[0]?.tokens?.promptTokens);
+gen.resetUsage();
+```
+
+> For `AxAgent`, both `getChatLog()` and `getUsage()` return `{ actor: ..., responder: ... }` — see `ax-agent` skill.
+
 ## Examples
 
 Fetch these for full working code:

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: "19.0.37"
+version: "19.0.39"
 ---
 
 # AxGEPA Codegen Rules (@ax-llm/ax)

package/skills/ax-learn.md

@@ -1,7 +1,7 @@
 ---
 name: ax-learn
 description: This skill helps an LLM generate correct AxLearn code using @ax-llm/ax. Use when the user asks about self-improving agents, trace-backed learning, feedback-aware updates, or AxLearn modes.
-version: "19.0.37"
+version: "19.0.39"
 ---
 
 # AxLearn Codegen Rules (@ax-llm/ax)

package/skills/ax-llm.md

@@ -1,7 +1,7 @@
 ---
 name: ax
 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: "19.0.37"
+version: "19.0.39"
 ---
 
 # Ax Library (@ax-llm/ax) Quick Reference

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: "19.0.37"
+version: "19.0.39"
 ---
 
 # Ax Signature Reference