zeitlich 0.2.38 → 0.2.40

package/src/lib/subagent/handler.ts

@@ -12,6 +12,7 @@ import type { JsonValue } from "../state/types";
 import type {
   InferSubagentResult,
   SubagentConfig,
+  SubagentFnResult,
   SubagentSandboxConfig,
   SubagentWorkflowInput,
 } from "./types";
@@ -25,6 +26,22 @@ import type {
 import type { SandboxOps, SandboxSnapshot } from "../sandbox/types";
 import { childSandboxReadySignal } from "./signals";
 
+/**
+ * Default `workflowRunTimeout` applied to every subagent child workflow
+ * unless overridden via `SubagentConfig.workflowOptions.workflowRunTimeout`.
+ *
+ * Chosen as a safety bound: Temporal retries failing workflow tasks forever
+ * by default, so a child that fails to initialize (e.g. missing workflow
+ * export) or is otherwise broken will never reach a terminal state on its
+ * own and the parent's `Subagent` tool call would hang indefinitely. A
+ * bounded run timeout guarantees the child is eventually terminated and the
+ * parent receives a structured `ChildWorkflowFailure` it can surface to the
+ * agent. One hour is generous enough for realistic agent sessions while
+ * still catching hangs; agents that legitimately need longer should set an
+ * explicit `workflowOptions.workflowRunTimeout`.
+ */
+export const DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT = "1h";
+
 /** Normalized sandbox config after resolving the union. */
 interface ResolvedSandboxConfig {
   source: "none" | "inherit" | "own";
@@ -103,8 +120,18 @@ export function createSubagentHandler<
   const persistentSandboxes = new Map<string, string>();
   /** Tracks agents whose first lazy sandbox creation is in-flight (guards concurrent init) */
   const persistentSandboxCreating = new Set<string>();
+  /**
+   * Latest failure from a lazy-creator call, keyed by agentName. Populated
+   * when a creator's `executeChild` throws, consumed by concurrent waiters so
+   * they fail deterministically instead of hanging on a condition predicate
+   * that will never be satisfied. Cleared once observed by all current
+   * waiters (on the next successful creator attempt).
+   */
+  const persistentSandboxCreationError = new Map<string, unknown>();
   /** Reverse lookup: childWorkflowId → agentName for in-flight lazy creators */
   const lazyCreatorAgent = new Map<string, string>();
+  /** Reverse lookup: childWorkflowId → agentName for in-flight snapshot-base creators */
+  const snapshotBaseCreatorAgent = new Map<string, string>();
   /** Maps childThreadId → latest snapshot for sandbox continuation via snapshots */
   const threadSnapshots = new Map<
     string,
@@ -117,14 +144,24 @@ export function createSubagentHandler<
   const persistentBaseSnapshot = new Map<string, SandboxSnapshot>();
   /** Tracks agents whose first snapshot-backed sandbox creation is in-flight */
   const persistentBaseSnapshotCreating = new Set<string>();
-
-  setHandler(childSandboxReadySignal, ({ childWorkflowId, sandboxId }) => {
-    const agentName = lazyCreatorAgent.get(childWorkflowId);
-    if (agentName && !persistentSandboxes.has(agentName)) {
-      persistentSandboxes.set(agentName, sandboxId);
-      lazyCreatorAgent.delete(childWorkflowId);
+  /** Latest failure from a snapshot-base creator call, keyed by agentName. */
+  const persistentBaseSnapshotCreationError = new Map<string, unknown>();
+
+  setHandler(
+    childSandboxReadySignal,
+    ({ childWorkflowId, sandboxId, baseSnapshot }) => {
+      const lazyAgent = lazyCreatorAgent.get(childWorkflowId);
+      if (lazyAgent && !persistentSandboxes.has(lazyAgent)) {
+        persistentSandboxes.set(lazyAgent, sandboxId);
+        lazyCreatorAgent.delete(childWorkflowId);
+      }
+      const snapAgent = snapshotBaseCreatorAgent.get(childWorkflowId);
+      if (snapAgent && baseSnapshot && !persistentBaseSnapshot.has(snapAgent)) {
+        persistentBaseSnapshot.set(snapAgent, baseSnapshot);
+        snapshotBaseCreatorAgent.delete(childWorkflowId);
+      }
     }
-  });
+  );
 
   const handler = async (
     args: SubagentArgs,
@@ -208,8 +245,23 @@ export function createSubagentHandler<
         baseSnap = persistentBaseSnapshot.get(config.agentName);
         if (!baseSnap) {
           if (persistentBaseSnapshotCreating.has(config.agentName)) {
-            await condition(() => persistentBaseSnapshot.has(config.agentName));
+            await condition(
+              () =>
+                persistentBaseSnapshot.has(config.agentName) ||
+                persistentBaseSnapshotCreationError.has(config.agentName) ||
+                !persistentBaseSnapshotCreating.has(config.agentName)
+            );
+            const creatorErr = persistentBaseSnapshotCreationError.get(
+              config.agentName
+            );
+            if (creatorErr !== undefined) {
+              throw creatorErr;
+            }
             baseSnap = persistentBaseSnapshot.get(config.agentName);
+            if (!baseSnap) {
+              persistentBaseSnapshotCreating.add(config.agentName);
+              isSnapshotBaseCreator = true;
+            }
           } else {
             persistentBaseSnapshotCreating.add(config.agentName);
             isSnapshotBaseCreator = true;
@@ -229,9 +281,27 @@ export function createSubagentHandler<
         baseSandboxId = persistentSandboxes.get(config.agentName);
         if (!baseSandboxId) {
           if (persistentSandboxCreating.has(config.agentName)) {
-            // Another call is already creating — wait for it to finish
-            await condition(() => persistentSandboxes.has(config.agentName));
+            // Another call is already creating — wait for it to finish.
+            // Also break out if the creator failed, so we can either fail
+            // fast with the same error or (if no one has re-claimed the
+            // creator role yet) take over ourselves.
+            await condition(
+              () =>
+                persistentSandboxes.has(config.agentName) ||
+                persistentSandboxCreationError.has(config.agentName) ||
+                !persistentSandboxCreating.has(config.agentName)
+            );
+            const creatorErr = persistentSandboxCreationError.get(
+              config.agentName
+            );
+            if (creatorErr !== undefined) {
+              throw creatorErr;
+            }
             baseSandboxId = persistentSandboxes.get(config.agentName);
+            if (!baseSandboxId) {
+              persistentSandboxCreating.add(config.agentName);
+              isLazyCreator = true;
+            }
           } else {
             // We're the first concurrent caller — claim the creator role
             persistentSandboxCreating.add(config.agentName);
@@ -290,6 +360,12 @@ export function createSubagentHandler<
           : config.context;
 
     const childOpts = {
+      // Apply a bounded run timeout by default so a child workflow that
+      // fails to initialize or otherwise never reaches a terminal state
+      // cannot hang the parent's `Subagent` tool call forever. Callers can
+      // raise, lower, or disable it via `workflowOptions.workflowRunTimeout`.
+      workflowRunTimeout: DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT,
+      ...(config.workflowOptions ?? {}),
       workflowId: childWorkflowId,
       args:
         resolvedContext === undefined
@@ -301,6 +377,9 @@ export function createSubagentHandler<
     if (isLazyCreator) {
       lazyCreatorAgent.set(childWorkflowId, config.agentName);
     }
+    if (isSnapshotBaseCreator) {
+      snapshotBaseCreatorAgent.set(childWorkflowId, config.agentName);
+    }
 
     log.info("subagent spawned", {
       subagent: config.agentName,
@@ -309,7 +388,38 @@ export function createSubagentHandler<
       sandboxSource: sandboxCfg.source,
     });
 
-    const childResult = await executeChild(config.workflow, childOpts);
+    // Always clear in-flight creator bookkeeping, even if `executeChild`
+    // throws. Otherwise a failing subagent would strand other concurrent
+    // callers waiting on `condition(() => persistentSandboxes.has(...))` /
+    // `persistentBaseSnapshot.has(...)` forever, because those conditions are
+    // only ever satisfied on the success path below. When we were the
+    // creator, also publish the error so any already-waiting concurrent
+    // callers fail with the same error instead of silently retrying or
+    // hanging.
+    let childResult: SubagentFnResult<InferSubagentResult<T[number]> | null>;
+    try {
+      childResult = (await executeChild(
+        config.workflow,
+        childOpts
+      )) as SubagentFnResult<InferSubagentResult<T[number]> | null>;
+    } catch (err) {
+      log.warn("subagent failed", {
+        subagent: config.agentName,
+        childWorkflowId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      if (isLazyCreator) {
+        persistentSandboxCreating.delete(config.agentName);
+        persistentSandboxCreationError.set(config.agentName, err);
+        lazyCreatorAgent.delete(childWorkflowId);
+      }
+      if (isSnapshotBaseCreator) {
+        persistentBaseSnapshotCreating.delete(config.agentName);
+        persistentBaseSnapshotCreationError.set(config.agentName, err);
+        snapshotBaseCreatorAgent.delete(childWorkflowId);
+      }
+      throw err;
+    }
 
     const effectiveShutdown =
       sandboxShutdownOverride ?? sandboxCfg.shutdown ?? "destroy";
@@ -386,10 +496,13 @@ export function createSubagentHandler<
 
     if (isLazyCreator) {
       persistentSandboxCreating.delete(config.agentName);
+      persistentSandboxCreationError.delete(config.agentName);
       lazyCreatorAgent.delete(childWorkflowId);
     }
     if (isSnapshotBaseCreator) {
       persistentBaseSnapshotCreating.delete(config.agentName);
+      persistentBaseSnapshotCreationError.delete(config.agentName);
+      snapshotBaseCreatorAgent.delete(childWorkflowId);
     }
 
     if (!toolResponse) {

package/src/lib/subagent/index.ts

@@ -1,4 +1,5 @@
 export type {
+  SubagentChildWorkflowOptions,
   SubagentConfig,
   SubagentContext,
   SubagentDefinition,
@@ -13,7 +14,10 @@ export type {
 } from "./types";
 export { createSubagentTool, SUBAGENT_TOOL_NAME } from "./tool";
 export type { SubagentArgs } from "./tool";
-export { createSubagentHandler } from "./handler";
+export {
+  createSubagentHandler,
+  DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT,
+} from "./handler";
 export { defineSubagent } from "./define";
 export { defineSubagentWorkflow } from "./workflow";
 export { buildSubagentRegistration } from "./register";