@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.0

package/skills/agentsam-cloudflare-workers/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: agentsam-cloudflare-workers
+description: >
+  Treat Cloudflare Workers, Wrangler, Durable Objects, D1, R2, Queues, Hyperdrive,
+  Browser, Containers, observability, versions, and deployment mechanics as a native
+  AgentSam execution dialect. Use when inspecting, debugging, profiling, operating,
+  or shipping Cloudflare-backed applications. Prefer typed Wrangler operations,
+  machine-readable output, explicit risk classes, real error/trace identifiers, and
+  Worker-runtime semantics over generic shell guessing.
+metadata:
+  short-description: "Cloudflare Workers/Wrangler native operations, observability, errors, and CPU discipline"
+  aliases:
+    - cloudflare
+    - workers
+    - wrangler
+    - cf-native
+user-invocable: true
+---
+
+# AgentSam Cloudflare Workers
+
+Cloudflare is a first-class execution environment, not just a deploy target. Use its
+runtime rules and Wrangler command contracts as native vocabulary.
+
+## Operating laws
+
+- Prefer structured Wrangler output such as `whoami --json`, deployments/versions JSON, and JSON tail events where supported.
+- Never ask a model to read or print `wrangler auth token`, API tokens, secrets, cookies, or credential files. Identity status is useful evidence; credential bytes are not.
+- Classify every operation before execution: read, local-runtime, filesystem-write, remote-write, secret-bearing, or long-running stream.
+- Keep `cwd`, account authority, connection identity, and execution leases runtime-owned. Do not accept them from model arguments when they are security-relevant.
+- Preserve real provider/runtime errors: process exit code, HTTP status, machine error type/code, request/Ray IDs, retry metadata, and bounded redacted stderr/body.
+- Do not infer CPU time from `performance.now()` or `Date.now()` around pure computation in a deployed Worker. Production timers advance around I/O; use local workerd/DevTools CPU profiles and production CPU metrics.
+- For expensive CPU investigations, collect a bounded profile summary and selected source evidence first, then hand that packet to the chosen reasoning model. Do not dump the repository or raw multi-megabyte profile into model context.
+- Prefer Web Crypto/native runtime primitives for CPU-intensive cryptography instead of pure-JavaScript reimplementations where the Worker contract allows it.
+- Remember that open TCP sockets have runtime and Durable Object lifecycle/cost implications; close them deliberately and prefer platform-native database connectivity such as Hyperdrive where appropriate.
+
+## Native workflow
+
+```text
+identify worker/config
+  -> verify Cloudflare identity without exposing token
+  -> inspect deployments/versions/config/types
+  -> reproduce locally with wrangler dev/workerd
+  -> collect JSON logs / CPU profile / production metrics
+  -> normalize errors and trace IDs
+  -> select only implicated source evidence
+  -> deterministic summary
+  -> optional high-reasoning model audit
+  -> verify locally
+  -> deploy only through the normal progression guard
+```
+
+Read the references for command risk classes, error envelopes, and CPU/observability mechanics.

package/skills/agentsam-cloudflare-workers/references/cpu-profiling.md

@@ -0,0 +1,16 @@
+# Worker CPU profiling
+
+A deployed Worker's `performance.now()` and `Date.now()` do not measure pure CPU loops reliably because the clock advances around I/O rather than ordinary CPU execution. Never create fake production CPU timings from those APIs.
+
+For CPU work:
+
+1. Reproduce with `wrangler dev`/workerd using production-like routes, request volume, and data/bindings where safe.
+2. Open DevTools from the Wrangler session and record a CPU profile.
+3. Export the `.cpuprofile` and run `agentsam cloudflare cpu analyze <profile.cpuprofile>`.
+4. Use the ranked self-time frames to select a small source slice.
+5. Optionally hand the bounded profile + selected source packet to a high-reasoning model through `cloudflare.cpu.audit`.
+6. Verify the fix locally, then compare production CPU metrics/error rate after normal deployment gates.
+
+Pay attention to garbage collection as well as application frames. Large allocation churn can be the hotspot even when no single application function looks dominant.
+
+Use native implementations when they remove JavaScript CPU work. For example, Worker Web Crypto operations are preferable to CPU-heavy pure-JavaScript cryptography when compatible with the required algorithm and contract.

package/skills/agentsam-cloudflare-workers/references/errors-and-observability.md

@@ -0,0 +1,29 @@
+# Cloudflare errors and observability
+
+## Error evidence contract
+
+When an operation fails, retain the most specific machine evidence available:
+
+```text
+source/provider
+operation
+process exit code or HTTP status
+machine error type
+machine error code
+request id / cf-ray when present
+retry-after and retry classification
+requested vs resolved processing/runtime mode when relevant
+bounded redacted response body or stderr
+```
+
+Do not flatten this to `request failed`, `429`, `500`, or `Wrangler failed` when richer evidence exists.
+
+## Retry discipline
+
+Retry only failures that can plausibly recover without changing operator state. Rate limits, ramp-rate throttles, overload, and transient provider 5xx errors may be retryable. Authentication, invalid arguments, billing/spend limits, unsupported regions, and missing permissions require configuration or operator action instead of retry loops.
+
+## Worker telemetry
+
+Use production Workers metrics/logs/traces for live evidence. Tail Workers and diagnostics channels can carry structured diagnostic events, but observability itself consumes resources and should remain bounded. Prefer structured fields and stable trace/request IDs over giant free-form logs.
+
+Unhandled promise rejections are runtime evidence and should be surfaced with the rejection reason/trace while redacting secrets.

package/skills/agentsam-cloudflare-workers/references/wrangler-native-map.md

@@ -0,0 +1,28 @@
+# Wrangler native map
+
+Treat Wrangler commands as typed operations rather than arbitrary shell text.
+
+## Safe model-visible reads
+
+AgentSam's initial native executor intentionally exposes only:
+
+- `whoami --json`
+- `deployments list --json`
+- `versions list --json`
+- `types --check`
+- `queues list`
+
+These are argv-built and cwd/config scoped. The allowlist is intentionally smaller than Wrangler's full command surface.
+
+## Known operational families
+
+- Identity/config: `whoami`, `auth list`, `auth activate`, `login`.
+- Development: `dev`, `types`, local persistence, remote bindings.
+- Observability: `tail`, deployments, versions, logs/traces/metrics.
+- Delivery: `deploy`, version deployment, rollback, triggers.
+- Data: D1, R2, KV, Queues, Hyperdrive, Vectorize.
+- Compute/AI: Containers, Browser, Workers AI, Workflows and related products.
+
+Remote mutation, rollback, secret handling, token retrieval, data writes, and long-running streams require a dedicated policy/approval path. Do not broaden the safe executor by passing arbitrary trailing argv.
+
+Wrangler global controls such as `--config`, `--cwd`, `--env`, and `--profile` are useful scoping mechanics. Keep them explicit; do not silently switch accounts or environments.

package/skills/catalog.json

@@ -48,6 +48,24 @@
         "agentsam-progression-guard/references/hooks-operational-io.md"
       ],
       "user_invocable": true
+    },
+    {
+      "id": "agentsam-cloudflare-workers",
+      "aliases": [
+        "cloudflare",
+        "workers",
+        "wrangler",
+        "cf-native"
+      ],
+      "title": "AgentSam Cloudflare Workers",
+      "description": "Operate and debug Cloudflare Workers with typed Wrangler operations, runtime-aware observability, structured errors, and CPU profiling discipline.",
+      "entry": "agentsam-cloudflare-workers/SKILL.md",
+      "references": [
+        "agentsam-cloudflare-workers/references/wrangler-native-map.md",
+        "agentsam-cloudflare-workers/references/errors-and-observability.md",
+        "agentsam-cloudflare-workers/references/cpu-profiling.md"
+      ],
+      "user_invocable": true
     }
   ]
 }

package/src/agent/capability-adapter.js

@@ -1,14 +1,32 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { getCapability, listCapabilities } from '../capabilities/manifest.js';
 import { repositorySnapshot } from '../capabilities/repository-snapshot.js';
+import { runWranglerNative, summarizeCloudflareCpuProfileFile, runCloudflareCpuAudit } from '../cloudflare/index.js';
 import { runRepositoryAudit } from './repository-audit.js';
 
+const PACKAGE_ROOT = path.resolve(fileURLToPath(new URL('../../', import.meta.url)));
+
+function loadSchema(value) {
+  if (!value) return { type: 'object', properties: {} };
+  if (typeof value === 'object' && !Array.isArray(value)) return structuredClone(value);
+  const filename = path.resolve(PACKAGE_ROOT, String(value));
+  if (filename !== PACKAGE_ROOT && !filename.startsWith(`${PACKAGE_ROOT}${path.sep}`)) throw new Error(`capability_schema_outside_package:${value}`);
+  try { return JSON.parse(fs.readFileSync(filename, 'utf8')); }
+  catch (error) { throw new Error(`capability_schema_unreadable:${value}:${error?.message || error}`); }
+}
+
 export function createCapabilityAdapter({ handlers = {}, reasoner } = {}) {
   const executable = new Map([
     ['repository.snapshot', (input) => repositorySnapshot(input)],
+    ['cloudflare.wrangler.native', (input = {}) => runWranglerNative(input.command, input)],
+    ['cloudflare.cpu.profile', (input = {}) => summarizeCloudflareCpuProfileFile(input)],
     ...Object.entries(handlers),
   ]);
   if (typeof reasoner === 'function') {
     executable.set('repository.audit', (input = {}) => runRepositoryAudit({ ...input, reasoner }));
+    executable.set('cloudflare.cpu.audit', (input = {}) => runCloudflareCpuAudit({ ...input, reasoner }));
   }
 
   function describe(id) {
@@ -18,33 +36,27 @@ export function createCapabilityAdapter({ handlers = {}, reasoner } = {}) {
   }
 
   return Object.freeze({
-    list(options = {}) {
-      return listCapabilities(options);
-    },
+    list(options = {}) { return listCapabilities(options); },
     describe,
     toolDescriptors({ domain, kind, includeUnavailable = false } = {}) {
-      return listCapabilities({ domain, kind }).filter((row) => includeUnavailable || executable.has(row.id)).map((row) => ({
+      return listCapabilities({ domain, kind, status: null }).filter((row) => includeUnavailable || executable.has(row.id)).map((row) => ({
         name: row.id,
         description: row.description,
-        input_schema: row.input_schema || null,
+        category: row.domain,
+        risk: row.side_effects === 'none' || row.side_effects === 'network-read' ? 'read' : 'write',
+        input_schema: loadSchema(row.input_schema),
         side_effects: row.side_effects,
         deterministic: row.deterministic,
         model_required: row.model_required,
       }));
     },
-    canInvoke(id) {
-      return executable.has(String(id || '').trim());
-    },
+    canInvoke(id) { return executable.has(String(id || '').trim()); },
     async invoke(id, input = {}) {
       const capability = describe(id);
       const handler = executable.get(capability.id);
       if (!handler) throw new Error(`capability_handler_unavailable:${capability.id}`);
       const value = await handler(input);
-      return {
-        capability_id: capability.id,
-        capability_version: capability.version,
-        result: value,
-      };
+      return { capability_id: capability.id, capability_version: capability.version, result: value };
     },
   });
 }

package/src/agent/index.js

@@ -1,2 +1,3 @@
 export { createCapabilityAdapter } from './capability-adapter.js';
 export { buildRepositoryAuditPacket, renderRepositoryAuditMarkdown, runRepositoryAudit } from './repository-audit.js';
+export { buildAgentToolSurface, capabilityFunctionName, runResponsesAgent } from './responses-runner.js';

package/src/agent/responses-runner.js

@@ -0,0 +1,325 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { assessContextUsage, compileAgentInstructions, createContextBudget, estimateContextTokens, truncateResultText } from '../context/index.js';
+import { getModelRecord, calculateModelCost } from '../models/index.js';
+import { searchToolCards, hydrateToolSchemas } from '../tools/index.js';
+import { createAgentEvent } from '../telemetry/index.js';
+import { diagnosticFromError } from '../errors/index.js';
+
+const RUNTIME_OWNED_KEYS = new Set(['account_id', 'user_id', 'tenant_id', 'workspace_id', 'connection_id', 'runtime_lease_id', 'execution_id']);
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function hash(value) { return `sha256:${createHash('sha256').update(String(value)).digest('hex')}`; }
+function event(emit, type, payload, runId) { if (typeof emit === 'function') emit(createAgentEvent(type, payload, { runId })); }
+
+export function capabilityFunctionName(id) {
+  const source = clean(id).replace(/[^A-Za-z0-9_-]+/g, '_').replace(/^_+|_+$/g, '') || 'capability';
+  if (source.length <= 58) return `as_${source}`;
+  return `as_${source.slice(0, 45)}_${createHash('sha256').update(source).digest('hex').slice(0, 10)}`;
+}
+
+function userMessage(text) {
+  return { role: 'user', content: [{ type: 'input_text', text: String(text) }] };
+}
+
+function modelBudget(record) {
+  const policy = record.context_policy || {};
+  return createContextBudget({
+    windowTokens: record.context_window,
+    targetInputTokens: policy.target_input_tokens,
+    compactAtTokens: policy.compact_at_tokens,
+    interveneAtTokens: policy.intervene_at_tokens,
+    maxNormalInputTokens: policy.max_normal_input_tokens,
+    pricingThresholdTokens: policy.pricing_threshold_tokens,
+    safetyMarginTokens: policy.safety_margin_tokens,
+  });
+}
+
+export function buildAgentToolSurface(capabilityAdapter, objective, options = {}) {
+  if (!capabilityAdapter?.toolDescriptors) throw new TypeError('capabilityAdapter.toolDescriptors is required');
+  const catalog = capabilityAdapter.toolDescriptors({ includeUnavailable: false });
+  const searched = searchToolCards(catalog, objective, { maxItems: options.maxTools ?? 8, maxChars: options.maxCardChars ?? 24_000 });
+  const selected = searched.cards.map((card) => card.tool);
+  const hydrated = hydrateToolSchemas(catalog, selected, { maxTools: options.maxTools ?? 8, maxChars: options.maxSchemaChars ?? 40_000 });
+  const aliases = new Map();
+  const tools = hydrated.tools.map((descriptor) => {
+    const alias = capabilityFunctionName(descriptor.name);
+    aliases.set(alias, descriptor.name);
+    return Object.freeze({
+      type: 'function',
+      name: alias,
+      description: descriptor.description,
+      parameters: descriptor.input_schema || { type: 'object', properties: {} },
+      strict: true,
+    });
+  });
+  return Object.freeze({
+    tools: Object.freeze(tools),
+    aliases,
+    descriptors: Object.freeze(hydrated.tools),
+    receipt: Object.freeze({
+      catalog_tools: catalog.length,
+      cards_returned: searched.receipt.returned_items,
+      card_chars: searched.receipt.chars,
+      hydrated_tools: hydrated.receipt.hydrated_tools,
+      hydrated_schema_chars: hydrated.receipt.schema_chars,
+      deferred_tools: Object.freeze(hydrated.receipt.deferred_tools),
+    }),
+  });
+}
+
+function sanitizeToolInput(value, descriptor, cwd) {
+  const parsed = value && typeof value === 'object' && !Array.isArray(value) ? { ...value } : {};
+  for (const key of RUNTIME_OWNED_KEYS) delete parsed[key];
+  const properties = descriptor?.input_schema?.properties || {};
+  if (Object.hasOwn(properties, 'cwd')) parsed.cwd = cwd;
+  return parsed;
+}
+
+function parseArguments(value) {
+  if (!clean(value)) return {};
+  try {
+    const parsed = JSON.parse(value);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('arguments must be an object');
+    return parsed;
+  } catch (error) { throw new Error(`invalid_tool_arguments:${error?.message || error}`); }
+}
+
+function boundedToolOutput(value, callId, maxChars) {
+  const serialized = typeof value === 'string' ? value : JSON.stringify(value);
+  const ref = `tool:${callId}`;
+  const digest = hash(serialized);
+  if (serialized.length <= maxChars) return Object.freeze({ ref, hash: digest, source_chars: serialized.length, chars: serialized.length, truncated: false, output: serialized });
+  const bounded = truncateResultText(serialized, maxChars);
+  return Object.freeze({
+    ref,
+    hash: digest,
+    source_chars: serialized.length,
+    chars: bounded.chars,
+    truncated: true,
+    output: JSON.stringify({ ref, hash: digest, truncated: true, source_chars: serialized.length, excerpt: bounded.text }),
+  });
+}
+
+function toolResultCharBudget(activeTokens, budget) {
+  if (!Number.isFinite(activeTokens) || activeTokens < 0) return budget.maxToolResultChars;
+  const reserveTokens = 4_000;
+  const headroomTokens = Math.max(256, budget.maxNormalInputTokens - Math.ceil(activeTokens) - reserveTokens);
+  return Math.max(1_024, Math.min(budget.maxToolResultChars, Math.floor(headroomTokens * budget.charsPerToken)));
+}
+
+function projectedInputTokens({ instructions, input, toolSurface, priorActiveTokens, budget }) {
+  const inputChars = typeof input === 'string' ? input.length : JSON.stringify(input ?? '').length;
+  const newTokens = estimateContextTokens(String(instructions || '').length + inputChars + toolSurface.receipt.hydrated_schema_chars, budget.charsPerToken);
+  return Math.max(newTokens, Number.isFinite(priorActiveTokens) ? Math.ceil(priorActiveTokens) + newTokens : newTokens);
+}
+
+function assertEconomicPreflight(projectedTokens, budget, allowOverride) {
+  if (allowOverride) return;
+  if (budget.pricingThresholdTokens != null && projectedTokens > budget.pricingThresholdTokens) {
+    throw new Error(`context_preflight_pricing_threshold:${projectedTokens}>${budget.pricingThresholdTokens}`);
+  }
+  if (projectedTokens >= budget.maxNormalInputTokens) throw new Error(`context_preflight_max_normal:${projectedTokens}>=${budget.maxNormalInputTokens}`);
+  if (projectedTokens >= budget.compactAtTokens) throw new Error(`context_preflight_compaction_required:${projectedTokens}>=${budget.compactAtTokens}`);
+}
+
+export async function runResponsesAgent(options = {}) {
+  const provider = options.provider;
+  if (!provider?.create || !provider?.continueWithToolOutputs) throw new TypeError('Responses provider adapter is required');
+  if (!options.capabilityAdapter) throw new TypeError('capabilityAdapter is required');
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const objective = clean(options.prompt);
+  if (!objective) throw new TypeError('prompt is required');
+  const record = getModelRecord(options.model);
+  if (!record) throw new RangeError(`unknown model: ${options.model}`);
+  const reasoningEffort = clean(options.reasoningEffort || 'low');
+  const serviceTier = clean(options.serviceTier || 'default');
+  const budget = modelBudget(record);
+  const instructionSet = options.instructions == null ? compileAgentInstructions(cwd, { maxChars: budget.maxSystemChars }) : null;
+  const instructions = options.instructions == null ? instructionSet.content : String(options.instructions);
+  const toolSurface = buildAgentToolSurface(options.capabilityAdapter, objective, options);
+  const emit = options.emit;
+  const runId = options.runId;
+  event(emit, 'tool.search', toolSurface.receipt, runId);
+
+  let previousResponseId = clean(options.previousResponseId) || null;
+  let priorActiveTokens = options.previousUsageSnapshot?.current_context?.input_tokens;
+  let input = objective;
+  let compacted = null;
+  let projected = projectedInputTokens({ instructions, input, toolSurface, priorActiveTokens, budget });
+
+  if (projected >= budget.compactAtTokens && previousResponseId && options.autoCompact !== false && typeof provider.compact === 'function') {
+    compacted = await provider.compact({
+      model: record.provider_model_id,
+      previousResponseId,
+      instructions,
+      promptCacheKey: options.promptCacheKey,
+      emit,
+      runId,
+    });
+    input = [...(compacted.output || []), userMessage(objective)];
+    previousResponseId = null;
+    priorActiveTokens = null;
+    projected = projectedInputTokens({ instructions, input, toolSurface, priorActiveTokens, budget });
+  }
+
+  assertEconomicPreflight(projected, budget, options.allowEconomicOverride === true);
+  const pressure = assessContextUsage(projected, budget);
+  const maxOutputTokens = Number.isInteger(options.maxOutputTokens) && options.maxOutputTokens > 0
+    ? Math.min(options.maxOutputTokens, record.max_output_tokens)
+    : Math.min(32_768, record.max_output_tokens);
+  const projectedCost = calculateModelCost(record, { input_tokens: projected, output_tokens: maxOutputTokens }, { serviceTier });
+  if (Number.isFinite(options.maxCallCostUsd) && projectedCost.total_usd > options.maxCallCostUsd) {
+    throw new Error(`projected_call_cost_exceeds_budget:${projectedCost.total_usd.toFixed(6)}>${Number(options.maxCallCostUsd).toFixed(6)}`);
+  }
+  const preflight = Object.freeze({
+    model: record.provider_model_id,
+    reasoning_effort: reasoningEffort,
+    service_tier: serviceTier,
+    estimated_input_tokens: projected,
+    max_output_tokens: maxOutputTokens,
+    projected_max_call_cost_usd: projectedCost.total_usd,
+    pricing_threshold_tokens: budget.pricingThresholdTokens,
+    tokens_until_pricing_threshold: pressure.tokensUntilPricingThreshold,
+    compacted_before_turn: Boolean(compacted),
+    estimate_kind: 'local',
+  });
+  if (typeof options.beforeRequest === 'function') {
+    const approved = await options.beforeRequest(preflight);
+    if (approved === false) throw new Error('model_request_not_approved');
+  }
+  event(emit, 'context.snapshot', {
+    estimate_kind: 'local',
+    estimated_input_tokens: projected,
+    window_tokens: budget.windowTokens,
+    utilization_ratio: pressure.utilizationRatio,
+    pricing_threshold_tokens: budget.pricingThresholdTokens,
+    tokens_until_pricing_threshold: pressure.tokensUntilPricingThreshold,
+    pressure: pressure.stage,
+    projected_max_call_cost_usd: projectedCost.total_usd,
+    tool_surface: toolSurface.receipt,
+  }, runId);
+
+  let cumulativeUsage = options.cumulativeUsage || null;
+  let totalCostUsd = 0;
+  let response = await provider.create({
+    model: record.provider_model_id,
+    input,
+    instructions,
+    reasoningEffort,
+    serviceTier,
+    tools: toolSurface.tools,
+    previousResponseId: previousResponseId || undefined,
+    maxOutputTokens,
+    promptCacheKey: options.promptCacheKey,
+    cumulativeUsage,
+    emit,
+    runId,
+  });
+  totalCostUsd += response.cost?.total_usd || 0;
+  cumulativeUsage = response.usage_snapshot?.cumulative || cumulativeUsage;
+
+  const toolReceipts = [];
+  const maxToolRounds = Number.isInteger(options.maxToolRounds) && options.maxToolRounds > 0 ? options.maxToolRounds : 8;
+  let rounds = 0;
+  while (response.tool_calls?.length) {
+    rounds += 1;
+    if (rounds > maxToolRounds) throw new Error(`tool_round_limit_exceeded:${maxToolRounds}`);
+    const outputs = [];
+    const activeTokens = response.usage_snapshot?.current_context?.input_tokens;
+    const maxToolChars = toolResultCharBudget(activeTokens, budget);
+    for (const call of response.tool_calls) {
+      const capabilityId = toolSurface.aliases.get(call.name);
+      if (!capabilityId) throw new Error(`unrecognized_tool_call:${call.name}`);
+      const descriptor = toolSurface.descriptors.find((row) => row.name === capabilityId);
+      const args = sanitizeToolInput(parseArguments(call.arguments), descriptor, cwd);
+      if (typeof options.beforeTool === 'function') {
+        const approved = await options.beforeTool({
+          call_id: call.call_id,
+          capability_id: capabilityId,
+          descriptor: descriptor ? { ...descriptor, input_schema: undefined } : null,
+          input: args,
+          cwd,
+        });
+        if (approved === false) {
+          const denied = new Error(`tool_execution_not_approved:${capabilityId}`);
+          denied.code = 'AGENTSAM_TOOL_NOT_APPROVED';
+          const diagnostic = diagnosticFromError(denied, { source: 'tool', kind: 'tool_execution_denied' });
+          event(emit, 'tool.failed', { call_id: call.call_id, capability_id: capabilityId, error: diagnostic }, runId);
+          event(emit, 'error.observed', { ...diagnostic, call_id: call.call_id, capability_id: capabilityId }, runId);
+          throw denied;
+        }
+      }
+      event(emit, 'tool.started', { call_id: call.call_id, capability_id: capabilityId }, runId);
+      try {
+        const value = await options.capabilityAdapter.invoke(capabilityId, args);
+        const bounded = boundedToolOutput(value, call.call_id, maxToolChars);
+        toolReceipts.push(Object.freeze({ call_id: call.call_id, capability_id: capabilityId, ...bounded, output: undefined }));
+        outputs.push({ call_id: call.call_id, output: bounded.output });
+        event(emit, 'tool.completed', {
+          call_id: call.call_id,
+          capability_id: capabilityId,
+          result_ref: bounded.ref,
+          result_hash: bounded.hash,
+          result_chars: bounded.chars,
+          source_chars: bounded.source_chars,
+          truncated: bounded.truncated,
+        }, runId);
+      } catch (error) {
+        const diagnostic = diagnosticFromError(error, { source: 'tool', kind: 'tool_execution_error' });
+        event(emit, 'tool.failed', { call_id: call.call_id, capability_id: capabilityId, error: diagnostic }, runId);
+        event(emit, 'error.observed', { ...diagnostic, call_id: call.call_id, capability_id: capabilityId }, runId);
+        outputs.push({ call_id: call.call_id, output: JSON.stringify({ ok: false, error: diagnostic }) });
+      }
+    }
+    response = await provider.continueWithToolOutputs({
+      model: record.provider_model_id,
+      previousResponseId: response.response_id,
+      toolOutputs: outputs,
+      instructions,
+      reasoningEffort,
+      serviceTier,
+      tools: toolSurface.tools,
+      maxOutputTokens,
+      promptCacheKey: options.promptCacheKey,
+      cumulativeUsage,
+      emit,
+      runId,
+    });
+    totalCostUsd += response.cost?.total_usd || 0;
+    cumulativeUsage = response.usage_snapshot?.cumulative || cumulativeUsage;
+  }
+
+  const active = response.usage_snapshot?.current_context?.input_tokens ?? 0;
+  const finalPressure = assessContextUsage(active, budget);
+  event(emit, 'context.snapshot', {
+    estimate_kind: 'provider',
+    active_input_tokens: active,
+    window_tokens: budget.windowTokens,
+    utilization_ratio: finalPressure.utilizationRatio,
+    pricing_threshold_tokens: budget.pricingThresholdTokens,
+    tokens_until_pricing_threshold: finalPressure.tokensUntilPricingThreshold,
+    pressure: finalPressure.stage,
+    compact_before_next_turn: finalPressure.shouldCompact,
+  }, runId);
+
+  return Object.freeze({
+    output_text: response.output_text || '',
+    response_id: response.response_id,
+    model: record.provider_model_id,
+    reasoning_effort: reasoningEffort,
+    requested_service_tier: serviceTier,
+    actual_service_tier: response.actual_service_tier,
+    usage_snapshot: response.usage_snapshot,
+    cumulative_usage: cumulativeUsage,
+    total_cost_usd: totalCostUsd,
+    tool_surface: toolSurface.receipt,
+    tool_receipts: Object.freeze(toolReceipts),
+    compacted_before_turn: Boolean(compacted),
+    continuation: Object.freeze({
+      previous_response_id: response.response_id,
+      usage_snapshot: response.usage_snapshot,
+      compact_before_next_turn: finalPressure.shouldCompact,
+    }),
+  });
+}