@inneranimalmedia/agentsam-sdk 2.6.1 → 2.6.3

package/src/agent/responses-runner.js

@@ -1,13 +1,23 @@
+import { compileToolSchema, restoreOptionalArguments } from '../providers/tool-schema.js';
 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 { assessContextUsage, compileAgentInstructions, createContextBudget, estimateContextTokens, truncateResultText, resolveProjectContext, buildProjectCard } from '../context/index.js';
+import { getModelRecord, calculateModelCost, loadModelPolicy } from '../models/index.js';
 import { searchToolCards, hydrateToolSchemas } from '../tools/index.js';
 import { createAgentEvent } from '../telemetry/index.js';
 import { diagnosticFromError } from '../errors/index.js';
+import { runAgentSamModelTurn } from './model-turn.js';
 
 const RUNTIME_OWNED_KEYS = new Set(['account_id', 'user_id', 'tenant_id', 'workspace_id', 'connection_id', 'runtime_lease_id', 'execution_id']);
 
+// A single integer ceiling ("die after 8 rounds") is not a meaningful safety
+// invariant for genuine engineering work -- it stops runs mid-task for no
+// reason tied to risk, cost, or progress. Replace it with named modes so
+// callers pick a budget that matches the work, while `quick` preserves the
+// exact previous default (8) for any caller that doesn't opt in.
+const RUN_MODE_BUDGETS = Object.freeze({ quick: 8, interactive: 32, agent: 128, long: 512 });
+const DEFAULT_NO_PROGRESS_LIMIT = 4;
+
 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 })); }
@@ -18,14 +28,31 @@ export function capabilityFunctionName(id) {
   return `as_${source.slice(0, 45)}_${createHash('sha256').update(source).digest('hex').slice(0, 10)}`;
 }
 
+// A turn's tool surface is a relevance-scored, maxTools-capped subset of the
+// full capability catalog (see buildAgentToolSurface). Provider conversation
+// state (previousResponseId) can carry a tool name from an earlier turn into
+// a later turn whose narrower surface no longer hydrated that capability, so
+// the model can legitimately call a real, executable capability whose alias
+// simply isn't in *this round's* toolSurface.aliases map. Before treating
+// that as an unrecognized/hallucinated call, check it against the adapter's
+// full executable catalog: if the alias resolves to a real, currently
+// invocable capability, honor it rather than failing a legitimate call.
+export function resolveCapabilityFallback(capabilityAdapter, aliasName) {
+  if (!capabilityAdapter?.toolDescriptors) return null;
+  const fullCatalog = capabilityAdapter.toolDescriptors({ includeUnavailable: false });
+  const descriptor = fullCatalog.find((row) => capabilityFunctionName(row.name) === aliasName);
+  if (!descriptor) return null;
+  return { capabilityId: descriptor.name, descriptor };
+}
+
 function userMessage(text) {
   return { role: 'user', content: [{ type: 'input_text', text: String(text) }] };
 }
 
-function modelBudget(record) {
+function modelBudget(record, policyOverride = null) {
   const windowTokens = Number(record?.context_window);
   if (!Number.isFinite(windowTokens) || windowTokens <= 0) return null;
-  const policy = record.context_policy || {};
+  const policy = { ...(record.context_policy || {}), ...(policyOverride || {}) };
   return createContextBudget({
     windowTokens,
     targetInputTokens: policy.target_input_tokens,
@@ -33,10 +60,71 @@ function modelBudget(record) {
     interveneAtTokens: policy.intervene_at_tokens,
     maxNormalInputTokens: policy.max_normal_input_tokens,
     pricingThresholdTokens: policy.pricing_threshold_tokens,
+    maxCumulativeInputTokens: policy.max_cumulative_input_tokens,
     safetyMarginTokens: policy.safety_margin_tokens,
   });
 }
 
+const UNKNOWN_WINDOW_CONTEXT_LIMITS = Object.freeze({
+  maxSystemChars: 24_000,
+  maxEvidenceChars: 48_000,
+  maxItemChars: 16_000,
+});
+
+function resolveUnknownWindowContext(cwd, card, contextItems = []) {
+  const rules = compileAgentInstructions(cwd, { maxChars: UNKNOWN_WINDOW_CONTEXT_LIMITS.maxSystemChars });
+  let remainingEvidenceChars = UNKNOWN_WINDOW_CONTEXT_LIMITS.maxEvidenceChars;
+  const included = [{
+    kind: 'repo',
+    ref: 'project://card',
+    priority: 100,
+    content: card.content,
+    chars: card.content.length,
+  }];
+  const deferred = [];
+
+  for (const item of contextItems) {
+    const ref = clean(item?.ref) || 'context://anonymous';
+    if (remainingEvidenceChars <= 0) {
+      deferred.push(ref);
+      continue;
+    }
+    const source = String(item?.content ?? '');
+    if (!source) continue;
+    const maxChars = Math.max(1, Math.min(UNKNOWN_WINDOW_CONTEXT_LIMITS.maxItemChars, remainingEvidenceChars));
+    const bounded = truncateResultText(source, maxChars);
+    included.push(Object.freeze({
+      ...item,
+      ref,
+      content: bounded.text,
+      chars: bounded.chars,
+      ...(bounded.truncated ? { truncated: true, source_chars: bounded.source_chars } : {}),
+    }));
+    remainingEvidenceChars -= bounded.chars;
+    if (bounded.truncated) deferred.push(ref + '#remainder');
+  }
+
+  const evidenceChars = UNKNOWN_WINDOW_CONTEXT_LIMITS.maxEvidenceChars - remainingEvidenceChars;
+  return Object.freeze({
+    objective_window_known: false,
+    rules,
+    items: Object.freeze(included),
+    receipt: Object.freeze({
+      estimate_kind: 'local',
+      window_tokens: null,
+      utilization_ratio: null,
+      pressure: 'unknown',
+      system_chars: rules.chars,
+      evidence_chars: evidenceChars,
+      sources_considered: contextItems.length + 1,
+      sources_included: included.length,
+      sources_deferred: deferred.length,
+      deferred_refs: Object.freeze(deferred),
+      fallback_policy: 'bounded_unknown_model_window',
+    }),
+  });
+}
+
 export function buildAgentToolSurface(capabilityAdapter, objective, options = {}) {
   if (!capabilityAdapter?.toolDescriptors) throw new TypeError('capabilityAdapter.toolDescriptors is required');
   const catalog = capabilityAdapter.toolDescriptors({ includeUnavailable: false });
@@ -51,8 +139,10 @@ export function buildAgentToolSurface(capabilityAdapter, objective, options = {}
       type: 'function',
       name: alias,
       description: descriptor.description,
-      parameters: descriptor.input_schema || { type: 'object', properties: {} },
-      strict: true,
+      parameters: ['openai', 'grok', 'gemini'].includes(options.schemaProvider)
+        ? compileToolSchema({ provider: options.schemaProvider, canonicalSchema: descriptor.input_schema, strict: descriptor.strict !== false, name: alias }).providerSchema
+        : descriptor.input_schema || { type: 'object', properties: {}, required: [], additionalProperties: false },
+      strict: descriptor.strict !== false,
     });
   });
   return Object.freeze({
@@ -64,7 +154,7 @@ export function buildAgentToolSurface(capabilityAdapter, objective, options = {}
       cards_returned: searched.receipt.returned_items,
       card_chars: searched.receipt.chars,
       hydrated_tools: hydrated.receipt.hydrated_tools,
-      hydrated_schema_chars: hydrated.receipt.schema_chars,
+      hydrated_schema_chars: tools.reduce((sum, tool) => sum + JSON.stringify(tool.parameters).length, 0),
       deferred_tools: Object.freeze(hydrated.receipt.deferred_tools),
     }),
   });
@@ -127,21 +217,80 @@ function assertEconomicPreflight(projectedTokens, budget, allowOverride) {
   if (projectedTokens >= budget.compactAtTokens) throw new Error(`context_preflight_compaction_required:${projectedTokens}>=${budget.compactAtTokens}`);
 }
 
-export async function runResponsesAgent(options = {}) {
+function cumulativeInputTokens(usage) {
+  return Math.max(0, Math.floor(Number(usage?.cumulative?.input_tokens ?? usage?.input_tokens ?? 0)));
+}
+
+function toolOutputInput(outputs) {
+  return outputs.map((row) => ({
+    type: 'function_call_output',
+    call_id: row.call_id,
+    output: typeof row.output === 'string' ? row.output : JSON.stringify(row.output ?? null),
+  }));
+}
+
+export async function runAgentSamTurn(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');
+  // Keep provider wire-format handling behind the inference-only boundary.
+  // This runner owns context, authorization, and the tool loop; the model
+  // adapter only returns a normalized turn (the raw provider response is
+  // retained below for continuation bookkeeping).
+  const modelTurn = async (request) => {
+    const turn = await runAgentSamModelTurn(request);
+    return turn.raw;
+  };
   const cwd = path.resolve(options.cwd || process.cwd());
   const objective = clean(options.prompt);
   if (!objective) throw new TypeError('prompt is required');
-  const record = options.modelRecord || getModelRecord(options.model);
-  if (!record) throw new RangeError(`unknown model: ${options.model}`);
+  const baseRecord = options.modelRecord || getModelRecord(options.model);
+  if (!baseRecord) throw new RangeError(`unknown model: ${options.model}`);
   const reasoningEffort = clean(options.reasoningEffort || 'auto');
   const serviceTier = clean(options.serviceTier || 'default');
-  const budget = modelBudget(record);
-  const instructionSet = options.instructions == null ? compileAgentInstructions(cwd, { maxChars: budget?.maxSystemChars || 48_000 }) : null;
-  const instructions = options.instructions == null ? instructionSet.content : String(options.instructions);
-  const toolSurface = buildAgentToolSurface(options.capabilityAdapter, objective, options);
+  const dynamicPolicy = options.modelPolicy || (options.policyDb
+    ? await loadModelPolicy(options.policyDb, { provider: baseRecord.provider, modelKey: baseRecord.model_key })
+    : null);
+  const record = dynamicPolicy
+    ? Object.freeze({ ...baseRecord, context_policy: Object.freeze({ ...(baseRecord.context_policy || {}), ...dynamicPolicy }) })
+    : baseRecord;
+  const budget = modelBudget(record, dynamicPolicy);
+  let instructions;
+  let resolvedContext = null;
+  if (options.instructions == null) {
+    const card = buildProjectCard(cwd, {
+      activeTaskId: options.activeTaskId || options.taskId,
+      lockedBy: options.lockedBy,
+      checkpointSha: options.checkpointSha,
+      beliefs: options.beliefs || options.workspaceState,
+    });
+    resolvedContext = budget
+      ? resolveProjectContext({
+          cwd,
+          objective,
+          budget,
+          items: [
+            {
+              kind: 'repo',
+              ref: 'project://card',
+              priority: 100,
+              content: card.content,
+            },
+            ...(options.contextItems || []),
+          ],
+        })
+      : resolveUnknownWindowContext(cwd, card, options.contextItems || []);
+    const cardContent = resolvedContext.items.find((i) => i.ref === 'project://card')?.content || card.content;
+    const extraContent = resolvedContext.items
+      .filter((i) => i.ref !== 'project://card')
+      .map((i) => i.content)
+      .join('\n\n');
+    const ruleContent = resolvedContext.rules?.content || '';
+    instructions = [cardContent, extraContent, ruleContent].filter(Boolean).join('\n\n');
+  } else {
+    instructions = String(options.instructions);
+  }
+  const toolSurface = buildAgentToolSurface(options.capabilityAdapter, objective, { ...options, schemaProvider: record.provider });
   const emit = options.emit;
   const runId = options.runId;
   event(emit, 'tool.search', toolSurface.receipt, runId);
@@ -152,6 +301,12 @@ export async function runResponsesAgent(options = {}) {
     : previousResponseId ? { previous_response_id: previousResponseId } : null;
   let priorActiveTokens = options.previousUsageSnapshot?.current_context?.input_tokens;
   let input = objective;
+  const pendingCompactedInput = providerState?.compacted_input;
+  if (!previousResponseId && Array.isArray(providerState?.compacted_input)) {
+    input = [...providerState.compacted_input, userMessage(objective)];
+    providerState = { ...providerState, compacted_input: undefined, compaction_input: undefined, has_compacted_input: undefined };
+    priorActiveTokens = null;
+  }
   let compacted = null;
   let projected = projectedInputTokens({ instructions, input, toolSurface, priorActiveTokens, budget });
 
@@ -161,15 +316,19 @@ export async function runResponsesAgent(options = {}) {
       modelRecord: record,
       previousResponseId,
       providerState,
+      input: !previousResponseId && pendingCompactedInput ? pendingCompactedInput : undefined,
       instructions,
       promptCacheKey: options.promptCacheKey,
       tokensBefore: Number.isFinite(priorActiveTokens) ? priorActiveTokens : projected,
       emit,
       runId,
     });
-    if (Array.isArray(compacted.output) && compacted.output.length) input = [...compacted.output, userMessage(objective)];
-    providerState = compacted.provider_state || null;
-    previousResponseId = clean(providerState?.previous_response_id) || null;
+    if (!Array.isArray(compacted.output) || !compacted.output.length) throw new Error('provider_compaction_output_missing');
+    input = [...compacted.output, userMessage(objective)];
+    // The returned output is the canonical input; do not prepend it again in the adapter.
+    providerState = null;
+    previousResponseId = null;
+    if (typeof options.onCompaction === 'function') await options.onCompaction(compacted);
     priorActiveTokens = null;
     projected = projectedInputTokens({ instructions, input, toolSurface, priorActiveTokens, budget });
   }
@@ -212,22 +371,42 @@ export async function runResponsesAgent(options = {}) {
     pressure: pressure?.stage ?? 'unknown',
     projected_max_call_cost_usd: projectedCost?.total_usd ?? null,
     tool_surface: toolSurface.receipt,
+    resolver_receipt: resolvedContext?.receipt || null,
   }, runId);
 
   let cumulativeUsage = options.cumulativeUsage || null;
+  let observedCumulativeInput = Number(cumulativeUsage?.input_tokens || 0);
+  const observeCumulativeInput = (snapshot) => {
+    const reported = Number(snapshot?.cumulative?.input_tokens);
+    if (Number.isFinite(reported) && reported >= 0) observedCumulativeInput = Math.max(observedCumulativeInput, reported);
+    else {
+      const perCall = Number(snapshot?.input_tokens || 0);
+      if (Number.isFinite(perCall) && perCall > 0) observedCumulativeInput += perCall;
+    }
+    return observedCumulativeInput;
+  };
+  if (compacted?.usage_delta || compacted?.usage) {
+    const delta = compacted.usage_delta || compacted.usage;
+    cumulativeUsage = Object.fromEntries(['input_tokens', 'output_tokens', 'cached_input_tokens', 'cache_write_tokens', 'reasoning_tokens'].map(key => [key, Number(cumulativeUsage?.[key] || 0) + Number(delta[key] || 0)]));
+  }
   let totalCostUsd = 0;
   const costBreakdownUsd = { input: 0, cached_input: 0, cache_write: 0, output: 0 };
+  const continuationCompactions = [];
+  let continuationGuardTriggered = false;
   const accumulateCost = (cost) => {
     totalCostUsd += Number(cost?.total_usd || 0);
     for (const key of Object.keys(costBreakdownUsd)) costBreakdownUsd[key] += Number(cost?.components_usd?.[key] || 0);
   };
-  let response = await provider.create({
+  accumulateCost(compacted?.cost);
+  let response = await modelTurn({
+    provider,
     model: record.provider_model_id,
     modelRecord: record,
     input,
     instructions,
     reasoningEffort,
     serviceTier,
+    autoCompact: options.autoCompact,
     tools: toolSurface.tools,
     previousResponseId: previousResponseId || undefined,
     providerState,
@@ -238,23 +417,40 @@ export async function runResponsesAgent(options = {}) {
     runId,
   });
   accumulateCost(response.cost);
+  observeCumulativeInput(response.usage_snapshot);
   providerState = response.provider_state || (response.response_id ? { previous_response_id: response.response_id } : providerState);
   cumulativeUsage = response.usage_snapshot?.cumulative || cumulativeUsage;
 
   const toolReceipts = [];
-  const maxToolRounds = Number.isInteger(options.maxToolRounds) && options.maxToolRounds > 0 ? options.maxToolRounds : 8;
+  const maxToolRounds = Number.isInteger(options.maxToolRounds) && options.maxToolRounds > 0
+    ? options.maxToolRounds
+    : (RUN_MODE_BUDGETS[options.runMode] ?? RUN_MODE_BUDGETS.quick);
+  const maxNoProgressRounds = Number.isInteger(options.maxNoProgressRounds) && options.maxNoProgressRounds > 0
+    ? options.maxNoProgressRounds
+    : DEFAULT_NO_PROGRESS_LIMIT;
+  const runStartedAt = Date.now();
+  let toolCallCount = 0;
+  let lastRoundSignature = null;
+  let repeatedRoundCount = 0;
   let rounds = 0;
   while (response.tool_calls?.length) {
     rounds += 1;
     if (rounds > maxToolRounds) throw new Error(`tool_round_limit_exceeded:${maxToolRounds}`);
+    toolCallCount += response.tool_calls.length;
+    const roundSignatureParts = [];
     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);
+      let capabilityId = toolSurface.aliases.get(call.name);
+      let descriptor = capabilityId ? toolSurface.descriptors.find((row) => row.name === capabilityId) : null;
+      if (!capabilityId) {
+        const fallback = resolveCapabilityFallback(options.capabilityAdapter, call.name);
+        if (fallback) { capabilityId = fallback.capabilityId; descriptor = fallback.descriptor; }
+      }
       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);
+      const args = sanitizeToolInput(restoreOptionalArguments(parseArguments(call.arguments), descriptor?.input_schema), descriptor, cwd);
+      roundSignatureParts.push(`${capabilityId}:${JSON.stringify(args)}`);
       if (typeof options.beforeTool === 'function') {
         const approved = await options.beforeTool({
           call_id: call.call_id,
@@ -294,24 +490,81 @@ export async function runResponsesAgent(options = {}) {
         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,
-      providerState: response.provider_state || providerState,
-      modelRecord: record,
-      toolOutputs: outputs,
-      instructions,
-      reasoningEffort,
-      serviceTier,
-      tools: toolSurface.tools,
-      maxOutputTokens,
-      promptCacheKey: options.promptCacheKey,
-      cumulativeUsage,
-      emit,
-      runId,
-    });
+    const roundSignature = roundSignatureParts.slice().sort().join('|');
+    repeatedRoundCount = (roundSignature && roundSignature === lastRoundSignature) ? repeatedRoundCount + 1 : 0;
+    lastRoundSignature = roundSignature;
+    if (repeatedRoundCount >= maxNoProgressRounds) {
+      throw new Error(`no_progress_detected:${repeatedRoundCount + 1}`);
+    }
+    const nextCumulativeInput = Math.max(cumulativeInputTokens(response.usage_snapshot), observedCumulativeInput);
+    const cumulativeLimit = budget?.maxCumulativeInputTokens ?? null;
+    const guardrailCrossed = cumulativeLimit != null && nextCumulativeInput > cumulativeLimit;
+    if (guardrailCrossed && !options.allowEconomicOverride && continuationGuardTriggered) {
+      throw new Error(`cumulative_input_guardrail_exceeded:${nextCumulativeInput}>${cumulativeLimit}`);
+    }
+
+    if (guardrailCrossed && !options.allowEconomicOverride && !continuationGuardTriggered) {
+      if (typeof provider.compact !== 'function') {
+        throw new Error(`cumulative_input_compaction_unavailable:${nextCumulativeInput}>${cumulativeLimit}`);
+      }
+      const midTurnCompaction = await provider.compact({
+        model: record.provider_model_id,
+        modelRecord: record,
+        previousResponseId: response.response_id,
+        providerState: response.provider_state || providerState,
+        instructions,
+        promptCacheKey: options.promptCacheKey,
+        tokensBefore: response.usage_snapshot?.current_context?.input_tokens || nextCumulativeInput,
+        emit,
+        runId,
+      });
+      if (!Array.isArray(midTurnCompaction.output) || !midTurnCompaction.output.length) throw new Error('provider_compaction_output_missing');
+      continuationCompactions.push(midTurnCompaction);
+      accumulateCost(midTurnCompaction.cost);
+      const delta = midTurnCompaction.usage_delta || midTurnCompaction.usage;
+      if (delta) {
+        cumulativeUsage = Object.fromEntries(['input_tokens', 'output_tokens', 'cached_input_tokens', 'cache_write_tokens', 'reasoning_tokens'].map(key => [key, Number(cumulativeUsage?.[key] || 0) + Number(delta[key] || 0)]));
+      }
+      continuationGuardTriggered = true;
+      response = await modelTurn({
+        provider,
+        model: record.provider_model_id,
+        modelRecord: record,
+        input: [...midTurnCompaction.output, ...toolOutputInput(outputs)],
+        instructions,
+        reasoningEffort,
+        serviceTier,
+        autoCompact: options.autoCompact,
+        tools: toolSurface.tools,
+        maxOutputTokens,
+        promptCacheKey: options.promptCacheKey,
+        cumulativeUsage,
+        emit,
+        runId,
+      });
+    } else {
+      response = await modelTurn({
+        provider,
+        model: record.provider_model_id,
+        previousResponseId: response.response_id,
+        providerState: response.provider_state || providerState,
+        modelRecord: record,
+        toolOutputs: outputs,
+        instructions,
+        reasoningEffort,
+        serviceTier,
+        autoCompact: options.autoCompact,
+        tools: toolSurface.tools,
+        maxOutputTokens,
+        promptCacheKey: options.promptCacheKey,
+        cumulativeUsage,
+        emit,
+        runId,
+      });
+    }
     accumulateCost(response.cost);
     providerState = response.provider_state || (response.response_id ? { previous_response_id: response.response_id } : providerState);
+    observeCumulativeInput(response.usage_snapshot);
     cumulativeUsage = response.usage_snapshot?.cumulative || cumulativeUsage;
   }
 
@@ -341,6 +594,16 @@ export async function runResponsesAgent(options = {}) {
     cost_breakdown_usd: Object.freeze({ ...costBreakdownUsd }),
     tool_surface: toolSurface.receipt,
     tool_receipts: Object.freeze(toolReceipts),
+    run_budget: Object.freeze({
+      run_mode: options.runMode || 'quick',
+      max_tool_rounds: maxToolRounds,
+      tool_rounds: rounds,
+      tool_calls: toolCallCount,
+      elapsed_ms: Date.now() - runStartedAt,
+      max_no_progress_rounds: maxNoProgressRounds,
+    }),
+    compaction: compacted ? { compaction_id: compacted.compaction_id, provider: record.provider, model: record.provider_model_id, created_at: new Date().toISOString(), usage: compacted.usage_delta || compacted.usage || {}, cost_usd: compacted.cost?.total_usd || 0 } : null,
+    continuation_compactions: Object.freeze(continuationCompactions.map((row) => ({ compaction_id: row.compaction_id, provider: record.provider, model: record.provider_model_id, usage: row.usage_delta || row.usage || {}, cost_usd: row.cost?.total_usd || 0 }))),
     compacted_before_turn: Boolean(compacted),
     provider_state: providerState,
     continuation: Object.freeze({
@@ -351,3 +614,6 @@ export async function runResponsesAgent(options = {}) {
     }),
   });
 }
+
+/** @deprecated Use runAgentSamTurn(). */
+export const runResponsesAgent = runAgentSamTurn;

package/src/capabilities/index.js

@@ -5,6 +5,7 @@ export {
   listCapabilities,
 } from './manifest.js';
 export { repositorySnapshot } from './repository-snapshot.js';
+export { terminalExec } from './terminal-exec.js';
 export {
   REPOSITORY_SNAPSHOT_VIEWS,
   buildRepositorySnapshotFacets,

package/src/capabilities/terminal-exec.js

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import os from 'node:os';
+import { runProcess } from '../security/process.js';
+import { redactDiagnosticValue } from '../errors/index.js';
+
+const COMMAND_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
+const DEFAULT_TIMEOUT_MS = 120_000;
+const MAX_TIMEOUT_MS = 900_000;
+const DEFAULT_OUTPUT_BYTES = 512 * 1024;
+const MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+
+// spawn() never invokes a shell for non-Windows commands (see security/process.js),
+// so a leading `~` in a cwd override or an argv entry (e.g. `git -C ~/repo`) is never
+// expanded by the OS. Expand it ourselves, matching standard shell semantics: only a
+// leading `~` or `~/...` is special, never `~` mid-string.
+function expandHome(value) {
+  const str = clean(value);
+  if (str !== '~' && !str.startsWith('~/')) return str;
+  const home = os.homedir();
+  if (!home) return str;
+  return str === '~' ? home : path.join(home, str.slice(2));
+}
+function boundedInteger(value, fallback, max) {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 1) return fallback;
+  return Math.min(number, max);
+}
+function projectDirectory(root, relativeCwd = '') {
+  const projectRoot = path.resolve(root || process.cwd());
+  const directory = path.resolve(projectRoot, clean(relativeCwd) || '.');
+  if (directory !== projectRoot && !directory.startsWith(`${projectRoot}${path.sep}`)) {
+    throw new Error('terminal_relative_cwd_outside_project');
+  }
+  return { projectRoot, directory };
+}
+
+function subprocessEnvironment(env = process.env) {
+  const blocked = /(?:^|_)(?:TOKEN|SECRET|PASSWORD|PASSCODE|API_KEY|PRIVATE_KEY|AUTHORIZATION|COOKIE|CREDENTIAL)(?:_|$)/i;
+  return Object.fromEntries(Object.entries(env || {}).filter(([key]) => !blocked.test(key)));
+}
+
+/**
+ * Run one argv-safe process for the interactive agent.
+ *
+ * The runtime owns the project root. The model may select only a relative
+ * working directory inside that root, and never receives credential-bearing
+ * environment variables through this capability.
+ */
+export async function terminalExec(input = {}, options = {}) {
+  const command = clean(input.command);
+  if (!COMMAND_RE.test(command)) throw new Error('terminal_command_must_be_pathless_executable');
+  const args = Array.isArray(input.args) ? input.args.map((value) => expandHome(value)) : [];
+  if (args.length > 128) throw new Error('terminal_argument_limit_exceeded');
+  const { projectRoot, directory } = projectDirectory(expandHome(input.cwd) || options.cwd, input.relative_cwd);
+  const timeoutMs = boundedInteger(input.timeout_ms, DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
+  const maxBytes = boundedInteger(input.max_output_bytes, DEFAULT_OUTPUT_BYTES, MAX_OUTPUT_BYTES);
+  const runner = options.run || runProcess;
+  const result = await runner(command, args, {
+    cwd: directory,
+    timeoutMs,
+    maxBytes,
+    signal: options.signal,
+    env: subprocessEnvironment(options.env || process.env),
+  });
+  return Object.freeze({
+    ok: result.code === 0,
+    command,
+    args,
+    project_root: projectRoot,
+    cwd: directory,
+    exit_code: result.code,
+    signal: result.signal || null,
+    stdout: redactDiagnosticValue(String(result.stdout || ''), { maxChars: maxBytes }),
+    stderr: redactDiagnosticValue(String(result.stderr || ''), { maxChars: maxBytes }),
+  });
+}