@axlsdk/axl 0.25.3 → 0.27.0

package/README.md

@@ -509,22 +509,28 @@ const checkpointed = await ctx.checkpoint('expensive-op', async () => expensiveO
 
 ### OpenTelemetry Observability
 
-Automatic span emission for every `ctx.*` primitive with cost-per-span attribution. Install `@opentelemetry/api` as an optional peer dependency.
+Automatic spans for `ctx.*` primitives and every model call Axl sends. Install
+`@opentelemetry/api` as an optional peer dependency.
 
 ```typescript
 import { defineConfig, AxlRuntime } from '@axlsdk/axl';
+import { context, trace } from '@opentelemetry/api';
+import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
 import {
   BasicTracerProvider,
   SimpleSpanProcessor,
 } from '@opentelemetry/sdk-trace-base';
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
 
-const tracerProvider = new BasicTracerProvider();
-tracerProvider.addSpanProcessor(
-  new SimpleSpanProcessor(
-    new OTLPTraceExporter({ url: 'http://localhost:4318/v1/traces' }),
-  ),
-);
+const tracerProvider = new BasicTracerProvider({
+  spanProcessors: [
+    new SimpleSpanProcessor(
+      new OTLPTraceExporter({ url: 'http://localhost:4318/v1/traces' }),
+    ),
+  ],
+});
+context.setGlobalContextManager(new AsyncLocalStorageContextManager());
+trace.setGlobalTracerProvider(tracerProvider);
 
 const config = defineConfig({
   telemetry: {
@@ -536,11 +542,29 @@ const config = defineConfig({
 
 const runtime = new AxlRuntime(config);
 await runtime.initializeTelemetry();
+
+// After the application stops accepting work:
+await runtime.shutdown();
+await tracerProvider.shutdown();
+context.disable();
+trace.disable();
 ```
 
-**Span model:** `axl.workflow.execute` > `axl.agent.ask` > `axl.tool.call`. Also: `axl.ctx.spawn`, `axl.ctx.race`, `axl.ctx.vote`, `axl.ctx.budget`, `axl.ctx.awaitHuman`. Each span includes relevant attributes (cost, duration, token counts, etc.).
+**Span model:** `axl.workflow.execute` > `axl.agent.ask` > `chat {model}`
+for model calls, with `axl.tool.call` under an agent when tools run. Also:
+`axl.ctx.spawn`, `axl.ctx.race`, `axl.ctx.vote`, `axl.ctx.budget`,
+`axl.ctx.awaitHuman`. Model-call spans use standard `gen_ai.*` attributes.
+Prompt and response content is off by default; see
+[content capture](../../docs/observability.md#genai-content-capture).
 
-When disabled (default), `NoopSpanManager` provides zero overhead.
+When telemetry is disabled (default), `NoopSpanManager` adds no overhead. Axl
+never shuts down your tracer provider; do that after `runtime.shutdown()`.
+
+For this Node setup, install the optional OTel packages used above:
+
+```bash
+npm install @opentelemetry/api @opentelemetry/context-async-hooks @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http
+```
 
 ```typescript
 import { createSpanManager, NoopSpanManager } from '@axlsdk/axl';
@@ -595,6 +619,9 @@ eval history row that owns them is saved, deleted with it, and reclaimed by a
 startup pass plus a periodic sweep. See
 [observability.md](../../docs/observability.md#captured-requests-opt-in) and
 [integration.md](../../docs/integration.md#diagnostic-artifact-storage).
+`foldJournal()` turns journal lines into one validated record per call, and
+`redactModelCallRecord()` returns a redacted copy. See
+[What a record contains](../../docs/observability.md#what-a-record-contains).
 
 Compatible loaded ESM/CJS copies share accounting, admission, and capture in
 one JavaScript realm. Cross-copy work emits one warning identifying both copies;
@@ -728,7 +755,9 @@ const store = await RedisStore.create({
 
 The prefix is concatenated as-given — no normalization. Include a trailing colon if you want one. Empty string is rejected.
 
-**TTLs are strongly recommended in production** — without them every `save*` accumulates forever and Redis eventually OOMs. Sliding window: `memory`, `session`, `sessionMeta` (every write refreshes; reads do NOT). Fixed-creation: `checkpoint`, `streamingEvents`. Fixed-refresh: `executionState`, `executionHistory`, `evalHistory`. `streamingEvents` is opt-in only (does NOT fall back to `defaultTtl`). See [api-reference.md](../../docs/api-reference.md#redisstore-options) for the full table.
+**TTLs are strongly recommended in production** — without them every `save*` accumulates forever and Redis eventually OOMs. Sliding window: `memory`, `session`, `sessionMeta` (every write refreshes; reads do NOT). Fixed from the first write: `checkpoint`, `streamingEvents`, `evalHistory` (re-saves and corrections keep an eval row's expiry). Restarted on every save: `executionState`, `executionHistory`. `streamingEvents` is opt-in only (does NOT fall back to `defaultTtl`). See [api-reference.md](../../docs/api-reference.md#redisstore-options) for the full table.
+
+`MemoryStore` and `SQLiteStore` take the same `ttls.executionHistory` / `ttls.evalHistory`; `MemoryStore` keeps the newest 1 000 runs by default (`maxExecutions`). See the [execution history retention guide](../../docs/migration/execution-history-retention.md).
 
 #### Crash survival: `state.persist: 'streaming'`
 
@@ -744,8 +773,7 @@ const runtime = new AxlRuntime({
   },
 });
 
-// Boot sequence: lazy-load THEN recover THEN accept new work
-await runtime.getExecutions();
+// Boot sequence: recover THEN accept new work
 const recovered = await runtime.recoverIncompleteStreams();
 console.log(`Recovered ${recovered.length} crashed executions`);
 app.listen(3000);
@@ -776,7 +804,19 @@ runtime.on('decision_cleanup_failed', (e) => {
 
 If the execution is still running, the workflow is aborted (and a paused `ctx.awaitHuman()` correctly wakes with `AbortError` — fixed in 0.17.7). The resurrection guard ensures the workflow's eventual `workflow_end` doesn't re-create the row. Deletion waits for any in-process approval resolution or cancellation compensation before the store sweep. Custom stores must make `resolveDecision` idempotent and implement the complete execution-scoped sweep in `deleteExecution`.
 
-`ExecutionInfo.metadata` round-trips from `ExecuteOptions.metadata` (`userId`, `tenantId`, etc.) — queryable via `runtime.getExecutions().filter(...)`. Internal session control-plane keys (`sessionHistory`, `sessionId`) are stripped before persistence; they remain available via `ctx.metadata` for dynamic selectors.
+`ExecutionInfo.metadata` round-trips from `ExecuteOptions.metadata` (`userId`, `tenantId`, etc.). Filter on it as you read history; for large histories, read a page at a time:
+
+```typescript
+let cursor: ExecutionCursor | undefined;
+do {
+  const page = await runtime.getExecutions({ limit: 500, cursor });
+  for (const e of page) if (e.metadata?.tenantId === tenantId) handle(e);
+  const last = page.at(-1);
+  cursor = last && { startedAt: last.startedAt, executionId: last.executionId };
+} while (cursor);
+```
+
+Internal session control-plane keys (`sessionHistory`, `sessionId`) are stripped before persistence; they remain available via `ctx.metadata` for dynamic selectors.
 
 ### Session Options
 

package/dist/{chunk-PJROX3XU.js → chunk-SBQL47BB.js}

@@ -12,11 +12,9 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 var OTelSpanManager = class _OTelSpanManager {
   tracer;
   otelApi;
-  tracerProvider;
-  constructor(otelApi, tracer, tracerProvider) {
+  constructor(otelApi, tracer) {
     this.otelApi = otelApi;
     this.tracer = tracer;
-    this.tracerProvider = tracerProvider;
   }
   static async create(config) {
     let otelApi;
@@ -30,28 +28,14 @@ var OTelSpanManager = class _OTelSpanManager {
     const tracerProvider = config.tracerProvider ?? otelApi.trace.getTracerProvider();
     const serviceName = config.serviceName ?? "axl";
     const tracer = tracerProvider.getTracer(serviceName);
-    return new _OTelSpanManager(otelApi, tracer, tracerProvider);
+    return new _OTelSpanManager(otelApi, tracer);
   }
   async withSpanAsync(name, attributes, fn) {
-    const otelApi = this.otelApi;
     return this.tracer.startActiveSpan(name, { attributes }, async (otelSpan) => {
       let statusWasSet = false;
-      const handle = {
-        setAttribute(key, value) {
-          otelSpan.setAttribute(key, value);
-        },
-        addEvent(eventName, attrs) {
-          otelSpan.addEvent(eventName, attrs);
-        },
-        setStatus(code, message) {
-          statusWasSet = true;
-          const statusCode = code === "ok" ? otelApi.SpanStatusCode.OK : code === "error" ? otelApi.SpanStatusCode.ERROR : otelApi.SpanStatusCode.UNSET;
-          otelSpan.setStatus({ code: statusCode, message });
-        },
-        end() {
-          otelSpan.end();
-        }
-      };
+      const handle = this.handle(otelSpan, () => {
+        statusWasSet = true;
+      });
       try {
         const result = await fn(handle);
         if (!statusWasSet) handle.setStatus("ok");
@@ -64,16 +48,47 @@ var OTelSpanManager = class _OTelSpanManager {
       }
     });
   }
+  /** Start a CLIENT inference span under the current OTel context. The caller ends it. */
+  startSpan(name, attributes, options) {
+    const span = this.tracer.startSpan(name, {
+      attributes,
+      ...options?.kind === "client" ? { kind: this.otelApi.SpanKind.CLIENT } : {},
+      ...options?.startTime !== void 0 ? { startTime: options.startTime } : {}
+    });
+    return this.handle(span);
+  }
+  handle(span, onStatus) {
+    const otelApi = this.otelApi;
+    let ended = false;
+    return {
+      setAttribute(key, value) {
+        if (!ended) span.setAttribute(key, value);
+      },
+      addEvent(name, attributes) {
+        if (!ended) span.addEvent(name, attributes);
+      },
+      setStatus(code, message) {
+        if (ended) return;
+        onStatus?.();
+        const statusCode = code === "ok" ? otelApi.SpanStatusCode.OK : code === "error" ? otelApi.SpanStatusCode.ERROR : otelApi.SpanStatusCode.UNSET;
+        span.setStatus({ code: statusCode, message });
+      },
+      end() {
+        if (ended) return;
+        ended = true;
+        span.end();
+      }
+    };
+  }
   addEventToActiveSpan(name, attributes) {
     const activeSpan = this.otelApi.trace.getActiveSpan?.();
     if (activeSpan) {
       activeSpan.addEvent(name, attributes);
     }
   }
+  // Axl uses an application-owned provider, whether supplied or global.
+  // Its lifecycle, including flush and shutdown, belongs to the application.
   async shutdown() {
-    if (this.tracerProvider && typeof this.tracerProvider.shutdown === "function") {
-      await this.tracerProvider.shutdown();
-    }
   }
 };
 
@@ -81,4 +96,4 @@ export {
   __require,
   OTelSpanManager
 };
-//# sourceMappingURL=chunk-PJROX3XU.js.map
+//# sourceMappingURL=chunk-SBQL47BB.js.map

package/dist/chunk-SBQL47BB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/telemetry/span-manager.ts"],"sourcesContent":["import type {\n  SpanAttributeValue,\n  SpanAttributes,\n  SpanHandle,\n  SpanManager,\n  TelemetryConfig,\n} from './types.js';\n\n/** Minimal interface for an OTel span. */\ninterface OTelSpan {\n  setAttribute(key: string, value: SpanAttributeValue): void;\n  addEvent(name: string, attributes?: SpanAttributes): void;\n  setStatus(status: { code: unknown; message?: string }): void;\n  end(): void;\n}\n\n/** Minimal interface for an OTel tracer. */\ninterface OTelTracer {\n  startSpan(\n    name: string,\n    options: { attributes: SpanAttributes; kind?: number; startTime?: number },\n  ): OTelSpan;\n  startActiveSpan<T>(\n    name: string,\n    options: { attributes: SpanAttributes },\n    fn: (span: OTelSpan) => Promise<T>,\n  ): Promise<T>;\n}\n\n/** Minimal interface for an OTel tracer provider. */\ninterface OTelTracerProvider {\n  getTracer(name: string): OTelTracer;\n}\n\n/** Minimal interface for the @opentelemetry/api module. */\ninterface OTelApi {\n  SpanKind: { CLIENT: number };\n  SpanStatusCode: { UNSET: unknown; OK: unknown; ERROR: unknown };\n  trace: {\n    getTracerProvider(): OTelTracerProvider;\n    getActiveSpan?(): OTelSpan | undefined;\n  };\n}\n\n/**\n * OpenTelemetry-backed SpanManager.\n * Dynamically imports @opentelemetry/api to avoid hard dependency.\n */\nexport class OTelSpanManager implements SpanManager {\n  private tracer: OTelTracer;\n  private otelApi: OTelApi;\n\n  private constructor(otelApi: OTelApi, tracer: OTelTracer) {\n    this.otelApi = otelApi;\n    this.tracer = tracer;\n  }\n\n  static async create(config: TelemetryConfig): Promise<OTelSpanManager> {\n    let otelApi: OTelApi;\n    try {\n      otelApi = (await import('@opentelemetry/api')) as unknown as OTelApi;\n    } catch {\n      throw new Error(\n        '@opentelemetry/api is required for telemetry. Install it with: npm install @opentelemetry/api',\n      );\n    }\n\n    const tracerProvider =\n      (config.tracerProvider as OTelTracerProvider | undefined) ??\n      otelApi.trace.getTracerProvider();\n    const serviceName = config.serviceName ?? 'axl';\n    const tracer = tracerProvider.getTracer(serviceName);\n\n    return new OTelSpanManager(otelApi, tracer);\n  }\n\n  async withSpanAsync<T>(\n    name: string,\n    attributes: SpanAttributes,\n    fn: (span: SpanHandle) => Promise<T>,\n  ): Promise<T> {\n    return this.tracer.startActiveSpan(name, { attributes }, async (otelSpan: OTelSpan) => {\n      let statusWasSet = false;\n      const handle = this.handle(otelSpan, () => {\n        statusWasSet = true;\n      });\n\n      try {\n        const result = await fn(handle);\n        if (!statusWasSet) handle.setStatus('ok');\n        return result;\n      } catch (err) {\n        // Error text can contain provider, prompt, or sensitive tool data.\n        // Keep exported status structural; host diagnostics remain in Axl's\n        // own error and redacted event channels.\n        handle.setStatus('error');\n        throw err;\n      } finally {\n        handle.end();\n      }\n    });\n  }\n\n  /** Start a CLIENT inference span under the current OTel context. The caller ends it. */\n  startSpan(\n    name: string,\n    attributes: SpanAttributes,\n    options?: { kind?: 'client'; startTime?: number },\n  ): SpanHandle {\n    const span = this.tracer.startSpan(name, {\n      attributes,\n      ...(options?.kind === 'client' ? { kind: this.otelApi.SpanKind.CLIENT } : {}),\n      ...(options?.startTime !== undefined ? { startTime: options.startTime } : {}),\n    });\n    return this.handle(span);\n  }\n\n  private handle(span: OTelSpan, onStatus?: () => void): SpanHandle {\n    const otelApi = this.otelApi;\n    let ended = false;\n    return {\n      setAttribute(key, value) {\n        if (!ended) span.setAttribute(key, value);\n      },\n      addEvent(name, attributes) {\n        if (!ended) span.addEvent(name, attributes);\n      },\n      setStatus(code, message) {\n        if (ended) return;\n        onStatus?.();\n        const statusCode =\n          code === 'ok'\n            ? otelApi.SpanStatusCode.OK\n            : code === 'error'\n              ? otelApi.SpanStatusCode.ERROR\n              : otelApi.SpanStatusCode.UNSET;\n        span.setStatus({ code: statusCode, message });\n      },\n      end() {\n        if (ended) return;\n        ended = true;\n        span.end();\n      },\n    };\n  }\n\n  addEventToActiveSpan(name: string, attributes?: SpanAttributes): void {\n    const activeSpan = this.otelApi.trace.getActiveSpan?.();\n    if (activeSpan) {\n      activeSpan.addEvent(name, attributes);\n    }\n  }\n\n  // Axl uses an application-owned provider, whether supplied or global.\n  // Its lifecycle, including flush and shutdown, belongs to the application.\n  async shutdown(): Promise<void> {}\n}\n"],"mappings":";;;;;;;;;;;AAgDO,IAAM,kBAAN,MAAM,iBAAuC;AAAA,EAC1C;AAAA,EACA;AAAA,EAEA,YAAY,SAAkB,QAAoB;AACxD,SAAK,UAAU;AACf,SAAK,SAAS;AAAA,EAChB;AAAA,EAEA,aAAa,OAAO,QAAmD;AACrE,QAAI;AACJ,QAAI;AACF,gBAAW,MAAM,OAAO,oBAAoB;AAAA,IAC9C,QAAQ;AACN,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AAEA,UAAM,iBACH,OAAO,kBACR,QAAQ,MAAM,kBAAkB;AAClC,UAAM,cAAc,OAAO,eAAe;AAC1C,UAAM,SAAS,eAAe,UAAU,WAAW;AAEnD,WAAO,IAAI,iBAAgB,SAAS,MAAM;AAAA,EAC5C;AAAA,EAEA,MAAM,cACJ,MACA,YACA,IACY;AACZ,WAAO,KAAK,OAAO,gBAAgB,MAAM,EAAE,WAAW,GAAG,OAAO,aAAuB;AACrF,UAAI,eAAe;AACnB,YAAM,SAAS,KAAK,OAAO,UAAU,MAAM;AACzC,uBAAe;AAAA,MACjB,CAAC;AAED,UAAI;AACF,cAAM,SAAS,MAAM,GAAG,MAAM;AAC9B,YAAI,CAAC,aAAc,QAAO,UAAU,IAAI;AACxC,eAAO;AAAA,MACT,SAAS,KAAK;AAIZ,eAAO,UAAU,OAAO;AACxB,cAAM;AAAA,MACR,UAAE;AACA,eAAO,IAAI;AAAA,MACb;AAAA,IACF,CAAC;AAAA,EACH;AAAA;AAAA,EAGA,UACE,MACA,YACA,SACY;AACZ,UAAM,OAAO,KAAK,OAAO,UAAU,MAAM;AAAA,MACvC;AAAA,MACA,GAAI,SAAS,SAAS,WAAW,EAAE,MAAM,KAAK,QAAQ,SAAS,OAAO,IAAI,CAAC;AAAA,MAC3E,GAAI,SAAS,cAAc,SAAY,EAAE,WAAW,QAAQ,UAAU,IAAI,CAAC;AAAA,IAC7E,CAAC;AACD,WAAO,KAAK,OAAO,IAAI;AAAA,EACzB;AAAA,EAEQ,OAAO,MAAgB,UAAmC;AAChE,UAAM,UAAU,KAAK;AACrB,QAAI,QAAQ;AACZ,WAAO;AAAA,MACL,aAAa,KAAK,OAAO;AACvB,YAAI,CAAC,MAAO,MAAK,aAAa,KAAK,KAAK;AAAA,MAC1C;AAAA,MACA,SAAS,MAAM,YAAY;AACzB,YAAI,CAAC,MAAO,MAAK,SAAS,MAAM,UAAU;AAAA,MAC5C;AAAA,MACA,UAAU,MAAM,SAAS;AACvB,YAAI,MAAO;AACX,mBAAW;AACX,cAAM,aACJ,SAAS,OACL,QAAQ,eAAe,KACvB,SAAS,UACP,QAAQ,eAAe,QACvB,QAAQ,eAAe;AAC/B,aAAK,UAAU,EAAE,MAAM,YAAY,QAAQ,CAAC;AAAA,MAC9C;AAAA,MACA,MAAM;AACJ,YAAI,MAAO;AACX,gBAAQ;AACR,aAAK,IAAI;AAAA,MACX;AAAA,IACF;AAAA,EACF;AAAA,EAEA,qBAAqB,MAAc,YAAmC;AACpE,UAAM,aAAa,KAAK,QAAQ,MAAM,gBAAgB;AACtD,QAAI,YAAY;AACd,iBAAW,SAAS,MAAM,UAAU;AAAA,IACtC;AAAA,EACF;AAAA;AAAA;AAAA,EAIA,MAAM,WAA0B;AAAA,EAAC;AACnC;","names":[]}