@axlsdk/axl 0.14.0 → 0.16.0

package/README.md

@@ -12,6 +12,8 @@ npm install @axlsdk/axl zod@^4
 
 > **Note:** `zod` is a peer dependency — your application and Axl share a single Zod instance. Zod v4 (`^4.0.0`) is required.
 
+> **Migrating from 0.15?** The 0.16.0 unified event model collapses `TraceEvent` and `StreamEvent` into a single `AxlEvent` union, renames `ExecutionInfo.steps` → `.events` and `AxlStream.steps` → `.lifecycle`, removes the deprecated `parentToolCallId` field, and changes `ctx.checkpoint(fn)` to `ctx.checkpoint(name, fn)`. See the [migration guide](../../docs/migration/unified-event-model.md) for the full rename/move table.
+
 ## Project Structure
 
 The recommended pattern separates config, tools, agents, workflows, and runtime into their own modules. Dependencies flow one direction: tools → agents → workflows → runtime.
@@ -303,8 +305,8 @@ const result = await runtime.execute('my-workflow', { query: 'Hello' });
 const stream = runtime.stream('my-workflow', { query: 'Hello' });
 for await (const event of stream) {
   if (event.type === 'token') process.stdout.write(event.data);
-  if (event.type === 'error') console.error('Stream error:', event.message);
-  if (event.type === 'done') console.log('Result:', event.data);
+  if (event.type === 'error') console.error('Stream error:', event.data.message);
+  if (event.type === 'done') console.log('Result:', event.data.result);
 }
 
 // Sessions
@@ -370,10 +372,12 @@ const decision = await ctx.awaitHuman({
   prompt: 'Approve this action?',
 });
 
-// Durable checkpoint — on first run, executes and saves the result.
-// On replay after a restart, returns the saved result without re-executing,
-// preventing duplicate side effects (double API calls, double charges, etc.)
-const checkpointed = await ctx.checkpoint(async () => expensiveOperation());
+// Durable checkpoint — on first run, executes and saves the result under
+// the given name. On replay after a restart, returns the saved result
+// without re-executing, preventing duplicate side effects (double API
+// calls, double charges, etc.). The name is a stable identifier and must
+// match across runs for replay to work.
+const checkpointed = await ctx.checkpoint('expensive-op', async () => expensiveOperation());
 ```
 
 ### OpenTelemetry Observability
@@ -453,6 +457,25 @@ const relevant = await ctx.recall('knowledge-base', {
 
 Vector store implementations: `InMemoryVectorStore` (testing), `SqliteVectorStore` (production, requires `better-sqlite3`).
 
+**Embedder cost attribution.** `OpenAIEmbedder` reports `{ tokens, cost, model }` on every embed call — computed from the response's `prompt_tokens` and a pricing table (`text-embedding-3-small` $0.02/1M, `-large` $0.13/1M, `ada-002` $0.10/1M). The cost flows through `runtime.trackExecution()` the same way agent-call cost does, counts against `ctx.budget()`, and shows up in Studio's Cost Dashboard under "Memory (Embedder)". See [observability.md](../../docs/observability.md#event-types) for the trace-event shape.
+
+**Custom `Embedder` implementations** (breaking change in 0.15.0 — `embed()` previously returned `Promise<number[][]>`):
+
+```typescript
+import type { Embedder, EmbedResult } from '@axlsdk/axl';
+
+class MyEmbedder implements Embedder {
+  readonly dimensions = 1536;
+
+  // `signal` is optional but recommended — lets budget hard-stops and user
+  // aborts cancel in-flight embedder fetches mid-retry.
+  async embed(texts: string[], signal?: AbortSignal): Promise<EmbedResult> {
+    const vectors = await myProvider.embed(texts, { signal });
+    return { vectors }; // `usage` optional — omit if you don't compute cost
+  }
+}
+```
+
 ### Agent Guardrails
 
 Input and output validation at the agent boundary. You define your own validation logic — Axl calls it before and after each LLM turn: