zeitlich 0.2.22 → 0.2.24

package/dist/index.cjs

@@ -6,6 +6,7 @@ var crypto = require('crypto');
 var common = require('@temporalio/common');
 var path = require('path');
 var activity = require('@temporalio/activity');
+var fs = require('fs');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -18,8 +19,8 @@ function createToolRouter(options) {
   for (const [_key, tool] of Object.entries(options.tools)) {
     toolMap.set(tool.name, tool);
   }
-  const resolve = (v) => typeof v === "function" ? v() : v;
-  const isEnabled = (tool) => resolve(tool.enabled) ?? true;
+  const resolve2 = (v) => typeof v === "function" ? v() : v;
+  const isEnabled = (tool) => resolve2(tool.enabled) ?? true;
   if (options.plugins) {
     for (const plugin of options.plugins) {
       toolMap.set(plugin.name, plugin);
@@ -88,7 +89,12 @@ function createToolRouter(options) {
           result: { error: errorStr, suppressed: true }
         };
     }
-    throw workflow.ApplicationFailure.fromError(error, { nonRetryable: true });
+    return {
+      content: JSON.stringify({
+        error: "The tool encountered an error. Please try again or use a different approach."
+      }),
+      result: { error: errorStr, suppressed: true }
+    };
   }
   async function runPostHooks(toolCall, tool, toolResult, effectiveArgs, turn, durationMs) {
     if (tool?.hooks?.onPostToolUse) {
@@ -97,7 +103,8 @@ function createToolRouter(options) {
         result: toolResult.data,
         threadId: options.threadId,
         turn,
-        durationMs
+        durationMs,
+        ...toolResult.metadata && { metadata: toolResult.metadata }
       });
     }
     if (options.hooks?.onPostToolUse) {
@@ -110,7 +117,7 @@ function createToolRouter(options) {
       });
     }
   }
-  async function processToolCall(toolCall, turn, sandboxId) {
+  async function processToolCall(toolCall, turn, sandboxId, sandboxStateUpdate) {
     const startTime = Date.now();
     const tool = toolMap.get(toolCall.name);
     const preResult = await runPreHooks(toolCall, tool, turn);
@@ -130,13 +137,15 @@ function createToolRouter(options) {
     let result;
     let content;
     let resultAppended = false;
+    let metadata;
     try {
       if (tool) {
         const routerContext = {
           threadId: options.threadId,
           toolCallId: toolCall.id,
           toolName: toolCall.name,
-          ...sandboxId !== void 0 && { sandboxId }
+          ...sandboxId !== void 0 && { sandboxId },
+          ...sandboxStateUpdate && { sandboxStateUpdate }
         };
         const response = await tool.handler(
           effectiveArgs,
@@ -145,6 +154,7 @@ function createToolRouter(options) {
         result = response.data;
         content = response.toolResponse;
         resultAppended = response.resultAppended === true;
+        metadata = response.metadata;
       } else {
         result = { error: `Unknown tool: ${toolCall.name}` };
         content = JSON.stringify(result, null, 2);
@@ -177,7 +187,8 @@ function createToolRouter(options) {
     const toolResult = {
       toolCallId: toolCall.id,
       name: toolCall.name,
-      data: result
+      data: result,
+      ...metadata && { metadata }
     };
     await runPostHooks(
       toolCall,
@@ -198,7 +209,7 @@ function createToolRouter(options) {
       if (!tool || !isEnabled(tool)) {
         throw new Error(`Tool ${toolCall.name} not found`);
       }
-      const parsedArgs = resolve(tool.schema).parse(toolCall.args);
+      const parsedArgs = resolve2(tool.schema).parse(toolCall.args);
       return {
         id: toolCall.id ?? "",
         name: toolCall.name,
@@ -215,8 +226,8 @@ function createToolRouter(options) {
     getToolDefinitions() {
       return Array.from(toolMap).filter(([, tool]) => isEnabled(tool)).map(([name, tool]) => ({
         name,
-        description: resolve(tool.description),
-        schema: resolve(tool.schema),
+        description: resolve2(tool.description),
+        schema: resolve2(tool.schema),
         strict: tool.strict,
         max_uses: tool.max_uses
       }));
@@ -227,9 +238,10 @@ function createToolRouter(options) {
       }
       const turn = context?.turn ?? 0;
       const sandboxId = context?.sandboxId;
+      const sandboxStateUpdate = context?.sandboxStateUpdate;
       if (options.parallel) {
         const results2 = await Promise.all(
-          toolCalls.map((tc) => processToolCall(tc, turn, sandboxId))
+          toolCalls.map((tc) => processToolCall(tc, turn, sandboxId, sandboxStateUpdate))
         );
         return results2.filter(
           (r) => r !== null
@@ -237,7 +249,7 @@ function createToolRouter(options) {
       }
       const results = [];
       for (const toolCall of toolCalls) {
-        const result = await processToolCall(toolCall, turn, sandboxId);
+        const result = await processToolCall(toolCall, turn, sandboxId, sandboxStateUpdate);
         if (result !== null) {
           results.push(result);
         }
@@ -281,7 +293,8 @@ function createToolRouter(options) {
         return {
           toolCallId: toolCall.id,
           name: toolCall.name,
-          data: response.data
+          data: response.data,
+          ...response.metadata && { metadata: response.metadata }
         };
       };
       if (options.parallel) {
@@ -325,7 +338,7 @@ function getShortId(length = 12) {
 var SUBAGENT_TOOL_NAME = "Subagent";
 function buildSubagentDescription(subagents) {
   const subagentList = subagents.map((s) => {
-    const continuation = s.allowThreadContinuation ? "\n*(Supports thread continuation \u2014 pass a threadId to resume a previous conversation)*" : "";
+    const continuation = s.thread && s.thread !== "new" ? "\n*(Supports thread continuation \u2014 pass a threadId to resume a previous conversation)*" : "";
     return `## ${s.agentName}
 ${s.description}${continuation}`;
   }).join("\n\n");
@@ -341,7 +354,7 @@ function createSubagentTool(subagents) {
   }
   const names = subagents.map((s) => s.agentName);
   const hasThreadContinuation = subagents.some(
-    (s) => s.allowThreadContinuation
+    (s) => s.thread && s.thread !== "new"
   );
   const baseFields = {
     subagent: z14__default.default.enum(names).describe("The type of subagent to launch"),
@@ -360,9 +373,25 @@ function createSubagentTool(subagents) {
     schema
   };
 }
+var childResultSignal = workflow.defineSignal("childResult");
+var destroySandboxSignal = workflow.defineSignal("destroySandbox");
+
+// src/lib/subagent/handler.ts
+function resolveSandboxConfig(config) {
+  if (!config || config === "none") return { source: "none" };
+  if (config === "inherit") return { source: "inherit" };
+  if (config === "own") return { source: "own" };
+  return { source: "own", shutdown: config.shutdown };
+}
 function createSubagentHandler(subagents) {
   const { taskQueue: parentTaskQueue } = workflow.workflowInfo();
-  return async (args, context) => {
+  const childResults = /* @__PURE__ */ new Map();
+  const pendingDestroys = /* @__PURE__ */ new Map();
+  const threadSandboxes = /* @__PURE__ */ new Map();
+  workflow.setHandler(childResultSignal, ({ childWorkflowId, result }) => {
+    childResults.set(childWorkflowId, result);
+  });
+  const handler = async (args, context) => {
     const config = subagents.find((s) => s.agentName === args.subagent);
     if (!config) {
       throw new Error(
@@ -371,12 +400,36 @@ function createSubagentHandler(subagents) {
     }
     const childWorkflowId = `${args.subagent}-${getShortId()}`;
     const { sandboxId: parentSandboxId } = context;
-    const inheritSandbox = config.sandbox !== "own" && !!parentSandboxId;
+    const sandboxCfg = resolveSandboxConfig(config.sandbox);
+    if (sandboxCfg.source === "inherit" && !parentSandboxId) {
+      throw new Error(
+        `Subagent "${config.agentName}" is configured with sandbox: "inherit" but the parent has no sandbox`
+      );
+    }
+    const threadMode = config.thread ?? "new";
+    const allowsContinuation = threadMode !== "new";
+    const continuationThreadId = args.threadId && allowsContinuation ? args.threadId : void 0;
+    let thread;
+    if (continuationThreadId) {
+      thread = { mode: threadMode, threadId: continuationThreadId };
+    }
+    let sandbox;
+    if (sandboxCfg.source === "inherit" && parentSandboxId) {
+      sandbox = {
+        mode: "inherit",
+        sandboxId: parentSandboxId,
+        ...context.sandboxStateUpdate && { stateUpdate: context.sandboxStateUpdate }
+      };
+    } else if (sandboxCfg.source === "own") {
+      const prevSbId = continuationThreadId ? threadSandboxes.get(continuationThreadId) : void 0;
+      if (prevSbId) {
+        sandbox = { mode: "fork", sandboxId: prevSbId };
+      }
+    }
     const workflowInput = {
-      ...args.threadId && args.threadId !== null && config.allowThreadContinuation && {
-        previousThreadId: args.threadId
-      },
-      ...inheritSandbox && { sandboxId: parentSandboxId }
+      ...thread && { thread },
+      ...sandbox && { sandbox },
+      ...sandboxCfg.shutdown && { sandboxShutdown: sandboxCfg.shutdown }
     };
     const resolvedContext = config.context === void 0 ? void 0 : typeof config.context === "function" ? config.context() : config.context;
     const childOpts = {
@@ -384,17 +437,44 @@ function createSubagentHandler(subagents) {
       args: resolvedContext === void 0 ? [args.prompt, workflowInput] : [args.prompt, workflowInput, resolvedContext],
       taskQueue: config.taskQueue ?? parentTaskQueue
     };
+    const childHandle = await workflow.startChild(config.workflow, childOpts);
+    const usesOwnSandbox = sandboxCfg.source === "own" || allowsContinuation && sandboxCfg.source !== "inherit";
+    if (usesOwnSandbox) {
+      pendingDestroys.set(childWorkflowId, childHandle);
+    }
+    await Promise.race([
+      workflow.condition(() => childResults.has(childWorkflowId)),
+      childHandle.result()
+    ]);
+    if (!childResults.has(childWorkflowId)) {
+      await workflow.condition(() => childResults.has(childWorkflowId));
+    }
+    const childResult = childResults.get(childWorkflowId);
+    childResults.delete(childWorkflowId);
+    if (!childResult) {
+      return {
+        toolResponse: "Subagent workflow did not signal a result",
+        data: null
+      };
+    }
     const {
       toolResponse,
       data,
       usage,
-      threadId: childThreadId
-    } = typeof config.workflow === "string" ? await workflow.executeChild(config.workflow, childOpts) : await workflow.executeChild(config.workflow, childOpts);
+      threadId: childThreadId,
+      sandboxId: childSandboxId,
+      metadata
+    } = childResult;
+    if (allowsContinuation && childSandboxId && childThreadId) {
+      threadSandboxes.set(childThreadId, childSandboxId);
+    }
     if (!toolResponse) {
       return {
         toolResponse: "Subagent workflow returned no response",
         data: null,
-        ...usage && { usage }
+        ...usage && { usage },
+        ...childSandboxId && { sandboxId: childSandboxId },
+        ...metadata && { metadata }
       };
     }
     const validated = config.resultSchema ? config.resultSchema.safeParse(data) : null;
@@ -402,11 +482,13 @@ function createSubagentHandler(subagents) {
       return {
         toolResponse: `Subagent workflow returned invalid data: ${validated.error.message}`,
         data: null,
-        ...usage && { usage }
+        ...usage && { usage },
+        ...childSandboxId && { sandboxId: childSandboxId },
+        ...metadata && { metadata }
       };
     }
     let finalToolResponse = toolResponse;
-    if (config.allowThreadContinuation && childThreadId) {
+    if (allowsContinuation && childThreadId) {
       finalToolResponse = typeof toolResponse === "string" ? `${toolResponse}
 
 [${config.agentName} Thread ID: ${childThreadId}]` : toolResponse;
@@ -414,9 +496,22 @@ function createSubagentHandler(subagents) {
     return {
       toolResponse: finalToolResponse,
       data: validated ? validated.data : data,
-      ...usage && { usage }
+      ...usage && { usage },
+      ...childSandboxId && { sandboxId: childSandboxId },
+      ...metadata && { metadata }
     };
   };
+  const destroySubagentSandboxes = async () => {
+    const handles = [...pendingDestroys.values()];
+    pendingDestroys.clear();
+    await Promise.all(
+      handles.map(async (handle) => {
+        await handle.signal(destroySandboxSignal);
+        await handle.result();
+      })
+    );
+  };
+  return { handler, destroySubagentSandboxes };
 }
 
 // src/lib/subagent/register.ts
@@ -430,12 +525,13 @@ function buildSubagentRegistration(subagents) {
     if (s.hooks) subagentHooksMap.set(s.agentName, s.hooks);
   }
   const resolveSubagentName = (args) => args.subagent;
-  return {
+  const { handler, destroySubagentSandboxes } = createSubagentHandler(subagents);
+  const registration = {
     name: SUBAGENT_TOOL_NAME,
     enabled: () => getEnabled().length > 0,
     description: () => createSubagentTool(getEnabled()).description,
     schema: () => createSubagentTool(getEnabled()).schema,
-    handler: createSubagentHandler(subagents),
+    handler,
     ...subagentHooksMap.size > 0 && {
       hooks: {
         onPreToolUse: async (ctx) => {
@@ -453,6 +549,7 @@ function buildSubagentRegistration(subagents) {
       }
     }
   };
+  return { registration, destroySubagentSandboxes };
 }
 var READ_SKILL_TOOL_NAME = "ReadSkill";
 function buildReadSkillDescription(skills) {
@@ -478,6 +575,29 @@ function createReadSkillTool(skills) {
 }
 
 // src/lib/skills/handler.ts
+function formatSkillResponse(skill) {
+  const parts = [];
+  parts.push(`<skill_content name="${skill.name}">`);
+  parts.push(skill.instructions);
+  if (skill.location) {
+    parts.push(`
+Skill directory: ${skill.location}`);
+    parts.push(
+      "Relative paths in this skill resolve against the skill directory above."
+    );
+  }
+  const resources = skill.resourceContents ? Object.keys(skill.resourceContents) : [];
+  if (resources.length > 0) {
+    parts.push("");
+    parts.push("<skill_resources>");
+    for (const r of resources) {
+      parts.push(`  <file>${r}</file>`);
+    }
+    parts.push("</skill_resources>");
+  }
+  parts.push("</skill_content>");
+  return parts.join("\n");
+}
 function createReadSkillHandler(skills) {
   const skillMap = new Map(skills.map((s) => [s.name, s]));
   return (args) => {
@@ -491,22 +611,42 @@ function createReadSkillHandler(skills) {
       };
     }
     return {
-      toolResponse: skill.instructions,
+      toolResponse: formatSkillResponse(skill),
       data: null
     };
   };
 }
 
 // src/lib/skills/register.ts
+function validateSkillNames(skills) {
+  const names = skills.map((s) => s.name);
+  const dupes = names.filter((n, i) => names.indexOf(n) !== i);
+  if (dupes.length > 0) {
+    throw new Error(
+      `Duplicate skill names: ${[...new Set(dupes)].join(", ")}`
+    );
+  }
+}
 function buildSkillRegistration(skills) {
   if (skills.length === 0) return null;
+  validateSkillNames(skills);
   return {
     ...createReadSkillTool(skills),
     handler: createReadSkillHandler(skills)
   };
 }
-var createSession = async ({
-  threadId: providedThreadId,
+function collectSkillFiles(skills) {
+  let files;
+  for (const skill of skills) {
+    if (!skill.resourceContents || !skill.location) continue;
+    for (const [relPath, content] of Object.entries(skill.resourceContents)) {
+      files ??= {};
+      files[`${skill.location}/${relPath}`] = content;
+    }
+  }
+  return files;
+}
+async function createSession({
   agentName,
   maxTurns = 50,
   metadata = {},
@@ -519,13 +659,27 @@ var createSession = async ({
   processToolsInParallel = true,
   hooks = {},
   appendSystemPrompt = true,
-  continueThread = false,
   waitForInputTimeout = "48h",
-  sandbox: sandboxOps,
-  sandboxId: inheritedSandboxId
-}) => {
-  const sourceThreadId = continueThread ? providedThreadId : void 0;
-  const threadId = continueThread && providedThreadId ? getShortId() : providedThreadId ?? getShortId();
+  sandboxOps,
+  thread: threadInit,
+  sandbox: sandboxInit,
+  sandboxShutdown = "destroy"
+}) {
+  const threadMode = threadInit?.mode ?? "new";
+  let threadId;
+  let sourceThreadId;
+  switch (threadMode) {
+    case "new":
+      threadId = threadInit?.mode === "new" && threadInit.threadId ? threadInit.threadId : getShortId();
+      break;
+    case "continue":
+      threadId = threadInit.threadId;
+      break;
+    case "fork":
+      sourceThreadId = threadInit.threadId;
+      threadId = getShortId();
+      break;
+  }
   const {
     appendToolResult,
     appendHumanMessage,
@@ -534,9 +688,13 @@ var createSession = async ({
     forkThread
   } = threadOps;
   const plugins = [];
+  let destroySubagentSandboxes;
   if (subagents) {
-    const reg = buildSubagentRegistration(subagents);
-    if (reg) plugins.push(reg);
+    const result = buildSubagentRegistration(subagents);
+    if (result) {
+      plugins.push(result.registration);
+      destroySubagentSandboxes = result.destroySubagentSandboxes;
+    }
   }
   if (skills) {
     const reg = buildSkillRegistration(skills);
@@ -584,12 +742,52 @@ var createSession = async ({
           stateManager.run();
         }
       );
-      let sandboxId = inheritedSandboxId;
-      const ownsSandbox = !sandboxId && !!sandboxOps;
-      if (ownsSandbox) {
-        const result = await sandboxOps.createSandbox({ id: threadId });
+      const sandboxMode = sandboxInit?.mode;
+      let sandboxId;
+      let sandboxOwned = false;
+      let sandboxStateUpdate;
+      if (sandboxMode === "inherit") {
+        const inheritInit = sandboxInit;
+        sandboxId = inheritInit.sandboxId;
+        if (inheritInit.stateUpdate) {
+          sandboxStateUpdate = inheritInit.stateUpdate;
+          stateManager.mergeUpdate(inheritInit.stateUpdate);
+        }
+        if (!sandboxOps) {
+          throw workflow.ApplicationFailure.create({
+            message: "sandboxId provided but no sandboxOps \u2014 cannot manage sandbox lifecycle",
+            nonRetryable: true
+          });
+        }
+      } else if (sandboxMode === "continue") {
+        if (!sandboxOps) {
+          throw workflow.ApplicationFailure.create({
+            message: "No sandboxOps provided \u2014 cannot continue sandbox",
+            nonRetryable: true
+          });
+        }
+        sandboxId = sandboxInit.sandboxId;
+        sandboxOwned = true;
+      } else if (sandboxMode === "fork") {
+        if (!sandboxOps) {
+          throw workflow.ApplicationFailure.create({
+            message: "No sandboxOps provided \u2014 cannot fork sandbox",
+            nonRetryable: true
+          });
+        }
+        sandboxId = await sandboxOps.forkSandbox(
+          sandboxInit.sandboxId
+        );
+        sandboxOwned = true;
+      } else if (sandboxOps) {
+        const skillFiles = skills ? collectSkillFiles(skills) : void 0;
+        const result = await sandboxOps.createSandbox(
+          skillFiles ? { initialFiles: skillFiles } : void 0
+        );
         sandboxId = result.sandboxId;
+        sandboxOwned = true;
         if (result.stateUpdate) {
+          sandboxStateUpdate = result.stateUpdate;
           stateManager.mergeUpdate(result.stateUpdate);
         }
       }
@@ -601,9 +799,9 @@ var createSession = async ({
         });
       }
       const systemPrompt = stateManager.getSystemPrompt();
-      if (continueThread && sourceThreadId) {
+      if (threadMode === "fork" && sourceThreadId) {
         await forkThread(sourceThreadId, threadId);
-      } else {
+      } else if (threadMode === "continue") ; else {
         if (appendSystemPrompt) {
           if (!systemPrompt || systemPrompt.trim() === "") {
             throw workflow.ApplicationFailure.create({
@@ -638,7 +836,8 @@ var createSession = async ({
               threadId,
               finalMessage: message,
               exitReason,
-              usage: stateManager.getTotalUsage()
+              usage: stateManager.getTotalUsage(),
+              sandboxId
             };
           }
           const parsedToolCalls = [];
@@ -660,7 +859,8 @@ var createSession = async ({
             parsedToolCalls,
             {
               turn: currentTurn,
-              ...sandboxId !== void 0 && { sandboxId }
+              ...sandboxId !== void 0 && { sandboxId },
+              ...sandboxStateUpdate && { sandboxStateUpdate }
             }
           );
           for (const result of toolCallResults) {
@@ -689,30 +889,40 @@ var createSession = async ({
         throw workflow.ApplicationFailure.fromError(error);
       } finally {
         await callSessionEnd(exitReason, stateManager.getTurns());
-        if (ownsSandbox && sandboxId && sandboxOps) {
-          await sandboxOps.destroySandbox(sandboxId);
+        if (sandboxOwned && sandboxId && sandboxOps) {
+          switch (sandboxShutdown) {
+            case "destroy":
+              await sandboxOps.destroySandbox(sandboxId);
+              break;
+            case "pause":
+            case "pause-until-parent-close":
+              await sandboxOps.pauseSandbox(sandboxId);
+              break;
+          }
+        }
+        if (destroySubagentSandboxes) {
+          await destroySubagentSandboxes();
         }
       }
       return {
         threadId,
         finalMessage: null,
         exitReason,
-        usage: stateManager.getTotalUsage()
+        usage: stateManager.getTotalUsage(),
+        sandboxId
       };
     }
   };
-};
+}
 
 // src/lib/workflow.ts
 function defineWorkflow(config, fn) {
   const workflow = async (input, workflowInput = {}) => {
     const sessionInput = {
       agentName: config.name,
-      ...workflowInput.previousThreadId && {
-        threadId: workflowInput.previousThreadId,
-        continueThread: true
-      },
-      ...workflowInput.sandboxId && { sandboxId: workflowInput.sandboxId }
+      sandboxShutdown: config.sandboxShutdown ?? "destroy",
+      ...workflowInput.thread && { thread: workflowInput.thread },
+      ...workflowInput.sandbox && { sandbox: workflowInput.sandbox }
     };
     return fn(input, sessionInput);
   };
@@ -970,22 +1180,58 @@ function defineSubagent(definition, overrides) {
     ...overrides
   };
 }
-
-// src/lib/subagent/workflow.ts
 function defineSubagentWorkflow(config, fn) {
-  const workflow = async (prompt, workflowInput, context) => {
+  const workflow$1 = async (prompt, workflowInput, context) => {
+    const effectiveShutdown = workflowInput.sandboxShutdown ?? config.sandboxShutdown ?? "destroy";
     const sessionInput = {
       agentName: config.name,
-      ...workflowInput.previousThreadId && {
-        threadId: workflowInput.previousThreadId,
-        continueThread: true
-      },
-      ...workflowInput.sandboxId && { sandboxId: workflowInput.sandboxId }
+      sandboxShutdown: effectiveShutdown,
+      ...workflowInput.thread && { thread: workflowInput.thread },
+      ...workflowInput.sandbox && { sandbox: workflowInput.sandbox }
     };
-    return fn(prompt, sessionInput, context ?? {});
+    const { destroySandbox, ...result } = await fn(
+      prompt,
+      sessionInput,
+      context ?? {}
+    );
+    if (effectiveShutdown === "pause-until-parent-close") {
+      if (!destroySandbox) {
+        throw workflow.ApplicationFailure.create({
+          message: `Subagent "${config.name}" has sandboxShutdown="pause-until-parent-close" but fn did not return a destroySandbox callback`,
+          nonRetryable: true
+        });
+      }
+      if (!result.sandboxId) {
+        throw workflow.ApplicationFailure.create({
+          message: `Subagent "${config.name}" has sandboxShutdown="pause-until-parent-close" but fn did not return a sandboxId`,
+          nonRetryable: true
+        });
+      }
+    }
+    const { parent } = workflow.workflowInfo();
+    if (!parent) {
+      throw workflow.ApplicationFailure.create({
+        message: "Subagent workflow called without a parent workflow",
+        nonRetryable: true
+      });
+    }
+    const parentHandle = workflow.getExternalWorkflowHandle(parent.workflowId);
+    await parentHandle.signal(childResultSignal, {
+      childWorkflowId: workflow.workflowInfo().workflowId,
+      result
+    });
+    if (destroySandbox) {
+      let destroyRequested = false;
+      workflow.setHandler(destroySandboxSignal, () => {
+        destroyRequested = true;
+      });
+      await workflow.condition(() => destroyRequested);
+      await destroySandbox();
+    }
+    return result;
   };
-  Object.defineProperty(workflow, "name", { value: config.name });
-  return Object.assign(workflow, {
+  Object.defineProperty(workflow$1, "name", { value: config.name });
+  return Object.assign(workflow$1, {
     agentName: config.name,
     description: config.description,
     ...config.resultSchema !== void 0 && {
@@ -1555,7 +1801,11 @@ var FileSystemSkillProvider = class {
     for (const dir of dirs) {
       const raw = await this.fs.readFile(path.join(this.baseDir, dir, "SKILL.md"));
       const { frontmatter } = parseSkillFile(raw);
-      skills.push(frontmatter);
+      const location = path.join(this.baseDir, dir);
+      skills.push({
+        ...frontmatter,
+        location
+      });
     }
     return skills;
   }
@@ -1569,7 +1819,15 @@ var FileSystemSkillProvider = class {
         `Skill directory "${name}" contains SKILL.md with mismatched name "${frontmatter.name}"`
       );
     }
-    return { ...frontmatter, instructions: body };
+    const location = path.join(this.baseDir, name);
+    const resourcePaths = await this.discoverResources(name);
+    const resourceContents = await this.readResourceContents(location, resourcePaths);
+    return {
+      ...frontmatter,
+      instructions: body,
+      location,
+      ...resourceContents && { resourceContents }
+    };
   }
   /**
    * Convenience method to load all skills with full instructions.
@@ -1581,10 +1839,48 @@ var FileSystemSkillProvider = class {
     for (const dir of dirs) {
       const raw = await this.fs.readFile(path.join(this.baseDir, dir, "SKILL.md"));
       const { frontmatter, body } = parseSkillFile(raw);
-      skills.push({ ...frontmatter, instructions: body });
+      const location = path.join(this.baseDir, dir);
+      const resourcePaths = await this.discoverResources(dir);
+      const resourceContents = await this.readResourceContents(location, resourcePaths);
+      skills.push({
+        ...frontmatter,
+        instructions: body,
+        location,
+        ...resourceContents && { resourceContents }
+      });
     }
     return skills;
   }
+  /**
+   * Recursively discovers all non-SKILL.md files inside the skill directory
+   * and returns their paths relative to the skill root.
+   */
+  async discoverResources(skillDir) {
+    const skillRoot = path.join(this.baseDir, skillDir);
+    const resources = [];
+    const walk2 = async (dir, prefix) => {
+      const entries = await this.fs.readdirWithFileTypes(dir);
+      for (const e of entries) {
+        if (e.name.startsWith(".")) continue;
+        const relPath = prefix ? `${prefix}/${e.name}` : e.name;
+        if (e.isDirectory) {
+          await walk2(path.join(dir, e.name), relPath);
+        } else if (e.isFile && e.name !== "SKILL.md") {
+          resources.push(relPath);
+        }
+      }
+    };
+    await walk2(skillRoot, "");
+    return resources;
+  }
+  async readResourceContents(location, resources) {
+    if (resources.length === 0) return void 0;
+    const contents = {};
+    for (const r of resources) {
+      contents[r] = await this.fs.readFile(path.join(location, r));
+    }
+    return contents;
+  }
   async discoverSkillDirs() {
     const entries = await this.fs.readdirWithFileTypes(this.baseDir);
     const dirs = [];
@@ -1717,6 +2013,9 @@ var SandboxManager = class {
   async destroy(id) {
     await this.provider.destroy(id);
   }
+  async pause(id, ttlSeconds) {
+    await this.provider.pause(id, ttlSeconds);
+  }
   async snapshot(id) {
     return this.provider.snapshot(id);
   }
@@ -1757,6 +2056,9 @@ var SandboxManager = class {
       destroySandbox: async (sandboxId) => {
         await this.destroy(sandboxId);
       },
+      pauseSandbox: async (sandboxId, ttlSeconds) => {
+        await this.pause(sandboxId, ttlSeconds);
+      },
       snapshotSandbox: async (sandboxId) => {
         return this.snapshot(sandboxId);
       },
@@ -1770,6 +2072,75 @@ var SandboxManager = class {
     );
   }
 };
+var NodeFsSandboxFileSystem = class {
+  workspaceBase;
+  constructor(workspaceBase) {
+    this.workspaceBase = workspaceBase;
+  }
+  abs(path$1) {
+    return path.resolve(this.workspaceBase, path$1);
+  }
+  async readFile(path) {
+    return fs.promises.readFile(this.abs(path), "utf-8");
+  }
+  async readFileBuffer(path) {
+    return fs.promises.readFile(this.abs(path));
+  }
+  async writeFile(path, content) {
+    await fs.promises.writeFile(this.abs(path), content);
+  }
+  async appendFile(path, content) {
+    await fs.promises.appendFile(this.abs(path), content);
+  }
+  async exists(path) {
+    try {
+      await fs.promises.access(this.abs(path));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async stat(path) {
+    const s = await fs.promises.stat(this.abs(path));
+    return {
+      isFile: s.isFile(),
+      isDirectory: s.isDirectory(),
+      isSymbolicLink: s.isSymbolicLink(),
+      size: s.size,
+      mtime: s.mtime
+    };
+  }
+  async mkdir(path, options) {
+    await fs.promises.mkdir(this.abs(path), options);
+  }
+  async readdir(path) {
+    return fs.promises.readdir(this.abs(path));
+  }
+  async readdirWithFileTypes(path) {
+    const entries = await fs.promises.readdir(this.abs(path), { withFileTypes: true });
+    return entries.map((e) => ({
+      name: e.name,
+      isFile: e.isFile(),
+      isDirectory: e.isDirectory(),
+      isSymbolicLink: e.isSymbolicLink()
+    }));
+  }
+  async rm(path, options) {
+    await fs.promises.rm(this.abs(path), options);
+  }
+  async cp(src, dest, options) {
+    await fs.promises.cp(this.abs(src), this.abs(dest), options);
+  }
+  async mv(src, dest) {
+    await fs.promises.rename(this.abs(src), this.abs(dest));
+  }
+  async readlink(path) {
+    return fs.promises.readlink(this.abs(path));
+  }
+  resolvePath(base, path$1) {
+    return path.posix.resolve(base, path$1);
+  }
+};
 
 // src/tools/bash/handler.ts
 var bashHandler = async (args, { sandbox }) => {
@@ -2026,6 +2397,7 @@ var toTree = async (fs, opts = {}) => {
 };
 
 exports.FileSystemSkillProvider = FileSystemSkillProvider;
+exports.NodeFsSandboxFileSystem = NodeFsSandboxFileSystem;
 exports.SandboxManager = SandboxManager;
 exports.SandboxNotFoundError = SandboxNotFoundError;
 exports.SandboxNotSupportedError = SandboxNotSupportedError;