zeitlich 0.2.22 → 0.2.24

package/src/lib/subagent/tool.ts

@@ -6,7 +6,7 @@ export const SUBAGENT_TOOL_NAME = "Subagent" as const;
 function buildSubagentDescription(subagents: SubagentConfig[]): string {
   const subagentList = subagents
     .map((s) => {
-      const continuation = s.allowThreadContinuation
+      const continuation = s.thread && s.thread !== "new"
         ? "\n*(Supports thread continuation — pass a threadId to resume a previous conversation)*"
         : "";
       return `## ${s.agentName}\n${s.description}${continuation}`;
@@ -39,7 +39,7 @@ export function createSubagentTool<T extends SubagentConfig[]>(
 
   const names = subagents.map((s) => s.agentName);
   const hasThreadContinuation = subagents.some(
-    (s) => s.allowThreadContinuation
+    (s) => s.thread && s.thread !== "new"
   );
 
   const baseFields = {

package/src/lib/subagent/types.ts

@@ -4,26 +4,33 @@ import type {
   PreToolUseHookResult,
   PostToolUseFailureHookResult,
 } from "../tool-router/types";
+import type {
+  ThreadInit,
+  SandboxInit,
+  SubagentSandboxShutdown,
+} from "../lifecycle";
 
 /** ToolHandlerResponse with threadId required (subagents must always surface their thread) */
 export type SubagentHandlerResponse<TResult = null> =
-  ToolHandlerResponse<TResult> & { threadId: string };
+  ToolHandlerResponse<TResult> & { threadId: string; sandboxId?: string };
 
 /**
  * Raw workflow input fields passed from parent to child workflow.
  * `defineSubagentWorkflow` maps this into `SubagentSessionInput`.
  */
 export interface SubagentWorkflowInput {
-  /** Thread ID from parent for continuation */
-  previousThreadId?: string;
-  /** Sandbox ID inherited from parent */
-  sandboxId?: string;
+  /** Thread initialization strategy forwarded from the parent */
+  thread?: ThreadInit;
+  /** Sandbox initialization strategy forwarded from the parent */
+  sandbox?: SandboxInit;
+  /** Sandbox shutdown override from the parent (takes precedence over workflow default) */
+  sandboxShutdown?: SubagentSandboxShutdown;
 }
 
 export type SubagentWorkflow<TResult extends z.ZodType = z.ZodType> = (
   prompt: string,
   workflowInput: SubagentWorkflowInput,
-  context?: Record<string, unknown>,
+  context?: Record<string, unknown>
 ) => Promise<SubagentHandlerResponse<z.infer<TResult> | null>>;
 
 /**
@@ -36,7 +43,7 @@ export type SubagentDefinition<
 > = ((
   prompt: string,
   workflowInput: SubagentWorkflowInput,
-  context?: TContext,
+  context?: TContext
 ) => Promise<SubagentHandlerResponse<z.infer<TResult> | null>>) & {
   readonly agentName: string;
   readonly description: string;
@@ -52,6 +59,23 @@ export type SubagentContext =
 export type InferSubagentResult<T extends SubagentConfig> =
   T extends SubagentConfig<infer S> ? z.infer<S> : null;
 
+/**
+ * Sandbox configuration for a subagent.
+ *
+ * String shorthands:
+ * - `"none"` — no sandbox (default).
+ * - `"inherit"` — reuse the parent's sandbox (shared filesystem/exec).
+ * - `"own"` — the child creates and owns its own sandbox (shutdown defaults to `"destroy"`).
+ *
+ * Object form (only for `source: "own"`):
+ * - `{ source: "own", shutdown?: SubagentSandboxShutdown }` — own sandbox with explicit shutdown policy.
+ */
+export type SubagentSandboxConfig =
+  | "none"
+  | "inherit"
+  | "own"
+  | { source: "own"; shutdown?: SubagentSandboxShutdown };
+
 /**
  * Configuration for a subagent that can be spawned by the parent workflow.
  *
@@ -65,23 +89,34 @@ export interface SubagentConfig<TResult extends z.ZodType = z.ZodType> {
   /** Whether this subagent is available (default: true). Disabled subagents are excluded from the Subagent tool. */
   enabled?: boolean | (() => boolean);
   /** Temporal workflow function or type name (used with executeChild) */
-  workflow: string | SubagentWorkflow<TResult>;
+  workflow: SubagentWorkflow<TResult>;
   /** Optional task queue - defaults to parent's queue if not specified */
   taskQueue?: string;
   /** Optional Zod schema to validate the child workflow's result. If omitted, result is passed through as-is. */
   resultSchema?: TResult;
   /** Optional context passed to the subagent — a static object or a function evaluated at invocation time */
   context?: SubagentContext;
-  /** Allow the parent agent to pass a threadId for this subagent to continue (default: false) */
-  allowThreadContinuation?: boolean;
   /** Per-subagent lifecycle hooks */
   hooks?: SubagentHooks;
+  /**
+   * Thread mode for this subagent.
+   *
+   * - `"new"` (default) — always start a fresh thread.
+   * - `"fork"` — the parent can pass a `threadId`; messages are copied into
+   *   a new thread and the subagent continues there.
+   * - `"continue"` — the parent can pass a `threadId`; the subagent appends
+   *   directly to the existing thread in-place.
+   */
+  thread?: "new" | "fork" | "continue";
   /**
    * Sandbox strategy for this subagent.
-   * - `'inherit'` (default): reuse the parent's sandbox (shared filesystem/exec).
-   * - `'own'`: the child creates and owns its own sandbox.
+   *
+   * String shorthands: `"none"` (default) | `"inherit"` | `"own"`.
+   * Object form: `{ source: "own", shutdown?: SubagentSandboxShutdown }`.
+   *
+   * @see {@link SubagentSandboxConfig}
    */
-  sandbox?: "inherit" | "own";
+  sandbox?: SubagentSandboxConfig;
 }
 
 /**
@@ -102,6 +137,8 @@ export interface SubagentHooks<TArgs = unknown, TResult = unknown> {
     threadId: string;
     turn: number;
     durationMs: number;
+    /** Unvalidated metadata from the child workflow (e.g. infrastructure state) */
+    metadata?: Record<string, unknown>;
   }) => void | Promise<void>;
   /** Called when this subagent execution fails */
   onExecutionFailure?: (ctx: {
@@ -112,16 +149,37 @@ export interface SubagentHooks<TArgs = unknown, TResult = unknown> {
   }) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
 }
 
+/**
+ * Extended response from the subagent `fn` — includes optional cleanup callbacks
+ * stripped before signaling the parent.
+ *
+ * When `TSandboxShutdown` is `"pause-until-parent-close"`, both `destroySandbox`
+ * and `sandboxId` become required so the parent can coordinate cleanup.
+ */
+export type SubagentFnResult<
+  TResult = null,
+  TSandboxShutdown extends SubagentSandboxShutdown = SubagentSandboxShutdown,
+> = SubagentHandlerResponse<TResult> &
+  (TSandboxShutdown extends "pause-until-parent-close"
+    ? { destroySandbox: () => Promise<void>; sandboxId: string }
+    : { destroySandbox?: () => Promise<void> });
+
+/** Payload sent by a child workflow to signal its result back to the parent */
+export interface ChildResultSignalPayload {
+  childWorkflowId: string;
+  result: SubagentHandlerResponse;
+}
+
 /**
  * Session config fields passed from parent to child workflow.
  */
 export interface SubagentSessionInput {
   /** Agent name — spread directly into `createSession` */
   agentName: string;
-  /** Thread ID to continue from */
-  threadId?: string;
-  /** Whether to continue an existing thread */
-  continueThread?: boolean;
-  /** Sandbox ID inherited from the parent agent */
-  sandboxId?: string;
+  /** Thread initialization strategy */
+  thread?: ThreadInit;
+  /** Sandbox initialization strategy */
+  sandbox?: SandboxInit;
+  /** Sandbox shutdown policy (default: "destroy") */
+  sandboxShutdown?: SubagentSandboxShutdown;
 }

package/src/lib/subagent/workflow.ts

@@ -1,10 +1,20 @@
 import type { z } from "zod";
+import {
+  workflowInfo,
+  getExternalWorkflowHandle,
+  setHandler,
+  condition,
+  ApplicationFailure,
+} from "@temporalio/workflow";
 import type {
   SubagentDefinition,
+  SubagentFnResult,
   SubagentHandlerResponse,
   SubagentWorkflowInput,
   SubagentSessionInput,
 } from "./types";
+import type { SubagentSandboxShutdown } from "../lifecycle";
+import { childResultSignal, destroySandboxSignal } from "./signals";
 
 /**
  * Defines a subagent workflow with embedded metadata (name, description, resultSchema).
@@ -54,34 +64,50 @@ import type {
  */
 // Without resultSchema — data is null
 export function defineSubagentWorkflow<
+  TSandboxShutdown extends SubagentSandboxShutdown = "destroy",
   TContext extends Record<string, unknown> = Record<string, unknown>,
 >(
-  config: { name: string; description: string },
+  config: {
+    name: string;
+    description: string;
+    sandboxShutdown?: TSandboxShutdown;
+  },
   fn: (
     prompt: string,
     sessionInput: SubagentSessionInput,
     context: TContext
-  ) => Promise<SubagentHandlerResponse<null>>
+  ) => Promise<SubagentFnResult<null, TSandboxShutdown>>
 ): SubagentDefinition<z.ZodNull, TContext>;
 // With resultSchema — data is inferred from the schema
 export function defineSubagentWorkflow<
   TResult extends z.ZodType,
+  TSandboxShutdown extends SubagentSandboxShutdown = "destroy",
   TContext extends Record<string, unknown> = Record<string, unknown>,
 >(
-  config: { name: string; description: string; resultSchema: TResult },
+  config: {
+    name: string;
+    description: string;
+    resultSchema: TResult;
+    sandboxShutdown?: TSandboxShutdown;
+  },
   fn: (
     prompt: string,
     sessionInput: SubagentSessionInput,
     context: TContext
-  ) => Promise<SubagentHandlerResponse<z.infer<TResult> | null>>
+  ) => Promise<SubagentFnResult<z.infer<TResult> | null, TSandboxShutdown>>
 ): SubagentDefinition<TResult, TContext>;
 export function defineSubagentWorkflow(
-  config: { name: string; description: string; resultSchema?: z.ZodType },
+  config: {
+    name: string;
+    description: string;
+    resultSchema?: z.ZodType;
+    sandboxShutdown?: SubagentSandboxShutdown;
+  },
   fn: (
     prompt: string,
     sessionInput: SubagentSessionInput,
     context: Record<string, unknown>
-  ) => Promise<SubagentHandlerResponse<unknown>>
+  ) => Promise<SubagentFnResult<unknown>>
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
 ): SubagentDefinition<any, any> {
   const workflow = async (
@@ -89,15 +115,60 @@ export function defineSubagentWorkflow(
     workflowInput: SubagentWorkflowInput,
     context?: Record<string, unknown>
   ): Promise<SubagentHandlerResponse<unknown>> => {
+    const effectiveShutdown =
+      workflowInput.sandboxShutdown ?? config.sandboxShutdown ?? "destroy";
+
     const sessionInput: SubagentSessionInput = {
       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;
   };
 
   // for temporal workflow name

package/src/lib/tool-router/router.integration.test.ts

@@ -579,7 +579,7 @@ describe("createToolRouter integration", () => {
     });
   });
 
-  it("throws when handler fails and no hook recovers", async () => {
+  it("suppresses error when handler fails and no hook recovers", async () => {
     const router = createToolRouter({
       tools: { Fail: failingTool } as const,
       threadId: "t-1",
@@ -592,9 +592,12 @@ describe("createToolRouter integration", () => {
       args: { reason: "unrecoverable" },
     });
 
-    await expect(
-      router.processToolCalls([parsed], { turn: 1 })
-    ).rejects.toThrow("unrecoverable");
+    const results = await router.processToolCalls([parsed], { turn: 1 });
+    expect(results).toHaveLength(1);
+    expect(at(results, 0).data).toEqual({
+      error: "Error: unrecoverable",
+      suppressed: true,
+    });
   });
 
   // --- Disabled tools ---
@@ -707,6 +710,136 @@ describe("createToolRouter integration", () => {
     expect(router.getResultsByName(results, "Add")).toHaveLength(1);
   });
 
+  // --- Metadata passthrough ---
+
+  it("handler metadata flows to ToolCallResult", async () => {
+    const metaTool = defineTool({
+      name: "Meta" as const,
+      description: "returns metadata",
+      schema: z.object({}),
+      handler: async () => ({
+        toolResponse: "ok",
+        data: null,
+        metadata: { jobId: "j-99", env: "prod" },
+      }),
+    });
+
+    const router = createToolRouter({
+      tools: { Meta: metaTool } as const,
+      threadId: "t-1",
+      appendToolResult: appendSpy.fn,
+    });
+
+    const parsed = router.parseToolCall({ id: "tc-1", name: "Meta", args: {} });
+    const results = await router.processToolCalls([parsed], { turn: 1 });
+
+    expect(at(results, 0).metadata).toEqual({ jobId: "j-99", env: "prod" });
+  });
+
+  it("handler metadata flows to per-tool post-hook", async () => {
+    let hookMetadata: Record<string, unknown> | undefined;
+
+    const metaTool = defineTool({
+      name: "Meta" as const,
+      description: "returns metadata",
+      schema: z.object({}),
+      handler: async () => ({
+        toolResponse: "ok",
+        data: null,
+        metadata: { region: "us-east-1" },
+      }),
+      hooks: {
+        onPostToolUse: async ({ metadata }) => {
+          hookMetadata = metadata;
+        },
+      },
+    });
+
+    const router = createToolRouter({
+      tools: { Meta: metaTool } as const,
+      threadId: "t-1",
+      appendToolResult: appendSpy.fn,
+    });
+
+    const parsed = router.parseToolCall({ id: "tc-1", name: "Meta", args: {} });
+    await router.processToolCalls([parsed], { turn: 1 });
+
+    expect(hookMetadata).toEqual({ region: "us-east-1" });
+  });
+
+  it("handler metadata flows to global post-hook via result", async () => {
+    let resultMetadata: Record<string, unknown> | undefined;
+
+    const metaTool = defineTool({
+      name: "Meta" as const,
+      description: "returns metadata",
+      schema: z.object({}),
+      handler: async () => ({
+        toolResponse: "ok",
+        data: null,
+        metadata: { traceId: "abc" },
+      }),
+    });
+
+    const router = createToolRouter({
+      tools: { Meta: metaTool } as const,
+      threadId: "t-1",
+      appendToolResult: appendSpy.fn,
+      hooks: {
+        onPostToolUse: async ({ result }) => {
+          resultMetadata = result.metadata;
+        },
+      },
+    });
+
+    const parsed = router.parseToolCall({ id: "tc-1", name: "Meta", args: {} });
+    await router.processToolCalls([parsed], { turn: 1 });
+
+    expect(resultMetadata).toEqual({ traceId: "abc" });
+  });
+
+  it("metadata is undefined when handler does not set it", async () => {
+    const router = createToolRouter({
+      tools: createTools(),
+      threadId: "t-1",
+      appendToolResult: appendSpy.fn,
+    });
+
+    const parsed = router.parseToolCall({
+      id: "tc-1",
+      name: "Echo",
+      args: { text: "hi" },
+    });
+    const results = await router.processToolCalls([parsed], { turn: 1 });
+
+    expect(at(results, 0).metadata).toBeUndefined();
+  });
+
+  it("processToolCallsByName passes metadata through", async () => {
+    const router = createToolRouter({
+      tools: createTools(),
+      threadId: "t-1",
+      appendToolResult: appendSpy.fn,
+    });
+
+    const calls = [
+      router.parseToolCall({ id: "tc-1", name: "Echo", args: { text: "a" } }),
+    ];
+
+    const results = await router.processToolCallsByName(
+      calls,
+      "Echo",
+      async (args: { text: string }) => ({
+        toolResponse: `custom: ${args.text}`,
+        data: { custom: args.text },
+        metadata: { source: "custom-handler" },
+      })
+    );
+
+    expect(results).toHaveLength(1);
+    expect(at(results, 0).metadata).toEqual({ source: "custom-handler" });
+  });
+
   // --- resultAppended flag ---
 
   it("skips appendToolResult when handler sets resultAppended", async () => {

package/src/lib/tool-router/router.ts

@@ -20,7 +20,7 @@ import type {
 } from "./types";
 
 import type { z } from "zod";
-import { ApplicationFailure, uuid4 } from "@temporalio/workflow";
+import { uuid4 } from "@temporalio/workflow";
 
 /**
  * Creates a tool router for declarative tool call processing.
@@ -110,7 +110,7 @@ export function createToolRouter<T extends ToolMap>(
 
   /**
    * Run per-tool → global failure hooks. Returns recovery content/result,
-   * or throws if no hook recovers.
+   * or a generic error response if no hook recovers.
    */
   async function runFailureHooks(
     toolCall: ParsedToolCallUnion<T>,
@@ -160,7 +160,12 @@ export function createToolRouter<T extends ToolMap>(
         };
     }
 
-    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 },
+    };
   }
 
   /** Run per-tool → global post-hooks. */
@@ -179,6 +184,7 @@ export function createToolRouter<T extends ToolMap>(
         threadId: options.threadId,
         turn,
         durationMs,
+        ...(toolResult.metadata && { metadata: toolResult.metadata }),
       });
     }
     if (options.hooks?.onPostToolUse) {
@@ -195,7 +201,8 @@ export function createToolRouter<T extends ToolMap>(
   async function processToolCall(
     toolCall: ParsedToolCallUnion<T>,
     turn: number,
-    sandboxId?: string
+    sandboxId?: string,
+    sandboxStateUpdate?: Record<string, unknown>
   ): Promise<ToolCallResultUnion<TResults> | null> {
     const startTime = Date.now();
     const tool = toolMap.get(toolCall.name);
@@ -220,6 +227,7 @@ export function createToolRouter<T extends ToolMap>(
     let result: unknown;
     let content!: ToolMessageContent;
     let resultAppended = false;
+    let metadata: Record<string, unknown> | undefined;
 
     try {
       if (tool) {
@@ -228,6 +236,7 @@ export function createToolRouter<T extends ToolMap>(
           toolCallId: toolCall.id,
           toolName: toolCall.name,
           ...(sandboxId !== undefined && { sandboxId }),
+          ...(sandboxStateUpdate && { sandboxStateUpdate }),
         };
         const response = await tool.handler(
           effectiveArgs as Parameters<typeof tool.handler>[0],
@@ -236,6 +245,7 @@ export function createToolRouter<T extends ToolMap>(
         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);
@@ -272,6 +282,7 @@ export function createToolRouter<T extends ToolMap>(
       toolCallId: toolCall.id,
       name: toolCall.name,
       data: result,
+      ...(metadata && { metadata }),
     } as ToolCallResultUnion<TResults>;
 
     // --- Post-hooks ---
@@ -341,10 +352,11 @@ export function createToolRouter<T extends ToolMap>(
 
       const turn = context?.turn ?? 0;
       const sandboxId = context?.sandboxId;
+      const sandboxStateUpdate = context?.sandboxStateUpdate;
 
       if (options.parallel) {
         const results = await Promise.all(
-          toolCalls.map((tc) => processToolCall(tc, turn, sandboxId))
+          toolCalls.map((tc) => processToolCall(tc, turn, sandboxId, sandboxStateUpdate))
         );
         return results.filter(
           (r): r is NonNullable<typeof r> => r !== null
@@ -353,7 +365,7 @@ export function createToolRouter<T extends ToolMap>(
 
       const results: ToolCallResultUnion<TResults>[] = [];
       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);
         }
@@ -410,6 +422,7 @@ export function createToolRouter<T extends ToolMap>(
           toolCallId: toolCall.id,
           name: toolCall.name as TName,
           data: response.data,
+          ...(response.metadata && { metadata: response.metadata }),
         };
       };
 

package/src/lib/tool-router/types.ts

@@ -142,6 +142,10 @@ export interface ToolHandlerResponse<TResult = null> {
   usage?: TokenUsage;
   /** Thread ID used by the handler (surfaced to the LLM for subagent thread continuation) */
   threadId?: string;
+  /** Sandbox ID created or used by the handler (e.g. child agent sandbox) */
+  sandboxId?: string;
+  /** Unvalidated metadata passthrough from handler to hooks (e.g. infrastructure state) */
+  metadata?: Record<string, unknown>;
 }
 
 /**
@@ -153,6 +157,8 @@ export interface RouterContext {
   toolCallId: string;
   toolName: string;
   sandboxId?: string;
+  /** Sandbox state update from the provider (passed through for subagent inheritance) */
+  sandboxStateUpdate?: Record<string, unknown>;
 }
 
 /**
@@ -225,6 +231,8 @@ export interface ToolCallResult<
   name: TName;
   data: TResult;
   usage?: TokenUsage;
+  /** Unvalidated metadata passthrough from handler to hooks (e.g. infrastructure state) */
+  metadata?: Record<string, unknown>;
 }
 
 /**
@@ -257,6 +265,8 @@ export interface ProcessToolCallsContext {
   turn?: number;
   /** Active sandbox ID (when a sandbox is configured for this session) */
   sandboxId?: string;
+  /** Sandbox state update from the provider (threaded to subagent handler for inheritance) */
+  sandboxStateUpdate?: Record<string, unknown>;
 }
 
 // ============================================================================
@@ -301,6 +311,7 @@ export interface ToolHooks<TArgs = unknown, TResult = unknown> {
     threadId: string;
     turn: number;
     durationMs: number;
+    metadata?: Record<string, unknown>;
   }) => void | Promise<void>;
   /** Called when this tool execution fails */
   onPostToolUseFailure?: (ctx: {