zeitlich 0.2.22 → 0.2.24

package/dist/workflow.js

@@ -1,4 +1,4 @@
-import { uuid4, setHandler, defineUpdate, ApplicationFailure, condition, defineQuery, workflowInfo, executeChild } from '@temporalio/workflow';
+import { defineSignal, uuid4, setHandler, defineUpdate, ApplicationFailure, condition, defineQuery, workflowInfo, getExternalWorkflowHandle, startChild } from '@temporalio/workflow';
 import z14, { z } from 'zod';
 import { ApplicationFailure as ApplicationFailure$1 } from '@temporalio/common';
 
@@ -79,7 +79,12 @@ function createToolRouter(options) {
           result: { error: errorStr, suppressed: true }
         };
     }
-    throw 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) {
@@ -88,7 +93,8 @@ function createToolRouter(options) {
         result: toolResult.data,
         threadId: options.threadId,
         turn,
-        durationMs
+        durationMs,
+        ...toolResult.metadata && { metadata: toolResult.metadata }
       });
     }
     if (options.hooks?.onPostToolUse) {
@@ -101,7 +107,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);
@@ -121,13 +127,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,
@@ -136,6 +144,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);
@@ -168,7 +177,8 @@ function createToolRouter(options) {
     const toolResult = {
       toolCallId: toolCall.id,
       name: toolCall.name,
-      data: result
+      data: result,
+      ...metadata && { metadata }
     };
     await runPostHooks(
       toolCall,
@@ -218,9 +228,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
@@ -228,7 +239,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);
         }
@@ -272,7 +283,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) {
@@ -316,7 +328,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");
@@ -332,7 +344,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.enum(names).describe("The type of subagent to launch"),
@@ -351,9 +363,25 @@ function createSubagentTool(subagents) {
     schema
   };
 }
+var childResultSignal = defineSignal("childResult");
+var destroySandboxSignal = 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 } = workflowInfo();
-  return async (args, context) => {
+  const childResults = /* @__PURE__ */ new Map();
+  const pendingDestroys = /* @__PURE__ */ new Map();
+  const threadSandboxes = /* @__PURE__ */ new Map();
+  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(
@@ -362,12 +390,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 = {
@@ -375,17 +427,44 @@ function createSubagentHandler(subagents) {
       args: resolvedContext === void 0 ? [args.prompt, workflowInput] : [args.prompt, workflowInput, resolvedContext],
       taskQueue: config.taskQueue ?? parentTaskQueue
     };
+    const childHandle = await startChild(config.workflow, childOpts);
+    const usesOwnSandbox = sandboxCfg.source === "own" || allowsContinuation && sandboxCfg.source !== "inherit";
+    if (usesOwnSandbox) {
+      pendingDestroys.set(childWorkflowId, childHandle);
+    }
+    await Promise.race([
+      condition(() => childResults.has(childWorkflowId)),
+      childHandle.result()
+    ]);
+    if (!childResults.has(childWorkflowId)) {
+      await 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 executeChild(config.workflow, childOpts) : await 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;
@@ -393,11 +472,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;
@@ -405,9 +486,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
@@ -421,12 +515,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) => {
@@ -444,6 +539,7 @@ function buildSubagentRegistration(subagents) {
       }
     }
   };
+  return { registration, destroySubagentSandboxes };
 }
 var READ_SKILL_TOOL_NAME = "ReadSkill";
 function buildReadSkillDescription(skills) {
@@ -469,6 +565,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) => {
@@ -482,22 +601,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 = {},
@@ -510,13 +649,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,
@@ -525,9 +678,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);
@@ -575,12 +732,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 ApplicationFailure.create({
+            message: "sandboxId provided but no sandboxOps \u2014 cannot manage sandbox lifecycle",
+            nonRetryable: true
+          });
+        }
+      } else if (sandboxMode === "continue") {
+        if (!sandboxOps) {
+          throw ApplicationFailure.create({
+            message: "No sandboxOps provided \u2014 cannot continue sandbox",
+            nonRetryable: true
+          });
+        }
+        sandboxId = sandboxInit.sandboxId;
+        sandboxOwned = true;
+      } else if (sandboxMode === "fork") {
+        if (!sandboxOps) {
+          throw 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);
         }
       }
@@ -592,9 +789,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 ApplicationFailure.create({
@@ -629,7 +826,8 @@ var createSession = async ({
               threadId,
               finalMessage: message,
               exitReason,
-              usage: stateManager.getTotalUsage()
+              usage: stateManager.getTotalUsage(),
+              sandboxId
             };
           }
           const parsedToolCalls = [];
@@ -651,7 +849,8 @@ var createSession = async ({
             parsedToolCalls,
             {
               turn: currentTurn,
-              ...sandboxId !== void 0 && { sandboxId }
+              ...sandboxId !== void 0 && { sandboxId },
+              ...sandboxStateUpdate && { sandboxStateUpdate }
             }
           );
           for (const result of toolCallResults) {
@@ -680,30 +879,40 @@ var createSession = async ({
         throw 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);
   };
@@ -884,19 +1093,55 @@ function defineSubagent(definition, overrides) {
     ...overrides
   };
 }
-
-// src/lib/subagent/workflow.ts
 function defineSubagentWorkflow(config, fn) {
   const workflow = 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 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 ApplicationFailure.create({
+          message: `Subagent "${config.name}" has sandboxShutdown="pause-until-parent-close" but fn did not return a sandboxId`,
+          nonRetryable: true
+        });
+      }
+    }
+    const { parent } = workflowInfo();
+    if (!parent) {
+      throw ApplicationFailure.create({
+        message: "Subagent workflow called without a parent workflow",
+        nonRetryable: true
+      });
+    }
+    const parentHandle = getExternalWorkflowHandle(parent.workflowId);
+    await parentHandle.signal(childResultSignal, {
+      childWorkflowId: workflowInfo().workflowId,
+      result
+    });
+    if (destroySandbox) {
+      let destroyRequested = false;
+      setHandler(destroySandboxSignal, () => {
+        destroyRequested = true;
+      });
+      await condition(() => destroyRequested);
+      await destroySandbox();
+    }
+    return result;
   };
   Object.defineProperty(workflow, "name", { value: config.name });
   return Object.assign(workflow, {