@granular-software/sdk 0.4.37 → 0.4.38

package/dist/agent-evals.mjs

@@ -1,5 +1,6 @@
 import { writeFile, mkdir } from 'fs/promises';
 import path from 'path';
+import OpenAI from 'openai';
 import * as Automerge from '@automerge/automerge';
 
 var __create = Object.create;
@@ -4618,6 +4619,7 @@ function withPromptTranscriptTimeout(promise) {
 var Session = class {
   client;
   clientId;
+  initialQuota;
   jobsMap = /* @__PURE__ */ new Map();
   pendingAgentMessagesByJobId = /* @__PURE__ */ new Map();
   eventListeners = /* @__PURE__ */ new Map();
@@ -4633,9 +4635,10 @@ var Session = class {
   promptCache = /* @__PURE__ */ new Map();
   /** Prompt ids locally answered before the document sync catches up. */
   hiddenPromptIds = /* @__PURE__ */ new Set();
-  constructor(client, clientId) {
+  constructor(client, clientId, options = {}) {
     this.client = client;
     this.clientId = clientId || `client_${Date.now()}`;
+    this.initialQuota = options.initialQuota || null;
     this.setupEventHandlers();
     this.setupToolInvokeHandler();
   }
@@ -4684,6 +4687,16 @@ var Session = class {
   get document() {
     return this.client.doc;
   }
+  get quota() {
+    return this.getQuota();
+  }
+  getQuota() {
+    const quota = this.client.doc.billing?.quota;
+    if (quota && typeof quota === "object") {
+      return quota;
+    }
+    return this.initialQuota;
+  }
   get sessionId() {
     return this.client.currentSessionId;
   }
@@ -11306,6 +11319,110 @@ async function invokeRegisteredEffect(effectMap, request) {
   return resolved.handler(request.input, context);
 }
 
+// src/spend.ts
+function toGranularHttpBase(apiUrl) {
+  const url = new URL(apiUrl);
+  if (url.protocol === "ws:") {
+    url.protocol = "http:";
+  } else if (url.protocol === "wss:") {
+    url.protocol = "https:";
+  }
+  url.pathname = url.pathname.replace(/\/ws\/connect$/, "").replace(/\/ws$/, "");
+  if (!url.pathname || url.pathname === "/") {
+    url.pathname = "/granular";
+  }
+  url.search = "";
+  url.hash = "";
+  return url.toString().replace(/\/$/, "");
+}
+function cleanIdPart(value) {
+  return value.replace(/[^a-zA-Z0-9_-]+/g, "_").replace(/^_+|_+$/g, "");
+}
+function buildOpenAISpendEventId(usage, context = {}) {
+  const requestId = usage.requestId?.trim();
+  if (!requestId) return void 0;
+  const scope = context.sessionId || context.environmentId || context.subjectId || context.sandboxId || "global";
+  return ["spend", "openai", scope, requestId].map(cleanIdPart).join("_");
+}
+function pricingEffectiveAtSeconds(value) {
+  if (!value) return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? Math.floor(parsed / 1e3) : null;
+}
+function compactContext(context) {
+  return Object.fromEntries(
+    Object.entries(context).filter(
+      ([, value]) => value != null && value !== ""
+    )
+  );
+}
+function omitTenantId(context) {
+  const scopedContext = { ...context };
+  delete scopedContext.tenantId;
+  return scopedContext;
+}
+async function recordOpenAIUsageSpend(options) {
+  const usageContext = compactContext({
+    ...options.usage.usageContext || {},
+    ...options.context || {}
+  });
+  const context = omitTenantId(usageContext);
+  const spendEventId = options.usage.spendEventId || buildOpenAISpendEventId(options.usage, context);
+  const metadata = {
+    ...options.metadata || {},
+    ...options.usage.rawUsage !== void 0 ? { openaiUsage: options.usage.rawUsage } : {},
+    usageContext: context
+  };
+  const response = await fetch(
+    `${toGranularHttpBase(options.apiUrl)}/control/spend/events`,
+    {
+      method: "POST",
+      cache: "no-store",
+      headers: {
+        Authorization: `Bearer ${options.token}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        ...spendEventId ? { spendEventId } : {},
+        sandboxId: context.sandboxId || null,
+        environmentId: context.environmentId || null,
+        sessionId: context.sessionId || null,
+        subjectId: context.subjectId || null,
+        permissionProfileId: context.permissionProfileId || null,
+        source: "openai",
+        lineItemType: "llm_tokens",
+        provider: options.usage.provider,
+        model: options.usage.model,
+        operation: options.usage.operation || "chat.completions",
+        requestId: options.usage.requestId || null,
+        inputTokens: options.usage.inputTokens,
+        outputTokens: options.usage.outputTokens,
+        cachedInputTokens: options.usage.cachedInputTokens,
+        reasoningTokens: options.usage.reasoningTokens,
+        quantity: options.usage.totalTokens,
+        quantityUnit: "tokens",
+        inputPricePerMillionMicros: options.usage.inputPricePerMillionMicros,
+        cachedInputPricePerMillionMicros: options.usage.cachedInputPricePerMillionMicros,
+        outputPricePerMillionMicros: options.usage.outputPricePerMillionMicros,
+        amountMicros: options.usage.amountMicros,
+        currency: options.usage.currency,
+        pricingSource: options.usage.pricingSource,
+        pricingEffectiveAt: pricingEffectiveAtSeconds(
+          options.usage.pricingEffectiveAt
+        ),
+        estimated: false,
+        metadata
+      })
+    }
+  );
+  if (!response.ok) {
+    throw new Error(
+      `Granular spend event failed (${response.status}): ${await response.text()}`
+    );
+  }
+  return response.json();
+}
+
 // ../metamodel-enum/src/index.ts
 function renderInlineStringUnion(values) {
   return values.map((value) => JSON.stringify(value)).join(" | ");
@@ -14088,7 +14205,7 @@ var EnvironmentSession = class extends Session {
   /** The last known graph container status, updated by checkReadiness() or on heartbeat */
   graphContainerStatus = null;
   constructor(client, environment, clientId, options = {}) {
-    super(client, clientId);
+    super(client, clientId, { initialQuota: options.initialQuota });
     this.environment = environment;
     this.sessionDataRoutePrefix = options.sessionDataRoutePrefix || "/orchestrator/ws/sessions";
   }
@@ -14887,6 +15004,15 @@ var Granular = class _Granular {
     const environment = this.bindEnvironmentHandle(envData);
     return this.bindWebSocketEnvironmentSession(environment, clientId, minted);
   }
+  async recordOpenAIUsageSpend(usage, context, options) {
+    return recordOpenAIUsageSpend({
+      apiUrl: this.apiUrl,
+      token: this.apiKey,
+      usage,
+      context,
+      metadata: options?.metadata
+    });
+  }
   /**
    * Mark a session closed in the control plane. If `environment` is the connected handle for that
    * `sessionId`, disconnects the WebSocket so the runtime tears down cleanly.
@@ -15041,7 +15167,8 @@ var Granular = class _Granular {
     const environmentSession = new EnvironmentSession(
       client,
       environment,
-      clientId
+      clientId,
+      { initialQuota: session.quota || null }
     );
     await environmentSession.hello();
     return environmentSession;
@@ -17250,12 +17377,107 @@ ${knownFactsBlock}
 ${input.request?.trim() || "Use the latest user message in the conversation."}`;
 }
 
+// src/openai-usage.ts
+var OPENAI_PRICING_SOURCE_URL = "https://developers.openai.com/api/docs/models/gpt-5.4/";
+var OPENAI_PRICING_EFFECTIVE_DATE = "2026-05-19";
+var OPENAI_MODEL_PRICING_USD_PER_MILLION = {
+  "gpt-5.4": {
+    provider: "openai",
+    model: "gpt-5.4",
+    currency: "USD",
+    inputUsdPerMillion: 2.5,
+    cachedInputUsdPerMillion: 0.25,
+    outputUsdPerMillion: 15,
+    sourceUrl: OPENAI_PRICING_SOURCE_URL,
+    effectiveDate: OPENAI_PRICING_EFFECTIVE_DATE
+  }
+};
+function asRecord5(value) {
+  return value && typeof value === "object" ? value : null;
+}
+function numberField(record, key) {
+  const value = record?.[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function microsPerMillion(usdPerMillion) {
+  return Math.round(usdPerMillion * 1e6);
+}
+function getOpenAIModelPricing(model) {
+  return OPENAI_MODEL_PRICING_USD_PER_MILLION[model] || null;
+}
+function normalizeOpenAIUsage(rawUsage) {
+  const usage = asRecord5(rawUsage);
+  if (!usage) {
+    return {
+      inputTokens: 0,
+      cachedInputTokens: 0,
+      uncachedInputTokens: 0,
+      outputTokens: 0,
+      reasoningTokens: 0,
+      totalTokens: 0
+    };
+  }
+  const inputTokens = numberField(usage, "prompt_tokens") || numberField(usage, "input_tokens");
+  const outputTokens = numberField(usage, "completion_tokens") || numberField(usage, "output_tokens");
+  const totalTokens = numberField(usage, "total_tokens") || inputTokens + outputTokens;
+  const inputDetails = asRecord5(usage.prompt_tokens_details) || asRecord5(usage.input_tokens_details);
+  const outputDetails = asRecord5(usage.completion_tokens_details) || asRecord5(usage.output_tokens_details);
+  const cachedInputTokens = Math.min(
+    inputTokens,
+    numberField(inputDetails, "cached_tokens") || numberField(inputDetails, "cached_input_tokens")
+  );
+  const reasoningTokens = numberField(outputDetails, "reasoning_tokens") || numberField(outputDetails, "reasoning_output_tokens");
+  return {
+    inputTokens,
+    cachedInputTokens,
+    uncachedInputTokens: Math.max(inputTokens - cachedInputTokens, 0),
+    outputTokens,
+    reasoningTokens,
+    totalTokens
+  };
+}
+function calculateOpenAITokenSpend(model, rawUsage) {
+  const pricing = getOpenAIModelPricing(model);
+  if (!pricing) return null;
+  const usage = normalizeOpenAIUsage(rawUsage);
+  const inputPricePerMillionMicros = microsPerMillion(
+    pricing.inputUsdPerMillion
+  );
+  const cachedInputPricePerMillionMicros = microsPerMillion(
+    pricing.cachedInputUsdPerMillion
+  );
+  const outputPricePerMillionMicros = microsPerMillion(
+    pricing.outputUsdPerMillion
+  );
+  const amountMicros = Math.round(
+    (usage.uncachedInputTokens * inputPricePerMillionMicros + usage.cachedInputTokens * cachedInputPricePerMillionMicros + usage.outputTokens * outputPricePerMillionMicros) / 1e6
+  );
+  return {
+    provider: "openai",
+    model,
+    inputTokens: usage.inputTokens,
+    cachedInputTokens: usage.cachedInputTokens,
+    uncachedInputTokens: usage.uncachedInputTokens,
+    outputTokens: usage.outputTokens,
+    reasoningTokens: usage.reasoningTokens,
+    totalTokens: usage.totalTokens,
+    amountMicros,
+    currency: "USD",
+    inputPricePerMillionMicros,
+    cachedInputPricePerMillionMicros,
+    outputPricePerMillionMicros,
+    pricingSource: pricing.sourceUrl,
+    pricingEffectiveAt: pricing.effectiveDate,
+    usage
+  };
+}
+
 // src/agent-evals.ts
 var DEFAULT_CONTROLLER_BUDGETS = {
   maxIterations: 6,
   maxNoProgressIterations: 2
 };
-function asRecord5(value) {
+function asRecord6(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   return value;
 }
@@ -17308,9 +17530,9 @@ function asArray3(value) {
   return Array.isArray(value) ? value : [value];
 }
 var GPT_54_TOKEN_PRICING_USD_PER_MILLION = {
-  input: 0.75,
-  cachedInput: 0.075,
-  output: 4.5
+  input: 2.5,
+  cachedInput: 0.25,
+  output: 15
 };
 function emptyTokenUsage() {
   return {
@@ -17327,14 +17549,24 @@ function emptyTokenUsage() {
     missingUsageCalls: 0
   };
 }
-function numberField(record, key) {
+function numberField2(record, key) {
   const value = record?.[key];
   return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 function calculateTokenCost(input) {
-  const inputCostUsd = input.uncachedInputTokens * GPT_54_TOKEN_PRICING_USD_PER_MILLION.input / 1e6;
-  const cachedInputCostUsd = input.cachedInputTokens * GPT_54_TOKEN_PRICING_USD_PER_MILLION.cachedInput / 1e6;
-  const outputCostUsd = input.outputTokens * GPT_54_TOKEN_PRICING_USD_PER_MILLION.output / 1e6;
+  const spend = input.model ? calculateOpenAITokenSpend(input.model, {
+    input_tokens: input.uncachedInputTokens + input.cachedInputTokens,
+    output_tokens: input.outputTokens,
+    input_tokens_details: { cached_tokens: input.cachedInputTokens }
+  }) : null;
+  const pricing = spend ? {
+    input: spend.inputPricePerMillionMicros / 1e6,
+    cachedInput: spend.cachedInputPricePerMillionMicros / 1e6,
+    output: spend.outputPricePerMillionMicros / 1e6
+  } : GPT_54_TOKEN_PRICING_USD_PER_MILLION;
+  const inputCostUsd = input.uncachedInputTokens * pricing.input / 1e6;
+  const cachedInputCostUsd = input.cachedInputTokens * pricing.cachedInput / 1e6;
+  const outputCostUsd = input.outputTokens * pricing.output / 1e6;
   return {
     inputCostUsd,
     cachedInputCostUsd,
@@ -17343,18 +17575,20 @@ function calculateTokenCost(input) {
   };
 }
 function extractTokenUsageFromRaw(raw) {
-  const usage = asRecord5(asRecord5(raw)?.usage);
+  const usage = asRecord6(asRecord6(raw)?.usage);
   if (!usage) return null;
-  const inputTokens = numberField(usage, "prompt_tokens") || numberField(usage, "input_tokens");
-  const outputTokens = numberField(usage, "completion_tokens") || numberField(usage, "output_tokens");
-  const details = asRecord5(usage.prompt_tokens_details) || asRecord5(usage.input_tokens_details);
+  const model = typeof asRecord6(raw)?.model === "string" ? asRecord6(raw)?.model : void 0;
+  const inputTokens = numberField2(usage, "prompt_tokens") || numberField2(usage, "input_tokens");
+  const outputTokens = numberField2(usage, "completion_tokens") || numberField2(usage, "output_tokens");
+  const details = asRecord6(usage.prompt_tokens_details) || asRecord6(usage.input_tokens_details);
   const cachedInputTokens = Math.min(
     inputTokens,
-    numberField(details, "cached_tokens") || numberField(details, "cached_input_tokens")
+    numberField2(details, "cached_tokens") || numberField2(details, "cached_input_tokens")
   );
   const uncachedInputTokens = Math.max(inputTokens - cachedInputTokens, 0);
-  const totalTokens = numberField(usage, "total_tokens") || inputTokens + outputTokens;
+  const totalTokens = numberField2(usage, "total_tokens") || inputTokens + outputTokens;
   const costs = calculateTokenCost({
+    model,
     uncachedInputTokens,
     cachedInputTokens,
     outputTokens
@@ -17405,7 +17639,7 @@ function aggregateTokenUsage(usages) {
 }
 function aggregateConversationTokenUsage(conversation) {
   return aggregateTokenUsage(
-    conversation.logTurns.flatMap(
+    (conversation.logTurns || []).flatMap(
       (turn) => turn.iterations.map((iteration) => iteration.tokenUsage)
     )
   );
@@ -17439,8 +17673,8 @@ function formatTokenUsage(usage) {
   ];
 }
 function getJobAgentMessages(liveDoc, jobId) {
-  const jobsById = asRecord5(asRecord5(liveDoc.jobs)?.byId);
-  const job = asRecord5(jobsById?.[jobId]);
+  const jobsById = asRecord6(asRecord6(liveDoc.jobs)?.byId);
+  const job = asRecord6(jobsById?.[jobId]);
   const agentMessages = job?.agentMessages;
   return Array.isArray(agentMessages) ? agentMessages : [];
 }
@@ -17499,12 +17733,12 @@ function buildHistory(entries) {
   );
 }
 function getOpenPromptsFromDoc(liveDoc) {
-  const jobsById = asRecord5(asRecord5(liveDoc?.jobs)?.byId) || {};
+  const jobsById = asRecord6(asRecord6(liveDoc?.jobs)?.byId) || {};
   const prompts = [];
   for (const job of Object.values(jobsById)) {
-    const promptRecords = asRecord5(asRecord5(job)?.prompts) || {};
+    const promptRecords = asRecord6(asRecord6(job)?.prompts) || {};
     for (const raw of Object.values(promptRecords)) {
-      const record = asRecord5(raw);
+      const record = asRecord6(raw);
       if (!record || record.status !== "open" || typeof record.promptId !== "string")
         continue;
       const prompt = normalizePrompt({
@@ -17525,11 +17759,11 @@ function getOpenPromptsFromDoc(liveDoc) {
   return prompts;
 }
 function filterPromptsByBoundary(liveDoc, prompts, boundaryTimestamp) {
-  const jobsById = asRecord5(asRecord5(liveDoc?.jobs)?.byId) || {};
+  const jobsById = asRecord6(asRecord6(liveDoc?.jobs)?.byId) || {};
   return prompts.filter((prompt) => {
     for (const jobRecord of Object.values(jobsById)) {
-      const promptsById = asRecord5(asRecord5(jobRecord)?.prompts) || {};
-      const promptRecord = asRecord5(promptsById[prompt.id]);
+      const promptsById = asRecord6(asRecord6(jobRecord)?.prompts) || {};
+      const promptRecord = asRecord6(promptsById[prompt.id]);
       const openedAt = Number(promptRecord?.openedAt) || 0;
       if (openedAt >= boundaryTimestamp) return true;
     }
@@ -17661,6 +17895,29 @@ function createOpenAIChatTurnGenerator(options) {
     ""
   );
   const model = options.model || "gpt-5.4";
+  const client = new OpenAI({
+    apiKey: options.apiKey,
+    baseURL: baseUrl,
+    defaultHeaders: options.headers
+  });
+  const emitUsage = async (rawUsage, requestId, usageContext) => {
+    if (!rawUsage || !options.onUsage) return;
+    const spend = calculateOpenAITokenSpend(model, rawUsage);
+    if (!spend) return;
+    const mergedUsageContext = {
+      ...options.usageContext || {},
+      ...usageContext || {}
+    };
+    await options.onUsage({
+      ...spend,
+      source: "openai",
+      lineItemType: "llm_tokens",
+      operation: "chat.completions",
+      requestId: requestId || null,
+      usageContext: mergedUsageContext,
+      rawUsage
+    });
+  };
   return async (input) => {
     const messages = [
       {
@@ -17677,80 +17934,46 @@ ${modelOutputInstruction()}`
       messages,
       response_format: { type: "json_object" }
     };
-    if (input.onTextDelta) {
-      payload.stream = true;
-    }
     if (typeof options.temperature === "number") {
       payload.temperature = options.temperature;
     }
     let lastError = null;
     for (let attempt = 1; attempt <= 3; attempt += 1) {
       try {
-        const response = await fetch(`${baseUrl}/chat/completions`, {
-          method: "POST",
-          headers: {
-            "content-type": "application/json",
-            authorization: `Bearer ${options.apiKey}`,
-            ...options.headers
-          },
-          body: JSON.stringify(payload)
-        });
-        if (!response.ok) {
-          const errorText = await response.text();
-          if (attempt < 3 && (response.status >= 500 || response.status === 429)) {
-            await sleep2(500 * attempt);
-            continue;
-          }
-          throw new Error(
-            `OpenAI chat generation failed: ${response.status} ${errorText}`
-          );
-        }
         let raw;
         let text = "";
-        if (input.onTextDelta && response.body) {
+        let usage = null;
+        let requestId = null;
+        if (input.onTextDelta) {
           const onTextDelta = input.onTextDelta;
-          const reader = response.body.getReader();
-          const decoder = new TextDecoder();
-          let buffer = "";
-          const processStreamLine = async (line) => {
-            const trimmedLine = line.trimEnd();
-            if (!trimmedLine.startsWith("data:")) return;
-            const data = trimmedLine.slice("data:".length).trim();
-            if (!data || data === "[DONE]") return;
-            const event = JSON.parse(data);
-            const delta = asRecord5(
-              asRecord5(event.choices?.[0])?.delta
-            )?.content;
-            const deltaText = typeof delta === "string" ? delta : Array.isArray(delta) ? delta.map((part) => asRecord5(part)?.text || "").join("") : "";
-            if (!deltaText) return;
+          const stream = await client.chat.completions.create({
+            ...payload,
+            stream: true,
+            stream_options: { include_usage: true }
+          });
+          for await (const event of stream) {
+            requestId = requestId || event.id || event._request_id || null;
+            usage = event.usage || usage;
+            const delta = event.choices?.[0]?.delta?.content;
+            const deltaText = typeof delta === "string" ? delta : Array.isArray(delta) ? delta.map((part) => asRecord6(part)?.text || "").join("") : "";
+            if (!deltaText) continue;
             text += deltaText;
             await onTextDelta(deltaText);
-          };
-          while (true) {
-            const { value, done } = await reader.read();
-            if (done) break;
-            buffer += decoder.decode(value, { stream: true });
-            while (true) {
-              const lineEnd = buffer.indexOf("\n");
-              if (lineEnd === -1) break;
-              const line = buffer.slice(0, lineEnd);
-              buffer = buffer.slice(lineEnd + 1);
-              await processStreamLine(line);
-            }
           }
-          buffer += decoder.decode();
-          if (buffer.trim()) {
-            await processStreamLine(buffer);
-          }
-          raw = { streamed: true };
+          raw = { streamed: true, model, usage, request_id: requestId };
         } else {
-          const json = await response.json();
-          raw = json;
-          const content = asRecord5(
-            asRecord5(json.choices?.[0])?.message
+          const completion = await client.chat.completions.create(
+            payload
+          );
+          raw = completion;
+          usage = completion.usage;
+          requestId = (typeof completion.id === "string" ? completion.id : null) || (typeof completion._request_id === "string" ? completion._request_id : null);
+          const content = asRecord6(
+            asRecord6(completion.choices?.[0])?.message
           )?.content;
-          text = typeof content === "string" ? content : Array.isArray(content) ? content.map((part) => asRecord5(part)?.text || "").join("") : "";
+          text = typeof content === "string" ? content : Array.isArray(content) ? content.map((part) => asRecord6(part)?.text || "").join("") : "";
         }
+        await emitUsage(usage, requestId, input.usageContext);
         const parsed = extractJsonObject(text);
         if (!parsed) {
           if (attempt < 3) {
@@ -17770,9 +17993,10 @@ ${modelOutputInstruction()}`
         };
       } catch (error) {
         lastError = error instanceof Error ? error : new Error(String(error));
-        if (attempt < 3 && /socket connection was closed unexpectedly|ECONNRESET|network|timed out/i.test(
+        const status = Number(error?.status);
+        if (attempt < 3 && (Number.isFinite(status) && (status >= 500 || status === 429) || /socket connection was closed unexpectedly|ECONNRESET|network|timed out/i.test(
           lastError.message
-        )) {
+        ))) {
           await sleep2(500 * attempt);
           continue;
         }
@@ -17805,12 +18029,12 @@ async function withTimeout2(promise, ms, label) {
   }
 }
 function getActionSummary(liveDoc, jobId) {
-  const jobsById = asRecord5(asRecord5(liveDoc?.jobs)?.byId) || {};
-  const job = asRecord5(jobsById[jobId]);
+  const jobsById = asRecord6(asRecord6(liveDoc?.jobs)?.byId) || {};
+  const job = asRecord6(jobsById[jobId]);
   const summary = Array.isArray(job?.actionSummary) ? job.actionSummary.filter(
     (line) => typeof line === "string"
   ) : [];
-  const trace = Array.isArray(job?.actionTrace) ? job.actionTrace.map((event) => asRecord5(event)).filter((event) => Boolean(event)) : [];
+  const trace = Array.isArray(job?.actionTrace) ? job.actionTrace.map((event) => asRecord6(event)).filter((event) => Boolean(event)) : [];
   const traceLines = trace.map((event) => {
     const kind = typeof event.kind === "string" ? event.kind : "";
     const action = typeof event.action === "string" ? event.action : "";
@@ -17831,9 +18055,9 @@ function getActionSummary(liveDoc, jobId) {
 }
 function normalizeHeapSnapshot2(heap) {
   return {
-    entriesByPath: asRecord5(heap?.entriesByPath) || {},
-    listsByName: asRecord5(heap?.listsByName) || {},
-    variablesByName: asRecord5(heap?.variablesByName) || {},
+    entriesByPath: asRecord6(heap?.entriesByPath) || {},
+    listsByName: asRecord6(heap?.listsByName) || {},
+    variablesByName: asRecord6(heap?.variablesByName) || {},
     updatedAt: typeof heap?.updatedAt === "number" ? heap.updatedAt : Date.now()
   };
 }
@@ -17868,9 +18092,9 @@ async function waitForJobOutcome(input) {
       input.boundaryTimestamp
     );
     lastPromptCount = prompts.length;
-    const messages = asArray3(asRecord5(liveDoc.conversation)?.messages);
+    const messages = asArray3(asRecord6(liveDoc.conversation)?.messages);
     lastMessageCount = messages.length;
-    lastJobSummary = asRecord5(asRecord5(liveDoc.jobs)?.byId)?.[input.job.id] || null;
+    lastJobSummary = asRecord6(asRecord6(liveDoc.jobs)?.byId)?.[input.job.id] || null;
     if (prompts.length > 0) {
       return { kind: "prompt", prompts, liveDoc, stdout, stderr };
     }
@@ -18054,7 +18278,8 @@ function jsonBlock(value) {
 }
 function buildSessionLogReport(input) {
   const { conversation, result, error } = input;
-  const systemPrompts = conversation.logTurns.flatMap(
+  const logTurns = conversation.logTurns || [];
+  const systemPrompts = logTurns.flatMap(
     (turn) => turn.iterations.map((iteration) => ({
       turn,
       iteration
@@ -18083,7 +18308,7 @@ function buildSessionLogReport(input) {
     "",
     "## Conversation"
   ];
-  for (const turn of conversation.logTurns) {
+  for (const turn of logTurns) {
     lines.push("", `### Turn ${turn.turnNumber}: ${turn.turnId}`, "");
     lines.push("**User**", "");
     lines.push(turn.request, "");
@@ -18281,7 +18506,7 @@ async function runAgentEvalSuite(options) {
             promptInteractions: completed.promptInteractions,
             result: completed.result,
             heap: normalizeHeapSnapshot2(
-              asRecord5(
+              asRecord6(
                 cloneJson(conversation.environment.document)?.heap
               )
             ),
@@ -18391,7 +18616,7 @@ async function runAgentEvalSuite(options) {
         finalResult = result;
       } catch (error) {
         const failureMessage = error instanceof Error ? error.message : String(error);
-        const failedTurn = conversation.logTurns[conversation.logTurns.length - 1];
+        const failedTurn = conversation.logTurns?.[conversation.logTurns.length - 1];
         if (failedTurn && !failedTurn.completed) {
           failedTurn.error = failureMessage;
           const failedIteration = latestIterationLog(failedTurn);
@@ -18524,7 +18749,7 @@ function createAgentEvalHarness(options) {
   }
   function buildCheckContext(conversation, completed, turnDir) {
     const liveDoc = cloneJson(conversation.environment.document);
-    const heap = normalizeHeapSnapshot2(asRecord5(liveDoc?.heap));
+    const heap = normalizeHeapSnapshot2(asRecord6(liveDoc?.heap));
     return {
       conversation,
       environment: conversation.environment,
@@ -18618,7 +18843,7 @@ function createAgentEvalHarness(options) {
       result: resumed.result,
       stdout: [...pending.stdout, ...resumed.stdout],
       agentMessages: getJobAgentMessages(liveDoc, pending.job.id),
-      sessionHeap: normalizeHeapSnapshot2(asRecord5(liveDoc?.heap))
+      sessionHeap: normalizeHeapSnapshot2(asRecord6(liveDoc?.heap))
     });
     const responseText = presentation.responseText || pending.finalReply || "Done.";
     pending.conversation.history.push({
@@ -18742,7 +18967,7 @@ function createAgentEvalHarness(options) {
           environmentId: conversation.environment.environmentId,
           domainRevision: conversation.environment.domainRevision
         },
-        heapSummary: projectHeapSummary(asRecord5(liveDoc?.heap), {
+        heapSummary: projectHeapSummary(asRecord6(liveDoc?.heap), {
           focus: heapFocus
         }),
         referentSummary: projectConversationReferentSummary(liveDoc),
@@ -18764,7 +18989,14 @@ function createAgentEvalHarness(options) {
           history: buildHistory(conversation.history),
           request,
           attempt: 1,
-          tools
+          tools,
+          usageContext: {
+            sandboxId: conversation.environment.sandboxId,
+            environmentId: conversation.environment.environmentId,
+            sessionId: conversation.environment.sessionId,
+            subjectId: conversation.environment.subjectId,
+            permissionProfileId: conversation.environment.permissionProfileId
+          }
         }),
         chatTimeoutMs,
         `chat generation for ${conversation.label} iteration ${iteration + 1}`
@@ -18913,7 +19145,7 @@ function createAgentEvalHarness(options) {
       const settledLiveDoc = cloneJson(
         conversation.environment.document
       );
-      const sessionHeap = normalizeHeapSnapshot2(asRecord5(settledLiveDoc?.heap));
+      const sessionHeap = normalizeHeapSnapshot2(asRecord6(settledLiveDoc?.heap));
       const presentation = resolveJobPresentation({
         jobId: job.id,
         result: outcome.result,
@@ -19037,7 +19269,10 @@ function createAgentTester(options) {
     model: options.openai?.model || options.model,
     baseUrl: options.openai?.baseUrl,
     temperature: options.openai?.temperature,
-    headers: options.openai?.headers
+    headers: options.openai?.headers,
+    onUsage: async (usage) => {
+      await granular.recordOpenAIUsageSpend(usage, usage.usageContext);
+    }
   });
   let resolvedEnvironmentId = "environmentId" in options.target ? options.target.environmentId : null;
   let connectSeeded = false;