@ax-llm/ax 18.0.7 → 18.0.9

package/package.json

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

package/skills/ax-agent.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent
 description: This skill helps with building AxAgent-based agents using @ax-llm/ax. Use when the user asks about agent(), AxAgent, child agents, tool functions, RLM mode, stopping agents, or composing multi-agent hierarchies.
-version: "18.0.7"
+version: "18.0.9"
 ---
 
 # AxAgent Guide (@ax-llm/ax)
@@ -399,7 +399,13 @@ const analyzer = agent(
     maxRuntimeChars: 2_000,                      // Cap for llmQuery context + code output (default: 5000)
     maxBatchedLlmQueryConcurrency: 6,            // Max parallel batched llmQuery calls (default: 8)
     maxTurns: 10,                                // Max Actor turns before forcing Responder (default: 10)
-    compressLog: true,                           // Store actionDescription in actionLog instead of full code
+    contextManagement: {                           // Semantic context management (replaces trajectoryPruning)
+      errorPruning: true,                          // Prune error entries after successful turns
+      hindsightEvaluation: true,                   // Heuristic importance scoring on entries
+      tombstoning: true,                           // Replace resolved errors with compact summaries
+      stateInspection: { contextThreshold: 2000 }, // Enable inspect_runtime() tool
+      pruneRank: 2,                                // Entries ranked below this are purged (0-5, default: 2)
+    },
     actorFields: ['reasoning'],                  // Output fields produced by Actor instead of Responder
     actorCallback: async (result) => {           // Called after each Actor turn
       console.log('Actor turn:', result);
@@ -441,6 +447,31 @@ Available permissions:
 
 > **Warning**: Granting `WORKERS` allows code to spawn sub-workers that get fresh, unlocked globals. A child worker has full access to `fetch`, `indexedDB`, etc. regardless of the parent's permissions. Only grant `WORKERS` when you trust the executed code.
 
+### Consecutive Execution Error Cutoff
+
+`AxJSRuntime` can enforce a cutoff for consecutive execution failures:
+
+```typescript
+import { AxJSRuntime } from '@ax-llm/ax';
+
+const runtime = new AxJSRuntime({
+  consecutiveErrorCutoff: 3,
+});
+```
+
+Behavior:
+
+- The runtime tracks consecutive execution failures.
+- The counter resets on successful execution.
+- When failures hit the configured cutoff, the runtime throws `AxRuntimeExecutionError` and exits the session.
+- Preflight guardrail errors are not counted (for example blocked `"use strict"` and reserved-name reassignment checks).
+
+You can manually reset the runtime-level counter:
+
+```typescript
+runtime.resetConsecutiveErrorCounter();
+```
+
 ### Structured Context Fields
 
 Context fields aren't limited to plain strings. You can pass structured data — objects and arrays with typed sub-fields:
@@ -721,18 +752,24 @@ but `globalThis.state = ...` (or mutating a shared `state` object) is the recomm
 Errors thrown by code running inside `session.execute(code)` cross the worker boundary and can be caught on the host. Always `await` `session.execute()` inside a try/catch:
 
 ```typescript
+import { AxRuntimeExecutionError } from '@ax-llm/ax';
+
 try {
   const result = await session.execute(code);
   // use result
 } catch (e) {
-  // e is an Error with name and message preserved from the worker
-  if (e instanceof Error && e.name === 'WaitForUserActionError') {
+  if (e instanceof AxRuntimeExecutionError) {
+    // Consecutive execution failures reached the cutoff; session was exited.
+  } else if (e instanceof Error && e.name === 'WaitForUserActionError') {
     // handle domain-specific error
   }
-  console.error(e.message);
+  console.error(e instanceof Error ? e.message : String(e));
 }
 ```
 
+- **`AxRuntimeExecutionError`** is thrown when the runtime reaches the configured consecutive execution failure cutoff.
+- The cutoff counter **resets on successful execution**.
+- **Preflight guardrail errors are not counted** toward the cutoff.
 - **`e.name`** and **`e.message`** are preserved, so you can branch on `e.name === 'WaitForUserActionError'` (or other custom error names) and use `e.message` for user-facing context.
 - **`e.cause`** is preserved when structured-cloneable, including recursive cause chains (with a depth limit).
 - **`e.data`** (optional) is preserved when the thrown error has a `data` property set to a structured-cloneable value (object, array, string, number, etc.). Use it for custom payloads (e.g. `(e as Error & { data?: unknown }).data`). Non-cloneable values are omitted.
@@ -779,6 +816,27 @@ RLM mode does not support true streaming. When using `streamingForward`, RLM run
 
 ## API Reference
 
+### `AxJSRuntime`
+
+```typescript
+new AxJSRuntime({
+  timeout?: number;
+  permissions?: readonly AxJSRuntimePermission[];
+  outputMode?: 'return' | 'stdout';
+  captureConsole?: boolean;
+  allowUnsafeNodeHostAccess?: boolean;
+  nodeWorkerPoolSize?: number;
+  debugNodeWorkerPool?: boolean;
+  consecutiveErrorCutoff?: number; // Cutoff for consecutive execution failures
+});
+
+runtime.resetConsecutiveErrorCounter(): void; // Resets runtime-level consecutive failure counter
+```
+
+### `AxRuntimeExecutionError`
+
+Thrown by `AxJSRuntime` when consecutive execution failures reach `consecutiveErrorCutoff`. When this happens, the active runtime session is exited. Preflight guardrail errors are not counted toward this cutoff.
+
 ### `AxRLMConfig`
 
 ```typescript
@@ -789,11 +847,20 @@ interface AxRLMConfig {
   maxRuntimeChars?: number;                  // Cap for llmQuery context + code output (default: 5000)
   maxBatchedLlmQueryConcurrency?: number;    // Max parallel batched llmQuery calls (default: 8)
   maxTurns?: number;                         // Max Actor turns before forcing Responder (default: 10)
-  compressLog?: boolean;                     // Use actionDescription entries instead of full code in actionLog
+  trajectoryPruning?: boolean;               // @deprecated Use contextManagement.errorPruning instead
+  contextManagement?: AxContextManagementConfig; // Semantic context management
   actorFields?: string[];                    // Output fields produced by Actor instead of Responder
   actorCallback?: (result: Record<string, unknown>) => void | Promise<void>;  // Called after each Actor turn
   mode?: 'simple' | 'advanced';                  // Sub-query mode: 'simple' = AxGen, 'advanced' = AxAgent (default: 'simple')
 }
+
+interface AxContextManagementConfig {
+  errorPruning?: boolean;                    // Prune error entries after successful turns
+  tombstoning?: boolean | Omit<AxProgramForwardOptions<string>, 'functions'>; // Replace resolved errors with compact summaries
+  hindsightEvaluation?: boolean;             // Heuristic importance scoring on entries
+  stateInspection?: { contextThreshold?: number }; // Enable inspect_runtime() tool
+  pruneRank?: number;                        // Entries ranked below this are purged (0-5, default: 2)
+}
 ```
 
 ### `AxCodeRuntime`
@@ -838,7 +905,8 @@ Extends `AxProgramForwardOptions` (without `functions`) with:
   maxRuntimeChars?: number;
   maxBatchedLlmQueryConcurrency?: number;
   maxTurns?: number;
-  compressLog?: boolean;
+  trajectoryPruning?: boolean;               // @deprecated Use contextManagement.errorPruning
+  contextManagement?: AxContextManagementConfig;
   actorFields?: string[];
   actorCallback?: (result: Record<string, unknown>) => void | Promise<void>;
   mode?: 'simple' | 'advanced';

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: "18.0.7"
+version: "18.0.9"
 ---
 
 # Ax Library (@ax-llm/ax) Usage Guide