zeitlich 0.2.21 → 0.2.23

package/dist/{types-CES_30qx.d.cts → types-DQW8l7pY.d.cts}

@@ -1,7 +1,7 @@
 import { Duration } from '@temporalio/common';
-import { a as ToolMap, b as ToolRouterHooks, M as MessageContent, S as SessionExitReason, c as ToolHandlerResponse, P as PreToolUseHookResult, d as PostToolUseFailureHookResult, e as RawToolCall, f as TokenUsage, B as BaseAgentState, g as RunAgentConfig, h as AgentStatus, W as WorkflowTask, i as ToolDefinition, j as ToolResultConfig, k as ToolCallResultUnion, I as InferToolResults } from './types-YbL7JpEA.cjs';
+import { a as ToolMap, b as ToolRouterHooks, M as MessageContent, S as SessionExitReason, c as ToolHandlerResponse, P as PreToolUseHookResult, d as PostToolUseFailureHookResult, e as RawToolCall, f as TokenUsage, B as BaseAgentState, g as RunAgentConfig, h as AgentStatus, W as WorkflowTask, i as ToolDefinition, j as ToolResultConfig, k as ToolCallResultUnion, I as InferToolResults } from './types-Bll19FZJ.cjs';
 import { z } from 'zod';
-import { g as SandboxOps } from './types-BMRzfELQ.cjs';
+import { g as SandboxOps } from './types-ChAMwU3q.cjs';
 import { QueryDefinition, ActivityInterfaceFor } from '@temporalio/workflow';
 import { UpdateDefinition } from '@temporalio/common/lib/interfaces';
 
@@ -69,19 +69,80 @@ interface Hooks<T extends ToolMap, TResult = unknown> extends ToolRouterHooks<T,
     onSessionEnd?: SessionEndHook;
 }
 
+/**
+ * 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.
+ */
+type ThreadInit = {
+    mode: "new";
+    threadId?: string;
+} | {
+    mode: "continue";
+    threadId: string;
+} | {
+    mode: "fork";
+    threadId: string;
+};
+/**
+ * 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.
+ */
+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).
+ */
+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.
+ */
+type SubagentSandboxShutdown = SandboxShutdown | "pause-until-parent-close";
+
 /** ToolHandlerResponse with threadId required (subagents must always surface their thread) */
 type SubagentHandlerResponse<TResult = null> = ToolHandlerResponse<TResult> & {
     threadId: string;
+    sandboxId?: string;
 };
 /**
  * Raw workflow input fields passed from parent to child workflow.
  * `defineSubagentWorkflow` maps this into `SubagentSessionInput`.
  */
 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;
 }
 type SubagentWorkflow<TResult extends z.ZodType = z.ZodType> = (prompt: string, workflowInput: SubagentWorkflowInput, context?: Record<string, unknown>) => Promise<SubagentHandlerResponse<z.infer<TResult> | null>>;
 /**
@@ -93,6 +154,23 @@ type SubagentDefinition<TResult extends z.ZodType = z.ZodType, TContext extends
     readonly description: string;
     readonly resultSchema?: TResult;
 };
+/** Context value or factory — resolved at invocation time when a function is provided */
+type SubagentContext = Record<string, unknown> | (() => Record<string, unknown>);
+/**
+ * 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.
+ */
+type SubagentSandboxConfig = "none" | "inherit" | "own" | {
+    source: "own";
+    shutdown?: SubagentSandboxShutdown;
+};
 /**
  * Configuration for a subagent that can be spawned by the parent workflow.
  *
@@ -106,23 +184,34 @@ 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 static context passed to the subagent on every invocation */
-    context?: Record<string, unknown>;
-    /** Allow the parent agent to pass a threadId for this subagent to continue (default: false) */
-    allowThreadContinuation?: boolean;
+    /** Optional context passed to the subagent — a static object or a function evaluated at invocation time */
+    context?: SubagentContext;
     /** 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;
 }
 /**
  * Per-subagent lifecycle hooks - defined on a SubagentConfig.
@@ -142,6 +231,8 @@ 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: {
@@ -151,18 +242,31 @@ interface SubagentHooks<TArgs = unknown, TResult = unknown> {
         turn: number;
     }) => 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.
+ */
+type SubagentFnResult<TResult = null, TSandboxShutdown extends SubagentSandboxShutdown = SubagentSandboxShutdown> = SubagentHandlerResponse<TResult> & (TSandboxShutdown extends "pause-until-parent-close" ? {
+    destroySandbox: () => Promise<void>;
+    sandboxId: string;
+} : {
+    destroySandbox?: () => Promise<void>;
+});
 /**
  * Session config fields passed from parent to child workflow.
  */
 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;
 }
 
 /**
@@ -350,14 +454,38 @@ interface ThreadOps {
     /** Copy all messages from sourceThreadId into a new thread at targetThreadId */
     forkThread(sourceThreadId: string, targetThreadId: string): Promise<void>;
 }
+/**
+ * Composes an adapter prefix + workflow scope for activity naming.
+ *
+ * The adapter prefix stays first (camelCase); the workflow scope is
+ * capitalised and appended. When `TScope` is empty the adapter prefix
+ * is used as-is.
+ *
+ * @example
+ * ```typescript
+ * ScopedPrefix<"codingAgent", "googleGenAI"> // "googleGenAICodingAgent"
+ * ScopedPrefix<"", "googleGenAI">            // "googleGenAI"
+ * ```
+ */
+type ScopedPrefix<TScope extends string, TAdapter extends string> = TScope extends "" ? TAdapter : `${TAdapter}${Capitalize<TScope>}`;
+/**
+ * Maps generic {@link ThreadOps} method names to adapter-prefixed names.
+ *
+ * @example
+ * ```typescript
+ * type GoogleOps = PrefixedThreadOps<"googleGenAI">;
+ * // → { googleGenAIInitializeThread, googleGenAIAppendHumanMessage, … }
+ * ```
+ */
+type PrefixedThreadOps<TPrefix extends string> = {
+    [K in keyof ThreadOps as `${TPrefix}${Capitalize<K & string>}`]: ThreadOps[K];
+};
 /**
  * Configuration for a Zeitlich agent session
  */
 interface SessionConfig<T extends ToolMap, M = unknown> {
     /** The name of the agent, should be unique within the workflows */
     agentName: string;
-    /** The thread ID to use for the session (defaults to a short generated ID) */
-    threadId?: string;
     /** Metadata for the session */
     metadata?: Record<string, unknown>;
     /** Whether to append the system prompt as message to the thread */
@@ -367,7 +495,7 @@ interface SessionConfig<T extends ToolMap, M = unknown> {
     /** Workflow-specific runAgent activity (with tools pre-bound) */
     runAgent: RunAgentActivity<M>;
     /** Thread operations (initialize, append messages, parse tool calls) */
-    threadOps?: ActivityInterfaceFor<ThreadOps>;
+    threadOps: ActivityInterfaceFor<ThreadOps>;
     /** Tool router for processing tool calls (optional if agent has no tools) */
     tools?: T;
     /** Subagent configurations */
@@ -383,28 +511,52 @@ interface SessionConfig<T extends ToolMap, M = unknown> {
      * Returns MessageContent array for the initial HumanMessage.
      */
     buildContextMessage: () => MessageContent | Promise<MessageContent>;
-    /** When true, skip thread initialization and system prompt — append only the new human message to the existing thread. */
-    continueThread?: boolean;
     /** How long to wait for input before cancelling the workflow */
     waitForInputTimeout?: Duration;
+    /**
+     * Thread initialization strategy (default: `{ mode: "new" }`).
+     *
+     * - `{ mode: "new" }` — start a fresh thread.
+     * - `{ mode: "new", threadId: "..." }` — start a fresh thread with a specific ID.
+     * - `{ mode: "continue", threadId: "..." }` — append to an existing thread in-place.
+     * - `{ mode: "fork", threadId: "..." }` — fork an existing thread and continue in the copy.
+     */
+    thread?: ThreadInit;
     /** Sandbox lifecycle operations (optional — omit for agents that don't need a sandbox) */
-    sandbox?: SandboxOps;
+    sandboxOps?: SandboxOps;
     /**
-     * Pre-existing sandbox ID to reuse (e.g. inherited from a parent agent).
-     * When set, the session skips `createSandbox` and will not destroy the
-     * sandbox on exit (the owner is responsible for cleanup).
+     * Sandbox initialization strategy.
+     *
+     * - `{ mode: "new" }` — create a fresh sandbox.
+     * - `{ mode: "continue", sandboxId: "..." }` — resume a paused sandbox (session owns it).
+     * - `{ mode: "fork", sandboxId: "..." }` — fork from an existing sandbox.
+     * - `{ mode: "inherit", sandboxId: "..." }` — use a parent's sandbox without ownership.
+     *
+     * When omitted and `sandboxOps` is provided, defaults to `{ mode: "new" }`.
      */
-    sandboxId?: string;
+    sandbox?: SandboxInit;
+    /**
+     * What to do with the sandbox when this session exits.
+     *
+     * Defaults to `"destroy"` when omitted.
+     * Has no effect when the sandbox is inherited (`sandbox.mode === "inherit"`).
+     */
+    sandboxShutdown?: SubagentSandboxShutdown;
 }
-interface ZeitlichSession<M = unknown> {
+type SessionResult<M, TState extends JsonSerializable<TState>, HasSandbox extends boolean = boolean> = {
+    threadId: string;
+    finalMessage: M | null;
+    exitReason: SessionExitReason;
+    usage: ReturnType<AgentStateManager<TState>["getTotalUsage"]>;
+} & (HasSandbox extends true ? {
+    sandboxId: string;
+} : {
+    sandboxId?: undefined;
+});
+interface ZeitlichSession<M = unknown, HasSandbox extends boolean = boolean> {
     runSession<T extends JsonSerializable<T>>(args: {
         stateManager: AgentStateManager<T>;
-    }): Promise<{
-        threadId: string;
-        finalMessage: M | null;
-        exitReason: SessionExitReason;
-        usage: ReturnType<AgentStateManager<T>["getTotalUsage"]>;
-    }>;
+    }): Promise<SessionResult<M, T, HasSandbox>>;
 }
 
-export type { AgentResponse as A, Hooks as H, JsonPrimitive as J, ModelInvoker as M, PostHumanMessageAppendHook as P, RunAgentActivity as R, SkillProvider as S, ThreadOps as T, ZeitlichSession as Z, ModelInvokerConfig as a, SkillMetadata as b, Skill as c, AgentState as d, AgentStateManager as e, JsonSerializable as f, JsonValue as g, PostHumanMessageAppendHookContext as h, PreHumanMessageAppendHook as i, PreHumanMessageAppendHookContext as j, SessionConfig as k, SessionEndHook as l, SessionEndHookContext as m, SessionStartHook as n, SessionStartHookContext as o, SubagentConfig as p, SubagentDefinition as q, SubagentHandlerResponse as r, SubagentHooks as s, SubagentSessionInput as t, SubagentWorkflow as u, SubagentWorkflowInput as v };
+export type { AgentResponse as A, SubagentSandboxShutdown as B, SubagentSessionInput as C, SubagentWorkflow as D, SubagentWorkflowInput as E, ThreadInit as F, Hooks as H, JsonPrimitive as J, ModelInvoker as M, PrefixedThreadOps as P, RunAgentActivity as R, ScopedPrefix as S, ThreadOps as T, ZeitlichSession as Z, ModelInvokerConfig as a, SkillProvider as b, SkillMetadata as c, Skill as d, AgentState as e, AgentStateManager as f, JsonSerializable as g, JsonValue as h, PostHumanMessageAppendHook as i, PostHumanMessageAppendHookContext as j, PreHumanMessageAppendHook as k, PreHumanMessageAppendHookContext as l, SandboxInit as m, SandboxShutdown as n, SessionConfig as o, SessionEndHook as p, SessionEndHookContext as q, SessionResult as r, SessionStartHook as s, SessionStartHookContext as t, SubagentConfig as u, SubagentDefinition as v, SubagentFnResult as w, SubagentHandlerResponse as x, SubagentHooks as y, SubagentSandboxConfig as z };

package/dist/{queries-CHa2iv_I.d.cts → types-GZ76HZSj.d.ts}

@@ -1,5 +1,5 @@
-import { a as SandboxFileSystem, F as FileStat, D as DirentEntry, S as Sandbox, d as SandboxCreateOptions } from './types-BMRzfELQ.cjs';
-import { R as RouterContext } from './types-YbL7JpEA.cjs';
+import { a as SandboxFileSystem, F as FileStat, D as DirentEntry, S as Sandbox, d as SandboxCreateOptions } from './types-ChAMwU3q.js';
+import { R as RouterContext } from './types-Bll19FZJ.js';
 
 /**
  * Ephemeral {@link SandboxFileSystem} backed by a {@link FileResolver}.
@@ -82,11 +82,11 @@ type TreeMutation<TMeta = FileEntryMetadata> = {
  */
 interface FileResolver<TCtx = unknown, TMeta = FileEntryMetadata> {
     resolveEntries(ctx: TCtx): Promise<FileEntry<TMeta>[]>;
-    readFile(id: string, ctx: TCtx): Promise<string>;
-    readFileBuffer(id: string, ctx: TCtx): Promise<Uint8Array>;
-    writeFile(id: string, content: string | Uint8Array, ctx: TCtx): Promise<void>;
+    readFile(id: string, ctx: TCtx, metadata: TMeta): Promise<string>;
+    readFileBuffer(id: string, ctx: TCtx, metadata: TMeta): Promise<Uint8Array>;
+    writeFile(id: string, content: string | Uint8Array, ctx: TCtx, metadata: TMeta): Promise<void>;
     createFile(path: string, content: string | Uint8Array, ctx: TCtx): Promise<FileEntry<TMeta>>;
-    deleteFile(id: string, ctx: TCtx): Promise<void>;
+    deleteFile(id: string, ctx: TCtx, metadata: TMeta): Promise<void>;
 }
 /**
  * Options for {@link VirtualSandboxProvider.create}.
@@ -122,45 +122,4 @@ interface VirtualSandboxContext<TCtx = unknown, TMeta = FileEntryMetadata> exten
     sandbox: VirtualSandbox<TCtx, TMeta>;
 }
 
-/**
- * Structural constraint: accepts any `AgentStateManager<T>` whose custom
- * state includes `fileTree: FileEntry<TMeta>[]`.
- */
-interface FileTreeAccessor<TMeta> {
-    get(key: "fileTree"): FileEntry<TMeta>[];
-}
-/**
- * Check whether any file in the tree has a `metadata.mimeType` that matches
- * the given pattern.
- *
- * Patterns:
- * - Exact: `"application/pdf"`
- * - Wildcard type: `"image/*"`
- *
- * Useful for conditionally enabling tools:
- *
- * ```ts
- * { enabled: hasFileWithMimeType(stateManager, "image/*") }
- * { enabled: hasFileWithMimeType(stateManager, ["image/*", "application/pdf"]) }
- * ```
- */
-declare function hasFileWithMimeType<TMeta>(stateManager: FileTreeAccessor<TMeta>, pattern: string | string[]): boolean;
-/**
- * Return all entries whose `metadata.mimeType` matches the given pattern.
- */
-declare function filesWithMimeType<TMeta>(stateManager: FileTreeAccessor<TMeta>, pattern: string): FileEntry<TMeta>[];
-/**
- * Check whether the tree contains a directory whose name matches the given
- * pattern. Directories are inferred from file paths.
- *
- * Patterns:
- * - Exact: `"src"`
- * - Glob with `*` wildcard: `"test*"`, `"*.generated"`
- *
- * ```ts
- * { enabled: hasDirectory(stateManager, "test*") }
- * ```
- */
-declare function hasDirectory<TMeta>(stateManager: FileTreeAccessor<TMeta>, pattern: string): boolean;
-
-export { type FileEntryMetadata as F, type TreeMutation as T, type VirtualSandboxCreateOptions as V, type FileResolver as a, type VirtualSandboxContext as b, type FileEntry as c, type VirtualSandbox as d, type FileTreeAccessor as e, type VirtualFileTree as f, VirtualSandboxFileSystem as g, type VirtualSandboxState as h, filesWithMimeType as i, hasDirectory as j, hasFileWithMimeType as k };
+export { type FileEntry as F, type TreeMutation as T, type VirtualSandboxCreateOptions as V, type FileEntryMetadata as a, type FileResolver as b, type VirtualSandboxContext as c, type VirtualSandbox as d, type VirtualFileTree as e, VirtualSandboxFileSystem as f, type VirtualSandboxState as g };