zeitlich 0.2.21 → 0.2.23

package/dist/index.js

@@ -1,4 +1,4 @@
-import { uuid4, setHandler, defineUpdate, ApplicationFailure, condition, proxyActivities, 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 { randomUUID, randomFillSync } from 'crypto';
 import { ApplicationFailure as ApplicationFailure$1 } from '@temporalio/common';
@@ -82,7 +82,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) {
@@ -91,7 +96,8 @@ function createToolRouter(options) {
         result: toolResult.data,
         threadId: options.threadId,
         turn,
-        durationMs
+        durationMs,
+        ...toolResult.metadata && { metadata: toolResult.metadata }
       });
     }
     if (options.hooks?.onPostToolUse) {
@@ -124,6 +130,7 @@ function createToolRouter(options) {
     let result;
     let content;
     let resultAppended = false;
+    let metadata;
     try {
       if (tool) {
         const routerContext = {
@@ -139,6 +146,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);
@@ -171,7 +179,8 @@ function createToolRouter(options) {
     const toolResult = {
       toolCallId: toolCall.id,
       name: toolCall.name,
-      data: result
+      data: result,
+      ...metadata && { metadata }
     };
     await runPostHooks(
       toolCall,
@@ -275,7 +284,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) {
@@ -319,7 +329,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");
@@ -335,7 +345,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"),
@@ -354,9 +364,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(
@@ -365,29 +391,77 @@ 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 };
+    } 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 = {
       workflowId: childWorkflowId,
-      args: config.context === void 0 ? [args.prompt, workflowInput] : [args.prompt, workflowInput, config.context],
+      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;
@@ -395,11 +469,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;
@@ -407,9 +483,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
@@ -423,12 +512,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) => {
@@ -446,6 +536,7 @@ function buildSubagentRegistration(subagents) {
       }
     }
   };
+  return { registration, destroySubagentSandboxes };
 }
 var READ_SKILL_TOOL_NAME = "ReadSkill";
 function buildReadSkillDescription(skills) {
@@ -498,8 +589,7 @@ function buildSkillRegistration(skills) {
     handler: createReadSkillHandler(skills)
   };
 }
-var createSession = async ({
-  threadId: providedThreadId,
+async function createSession({
   agentName,
   maxTurns = 50,
   metadata = {},
@@ -512,24 +602,42 @@ 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,
     initializeThread,
     appendSystemMessage,
     forkThread
-  } = threadOps ?? proxyDefaultThreadOps();
+  } = 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);
@@ -577,11 +685,41 @@ 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;
+      if (sandboxMode === "inherit") {
+        sandboxId = sandboxInit.sandboxId;
+        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 result = await sandboxOps.createSandbox();
         sandboxId = result.sandboxId;
+        sandboxOwned = true;
         if (result.stateUpdate) {
           stateManager.mergeUpdate(result.stateUpdate);
         }
@@ -594,9 +732,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({
@@ -631,7 +769,8 @@ var createSession = async ({
               threadId,
               finalMessage: message,
               exitReason,
-              usage: stateManager.getTotalUsage()
+              usage: stateManager.getTotalUsage(),
+              sandboxId
             };
           }
           const parsedToolCalls = [];
@@ -682,55 +821,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
       };
     }
   };
-};
-function proxyDefaultThreadOps(options) {
-  return proxyActivities(
-    options ?? {
-      startToCloseTimeout: "10s",
-      retry: {
-        maximumAttempts: 6,
-        initialInterval: "5s",
-        maximumInterval: "15m",
-        backoffCoefficient: 4
-      }
-    }
-  );
-}
-function proxySandboxOps(options) {
-  return proxyActivities(
-    options ?? {
-      startToCloseTimeout: "30s",
-      retry: {
-        maximumAttempts: 3,
-        initialInterval: "2s",
-        maximumInterval: "30s",
-        backoffCoefficient: 2
-      }
-    }
-  );
 }
 
 // src/lib/workflow.ts
 function defineWorkflow(config, fn) {
   const workflow = async (input, workflowInput = {}) => {
     const sessionInput = {
-      ...workflowInput.previousThreadId && {
-        threadId: workflowInput.previousThreadId,
-        continueThread: true
-      },
-      ...workflowInput.sandboxId && { sandboxId: workflowInput.sandboxId }
+      agentName: config.name,
+      sandboxShutdown: config.sandboxShutdown ?? "destroy",
+      ...workflowInput.thread && { thread: workflowInput.thread },
+      ...workflowInput.sandbox && { sandbox: workflowInput.sandbox }
     };
     return fn(input, sessionInput);
   };
@@ -988,19 +1112,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, {
@@ -1735,6 +1895,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);
   }
@@ -1742,22 +1905,53 @@ var SandboxManager = class {
     const sandbox = await this.provider.restore(snapshot);
     return sandbox.id;
   }
+  async fork(sandboxId) {
+    const sandbox = await this.provider.fork(sandboxId);
+    return sandbox.id;
+  }
   /**
-   * Returns Temporal activity functions matching {@link SandboxOps}.
-   * Spread these into your worker's activity map.
+   * Returns Temporal activity functions with prefixed names.
+   *
+   * The provider's `id` is automatically prepended, so you only need
+   * to pass the workflow/scope name. Use the matching `proxy*SandboxOps()`
+   * helper from the adapter's `/workflow` entrypoint on the workflow side.
+   *
+   * @param scope - Workflow name (appended to the provider id)
+   *
+   * @example
+   * ```typescript
+   * const manager = new SandboxManager(new InMemorySandboxProvider());
+   * manager.createActivities("CodingAgent");
+   * // registers: inMemoryCodingAgentCreateSandbox, inMemoryCodingAgentDestroySandbox, …
+   *
+   * const vmgr = new SandboxManager(new VirtualSandboxProvider(resolver));
+   * vmgr.createActivities("CodingAgent");
+   * // registers: virtualCodingAgentCreateSandbox, …
+   * ```
    */
-  createActivities() {
-    return {
+  createActivities(scope) {
+    const prefix = `${this.provider.id}${scope.charAt(0).toUpperCase()}${scope.slice(1)}`;
+    const ops = {
       createSandbox: async (options) => {
         return this.create(options);
       },
       destroySandbox: async (sandboxId) => {
         await this.destroy(sandboxId);
       },
+      pauseSandbox: async (sandboxId, ttlSeconds) => {
+        await this.pause(sandboxId, ttlSeconds);
+      },
       snapshotSandbox: async (sandboxId) => {
         return this.snapshot(sandboxId);
+      },
+      forkSandbox: async (sandboxId) => {
+        return this.fork(sandboxId);
       }
     };
+    const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+    return Object.fromEntries(
+      Object.entries(ops).map(([k, v]) => [`${prefix}${cap(k)}`, v])
+    );
   }
 };
 
@@ -2015,6 +2209,6 @@ var toTree = async (fs, opts = {}) => {
   return base + subtree;
 };
 
-export { FileSystemSkillProvider, SandboxManager, SandboxNotFoundError, SandboxNotSupportedError, applyVirtualTreeMutations, askUserQuestionTool, bashHandler, bashTool, createAgentStateManager, createAskUserQuestionHandler, createBashToolDescription, createReadSkillHandler, createReadSkillTool, createRunAgentActivity, createSession, createTaskCreateHandler, createTaskGetHandler, createTaskListHandler, createTaskUpdateHandler, createThreadManager, createToolRouter, defineSubagent, defineSubagentWorkflow, defineTool, defineWorkflow, editHandler, editTool, filesWithMimeType, formatVirtualFileTree, getShortId, globHandler, globTool, grepTool, hasDirectory, hasFileWithMimeType, hasNoOtherToolCalls, isTerminalStatus, parseSkillFile, proxyDefaultThreadOps, proxySandboxOps, queryParentWorkflowState, readFileHandler, readFileTool, taskCreateTool, taskGetTool, taskListTool, taskUpdateTool, toTree, withAutoAppend, withParentWorkflowState, withSandbox, writeFileHandler, writeFileTool };
+export { FileSystemSkillProvider, SandboxManager, SandboxNotFoundError, SandboxNotSupportedError, applyVirtualTreeMutations, askUserQuestionTool, bashHandler, bashTool, createAgentStateManager, createAskUserQuestionHandler, createBashToolDescription, createReadSkillHandler, createReadSkillTool, createRunAgentActivity, createSession, createTaskCreateHandler, createTaskGetHandler, createTaskListHandler, createTaskUpdateHandler, createThreadManager, createToolRouter, defineSubagent, defineSubagentWorkflow, defineTool, defineWorkflow, editHandler, editTool, filesWithMimeType, formatVirtualFileTree, getShortId, globHandler, globTool, grepTool, hasDirectory, hasFileWithMimeType, hasNoOtherToolCalls, isTerminalStatus, parseSkillFile, queryParentWorkflowState, readFileHandler, readFileTool, taskCreateTool, taskGetTool, taskListTool, taskUpdateTool, toTree, withAutoAppend, withParentWorkflowState, withSandbox, writeFileHandler, writeFileTool };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map