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

package/dist/core/capabilities/builtins/DynamicSubAgents.mjs

@@ -0,0 +1,134 @@
+// src/core/capabilities/builtins/DynamicSubAgents.ts
+import dedent from "dedent";
+import { z } from "zod";
+import "../../InstructionBuilder.mjs";
+import { defineTool, LocalToolMCP } from "../../mcp/LocalToolMCP.mjs";
+var SUB_AGENT_TOOL_NAME = "create_sub_agent";
+var SUB_AGENTS_SERVER_ID = "sub_agents";
+var SUB_AGENTS_REMINDER_TAG = "sub-agents";
+var SUB_AGENT_IDENTITY = "You are the Agent operating as a sub-agent that has been delegated a specific task. The Agent has access to the same tools as the parent agent. The Agent must focus on completing the delegated task and return a concise result. The Agent cannot ask questions to the user.";
+function createDynamicSubAgentLargeToolResponseGuidance() {
+  return dedent`
+    For large unstructured output like web search, documentation lookup, or broad search results,
+    the Agent should prefer delegating to a sub-agent and ask it to return only the relevant summary, with citations
+    when they improve verification.`;
+}
+function buildDynamicSubAgentsInstruction(builder, params) {
+  const sandboxGuidance = params.sandboxAvailable ? dedent`
+      When both sub-agents and sandbox are available, the Agent should always use sandbox code for mechanical data processing.
+      The Agent should use sub-agents for tasks that return large unstructured text (e.g. web search, documentation lookup) or
+      where multi-step reasoning is needed to process and summarize the results.` : "";
+  const paragraphs = [
+    dedent`The Agent can create sub-agents using the ${SUB_AGENT_TOOL_NAME} tool. Sub-agents are best for tasks that involve one or more tool calls that would fill up the context window or are blocked due to "Large Tool Response",
+    or tasks requiring exploration and reasoning that can be clearly delegated.`,
+    createDynamicSubAgentLargeToolResponseGuidance(),
+    ...sandboxGuidance ? [sandboxGuidance] : [],
+    dedent`The Agent should ask the sub-agent to include references or citations when they would improve reliability or make
+    verification easier.`
+  ];
+  builder.addSection(SUB_AGENTS_REMINDER_TAG, paragraphs.join("\n\n").trim());
+}
+var DynamicSubAgents = class extends LocalToolMCP {
+  name = SUB_AGENTS_SERVER_ID;
+  displayName = "DynamicSubAgents";
+  tracingEnabled = false;
+  tools;
+  getCreateSubAgentDescription(modelSetConfig) {
+    let modelSetGuidance = "";
+    const modelSetModels = modelSetConfig ? Object.keys(modelSetConfig) : [];
+    if (modelSetConfig && modelSetModels.length > 0) {
+      const modelList = Object.entries(modelSetConfig).map(([key, entry]) => `- [${key}]: ${entry.description}`).join("\n");
+      modelSetGuidance = dedent`
+        Pick a suitable model for the task being delegated from the following list of models and their descriptions:
+        ${modelList}
+        `;
+    }
+    const paragraphs = [
+      `Delegate a well-defined task to a sub-agent. The Agent must not delegate the whole work to the sub-agent.`,
+      `The sub-agent has access to the same tools and the same sandbox environment as the parent Agent. Files created or modified by either agent are shared and remain available to both.`,
+      ...modelSetGuidance ? [modelSetGuidance] : [],
+      `The sub-agent has NO access to the prior conversation or the user's original message. The Agent must provide a clear, self-contained instruction that includes all necessary context, the exact task to perform, any constraints, what outputs are expected, and what work has already been completed so effort is not duplicated.`
+    ];
+    return paragraphs.join("\n\n").trim();
+  }
+  getCreateSubAgentTool(modelSetConfig) {
+    const modelKeys = Object.keys(modelSetConfig ?? {});
+    if (modelKeys.length > 0) {
+      return defineTool({
+        name: SUB_AGENT_TOOL_NAME,
+        description: this.getCreateSubAgentDescription(modelSetConfig),
+        schema: z.object({
+          name: z.string().min(1),
+          input: z.string().min(1),
+          model: z.enum(modelKeys)
+        }),
+        handler: (input) => Promise.resolve({
+          createSubAgent: {
+            type: "dynamic",
+            name: input.name,
+            input: input.input,
+            model: input.model
+          }
+        })
+      });
+    }
+    return defineTool({
+      name: SUB_AGENT_TOOL_NAME,
+      description: this.getCreateSubAgentDescription(modelSetConfig),
+      schema: z.object({
+        name: z.string().min(1),
+        input: z.string().min(1)
+      }),
+      handler: (input) => Promise.resolve({
+        createSubAgent: {
+          type: "dynamic",
+          name: input.name,
+          input: input.input
+        }
+      })
+    });
+  }
+  constructor({ modelSetConfig, tracing }) {
+    super({ tracing });
+    this.tools = [this.getCreateSubAgentTool(modelSetConfig)];
+  }
+  getTools() {
+    return this.tools;
+  }
+  toolCallInfo(params, _resolveUnderlyingTool) {
+    void _resolveUnderlyingTool;
+    return Promise.resolve({
+      type: "truefoundry-system",
+      mcp_server_id: this.mcpServerId,
+      mcp_server_name: this.name,
+      original_tool_name: params.name,
+      is_approval_required: false,
+      is_thread_creation: true
+    });
+  }
+};
+function dynamicSubAgents(options) {
+  const toolSet = new DynamicSubAgents({
+    modelSetConfig: options.modelSetConfig,
+    tracing: options.tracing
+  });
+  return {
+    systemToolSets: [toolSet],
+    instructionBuilders: [
+      (builder) => {
+        buildDynamicSubAgentsInstruction(builder, { sandboxAvailable: options.sandboxAvailable });
+      }
+    ]
+  };
+}
+export {
+  DynamicSubAgents,
+  SUB_AGENTS_REMINDER_TAG,
+  SUB_AGENTS_SERVER_ID,
+  SUB_AGENT_IDENTITY,
+  SUB_AGENT_TOOL_NAME,
+  buildDynamicSubAgentsInstruction,
+  createDynamicSubAgentLargeToolResponseGuidance,
+  dynamicSubAgents
+};
+//# sourceMappingURL=DynamicSubAgents.mjs.map

package/dist/core/capabilities/builtins/DynamicSubAgents.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/core/capabilities/builtins/DynamicSubAgents.ts"],"sourcesContent":["import type { CallToolRequest } from '@modelcontextprotocol/sdk/types.js';\nimport dedent from 'dedent';\nimport { z } from 'zod';\nimport { InstructionBuilder } from '../../InstructionBuilder';\nimport type { InternalToolCallInfo } from '../../llm/LLMTypes';\nimport { defineTool, LocalToolMCP, type ToolDefinition } from '../../mcp/LocalToolMCP';\nimport type { AgentTracing } from '../../tracing/AgentTracing';\nimport type { AgentCapability } from '../AgentCapability';\n\nexport const SUB_AGENT_TOOL_NAME = 'create_sub_agent';\nexport const SUB_AGENTS_SERVER_ID = 'sub_agents';\nexport const SUB_AGENTS_REMINDER_TAG = 'sub-agents';\n\nexport const SUB_AGENT_IDENTITY =\n  'You are the Agent operating as a sub-agent that has been delegated a specific task. The Agent has access to the same tools as the parent agent. The Agent must focus on completing the delegated task and return a concise result. The Agent cannot ask questions to the user.';\n\nexport interface ModelSetEntry {\n  description: string;\n  model_params?: Record<string, unknown> | undefined;\n}\n\nexport type ModelSetConfig = Record<string, ModelSetEntry>;\n\nexport function createDynamicSubAgentLargeToolResponseGuidance(): string {\n  return dedent`\n    For large unstructured output like web search, documentation lookup, or broad search results,\n    the Agent should prefer delegating to a sub-agent and ask it to return only the relevant summary, with citations\n    when they improve verification.`;\n}\n\nexport function buildDynamicSubAgentsInstruction(\n  builder: InstructionBuilder,\n  params: { sandboxAvailable: boolean },\n): void {\n  const sandboxGuidance = params.sandboxAvailable\n    ? dedent`\n      When both sub-agents and sandbox are available, the Agent should always use sandbox code for mechanical data processing.\n      The Agent should use sub-agents for tasks that return large unstructured text (e.g. web search, documentation lookup) or\n      where multi-step reasoning is needed to process and summarize the results.`\n    : '';\n\n  const paragraphs = [\n    dedent`The Agent can create sub-agents using the ${SUB_AGENT_TOOL_NAME} tool. Sub-agents are best for tasks that involve one or more tool calls that would fill up the context window or are blocked due to \"Large Tool Response\",\n    or tasks requiring exploration and reasoning that can be clearly delegated.`,\n    createDynamicSubAgentLargeToolResponseGuidance(),\n    ...(sandboxGuidance ? [sandboxGuidance] : []),\n    dedent`The Agent should ask the sub-agent to include references or citations when they would improve reliability or make\n    verification easier.`,\n  ];\n\n  builder.addSection(SUB_AGENTS_REMINDER_TAG, paragraphs.join('\\n\\n').trim());\n}\n\nexport class DynamicSubAgents extends LocalToolMCP {\n  readonly name = SUB_AGENTS_SERVER_ID;\n  readonly displayName = 'DynamicSubAgents';\n  override readonly tracingEnabled = false;\n  private tools: ToolDefinition[];\n\n  private getCreateSubAgentDescription(modelSetConfig?: ModelSetConfig): string {\n    let modelSetGuidance = '';\n    const modelSetModels = modelSetConfig ? Object.keys(modelSetConfig) : [];\n    if (modelSetConfig && modelSetModels.length > 0) {\n      const modelList = Object.entries(modelSetConfig)\n        .map(([key, entry]) => `- [${key}]: ${entry.description}`)\n        .join('\\n');\n      modelSetGuidance = dedent`\n        Pick a suitable model for the task being delegated from the following list of models and their descriptions:\n        ${modelList}\n        `;\n    }\n\n    const paragraphs = [\n      `Delegate a well-defined task to a sub-agent. The Agent must not delegate the whole work to the sub-agent.`,\n      `The sub-agent has access to the same tools and the same sandbox environment as the parent Agent. Files created or modified by either agent are shared and remain available to both.`,\n      ...(modelSetGuidance ? [modelSetGuidance] : []),\n      `The sub-agent has NO access to the prior conversation or the user's original message. The Agent must provide a clear, self-contained instruction that includes all necessary context, the exact task to perform, any constraints, what outputs are expected, and what work has already been completed so effort is not duplicated.`,\n    ];\n\n    return paragraphs.join('\\n\\n').trim();\n  }\n\n  private getCreateSubAgentTool(modelSetConfig?: ModelSetConfig): ToolDefinition {\n    const modelKeys = Object.keys(modelSetConfig ?? {});\n    if (modelKeys.length > 0) {\n      return defineTool({\n        name: SUB_AGENT_TOOL_NAME,\n        description: this.getCreateSubAgentDescription(modelSetConfig),\n        schema: z.object({\n          name: z.string().min(1),\n          input: z.string().min(1),\n          model: z.enum(modelKeys as [string, ...string[]]),\n        }),\n        handler: input =>\n          Promise.resolve({\n            createSubAgent: {\n              type: 'dynamic',\n              name: input.name,\n              input: input.input,\n              model: input.model,\n            },\n          }),\n      });\n    }\n    return defineTool({\n      name: SUB_AGENT_TOOL_NAME,\n      description: this.getCreateSubAgentDescription(modelSetConfig),\n      schema: z.object({\n        name: z.string().min(1),\n        input: z.string().min(1),\n      }),\n      handler: input =>\n        Promise.resolve({\n          createSubAgent: {\n            type: 'dynamic',\n            name: input.name,\n            input: input.input,\n          },\n        }),\n    });\n  }\n\n  constructor({ modelSetConfig, tracing }: { modelSetConfig?: ModelSetConfig | undefined; tracing: AgentTracing }) {\n    super({ tracing });\n    this.tools = [this.getCreateSubAgentTool(modelSetConfig)];\n  }\n\n  protected getTools(): ToolDefinition[] {\n    return this.tools;\n  }\n\n  override toolCallInfo(\n    params: CallToolRequest['params'],\n    _resolveUnderlyingTool?: boolean,\n  ): Promise<InternalToolCallInfo> {\n    void _resolveUnderlyingTool;\n    return Promise.resolve({\n      type: 'truefoundry-system',\n      mcp_server_id: this.mcpServerId,\n      mcp_server_name: this.name,\n      original_tool_name: params.name,\n      is_approval_required: false,\n      is_thread_creation: true,\n    });\n  }\n}\n\nexport function dynamicSubAgents(options: {\n  modelSetConfig?: ModelSetConfig | undefined;\n  sandboxAvailable: boolean;\n  tracing: AgentTracing;\n}): AgentCapability {\n  const toolSet = new DynamicSubAgents({\n    modelSetConfig: options.modelSetConfig,\n    tracing: options.tracing,\n  });\n  return {\n    systemToolSets: [toolSet],\n    instructionBuilders: [\n      builder => {\n        buildDynamicSubAgentsInstruction(builder, { sandboxAvailable: options.sandboxAvailable });\n      },\n    ],\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/core/capabilities/builtins/LargeToolResponse.d.ts

@@ -0,0 +1,40 @@
+import type { Logger } from 'winston';
+import type { ToolCallResult } from '../../mcp/executeToolCalls';
+import type { AgentCapability } from '../AgentCapability';
+import type { AgentThreadExecutionContext } from '../AgentContextProcessor';
+import type { ToolResponseProcessor, ToolResponseProcessorResult } from '../ToolResponseProcessor';
+export declare const DEFAULT_INDIVIDUAL_TOOL_TOKEN_THRESHOLD = 6000;
+export declare const DEFAULT_TOTAL_TOOL_TOKEN_THRESHOLD = 10000;
+export declare const DEFAULT_PREVIEW_NUMBER_OF_CHARACTERS = 100;
+export declare class LargeToolResponseProcessor implements ToolResponseProcessor {
+    private dynamicSubAgentsPresent;
+    private individualTokenThreshold;
+    private totalTokenThreshold;
+    private previewNumberOfCharacters;
+    private readonly logger;
+    constructor(param: {
+        dynamicSubAgentsPresent: boolean;
+        individualTokenThreshold: number;
+        totalTokenThreshold: number;
+        previewNumberOfCharacters: number;
+        logger: Logger;
+    });
+    private createLargeToolResponseGuidance;
+    private createFileDumpMessage;
+    private buildResultsWithInfo;
+    private blockResult;
+    private uploadToSandboxAndPrependFilePath;
+    private executeSandboxDumps;
+    process(results: ToolCallResult[], execution: Readonly<AgentThreadExecutionContext>): Promise<ToolResponseProcessorResult>;
+}
+export interface LargeToolResponseSettings {
+    individualTokenThreshold?: number | undefined;
+    totalTokenThreshold?: number | undefined;
+    previewNumberOfCharacters?: number | undefined;
+}
+export declare function largeToolResponse(options: {
+    dynamicSubAgentsPresent: boolean;
+    settings?: LargeToolResponseSettings | undefined;
+    logger: Logger;
+}): AgentCapability;
+//# sourceMappingURL=LargeToolResponse.d.ts.map

package/dist/core/capabilities/builtins/LargeToolResponse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LargeToolResponse.d.ts","sourceRoot":"","sources":["../../../../src/core/capabilities/builtins/LargeToolResponse.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAIjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,KAAK,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAGnG,eAAO,MAAM,uCAAuC,OAAO,CAAC;AAC5D,eAAO,MAAM,kCAAkC,QAAQ,CAAC;AACxD,eAAO,MAAM,oCAAoC,MAAM,CAAC;AA4BxD,qBAAa,0BAA2B,YAAW,qBAAqB;IACtE,OAAO,CAAC,uBAAuB,CAAU;IACzC,OAAO,CAAC,wBAAwB,CAAS;IACzC,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,yBAAyB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,YAAY,KAAK,EAAE;QACjB,uBAAuB,EAAE,OAAO,CAAC;QACjC,wBAAwB,EAAE,MAAM,CAAC;QACjC,mBAAmB,EAAE,MAAM,CAAC;QAC5B,yBAAyB,EAAE,MAAM,CAAC;QAClC,MAAM,EAAE,MAAM,CAAC;KAChB,EAWA;IAED,OAAO,CAAC,+BAA+B;IAgBvC,OAAO,CAAC,qBAAqB;IAoB7B,OAAO,CAAC,oBAAoB;IAS5B,OAAO,CAAC,WAAW;YA4BL,iCAAiC;YA2BjC,mBAAmB;IAO3B,OAAO,CACX,OAAO,EAAE,cAAc,EAAE,EACzB,SAAS,EAAE,QAAQ,CAAC,2BAA2B,CAAC,GAC/C,OAAO,CAAC,2BAA2B,CAAC,CA8BtC;CACF;AAED,MAAM,WAAW,yBAAyB;IACxC,wBAAwB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,yBAAyB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChD;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IACzC,uBAAuB,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,EAAE,yBAAyB,GAAG,SAAS,CAAC;IACjD,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,eAAe,CAYlB"}

package/dist/core/capabilities/builtins/LargeToolResponse.js

@@ -0,0 +1,225 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core/capabilities/builtins/LargeToolResponse.ts
+var LargeToolResponse_exports = {};
+__export(LargeToolResponse_exports, {
+  DEFAULT_INDIVIDUAL_TOOL_TOKEN_THRESHOLD: () => DEFAULT_INDIVIDUAL_TOOL_TOKEN_THRESHOLD,
+  DEFAULT_PREVIEW_NUMBER_OF_CHARACTERS: () => DEFAULT_PREVIEW_NUMBER_OF_CHARACTERS,
+  DEFAULT_TOTAL_TOOL_TOKEN_THRESHOLD: () => DEFAULT_TOTAL_TOOL_TOKEN_THRESHOLD,
+  LargeToolResponseProcessor: () => LargeToolResponseProcessor,
+  largeToolResponse: () => largeToolResponse
+});
+module.exports = __toCommonJS(LargeToolResponse_exports);
+var import_dedent = __toESM(require("dedent"), 1);
+var import_usage = require("../../llm/usage.js");
+var import_Sandbox = require("../../sandbox/Sandbox.js");
+var import_errorLogFields = require("../../util/errorLogFields.js");
+var import_DynamicSubAgents = require("./DynamicSubAgents.js");
+var DEFAULT_INDIVIDUAL_TOOL_TOKEN_THRESHOLD = 6e3;
+var DEFAULT_TOTAL_TOOL_TOKEN_THRESHOLD = 1e4;
+var DEFAULT_PREVIEW_NUMBER_OF_CHARACTERS = 100;
+var FAILURE_MESSAGE_TRUNCATION_LENGTH = 500;
+function categorize(result, sandbox) {
+  if (result.failure) return "failure";
+  if (!result.info) {
+    throw new Error(`Unreachable`);
+  }
+  if (sandbox && result.info.toolSet === sandbox) return "sandbox";
+  return "mcp";
+}
+function createContentPreview(content, previewChars) {
+  if (content.length <= previewChars * 2) {
+    return content;
+  }
+  return `${content.slice(0, previewChars)}
+...
+${content.slice(-previewChars)}`;
+}
+var LargeToolResponseProcessor = class {
+  dynamicSubAgentsPresent;
+  individualTokenThreshold;
+  totalTokenThreshold;
+  previewNumberOfCharacters;
+  logger;
+  constructor(param) {
+    if (param.individualTokenThreshold > param.totalTokenThreshold) {
+      throw new Error(
+        `individualTokenThreshold (${String(param.individualTokenThreshold)}) must be <= totalTokenThreshold (${String(param.totalTokenThreshold)})`
+      );
+    }
+    this.dynamicSubAgentsPresent = param.dynamicSubAgentsPresent;
+    this.individualTokenThreshold = param.individualTokenThreshold;
+    this.totalTokenThreshold = param.totalTokenThreshold;
+    this.previewNumberOfCharacters = param.previewNumberOfCharacters;
+    this.logger = param.logger.child({ module: "LargeToolResponse" });
+  }
+  createLargeToolResponseGuidance(sandbox) {
+    const steps = ["Check if some parameter can be passed in order to reduce the output size."];
+    if (sandbox) {
+      steps.push((0, import_Sandbox.createSandboxLargeToolResponseGuidance)());
+    }
+    if (this.dynamicSubAgentsPresent) {
+      steps.push((0, import_DynamicSubAgents.createDynamicSubAgentLargeToolResponseGuidance)());
+    }
+    return `Content too big. To handle a large tool call the Agent can do the following:
+${steps.map((step, index) => `${String(index + 1)}. ${step}`).join("\n")}`;
+  }
+  createFileDumpMessage(params) {
+    const { filePath, preview } = params;
+    const steps = [
+      import_dedent.default`Use sandbox to read parts of the file or extract data.
+      Use ${import_Sandbox.SANDBOX_SCHEMA_INFER_TAG} to undertand the schema.`
+    ];
+    if (this.dynamicSubAgentsPresent) {
+      steps.push(
+        `${(0, import_DynamicSubAgents.createDynamicSubAgentLargeToolResponseGuidance)()} The Agent must pass file path to sub-agent also.`
+      );
+    }
+    const guidance = `The Agent can do the following to handle it:
+${steps.map((step, index) => `${String(index + 1)}. ${step}`).join("\n")}`;
+    return `Content too large. Result saved to: ${filePath}.
+
+${guidance}
+
+Preview (first and last ${String(this.previewNumberOfCharacters)} chars):
+${preview}`;
+  }
+  buildResultsWithInfo(results, sandbox) {
+    return results.map((toolCallResult) => ({
+      toolCallResult,
+      originalContent: toolCallResult.message.content,
+      originalTokens: (0, import_usage.estimateTokensForString)(toolCallResult.message.content),
+      category: categorize(toolCallResult, sandbox)
+    }));
+  }
+  blockResult(entry, pendingSandboxDumps, sandbox) {
+    const preview = createContentPreview(entry.originalContent, this.previewNumberOfCharacters);
+    let newContent;
+    switch (entry.category) {
+      case "failure":
+        newContent = entry.originalContent.slice(0, FAILURE_MESSAGE_TRUNCATION_LENGTH);
+        break;
+      case "sandbox":
+        newContent = `Content too big. The Agent should write to a file if required and use grep and sed.
+
+Preview:
+${preview}`;
+        break;
+      case "mcp":
+        newContent = `${this.createLargeToolResponseGuidance(sandbox)}
+
+Preview (first and last ${String(this.previewNumberOfCharacters)} chars):
+${preview}`;
+        if (sandbox) {
+          pendingSandboxDumps.push(entry);
+        }
+        break;
+    }
+    entry.toolCallResult.message.content = newContent;
+    entry.toolCallResult.isStructuredContent = false;
+    return Math.max(0, entry.originalTokens - (0, import_usage.estimateTokensForString)(newContent));
+  }
+  async uploadToSandboxAndPrependFilePath(entry, index, sandbox) {
+    if (!entry.toolCallResult.info) {
+      throw new Error(`Unreachable`);
+    }
+    const sanitizedName = entry.toolCallResult.info.originalToolName.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 40);
+    const epoch = Date.now();
+    const fileName = `${sanitizedName}_${String(index)}_${String(epoch)}.txt`;
+    try {
+      const stored = await sandbox.writeArtifact({
+        fileName,
+        content: Buffer.from(entry.originalContent),
+        sourceTool: entry.toolCallResult.info
+      });
+      const preview = createContentPreview(entry.originalContent, this.previewNumberOfCharacters);
+      entry.toolCallResult.message.content = this.createFileDumpMessage({ filePath: stored.filePath, preview });
+      entry.toolCallResult.isStructuredContent = false;
+      return stored.sandboxCreated;
+    } catch (error) {
+      this.logger.error("Failed to upload to sandbox", (0, import_errorLogFields.extractErrorLogFields)(error));
+      return void 0;
+    }
+  }
+  async executeSandboxDumps(entries, sandbox) {
+    const results = await Promise.all(
+      entries.map((entry, index) => this.uploadToSandboxAndPrependFilePath(entry, index, sandbox))
+    );
+    return results.find((r) => r !== void 0);
+  }
+  async process(results, execution) {
+    const sandbox = execution.sandbox;
+    const resultsWithInfo = this.buildResultsWithInfo(results, sandbox);
+    let runningTotal = resultsWithInfo.reduce((sum, e) => sum + e.originalTokens, 0);
+    if (runningTotal < this.individualTokenThreshold) {
+      return {};
+    }
+    const pendingSandboxDumps = [];
+    const unblocked = [];
+    for (const entry of resultsWithInfo) {
+      if (entry.originalTokens >= this.individualTokenThreshold) {
+        runningTotal -= this.blockResult(entry, pendingSandboxDumps, sandbox);
+      } else {
+        unblocked.push(entry);
+      }
+    }
+    const sortedUnblocked = [...unblocked].sort((a, b) => b.originalTokens - a.originalTokens);
+    for (const entry of sortedUnblocked) {
+      if (runningTotal < this.totalTokenThreshold) {
+        break;
+      }
+      runningTotal -= this.blockResult(entry, pendingSandboxDumps, sandbox);
+    }
+    const sandboxCreated = sandbox ? await this.executeSandboxDumps(pendingSandboxDumps, sandbox) : void 0;
+    return sandboxCreated !== void 0 ? { sandboxCreated } : {};
+  }
+};
+function largeToolResponse(options) {
+  return {
+    toolResponseProcessors: [
+      new LargeToolResponseProcessor({
+        dynamicSubAgentsPresent: options.dynamicSubAgentsPresent,
+        individualTokenThreshold: options.settings?.individualTokenThreshold ?? DEFAULT_INDIVIDUAL_TOOL_TOKEN_THRESHOLD,
+        totalTokenThreshold: options.settings?.totalTokenThreshold ?? DEFAULT_TOTAL_TOOL_TOKEN_THRESHOLD,
+        previewNumberOfCharacters: options.settings?.previewNumberOfCharacters ?? DEFAULT_PREVIEW_NUMBER_OF_CHARACTERS,
+        logger: options.logger
+      })
+    ]
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_INDIVIDUAL_TOOL_TOKEN_THRESHOLD,
+  DEFAULT_PREVIEW_NUMBER_OF_CHARACTERS,
+  DEFAULT_TOTAL_TOOL_TOKEN_THRESHOLD,
+  LargeToolResponseProcessor,
+  largeToolResponse
+});
+//# sourceMappingURL=LargeToolResponse.js.map

package/dist/core/capabilities/builtins/LargeToolResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/core/capabilities/builtins/LargeToolResponse.ts"],"sourcesContent":["import dedent from 'dedent';\nimport type { Logger } from 'winston';\nimport { estimateTokensForString } from '../../llm/usage';\nimport type { ToolCallResult } from '../../mcp/executeToolCalls';\nimport type { Sandbox, SandboxInfo } from '../../sandbox/Sandbox';\nimport { createSandboxLargeToolResponseGuidance, SANDBOX_SCHEMA_INFER_TAG } from '../../sandbox/Sandbox';\nimport { extractErrorLogFields } from '../../util/errorLogFields';\nimport type { AgentCapability } from '../AgentCapability';\nimport type { AgentThreadExecutionContext } from '../AgentContextProcessor';\nimport type { ToolResponseProcessor, ToolResponseProcessorResult } from '../ToolResponseProcessor';\nimport { createDynamicSubAgentLargeToolResponseGuidance } from './DynamicSubAgents';\n\nexport const DEFAULT_INDIVIDUAL_TOOL_TOKEN_THRESHOLD = 6000;\nexport const DEFAULT_TOTAL_TOOL_TOKEN_THRESHOLD = 10000;\nexport const DEFAULT_PREVIEW_NUMBER_OF_CHARACTERS = 100;\nconst FAILURE_MESSAGE_TRUNCATION_LENGTH = 500;\n\ntype ResultCategory = 'failure' | 'sandbox' | 'mcp';\n\ninterface ToolResultWithInfo {\n  toolCallResult: ToolCallResult;\n  originalContent: string;\n  originalTokens: number;\n  category: ResultCategory;\n}\n\nfunction categorize(result: ToolCallResult, sandbox: Sandbox | undefined): ResultCategory {\n  if (result.failure) return 'failure';\n  if (!result.info) {\n    throw new Error(`Unreachable`);\n  }\n  if (sandbox && result.info.toolSet === sandbox) return 'sandbox';\n  return 'mcp';\n}\n\nfunction createContentPreview(content: string, previewChars: number): string {\n  if (content.length <= previewChars * 2) {\n    return content;\n  }\n  return `${content.slice(0, previewChars)}\\n...\\n${content.slice(-previewChars)}`;\n}\n\nexport class LargeToolResponseProcessor implements ToolResponseProcessor {\n  private dynamicSubAgentsPresent: boolean;\n  private individualTokenThreshold: number;\n  private totalTokenThreshold: number;\n  private previewNumberOfCharacters: number;\n  private readonly logger: Logger;\n\n  constructor(param: {\n    dynamicSubAgentsPresent: boolean;\n    individualTokenThreshold: number;\n    totalTokenThreshold: number;\n    previewNumberOfCharacters: number;\n    logger: Logger;\n  }) {\n    if (param.individualTokenThreshold > param.totalTokenThreshold) {\n      throw new Error(\n        `individualTokenThreshold (${String(param.individualTokenThreshold)}) must be <= totalTokenThreshold (${String(param.totalTokenThreshold)})`,\n      );\n    }\n    this.dynamicSubAgentsPresent = param.dynamicSubAgentsPresent;\n    this.individualTokenThreshold = param.individualTokenThreshold;\n    this.totalTokenThreshold = param.totalTokenThreshold;\n    this.previewNumberOfCharacters = param.previewNumberOfCharacters;\n    this.logger = param.logger.child({ module: 'LargeToolResponse' });\n  }\n\n  private createLargeToolResponseGuidance(sandbox: Sandbox | undefined): string {\n    const steps = ['Check if some parameter can be passed in order to reduce the output size.'];\n\n    if (sandbox) {\n      steps.push(createSandboxLargeToolResponseGuidance());\n    }\n\n    if (this.dynamicSubAgentsPresent) {\n      steps.push(createDynamicSubAgentLargeToolResponseGuidance());\n    }\n\n    return `Content too big. To handle a large tool call the Agent can do the following:\\n${steps\n      .map((step, index) => `${String(index + 1)}. ${step}`)\n      .join('\\n')}`;\n  }\n\n  private createFileDumpMessage(params: { filePath: string; preview: string }): string {\n    const { filePath, preview } = params;\n    const steps: string[] = [\n      dedent`Use sandbox to read parts of the file or extract data.\n      Use ${SANDBOX_SCHEMA_INFER_TAG} to undertand the schema.`,\n    ];\n\n    if (this.dynamicSubAgentsPresent) {\n      steps.push(\n        `${createDynamicSubAgentLargeToolResponseGuidance()} The Agent must pass file path to sub-agent also.`,\n      );\n    }\n\n    const guidance = `The Agent can do the following to handle it:\\n${steps\n      .map((step, index) => `${String(index + 1)}. ${step}`)\n      .join('\\n')}`;\n\n    return `Content too large. Result saved to: ${filePath}.\\n\\n${guidance}\\n\\nPreview (first and last ${String(this.previewNumberOfCharacters)} chars):\\n${preview}`;\n  }\n\n  private buildResultsWithInfo(results: ToolCallResult[], sandbox: Sandbox | undefined): ToolResultWithInfo[] {\n    return results.map(toolCallResult => ({\n      toolCallResult,\n      originalContent: toolCallResult.message.content,\n      originalTokens: estimateTokensForString(toolCallResult.message.content),\n      category: categorize(toolCallResult, sandbox),\n    }));\n  }\n\n  private blockResult(\n    entry: ToolResultWithInfo,\n    pendingSandboxDumps: ToolResultWithInfo[],\n    sandbox: Sandbox | undefined,\n  ): number {\n    const preview = createContentPreview(entry.originalContent, this.previewNumberOfCharacters);\n\n    let newContent: string;\n    switch (entry.category) {\n      case 'failure':\n        newContent = entry.originalContent.slice(0, FAILURE_MESSAGE_TRUNCATION_LENGTH);\n        break;\n      case 'sandbox':\n        newContent = `Content too big. The Agent should write to a file if required and use grep and sed.\\n\\nPreview:\\n${preview}`;\n        break;\n      case 'mcp':\n        newContent = `${this.createLargeToolResponseGuidance(sandbox)}\\n\\nPreview (first and last ${String(this.previewNumberOfCharacters)} chars):\\n${preview}`;\n        if (sandbox) {\n          pendingSandboxDumps.push(entry);\n        }\n        break;\n    }\n\n    entry.toolCallResult.message.content = newContent;\n    entry.toolCallResult.isStructuredContent = false;\n    return Math.max(0, entry.originalTokens - estimateTokensForString(newContent));\n  }\n\n  private async uploadToSandboxAndPrependFilePath(\n    entry: ToolResultWithInfo,\n    index: number,\n    sandbox: Sandbox,\n  ): Promise<SandboxInfo | undefined> {\n    if (!entry.toolCallResult.info) {\n      throw new Error(`Unreachable`);\n    }\n    const sanitizedName = entry.toolCallResult.info.originalToolName.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 40);\n    const epoch = Date.now();\n    const fileName = `${sanitizedName}_${String(index)}_${String(epoch)}.txt`;\n    try {\n      const stored = await sandbox.writeArtifact({\n        fileName,\n        content: Buffer.from(entry.originalContent),\n        sourceTool: entry.toolCallResult.info,\n      });\n      const preview = createContentPreview(entry.originalContent, this.previewNumberOfCharacters);\n      entry.toolCallResult.message.content = this.createFileDumpMessage({ filePath: stored.filePath, preview });\n      entry.toolCallResult.isStructuredContent = false;\n      return stored.sandboxCreated;\n    } catch (error) {\n      this.logger.error('Failed to upload to sandbox', extractErrorLogFields(error));\n      return undefined;\n    }\n  }\n\n  private async executeSandboxDumps(entries: ToolResultWithInfo[], sandbox: Sandbox): Promise<SandboxInfo | undefined> {\n    const results = await Promise.all(\n      entries.map((entry, index) => this.uploadToSandboxAndPrependFilePath(entry, index, sandbox)),\n    );\n    return results.find(r => r !== undefined);\n  }\n\n  async process(\n    results: ToolCallResult[],\n    execution: Readonly<AgentThreadExecutionContext>,\n  ): Promise<ToolResponseProcessorResult> {\n    const sandbox = execution.sandbox;\n    const resultsWithInfo = this.buildResultsWithInfo(results, sandbox);\n    let runningTotal = resultsWithInfo.reduce((sum, e) => sum + e.originalTokens, 0);\n\n    if (runningTotal < this.individualTokenThreshold) {\n      return {};\n    }\n\n    const pendingSandboxDumps: ToolResultWithInfo[] = [];\n\n    const unblocked: ToolResultWithInfo[] = [];\n    for (const entry of resultsWithInfo) {\n      if (entry.originalTokens >= this.individualTokenThreshold) {\n        runningTotal -= this.blockResult(entry, pendingSandboxDumps, sandbox);\n      } else {\n        unblocked.push(entry);\n      }\n    }\n\n    const sortedUnblocked = [...unblocked].sort((a, b) => b.originalTokens - a.originalTokens);\n    for (const entry of sortedUnblocked) {\n      if (runningTotal < this.totalTokenThreshold) {\n        break;\n      }\n      runningTotal -= this.blockResult(entry, pendingSandboxDumps, sandbox);\n    }\n\n    const sandboxCreated = sandbox ? await this.executeSandboxDumps(pendingSandboxDumps, sandbox) : undefined;\n    return sandboxCreated !== undefined ? { sandboxCreated } : {};\n  }\n}\n\nexport interface LargeToolResponseSettings {\n  individualTokenThreshold?: number | undefined;\n  totalTokenThreshold?: number | undefined;\n  previewNumberOfCharacters?: number | undefined;\n}\n\nexport function largeToolResponse(options: {\n  dynamicSubAgentsPresent: boolean;\n  settings?: LargeToolResponseSettings | undefined;\n  logger: Logger;\n}): AgentCapability {\n  return {\n    toolResponseProcessors: [\n      new LargeToolResponseProcessor({\n        dynamicSubAgentsPresent: options.dynamicSubAgentsPresent,\n        individualTokenThreshold: options.settings?.individualTokenThreshold ?? DEFAULT_INDIVIDUAL_TOOL_TOKEN_THRESHOLD,\n        totalTokenThreshold: options.settings?.totalTokenThreshold ?? DEFAULT_TOTAL_TOOL_TOKEN_THRESHOLD,\n        previewNumberOfCharacters: options.settings?.previewNumberOfCharacters ?? DEFAULT_PREVIEW_NUMBER_OF_CHARACTERS,\n        logger: options.logger,\n      }),\n    ],\n  };\n}\n"],"mappings":"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","names":["dedent"]}

package/dist/core/capabilities/builtins/LargeToolResponse.mjs

@@ -0,0 +1,186 @@
+// src/core/capabilities/builtins/LargeToolResponse.ts
+import dedent from "dedent";
+import { estimateTokensForString } from "../../llm/usage.mjs";
+import { createSandboxLargeToolResponseGuidance, SANDBOX_SCHEMA_INFER_TAG } from "../../sandbox/Sandbox.mjs";
+import { extractErrorLogFields } from "../../util/errorLogFields.mjs";
+import { createDynamicSubAgentLargeToolResponseGuidance } from "./DynamicSubAgents.mjs";
+var DEFAULT_INDIVIDUAL_TOOL_TOKEN_THRESHOLD = 6e3;
+var DEFAULT_TOTAL_TOOL_TOKEN_THRESHOLD = 1e4;
+var DEFAULT_PREVIEW_NUMBER_OF_CHARACTERS = 100;
+var FAILURE_MESSAGE_TRUNCATION_LENGTH = 500;
+function categorize(result, sandbox) {
+  if (result.failure) return "failure";
+  if (!result.info) {
+    throw new Error(`Unreachable`);
+  }
+  if (sandbox && result.info.toolSet === sandbox) return "sandbox";
+  return "mcp";
+}
+function createContentPreview(content, previewChars) {
+  if (content.length <= previewChars * 2) {
+    return content;
+  }
+  return `${content.slice(0, previewChars)}
+...
+${content.slice(-previewChars)}`;
+}
+var LargeToolResponseProcessor = class {
+  dynamicSubAgentsPresent;
+  individualTokenThreshold;
+  totalTokenThreshold;
+  previewNumberOfCharacters;
+  logger;
+  constructor(param) {
+    if (param.individualTokenThreshold > param.totalTokenThreshold) {
+      throw new Error(
+        `individualTokenThreshold (${String(param.individualTokenThreshold)}) must be <= totalTokenThreshold (${String(param.totalTokenThreshold)})`
+      );
+    }
+    this.dynamicSubAgentsPresent = param.dynamicSubAgentsPresent;
+    this.individualTokenThreshold = param.individualTokenThreshold;
+    this.totalTokenThreshold = param.totalTokenThreshold;
+    this.previewNumberOfCharacters = param.previewNumberOfCharacters;
+    this.logger = param.logger.child({ module: "LargeToolResponse" });
+  }
+  createLargeToolResponseGuidance(sandbox) {
+    const steps = ["Check if some parameter can be passed in order to reduce the output size."];
+    if (sandbox) {
+      steps.push(createSandboxLargeToolResponseGuidance());
+    }
+    if (this.dynamicSubAgentsPresent) {
+      steps.push(createDynamicSubAgentLargeToolResponseGuidance());
+    }
+    return `Content too big. To handle a large tool call the Agent can do the following:
+${steps.map((step, index) => `${String(index + 1)}. ${step}`).join("\n")}`;
+  }
+  createFileDumpMessage(params) {
+    const { filePath, preview } = params;
+    const steps = [
+      dedent`Use sandbox to read parts of the file or extract data.
+      Use ${SANDBOX_SCHEMA_INFER_TAG} to undertand the schema.`
+    ];
+    if (this.dynamicSubAgentsPresent) {
+      steps.push(
+        `${createDynamicSubAgentLargeToolResponseGuidance()} The Agent must pass file path to sub-agent also.`
+      );
+    }
+    const guidance = `The Agent can do the following to handle it:
+${steps.map((step, index) => `${String(index + 1)}. ${step}`).join("\n")}`;
+    return `Content too large. Result saved to: ${filePath}.
+
+${guidance}
+
+Preview (first and last ${String(this.previewNumberOfCharacters)} chars):
+${preview}`;
+  }
+  buildResultsWithInfo(results, sandbox) {
+    return results.map((toolCallResult) => ({
+      toolCallResult,
+      originalContent: toolCallResult.message.content,
+      originalTokens: estimateTokensForString(toolCallResult.message.content),
+      category: categorize(toolCallResult, sandbox)
+    }));
+  }
+  blockResult(entry, pendingSandboxDumps, sandbox) {
+    const preview = createContentPreview(entry.originalContent, this.previewNumberOfCharacters);
+    let newContent;
+    switch (entry.category) {
+      case "failure":
+        newContent = entry.originalContent.slice(0, FAILURE_MESSAGE_TRUNCATION_LENGTH);
+        break;
+      case "sandbox":
+        newContent = `Content too big. The Agent should write to a file if required and use grep and sed.
+
+Preview:
+${preview}`;
+        break;
+      case "mcp":
+        newContent = `${this.createLargeToolResponseGuidance(sandbox)}
+
+Preview (first and last ${String(this.previewNumberOfCharacters)} chars):
+${preview}`;
+        if (sandbox) {
+          pendingSandboxDumps.push(entry);
+        }
+        break;
+    }
+    entry.toolCallResult.message.content = newContent;
+    entry.toolCallResult.isStructuredContent = false;
+    return Math.max(0, entry.originalTokens - estimateTokensForString(newContent));
+  }
+  async uploadToSandboxAndPrependFilePath(entry, index, sandbox) {
+    if (!entry.toolCallResult.info) {
+      throw new Error(`Unreachable`);
+    }
+    const sanitizedName = entry.toolCallResult.info.originalToolName.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 40);
+    const epoch = Date.now();
+    const fileName = `${sanitizedName}_${String(index)}_${String(epoch)}.txt`;
+    try {
+      const stored = await sandbox.writeArtifact({
+        fileName,
+        content: Buffer.from(entry.originalContent),
+        sourceTool: entry.toolCallResult.info
+      });
+      const preview = createContentPreview(entry.originalContent, this.previewNumberOfCharacters);
+      entry.toolCallResult.message.content = this.createFileDumpMessage({ filePath: stored.filePath, preview });
+      entry.toolCallResult.isStructuredContent = false;
+      return stored.sandboxCreated;
+    } catch (error) {
+      this.logger.error("Failed to upload to sandbox", extractErrorLogFields(error));
+      return void 0;
+    }
+  }
+  async executeSandboxDumps(entries, sandbox) {
+    const results = await Promise.all(
+      entries.map((entry, index) => this.uploadToSandboxAndPrependFilePath(entry, index, sandbox))
+    );
+    return results.find((r) => r !== void 0);
+  }
+  async process(results, execution) {
+    const sandbox = execution.sandbox;
+    const resultsWithInfo = this.buildResultsWithInfo(results, sandbox);
+    let runningTotal = resultsWithInfo.reduce((sum, e) => sum + e.originalTokens, 0);
+    if (runningTotal < this.individualTokenThreshold) {
+      return {};
+    }
+    const pendingSandboxDumps = [];
+    const unblocked = [];
+    for (const entry of resultsWithInfo) {
+      if (entry.originalTokens >= this.individualTokenThreshold) {
+        runningTotal -= this.blockResult(entry, pendingSandboxDumps, sandbox);
+      } else {
+        unblocked.push(entry);
+      }
+    }
+    const sortedUnblocked = [...unblocked].sort((a, b) => b.originalTokens - a.originalTokens);
+    for (const entry of sortedUnblocked) {
+      if (runningTotal < this.totalTokenThreshold) {
+        break;
+      }
+      runningTotal -= this.blockResult(entry, pendingSandboxDumps, sandbox);
+    }
+    const sandboxCreated = sandbox ? await this.executeSandboxDumps(pendingSandboxDumps, sandbox) : void 0;
+    return sandboxCreated !== void 0 ? { sandboxCreated } : {};
+  }
+};
+function largeToolResponse(options) {
+  return {
+    toolResponseProcessors: [
+      new LargeToolResponseProcessor({
+        dynamicSubAgentsPresent: options.dynamicSubAgentsPresent,
+        individualTokenThreshold: options.settings?.individualTokenThreshold ?? DEFAULT_INDIVIDUAL_TOOL_TOKEN_THRESHOLD,
+        totalTokenThreshold: options.settings?.totalTokenThreshold ?? DEFAULT_TOTAL_TOOL_TOKEN_THRESHOLD,
+        previewNumberOfCharacters: options.settings?.previewNumberOfCharacters ?? DEFAULT_PREVIEW_NUMBER_OF_CHARACTERS,
+        logger: options.logger
+      })
+    ]
+  };
+}
+export {
+  DEFAULT_INDIVIDUAL_TOOL_TOKEN_THRESHOLD,
+  DEFAULT_PREVIEW_NUMBER_OF_CHARACTERS,
+  DEFAULT_TOTAL_TOOL_TOKEN_THRESHOLD,
+  LargeToolResponseProcessor,
+  largeToolResponse
+};
+//# sourceMappingURL=LargeToolResponse.mjs.map