@agentfield/sdk 0.1.110 → 0.1.111-rc.2

package/dist/index.js

@@ -1,6 +1,6 @@
-import fs, { promises } from 'fs';
+import fs, { promises, readFileSync } from 'fs';
 import * as path2 from 'path';
-import path2__default, { resolve } from 'path';
+import path2__default, { resolve, dirname } from 'path';
 import { createRequire } from 'module';
 import { spawn } from 'child_process';
 import express from 'express';
@@ -25,6 +25,7 @@ import { Buffer as Buffer$1 } from 'buffer';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { generateKeyPair, exportJWK, importJWK, CompactEncrypt, compactDecrypt } from 'jose';
 import { readFile } from 'fs/promises';
+import { fileURLToPath } from 'url';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -154,14 +155,14 @@ function getZodConverter() {
   }
   return zodConverter;
 }
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function hasJsonSchema(value) {
-  return isRecord(value) && typeof value.jsonSchema === "function";
+  return isRecord2(value) && typeof value.jsonSchema === "function";
 }
 function hasParse(value) {
-  return isRecord(value) && typeof value.parse === "function";
+  return isRecord2(value) && typeof value.parse === "function";
 }
 function estimateTokens(text2) {
   return Math.floor(text2.length / 4);
@@ -190,7 +191,7 @@ function getSchemaPath(cwd) {
   return path2__default.join(cwd, SCHEMA_FILENAME);
 }
 function schemaToJsonSchema(schema) {
-  if (isRecord(schema)) {
+  if (isRecord2(schema)) {
     if ("type" in schema || "properties" in schema || "$schema" in schema) {
       return schema;
     }
@@ -338,7 +339,7 @@ var claude_exports = {};
 __export(claude_exports, {
   ClaudeCodeProvider: () => ClaudeCodeProvider
 });
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null;
 }
 function getString(record, key) {
@@ -382,10 +383,16 @@ var init_claude = __esm({
         let totalCost;
         let numTurns = 0;
         let sessionId = "";
+        let usageObj;
+        let inputTokens;
+        let outputTokens;
+        let cacheReadTokens;
+        let cacheCreationTokens;
+        let modelName;
         const startApi = Date.now();
         try {
           for await (const msg of sdk.query({ prompt, options: agentOptions })) {
-            const msgObj = isRecord2(msg) ? msg : { raw: String(msg) };
+            const msgObj = isRecord3(msg) ? msg : { raw: String(msg) };
             messages.push(msgObj);
             const msgType = getString(msgObj, "type") ?? "";
             if (msgType === "result") {
@@ -404,16 +411,28 @@ var init_claude = __esm({
               }
               const turns = getNumber(msgObj, "num_turns");
               numTurns = turns === void 0 ? messages.length : Math.trunc(turns);
-            } else if (msgType === "assistant" && resultText === void 0) {
+              if (isRecord3(msgObj.usage)) {
+                usageObj = msgObj.usage;
+                inputTokens = getNumber(usageObj, "input_tokens");
+                outputTokens = getNumber(usageObj, "output_tokens");
+                cacheReadTokens = getNumber(usageObj, "cache_read_input_tokens");
+                cacheCreationTokens = getNumber(usageObj, "cache_creation_input_tokens");
+              }
+              modelName = getString(msgObj, "model") ?? modelName;
+            } else if (msgType === "assistant") {
+              if (modelName === void 0 && isRecord3(msgObj.message)) {
+                modelName = getString(msgObj.message, "model");
+              }
+              if (resultText !== void 0) continue;
               let content = msgObj.content;
-              if (content === void 0 && isRecord2(msgObj.message)) {
+              if (content === void 0 && isRecord3(msgObj.message)) {
                 content = msgObj.message.content;
               }
               if (typeof content === "string") {
                 resultText = content;
               } else if (Array.isArray(content)) {
                 for (const block of content) {
-                  if (isRecord2(block) && block.type === "text" && typeof block.text === "string") {
+                  if (isRecord3(block) && block.type === "text" && typeof block.text === "string") {
                     resultText = block.text;
                   }
                 }
@@ -427,7 +446,13 @@ var init_claude = __esm({
               durationApiMs: Date.now() - startApi,
               numTurns,
               totalCostUsd: totalCost,
-              sessionId
+              sessionId,
+              usage: usageObj,
+              inputTokens,
+              outputTokens,
+              cacheReadTokens,
+              cacheCreationTokens,
+              model: modelName
             }),
             isError: false
           });
@@ -454,7 +479,7 @@ function resolveIdleMs(idleSeconds) {
   return seconds > 0 ? seconds * 1e3 : void 0;
 }
 function runCli(cmd, options) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const [bin, ...args] = cmd;
     const env = { ...process.env, ...options?.env };
     applyOpenRouterAttributionEnv(env);
@@ -514,7 +539,7 @@ function runCli(cmd, options) {
       }
       settled = true;
       cleanup();
-      resolve2({ stdout, stderr, exitCode: code ?? 0 });
+      resolve3({ stdout, stderr, exitCode: code ?? 0 });
     });
     proc.on("error", (err) => {
       if (settled) {
@@ -841,6 +866,10 @@ var runner_exports = {};
 __export(runner_exports, {
   HarnessRunner: () => HarnessRunner
 });
+function tokenMetrics(raw) {
+  const { inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens, totalTokens, model } = raw.metrics;
+  return { inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens, totalTokens, model };
+}
 var TRANSIENT_PATTERNS, HarnessRunner;
 var init_runner = __esm({
   "src/harness/runner.ts"() {
@@ -891,7 +920,8 @@ var init_runner = __esm({
             numTurns: raw.metrics.numTurns,
             durationMs: Date.now() - startTime,
             sessionId: raw.metrics.sessionId,
-            messages: raw.messages
+            messages: raw.messages,
+            ...tokenMetrics(raw)
           });
         } finally {
           if (schema !== void 0) {
@@ -984,7 +1014,8 @@ var init_runner = __esm({
             numTurns: raw.metrics.numTurns,
             durationMs: Date.now() - startTime,
             sessionId: raw.metrics.sessionId,
-            messages: raw.messages
+            messages: raw.messages,
+            ...tokenMetrics(raw)
           });
         }
         return createHarnessResult({
@@ -995,7 +1026,8 @@ var init_runner = __esm({
           numTurns: raw.metrics.numTurns,
           durationMs: Date.now() - startTime,
           sessionId: raw.metrics.sessionId,
-          messages: raw.messages
+          messages: raw.messages,
+          ...tokenMetrics(raw)
         });
       }
       async buildProvider(providerName, options) {
@@ -1008,8 +1040,8 @@ var init_runner = __esm({
         return base + jitter;
       }
       sleep(delaySeconds) {
-        return new Promise((resolve2) => {
-          setTimeout(resolve2, Math.max(0, delaySeconds) * 1e3);
+        return new Promise((resolve3) => {
+          setTimeout(resolve3, Math.max(0, delaySeconds) * 1e3);
         });
       }
     };
@@ -1200,8 +1232,8 @@ var PauseManager = class {
       return existing.promise;
     }
     let resolveFn;
-    const promise = new Promise((resolve2) => {
-      resolveFn = resolve2;
+    const promise = new Promise((resolve3) => {
+      resolveFn = resolve3;
     });
     this.pending.set(approvalRequestId, { resolve: resolveFn, promise });
     if (executionId) {
@@ -1423,7 +1455,7 @@ var ApprovalClient = class {
   }
 };
 function sleep(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 
 // src/triggers/factories.ts
@@ -1481,6 +1513,205 @@ function triggerToPayload(trigger) {
   const _exhaustive = trigger;
   throw new TypeError(`Unknown trigger kind: ${_exhaustive}`);
 }
+
+// src/triggers/dispatch.ts
+function isTriggerEnvelope(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return false;
+  const obj = body;
+  if (!("event" in obj && "_meta" in obj)) return false;
+  const meta = obj._meta;
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) return false;
+  return "trigger_id" in meta;
+}
+function unwrapEnvelope(body) {
+  if (!isTriggerEnvelope(body)) {
+    return { input: body };
+  }
+  const meta = body._meta;
+  let receivedAt;
+  try {
+    receivedAt = new Date(meta.received_at);
+    if (isNaN(receivedAt.getTime())) {
+      receivedAt = /* @__PURE__ */ new Date();
+    }
+  } catch {
+    receivedAt = /* @__PURE__ */ new Date();
+  }
+  const triggerContext = {
+    triggerId: meta.trigger_id,
+    source: meta.source,
+    eventType: meta.event_type,
+    eventId: meta.event_id,
+    idempotencyKey: meta.idempotency_key,
+    receivedAt,
+    vcId: meta.vc_id
+  };
+  return {
+    input: body.event,
+    triggerContext
+  };
+}
+function applyTriggerTransform(triggerContext, bindings, input) {
+  if (!bindings || bindings.length === 0) return input;
+  let bestMatch;
+  let bestSpecificity = -1;
+  for (const binding of bindings) {
+    if (binding.kind !== "event") continue;
+    if (binding.spec.source !== triggerContext.source) continue;
+    const types = binding.spec.types ?? [];
+    if (types.length > 0) {
+      const matched = types.some(
+        (t) => triggerContext.eventType === t || triggerContext.eventType.startsWith(t + ".")
+      );
+      if (!matched) continue;
+      if (1 > bestSpecificity) {
+        bestMatch = binding;
+        bestSpecificity = 1;
+      }
+    } else {
+      if (0 > bestSpecificity) {
+        bestMatch = binding;
+        bestSpecificity = 0;
+      }
+    }
+  }
+  if (bestMatch?.spec.transform) {
+    try {
+      return bestMatch.spec.transform(input);
+    } catch {
+      return input;
+    }
+  }
+  return input;
+}
+
+// src/usage/costTracker.ts
+var USAGE_ENVELOPE_KEY = "__agentfield_usage__";
+function deriveProvider(model) {
+  if (!model) return null;
+  const slug = String(model).trim();
+  const slash = slug.indexOf("/");
+  if (slash < 0) return null;
+  return slug.slice(0, slash).toLowerCase() || null;
+}
+function toCount(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return 0;
+  return Math.trunc(value);
+}
+function toCost(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  return value;
+}
+function round6(value) {
+  return Math.round(value * 1e6) / 1e6;
+}
+var CostTracker = class {
+  entries = [];
+  /**
+   * Record a single call's usage.
+   *
+   * Cost is optional: a call with known token counts but unknown price is
+   * still recorded (`costUsd: null`) so tokens are never discarded.
+   */
+  record(init) {
+    this.entries.push({
+      model: init.model,
+      inputTokens: toCount(init.inputTokens),
+      outputTokens: toCount(init.outputTokens),
+      totalTokens: toCount(init.totalTokens),
+      costUsd: toCost(init.costUsd),
+      reasonerName: init.reasonerName ?? null,
+      source: init.source ?? "llm",
+      provider: init.provider ?? deriveProvider(init.model),
+      harness: init.harness ?? null,
+      cacheReadTokens: toCount(init.cacheReadTokens),
+      cacheCreationTokens: toCount(init.cacheCreationTokens),
+      costSource: init.costSource ?? null
+    });
+  }
+  /** Total accumulated cost in USD (unknown costs count as zero). */
+  get totalCostUsd() {
+    return this.entries.reduce((sum, e) => sum + (e.costUsd ?? 0), 0);
+  }
+  /** Total tokens used across all calls (per-entry total, no fallback). */
+  get totalTokens() {
+    return this.entries.reduce((sum, e) => sum + e.totalTokens, 0);
+  }
+  /** Number of calls tracked. */
+  get callCount() {
+    return this.entries.length;
+  }
+  get hasEntries() {
+    return this.entries.length > 0;
+  }
+  /**
+   * Return the transport contract form attached to execution envelopes.
+   *
+   * Matches the Python SDK's `CostTracker.serialize()` byte-for-byte in shape:
+   * unset string fields serialize as null, `total_cost_usd` is null when no
+   * entry had a known cost, and a per-entry `total_tokens` of zero falls back
+   * to input + output.
+   */
+  serialize() {
+    const entries = [];
+    let totalInput = 0;
+    let totalOutput = 0;
+    let totalTokens = 0;
+    let totalCost = 0;
+    let anyCost = false;
+    for (const e of this.entries) {
+      const entryTotal = e.totalTokens || e.inputTokens + e.outputTokens;
+      entries.push({
+        source: e.source,
+        provider: e.provider,
+        model: e.model,
+        harness: e.harness,
+        reasoner: e.reasonerName,
+        input_tokens: e.inputTokens,
+        output_tokens: e.outputTokens,
+        cache_read_tokens: e.cacheReadTokens,
+        cache_creation_tokens: e.cacheCreationTokens,
+        total_tokens: entryTotal,
+        cost_usd: e.costUsd,
+        cost_source: e.costSource
+      });
+      totalInput += e.inputTokens;
+      totalOutput += e.outputTokens;
+      totalTokens += entryTotal;
+      if (e.costUsd !== null) {
+        totalCost += e.costUsd;
+        anyCost = true;
+      }
+    }
+    return {
+      total_cost_usd: anyCost ? round6(totalCost) : null,
+      total_input_tokens: totalInput,
+      total_output_tokens: totalOutput,
+      total_tokens: totalTokens,
+      entries
+    };
+  }
+  /** Clear all tracked entries. */
+  reset() {
+    this.entries = [];
+  }
+};
+function usageSummaryOrNull(tracker) {
+  if (!tracker || !tracker.hasEntries) return null;
+  return tracker.serialize();
+}
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function attachUsageToSyncResult(result, tracker) {
+  const usage = usageSummaryOrNull(tracker);
+  if (usage === null || !isPlainObject(result)) return result;
+  return { ...result, [USAGE_ENVELOPE_KEY]: usage };
+}
+
+// src/context/ExecutionContext.ts
 var store = new AsyncLocalStorage();
 var ExecutionContext = class {
   input;
@@ -1488,12 +1719,21 @@ var ExecutionContext = class {
   req;
   res;
   agent;
+  /**
+   * Per-execution LLM/harness usage accumulator. Each top-level execution
+   * binds a fresh tracker (isolated across concurrent executions via the
+   * AsyncLocalStorage this context lives in); nested local `agent.call()`
+   * executions inherit the parent's tracker so their usage rolls up into the
+   * parent's report.
+   */
+  costTracker;
   constructor(params) {
     this.input = params.input;
     this.metadata = params.metadata;
     this.req = params.req;
     this.res = params.res;
     this.agent = params.agent;
+    this.costTracker = params.costTracker ?? new CostTracker();
   }
   get logger() {
     return this.agent.getExecutionLogger();
@@ -1505,6 +1745,79 @@ var ExecutionContext = class {
     return store.getStore();
   }
 };
+
+// src/usage/aiUsage.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function num(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function extractTokenUsage(usage) {
+  if (!isRecord(usage)) {
+    return { inputTokens: 0, outputTokens: 0, totalTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 };
+  }
+  const inputDetails = isRecord(usage.inputTokenDetails) ? usage.inputTokenDetails : void 0;
+  return {
+    inputTokens: num(usage.inputTokens),
+    outputTokens: num(usage.outputTokens),
+    totalTokens: num(usage.totalTokens),
+    // `cachedInputTokens` is the deprecated pre-details alias — keep it as a
+    // fallback so older provider adapters still report cache reads.
+    cacheReadTokens: num(inputDetails?.cacheReadTokens) || num(usage.cachedInputTokens),
+    cacheCreationTokens: num(inputDetails?.cacheWriteTokens)
+  };
+}
+function costFromUsageRaw(usage) {
+  if (!isRecord(usage) || !isRecord(usage.raw)) return null;
+  const cost = usage.raw.cost;
+  return typeof cost === "number" && Number.isFinite(cost) && cost >= 0 ? cost : null;
+}
+function costFromProviderMetadata(providerMetadata) {
+  if (!isRecord(providerMetadata)) return null;
+  const openrouter = providerMetadata.openrouter;
+  if (!isRecord(openrouter) || !isRecord(openrouter.usage)) return null;
+  const cost = openrouter.usage.cost;
+  return typeof cost === "number" && Number.isFinite(cost) && cost >= 0 ? cost : null;
+}
+function extractProviderCostUsd(source) {
+  if (Array.isArray(source.steps) && source.steps.length > 0) {
+    let sum = 0;
+    let any = false;
+    for (const step of source.steps) {
+      const cost = costFromUsageRaw(isRecord(step) ? step.usage : void 0);
+      if (cost !== null) {
+        sum += cost;
+        any = true;
+      }
+    }
+    if (any) return sum;
+  }
+  return costFromUsageRaw(source.totalUsage) ?? costFromUsageRaw(source.usage) ?? costFromProviderMetadata(source.providerMetadata);
+}
+function recordAiSdkUsage(params) {
+  try {
+    const current = ExecutionContext.getCurrent();
+    const tracker = params.tracker ?? current?.costTracker;
+    if (!tracker) return;
+    const tokens = extractTokenUsage(params.source.totalUsage ?? params.source.usage);
+    const cost = extractProviderCostUsd(params.source);
+    const hasTokens = tokens.inputTokens > 0 || tokens.outputTokens > 0 || tokens.totalTokens > 0 || tokens.cacheReadTokens > 0 || tokens.cacheCreationTokens > 0;
+    if (!hasTokens && cost === null) return;
+    tracker.record({
+      model: params.model,
+      ...tokens,
+      costUsd: cost,
+      costSource: cost !== null ? "provider" : null,
+      reasonerName: params.reasonerName !== void 0 ? params.reasonerName : current?.metadata.reasonerId ?? null,
+      source: "llm",
+      provider: params.provider ?? void 0
+    });
+  } catch {
+  }
+}
+
+// src/ai/ToolCalling.ts
 var DEFAULT_MAX_TURNS = 10;
 var DEFAULT_MAX_TOOL_CALLS = 25;
 var DEFAULT_HEALTH_STATUS = void 0;
@@ -1722,9 +2035,15 @@ function wrapToolsWithObservability(toolMap, agent, trace, maxToolCalls, getCurr
   }
   return { tools: observableTools, getTotalCalls: () => totalCalls };
 }
-async function executeToolCallLoop(agent, prompt, toolMap, config, needsLazyHydration, buildModel, options = {}) {
+async function executeToolCallLoop(agent, prompt, toolMap, config, needsLazyHydration, buildModel, options = {}, modelChoice) {
   const maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS;
   const maxToolCalls = config.maxToolCalls ?? DEFAULT_MAX_TOOL_CALLS;
+  const usageModel = modelChoice?.modelName ?? options.model;
+  const recordLoopUsage = (result2) => {
+    if (usageModel) {
+      recordAiSdkUsage({ source: result2, model: usageModel, provider: modelChoice?.provider });
+    }
+  };
   const trace = {
     calls: [],
     totalTurns: 0,
@@ -1751,6 +2070,7 @@ async function executeToolCallLoop(agent, prompt, toolMap, config, needsLazyHydr
       stopWhen: stepCountIs(1)
       // Stop after LLM's first response (tool selection)
     });
+    recordLoopUsage(selectionResult);
     const selectedNames = /* @__PURE__ */ new Set();
     for (const step of selectionResult.steps) {
       for (const tc of step.toolCalls) {
@@ -1794,6 +2114,7 @@ async function executeToolCallLoop(agent, prompt, toolMap, config, needsLazyHydr
       trace.totalTurns = currentTurn;
     }
   });
+  recordLoopUsage(result);
   trace.finalResponse = result.text;
   trace.totalTurns = result.steps.length;
   return { text: result.text, trace };
@@ -1821,6 +2142,13 @@ var ReasonerContext = class {
   memory;
   workflow;
   did;
+  /**
+   * Per-execution token/cost usage accumulator. LLM calls made through
+   * `ctx.ai()` / `ctx.aiWithTools()` and harness runs record into it
+   * automatically; reasoner authors may also `record()` custom entries. Its
+   * serialized summary is attached to the execution's terminal report.
+   */
+  costTracker;
   /**
    * AbortSignal that fires when the control plane cancels this execution
    * (per-execution cancel, the bottom-up cancel-tree endpoint, or any
@@ -1830,6 +2158,12 @@ var ReasonerContext = class {
    * CPU loops, check `ctx.signal.aborted` periodically and throw.
    */
   signal;
+  /**
+   * Trigger context populated when the reasoner was invoked by an inbound
+   * webhook event or cron schedule. `undefined` for direct calls via
+   * `app.call(...)` or HTTP POST without a dispatcher envelope.
+   */
+  trigger;
   constructor(params) {
     this.input = params.input;
     this.executionId = params.executionId;
@@ -1852,6 +2186,8 @@ var ReasonerContext = class {
     this.workflow = params.workflow;
     this.did = params.did;
     this.signal = params.signal ?? new AbortController().signal;
+    this.costTracker = params.costTracker ?? ExecutionContext.getCurrent()?.costTracker ?? new CostTracker();
+    this.trigger = params.trigger;
   }
   ai(prompt, options) {
     if (options?.tools) {
@@ -1875,6 +2211,7 @@ var ReasonerContext = class {
       maxTurns: options.maxTurns ?? config.maxTurns ?? 10,
       maxToolCalls: options.maxToolCalls ?? config.maxToolCalls ?? 25
     };
+    const modelChoice = typeof this.aiClient.resolveModelChoice === "function" ? this.aiClient.resolveModelChoice(options) : void 0;
     return executeToolCallLoop(
       this.agent,
       prompt,
@@ -1882,7 +2219,8 @@ var ReasonerContext = class {
       mergedConfig,
       needsLazyHydration,
       () => this.aiClient.getModel(options),
-      options
+      options,
+      modelChoice
     );
   }
   aiStream(prompt, options) {
@@ -1947,7 +2285,8 @@ function getCurrentContext() {
     aiClient: agent.getAIClient(),
     memory: agent.getMemoryInterface(metadata),
     workflow: agent.getWorkflowReporter(metadata),
-    did: agent.getDidInterface(metadata, input)
+    did: agent.getDidInterface(metadata, input),
+    costTracker: execution.costTracker
   });
 }
 
@@ -2165,7 +2504,7 @@ var StatelessRateLimiter = class {
     }
   }
   async _sleep(delaySeconds) {
-    await new Promise((resolve2) => setTimeout(resolve2, delaySeconds * 1e3));
+    await new Promise((resolve3) => setTimeout(resolve3, delaySeconds * 1e3));
   }
   _now() {
     return Date.now() / 1e3;
@@ -2209,6 +2548,26 @@ function toError(error) {
 
 // src/ai/AIClient.ts
 init_openrouterAttribution();
+
+// src/ai/openrouterUsage.ts
+function withOpenRouterUsageInclude(baseFetch) {
+  return (input, init) => {
+    const impl = ((...args) => globalThis.fetch(...args));
+    try {
+      if (init && typeof init.body === "string") {
+        const parsed = JSON.parse(init.body);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) && parsed.usage === void 0) {
+          parsed.usage = { include: true };
+          return impl(input, { ...init, body: JSON.stringify(parsed) });
+        }
+      }
+    } catch {
+    }
+    return impl(input, init);
+  };
+}
+
+// src/ai/AIClient.ts
 function repairJsonText(text2) {
   let cleaned = text2.trim();
   const codeBlockMatch = cleaned.match(/```(?:json)?\s*([\s\S]*?)```/);
@@ -2243,6 +2602,7 @@ var AIClient = class {
     };
   }
   async generate(prompt, options = {}) {
+    const { provider, modelName } = this.resolveModelChoice(options);
     const model = this.buildModel(options);
     if (options.schema) {
       const schema = options.schema;
@@ -2257,6 +2617,7 @@ var AIClient = class {
         experimental_repairText: async ({ text: text2 }) => repairJsonText(text2)
       });
       const response2 = await this.withRateLimitRetry(call2);
+      recordAiSdkUsage({ source: response2, model: modelName, provider });
       return response2.object;
     }
     const call = async () => generateText({
@@ -2267,8 +2628,13 @@ var AIClient = class {
       maxOutputTokens: options.maxTokens ?? this.config.maxTokens
     });
     const response = await this.withRateLimitRetry(call);
+    recordAiSdkUsage({ source: response, model: modelName, provider });
     return response.text;
   }
+  // NOTE: stream() usage is deliberately NOT captured. The AI SDK's
+  // streamResult.usage/.totalUsage promises "automatically consume the
+  // stream": attaching to them would force full background consumption of a
+  // stream the caller may abandon early, changing stream semantics.
   async stream(prompt, options = {}) {
     const model = this.buildModel(options);
     const streamResult = streamText({
@@ -2307,9 +2673,19 @@ var AIClient = class {
   getModel(options = {}) {
     return this.buildModel(options);
   }
+  /**
+   * Resolve the effective provider/model pair for a request without building
+   * the model. Used by usage tracking to attribute token/cost entries to the
+   * model actually called.
+   */
+  resolveModelChoice(options = {}) {
+    return {
+      provider: options.provider ?? this.config.provider ?? "openai",
+      modelName: options.model ?? this.config.model ?? "gpt-4o"
+    };
+  }
   buildModel(options) {
-    const provider = options.provider ?? this.config.provider ?? "openai";
-    const modelName = options.model ?? this.config.model ?? "gpt-4o";
+    const { provider, modelName } = this.resolveModelChoice(options);
     const openRouterHeaders = this.openRouterHeaders(provider, modelName);
     switch (provider) {
       case "anthropic": {
@@ -2365,7 +2741,8 @@ var AIClient = class {
         const openrouter = createOpenAI({
           apiKey: this.config.apiKey,
           baseURL: this.config.baseUrl ?? "https://openrouter.ai/api/v1",
-          headers: openRouterHeaders
+          headers: openRouterHeaders,
+          fetch: withOpenRouterUsageInclude()
         });
         return openrouter.chat(modelName);
       }
@@ -2382,7 +2759,7 @@ var AIClient = class {
         const openai = createOpenAI({
           apiKey: this.config.apiKey,
           baseURL: this.config.baseUrl,
-          ...openRouterHeaders ? { headers: openRouterHeaders } : {}
+          ...openRouterHeaders ? { headers: openRouterHeaders, fetch: withOpenRouterUsageInclude() } : {}
         });
         return openai(modelName);
       }
@@ -3088,6 +3465,7 @@ var AgentFieldClient = class {
     if (payload.result !== void 0) body.result = wrapResult(payload.result);
     if (payload.error !== void 0) body.error = payload.error;
     if (payload.errorDetails !== void 0) body.error_details = payload.errorDetails;
+    if (payload.usage !== void 0) body.usage = payload.usage;
     const bodyStr = JSON.stringify(body);
     const authHeaders = this.didAuthenticator.signRequest(Buffer.from(bodyStr));
     for (let attempt = 0; attempt < maxRetries; attempt++) {
@@ -3289,7 +3667,7 @@ var AgentFieldClient = class {
   }
 };
 function sleep2(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 async function safePauseCallback(cb) {
   if (!cb) return;
@@ -4748,6 +5126,44 @@ var Agent = class {
     }
     return this;
   }
+  /**
+   * Sugar for registering an event-triggered reasoner.
+   *
+   * Equivalent to:
+   * ```ts
+   * app.reasoner(name, handler, { triggers: [eventTrigger(spec)] });
+   * ```
+   *
+   * The reasoner name defaults to `handler.name` when not provided.
+   */
+  onEvent(spec, handler, options) {
+    const name = spec.name || handler.name || `on_${spec.source}`;
+    const { name: _discarded, ...triggerSpec } = spec;
+    const binding = eventTrigger(triggerSpec);
+    return this.reasoner(name, handler, {
+      ...options,
+      triggers: [...options?.triggers ?? [], binding]
+    });
+  }
+  /**
+   * Sugar for registering a schedule-triggered (cron) reasoner.
+   *
+   * Equivalent to:
+   * ```ts
+   * app.reasoner(name, handler, { triggers: [scheduleTrigger({ cron })] });
+   * ```
+   *
+   * The reasoner name defaults to `handler.name` when not provided.
+   */
+  onSchedule(cron, handler, options) {
+    const name = options?.name || handler.name || "on_schedule";
+    const binding = scheduleTrigger({ cron, timezone: options?.timezone });
+    const { name: _discarded, timezone: _tz, ...restOptions } = options ?? {};
+    return this.reasoner(name, handler, {
+      ...restOptions,
+      triggers: [...restOptions?.triggers ?? [], binding]
+    });
+  }
   skill(name, handler, options) {
     this.skills.register(name, handler, options);
     if (options?.requireRealtimeValidation) {
@@ -4801,7 +5217,53 @@ var Agent = class {
   }
   async harness(prompt, options) {
     const runner = await this.getHarnessRunner();
-    return runner.run(prompt, options ?? {});
+    const result = await runner.run(prompt, options ?? {});
+    this.recordHarnessUsage(result, options);
+    return result;
+  }
+  /**
+   * Record a harness run's token/cost usage into the current execution's
+   * tracker. Mirrors the Python SDK's `_record_harness_usage`: a no-op when
+   * the harness reported neither tokens nor cost (the common case for
+   * providers that don't expose usage) so empty entries are never emitted;
+   * cost is threaded even when tokens are unknown, and vice versa. Never
+   * throws — usage capture is best-effort.
+   */
+  recordHarnessUsage(result, options) {
+    try {
+      const current = ExecutionContext.getCurrent();
+      const tracker = current?.costTracker;
+      if (!tracker) return;
+      const inputTokens = result.inputTokens ?? 0;
+      const outputTokens = result.outputTokens ?? 0;
+      const cacheRead = result.cacheReadTokens ?? 0;
+      const cacheCreation = result.cacheCreationTokens ?? 0;
+      const reportedTotal = result.totalTokens ?? 0;
+      const cost = typeof result.costUsd === "number" && Number.isFinite(result.costUsd) ? result.costUsd : null;
+      if (!inputTokens && !outputTokens && !cacheRead && !cacheCreation && !reportedTotal && cost === null) {
+        return;
+      }
+      const providerName = options?.provider ?? this.config.harnessConfig?.provider;
+      const harnessName = providerName ? String(providerName).replace(/-/g, "_") : null;
+      const modelName = String(
+        result.model ?? options?.model ?? this.config.harnessConfig?.model ?? providerName ?? "harness"
+      );
+      tracker.record({
+        model: modelName,
+        inputTokens,
+        outputTokens,
+        totalTokens: reportedTotal || inputTokens + outputTokens,
+        costUsd: cost,
+        reasonerName: current.metadata.reasonerId ?? null,
+        source: "harness",
+        provider: deriveProvider(modelName),
+        harness: harnessName,
+        cacheReadTokens: cacheRead,
+        cacheCreationTokens: cacheCreation,
+        costSource: cost !== null ? "provider" : null
+      });
+    } catch {
+    }
   }
   getMemoryInterface(metadata) {
     const defaultScope = this.config.memoryConfig?.defaultScope ?? "workflow";
@@ -4918,9 +5380,9 @@ var Agent = class {
     try {
       const result = await Promise.race([
         future,
-        new Promise((resolve2) => {
+        new Promise((resolve3) => {
           timer = setTimeout(() => {
-            resolve2(
+            resolve3(
               new ApprovalResult({
                 decision: "expired",
                 feedback: "timed out waiting for approval",
@@ -4973,8 +5435,8 @@ var Agent = class {
     const port = this.config.port ?? 8001;
     const host = this.config.host ?? "0.0.0.0";
     await this.agentFieldClient.heartbeat("starting");
-    await new Promise((resolve2, reject) => {
-      this.server = this.app.listen(port, host, () => resolve2()).on("error", reject);
+    await new Promise((resolve3, reject) => {
+      this.server = this.app.listen(port, host, () => resolve3()).on("error", reject);
     });
     this.memoryEventClient.start();
     this.startHeartbeat();
@@ -4984,20 +5446,27 @@ var Agent = class {
       clearInterval(this.heartbeatTimer);
     }
     this.pauseManager.cancelAll();
-    await new Promise((resolve2, reject) => {
+    await new Promise((resolve3, reject) => {
       this.server?.close((err) => {
         if (err) reject(err);
-        else resolve2();
+        else resolve3();
       });
     });
     this.memoryEventClient.stop();
   }
   async call(target, input) {
     const { agentId, name } = this.parseTarget(target);
-    const parentMetadata = ExecutionContext.getCurrent()?.metadata;
+    const parentContext = ExecutionContext.getCurrent();
+    const parentMetadata = parentContext?.metadata;
     if (!agentId || agentId === this.config.nodeId) {
       const local = this.reasoners.get(name);
       if (!local) throw new Error(`Reasoner not found: ${name}`);
+      const { input: unwrappedInput, triggerContext } = unwrapEnvelope(input);
+      let resolvedInput = unwrappedInput;
+      if (triggerContext) {
+        const bindings = local.options?.triggers ?? [];
+        resolvedInput = applyTriggerTransform(triggerContext, bindings, unwrappedInput);
+      }
       const runId2 = parentMetadata?.runId ?? parentMetadata?.executionId ?? randomUUID();
       const rootWorkflowId2 = parentMetadata?.rootWorkflowId ?? parentMetadata?.workflowId ?? runId2;
       const metadata = {
@@ -5012,14 +5481,18 @@ var Agent = class {
       const dummyReq = {};
       const dummyRes = {};
       const execCtx = new ExecutionContext({
-        input,
+        input: resolvedInput,
         metadata: {
           ...metadata,
           executionId: metadata.executionId ?? randomUUID()
         },
         req: dummyReq,
         res: dummyRes,
-        agent: this
+        agent: this,
+        // Nested local calls inherit the parent's cost tracker so their LLM /
+        // harness usage rolls up into the parent execution's usage report
+        // (entries still carry the child reasoner's name).
+        costTracker: parentContext?.costTracker
       });
       const startTime = Date.now();
       this.executionLogger.system("agent.call.started", "Local agent call started", {
@@ -5069,7 +5542,7 @@ var Agent = class {
         try {
           const result = await local.handler(
             new ReasonerContext({
-              input,
+              input: resolvedInput,
               executionId: execCtx.metadata.executionId,
               runId: execCtx.metadata.runId,
               sessionId: execCtx.metadata.sessionId,
@@ -5088,7 +5561,9 @@ var Agent = class {
               aiClient: this.aiClient,
               memory: this.getMemoryInterface(execCtx.metadata),
               workflow: this.getWorkflowReporter(execCtx.metadata),
-              did: this.getDidInterface(execCtx.metadata, input, name)
+              did: this.getDidInterface(execCtx.metadata, resolvedInput, name),
+              trigger: triggerContext,
+              costTracker: execCtx.costTracker
             })
           );
           this.executionLogger.system("reasoner.completed", "Reasoner execution completed", {
@@ -5790,6 +6265,8 @@ var Agent = class {
     watchdog.catch(() => {
     });
     const completedAt = () => (/* @__PURE__ */ new Date()).toISOString();
+    const usageTracker = new CostTracker();
+    const usage = () => usageSummaryOrNull(usageTracker) ?? void 0;
     try {
       const result = await Promise.race([
         this.runReasoner(reasoner, {
@@ -5797,7 +6274,8 @@ var Agent = class {
           input: params.input,
           metadata: params.metadata,
           respond: false,
-          controller
+          controller,
+          costTracker: usageTracker
         }),
         watchdog
       ]);
@@ -5806,7 +6284,8 @@ var Agent = class {
         result,
         durationMs: Date.now() - start,
         completedAt: completedAt(),
-        reasoner: reasonerName
+        reasoner: reasonerName,
+        usage: usage()
       });
     } catch (err) {
       const durationMs = Date.now() - start;
@@ -5817,7 +6296,8 @@ var Agent = class {
           errorDetails: { reason: "reasoner_timeout" },
           durationMs,
           completedAt: completedAt(),
-          reasoner: reasonerName
+          reasoner: reasonerName,
+          usage: usage()
         });
       } else if (controller.signal.aborted) {
         await this.agentFieldClient.reportExecutionResult(executionId, {
@@ -5826,7 +6306,8 @@ var Agent = class {
           errorDetails: { reason: "cancelled" },
           durationMs,
           completedAt: completedAt(),
-          reasoner: reasonerName
+          reasoner: reasonerName,
+          usage: usage()
         });
       } else {
         await this.agentFieldClient.reportExecutionResult(executionId, {
@@ -5835,7 +6316,8 @@ var Agent = class {
           errorDetails: err?.responseData,
           durationMs,
           completedAt: completedAt(),
-          reasoner: reasonerName
+          reasoner: reasonerName,
+          usage: usage()
         });
       }
     } finally {
@@ -5851,12 +6333,20 @@ var Agent = class {
       rootWorkflowId: params.metadata.rootWorkflowId ?? params.metadata.workflowId ?? params.metadata.runId ?? params.metadata.executionId,
       reasonerId: params.metadata.reasonerId ?? params.targetName
     };
+    const costTracker = params.costTracker ?? new CostTracker();
+    const { input: unwrappedInput, triggerContext } = unwrapEnvelope(params.input);
+    let resolvedInput = unwrappedInput;
+    if (triggerContext) {
+      const bindings = reasoner.options?.triggers ?? [];
+      resolvedInput = applyTriggerTransform(triggerContext, bindings, unwrappedInput);
+    }
     const execCtx = new ExecutionContext({
-      input: params.input,
+      input: resolvedInput,
       metadata: executionMetadata,
       req,
       res,
-      agent: this
+      agent: this,
+      costTracker
     });
     const { controller, release } = this.cancelRegistry.register(
       executionMetadata.executionId,
@@ -5881,7 +6371,7 @@ var Agent = class {
       });
       try {
         const ctx = new ReasonerContext({
-          input: params.input,
+          input: resolvedInput,
           executionId: executionMetadata.executionId,
           runId: executionMetadata.runId,
           sessionId: executionMetadata.sessionId,
@@ -5900,8 +6390,10 @@ var Agent = class {
           aiClient: this.aiClient,
           memory: this.getMemoryInterface(executionMetadata),
           workflow: this.getWorkflowReporter(executionMetadata),
-          did: this.getDidInterface(executionMetadata, params.input, params.targetName),
-          signal: controller.signal
+          did: this.getDidInterface(executionMetadata, resolvedInput, params.targetName),
+          signal: controller.signal,
+          trigger: triggerContext,
+          costTracker
         });
         const result = await reasoner.handler(ctx);
         this.executionLogger.system("reasoner.completed", "Reasoner execution completed", {
@@ -5920,7 +6412,7 @@ var Agent = class {
           rootWorkflowId: executionMetadata.rootWorkflowId
         });
         if (params.respond && params.res) {
-          params.res.json(result);
+          params.res.json(attachUsageToSyncResult(result, costTracker));
           return;
         }
         return result;
@@ -6146,7 +6638,7 @@ var Agent = class {
     const timeoutMs = 5 * 60 * 1e3;
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-      await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
+      await new Promise((resolve3) => setTimeout(resolve3, pollInterval));
       try {
         const node = await this.agentFieldClient.getNode(this.config.nodeId);
         const status = node?.lifecycle_status;
@@ -7575,14 +8067,62 @@ var OpenRouterMediaProvider = class {
   }
 };
 function sleep3(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 
 // src/harness/index.ts
 init_types();
 init_factory();
 init_runner();
+async function simulateTrigger(handler, options) {
+  const body = options.body ?? {};
+  const triggerContext = {
+    triggerId: options.triggerId ?? `trg_sim_${randomUUID().slice(0, 12)}`,
+    source: options.source,
+    eventType: options.eventType ?? "",
+    eventId: options.eventId ?? `evt_sim_${randomUUID().slice(0, 12)}`,
+    idempotencyKey: options.idempotencyKey ?? `idem_sim_${randomUUID().slice(0, 12)}`,
+    receivedAt: options.receivedAt ?? /* @__PURE__ */ new Date(),
+    vcId: options.vcId
+  };
+  let resolvedInput = body;
+  if (options.bindings && options.bindings.length > 0) {
+    resolvedInput = applyTriggerTransform(triggerContext, options.bindings, body);
+  }
+  const ctx = {
+    input: resolvedInput,
+    trigger: triggerContext,
+    executionId: `exec_sim_${randomUUID().slice(0, 12)}`
+  };
+  return handler(ctx);
+}
+async function simulateSchedule(handler, options) {
+  return simulateTrigger(handler, {
+    source: "cron",
+    body: options?.cron ? { cron: options.cron } : {},
+    eventType: "tick",
+    receivedAt: options?.receivedAt,
+    bindings: options?.bindings
+  });
+}
+function loadFixture(source) {
+  const dir = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    resolve(dir, "fixtures", `${source}.json`),
+    resolve(dir, "..", "src", "triggers", "fixtures", `${source}.json`)
+  ];
+  for (const fixturePath of candidates) {
+    try {
+      const content = readFileSync(fixturePath, "utf-8");
+      return JSON.parse(content);
+    } catch {
+    }
+  }
+  throw new Error(
+    `No fixture for source="${source}". Looked at ${candidates.join(", ")}`
+  );
+}
 
-export { ACTIVE_STATUSES, AIClient, Agent, AgentRouter, ApprovalClient, ApprovalResult, Audio, CANONICAL_STATUSES, DIDAuthenticator, DidClient, DidInterface, DidManager, ExecutionContext, ExecutionLogger, ExecutionStatus, File, HEADER_CALLER_DID, HEADER_DID_NONCE, HEADER_DID_SIGNATURE, HEADER_DID_TIMESTAMP, HarnessRunner, Image, JWE_ALG, JWE_ENC, KEY_AGREEMENT_TYPE, MediaProviderError, MediaRouter, MemoryClient, MemoryClientBase, MemoryEventClient, MemoryInterface, MultimodalResponse, OpenRouterMediaProvider, PauseClock, PauseManager, PayloadEncryptionError, RateLimitError, RealtimeSession, ReasonerContext, SUPPORTED_PROVIDERS, SUPPORTED_SESSION_TRANSPORTS, SessionTransportError, SkillContext, StatelessRateLimiter, TERMINAL_STATUSES, Text, Video, WorkflowReporter, audioFromBase64, audioFromBuffer, audioFromFile, audioFromUrl, buildProvider, buildSessionDefinition, buildToolConfig, capabilitiesToTools, capabilityToMetadataTool, capabilityToTool, createExecutionLogger, createHarnessResult, createMetrics, createMultimodalResponse, createRawResult, decrypt, decryptToString, encryptForDid, encryptToJwk, eventTrigger, executeToolCallLoop, extractKeyAgreementJwk, fileFromBase64, fileFromBuffer, fileFromPath, fileFromUrl, generateX25519KeyPair, getCurrentContext, getCurrentSkillContext, imageFromBase64, imageFromBuffer, imageFromFile, imageFromUrl, installApprovalWebhookRoute, isActive, isExecutionLogBatchPayload, isTerminal, normalizeExecutionLogEntry, normalizeSessionTransportValue, normalizeStatus, scheduleTrigger, serializeExecutionLogEntry, text, triggerToPayload, validateSessionTransport, videoFromBase64, videoFromBuffer, videoFromFile, videoFromUrl };
+export { ACTIVE_STATUSES, AIClient, Agent, AgentRouter, ApprovalClient, ApprovalResult, Audio, CANONICAL_STATUSES, CostTracker, DIDAuthenticator, DidClient, DidInterface, DidManager, ExecutionContext, ExecutionLogger, ExecutionStatus, File, HEADER_CALLER_DID, HEADER_DID_NONCE, HEADER_DID_SIGNATURE, HEADER_DID_TIMESTAMP, HarnessRunner, Image, JWE_ALG, JWE_ENC, KEY_AGREEMENT_TYPE, MediaProviderError, MediaRouter, MemoryClient, MemoryClientBase, MemoryEventClient, MemoryInterface, MultimodalResponse, OpenRouterMediaProvider, PauseClock, PauseManager, PayloadEncryptionError, RateLimitError, RealtimeSession, ReasonerContext, SUPPORTED_PROVIDERS, SUPPORTED_SESSION_TRANSPORTS, SessionTransportError, SkillContext, StatelessRateLimiter, TERMINAL_STATUSES, Text, USAGE_ENVELOPE_KEY, Video, WorkflowReporter, applyTriggerTransform, attachUsageToSyncResult, audioFromBase64, audioFromBuffer, audioFromFile, audioFromUrl, buildProvider, buildSessionDefinition, buildToolConfig, capabilitiesToTools, capabilityToMetadataTool, capabilityToTool, createExecutionLogger, createHarnessResult, createMetrics, createMultimodalResponse, createRawResult, decrypt, decryptToString, deriveProvider, encryptForDid, encryptToJwk, eventTrigger, executeToolCallLoop, extractKeyAgreementJwk, fileFromBase64, fileFromBuffer, fileFromPath, fileFromUrl, generateX25519KeyPair, getCurrentContext, getCurrentSkillContext, imageFromBase64, imageFromBuffer, imageFromFile, imageFromUrl, installApprovalWebhookRoute, isActive, isExecutionLogBatchPayload, isTerminal, isTriggerEnvelope, loadFixture, normalizeExecutionLogEntry, normalizeSessionTransportValue, normalizeStatus, scheduleTrigger, serializeExecutionLogEntry, simulateSchedule, simulateTrigger, text, triggerToPayload, unwrapEnvelope, usageSummaryOrNull, validateSessionTransport, videoFromBase64, videoFromBuffer, videoFromFile, videoFromUrl };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map