@truefoundry/trueforge-core 0.0.0 → 0.1.0-rc.0

package/dist/core/runtime/AgentThread.mjs

@@ -0,0 +1,1062 @@
+// src/core/runtime/AgentThread.ts
+import { SUB_AGENT_IDENTITY } from "../capabilities/builtins/DynamicSubAgents.mjs";
+import { AgentHarnessError, InvalidAgentSendInputError } from "../errors.mjs";
+import {
+  EventType,
+  newEventId
+} from "../events/schema.mjs";
+import { InstructionBuilder, ROOT_AGENT_IDENTITY } from "../InstructionBuilder.mjs";
+import "../llm/LLMTypes.mjs";
+import { toOpenAIResponseFormat } from "../llm/responseFormat.mjs";
+import { toOpenAIChatMessage } from "../llm/toOpenAIChatMessage.mjs";
+import { estimateTokensForString } from "../llm/usage.mjs";
+import { convertMCPServersToTools } from "../mcp/convertMCPServers.mjs";
+import { executeToolCalls } from "../mcp/executeToolCalls.mjs";
+import {
+  InternalEventType
+} from "./AgentThread.types.mjs";
+import {
+  currentContextUsageFromCompletion,
+  getEmptyCurrentContextUsage,
+  mergeCurrentContextUsage
+} from "./contextUsage.mjs";
+import {
+  assistantMessageContentToStringForSubAgent,
+  estimateTokensForContextMessages,
+  INTERNAL_SYSTEM_PROMPT,
+  isApprovalDecisionMessage,
+  isClientSideToolResponseMessage,
+  isInputUserMessage,
+  isLLMContextMessage,
+  isLLMToolMessage,
+  makeUnknownToolInfo,
+  scanApprovalDecisions,
+  toEnrichedToolCall,
+  toToolCallInfo
+} from "./contextUtils.mjs";
+import { DeferredTool } from "./DeferredTool.mjs";
+import { createEmptyAgentThreadMetrics, updateMetricsFromUsage } from "./metrics.mjs";
+import { getClosableOpenToolCallIds, OpenToolCallCloser } from "./OpenToolCallCloser.mjs";
+import { isEmptyMessageContent, processAgentUserInput } from "./UserInputMessage.mjs";
+var DEFAULT_ITERATION_LIMIT = 25;
+var VALID_TRANSITIONS = {
+  "llm-call-required": ["tool-response-required", "user-input-required"],
+  "tool-response-required": ["llm-call-required"],
+  // user-input-required transitions to:
+  //   tool-response-required — after approval decisions are appended (approval flow)
+  //   llm-call-required     — after client-side tool responses resolve tool calls directly
+  "user-input-required": ["tool-response-required", "llm-call-required"]
+};
+function assertValidTransition(from, to) {
+  if (!VALID_TRANSITIONS[from].includes(to)) {
+    throw new Error(`Invalid state transition: ${from} \u2192 ${to}`);
+  }
+}
+function deriveAgentThreadState(context) {
+  const openToolCallIds = getOpenToolCallIds(context);
+  if (openToolCallIds.size === 0) return "llm-call-required";
+  const assistant = lastAssistantInContext(context);
+  const decisions = scanApprovalDecisions(context);
+  const hasPendingApproval = assistant?.tool_calls?.some(
+    (tc) => openToolCallIds.has(tc.id) && tc.tool_info.is_approval_required === true && !decisions.has(tc.id)
+  );
+  const hasPendingClientSideTool = assistant?.tool_calls?.some(
+    (tc) => openToolCallIds.has(tc.id) && tc.tool_info.is_client_side === true
+  );
+  return hasPendingApproval || hasPendingClientSideTool ? "user-input-required" : "tool-response-required";
+}
+function hasToolCalls(message) {
+  return Boolean(message.tool_calls && message.tool_calls.length > 0);
+}
+function getOpenToolCallIds(context) {
+  const resolvedToolCallIds = /* @__PURE__ */ new Set();
+  const openToolCallIds = /* @__PURE__ */ new Set();
+  for (let i = context.length - 1; i >= 0; i--) {
+    const msg = context[i];
+    if (msg === void 0) continue;
+    if (!isLLMContextMessage(msg)) continue;
+    if (msg.role === "tool") {
+      resolvedToolCallIds.add(msg.tool_call_id);
+      continue;
+    }
+    if (msg.role === "assistant") {
+      for (const tc of msg.tool_calls ?? []) openToolCallIds.add(tc.id);
+      for (const id of resolvedToolCallIds) openToolCallIds.delete(id);
+      break;
+    }
+  }
+  return openToolCallIds;
+}
+function lastAssistantInContext(context) {
+  return context.findLast(
+    (msg) => isLLMContextMessage(msg) && msg.role === "assistant"
+  );
+}
+function getUnclosableOpenToolCallIds(context, openToolCallIds) {
+  const blockingOpenToolCallIds = new Set(openToolCallIds);
+  for (const id of getClosableOpenToolCallIds(context)) {
+    blockingOpenToolCallIds.delete(id);
+  }
+  return blockingOpenToolCallIds;
+}
+function buildMCPInitializeEvent(initInfo, threadId) {
+  return {
+    type: EventType.MCP_INITIALIZE,
+    id: newEventId(),
+    created_at: (/* @__PURE__ */ new Date()).toISOString(),
+    thread_id: threadId,
+    mcp_servers: initInfo
+  };
+}
+function buildMCPAuthRequiredEvent(authRequirementInfo, threadId) {
+  return {
+    type: InternalEventType.MCP_AUTH_REQUIRED,
+    id: newEventId(),
+    created_at: (/* @__PURE__ */ new Date()).toISOString(),
+    mcp_servers: authRequirementInfo.flatMap((or) => or.servers.map((s) => ({ ...s, thread_ids: [threadId] }))),
+    // threadId identifies which thread triggered auth for each server so AgentThreadOrchestrator can merge
+    // auth events across parallel sub-agents by server.
+    thread_id: null
+  };
+}
+function buildSandboxCreatedEvent(info) {
+  return {
+    type: EventType.SANDBOX_CREATED,
+    id: newEventId(),
+    created_at: (/* @__PURE__ */ new Date()).toISOString(),
+    ...info,
+    thread_id: null
+  };
+}
+function buildModelMessageEvent({
+  assistantMessage,
+  threadId,
+  finishReason,
+  usage,
+  id
+}) {
+  const { role, tool_calls, thinking_blocks, source, ...rest } = assistantMessage;
+  void role;
+  void thinking_blocks;
+  void source;
+  const event = {
+    ...rest,
+    tool_calls: tool_calls?.map(toEnrichedToolCall),
+    type: EventType.MODEL_MESSAGE,
+    id,
+    created_at: (/* @__PURE__ */ new Date()).toISOString(),
+    thread_id: threadId,
+    finish_reason: finishReason,
+    ...usage && { usage }
+  };
+  return event;
+}
+function validateUserMessage(message, blockingOpenToolCallIds, index) {
+  if (isEmptyMessageContent(message.content)) {
+    throw new InvalidAgentSendInputError(`messages[${String(index)}] user message has empty content`);
+  }
+  if (blockingOpenToolCallIds.size > 0) {
+    throw new InvalidAgentSendInputError("user message cannot be sent while approvals or questions are pending");
+  }
+}
+function validateToolMessage(message, openToolCallIds, index) {
+  if (!openToolCallIds.has(message.tool_call_id)) {
+    throw new InvalidAgentSendInputError(
+      `messages[${String(index)}] no open tool call for tool_call_id '${message.tool_call_id}'`
+    );
+  }
+}
+function validateApprovalMessage(message, pendingApprovalIds, index) {
+  if (!pendingApprovalIds.has(message.tool_call_id)) {
+    throw new InvalidAgentSendInputError(
+      `messages[${String(index)}] no pending approval for tool_call_id '${message.tool_call_id}'`
+    );
+  }
+}
+function getPendingApprovalToolCalls(context) {
+  const openToolCallIds = getOpenToolCallIds(context);
+  const decisions = scanApprovalDecisions(context);
+  const assistant = lastAssistantInContext(context);
+  return (assistant?.tool_calls ?? []).filter(
+    (tc) => openToolCallIds.has(tc.id) && tc.tool_info.is_approval_required === true && !decisions.has(tc.id)
+  );
+}
+function getPendingClientSideToolCalls(context) {
+  const openToolCallIds = getOpenToolCallIds(context);
+  const assistant = lastAssistantInContext(context);
+  return (assistant?.tool_calls ?? []).filter((tc) => openToolCallIds.has(tc.id) && tc.tool_info.is_client_side === true);
+}
+function validateInputMessageTypesGivenContext(context, messages) {
+  const openToolCallIds = getOpenToolCallIds(context);
+  const blockingOpenToolCallIds = getUnclosableOpenToolCallIds(context, openToolCallIds);
+  const pendingApprovalIds = new Set(getPendingApprovalToolCalls(context).map((tc) => tc.id));
+  const pendingClientSideIds = new Set(getPendingClientSideToolCalls(context).map((tc) => tc.id));
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    if (m === void 0) continue;
+    if (isApprovalDecisionMessage(m)) {
+      validateApprovalMessage(m, pendingApprovalIds, i);
+      pendingApprovalIds.delete(m.tool_call_id);
+    } else if (isInputUserMessage(m)) {
+      validateUserMessage(m, blockingOpenToolCallIds, i);
+    } else if (isClientSideToolResponseMessage(m) || isLLMToolMessage(m)) {
+      validateToolMessage(m, openToolCallIds, i);
+      openToolCallIds.delete(m.tool_call_id);
+      blockingOpenToolCallIds.delete(m.tool_call_id);
+      pendingClientSideIds.delete(m.tool_call_id);
+    } else {
+      const _exhaustive = m;
+      throw new InvalidAgentSendInputError(
+        `messages[${String(i)}] has unsupported type: ${JSON.stringify(_exhaustive)}`
+      );
+    }
+  }
+  if (pendingApprovalIds.size > 0 || pendingClientSideIds.size > 0) {
+    const missing = [...pendingApprovalIds, ...pendingClientSideIds];
+    throw new InvalidAgentSendInputError(
+      `Send batch must resolve all pending tool calls awaiting user input. Missing: ${missing.join(", ")}`
+    );
+  }
+}
+async function buildModelMessageDeltaEvent({
+  chunk,
+  threadId,
+  toolMapping,
+  usage,
+  id,
+  logger
+}) {
+  const choice = chunk.choices[0];
+  const delta = choice?.delta;
+  const finishReason = choice?.finish_reason;
+  if (!delta || Object.keys(delta).length === 0 && !finishReason && !usage) {
+    return;
+  }
+  if (!delta.tool_calls?.length && !delta.content && !delta.reasoning_content && !finishReason && !usage) {
+    return;
+  }
+  const toolCalls = delta.tool_calls ?? [];
+  for (const toolCall of toolCalls) {
+    if (toolCall.function?.name) {
+      const toolInfo = toolMapping.get(toolCall.function.name);
+      if (!toolInfo) {
+        logger.warn(`LLM called unknown tool: Tool ${toolCall.function.name} not found in tool mapping.`);
+        toolCall.tool_info = toToolCallInfo(makeUnknownToolInfo(toolCall.function.name));
+        continue;
+      }
+      toolCall.tool_info = toToolCallInfo(
+        await toolInfo.toolSet.toolCallInfo(
+          { name: toolInfo.originalToolName },
+          false
+          /* resolveUnderlyingTool */
+        )
+      );
+    }
+  }
+  const { role, function_call, thinking_blocks, ...deltaWithoutRole } = delta;
+  void role;
+  void function_call;
+  void thinking_blocks;
+  return {
+    ...deltaWithoutRole,
+    type: EventType.MODEL_MESSAGE_DELTA,
+    id,
+    thread_id: threadId,
+    ...finishReason && { finish_reason: finishReason },
+    ...usage && { usage }
+  };
+}
+async function buildContextAssistantMessage(assistantMessage, toolMapping) {
+  if (!assistantMessage.tool_calls?.length) {
+    const { tool_calls, ...rest } = assistantMessage;
+    void tool_calls;
+    return rest;
+  }
+  const enrichedToolCalls = [];
+  for (const toolCall of assistantMessage.tool_calls) {
+    const toolInfo = toolMapping.get(toolCall.function.name);
+    if (!toolInfo) {
+      enrichedToolCalls.push({ ...toolCall, tool_info: makeUnknownToolInfo(toolCall.function.name) });
+      continue;
+    }
+    const tool_info = await toolInfo.toolSet.toolCallInfo(
+      {
+        name: toolInfo.originalToolName,
+        arguments: tryParseToolArgs(toolCall.function.arguments)
+      },
+      // During context persistence, we have the complete message and hence the tool arguments are available.
+      // Hence, we resolve the underlying tool to get the tool information.
+      true
+    );
+    enrichedToolCalls.push({ ...toolCall, tool_info });
+  }
+  return { ...assistantMessage, tool_calls: enrichedToolCalls };
+}
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function tryParseToolArgs(args) {
+  if (!args) return {};
+  try {
+    const parsed = JSON.parse(args);
+    return isJsonObject(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+var AgentThread = class {
+  threadId;
+  parent;
+  definition;
+  title;
+  agentInfo;
+  context;
+  currentContextUsage;
+  preSendContextProcessors;
+  preLLMContextProcessors;
+  preEphemeralLLMContextProcessors;
+  postToolCallContextProcessor;
+  instruction;
+  toolResponseProcessors;
+  instructionBuilders;
+  systemToolSets;
+  deferredTool;
+  convertedTools;
+  pendingSandboxCreatedEvents = [];
+  sandbox;
+  tracing;
+  logger;
+  metrics = createEmptyAgentThreadMetrics();
+  tfyManagedServerNames = /* @__PURE__ */ new Set();
+  contextBusy = false;
+  preSendRanThisTurn = false;
+  currentState = null;
+  preComputedCompletion;
+  /** Mirrored capability KV — source for toSnapshot().capability_state. */
+  capabilityState = {};
+  capabilityStateKeys;
+  constructor(input) {
+    this.tracing = input.tracing;
+    this.logger = input.logger.child({ module: "AgentThread" });
+    this.threadId = input.threadId;
+    this.definition = input.definition;
+    this.context = input.context ? [...input.context] : [];
+    this.title = input.title;
+    this.parent = input.parent;
+    this.currentContextUsage = input.currentContextUsage ?? getEmptyCurrentContextUsage();
+    this.agentInfo = input.agentInfo;
+    this.preComputedCompletion = input.preComputedCompletion;
+    this.sandbox = input.sandbox;
+    const capabilities = input.capabilities ?? [];
+    this.systemToolSets = capabilities.flatMap((c) => c.systemToolSets ?? []);
+    this.preLLMContextProcessors = capabilities.flatMap((c) => c.preLLMProcessors ?? []);
+    this.preEphemeralLLMContextProcessors = capabilities.flatMap((c) => c.preLLMEphemeralProcessors ?? []);
+    this.postToolCallContextProcessor = capabilities.flatMap((c) => c.postToolCallProcessors ?? []);
+    this.toolResponseProcessors = capabilities.flatMap((c) => c.toolResponseProcessors ?? []);
+    this.instructionBuilders = capabilities.flatMap((c) => c.instructionBuilders ?? []);
+    const capabilityPreSend = capabilities.flatMap((c) => c.preSendProcessors ?? []);
+    this.preSendContextProcessors = [new OpenToolCallCloser(), ...capabilityPreSend];
+    assertUniqueStateKeys(capabilities);
+    const claimed = claimCapabilityState(capabilities, input.capabilityState, this.logger);
+    this.capabilityState = claimed;
+    this.capabilityStateKeys = new Set(
+      capabilities.map((c) => c.state?.key).filter((k) => typeof k === "string")
+    );
+    for (const capability of capabilities) {
+      if (!capability.state) continue;
+      const value = claimed[capability.state.key];
+      if (value !== void 0) {
+        capability.state.load(value);
+      }
+    }
+    if (this.definition.toolSets?.length) {
+      this.deferredTool = new DeferredTool(this.definition.toolSets, {
+        tracing: this.tracing,
+        logger: input.logger
+      });
+    }
+    if (this.sandbox) {
+      this.sandbox.configureCodeMode(this.definition.toolSets ?? []);
+    }
+    this.instruction = this.buildInstruction(this.definition.instruction);
+  }
+  buildInstruction(userInstruction) {
+    const identity = this.parent ? SUB_AGENT_IDENTITY : ROOT_AGENT_IDENTITY;
+    const builder = InstructionBuilder.createSystemPrompt(identity);
+    const capabilities = builder.beginSection("agent-capabilities");
+    capabilities.addSection("internal-messages", INTERNAL_SYSTEM_PROMPT);
+    if (this.sandbox) {
+      this.sandbox.buildInstruction(capabilities);
+    }
+    if (this.deferredTool) {
+      this.deferredTool.buildInstruction(capabilities);
+    }
+    for (const build of this.instructionBuilders) {
+      build(capabilities);
+    }
+    if (!this.parent && userInstruction?.trim()) {
+      builder.addSection("user-instructions", userInstruction.trim(), true);
+    }
+    return builder.build();
+  }
+  async *send(messages) {
+    if (messages.length === 0 && !this.isAwaitingUserInput()) {
+      return;
+    }
+    this.throwIfContextBusy();
+    this.contextBusy = true;
+    try {
+      for await (const event of this.executeContextProcessors("preSend")) {
+        yield event;
+      }
+      this.preSendRanThisTurn = true;
+      validateInputMessageTypesGivenContext(this.context, messages);
+      const approvals = [];
+      const clientSideToolResponses = [];
+      const contextMessages = [];
+      for (const m of messages) {
+        if (isApprovalDecisionMessage(m)) {
+          approvals.push(m);
+        } else if (isClientSideToolResponseMessage(m)) {
+          clientSideToolResponses.push(m);
+        } else if (isInputUserMessage(m)) {
+          const result = await processAgentUserInput(m, this.sandbox);
+          contextMessages.push(result.message);
+          if (result.sandboxCreated) {
+            this.pendingSandboxCreatedEvents.push(buildSandboxCreatedEvent(result.sandboxCreated));
+          }
+        } else if (isLLMToolMessage(m)) {
+          contextMessages.push(m);
+        } else {
+          const _exhaustive = m;
+          throw new InvalidAgentSendInputError(`Unsupported send input: ${JSON.stringify(_exhaustive)}`);
+        }
+      }
+      if (approvals.length > 0 || clientSideToolResponses.length > 0) {
+        const approvalContext = approvals.map((a) => ({
+          type: EventType.USER_TOOL_APPROVAL,
+          tool_call_id: a.tool_call_id,
+          approval: a.approval
+        }));
+        const toolResponseContext = clientSideToolResponses.map((m) => ({
+          role: "tool",
+          tool_call_id: m.tool_call_id,
+          content: m.content
+        }));
+        yield* this.appendToContext({
+          context: [...approvalContext, ...toolResponseContext],
+          output: [],
+          currentContextUsage: void 0,
+          usage: void 0
+        });
+      }
+      if (contextMessages.length > 0) {
+        yield* this.appendToContext({
+          context: contextMessages,
+          output: [],
+          currentContextUsage: void 0,
+          usage: void 0
+        });
+      }
+    } finally {
+      this.contextBusy = false;
+    }
+  }
+  throwIfContextBusy() {
+    if (this.contextBusy) {
+      throw new Error(`context is busy for thread ${this.threadId}`);
+    }
+  }
+  deriveState() {
+    const next = deriveAgentThreadState(this.context);
+    if (this.currentState) {
+      assertValidTransition(this.currentState, next);
+    }
+    this.currentState = next;
+    return next;
+  }
+  *appendToContext(opts) {
+    const { context, output, currentContextUsage, usage, completion } = opts;
+    const newCurrentContextUsage = currentContextUsage ?? mergeCurrentContextUsage(this.currentContextUsage, estimateTokensForContextMessages(context));
+    const event = {
+      type: InternalEventType.AGENT_CONTEXT_APPEND,
+      thread_id: this.threadId,
+      context,
+      output,
+      current_context_usage: newCurrentContextUsage,
+      ...completion && { completion }
+    };
+    if (usage) {
+      updateMetricsFromUsage(this.metrics, usage);
+    }
+    yield event;
+    this.context = this.context.concat(context);
+    this.currentContextUsage = newCurrentContextUsage;
+  }
+  *overwriteContext(payload) {
+    const event = {
+      thread_id: this.threadId,
+      ...payload
+    };
+    updateMetricsFromUsage(this.metrics, payload.usage);
+    yield event;
+    this.context = payload.context;
+    this.currentContextUsage = payload.current_context_usage;
+    this.metrics.total_summarizations++;
+  }
+  generateErrorEvent(message, output) {
+    return {
+      type: InternalEventType.AGENT_DONE,
+      status: "error",
+      thread_id: this.threadId,
+      title: this.title,
+      error: message,
+      parent: this.parent,
+      send_to_parent: this.parent ? {
+        role: "tool",
+        content: message,
+        tool_call_id: this.parent.tool_call_id
+      } : void 0,
+      ...output && { output }
+    };
+  }
+  hasOpenToolCallId(toolCallId) {
+    return getOpenToolCallIds(this.context).has(toolCallId);
+  }
+  // True when this thread is paused waiting on the user to resolve a pending tool
+  // approval or a client-side tool response.
+  isAwaitingUserInput() {
+    return getPendingApprovalToolCalls(this.context).length > 0 || getPendingClientSideToolCalls(this.context).length > 0;
+  }
+  // Pure validation of an input batch against this thread's current context; throws
+  // on an invalid/incomplete batch without mutating the context.
+  validateSendInput(messages) {
+    validateInputMessageTypesGivenContext(this.context, messages);
+  }
+  toSnapshot() {
+    const capability_state = Object.keys(this.capabilityState).length > 0 ? { ...this.capabilityState } : null;
+    return {
+      thread_id: this.threadId,
+      context: this.context,
+      current_context_usage: this.currentContextUsage,
+      parent: this.parent ?? null,
+      agent_info: this.agentInfo ?? null,
+      completion: this.preComputedCompletion ?? null,
+      capability_state
+    };
+  }
+  getAgentThreadMetrics() {
+    return { ...this.metrics };
+  }
+  transformToLLMRequest(tools) {
+    let messages = [];
+    if (this.instruction) {
+      messages.push({
+        role: "system",
+        content: this.instruction
+      });
+    }
+    if (this.definition.messages) {
+      for (const msg of this.definition.messages) {
+        if (isLLMContextMessage(msg)) {
+          messages.push(toOpenAIChatMessage(msg));
+        }
+      }
+    }
+    const contextMessages = this.context.filter(isLLMContextMessage).map((msg) => toOpenAIChatMessage(msg));
+    messages.push(...contextMessages);
+    for (const processor of this.preEphemeralLLMContextProcessors) {
+      messages = processor.processPreLLMEphemeral(messages) ?? messages;
+    }
+    const requestBody = {
+      messages,
+      stream: true,
+      ...this.definition.responseFormat !== void 0 ? { response_format: toOpenAIResponseFormat(this.definition.responseFormat) } : {}
+    };
+    if (this.definition.modelParams) {
+      Object.assign(requestBody, this.definition.modelParams);
+    }
+    if (tools.length > 0) {
+      requestBody.tools = tools;
+    }
+    return requestBody;
+  }
+  computeAssistantMessageUsage(params) {
+    const { requestBody, usage, toolMapping } = params;
+    const trimmedInstruction = this.definition.instruction?.trim() ?? "";
+    const instructionsEstimate = this.parent ? 0 : Math.round(estimateTokensForString(trimmedInstruction));
+    const skillsEstimate = this.sandbox?.estimateSkillsTokens() ?? 0;
+    let tfyManagedToolTokens = 0;
+    let userToolTokens = 0;
+    if (requestBody.tools) {
+      for (const tool of requestBody.tools) {
+        const toolTokens = Math.round(estimateTokensForString(JSON.stringify(tool)));
+        const info = "function" in tool ? toolMapping.get(tool.function.name) : void 0;
+        if (info && this.tfyManagedServerNames.has(info.toolSet.name)) {
+          tfyManagedToolTokens += toolTokens;
+        } else {
+          userToolTokens += toolTokens;
+        }
+      }
+    }
+    const totalInstructionTokens = Math.round(estimateTokensForString(this.instruction ?? ""));
+    const harnessInstructionTokens = Math.max(0, totalInstructionTokens - instructionsEstimate - skillsEstimate);
+    const harnessEstimate = harnessInstructionTokens + tfyManagedToolTokens;
+    const estimatedComponentsTotal = harnessEstimate + skillsEstimate + instructionsEstimate + userToolTokens;
+    const messagesEstimate = Math.max(0, usage.input_tokens - estimatedComponentsTotal);
+    return {
+      input_tokens: usage.input_tokens,
+      output_tokens: usage.output_tokens,
+      cache_read_tokens: usage.cache_read_tokens,
+      cache_write_tokens: usage.cache_write_tokens,
+      input_tokens_breakdown: {
+        harness: harnessEstimate,
+        skills: skillsEstimate,
+        instructions: instructionsEstimate,
+        tool_definitions: userToolTokens,
+        messages: messagesEstimate
+      }
+    };
+  }
+  async *executeContextProcessors(hook) {
+    let processors;
+    switch (hook) {
+      case "preSend":
+        processors = this.preSendContextProcessors.map((p) => p.processPreSend.bind(p));
+        break;
+      case "preLLM":
+        processors = this.preLLMContextProcessors.map((p) => p.processPreLLM.bind(p));
+        break;
+      case "postToolCall":
+        processors = this.postToolCallContextProcessor.map((p) => p.processPostToolCall.bind(p));
+        break;
+      default:
+        throw new Error(`Unknown hook: ${String(hook)}`);
+    }
+    const execution = {
+      threadId: this.threadId,
+      sandbox: this.sandbox,
+      currentContextUsage: this.currentContextUsage,
+      context: this.context
+    };
+    for (const processor of processors) {
+      for await (const response of processor(execution)) {
+        switch (response.type) {
+          case InternalEventType.AGENT_CONTEXT_APPEND:
+            yield* this.appendToContext({
+              context: response.context,
+              output: response.output,
+              currentContextUsage: response.current_context_usage ?? this.currentContextUsage,
+              usage: void 0
+            });
+            break;
+          case EventType.AGENT_CONTEXT_OVERWRITE:
+            yield* this.overwriteContext(response);
+            break;
+          case InternalEventType.PASSTHROUGH:
+            yield response;
+            break;
+          case InternalEventType.CAPABILITY_STATE:
+            if (!this.capabilityStateKeys.has(response.key)) {
+              throw new AgentHarnessError(
+                "capability_state_error",
+                `CAPABILITY_STATE key '${response.key}' is not declared by any capability on thread '${this.threadId}'`
+              );
+            }
+            yield {
+              type: InternalEventType.CAPABILITY_STATE,
+              thread_id: this.threadId,
+              key: response.key,
+              state: response.state
+            };
+            this.capabilityState[response.key] = response.state;
+            break;
+          default: {
+            const _exhaustive = response;
+            return _exhaustive;
+          }
+        }
+      }
+    }
+  }
+  async init() {
+    if (this.convertedTools) {
+      return { initializationInfo: [], authRequirementInfo: [] };
+    }
+    return this.initTools();
+  }
+  async initTools() {
+    const tfyManagedServers = [...this.systemToolSets];
+    if (this.sandbox) {
+      tfyManagedServers.push(this.sandbox);
+    }
+    if (this.deferredTool) {
+      tfyManagedServers.push(this.deferredTool);
+    }
+    const userServers = [...this.definition.toolSets ?? []];
+    const { convertedTools, initializationInfo, authRequirementInfo } = await convertMCPServersToTools({
+      tfyManagedServers,
+      userServers
+    });
+    this.convertedTools = convertedTools;
+    this.tfyManagedServerNames = new Set(tfyManagedServers.map((s) => s.name));
+    return { initializationInfo, authRequirementInfo };
+  }
+  getConvertedTools() {
+    if (!this.convertedTools) {
+      throw new Error("unreachable");
+    }
+    return this.convertedTools;
+  }
+  async *stepLLMCall(tools, toolMapping, signal) {
+    const modelMessageEventId = newEventId();
+    if (signal?.aborted) {
+      return { outcome: "exit", modelMessageEventId };
+    }
+    for await (const event of this.executeContextProcessors("preLLM")) {
+      yield event;
+    }
+    const requestBody = this.transformToLLMRequest(tools);
+    const llmStream = this.definition.modelClient.create(requestBody);
+    yield {
+      type: EventType.MODEL_MESSAGE,
+      thread_id: this.threadId,
+      created_at: (/* @__PURE__ */ new Date()).toISOString(),
+      id: modelMessageEventId
+    };
+    let firstDeltaTimestamped = false;
+    let result = await llmStream.next();
+    let modelMessageUsage = void 0;
+    while (!result.done) {
+      const chunk = result.value;
+      if (chunk.usage) {
+        modelMessageUsage = this.computeAssistantMessageUsage({
+          requestBody,
+          usage: chunk.usage,
+          toolMapping
+        });
+      }
+      const event = await buildModelMessageDeltaEvent({
+        chunk,
+        threadId: this.threadId,
+        toolMapping,
+        usage: modelMessageUsage,
+        id: modelMessageEventId,
+        logger: this.logger
+      });
+      if (event) {
+        if (!firstDeltaTimestamped) {
+          firstDeltaTimestamped = true;
+          yield { ...event, created_at: (/* @__PURE__ */ new Date()).toISOString() };
+        } else {
+          yield event;
+        }
+      }
+      result = await llmStream.next();
+    }
+    if (signal?.aborted) {
+      return { outcome: "exit", modelMessageEventId };
+    }
+    modelMessageUsage ??= this.computeAssistantMessageUsage({
+      requestBody,
+      usage: result.value.usage,
+      toolMapping
+    });
+    const assistantMessage = await buildContextAssistantMessage(
+      result.value.output,
+      toolMapping
+    );
+    const finishReason = result.value.finish_reason;
+    const agentAssistantMessage = buildModelMessageEvent({
+      assistantMessage,
+      threadId: this.threadId,
+      finishReason,
+      usage: modelMessageUsage,
+      id: modelMessageEventId
+    });
+    let completion;
+    if (this.parent) {
+      if (finishReason === "length") {
+        const errorMessage = assistantMessageContentToStringForSubAgent(
+          assistantMessage.content,
+          "max_tokens breached"
+        );
+        completion = {
+          type: "error",
+          output: agentAssistantMessage,
+          error_message: errorMessage,
+          send_to_parent: { role: "tool", tool_call_id: this.parent.tool_call_id, content: errorMessage }
+        };
+      } else if (!hasToolCalls(assistantMessage)) {
+        const content = assistantMessageContentToStringForSubAgent(assistantMessage.content);
+        completion = {
+          type: "done",
+          output: agentAssistantMessage,
+          send_to_parent: { role: "tool", tool_call_id: this.parent.tool_call_id, content }
+        };
+      }
+    }
+    yield* this.appendToContext({
+      context: [assistantMessage],
+      output: [agentAssistantMessage],
+      currentContextUsage: currentContextUsageFromCompletion(result.value.usage),
+      usage: result.value.usage,
+      completion
+    });
+    if (finishReason === "length") {
+      const errorContent = completion?.error_message ?? "max_tokens breached";
+      yield this.generateErrorEvent(errorContent, agentAssistantMessage);
+      return { outcome: "exit", modelMessageEventId };
+    }
+    if (!hasToolCalls(assistantMessage)) {
+      yield {
+        type: InternalEventType.AGENT_DONE,
+        status: "done",
+        thread_id: this.threadId,
+        title: this.title,
+        output: agentAssistantMessage,
+        parent: this.parent,
+        send_to_parent: completion?.send_to_parent
+      };
+      return { outcome: "exit", modelMessageEventId };
+    }
+    return { outcome: "continue", modelMessageEventId };
+  }
+  async *stepToolResponse(toolMapping) {
+    const assistantMessage = lastAssistantInContext(this.context);
+    if (!assistantMessage) {
+      throw new Error("unreachable");
+    }
+    const openIds = getOpenToolCallIds(this.context);
+    const openCalls = assistantMessage.tool_calls?.filter((tc) => openIds.has(tc.id)) ?? [];
+    const decisions = scanApprovalDecisions(this.context);
+    const assistantForExecution = {
+      ...assistantMessage,
+      tool_calls: openCalls
+    };
+    const {
+      toolCallResults,
+      initializationInfo,
+      createThreadEvents,
+      sandboxCreated,
+      authRequirementInfo,
+      approvalRequiredToolCalls,
+      clientSideToolCalls,
+      events: passthroughEvents
+    } = await executeToolCalls({
+      assistantMessage: assistantForExecution,
+      toolMapping,
+      threadId: this.threadId,
+      approvalDecisions: decisions
+    });
+    void clientSideToolCalls;
+    if (approvalRequiredToolCalls.length > 0) {
+      throw new Error("Unreachable");
+    }
+    this.metrics.total_tool_calls += toolCallResults.length;
+    this.metrics.total_sub_agents += createThreadEvents.length;
+    if (initializationInfo.length > 0) {
+      yield buildMCPInitializeEvent(initializationInfo, this.threadId);
+    }
+    if (sandboxCreated) {
+      yield buildSandboxCreatedEvent(sandboxCreated);
+    }
+    for (const event of passthroughEvents) {
+      yield { type: InternalEventType.PASSTHROUGH, event };
+    }
+    const toolIdsBeforeProcessing = toolCallResults.map((t) => t.message.tool_call_id);
+    const toolResponseExecution = {
+      threadId: this.threadId,
+      sandbox: this.sandbox,
+      currentContextUsage: this.currentContextUsage,
+      context: this.context
+    };
+    for (const processor of this.toolResponseProcessors) {
+      const processorResult = await processor.process(toolCallResults, toolResponseExecution);
+      if (processorResult.sandboxCreated) {
+        yield buildSandboxCreatedEvent(processorResult.sandboxCreated);
+      }
+      for (const event of processorResult.events ?? []) {
+        yield { type: InternalEventType.PASSTHROUGH, event };
+      }
+    }
+    if (toolIdsBeforeProcessing.length !== toolCallResults.length) {
+      throw Error("Some tool call processor has removed tool call.");
+    }
+    const toolIdsAfterProcessing = new Set(toolCallResults.map((t) => t.message.tool_call_id));
+    if (!toolIdsBeforeProcessing.every((id) => toolIdsAfterProcessing.has(id))) {
+      throw Error("Tool call IDs do not match after processing.");
+    }
+    const agentToolMessages = toolCallResults.map((t) => {
+      const { role, ...toolMessage } = t.message;
+      void role;
+      return {
+        ...toolMessage,
+        type: EventType.TOOL_RESPONSE,
+        id: newEventId(),
+        created_at: t.completedAt,
+        thread_id: this.threadId
+      };
+    });
+    for (const msg of agentToolMessages) {
+      yield msg;
+    }
+    yield* this.appendToContext({
+      context: toolCallResults.map((t) => t.message),
+      output: [],
+      currentContextUsage: void 0,
+      usage: void 0
+    });
+    if (authRequirementInfo.length > 0) {
+      yield buildMCPAuthRequiredEvent(authRequirementInfo, this.threadId);
+      return "exit";
+    }
+    for await (const event of this.executeContextProcessors("postToolCall")) {
+      yield event;
+    }
+    for (const event of createThreadEvents) {
+      yield event;
+    }
+    if (createThreadEvents.length > 0) {
+      return "exit";
+    }
+    return "continue";
+  }
+  *stepUserInputRequired(modelMessageEventId) {
+    const pendingClientSideToolCalls = getPendingClientSideToolCalls(this.context);
+    if (pendingClientSideToolCalls.length > 0) {
+      const responseRequiredEvent = {
+        type: EventType.TOOL_RESPONSE_REQUIRED,
+        id: newEventId(),
+        created_at: (/* @__PURE__ */ new Date()).toISOString(),
+        thread_id: this.threadId,
+        tool_calls: pendingClientSideToolCalls.map((tc) => ({ id: tc.id, source_event_id: modelMessageEventId }))
+      };
+      yield responseRequiredEvent;
+    }
+    const pendingApprovalToolCalls = getPendingApprovalToolCalls(this.context);
+    if (pendingApprovalToolCalls.length > 0) {
+      const event = {
+        type: EventType.TOOL_APPROVAL_REQUIRED,
+        id: newEventId(),
+        created_at: (/* @__PURE__ */ new Date()).toISOString(),
+        thread_id: this.threadId,
+        tool_calls: pendingApprovalToolCalls.map(({ id }) => ({ id, source_event_id: modelMessageEventId }))
+      };
+      yield event;
+    }
+    return "exit";
+  }
+  buildReplayEvent(c) {
+    const base = {
+      type: InternalEventType.AGENT_DONE,
+      thread_id: this.threadId,
+      title: this.title,
+      parent: this.parent,
+      send_to_parent: c.send_to_parent
+    };
+    return c.type === "done" ? { ...base, status: "done", output: c.output } : { ...base, status: "error", error: c.error_message ?? "Sub-agent errored", output: c.output };
+  }
+  async *execute(options) {
+    const signal = options?.signal;
+    this.throwIfContextBusy();
+    this.contextBusy = true;
+    this.currentState = null;
+    try {
+      if (this.preComputedCompletion) {
+        yield this.buildReplayEvent(this.preComputedCompletion);
+        return;
+      }
+      if (!this.preSendRanThisTurn) {
+        for await (const event of this.executeContextProcessors("preSend")) {
+          yield event;
+        }
+      }
+      this.preSendRanThisTurn = false;
+      const { initializationInfo, authRequirementInfo } = await this.tracing.withInitSpan(() => this.init());
+      if (initializationInfo.length > 0) {
+        yield buildMCPInitializeEvent(initializationInfo, this.threadId);
+      }
+      if (authRequirementInfo.length > 0) {
+        yield buildMCPAuthRequiredEvent(authRequirementInfo, this.threadId);
+        return;
+      }
+      const { tools, toolMapping } = this.getConvertedTools();
+      const iterationLimit = this.definition.iterationLimit ?? DEFAULT_ITERATION_LIMIT;
+      let currentModelMessageEventId = "";
+      for (; ; ) {
+        for (; ; ) {
+          const sandboxCreatedEvent = this.pendingSandboxCreatedEvents.shift();
+          if (sandboxCreatedEvent === void 0) break;
+          yield sandboxCreatedEvent;
+        }
+        const state = this.deriveState();
+        let outcome;
+        switch (state) {
+          case "llm-call-required": {
+            if (signal?.aborted) return;
+            if (this.metrics.iterations >= iterationLimit) {
+              yield this.generateErrorEvent(
+                `You have reached iteration limit of ${String(iterationLimit)}, please request again`
+              );
+              return;
+            }
+            this.metrics.iterations++;
+            const llmResult = yield* this.stepLLMCall(tools, toolMapping, signal);
+            outcome = llmResult.outcome;
+            currentModelMessageEventId = llmResult.modelMessageEventId;
+            break;
+          }
+          case "tool-response-required": {
+            if (signal?.aborted) return;
+            outcome = yield* this.stepToolResponse(toolMapping);
+            break;
+          }
+          case "user-input-required": {
+            outcome = yield* this.stepUserInputRequired(currentModelMessageEventId);
+            break;
+          }
+          default: {
+            throw new Error("unreachable");
+          }
+        }
+        if (outcome === "exit") return;
+      }
+    } catch (error) {
+      yield this.generateErrorEvent(error instanceof Error ? error.message : "Unknown error occurred");
+    } finally {
+      this.contextBusy = false;
+    }
+  }
+};
+function assertUniqueStateKeys(capabilities) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const capability of capabilities) {
+    const key = capability.state?.key;
+    if (!key) continue;
+    if (seen.has(key)) {
+      throw new AgentHarnessError(
+        "capability_state_error",
+        `Duplicate capability state key '${key}' \u2014 each key may be claimed by at most one capability`
+      );
+    }
+    seen.add(key);
+  }
+}
+function claimCapabilityState(capabilities, input, logger) {
+  if (!input) return {};
+  const claimedKeys = new Set(capabilities.map((c) => c.state?.key).filter((k) => typeof k === "string"));
+  const claimed = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (!claimedKeys.has(key)) {
+      logger.warn(`Dropping unclaimed capability_state key '${key}' \u2014 no capability declares it`);
+      continue;
+    }
+    claimed[key] = value;
+  }
+  return claimed;
+}
+export {
+  AgentThread
+};
+//# sourceMappingURL=AgentThread.mjs.map