zeitlich 0.2.36 → 0.2.38

package/src/lib/subagent/tool.ts

@@ -6,9 +6,10 @@ export const SUBAGENT_TOOL_NAME = "Subagent" as const;
 function buildSubagentDescription(subagents: SubagentConfig[]): string {
   const subagentList = subagents
     .map((s) => {
-      const continuation = s.thread && s.thread !== "new"
-        ? "\n*(Supports thread continuation — pass a threadId to resume a previous conversation)*"
-        : "";
+      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}`;
     })
     .join("\n\n");

package/src/lib/subagent/types.ts

@@ -10,10 +10,24 @@ import type {
   SandboxInit,
   SubagentSandboxShutdown,
 } from "../lifecycle";
+import type { SandboxOps, SandboxSnapshot } from "../sandbox/types";
 
 /** ToolHandlerResponse with threadId required (subagents must always surface their thread) */
-export type SubagentHandlerResponse<TResult = null, TToolResponse = JsonValue> =
-  ToolHandlerResponse<TResult, TToolResponse> & { threadId: string; sandboxId?: string };
+export type SubagentHandlerResponse<
+  TResult = null,
+  TToolResponse = JsonValue,
+> = ToolHandlerResponse<TResult, TToolResponse> & {
+  threadId: string;
+  sandboxId?: string;
+  /** Snapshot captured on session exit when `sandboxShutdown === "snapshot"`. */
+  snapshot?: SandboxSnapshot;
+  /**
+   * Snapshot captured immediately after the sandbox was seeded (before the
+   * first agent turn) when `continuation === "snapshot"`. Only set on the
+   * first call that actually created the sandbox.
+   */
+  baseSnapshot?: SandboxSnapshot;
+};
 
 /**
  * Raw workflow input fields passed from parent to child workflow.
@@ -64,13 +78,19 @@ export type InferSubagentResult<T extends SubagentConfig> =
  * Sandbox configuration for a subagent.
  *
  * - `"none"` — no sandbox (default).
- * - `{ source: "inherit", continuation }` — reuse the parent's sandbox.
+ * - `{ source: "inherit", continuation, proxy }` — 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.
+ * - `{ source: "own", init?, continuation, proxy }` — 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.
+ *
+ * `proxy` is a factory that returns workflow-safe sandbox ops matching the
+ * subagent's own activities. Called once inside `createSubagentHandler` with
+ * `scope = agentName`, so the returned proxy resolves to the same activity
+ * prefix the child session uses. The parent uses it to destroy lingering
+ * sandboxes and delete stored snapshots at shutdown.
  */
 export type SubagentSandboxConfig =
   | "none"
@@ -78,12 +98,14 @@ export type SubagentSandboxConfig =
       source: "inherit";
       continuation: "continue" | "fork";
       shutdown?: SubagentSandboxShutdown;
+      proxy: (scope: string) => SandboxOps;
     }
   | {
       source: "own";
       init?: "per-call" | "once";
-      continuation: "continue" | "fork";
+      continuation: "continue" | "fork" | "snapshot";
       shutdown?: SubagentSandboxShutdown;
+      proxy: (scope: string) => SandboxOps;
     };
 
 /**
@@ -122,6 +144,21 @@ export interface SubagentConfig<TResult extends z.ZodType = z.ZodType> {
    * Sandbox strategy for this subagent.
    *
    * @see {@link SubagentSandboxConfig}
+   *
+   * @example
+   * ```ts
+   * import { proxyDaytonaSandboxOps } from "zeitlich/adapters/sandbox/daytona/workflow";
+   *
+   * const researcher: SubagentConfig = {
+   *   agentName: "researcher",
+   *   workflow: researcherWorkflow,
+   *   sandbox: {
+   *     source: "own",
+   *     continuation: "snapshot",
+   *     proxy: proxyDaytonaSandboxOps,
+   *   },
+   * };
+   * ```
    */
   sandbox?: SubagentSandboxConfig;
 }
@@ -157,12 +194,11 @@ export interface SubagentHooks<TArgs = unknown, TResult = unknown> {
 }
 
 /**
- * Extended response from the subagent `fn` — includes optional cleanup callbacks
- * stripped before signaling the parent.
+ * Response returned from a subagent workflow `fn`.
  *
  * When `TSandboxShutdown` is `"pause-until-parent-close"` or
- * `"keep-until-parent-close"`, both `destroySandbox` and `sandboxId` become
- * required so the parent can coordinate cleanup.
+ * `"keep-until-parent-close"`, the parent needs the `sandboxId` to destroy
+ * the sandbox at its own shutdown, so the field becomes required.
  */
 export type SubagentFnResult<
   TResult = null,
@@ -171,14 +207,8 @@ export type SubagentFnResult<
   (TSandboxShutdown extends
     | "pause-until-parent-close"
     | "keep-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;
-}
+    ? { sandboxId: string }
+    : { sandboxId?: string });
 
 /** Payload sent by a child workflow as soon as its sandbox is ready */
 export interface ChildSandboxReadySignalPayload {

package/src/lib/subagent/workflow.ts

@@ -2,8 +2,6 @@ import type { z } from "zod";
 import {
   workflowInfo,
   getExternalWorkflowHandle,
-  setHandler,
-  condition,
   ApplicationFailure,
 } from "@temporalio/workflow";
 import type {
@@ -14,11 +12,7 @@ import type {
   SubagentSessionInput,
 } from "./types";
 import type { SubagentSandboxShutdown } from "../lifecycle";
-import {
-  childResultSignal,
-  childSandboxReadySignal,
-  destroySandboxSignal,
-} from "./signals";
+import { childSandboxReadySignal } from "./signals";
 
 /**
  * Defines a subagent workflow with embedded metadata (name, description, resultSchema).
@@ -137,51 +131,17 @@ export function defineSubagentWorkflow(
       ...(workflowInput.thread && { thread: workflowInput.thread }),
       ...(workflowInput.sandbox && { sandbox: workflowInput.sandbox }),
       onSandboxReady: (sandboxId: string) => {
-        void parentHandle.signal(childSandboxReadySignal, {
-          childWorkflowId: workflowInfo().workflowId,
-          sandboxId,
-        });
+        const isReuse = workflowInput.sandbox?.mode === "continue";
+        if (!isReuse) {
+          void parentHandle.signal(childSandboxReadySignal, {
+            childWorkflowId: workflowInfo().workflowId,
+            sandboxId,
+          });
+        }
       },
     };
-    const { destroySandbox, ...result } = await fn(
-      prompt,
-      sessionInput,
-      context ?? {}
-    );
-
-    if (
-      effectiveShutdown === "pause-until-parent-close" ||
-      effectiveShutdown === "keep-until-parent-close"
-    ) {
-      if (!destroySandbox) {
-        throw ApplicationFailure.create({
-          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="${effectiveShutdown}" but fn did not return a sandboxId`,
-          nonRetryable: true,
-        });
-      }
-    }
-
-    await parentHandle.signal(childResultSignal, {
-      childWorkflowId: workflowInfo().workflowId,
-      result,
-    });
-
-    if (destroySandbox) {
-      let destroyRequested = false;
-      setHandler(destroySandboxSignal, () => {
-        destroyRequested = true;
-      });
-      await condition(() => destroyRequested);
-      await destroySandbox();
-    }
 
-    return result;
+    return fn(prompt, sessionInput, context ?? {});
   };
 
   // for temporal workflow name

package/src/lib/thread/id.test.ts

@@ -8,7 +8,7 @@ vi.mock("@temporalio/workflow", () => ({
     const bytes = Array.from({ length: 16 }, (_, i) =>
       ((uuidCounter * 31 + i * 7 + uuidCounter * i) & 0xff)
         .toString(16)
-        .padStart(2, "0"),
+        .padStart(2, "0")
     ).join("");
     return `${bytes.slice(0, 8)}-${bytes.slice(8, 12)}-${bytes.slice(12, 16)}-${bytes.slice(16, 20)}-${bytes.slice(20, 32)}`;
   },

package/src/lib/thread/id.ts

@@ -1,7 +1,6 @@
 import { uuid4 } from "@temporalio/workflow";
 
-const BASE62 =
-  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+const BASE62 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
 
 /**
  * Generate a compact, workflow-deterministic identifier.

package/src/lib/thread/manager.ts

@@ -104,5 +104,23 @@ export function createThreadManager<T>(
     async delete(): Promise<void> {
       await redis.del(redisKey, metaKey);
     },
+
+    async length(): Promise<number> {
+      await assertThreadExists();
+      return redis.llen(redisKey);
+    },
+
+    async truncate(length: number): Promise<void> {
+      await assertThreadExists();
+      if (length <= 0) {
+        await redis.del(redisKey);
+        await redis.expire(metaKey, THREAD_TTL_SECONDS);
+      } else {
+        await redis.ltrim(redisKey, 0, length - 1);
+        await redis.expire(redisKey, THREAD_TTL_SECONDS);
+      }
+      // Dedup keys for removed messages are left to expire via their TTL.
+      // Post-truncate appends use fresh ids so collisions do not occur in practice.
+    },
   };
 }

package/src/lib/thread/proxy.ts

@@ -25,7 +25,7 @@ import type { ThreadOps } from "../session/types";
 export function createThreadOpsProxy(
   adapterPrefix: string,
   scope?: string,
-  options?: Parameters<typeof proxyActivities>[0],
+  options?: Parameters<typeof proxyActivities>[0]
 ): ActivityInterfaceFor<ThreadOps> {
   const resolvedScope = scope ?? workflowInfo().workflowType;
 
@@ -39,11 +39,10 @@ export function createThreadOpsProxy(
         maximumInterval: "15m",
         backoffCoefficient: 4,
       },
-    },
+    }
   );
 
-  const prefix =
-    `${adapterPrefix}${resolvedScope.charAt(0).toUpperCase()}${resolvedScope.slice(1)}`;
+  const prefix = `${adapterPrefix}${resolvedScope.charAt(0).toUpperCase()}${resolvedScope.slice(1)}`;
   const p = (key: string): string =>
     `${prefix}${key.charAt(0).toUpperCase()}${key.slice(1)}`;
 
@@ -54,5 +53,6 @@ export function createThreadOpsProxy(
     appendAgentMessage: acts[p("appendAgentMessage")],
     appendSystemMessage: acts[p("appendSystemMessage")],
     forkThread: acts[p("forkThread")],
+    truncateThread: acts[p("truncateThread")],
   } as ActivityInterfaceFor<ThreadOps>;
 }

package/src/lib/thread/types.ts

@@ -36,6 +36,15 @@ export interface BaseThreadManager<T> {
   fork(newThreadId: string): Promise<BaseThreadManager<T>>;
   /** Delete the thread */
   delete(): Promise<void>;
+  /** Get the number of stored messages currently in the thread */
+  length(): Promise<number>;
+  /**
+   * Truncate the thread to the given length (inclusive). Any messages
+   * beyond `length` are removed. When `length` is 0 the thread ends up
+   * empty (but still exists). Also clears any dedup markers so that
+   * subsequent appends with the same ids replay correctly.
+   */
+  truncate(length: number): Promise<void>;
 }
 
 /**
@@ -61,9 +70,17 @@ export interface BaseThreadManager<T> {
  */
 export interface ThreadManagerHooks<TStored, TPrepared = TStored> {
   /** Called for each stored message before SDK-specific processing (system extraction, role merging, format conversion) */
-  onPrepareMessage?: (message: TStored, index: number, thread: readonly TStored[]) => TStored;
+  onPrepareMessage?: (
+    message: TStored,
+    index: number,
+    thread: readonly TStored[]
+  ) => TStored;
   /** Called for each SDK-native message after all processing, right before the payload is returned */
-  onPreparedMessage?: (message: TPrepared, index: number, messages: readonly TPrepared[]) => TPrepared;
+  onPreparedMessage?: (
+    message: TPrepared,
+    index: number,
+    messages: readonly TPrepared[]
+  ) => TPrepared;
 }
 
 export interface ProviderThreadManager<
@@ -78,6 +95,6 @@ export interface ProviderThreadManager<
     id: string,
     toolCallId: string,
     toolName: string,
-    content: TToolContent,
+    content: TToolContent
   ): Promise<void>;
 }

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

@@ -1,8 +1,4 @@
-export {
-  createToolRouter,
-  defineTool,
-  hasNoOtherToolCalls,
-} from "./router";
+export { createToolRouter, defineTool, hasNoOtherToolCalls } from "./router";
 export { withAutoAppend } from "./auto-append";
 export { withSandbox } from "./with-sandbox";
 export type { SandboxContext } from "./with-sandbox";
@@ -26,6 +22,8 @@ export type {
   InferToolResults,
   ToolCallResultUnion,
   ProcessToolCallsContext,
+  ProcessToolCallsResult,
+  RewindSignal,
   PreToolUseHookResult,
   PostToolUseFailureHookResult,
   ToolHooks,

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

@@ -23,8 +23,20 @@ vi.mock("@temporalio/workflow", () => {
     }
   }
   const noop = () => {};
+  class MockCancellationScope {
+    cancellable: boolean;
+    constructor(opts?: { cancellable?: boolean }) {
+      this.cancellable = opts?.cancellable ?? true;
+    }
+    async run<T>(fn: () => Promise<T>): Promise<T> {
+      return fn();
+    }
+    cancel(): void {}
+  }
   return {
     ApplicationFailure: MockApplicationFailure,
+    CancellationScope: MockCancellationScope,
+    isCancellation: (_err: unknown) => false,
     uuid4: () => "00000000-0000-0000-0000-000000000000",
     log: { trace: noop, debug: noop, info: noop, warn: noop, error: noop },
   };
@@ -348,7 +360,7 @@ describe("createToolRouter edge cases", () => {
       parallel: true,
     });
 
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+     
     const results = await router.processToolCalls([
       { id: "tc-1", name: "Unknown1", args: {} },
       { id: "tc-2", name: "Unknown2", args: {} },
@@ -648,6 +660,86 @@ describe("createToolRouter edge cases", () => {
       recovered: true,
     });
   });
+
+  // --- Rewind signal -------------------------------------------------------
+
+  it("attaches a rewind signal and skips result append when handler returns rewind:true", async () => {
+    const rewindTool = defineTool({
+      name: "Rewind" as const,
+      description: "rewinds",
+      schema: z.object({}),
+      handler: async () => ({
+        toolResponse: "ignored",
+        data: null,
+        rewind: true,
+      }),
+    });
+
+    const router = createToolRouter({
+      tools: { Rewind: rewindTool } as const,
+      threadId: "t-1",
+      appendToolResult: appendSpy.fn,
+    });
+
+    const parsed = router.parseToolCall({
+      id: "tc-1",
+      name: "Rewind",
+      args: {},
+    });
+
+    const results = await router.processToolCalls([parsed]);
+
+    expect(results).toHaveLength(0);
+    expect(results.rewind).toEqual({
+      toolCallId: "tc-1",
+      toolName: "Rewind",
+    });
+    expect(appendSpy.calls).toHaveLength(0);
+  });
+
+  it("short-circuits further sequential tool calls when one requests rewind", async () => {
+    let laterCalled = false;
+    const laterTool = defineTool({
+      name: "Later" as const,
+      description: "runs after rewind",
+      schema: z.object({}),
+      handler: async () => {
+        laterCalled = true;
+        return { toolResponse: "ok", data: null };
+      },
+    });
+    const rewindTool = defineTool({
+      name: "Rewind" as const,
+      description: "rewinds",
+      schema: z.object({}),
+      handler: async () => ({
+        toolResponse: "ignored",
+        data: null,
+        rewind: true,
+      }),
+    });
+
+    const router = createToolRouter({
+      tools: { Rewind: rewindTool, Later: laterTool } as const,
+      threadId: "t-1",
+      appendToolResult: appendSpy.fn,
+      parallel: false,
+    });
+
+    const calls = [
+      router.parseToolCall({ id: "tc-1", name: "Rewind", args: {} }),
+      router.parseToolCall({ id: "tc-2", name: "Later", args: {} }),
+    ];
+
+    const results = await router.processToolCalls(calls);
+
+    expect(results).toHaveLength(0);
+    expect(results.rewind).toEqual({
+      toolCallId: "tc-1",
+      toolName: "Rewind",
+    });
+    expect(laterCalled).toBe(false);
+  });
 });
 
 describe("hasNoOtherToolCalls", () => {

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

@@ -23,8 +23,20 @@ vi.mock("@temporalio/workflow", () => {
     }
   }
   const noop = () => {};
+  class MockCancellationScope {
+    cancellable: boolean;
+    constructor(opts?: { cancellable?: boolean }) {
+      this.cancellable = opts?.cancellable ?? true;
+    }
+    async run<T>(fn: () => Promise<T>): Promise<T> {
+      return fn();
+    }
+    cancel(): void {}
+  }
   return {
     ApplicationFailure: MockApplicationFailure,
+    CancellationScope: MockCancellationScope,
+    isCancellation: (_err: unknown) => false,
     uuid4: () => "00000000-0000-0000-0000-000000000000",
     log: { trace: noop, debug: noop, info: noop, warn: noop, error: noop },
   };