@polos/sdk 0.1.1 → 0.1.3

package/dist/index.cjs

@@ -8,10 +8,34 @@ var Fastify = require('fastify');
 var api = require('@opentelemetry/api');
 var sdkTraceBase = require('@opentelemetry/sdk-trace-base');
 var contextAsyncHooks = require('@opentelemetry/context-async-hooks');
+var zod = require('zod');
+var child_process = require('child_process');
+var fs2 = require('fs/promises');
+var path = require('path');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
 var Fastify__default = /*#__PURE__*/_interopDefault(Fastify);
+var fs2__namespace = /*#__PURE__*/_interopNamespace(fs2);
+var path__namespace = /*#__PURE__*/_interopNamespace(path);
 
 // src/core/registry.ts
 var WorkflowNotFoundError = class extends Error {
@@ -32,9 +56,6 @@ function createWorkflowRegistry() {
   const workflows = /* @__PURE__ */ new Map();
   return {
     register(workflow) {
-      if (workflows.has(workflow.id)) {
-        throw new DuplicateWorkflowError(workflow.id);
-      }
       workflows.set(workflow.id, workflow);
     },
     get(workflowId) {
@@ -212,6 +233,12 @@ var OrchestratorClient = class {
     this.timeout = config.timeout ?? 3e4;
     this.maxRetries = config.maxRetries ?? 3;
   }
+  /**
+   * Get the API URL.
+   */
+  getApiUrl() {
+    return this.apiUrl;
+  }
   /**
    * Get the project ID.
    */
@@ -235,8 +262,8 @@ var OrchestratorClient = class {
   /**
    * Make an HTTP request with retry logic.
    */
-  async request(method, path, options) {
-    const url = `${this.apiUrl}${path}`;
+  async request(method, path3, options) {
+    const url = `${this.apiUrl}${path3}`;
     const retries = options?.retries ?? this.maxRetries;
     let lastError;
     for (let attempt = 0; attempt <= retries; attempt++) {
@@ -288,7 +315,7 @@ var OrchestratorClient = class {
         }
         if (attempt < retries) {
           const delay = Math.min(1e3 * Math.pow(2, attempt), 16e3);
-          await new Promise((resolve) => setTimeout(resolve, delay));
+          await new Promise((resolve8) => setTimeout(resolve8, delay));
         }
       }
     }
@@ -727,7 +754,7 @@ var OrchestratorClient = class {
       if (execution.status === "completed" || execution.status === "failed" || execution.status === "cancelled") {
         return execution;
       }
-      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+      await new Promise((resolve8) => setTimeout(resolve8, pollInterval));
     }
     throw new Error(`Execution ${executionId} timed out after ${String(timeout)}ms`);
   }
@@ -1193,6 +1220,46 @@ function isToolWorkflow(workflow) {
 }
 function defineTool(config, handler) {
   const toolParameters = config.inputSchema ? zodToJsonSchema.zodToJsonSchema(config.inputSchema, { target: "openApi3" }) : { type: "object", properties: {} };
+  const effectiveHandler = config.approval === "always" ? async (ctx, input) => {
+    const approvalId = await ctx.step.uuid("_approval_id");
+    const response = await ctx.step.suspend(
+      `approve_${config.id}_${approvalId}`,
+      {
+        data: {
+          _form: {
+            title: `Approve tool: ${config.id}`,
+            description: `The agent wants to use the "${config.id}" tool.`,
+            fields: [
+              {
+                key: "approved",
+                type: "boolean",
+                label: "Approve this tool call?",
+                required: true,
+                default: false
+              },
+              {
+                key: "feedback",
+                type: "textarea",
+                label: "Feedback for the agent (optional)",
+                description: "If rejecting, tell the agent what to do instead.",
+                required: false
+              }
+            ],
+            context: { tool: config.id, input }
+          },
+          _source: "tool_approval",
+          _tool: config.id
+        }
+      }
+    );
+    if (response.data?.approved !== true) {
+      const feedback = response.data?.feedback;
+      throw new Error(
+        `Tool "${config.id}" was rejected by the user.${feedback ? ` Feedback: ${feedback}` : ""}`
+      );
+    }
+    return handler(ctx, input);
+  } : handler;
   const workflow = defineWorkflow(
     {
       id: config.id,
@@ -1205,7 +1272,8 @@ function defineTool(config, handler) {
       onStart: config.onStart,
       onEnd: config.onEnd
     },
-    handler
+    effectiveHandler,
+    config.autoRegister === void 0 ? void 0 : { autoRegister: config.autoRegister }
   );
   const toolWorkflow = Object.assign(workflow, {
     toolDescription: config.description,
@@ -1249,7 +1317,7 @@ function calculateDelay(attempt, options) {
   return Math.round(delay);
 }
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 async function retry(fn, options = {}) {
   const opts = { ...DEFAULT_OPTIONS, ...options };
@@ -1438,7 +1506,7 @@ function createStepHelper(options) {
       if (options2.days) totalSeconds += options2.days * 86400;
       if (options2.weeks) totalSeconds += options2.weeks * 604800;
       const totalMs = totalSeconds * 1e3;
-      await new Promise((resolve) => setTimeout(resolve, totalMs));
+      await new Promise((resolve8) => setTimeout(resolve8, totalMs));
       store.set(key, { wait_until: new Date(Date.now() + totalMs).toISOString() });
     },
     async waitUntil(key, date) {
@@ -1446,7 +1514,7 @@ function createStepHelper(options) {
       if (cached) return;
       const now = Date.now();
       const waitMs = Math.max(0, date.getTime() - now);
-      await new Promise((resolve) => setTimeout(resolve, waitMs));
+      await new Promise((resolve8) => setTimeout(resolve8, waitMs));
       store.set(key, { wait_until: date.toISOString() });
     },
     // eslint-disable-next-line @typescript-eslint/require-await -- stub implementation
@@ -1739,11 +1807,18 @@ function convertMiddlewareToolCallToPython(tc) {
 function convertVercelUsageToPython(usage) {
   const input = usage.inputTokens ?? 0;
   const output = usage.outputTokens ?? 0;
-  return {
+  const result = {
     input_tokens: input,
     output_tokens: output,
     total_tokens: usage.totalTokens ?? input + output
   };
+  if (usage.inputTokenDetails?.cacheReadTokens != null) {
+    result.cache_read_input_tokens = usage.inputTokenDetails.cacheReadTokens;
+  }
+  if (usage.inputTokenDetails?.cacheWriteTokens != null) {
+    result.cache_creation_input_tokens = usage.inputTokenDetails.cacheWriteTokens;
+  }
+  return result;
 }
 function convertFinishReason(reason) {
   if (!reason) return null;
@@ -1758,6 +1833,41 @@ function convertFinishReason(reason) {
 }
 
 // src/llm/llm.ts
+var ANTHROPIC_CACHE_BREAKPOINT = {
+  anthropic: { cacheControl: { type: "ephemeral" } }
+};
+function isAnthropicModel(model) {
+  return getModelProvider(model).startsWith("anthropic");
+}
+function applyAnthropicCacheControl(args, model) {
+  if (!isAnthropicModel(model)) return;
+  if (typeof args["system"] === "string") {
+    args["system"] = {
+      role: "system",
+      content: args["system"],
+      providerOptions: ANTHROPIC_CACHE_BREAKPOINT
+    };
+  }
+  const tools = args["tools"];
+  if (tools) {
+    const toolNames = Object.keys(tools);
+    if (toolNames.length > 0) {
+      const lastToolName = toolNames[toolNames.length - 1];
+      tools[lastToolName] = {
+        ...tools[lastToolName],
+        providerOptions: ANTHROPIC_CACHE_BREAKPOINT
+      };
+    }
+  }
+  const messages = args["messages"];
+  if (messages && messages.length > 0) {
+    const lastMsg = messages[messages.length - 1];
+    messages[messages.length - 1] = {
+      ...lastMsg,
+      providerOptions: ANTHROPIC_CACHE_BREAKPOINT
+    };
+  }
+}
 function buildGenerateArgs(model, messages, options) {
   const args = { model, messages };
   const tools = convertToolsToVercel(options.tools);
@@ -1769,6 +1879,7 @@ function buildGenerateArgs(model, messages, options) {
   if (options.outputSchema) {
     args["experimental_output"] = ai.Output.object({ schema: options.outputSchema });
   }
+  applyAnthropicCacheControl(args, model);
   return args;
 }
 var LLM = class {
@@ -2514,11 +2625,12 @@ async function agentStreamFunction(ctx, payload, agentDef) {
   let finalInputTokens = 0;
   let finalOutputTokens = 0;
   let finalTotalTokens = 0;
+  let finalCacheReadInputTokens = 0;
+  let finalCacheCreationInputTokens = 0;
   let lastLlmResultContent = null;
   const allToolResults = [];
   const steps = [];
   let endSteps = false;
-  let toolResults;
   let checkedStructuredOutput = false;
   let cachedHistoryMessages = null;
   if (agentDef.conversationHistory > 0 && conversationId) {
@@ -2559,7 +2671,7 @@ async function agentStreamFunction(ctx, payload, agentDef) {
       break;
     }
   }
-  const safetyMaxSteps = hasMaxStepsCondition ? null : parseInt(process.env["POLOS_AGENT_MAX_STEPS"] ?? "10", 10);
+  const safetyMaxSteps = hasMaxStepsCondition ? null : parseInt(process.env["POLOS_AGENT_MAX_STEPS"] ?? "20", 10);
   const execCtxForPublish = getExecutionContext();
   const publishEvent = async (topic, eventData) => {
     if (execCtxForPublish?.orchestratorClient) {
@@ -2608,7 +2720,6 @@ async function agentStreamFunction(ctx, payload, agentDef) {
         agent_step: agentStep,
         guardrails,
         guardrail_max_retries: guardrailMaxRetries,
-        tool_results: toolResults,
         outputSchema: outputSchemaForLlm
       });
       if (guardrails.length > 0 && streaming && llmResult.content) {
@@ -2637,17 +2748,21 @@ async function agentStreamFunction(ctx, payload, agentDef) {
           temperature: agentConfig.temperature,
           maxTokens: agentConfig.maxOutputTokens,
           agent_step: agentStep,
-          tool_results: toolResults,
           outputSchema: outputSchemaForLlm
         },
         publishEvent
       );
     }
-    toolResults = void 0;
     if (llmResult.usage) {
       finalInputTokens += llmResult.usage.input_tokens;
       finalOutputTokens += llmResult.usage.output_tokens;
       finalTotalTokens += llmResult.usage.total_tokens;
+      if (llmResult.usage.cache_read_input_tokens) {
+        finalCacheReadInputTokens += llmResult.usage.cache_read_input_tokens;
+      }
+      if (llmResult.usage.cache_creation_input_tokens) {
+        finalCacheCreationInputTokens += llmResult.usage.cache_creation_input_tokens;
+      }
     }
     lastLlmResultContent = llmResult.content;
     const toolCalls = llmResult.tool_calls ?? [];
@@ -2656,6 +2771,7 @@ async function agentStreamFunction(ctx, payload, agentDef) {
         `LLM failed to generate output: agent_id=${agentDef.id}, agent_step=${String(agentStep)}`
       );
     }
+    conversationMessages.push(...llmResult.raw_output);
     const batchWorkflows = [];
     const toolCallList = [];
     let toolResultsRecordedList = [];
@@ -2716,7 +2832,7 @@ async function agentStreamFunction(ctx, payload, agentDef) {
         const toolSpec = batchWorkflows[i];
         const toolCallInfo = toolCallList[i];
         const toolName = toolCallInfo.tool_name;
-        const toolResult = batchToolResult;
+        const toolResult = batchToolResult.success ? batchToolResult.result : `Error: ${batchToolResult.error ?? "unknown error"}`;
         const toolCallId = toolCallInfo.tool_call_id;
         const toolCallCallId = toolCallInfo.tool_call_call_id;
         if (agentDef.agentHooks.onToolEnd.length > 0) {
@@ -2747,7 +2863,8 @@ async function agentStreamFunction(ctx, payload, agentDef) {
         });
       }
       allToolResults.push(...toolResultsRecordedList);
-      toolResults = currentIterationToolResults;
+      const toolResultMessages = convertToolResultsToMessages(currentIterationToolResults);
+      conversationMessages.push(...toolResultMessages);
     }
     steps.push({
       step: agentStep,
@@ -2755,7 +2872,7 @@ async function agentStreamFunction(ctx, payload, agentDef) {
       tool_calls: toolCalls,
       tool_results: toolResultsRecordedList,
       usage: llmResult.usage,
-      raw_output: llmResult.raw_output
+      raw_output: conversationMessages
     });
     if (agentDef.agentHooks.onAgentStepEnd.length > 0) {
       const hookResult = await executeHookChain(agentDef.agentHooks.onAgentStepEnd, {
@@ -2772,7 +2889,7 @@ async function agentStreamFunction(ctx, payload, agentDef) {
         throw new Error(hookResult.error ?? "on_agent_step_end hook failed");
       }
     }
-    if (toolResults === void 0 || toolResults.length === 0) {
+    if (currentIterationToolResults.length === 0) {
       endSteps = true;
     }
     if (stopConditions.length > 0 && !endSteps) {
@@ -2805,7 +2922,6 @@ async function agentStreamFunction(ctx, payload, agentDef) {
       checkedStructuredOutput = true;
       if (!parseResult.success) {
         endSteps = false;
-        conversationMessages = llmResult.raw_output;
         const schemaJson = JSON.stringify(agentDef.outputSchema, null, 2);
         const fixPrompt = `The previous response was not valid JSON matching the required schema. Please reformat your response to be valid JSON that strictly conforms to this schema:
 
@@ -2818,9 +2934,6 @@ Please provide ONLY valid JSON that matches the schema, with no additional text
       }
     }
     if (!endSteps) {
-      if (!checkedStructuredOutput) {
-        conversationMessages = llmResult.raw_output;
-      }
       agentStep++;
     }
   }
@@ -2873,7 +2986,11 @@ Please provide ONLY valid JSON that matches the schema, with no additional text
     usage: {
       input_tokens: finalInputTokens,
       output_tokens: finalOutputTokens,
-      total_tokens: finalTotalTokens
+      total_tokens: finalTotalTokens,
+      ...finalCacheReadInputTokens > 0 && { cache_read_input_tokens: finalCacheReadInputTokens },
+      ...finalCacheCreationInputTokens > 0 && {
+        cache_creation_input_tokens: finalCacheCreationInputTokens
+      }
     }
   };
 }
@@ -3034,7 +3151,7 @@ function defineAgent(config) {
         maxOutputTokens: config.maxOutputTokens
       },
       input,
-      streaming: streamingFlag ?? true,
+      streaming: streamingFlag ?? config.streamToWorkflow ?? false,
       conversation_id: conversationIdValue
     };
     return agentStreamFunction(ctx, streamPayload, {
@@ -4091,16 +4208,27 @@ function createOrchestratorStepHelper(orchestratorClient, cachedSteps, execCtx,
       if (items.length === 0) return [];
       const existing = checkExistingStep(key);
       if (existing) {
-        const raw = handleExistingStep(existing);
+        let raw;
+        try {
+          raw = handleExistingStep(existing);
+        } catch {
+          raw = existing.outputs;
+        }
         if (Array.isArray(raw)) {
           return raw.map((item) => {
-            if (item && typeof item === "object" && "result" in item) {
-              return item["result"];
+            if (item && typeof item === "object" && "success" in item) {
+              const rec = item;
+              return {
+                workflowId: typeof rec["workflow_id"] === "string" ? rec["workflow_id"] : "",
+                success: rec["success"] === true,
+                result: rec["result"] ?? null,
+                error: typeof rec["error"] === "string" ? rec["error"] : null
+              };
             }
-            return item;
+            return { workflowId: "", success: true, result: item, error: null };
           });
         }
-        return raw;
+        return raw.map((r) => ({ workflowId: "", success: true, result: r, error: null }));
       }
       const workflows = items.map((item) => {
         const workflowId = typeof item.workflow === "string" ? item.workflow : item.workflow.id;
@@ -4163,7 +4291,7 @@ function createOrchestratorStepHelper(orchestratorClient, cachedSteps, execCtx,
       });
       const waitThreshold = Number(process.env["POLOS_WAIT_THRESHOLD_SECONDS"] ?? "10");
       if (totalSeconds <= waitThreshold) {
-        await new Promise((resolve) => setTimeout(resolve, totalSeconds * 1e3));
+        await new Promise((resolve8) => setTimeout(resolve8, totalSeconds * 1e3));
         await saveStepOutput(key, { wait_until: waitUntil.toISOString() });
         return;
       }
@@ -4199,7 +4327,7 @@ function createOrchestratorStepHelper(orchestratorClient, cachedSteps, execCtx,
       });
       const waitThreshold = Number(process.env["POLOS_WAIT_THRESHOLD_SECONDS"] ?? "10");
       if (waitSeconds <= waitThreshold) {
-        await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1e3));
+        await new Promise((resolve8) => setTimeout(resolve8, waitSeconds * 1e3));
         await saveStepOutput(key, { wait_until: date.toISOString() });
         return;
       }
@@ -4273,12 +4401,14 @@ function createOrchestratorStepHelper(orchestratorClient, cachedSteps, execCtx,
         return handleExistingStep(existing);
       }
       const topic = `workflow/${execCtx.rootWorkflowId}/${execCtx.rootExecutionId}`;
+      const approvalUrl = `${orchestratorClient.getApiUrl()}/approve/${execCtx.rootExecutionId}/${key}`;
+      const eventData = options?.data != null && typeof options.data === "object" && !Array.isArray(options.data) ? { ...options.data, _approval_url: approvalUrl } : { _original: options?.data, _approval_url: approvalUrl };
       await orchestratorClient.publishEvent({
         topic,
         events: [
           {
             eventType: `suspend_${key}`,
-            data: options?.data
+            data: eventData
           }
         ],
         executionId: execCtx.executionId,
@@ -4941,10 +5071,10 @@ var Worker = class {
       process.on("SIGINT", signalHandler);
       process.on("SIGTERM", signalHandler);
       this.signalHandler = signalHandler;
-      await new Promise((resolve) => {
+      await new Promise((resolve8) => {
         const checkState = () => {
           if (this.state === "stopping" || this.state === "stopped") {
-            resolve();
+            resolve8();
           } else {
             setTimeout(checkState, 100);
           }
@@ -4983,7 +5113,7 @@ var Worker = class {
     const waitTimeout = 3e4;
     const waitStart = Date.now();
     while (this.activeExecutions.size > 0 && Date.now() - waitStart < waitTimeout) {
-      await new Promise((resolve) => setTimeout(resolve, 100));
+      await new Promise((resolve8) => setTimeout(resolve8, 100));
     }
     if (this.activeExecutions.size > 0) {
       logger6.warn(`${String(this.activeExecutions.size)} executions did not complete in time`);
@@ -5539,8 +5669,1009 @@ var GuardrailResult2 = {
     error
   })
 };
+var askUserInputSchema = zod.z.object({
+  question: zod.z.string().describe("The question to ask the user"),
+  title: zod.z.string().optional().describe("Short title for the question (shown as heading)"),
+  fields: zod.z.array(
+    zod.z.object({
+      key: zod.z.string().describe("Unique key for this field"),
+      type: zod.z.enum(["text", "textarea", "number", "boolean", "select"]).describe("Field type"),
+      label: zod.z.string().describe("Label shown to user"),
+      description: zod.z.string().optional().describe("Help text for the field"),
+      required: zod.z.boolean().optional().describe("Whether this field is required"),
+      options: zod.z.array(
+        zod.z.object({
+          label: zod.z.string(),
+          value: zod.z.string()
+        })
+      ).optional().describe("Options for select fields")
+    })
+  ).optional().describe(
+    "Structured form fields for the response. If omitted, shows a single text response field."
+  )
+});
+function createAskUserTool() {
+  return defineTool(
+    {
+      id: "ask_user",
+      description: "Ask the user a question and wait for their response. Use this when you need clarification, a decision, or any input from the user. You can define structured fields (text, select, boolean, etc.) for specific response formats, or omit fields for a free-text response.",
+      inputSchema: askUserInputSchema
+    },
+    async (ctx, input) => {
+      const fields = input.fields ?? [
+        {
+          key: "response",
+          type: "textarea",
+          label: input.question,
+          required: true
+        }
+      ];
+      const askId = await ctx.step.uuid("_ask_user_id");
+      const response = await ctx.step.suspend(`ask_user_${askId}`, {
+        data: {
+          _form: {
+            title: input.title ?? "Agent Question",
+            description: input.question,
+            fields
+          },
+          _source: "ask_user",
+          _tool: "ask_user"
+        }
+      });
+      return response?.["data"] ?? {};
+    }
+  );
+}
+var webSearchInputSchema = zod.z.object({
+  query: zod.z.string().describe("The search query"),
+  maxResults: zod.z.number().optional().describe("Maximum number of results to return"),
+  topic: zod.z.enum(["general", "news"]).optional().describe("Topic filter: general web search or news")
+});
+function createTavilySearchFn(config) {
+  return async (query, options) => {
+    const apiKey = config.apiKey ?? process.env["TAVILY_API_KEY"];
+    if (!apiKey) {
+      throw new Error(
+        "Tavily API key is required. Provide it via the apiKey option or set the TAVILY_API_KEY environment variable."
+      );
+    }
+    const baseUrl = (config.baseUrl ?? "https://api.tavily.com").replace(/\/+$/, "");
+    const body = {
+      query,
+      max_results: options.maxResults,
+      search_depth: config.searchDepth ?? "basic",
+      include_answer: config.includeAnswer ?? true,
+      include_raw_content: config.includeRawContent ?? false,
+      topic: options.topic
+    };
+    const response = await fetch(`${baseUrl}/search`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`
+      },
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      let errorMessage;
+      try {
+        const errorBody = await response.json();
+        errorMessage = typeof errorBody["detail"] === "string" ? errorBody["detail"] : JSON.stringify(errorBody);
+      } catch {
+        errorMessage = await response.text();
+      }
+      throw new Error(`Tavily API error (${String(response.status)}): ${errorMessage}`);
+    }
+    const data = await response.json();
+    return {
+      query: data.query,
+      answer: data.answer,
+      results: data.results.map((r) => ({
+        title: r.title,
+        url: r.url,
+        content: r.content,
+        score: r.score,
+        publishedDate: r.published_date
+      }))
+    };
+  };
+}
+function createWebSearchTool(config) {
+  const toolId = config?.toolId ?? "web_search";
+  const defaultMaxResults = config?.maxResults ?? 5;
+  const defaultTopic = config?.topic ?? "general";
+  const searchFn = config?.search ?? createTavilySearchFn(config ?? {});
+  return defineTool(
+    {
+      id: toolId,
+      description: "Search the web for current information. Returns a list of relevant results with titles, URLs, and content snippets.",
+      inputSchema: webSearchInputSchema,
+      approval: config?.approval
+    },
+    async (ctx, input) => {
+      const options = {
+        maxResults: input.maxResults ?? defaultMaxResults,
+        topic: input.topic ?? defaultTopic
+      };
+      const result = await ctx.step.run("web_search", () => searchFn(input.query, options), {
+        input: { query: input.query, options }
+      });
+      return result;
+    }
+  );
+}
+
+// src/execution/output.ts
+var DEFAULT_MAX_CHARS = 1e5;
+var HEAD_RATIO = 0.2;
+function truncateOutput(output, maxChars) {
+  const max = maxChars ?? DEFAULT_MAX_CHARS;
+  if (output.length <= max) {
+    return { text: output, truncated: false };
+  }
+  const headSize = Math.floor(max * HEAD_RATIO);
+  const tailSize = max - headSize;
+  const omitted = output.length - headSize - tailSize;
+  const head = output.slice(0, headSize);
+  const tail = output.slice(-tailSize);
+  const text = `${head}
+
+--- truncated ${String(omitted)} characters ---
+
+${tail}`;
+  return { text, truncated: true };
+}
+function isBinary(buffer) {
+  const checkLength = Math.min(buffer.length, 8192);
+  for (let i = 0; i < checkLength; i++) {
+    if (buffer[i] === 0) {
+      return true;
+    }
+  }
+  return false;
+}
+function parseGrepOutput(output) {
+  if (!output.trim()) {
+    return [];
+  }
+  const matches = [];
+  const lines = output.split("\n");
+  for (const line of lines) {
+    if (!line) continue;
+    const match = /^(.+?):(\d+):(.*)$/.exec(line);
+    if (match?.[1] && match[2] && match[3] !== void 0) {
+      matches.push({ path: match[1], line: parseInt(match[2], 10), text: match[3] });
+    }
+  }
+  return matches;
+}
+function stripAnsi(text) {
+  return text.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "");
+}
+
+// src/execution/docker.ts
+var DEFAULT_CONTAINER_WORKDIR = "/workspace";
+var DEFAULT_TIMEOUT_SECONDS = 300;
+var DEFAULT_MAX_OUTPUT_CHARS = 1e5;
+function spawnCommand(command, args, options) {
+  return new Promise((resolve8, reject) => {
+    let settled = false;
+    const settle = (fn) => {
+      if (!settled) {
+        settled = true;
+        fn();
+      }
+    };
+    const proc = child_process.spawn(command, args, { stdio: ["pipe", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let killed = false;
+    proc.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+    proc.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+    proc.stdin.on("error", () => {
+    });
+    proc.stdout.on("error", () => {
+    });
+    proc.stderr.on("error", () => {
+    });
+    const timeoutMs = (options?.timeout ?? DEFAULT_TIMEOUT_SECONDS) * 1e3;
+    const timer = setTimeout(() => {
+      killed = true;
+      proc.kill("SIGKILL");
+    }, timeoutMs);
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      settle(() => {
+        if (killed) {
+          resolve8({
+            exitCode: 137,
+            stdout,
+            stderr: stderr + "\n[Process killed: timeout exceeded]"
+          });
+        } else {
+          resolve8({ exitCode: code ?? 1, stdout, stderr });
+        }
+      });
+    });
+    proc.on("error", (err) => {
+      clearTimeout(timer);
+      settle(() => {
+        reject(err);
+      });
+    });
+    if (options?.stdin) {
+      proc.stdin.write(options.stdin, () => {
+        proc.stdin.end();
+      });
+    } else {
+      proc.stdin.end();
+    }
+  });
+}
+var DockerEnvironment = class {
+  type = "docker";
+  containerId = null;
+  containerName;
+  config;
+  containerWorkdir;
+  maxOutputChars;
+  constructor(config, maxOutputChars) {
+    this.config = config;
+    this.containerWorkdir = config.containerWorkdir ?? DEFAULT_CONTAINER_WORKDIR;
+    this.containerName = `polos-sandbox-${crypto.randomUUID().slice(0, 8)}`;
+    this.maxOutputChars = maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS;
+  }
+  async initialize() {
+    const args = [
+      "run",
+      "-d",
+      "--name",
+      this.containerName,
+      "-v",
+      `${this.config.workspaceDir}:${this.containerWorkdir}:rw`,
+      "-w",
+      this.containerWorkdir
+    ];
+    if (this.config.memory) {
+      args.push("--memory", this.config.memory);
+    }
+    if (this.config.cpus) {
+      args.push("--cpus", this.config.cpus);
+    }
+    args.push("--network", this.config.network ?? "none");
+    if (this.config.env) {
+      for (const [key, value] of Object.entries(this.config.env)) {
+        args.push("-e", `${key}=${value}`);
+      }
+    }
+    args.push(this.config.image, "sleep", "infinity");
+    const result = await spawnCommand("docker", args, { timeout: 60 });
+    if (result.exitCode !== 0) {
+      throw new Error(`Failed to create Docker container: ${result.stderr.trim()}`);
+    }
+    this.containerId = result.stdout.trim().slice(0, 12);
+    if (this.config.setupCommand) {
+      const setupResult = await this.exec(this.config.setupCommand);
+      if (setupResult.exitCode !== 0) {
+        throw new Error(
+          `Setup command failed (exit ${String(setupResult.exitCode)}): ${setupResult.stderr.trim()}`
+        );
+      }
+    }
+  }
+  async exec(command, opts) {
+    this.assertInitialized();
+    const args = opts?.stdin ? ["exec", "-i"] : ["exec"];
+    const cwd = opts?.cwd ?? this.containerWorkdir;
+    args.push("-w", cwd);
+    if (opts?.env) {
+      for (const [key, value] of Object.entries(opts.env)) {
+        args.push("-e", `${key}=${value}`);
+      }
+    }
+    args.push(this.containerName, "sh", "-c", command);
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_SECONDS;
+    const start = Date.now();
+    const result = await spawnCommand("docker", args, {
+      timeout,
+      stdin: opts?.stdin
+    });
+    const durationMs = Date.now() - start;
+    const { text: stdout, truncated: stdoutTruncated } = truncateOutput(
+      stripAnsi(result.stdout),
+      this.maxOutputChars
+    );
+    const { text: stderr } = truncateOutput(stripAnsi(result.stderr), this.maxOutputChars);
+    return {
+      exitCode: result.exitCode,
+      stdout,
+      stderr,
+      durationMs,
+      truncated: stdoutTruncated
+    };
+  }
+  async readFile(filePath) {
+    const hostPath = this.toHostPath(filePath);
+    const buffer = await fs2__namespace.readFile(hostPath);
+    if (isBinary(buffer)) {
+      throw new Error(`Cannot read binary file: ${filePath}`);
+    }
+    return buffer.toString("utf-8");
+  }
+  async writeFile(filePath, content) {
+    const hostPath = this.toHostPath(filePath);
+    await fs2__namespace.mkdir(path__namespace.dirname(hostPath), { recursive: true });
+    await fs2__namespace.writeFile(hostPath, content, "utf-8");
+  }
+  async fileExists(filePath) {
+    const hostPath = this.toHostPath(filePath);
+    try {
+      await fs2__namespace.access(hostPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async glob(pattern, opts) {
+    const cwd = opts?.cwd ?? this.containerWorkdir;
+    let command = `find ${cwd} -type f -name '${pattern}'`;
+    if (opts?.ignore) {
+      for (const ignore of opts.ignore) {
+        command += ` ! -path '${ignore}'`;
+      }
+    }
+    command += " 2>/dev/null | sort | head -1000";
+    const result = await this.exec(command);
+    if (!result.stdout.trim()) return [];
+    return result.stdout.trim().split("\n").filter(Boolean);
+  }
+  async grep(pattern, opts) {
+    const cwd = opts?.cwd ?? this.containerWorkdir;
+    const maxResults = opts?.maxResults ?? 100;
+    let command = "grep -rn";
+    if (opts?.contextLines !== void 0) {
+      command += ` -C ${String(opts.contextLines)}`;
+    }
+    if (opts?.include) {
+      for (const inc of opts.include) {
+        command += ` --include='${inc}'`;
+      }
+    }
+    const escapedPattern = pattern.replace(/'/g, "'\\''");
+    command += ` -- '${escapedPattern}' ${cwd}`;
+    command += ` 2>/dev/null | head -${String(maxResults)}`;
+    const result = await this.exec(command);
+    return parseGrepOutput(result.stdout);
+  }
+  async destroy() {
+    if (!this.containerId) return;
+    try {
+      await spawnCommand("docker", ["rm", "-f", this.containerName], { timeout: 30 });
+    } finally {
+      this.containerId = null;
+    }
+  }
+  getCwd() {
+    return this.containerWorkdir;
+  }
+  getInfo() {
+    return {
+      type: "docker",
+      cwd: this.containerWorkdir,
+      sandboxId: this.containerId ?? void 0
+    };
+  }
+  /**
+   * Translate a container path to the corresponding host filesystem path.
+   * Validates the path stays within the workspace to prevent traversal.
+   */
+  toHostPath(containerPath) {
+    const resolved = path__namespace.posix.resolve(this.containerWorkdir, containerPath);
+    if (!resolved.startsWith(this.containerWorkdir)) {
+      throw new Error(`Path traversal detected: "${containerPath}" resolves outside workspace`);
+    }
+    const relative2 = path__namespace.posix.relative(this.containerWorkdir, resolved);
+    return path__namespace.join(this.config.workspaceDir, relative2);
+  }
+  /**
+   * Translate a host filesystem path to the corresponding container path.
+   */
+  toContainerPath(hostPath) {
+    const resolved = path__namespace.resolve(hostPath);
+    if (!resolved.startsWith(this.config.workspaceDir)) {
+      throw new Error(
+        `Path outside workspace: "${hostPath}" is not within "${this.config.workspaceDir}"`
+      );
+    }
+    const relative2 = path__namespace.relative(this.config.workspaceDir, resolved);
+    return path__namespace.posix.join(this.containerWorkdir, relative2);
+  }
+  assertInitialized() {
+    if (!this.containerId) {
+      throw new Error("Docker environment not initialized. Call initialize() first.");
+    }
+  }
+};
+var DEFAULT_TIMEOUT_SECONDS2 = 300;
+var DEFAULT_MAX_OUTPUT_CHARS2 = 1e5;
+function spawnLocal(command, options) {
+  return new Promise((resolve8, reject) => {
+    let settled = false;
+    const settle = (fn) => {
+      if (!settled) {
+        settled = true;
+        fn();
+      }
+    };
+    const proc = child_process.spawn("sh", ["-c", command], {
+      cwd: options.cwd,
+      env: options.env ? { ...process.env, ...options.env } : void 0,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    let killed = false;
+    proc.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+    proc.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+    proc.stdin.on("error", () => {
+    });
+    proc.stdout.on("error", () => {
+    });
+    proc.stderr.on("error", () => {
+    });
+    const timeoutMs = (options.timeout ?? DEFAULT_TIMEOUT_SECONDS2) * 1e3;
+    const timer = setTimeout(() => {
+      killed = true;
+      proc.kill("SIGKILL");
+    }, timeoutMs);
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      settle(() => {
+        if (killed) {
+          resolve8({
+            exitCode: 137,
+            stdout,
+            stderr: stderr + "\n[Process killed: timeout exceeded]"
+          });
+        } else {
+          resolve8({ exitCode: code ?? 1, stdout, stderr });
+        }
+      });
+    });
+    proc.on("error", (err) => {
+      clearTimeout(timer);
+      settle(() => {
+        reject(err);
+      });
+    });
+    if (options.stdin) {
+      proc.stdin.write(options.stdin, () => {
+        proc.stdin.end();
+      });
+    } else {
+      proc.stdin.end();
+    }
+  });
+}
+var LocalEnvironment = class {
+  type = "local";
+  config;
+  cwd;
+  maxOutputChars;
+  constructor(config, maxOutputChars) {
+    this.config = config ?? {};
+    this.cwd = path__namespace.resolve(config?.cwd ?? process.cwd());
+    this.maxOutputChars = maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS2;
+  }
+  async initialize() {
+    try {
+      const stat2 = await fs2__namespace.stat(this.cwd);
+      if (!stat2.isDirectory()) {
+        throw new Error(`Working directory is not a directory: ${this.cwd}`);
+      }
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        throw new Error(`Working directory does not exist: ${this.cwd}`);
+      }
+      throw err;
+    }
+  }
+  async exec(command, opts) {
+    const cwd = opts?.cwd ? this.resolvePath(opts.cwd) : this.cwd;
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_SECONDS2;
+    const start = Date.now();
+    const result = await spawnLocal(command, {
+      cwd,
+      env: opts?.env,
+      timeout,
+      stdin: opts?.stdin
+    });
+    const durationMs = Date.now() - start;
+    const { text: stdout, truncated: stdoutTruncated } = truncateOutput(
+      stripAnsi(result.stdout),
+      this.maxOutputChars
+    );
+    const { text: stderr } = truncateOutput(stripAnsi(result.stderr), this.maxOutputChars);
+    return {
+      exitCode: result.exitCode,
+      stdout,
+      stderr,
+      durationMs,
+      truncated: stdoutTruncated
+    };
+  }
+  async readFile(filePath) {
+    const resolved = this.resolvePath(filePath);
+    await this.assertNotSymlink(resolved);
+    const buffer = await fs2__namespace.readFile(resolved);
+    if (isBinary(buffer)) {
+      throw new Error(`Cannot read binary file: ${filePath}`);
+    }
+    return buffer.toString("utf-8");
+  }
+  async writeFile(filePath, content) {
+    const resolved = this.resolvePath(filePath);
+    this.assertPathSafe(resolved);
+    const parentDir = path__namespace.dirname(resolved);
+    await fs2__namespace.mkdir(parentDir, { recursive: true });
+    await fs2__namespace.writeFile(resolved, content, "utf-8");
+  }
+  async fileExists(filePath) {
+    const resolved = this.resolvePath(filePath);
+    try {
+      await fs2__namespace.access(resolved);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async glob(pattern, opts) {
+    const cwd = opts?.cwd ? this.resolvePath(opts.cwd) : this.cwd;
+    let command = `find ${cwd} -type f -name '${pattern}'`;
+    if (opts?.ignore) {
+      for (const ignore of opts.ignore) {
+        command += ` ! -path '${ignore}'`;
+      }
+    }
+    command += " 2>/dev/null | sort | head -1000";
+    const result = await this.exec(command);
+    if (!result.stdout.trim()) return [];
+    return result.stdout.trim().split("\n").filter(Boolean);
+  }
+  async grep(pattern, opts) {
+    const cwd = opts?.cwd ? this.resolvePath(opts.cwd) : this.cwd;
+    const maxResults = opts?.maxResults ?? 100;
+    let command = "grep -rn";
+    if (opts?.contextLines !== void 0) {
+      command += ` -C ${String(opts.contextLines)}`;
+    }
+    if (opts?.include) {
+      for (const inc of opts.include) {
+        command += ` --include='${inc}'`;
+      }
+    }
+    const escapedPattern = pattern.replace(/'/g, "'\\''");
+    command += ` -- '${escapedPattern}' ${cwd}`;
+    command += ` 2>/dev/null | head -${String(maxResults)}`;
+    const result = await this.exec(command);
+    return parseGrepOutput(result.stdout);
+  }
+  async destroy() {
+  }
+  getCwd() {
+    return this.cwd;
+  }
+  getInfo() {
+    return {
+      type: "local",
+      cwd: this.cwd
+    };
+  }
+  /**
+   * Resolve a path relative to the working directory.
+   */
+  resolvePath(p) {
+    return path__namespace.resolve(this.cwd, p);
+  }
+  /**
+   * Assert that a resolved path stays within the path restriction.
+   * No-op when path restriction is not configured.
+   */
+  assertPathSafe(resolvedPath) {
+    if (!this.config.pathRestriction) return;
+    const restriction = path__namespace.resolve(this.config.pathRestriction);
+    if (resolvedPath !== restriction && !resolvedPath.startsWith(restriction + "/")) {
+      throw new Error(`Path traversal detected: "${resolvedPath}" is outside of "${restriction}"`);
+    }
+  }
+  /**
+   * Assert that a path is not a symbolic link.
+   * Only enforced when path restriction is configured.
+   */
+  async assertNotSymlink(resolvedPath) {
+    if (!this.config.pathRestriction) return;
+    try {
+      const stat2 = await fs2__namespace.lstat(resolvedPath);
+      if (stat2.isSymbolicLink()) {
+        throw new Error(
+          `Symbolic link detected: "${resolvedPath}". Symlinks are blocked when pathRestriction is set.`
+        );
+      }
+    } catch (err) {
+      if (err.code === "ENOENT") return;
+      throw err;
+    }
+  }
+};
+function matchGlob(text, pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  const regexStr = `^${escaped.replace(/\*/g, ".*")}$`;
+  return new RegExp(regexStr).test(text);
+}
+function evaluateAllowlist(command, patterns) {
+  const trimmed = command.trim();
+  return patterns.some((pattern) => matchGlob(trimmed, pattern));
+}
+function isWithinRestriction(resolvedPath, restriction) {
+  const base = path.resolve(restriction);
+  return resolvedPath === base || resolvedPath.startsWith(base + "/");
+}
+function assertSafePath(filePath, restriction) {
+  const base = path.resolve(restriction);
+  const resolved = path.resolve(base, filePath);
+  if (!isWithinRestriction(resolved, base)) {
+    throw new Error(`Path traversal detected: "${filePath}" resolves outside of "${restriction}"`);
+  }
+}
+
+// src/execution/tools/exec.ts
+async function requestApproval(ctx, command, env) {
+  const envInfo = env.getInfo();
+  const approvalId = await ctx.step.uuid("_approval_id");
+  const response = await ctx.step.suspend(
+    `approve_exec_${approvalId}`,
+    {
+      data: {
+        _form: {
+          title: "Approve command execution",
+          description: `The agent wants to run a shell command in the ${envInfo.type} environment.`,
+          fields: [
+            {
+              key: "approved",
+              type: "boolean",
+              label: "Approve this command?",
+              required: true,
+              default: false
+            },
+            {
+              key: "allow_always",
+              type: "boolean",
+              label: "Always allow this command in the future?",
+              required: false,
+              default: false
+            },
+            {
+              key: "feedback",
+              type: "textarea",
+              label: "Feedback for the agent (optional)",
+              description: "If rejecting, tell the agent what to do instead.",
+              required: false
+            }
+          ],
+          context: {
+            command,
+            cwd: env.getCwd(),
+            environment: envInfo.type
+          }
+        },
+        _source: "exec_security",
+        _tool: "exec"
+      }
+    }
+  );
+  const feedback = response.data?.feedback;
+  return {
+    approved: response.data?.approved === true,
+    ...feedback ? { feedback } : {}
+  };
+}
+function rejectedResult(command, feedback) {
+  let stderr = `Command rejected by user: ${command}`;
+  if (feedback) {
+    stderr += `
+User feedback: ${feedback}`;
+  }
+  return {
+    exitCode: -1,
+    stdout: "",
+    stderr,
+    durationMs: 0,
+    truncated: false
+  };
+}
+function createExecTool(getEnv, config) {
+  return defineTool(
+    {
+      id: "exec",
+      description: "Execute a shell command in the sandbox environment. Returns stdout, stderr, and exit code. Use this for running builds, tests, installing packages, or any shell operation.",
+      inputSchema: zod.z.object({
+        command: zod.z.string().describe("The shell command to execute"),
+        cwd: zod.z.string().optional().describe("Working directory for the command"),
+        env: zod.z.record(zod.z.string()).optional().describe("Environment variables to set"),
+        timeout: zod.z.number().optional().describe("Timeout in seconds (default: 300)")
+      })
+    },
+    async (ctx, input) => {
+      const env = await getEnv();
+      if (config?.security === "approval-always") {
+        const result = await requestApproval(ctx, input.command, env);
+        if (!result.approved) return rejectedResult(input.command, result.feedback);
+      } else if (config?.security === "allowlist") {
+        if (!evaluateAllowlist(input.command, config.allowlist ?? [])) {
+          const result = await requestApproval(ctx, input.command, env);
+          if (!result.approved) return rejectedResult(input.command, result.feedback);
+        }
+      }
+      return env.exec(input.command, {
+        cwd: input.cwd,
+        env: input.env,
+        timeout: input.timeout ?? config?.timeout
+      });
+    }
+  );
+}
+function isPathAllowed(resolvedPath, restriction) {
+  return isWithinRestriction(resolvedPath, path.resolve(restriction));
+}
+async function requirePathApproval(ctx, toolName, targetPath, restriction) {
+  const approvalId = await ctx.step.uuid("_approval_id");
+  const response = await ctx.step.suspend(
+    `approve_${toolName}_${approvalId}`,
+    {
+      data: {
+        _form: {
+          title: `${toolName}: access outside workspace`,
+          description: `The agent wants to ${toolName} a path outside the workspace.`,
+          fields: [
+            {
+              key: "approved",
+              type: "boolean",
+              label: "Allow this operation?",
+              required: true,
+              default: false
+            },
+            {
+              key: "feedback",
+              type: "textarea",
+              label: "Feedback for the agent (optional)",
+              description: "If rejecting, tell the agent what to do instead.",
+              required: false
+            }
+          ],
+          context: {
+            tool: toolName,
+            path: targetPath,
+            restriction
+          }
+        },
+        _source: "path_approval",
+        _tool: toolName
+      }
+    }
+  );
+  if (response.data?.approved !== true) {
+    const feedback = response.data?.feedback;
+    throw new Error(
+      `Access to "${targetPath}" was rejected by the user.${feedback ? ` Feedback: ${feedback}` : ""}`
+    );
+  }
+}
+
+// src/execution/tools/read.ts
+function createReadTool(getEnv, pathConfig) {
+  return defineTool(
+    {
+      id: "read",
+      description: "Read the contents of a file. Returns the file content as text. Optionally specify offset (line number to start from, 0-based) and limit (number of lines).",
+      inputSchema: zod.z.object({
+        path: zod.z.string().describe("Path to the file to read"),
+        offset: zod.z.number().optional().describe("Line offset to start reading from (0-based)"),
+        limit: zod.z.number().optional().describe("Maximum number of lines to return")
+      })
+    },
+    async (ctx, input) => {
+      const env = await getEnv();
+      if (pathConfig?.pathRestriction) {
+        const resolved = path.resolve(env.getCwd(), input.path);
+        if (!isPathAllowed(resolved, pathConfig.pathRestriction)) {
+          await requirePathApproval(ctx, "read", resolved, pathConfig.pathRestriction);
+        }
+      }
+      let content = await env.readFile(input.path);
+      if (input.offset !== void 0 || input.limit !== void 0) {
+        const lines = content.split("\n");
+        const start = input.offset ?? 0;
+        const end = input.limit !== void 0 ? start + input.limit : lines.length;
+        content = lines.slice(start, end).join("\n");
+      }
+      return { content, path: input.path };
+    }
+  );
+}
+function createWriteTool(getEnv, approval) {
+  return defineTool(
+    {
+      id: "write",
+      description: "Write content to a file. Creates the file if it does not exist, or overwrites it if it does. Parent directories are created automatically.",
+      inputSchema: zod.z.object({
+        path: zod.z.string().describe("Path to the file to write"),
+        content: zod.z.string().describe("Content to write to the file")
+      }),
+      approval
+    },
+    async (_ctx, input) => {
+      const env = await getEnv();
+      await env.writeFile(input.path, input.content);
+      return { success: true, path: input.path };
+    }
+  );
+}
+function createEditTool(getEnv, approval) {
+  return defineTool(
+    {
+      id: "edit",
+      description: "Edit a file by replacing an exact string match. The old_text must match exactly (including whitespace and indentation). Use this for precise code modifications.",
+      inputSchema: zod.z.object({
+        path: zod.z.string().describe("Path to the file to edit"),
+        old_text: zod.z.string().describe("Exact text to find and replace"),
+        new_text: zod.z.string().describe("Text to replace the old_text with")
+      }),
+      approval
+    },
+    async (_ctx, input) => {
+      const env = await getEnv();
+      const content = await env.readFile(input.path);
+      if (!content.includes(input.old_text)) {
+        throw new Error(
+          `old_text not found in ${input.path}. Make sure the text matches exactly, including whitespace and indentation.`
+        );
+      }
+      const newContent = content.replace(input.old_text, input.new_text);
+      await env.writeFile(input.path, newContent);
+      return { success: true, path: input.path };
+    }
+  );
+}
+function createGlobTool(getEnv, pathConfig) {
+  return defineTool(
+    {
+      id: "glob",
+      description: "Find files matching a glob pattern. Returns a list of file paths. Use this to discover files in the project structure.",
+      inputSchema: zod.z.object({
+        pattern: zod.z.string().describe('Glob pattern to match (e.g., "*.ts", "src/**/*.js")'),
+        cwd: zod.z.string().optional().describe("Directory to search in"),
+        ignore: zod.z.array(zod.z.string()).optional().describe("Patterns to exclude from results")
+      })
+    },
+    async (ctx, input) => {
+      const env = await getEnv();
+      if (pathConfig?.pathRestriction && input.cwd) {
+        const resolved = path.resolve(env.getCwd(), input.cwd);
+        if (!isPathAllowed(resolved, pathConfig.pathRestriction)) {
+          await requirePathApproval(ctx, "glob", resolved, pathConfig.pathRestriction);
+        }
+      }
+      const files = await env.glob(input.pattern, {
+        cwd: input.cwd,
+        ignore: input.ignore
+      });
+      return { files };
+    }
+  );
+}
+function createGrepTool(getEnv, pathConfig) {
+  return defineTool(
+    {
+      id: "grep",
+      description: "Search file contents for a pattern using grep. Returns matching lines with file paths and line numbers. Use this to find code patterns, references, or specific text.",
+      inputSchema: zod.z.object({
+        pattern: zod.z.string().describe("Search pattern (regex supported)"),
+        cwd: zod.z.string().optional().describe("Directory to search in"),
+        include: zod.z.array(zod.z.string()).optional().describe('File patterns to include (e.g., ["*.ts", "*.js"])'),
+        maxResults: zod.z.number().optional().describe("Maximum number of matches to return (default: 100)"),
+        contextLines: zod.z.number().optional().describe("Number of context lines around each match")
+      })
+    },
+    async (ctx, input) => {
+      const env = await getEnv();
+      if (pathConfig?.pathRestriction && input.cwd) {
+        const resolved = path.resolve(env.getCwd(), input.cwd);
+        if (!isPathAllowed(resolved, pathConfig.pathRestriction)) {
+          await requirePathApproval(ctx, "grep", resolved, pathConfig.pathRestriction);
+        }
+      }
+      const matches = await env.grep(input.pattern, {
+        cwd: input.cwd,
+        include: input.include,
+        maxResults: input.maxResults,
+        contextLines: input.contextLines
+      });
+      return { matches };
+    }
+  );
+}
+
+// src/execution/sandbox-tools.ts
+function createEnvironment(config) {
+  const envType = config?.env ?? "docker";
+  switch (envType) {
+    case "docker": {
+      const dockerConfig = config?.docker ?? {
+        image: "node:20-slim",
+        workspaceDir: process.cwd()
+      };
+      return new DockerEnvironment(dockerConfig, config?.exec?.maxOutputChars);
+    }
+    case "e2b":
+      throw new Error("E2B environment is not yet implemented.");
+    case "local":
+      return new LocalEnvironment(config?.local, config?.exec?.maxOutputChars);
+    default:
+      throw new Error(`Unknown environment type: ${String(envType)}`);
+  }
+}
+function sandboxTools(config) {
+  let env = null;
+  let envPromise = null;
+  async function getEnv() {
+    if (env) return env;
+    if (envPromise) return envPromise;
+    envPromise = (async () => {
+      const created = createEnvironment(config);
+      await created.initialize();
+      env = created;
+      return env;
+    })();
+    return envPromise;
+  }
+  const envType = config?.env ?? "docker";
+  if (envType === "e2b") {
+    throw new Error("E2B environment is not yet implemented.");
+  }
+  const effectiveExecConfig = envType === "local" && !config?.exec?.security ? { ...config?.exec, security: "approval-always" } : config?.exec;
+  const fileApproval = config?.fileApproval ?? (envType === "local" ? "always" : void 0);
+  const pathConfig = config?.local?.pathRestriction ? { pathRestriction: config.local.pathRestriction } : void 0;
+  const include = new Set(
+    config?.tools ?? ["exec", "read", "write", "edit", "glob", "grep"]
+  );
+  const tools = [];
+  if (include.has("exec")) tools.push(createExecTool(getEnv, effectiveExecConfig));
+  if (include.has("read")) tools.push(createReadTool(getEnv, pathConfig));
+  if (include.has("write")) tools.push(createWriteTool(getEnv, fileApproval));
+  if (include.has("edit")) tools.push(createEditTool(getEnv, fileApproval));
+  if (include.has("glob")) tools.push(createGlobTool(getEnv, pathConfig));
+  if (include.has("grep")) tools.push(createGrepTool(getEnv, pathConfig));
+  const result = tools;
+  result.cleanup = async () => {
+    if (env) {
+      await env.destroy();
+      env = null;
+      envPromise = null;
+    }
+  };
+  return result;
+}
 
 exports.AgentRunConfig = AgentRunConfig;
+exports.DockerEnvironment = DockerEnvironment;
 exports.DuplicateWorkflowError = DuplicateWorkflowError;
 exports.ExecutionHandle = ExecutionHandle;
 exports.GuardrailError = GuardrailError;
@@ -5562,6 +6693,7 @@ exports.Worker = Worker;
 exports.WorkerServer = WorkerServer;
 exports.WorkflowNotFoundError = WorkflowNotFoundError;
 exports.agentStreamFunction = agentStreamFunction;
+exports.assertSafePath = assertSafePath;
 exports.batchAgentInvoke = batchAgentInvoke;
 exports.batchInvoke = batchInvoke;
 exports.composeGuardrails = composeGuardrails;
@@ -5574,15 +6706,24 @@ exports.convertToolResultsToMessages = convertToolResultsToMessages;
 exports.convertToolsToVercel = convertToolsToVercel;
 exports.convertVercelToolCallToPython = convertVercelToolCallToPython;
 exports.convertVercelUsageToPython = convertVercelUsageToPython;
+exports.createAskUserTool = createAskUserTool;
+exports.createEditTool = createEditTool;
+exports.createExecTool = createExecTool;
+exports.createGlobTool = createGlobTool;
+exports.createGrepTool = createGrepTool;
 exports.createLogger = createLogger;
+exports.createReadTool = createReadTool;
 exports.createStepHelper = createStepHelper;
 exports.createStepStore = createStepStore;
+exports.createWebSearchTool = createWebSearchTool;
 exports.createWorkflowRegistry = createWorkflowRegistry;
+exports.createWriteTool = createWriteTool;
 exports.defineAgent = defineAgent;
 exports.defineGuardrail = defineGuardrail;
 exports.defineHook = defineHook;
 exports.defineTool = defineTool;
 exports.defineWorkflow = defineWorkflow;
+exports.evaluateAllowlist = evaluateAllowlist;
 exports.executeGuardrailChain = executeGuardrailChain;
 exports.executeGuardrailsOrThrow = executeGuardrailsOrThrow;
 exports.executeHookChain = executeHookChain;
@@ -5597,6 +6738,7 @@ exports.hasText = hasText;
 exports.initializeOtel = initializeOtel;
 exports.initializeState = initializeState;
 exports.isAgentWorkflow = isAgentWorkflow;
+exports.isBinary = isBinary;
 exports.isGuardrail = isGuardrail;
 exports.isHook = isHook;
 exports.isOtelAvailable = isOtelAvailable;
@@ -5610,10 +6752,14 @@ exports.normalizeGuardrail = normalizeGuardrail;
 exports.normalizeGuardrails = normalizeGuardrails;
 exports.normalizeHook = normalizeHook;
 exports.normalizeHooks = normalizeHooks;
+exports.parseGrepOutput = parseGrepOutput;
 exports.retry = retry;
+exports.sandboxTools = sandboxTools;
 exports.serializeFinalState = serializeFinalState;
 exports.sleep = sleep;
 exports.stopCondition = stopCondition;
+exports.stripAnsi = stripAnsi;
+exports.truncateOutput = truncateOutput;
 exports.validateState = validateState;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map