zeitlich 0.2.33 → 0.2.35

package/src/lib/subagent/types.ts

@@ -63,19 +63,28 @@ export type InferSubagentResult<T extends SubagentConfig> =
 /**
  * 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.
+ * - `{ source: "inherit", continuation }` — reuse the parent's sandbox.
+ *   `continuation: "continue"` shares the parent sandbox directly;
+ *   `continuation: "fork"` forks from the parent on every call.
+ * - `{ source: "own", init?, continuation }` — the child gets its own sandbox.
+ *   `init: "per-call"` (default) creates fresh each call (thread continuation
+ *   uses the previous sandbox). `init: "once"` creates on the first call and
+ *   stores it for all subsequent calls.
  */
 export type SubagentSandboxConfig =
   | "none"
-  | "inherit"
-  | "own"
-  | { source: "own"; shutdown?: SubagentSandboxShutdown };
+  | {
+      source: "inherit";
+      continuation: "continue" | "fork";
+      shutdown?: SubagentSandboxShutdown;
+    }
+  | {
+      source: "own";
+      init?: "per-call" | "once";
+      continuation: "continue" | "fork";
+      shutdown?: SubagentSandboxShutdown;
+    };
 
 /**
  * Configuration for a subagent that can be spawned by the parent workflow.
@@ -112,9 +121,6 @@ export interface SubagentConfig<TResult extends z.ZodType = z.ZodType> {
   /**
    * Sandbox strategy for this subagent.
    *
-   * String shorthands: `"none"` (default) | `"inherit"` | `"own"`.
-   * Object form: `{ source: "own", shutdown?: SubagentSandboxShutdown }`.
-   *
    * @see {@link SubagentSandboxConfig}
    */
   sandbox?: SubagentSandboxConfig;
@@ -154,14 +160,17 @@ export interface SubagentHooks<TArgs = unknown, TResult = unknown> {
  * 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.
+ * When `TSandboxShutdown` is `"pause-until-parent-close"` or
+ * `"keep-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"
+  (TSandboxShutdown extends
+    | "pause-until-parent-close"
+    | "keep-until-parent-close"
     ? { destroySandbox: () => Promise<void>; sandboxId: string }
     : { destroySandbox?: () => Promise<void> });
 
@@ -171,6 +180,12 @@ export interface ChildResultSignalPayload {
   result: SubagentHandlerResponse;
 }
 
+/** Payload sent by a child workflow as soon as its sandbox is ready */
+export interface ChildSandboxReadySignalPayload {
+  childWorkflowId: string;
+  sandboxId: string;
+}
+
 /**
  * Session config fields passed from parent to child workflow.
  */
@@ -183,4 +198,6 @@ export interface SubagentSessionInput {
   sandbox?: SandboxInit;
   /** Sandbox shutdown policy (default: "destroy") */
   sandboxShutdown?: SubagentSandboxShutdown;
+  /** Called by the session as soon as the sandbox is created, before the agent loop starts. */
+  onSandboxReady?: (sandboxId: string) => void;
 }

package/src/lib/subagent/workflow.ts

@@ -14,7 +14,11 @@ import type {
   SubagentSessionInput,
 } from "./types";
 import type { SubagentSandboxShutdown } from "../lifecycle";
-import { childResultSignal, destroySandboxSignal } from "./signals";
+import {
+  childResultSignal,
+  childSandboxReadySignal,
+  destroySandboxSignal,
+} from "./signals";
 
 /**
  * Defines a subagent workflow with embedded metadata (name, description, resultSchema).
@@ -118,11 +122,26 @@ export function defineSubagentWorkflow(
     const effectiveShutdown =
       workflowInput.sandboxShutdown ?? config.sandboxShutdown ?? "destroy";
 
+    const { parent } = workflowInfo();
+    if (!parent) {
+      throw ApplicationFailure.create({
+        message: "Subagent workflow called without a parent workflow",
+        nonRetryable: true,
+      });
+    }
+    const parentHandle = getExternalWorkflowHandle(parent.workflowId);
+
     const sessionInput: SubagentSessionInput = {
       agentName: config.name,
       sandboxShutdown: effectiveShutdown,
       ...(workflowInput.thread && { thread: workflowInput.thread }),
       ...(workflowInput.sandbox && { sandbox: workflowInput.sandbox }),
+      onSandboxReady: (sandboxId: string) => {
+        void parentHandle.signal(childSandboxReadySignal, {
+          childWorkflowId: workflowInfo().workflowId,
+          sandboxId,
+        });
+      },
     };
     const { destroySandbox, ...result } = await fn(
       prompt,
@@ -130,30 +149,24 @@ export function defineSubagentWorkflow(
       context ?? {}
     );
 
-    if (effectiveShutdown === "pause-until-parent-close") {
+    if (
+      effectiveShutdown === "pause-until-parent-close" ||
+      effectiveShutdown === "keep-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`,
+          message: `Subagent "${config.name}" has sandboxShutdown="${effectiveShutdown}" 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`,
+          message: `Subagent "${config.name}" has sandboxShutdown="${effectiveShutdown}" 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,

package/src/lib/thread/types.ts

@@ -1,6 +1,5 @@
 import type Redis from "ioredis";
 import type { JsonValue } from "../state/types";
-
 export interface ThreadManagerConfig<T> {
   redis: Redis;
   threadId: string;
@@ -71,9 +70,10 @@ export interface ProviderThreadManager<
   TStored,
   TContent = string,
   TToolContent = JsonValue,
+  TSystemContent = string,
 > extends BaseThreadManager<TStored> {
   appendUserMessage(id: string, content: TContent): Promise<void>;
-  appendSystemMessage(id: string, content: string): Promise<void>;
+  appendSystemMessage(id: string, content: TSystemContent): Promise<void>;
   appendToolResult(
     id: string,
     toolCallId: string,

package/src/lib/types.ts

@@ -28,7 +28,7 @@ export interface BaseAgentState {
   /** In-memory file contents keyed by path, bypassing the resolver (e.g. skill resources). */
   inlineFiles?: Record<string, string>;
   virtualFsCtx?: unknown;
-  systemPrompt?: string;
+  systemPrompt?: unknown;
   totalInputTokens: number;
   totalOutputTokens: number;
   cachedWriteTokens: number;

package/src/lib/virtual-fs/manager.ts

@@ -21,7 +21,7 @@ import type {
  * const activities = {
  *   ...createVirtualFsActivities(resolver, "CodingAgent"),
  * };
- * // registers: codingAgentResolveFileTree
+ * // registers: virtualFsCodingAgentResolveFileTree
  * ```
  */
 export function createVirtualFsActivities<

package/src/lib/virtual-fs/types.ts

@@ -93,7 +93,7 @@ export interface VirtualFsOps<TCtx = unknown, TMeta = FileEntryMetadata> {
  * @example
  * ```typescript
  * type Ops = PrefixedVirtualFsOps<"codingAgent">;
- * // → { codingAgentResolveFileTree: ... }
+ * // → { virtualFsCodingAgentResolveFileTree: ... }
  * ```
  */
 export type PrefixedVirtualFsOps<
@@ -104,7 +104,7 @@ export type PrefixedVirtualFsOps<
   [K in keyof VirtualFsOps<
     TCtx,
     TMeta
-  > as `${TPrefix}${Capitalize<K & string>}`]: VirtualFsOps<TCtx, TMeta>[K];
+  > as `virtualFs${Capitalize<TPrefix>}${Capitalize<K & string>}`]: VirtualFsOps<TCtx, TMeta>[K];
 };
 
 // ============================================================================

package/src/lib/virtual-fs/virtual-fs.test.ts

@@ -398,8 +398,8 @@ describe("createVirtualFsActivities", () => {
     const { resolver } = createMockResolver();
     const activities = createVirtualFsActivities(resolver, "codingAgent");
 
-    expect(activities).toHaveProperty("codingAgentResolveFileTree");
-    const result = await activities.codingAgentResolveFileTree(ctx);
+    expect(activities).toHaveProperty("virtualFsCodingAgentResolveFileTree");
+    const result = await activities.virtualFsCodingAgentResolveFileTree(ctx);
     expect(result.fileTree).toHaveLength(3);
     expect(result.fileTree[0]?.path).toMatch(/^\/resolved\//);
   });

package/src/workflow.ts

@@ -119,7 +119,6 @@ export type {
   ToolResultConfig,
   SessionExitReason,
   SerializableToolDefinition,
-  // Task types
   TaskStatus,
   WorkflowTask,
 } from "./lib/types";