zeitlich 0.2.21 → 0.2.23

package/src/lib/lifecycle.ts

@@ -0,0 +1,57 @@
+// ============================================================================
+// Thread lifecycle
+// ============================================================================
+
+/**
+ * Thread initialization strategy.
+ *
+ * - `"new"` — start a fresh thread (optionally specify its ID).
+ * - `"continue"` — append directly to an existing thread in-place.
+ * - `"fork"` — copy all messages from an existing thread into a new one and
+ *   continue there.
+ */
+export type ThreadInit =
+  | { mode: "new"; threadId?: string }
+  | { mode: "continue"; threadId: string }
+  | { mode: "fork"; threadId: string };
+
+// ============================================================================
+// Sandbox lifecycle
+// ============================================================================
+
+/**
+ * Sandbox initialization strategy.
+ *
+ * - `"new"` — create a fresh sandbox.
+ * - `"continue"` — resume a previously-paused sandbox (this session takes
+ *   ownership and the shutdown policy applies on exit).
+ * - `"fork"` — fork from an existing (or paused) sandbox; a new sandbox is
+ *   created and owned by this session.
+ * - `"inherit"` — use a sandbox owned by someone else (e.g. a parent agent).
+ *   The session will **not** manage its lifecycle on exit.
+ */
+export type SandboxInit =
+  | { mode: "new" }
+  | { mode: "continue"; sandboxId: string }
+  | { mode: "fork"; sandboxId: string }
+  | { mode: "inherit"; sandboxId: string };
+
+/**
+ * What to do with the sandbox when the session exits.
+ *
+ * - `"destroy"` — tear down the sandbox entirely.
+ * - `"pause"` — pause the sandbox so it can be resumed later.
+ * - `"keep"` — leave the sandbox running (no-op on exit).
+ */
+export type SandboxShutdown = "destroy" | "pause" | "keep";
+
+/**
+ * Extended shutdown options available to subagent workflows.
+ *
+ * Includes all base {@link SandboxShutdown} values plus:
+ * - `"pause-until-parent-close"` — pause the sandbox on exit, then wait for
+ *   the parent workflow to signal when to destroy it.
+ */
+export type SubagentSandboxShutdown =
+  | SandboxShutdown
+  | "pause-until-parent-close";

package/src/lib/sandbox/manager.ts

@@ -2,6 +2,7 @@ import type {
   Sandbox,
   SandboxCreateOptions,
   SandboxOps,
+  PrefixedSandboxOps,
   SandboxProvider,
   SandboxSnapshot,
 } from "./types";
@@ -16,16 +17,20 @@ import type {
  * ```typescript
  * const manager = new SandboxManager(new InMemorySandboxProvider());
  * const activities = {
- *   ...manager.createActivities(),
+ *   ...manager.createActivities("CodingAgent"),
  *   bashHandler: withSandbox(manager, bashHandler),
  * };
+ * // registers: inMemoryCodingAgentCreateSandbox, …
  * ```
  */
 export class SandboxManager<
   TOptions extends SandboxCreateOptions = SandboxCreateOptions,
   TSandbox extends Sandbox = Sandbox,
+  TId extends string = string,
 > {
-  constructor(private provider: SandboxProvider<TOptions, TSandbox>) {}
+  constructor(
+    private provider: SandboxProvider<TOptions, TSandbox> & { readonly id: TId }
+  ) {}
 
   async create(
     options?: TOptions
@@ -42,6 +47,10 @@ export class SandboxManager<
     await this.provider.destroy(id);
   }
 
+  async pause(id: string, ttlSeconds?: number): Promise<void> {
+    await this.provider.pause(id, ttlSeconds);
+  }
+
   async snapshot(id: string): Promise<SandboxSnapshot> {
     return this.provider.snapshot(id);
   }
@@ -51,12 +60,36 @@ export class SandboxManager<
     return sandbox.id;
   }
 
+  async fork(sandboxId: string): Promise<string> {
+    const sandbox = await this.provider.fork(sandboxId);
+    return sandbox.id;
+  }
+
   /**
-   * Returns Temporal activity functions matching {@link SandboxOps}.
-   * Spread these into your worker's activity map.
+   * Returns Temporal activity functions with prefixed names.
+   *
+   * The provider's `id` is automatically prepended, so you only need
+   * to pass the workflow/scope name. Use the matching `proxy*SandboxOps()`
+   * helper from the adapter's `/workflow` entrypoint on the workflow side.
+   *
+   * @param scope - Workflow name (appended to the provider id)
+   *
+   * @example
+   * ```typescript
+   * const manager = new SandboxManager(new InMemorySandboxProvider());
+   * manager.createActivities("CodingAgent");
+   * // registers: inMemoryCodingAgentCreateSandbox, inMemoryCodingAgentDestroySandbox, …
+   *
+   * const vmgr = new SandboxManager(new VirtualSandboxProvider(resolver));
+   * vmgr.createActivities("CodingAgent");
+   * // registers: virtualCodingAgentCreateSandbox, …
+   * ```
    */
-  createActivities(): SandboxOps<TOptions> {
-    return {
+  createActivities<S extends string>(
+    scope: S
+  ): PrefixedSandboxOps<`${TId}${Capitalize<S>}`, TOptions> {
+    const prefix = `${this.provider.id}${scope.charAt(0).toUpperCase()}${scope.slice(1)}`;
+    const ops: SandboxOps<TOptions> = {
       createSandbox: async (
         options?: TOptions
       ): Promise<{
@@ -68,9 +101,22 @@ export class SandboxManager<
       destroySandbox: async (sandboxId: string): Promise<void> => {
         await this.destroy(sandboxId);
       },
+      pauseSandbox: async (
+        sandboxId: string,
+        ttlSeconds?: number
+      ): Promise<void> => {
+        await this.pause(sandboxId, ttlSeconds);
+      },
       snapshotSandbox: async (sandboxId: string): Promise<SandboxSnapshot> => {
         return this.snapshot(sandboxId);
       },
+      forkSandbox: async (sandboxId: string): Promise<string> => {
+        return this.fork(sandboxId);
+      },
     };
+    const cap = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1);
+    return Object.fromEntries(
+      Object.entries(ops).map(([k, v]) => [`${prefix}${cap(k)}`, v])
+    ) as PrefixedSandboxOps<`${TId}${Capitalize<S>}`, TOptions>;
   }
 }

package/src/lib/sandbox/sandbox.test.ts

@@ -1,10 +1,10 @@
 import { describe, expect, it, beforeEach } from "vitest";
 import { SandboxManager } from "./manager";
 import { InMemorySandboxProvider } from "../../adapters/sandbox/inmemory/index";
-import { SandboxNotFoundError } from "./types";
+import { SandboxNotFoundError, type Sandbox, type SandboxCreateOptions } from "./types";
 
 describe("SandboxManager", () => {
-  let manager: SandboxManager;
+  let manager: SandboxManager<SandboxCreateOptions, Sandbox, "inMemory">;
 
   beforeEach(() => {
     manager = new SandboxManager(new InMemorySandboxProvider());
@@ -54,7 +54,7 @@ describe("SandboxManager", () => {
 
     const snapshot = await manager.snapshot(sandboxId);
     expect(snapshot.sandboxId).toBe(sandboxId);
-    expect(snapshot.providerId).toBe("inmemory");
+    expect(snapshot.providerId).toBe("inMemory");
 
     await manager.destroy(sandboxId);
     await expect(manager.getSandbox(sandboxId)).rejects.toThrow(SandboxNotFoundError);
@@ -68,16 +68,17 @@ describe("SandboxManager", () => {
     expect(extra).toBe("world");
   });
 
-  it("createActivities returns SandboxOps-shaped object", async () => {
-    const activities = manager.createActivities();
-    expect(activities.createSandbox).toBeTypeOf("function");
-    expect(activities.destroySandbox).toBeTypeOf("function");
-    expect(activities.snapshotSandbox).toBeTypeOf("function");
+  it("createActivities returns prefixed SandboxOps-shaped object", async () => {
+    // provider.id is "inMemory", scope is "Test" → prefix "inMemoryTest"
+    const activities = manager.createActivities("Test");
+    expect(activities.inMemoryTestCreateSandbox).toBeTypeOf("function");
+    expect(activities.inMemoryTestDestroySandbox).toBeTypeOf("function");
+    expect(activities.inMemoryTestSnapshotSandbox).toBeTypeOf("function");
 
-    const { sandboxId } = await activities.createSandbox();
+    const { sandboxId } = await activities.inMemoryTestCreateSandbox();
     await expect(manager.getSandbox(sandboxId)).resolves.toBeTruthy();
 
-    await activities.destroySandbox(sandboxId);
+    await activities.inMemoryTestDestroySandbox(sandboxId);
     await expect(manager.getSandbox(sandboxId)).rejects.toThrow(
       SandboxNotFoundError,
     );
@@ -85,7 +86,7 @@ describe("SandboxManager", () => {
 });
 
 describe("InMemorySandboxProvider", () => {
-  let manager: SandboxManager;
+  let manager: SandboxManager<SandboxCreateOptions, Sandbox, "inMemory">;
 
   beforeEach(() => {
     manager = new SandboxManager(new InMemorySandboxProvider());

package/src/lib/sandbox/types.ts

@@ -35,8 +35,15 @@ export interface SandboxFileSystem {
   mkdir(path: string, options?: { recursive?: boolean }): Promise<void>;
   readdir(path: string): Promise<string[]>;
   readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
-  rm(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>;
-  cp(src: string, dest: string, options?: { recursive?: boolean }): Promise<void>;
+  rm(
+    path: string,
+    options?: { recursive?: boolean; force?: boolean }
+  ): Promise<void>;
+  cp(
+    src: string,
+    dest: string,
+    options?: { recursive?: boolean }
+  ): Promise<void>;
   mv(src: string, dest: string): Promise<void>;
   readlink(path: string): Promise<string>;
   resolvePath(base: string, path: string): string;
@@ -125,8 +132,10 @@ export interface SandboxProvider<
   create(options?: TOptions): Promise<SandboxCreateResult>;
   get(sandboxId: string): Promise<TSandbox>;
   destroy(sandboxId: string): Promise<void>;
+  pause(sandboxId: string, ttlSeconds?: number): Promise<void>;
   snapshot(sandboxId: string): Promise<SandboxSnapshot>;
   restore(snapshot: SandboxSnapshot): Promise<Sandbox>;
+  fork(sandboxId: string): Promise<Sandbox>;
 }
 
 // ============================================================================
@@ -137,12 +146,30 @@ export interface SandboxOps<
   TOptions extends SandboxCreateOptions = SandboxCreateOptions,
 > {
   createSandbox(
-    options?: TOptions,
+    options?: TOptions
   ): Promise<{ sandboxId: string; stateUpdate?: Record<string, unknown> }>;
   destroySandbox(sandboxId: string): Promise<void>;
+  pauseSandbox(sandboxId: string): Promise<void>;
   snapshotSandbox(sandboxId: string): Promise<SandboxSnapshot>;
+  forkSandbox(sandboxId: string): Promise<string>;
 }
 
+/**
+ * Maps generic {@link SandboxOps} method names to adapter-prefixed names.
+ *
+ * @example
+ * ```typescript
+ * type InMemOps = PrefixedSandboxOps<"inMemory">;
+ * // → { inMemoryCreateSandbox, inMemoryDestroySandbox, inMemorySnapshotSandbox }
+ * ```
+ */
+export type PrefixedSandboxOps<
+  TPrefix extends string,
+  TOptions extends SandboxCreateOptions = SandboxCreateOptions,
+> = {
+  [K in keyof SandboxOps<TOptions> as `${TPrefix}${Capitalize<K & string>}`]: SandboxOps<TOptions>[K];
+};
+
 // ============================================================================
 // Errors
 // ============================================================================
@@ -154,7 +181,7 @@ export class SandboxNotSupportedError extends ApplicationFailure {
     super(
       `Sandbox does not support: ${operation}`,
       "SandboxNotSupportedError",
-      true,
+      true
     );
   }
 }

package/src/lib/session/index.ts

@@ -1,11 +1,10 @@
-export {
-  createSession,
-  proxyDefaultThreadOps,
-  proxySandboxOps,
-} from "./session";
+export { createSession } from "./session";
 
 export type {
   ThreadOps,
+  PrefixedThreadOps,
+  ScopedPrefix,
   SessionConfig,
+  SessionResult,
   ZeitlichSession,
 } from "./types";