zeitlich 0.2.13 → 0.2.14

package/dist/workflow.js

@@ -1,148 +1,8 @@
 import { uuid4, setHandler, defineUpdate, ApplicationFailure, condition, proxyActivities, defineQuery, workflowInfo, executeChild } from '@temporalio/workflow';
 import z14, { z } from 'zod';
+import { ApplicationFailure as ApplicationFailure$1 } from '@temporalio/common';
 
-// src/lib/session.ts
-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)*" : "";
-    return `## ${s.agentName}
-${s.description}${continuation}`;
-  }).join("\n\n");
-  return `The ${SUBAGENT_TOOL_NAME} tool launches specialized agents (subagents) that autonomously handle complex work. Each agent type has specific capabilities and tools available to it.
-
-# Available subagents:
-${subagentList}
-`;
-}
-function createSubagentTool(subagents) {
-  if (subagents.length === 0) {
-    throw new Error("createTaskTool requires at least one subagent");
-  }
-  const names = subagents.map((s) => s.agentName);
-  const hasThreadContinuation = subagents.some(
-    (s) => s.allowThreadContinuation
-  );
-  const baseFields = {
-    subagent: z14.enum(names).describe("The type of subagent to launch"),
-    description: z14.string().describe("A short (3-5 word) description of the task"),
-    prompt: z14.string().describe("The task for the agent to perform")
-  };
-  const schema = hasThreadContinuation ? z14.object({
-    ...baseFields,
-    threadId: z14.string().nullable().describe(
-      "Thread ID to continue an existing conversation, or null to start a new one"
-    )
-  }) : z14.object(baseFields);
-  return {
-    name: SUBAGENT_TOOL_NAME,
-    description: buildSubagentDescription(subagents),
-    schema
-  };
-}
-var BASE62 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
-function getShortId(length = 12) {
-  const hex = uuid4().replace(/-/g, "");
-  let result = "";
-  for (let i = 0; i < length; i++) {
-    const byte = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
-    result += BASE62[byte % BASE62.length];
-  }
-  return result;
-}
-
-// src/tools/subagent/handler.ts
-function createSubagentHandler(subagents) {
-  const { taskQueue: parentTaskQueue } = workflowInfo();
-  return async (args) => {
-    const config = subagents.find((s) => s.agentName === args.subagent);
-    if (!config) {
-      throw new Error(
-        `Unknown subagent: ${args.subagent}. Available: ${subagents.map((s) => s.agentName).join(", ")}`
-      );
-    }
-    const childWorkflowId = `${args.subagent}-${getShortId()}`;
-    const input = {
-      prompt: args.prompt,
-      ...config.context && { context: config.context },
-      ...args.threadId && config.allowThreadContinuation && { threadId: args.threadId }
-    };
-    const childOpts = {
-      workflowId: childWorkflowId,
-      args: [input],
-      taskQueue: config.taskQueue ?? parentTaskQueue
-    };
-    const { toolResponse, data, usage, threadId: childThreadId } = typeof config.workflow === "string" ? await executeChild(config.workflow, childOpts) : await executeChild(config.workflow, childOpts);
-    if (!toolResponse) {
-      return {
-        toolResponse: "Subagent workflow returned no response",
-        data: null,
-        ...usage && { usage }
-      };
-    }
-    const validated = config.resultSchema ? config.resultSchema.safeParse(data) : null;
-    if (validated && !validated.success) {
-      return {
-        toolResponse: `Subagent workflow returned invalid data: ${validated.error.message}`,
-        data: null,
-        ...usage && { usage }
-      };
-    }
-    let finalToolResponse = toolResponse;
-    if (config.allowThreadContinuation && childThreadId) {
-      finalToolResponse = typeof toolResponse === "string" ? `${toolResponse}
-
-[Thread ID: ${childThreadId}]` : toolResponse;
-    }
-    return {
-      toolResponse: finalToolResponse,
-      data: validated ? validated.data : data,
-      ...usage && { usage }
-    };
-  };
-}
-var READ_SKILL_TOOL_NAME = "ReadSkill";
-function buildReadSkillDescription(skills) {
-  const skillList = skills.map((s) => `- **${s.name}**: ${s.description}`).join("\n");
-  return `Load the full instructions for a skill. Read the skill before following its instructions.
-
-# Available skills:
-${skillList}
-`;
-}
-function createReadSkillTool(skills) {
-  if (skills.length === 0) {
-    throw new Error("createReadSkillTool requires at least one skill");
-  }
-  const names = skills.map((s) => s.name);
-  return {
-    name: READ_SKILL_TOOL_NAME,
-    description: buildReadSkillDescription(skills),
-    schema: z14.object({
-      skill_name: z14.enum(names).describe("The name of the skill to load")
-    })
-  };
-}
-
-// src/tools/read-skill/handler.ts
-function createReadSkillHandler(skills) {
-  const skillMap = new Map(skills.map((s) => [s.name, s]));
-  return (args) => {
-    const skill = skillMap.get(args.skill_name);
-    if (!skill) {
-      return {
-        toolResponse: JSON.stringify({
-          error: `Skill "${args.skill_name}" not found`
-        }),
-        data: null
-      };
-    }
-    return {
-      toolResponse: skill.instructions,
-      data: null
-    };
-  };
-}
+// src/lib/session/session.ts
 function createToolRouter(options) {
   const { appendToolResult } = options;
   const toolMap = /* @__PURE__ */ new Map();
@@ -150,45 +10,12 @@ function createToolRouter(options) {
     toolMap.set(tool.name, tool);
   }
   const isEnabled = (tool) => tool.enabled ?? true;
-  if (options.subagents) {
-    if (options.subagents.length > 0) {
-      const subagentHooksMap = /* @__PURE__ */ new Map();
-      for (const s of options.subagents) {
-        if (s.hooks) subagentHooksMap.set(s.agentName, s.hooks);
-      }
-      const resolveSubagentName = (args) => args.subagent;
-      toolMap.set(SUBAGENT_TOOL_NAME, {
-        ...createSubagentTool(options.subagents),
-        handler: createSubagentHandler(options.subagents),
-        ...subagentHooksMap.size > 0 && {
-          hooks: {
-            onPreToolUse: async (ctx) => {
-              const hooks = subagentHooksMap.get(resolveSubagentName(ctx.args));
-              return hooks?.onPreExecution?.(ctx) ?? {};
-            },
-            onPostToolUse: async (ctx) => {
-              const hooks = subagentHooksMap.get(resolveSubagentName(ctx.args));
-              await hooks?.onPostExecution?.(ctx);
-            },
-            onPostToolUseFailure: async (ctx) => {
-              const hooks = subagentHooksMap.get(resolveSubagentName(ctx.args));
-              return hooks?.onExecutionFailure?.(ctx) ?? {};
-            }
-          }
-        }
-      });
+  if (options.plugins) {
+    for (const plugin of options.plugins) {
+      toolMap.set(plugin.name, plugin);
     }
   }
-  if (options.skills && options.skills.length > 0) {
-    toolMap.set(READ_SKILL_TOOL_NAME, {
-      ...createReadSkillTool(options.skills),
-      handler: createReadSkillHandler(options.skills)
-    });
-  }
-  async function processToolCall(toolCall, turn, handlerContext) {
-    const startTime = Date.now();
-    const tool = toolMap.get(toolCall.name);
-    const toolHooks = tool?.hooks;
+  async function runPreHooks(toolCall, tool, turn) {
     let effectiveArgs = toolCall.args;
     if (options.hooks?.onPreToolUse) {
       const preResult = await options.hooks.onPreToolUse({
@@ -196,58 +23,105 @@ function createToolRouter(options) {
         threadId: options.threadId,
         turn
       });
-      if (preResult?.skip) {
-        await appendToolResult({
-          threadId: options.threadId,
-          toolCallId: toolCall.id,
-          toolName: toolCall.name,
-          content: JSON.stringify({
-            skipped: true,
-            reason: "Skipped by PreToolUse hook"
-          })
-        });
-        return null;
-      }
-      if (preResult?.modifiedArgs !== void 0) {
+      if (preResult?.skip) return { skip: true };
+      if (preResult?.modifiedArgs !== void 0)
         effectiveArgs = preResult.modifiedArgs;
-      }
     }
-    if (toolHooks?.onPreToolUse) {
-      const preResult = await toolHooks.onPreToolUse({
+    if (tool?.hooks?.onPreToolUse) {
+      const preResult = await tool.hooks.onPreToolUse({
         args: effectiveArgs,
         threadId: options.threadId,
         turn
       });
-      if (preResult?.skip) {
-        await appendToolResult({
-          threadId: options.threadId,
-          toolCallId: toolCall.id,
-          toolName: toolCall.name,
-          content: JSON.stringify({
-            skipped: true,
-            reason: "Skipped by tool PreToolUse hook"
-          })
-        });
-        return null;
-      }
-      if (preResult?.modifiedArgs !== void 0) {
+      if (preResult?.skip) return { skip: true };
+      if (preResult?.modifiedArgs !== void 0)
         effectiveArgs = preResult.modifiedArgs;
-      }
     }
+    return { skip: false, args: effectiveArgs };
+  }
+  async function runFailureHooks(toolCall, tool, error, effectiveArgs, turn) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    const errorStr = String(error);
+    if (tool?.hooks?.onPostToolUseFailure) {
+      const r = await tool.hooks.onPostToolUseFailure({
+        args: effectiveArgs,
+        error: err,
+        threadId: options.threadId,
+        turn
+      });
+      if (r?.fallbackContent !== void 0)
+        return { content: r.fallbackContent, result: { error: errorStr, recovered: true } };
+      if (r?.suppress)
+        return {
+          content: JSON.stringify({ error: errorStr, suppressed: true }),
+          result: { error: errorStr, suppressed: true }
+        };
+    }
+    if (options.hooks?.onPostToolUseFailure) {
+      const r = await options.hooks.onPostToolUseFailure({
+        toolCall,
+        error: err,
+        threadId: options.threadId,
+        turn
+      });
+      if (r?.fallbackContent !== void 0)
+        return { content: r.fallbackContent, result: { error: errorStr, recovered: true } };
+      if (r?.suppress)
+        return {
+          content: JSON.stringify({ error: errorStr, suppressed: true }),
+          result: { error: errorStr, suppressed: true }
+        };
+    }
+    throw ApplicationFailure.fromError(error, { nonRetryable: true });
+  }
+  async function runPostHooks(toolCall, tool, toolResult, effectiveArgs, turn, durationMs) {
+    if (tool?.hooks?.onPostToolUse) {
+      await tool.hooks.onPostToolUse({
+        args: effectiveArgs,
+        result: toolResult.data,
+        threadId: options.threadId,
+        turn,
+        durationMs
+      });
+    }
+    if (options.hooks?.onPostToolUse) {
+      await options.hooks.onPostToolUse({
+        toolCall,
+        result: toolResult,
+        threadId: options.threadId,
+        turn,
+        durationMs
+      });
+    }
+  }
+  async function processToolCall(toolCall, turn, sandboxId) {
+    const startTime = Date.now();
+    const tool = toolMap.get(toolCall.name);
+    const preResult = await runPreHooks(toolCall, tool, turn);
+    if (preResult.skip) {
+      await appendToolResult({
+        threadId: options.threadId,
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        content: JSON.stringify({ skipped: true, reason: "Skipped by PreToolUse hook" })
+      });
+      return null;
+    }
+    const effectiveArgs = preResult.args;
     let result;
     let content;
     let resultAppended = false;
     try {
       if (tool) {
-        const enrichedContext = {
-          ...handlerContext ?? {},
+        const routerContext = {
           threadId: options.threadId,
           toolCallId: toolCall.id,
-          toolName: toolCall.name
+          toolName: toolCall.name,
+          ...sandboxId !== void 0 && { sandboxId }
         };
         const response = await tool.handler(
           effectiveArgs,
-          enrichedContext
+          routerContext
         );
         result = response.data;
         content = response.toolResponse;
@@ -257,47 +131,9 @@ function createToolRouter(options) {
         content = JSON.stringify(result, null, 2);
       }
     } catch (error) {
-      const err = error instanceof Error ? error : new Error(String(error));
-      let recovered = false;
-      if (toolHooks?.onPostToolUseFailure) {
-        const failureResult = await toolHooks.onPostToolUseFailure({
-          args: effectiveArgs,
-          error: err,
-          threadId: options.threadId,
-          turn
-        });
-        if (failureResult?.fallbackContent !== void 0) {
-          content = failureResult.fallbackContent;
-          result = { error: String(error), recovered: true };
-          recovered = true;
-        } else if (failureResult?.suppress) {
-          content = JSON.stringify({ error: String(error), suppressed: true });
-          result = { error: String(error), suppressed: true };
-          recovered = true;
-        }
-      }
-      if (!recovered && options.hooks?.onPostToolUseFailure) {
-        const failureResult = await options.hooks.onPostToolUseFailure({
-          toolCall,
-          error: err,
-          threadId: options.threadId,
-          turn
-        });
-        if (failureResult?.fallbackContent !== void 0) {
-          content = failureResult.fallbackContent;
-          result = { error: String(error), recovered: true };
-          recovered = true;
-        } else if (failureResult?.suppress) {
-          content = JSON.stringify({ error: String(error), suppressed: true });
-          result = { error: String(error), suppressed: true };
-          recovered = true;
-        }
-      }
-      if (!recovered) {
-        throw ApplicationFailure.fromError(error, {
-          nonRetryable: true
-        });
-      }
+      const recovery = await runFailureHooks(toolCall, tool, error, effectiveArgs, turn);
+      result = recovery.result;
+      content = recovery.content;
     }
     if (!resultAppended) {
       await appendToolResult({
@@ -312,29 +148,10 @@ function createToolRouter(options) {
       name: toolCall.name,
       data: result
     };
-    const durationMs = Date.now() - startTime;
-    if (toolHooks?.onPostToolUse) {
-      await toolHooks.onPostToolUse({
-        args: effectiveArgs,
-        result,
-        threadId: options.threadId,
-        turn,
-        durationMs
-      });
-    }
-    if (options.hooks?.onPostToolUse) {
-      await options.hooks.onPostToolUse({
-        toolCall,
-        result: toolResult,
-        threadId: options.threadId,
-        turn,
-        durationMs
-      });
-    }
+    await runPostHooks(toolCall, tool, toolResult, effectiveArgs, turn, Date.now() - startTime);
     return toolResult;
   }
   return {
-    // --- Methods from registry ---
     hasTools() {
       return Array.from(toolMap.values()).some(isEnabled);
     },
@@ -358,32 +175,25 @@ function createToolRouter(options) {
       return Array.from(toolMap.entries()).filter(([, tool]) => isEnabled(tool)).map(([name]) => name);
     },
     getToolDefinitions() {
-      const activeSubagents = options.subagents?.filter((subagent) => isEnabled(subagent)) ?? [];
-      const activeSkills = options.skills ?? [];
-      return [
-        ...Array.from(toolMap).filter(
-          ([, tool]) => isEnabled(tool) && tool.name !== SUBAGENT_TOOL_NAME && tool.name !== READ_SKILL_TOOL_NAME
-        ).map(([name, tool]) => ({
-          name,
-          description: tool.description,
-          schema: tool.schema,
-          strict: tool.strict,
-          max_uses: tool.max_uses
-        })),
-        ...activeSubagents.length > 0 ? [createSubagentTool(activeSubagents)] : [],
-        ...activeSkills.length > 0 ? [createReadSkillTool(activeSkills)] : []
-      ];
+      return Array.from(toolMap).filter(([, tool]) => isEnabled(tool)).map(([name, tool]) => ({
+        name,
+        description: tool.description,
+        schema: tool.schema,
+        strict: tool.strict,
+        max_uses: tool.max_uses
+      }));
     },
-    // --- Methods for processing tool calls ---
     async processToolCalls(toolCalls, context) {
       if (toolCalls.length === 0) {
         return [];
       }
       const turn = context?.turn ?? 0;
-      const handlerContext = context?.handlerContext;
+      const sandboxId = context?.sandboxId;
       if (options.parallel) {
         const results2 = await Promise.all(
-          toolCalls.map((tc) => processToolCall(tc, turn, handlerContext))
+          toolCalls.map(
+            (tc) => processToolCall(tc, turn, sandboxId)
+          )
         );
         return results2.filter(
           (r) => r !== null
@@ -391,7 +201,11 @@ function createToolRouter(options) {
       }
       const results = [];
       for (const toolCall of toolCalls) {
-        const result = await processToolCall(toolCall, turn, handlerContext);
+        const result = await processToolCall(
+          toolCall,
+          turn,
+          sandboxId
+        );
         if (result !== null) {
           results.push(result);
         }
@@ -403,17 +217,16 @@ function createToolRouter(options) {
       if (matchingCalls.length === 0) {
         return [];
       }
-      const handlerContext = context?.handlerContext ?? {};
       const processOne = async (toolCall) => {
-        const enrichedContext = {
-          ...handlerContext ?? {},
+        const routerContext = {
           threadId: options.threadId,
           toolCallId: toolCall.id,
-          toolName: toolCall.name
+          toolName: toolCall.name,
+          ...context?.sandboxId !== void 0 && { sandboxId: context.sandboxId }
         };
         const response = await handler(
           toolCall.args,
-          enrichedContext
+          routerContext
         );
         if (!response.resultAppended) {
           await appendToolResult({
@@ -438,7 +251,6 @@ function createToolRouter(options) {
       }
       return results;
     },
-    // --- Utility methods ---
     filterByName(toolCalls, name) {
       return toolCalls.filter(
         (tc) => tc.name === name
@@ -455,14 +267,198 @@ function createToolRouter(options) {
 function defineTool(tool) {
   return tool;
 }
-function defineSubagent(config) {
-  return config;
-}
 function hasNoOtherToolCalls(toolCalls, excludeName) {
   return toolCalls.filter((tc) => tc.name !== excludeName).length === 0;
 }
+var BASE62 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+function getShortId(length = 12) {
+  const hex = uuid4().replace(/-/g, "");
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    const byte = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    result += BASE62[byte % BASE62.length];
+  }
+  return result;
+}
+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)*" : "";
+    return `## ${s.agentName}
+${s.description}${continuation}`;
+  }).join("\n\n");
+  return `The ${SUBAGENT_TOOL_NAME} tool launches specialized agents (subagents) that autonomously handle complex work. Each agent type has specific capabilities and tools available to it.
+
+# Available subagents:
+${subagentList}
+`;
+}
+function createSubagentTool(subagents) {
+  if (subagents.length === 0) {
+    throw new Error("createSubagentTool requires at least one subagent");
+  }
+  const names = subagents.map((s) => s.agentName);
+  const hasThreadContinuation = subagents.some(
+    (s) => s.allowThreadContinuation
+  );
+  const baseFields = {
+    subagent: z14.enum(names).describe("The type of subagent to launch"),
+    description: z14.string().describe("A short (3-5 word) description of the task"),
+    prompt: z14.string().describe("The task for the agent to perform")
+  };
+  const schema = hasThreadContinuation ? z14.object({
+    ...baseFields,
+    threadId: z14.string().nullable().describe(
+      "Thread ID to continue an existing conversation, or null to start a new one"
+    )
+  }) : z14.object(baseFields);
+  return {
+    name: SUBAGENT_TOOL_NAME,
+    description: buildSubagentDescription(subagents),
+    schema
+  };
+}
+function createSubagentHandler(subagents) {
+  const { taskQueue: parentTaskQueue } = workflowInfo();
+  return async (args, context) => {
+    const config = subagents.find((s) => s.agentName === args.subagent);
+    if (!config) {
+      throw new Error(
+        `Unknown subagent: ${args.subagent}. Available: ${subagents.map((s) => s.agentName).join(", ")}`
+      );
+    }
+    const childWorkflowId = `${args.subagent}-${getShortId()}`;
+    const { sandboxId: parentSandboxId } = context;
+    const inheritSandbox = config.sandbox !== "own" && !!parentSandboxId;
+    const input = {
+      prompt: args.prompt,
+      ...config.context && { context: config.context },
+      ...args.threadId && args.threadId !== null && config.allowThreadContinuation && { previousThreadId: args.threadId },
+      ...inheritSandbox && { sandboxId: parentSandboxId }
+    };
+    const childOpts = {
+      workflowId: childWorkflowId,
+      args: [input],
+      taskQueue: config.taskQueue ?? parentTaskQueue
+    };
+    const {
+      toolResponse,
+      data,
+      usage,
+      threadId: childThreadId
+    } = typeof config.workflow === "string" ? await executeChild(config.workflow, childOpts) : await executeChild(config.workflow, childOpts);
+    if (!toolResponse) {
+      return {
+        toolResponse: "Subagent workflow returned no response",
+        data: null,
+        ...usage && { usage }
+      };
+    }
+    const validated = config.resultSchema ? config.resultSchema.safeParse(data) : null;
+    if (validated && !validated.success) {
+      return {
+        toolResponse: `Subagent workflow returned invalid data: ${validated.error.message}`,
+        data: null,
+        ...usage && { usage }
+      };
+    }
+    let finalToolResponse = toolResponse;
+    if (config.allowThreadContinuation && childThreadId) {
+      finalToolResponse = typeof toolResponse === "string" ? `${toolResponse}
+
+[Thread ID: ${childThreadId}]` : toolResponse;
+    }
+    return {
+      toolResponse: finalToolResponse,
+      data: validated ? validated.data : data,
+      ...usage && { usage }
+    };
+  };
+}
+
+// src/lib/subagent/register.ts
+function buildSubagentRegistration(subagents) {
+  const enabled = subagents.filter((s) => s.enabled ?? true);
+  if (enabled.length === 0) return null;
+  const subagentHooksMap = /* @__PURE__ */ new Map();
+  for (const s of enabled) {
+    if (s.hooks) subagentHooksMap.set(s.agentName, s.hooks);
+  }
+  const resolveSubagentName = (args) => args.subagent;
+  return {
+    ...createSubagentTool(enabled),
+    handler: createSubagentHandler(enabled),
+    ...subagentHooksMap.size > 0 && {
+      hooks: {
+        onPreToolUse: async (ctx) => {
+          const hooks = subagentHooksMap.get(resolveSubagentName(ctx.args));
+          return hooks?.onPreExecution?.(ctx) ?? {};
+        },
+        onPostToolUse: async (ctx) => {
+          const hooks = subagentHooksMap.get(resolveSubagentName(ctx.args));
+          await hooks?.onPostExecution?.(ctx);
+        },
+        onPostToolUseFailure: async (ctx) => {
+          const hooks = subagentHooksMap.get(resolveSubagentName(ctx.args));
+          return hooks?.onExecutionFailure?.(ctx) ?? {};
+        }
+      }
+    }
+  };
+}
+var READ_SKILL_TOOL_NAME = "ReadSkill";
+function buildReadSkillDescription(skills) {
+  const skillList = skills.map((s) => `- **${s.name}**: ${s.description}`).join("\n");
+  return `Load the full instructions for a skill. Read the skill before following its instructions.
+
+# Available skills:
+${skillList}
+`;
+}
+function createReadSkillTool(skills) {
+  if (skills.length === 0) {
+    throw new Error("createReadSkillTool requires at least one skill");
+  }
+  const names = skills.map((s) => s.name);
+  return {
+    name: READ_SKILL_TOOL_NAME,
+    description: buildReadSkillDescription(skills),
+    schema: z14.object({
+      skill_name: z14.enum(names).describe("The name of the skill to load")
+    })
+  };
+}
+
+// src/lib/skills/handler.ts
+function createReadSkillHandler(skills) {
+  const skillMap = new Map(skills.map((s) => [s.name, s]));
+  return (args) => {
+    const skill = skillMap.get(args.skill_name);
+    if (!skill) {
+      return {
+        toolResponse: JSON.stringify({
+          error: `Skill "${args.skill_name}" not found`
+        }),
+        data: null
+      };
+    }
+    return {
+      toolResponse: skill.instructions,
+      data: null
+    };
+  };
+}
+
+// src/lib/skills/register.ts
+function buildSkillRegistration(skills) {
+  if (skills.length === 0) return null;
+  return {
+    ...createReadSkillTool(skills),
+    handler: createReadSkillHandler(skills)
+  };
+}
 
-// src/lib/session.ts
+// src/lib/session/session.ts
 var createSession = async ({
   threadId: providedThreadId,
   agentName,
@@ -478,7 +474,9 @@ var createSession = async ({
   hooks = {},
   appendSystemPrompt = true,
   continueThread = false,
-  waitForInputTimeout = "48h"
+  waitForInputTimeout = "48h",
+  sandbox: sandboxOps,
+  sandboxId: inheritedSandboxId
 }) => {
   const threadId = providedThreadId ?? getShortId();
   const {
@@ -487,13 +485,21 @@ var createSession = async ({
     initializeThread,
     appendSystemMessage
   } = threadOps ?? proxyDefaultThreadOps();
+  const plugins = [];
+  if (subagents) {
+    const reg = buildSubagentRegistration(subagents);
+    if (reg) plugins.push(reg);
+  }
+  if (skills) {
+    const reg = buildSkillRegistration(skills);
+    if (reg) plugins.push(reg);
+  }
   const toolRouter = createToolRouter({
     tools,
     appendToolResult,
     threadId,
     hooks,
-    subagents,
-    skills,
+    plugins,
     parallel: processToolsInParallel
   });
   const callSessionEnd = async (exitReason, turns) => {
@@ -530,6 +536,17 @@ var createSession = async ({
           stateManager.run();
         }
       );
+      let sandboxId = inheritedSandboxId;
+      const ownsSandbox = !sandboxId && !!sandboxOps;
+      if (ownsSandbox) {
+        const result = await sandboxOps.createSandbox({ id: threadId });
+        sandboxId = result.sandboxId;
+        if (result.stateUpdate) {
+          stateManager.mergeUpdate(
+            result.stateUpdate
+          );
+        }
+      }
       if (hooks.onSessionStart) {
         await hooks.onSessionStart({
           threadId,
@@ -570,6 +587,7 @@ var createSession = async ({
             stateManager.complete();
             exitReason = "completed";
             return {
+              threadId,
               finalMessage: message,
               exitReason,
               usage: stateManager.getTotalUsage()
@@ -593,7 +611,8 @@ var createSession = async ({
           const toolCallResults = await toolRouter.processToolCalls(
             parsedToolCalls,
             {
-              turn: currentTurn
+              turn: currentTurn,
+              ...sandboxId !== void 0 && { sandboxId }
             }
           );
           for (const result of toolCallResults) {
@@ -621,8 +640,12 @@ var createSession = async ({
         throw ApplicationFailure.fromError(error);
       } finally {
         await callSessionEnd(exitReason, stateManager.getTurns());
+        if (ownsSandbox && sandboxId && sandboxOps) {
+          await sandboxOps.destroySandbox(sandboxId);
+        }
       }
       return {
+        threadId,
         finalMessage: null,
         exitReason,
         usage: stateManager.getTotalUsage()
@@ -643,16 +666,26 @@ function proxyDefaultThreadOps(options) {
     }
   );
 }
+function proxySandboxOps(options) {
+  return proxyActivities(
+    options ?? {
+      startToCloseTimeout: "30s",
+      retry: {
+        maximumAttempts: 3,
+        initialInterval: "2s",
+        maximumInterval: "30s",
+        backoffCoefficient: 2
+      }
+    }
+  );
+}
 
 // src/lib/types.ts
-var agentQueryName = (agentName) => `get${agentName}State`;
-var agentStateChangeUpdateName = (agentName) => `waitFor${agentName}StateChange`;
 function isTerminalStatus(status) {
   return status === "COMPLETED" || status === "FAILED" || status === "CANCELLED";
 }
 function createAgentStateManager({
-  initialState,
-  agentName
+  initialState
 }) {
   let status = initialState?.status ?? "RUNNING";
   let version = initialState?.version ?? 0;
@@ -683,11 +716,9 @@ function createAgentStateManager({
       ...customState
     };
   }
-  const stateQuery = defineQuery(
-    agentQueryName(agentName)
-  );
+  const stateQuery = defineQuery("getAgentState");
   const stateChangeUpdate = defineUpdate(
-    agentStateChangeUpdateName(agentName)
+    "waitForAgentStateChange"
   );
   setHandler(stateQuery, () => buildState());
   setHandler(stateChangeUpdate, async (lastKnownVersion) => {
@@ -751,6 +782,10 @@ function createAgentStateManager({
       customState[key] = value;
       version++;
     },
+    mergeUpdate(update) {
+      Object.assign(customState, update);
+      version++;
+    },
     getCurrentState() {
       return buildState();
     },
@@ -806,6 +841,95 @@ function createAgentStateManager({
   };
 }
 
+// src/lib/subagent/define.ts
+function defineSubagent(config) {
+  return config;
+}
+var SandboxNotSupportedError = class extends ApplicationFailure$1 {
+  constructor(operation) {
+    super(
+      `Sandbox does not support: ${operation}`,
+      "SandboxNotSupportedError",
+      true
+    );
+  }
+};
+var SandboxNotFoundError = class extends ApplicationFailure$1 {
+  constructor(sandboxId) {
+    super(`Sandbox not found: ${sandboxId}`, "SandboxNotFoundError", true);
+  }
+};
+
+// src/adapters/sandbox/virtual/mutations.ts
+function applyVirtualTreeMutations(stateManager, mutations) {
+  let tree = [...stateManager.get("fileTree")];
+  for (const m of mutations) {
+    switch (m.type) {
+      case "add":
+        tree.push(m.entry);
+        break;
+      case "remove":
+        tree = tree.filter((e) => e.path !== m.path);
+        break;
+      case "update":
+        tree = tree.map(
+          (e) => e.path === m.path ? { ...e, ...m.entry } : e
+        );
+        break;
+    }
+  }
+  stateManager.set("fileTree", tree);
+  return tree;
+}
+
+// src/adapters/sandbox/virtual/tree.ts
+var buildTree = (entries) => {
+  const root = { name: "/", children: /* @__PURE__ */ new Map(), isFile: false };
+  for (const entry of entries) {
+    const parts = entry.path.split("/").filter(Boolean);
+    let current = root;
+    for (const part of parts) {
+      let child = current.children.get(part);
+      if (!child) {
+        child = { name: part, children: /* @__PURE__ */ new Map(), isFile: false };
+        current.children.set(part, child);
+      }
+      current = child;
+    }
+    current.isFile = current.children.size === 0;
+  }
+  return root;
+};
+var printNode = (node, tab, sort) => {
+  const entries = [...node.children.values()];
+  if (sort) {
+    entries.sort((a, b) => {
+      if (!a.isFile && !b.isFile) return a.name.localeCompare(b.name);
+      if (!a.isFile) return -1;
+      if (!b.isFile) return 1;
+      return a.name.localeCompare(b.name);
+    });
+  }
+  let str = "";
+  for (const [i, entry] of entries.entries()) {
+    const isLast = i === entries.length - 1;
+    const branch = isLast ? "\u2514\u2500" : "\u251C\u2500";
+    const childTab = tab + (isLast ? "   " : "\u2502  ");
+    if (entry.isFile) {
+      str += "\n" + tab + branch + " " + entry.name;
+    } else {
+      const subtree = printNode(entry, childTab, sort);
+      str += "\n" + tab + branch + " " + entry.name + "/" + subtree;
+    }
+  }
+  return str;
+};
+function formatVirtualFileTree(entries, opts = {}) {
+  const sort = opts.sort ?? true;
+  const root = buildTree(entries);
+  return "/" + printNode(root, "", sort);
+}
+
 // src/lib/skills/parse.ts
 function parseSkillFile(raw) {
   const trimmed = raw.replace(/^\uFEFF/, "");
@@ -1228,6 +1352,6 @@ var createAskUserQuestionHandler = () => async (args) => {
   };
 };
 
-export { agentQueryName, agentStateChangeUpdateName, askUserQuestionTool, bashTool, createAgentStateManager, createAskUserQuestionHandler, createBashToolDescription, createReadSkillHandler, createReadSkillTool, createSession, createSubagentTool, createTaskCreateHandler, createTaskGetHandler, createTaskListHandler, createTaskUpdateHandler, createToolRouter, defineSubagent, defineTool, editTool, getShortId, globTool, grepTool, hasNoOtherToolCalls, isTerminalStatus, parseSkillFile, proxyDefaultThreadOps, readFileTool, taskCreateTool, taskGetTool, taskListTool, taskUpdateTool, writeFileTool };
+export { SandboxNotFoundError, SandboxNotSupportedError, applyVirtualTreeMutations, askUserQuestionTool, bashTool, createAgentStateManager, createAskUserQuestionHandler, createBashToolDescription, createReadSkillHandler, createReadSkillTool, createSession, createTaskCreateHandler, createTaskGetHandler, createTaskListHandler, createTaskUpdateHandler, createToolRouter, defineSubagent, defineTool, editTool, formatVirtualFileTree, getShortId, globTool, grepTool, hasNoOtherToolCalls, isTerminalStatus, parseSkillFile, proxyDefaultThreadOps, proxySandboxOps, readFileTool, taskCreateTool, taskGetTool, taskListTool, taskUpdateTool, writeFileTool };
 //# sourceMappingURL=workflow.js.map
 //# sourceMappingURL=workflow.js.map