zeitlich 0.2.32 → 0.2.34

package/dist/index.d.cts

@@ -1,12 +1,12 @@
-import { B as BashArgs, F as FileEditArgs, G as GlobArgs, a as FileReadArgs, b as FileWriteArgs } from './workflow-BWKQcz9d.cjs';
-export { A as AskUserQuestionArgs, c as FileTreeAccessor, d as GrepArgs, O as ObservabilityHooks, R as ReadSkillArgs, S as SessionEndedEvent, e as SessionStartedEvent, f as SubagentArgs, T as TaskCreateArgs, g as TaskGetArgs, h as TaskListArgs, i as TaskUpdateArgs, j as ToolExecutedEvent, k as TurnCompletedEvent, W as WorkflowConfig, l as WorkflowInput, m as WorkflowSessionInput, Z as ZeitlichObservabilitySinks, n as applyVirtualTreeMutations, o as askUserQuestionTool, p as bashTool, q as composeHooks, r as createAgentStateManager, s as createAskUserQuestionHandler, t as createBashToolDescription, u as createObservabilityHooks, v as createReadSkillHandler, w as createReadSkillTool, x as createSession, y as createTaskCreateHandler, z as createTaskGetHandler, C as createTaskListHandler, D as createTaskUpdateHandler, E as createToolRouter, H as defineSubagent, I as defineSubagentWorkflow, J as defineTool, K as defineWorkflow, L as editTool, M as filesWithMimeType, N as formatVirtualFileTree, P as getShortId, Q as globTool, U as grepTool, V as hasDirectory, X as hasFileWithMimeType, Y as hasNoOtherToolCalls, _ as parseSkillFile, $ as proxyVirtualFsOps, a0 as readFileTool, a1 as taskCreateTool, a2 as taskGetTool, a3 as taskListTool, a4 as taskUpdateTool, a5 as writeFileTool } from './workflow-BWKQcz9d.cjs';
-import { R as RouterContext, d as ToolResultConfig, c as ActivityToolHandler, J as JsonValue, b as ToolHandlerResponse, B as BaseAgentState, e as RunAgentConfig, f as SkillProvider, g as SkillMetadata, h as Skill, F as FileEntryMetadata, i as FileResolver, V as VirtualFsContext, j as TreeMutation, k as PrefixedVirtualFsOps } from './types-Bpq5fDI5.cjs';
-export { l as AgentConfig, m as AgentFile, A as AgentResponse, n as AgentState, o as AgentStateManager, p as AgentStatus, q as AppendToolResultFn, r as FileEntry, H as Hooks, I as InferToolResults, s as JsonPrimitive, t as JsonSerializable, a as ModelInvoker, M as ModelInvokerConfig, u as ParsedToolCall, v as ParsedToolCallUnion, w as PostHumanMessageAppendHook, x as PostHumanMessageAppendHookContext, y as PostToolUseFailureHook, z as PostToolUseFailureHookContext, C as PostToolUseFailureHookResult, D as PostToolUseHook, E as PostToolUseHookContext, G as PreHumanMessageAppendHook, K as PreHumanMessageAppendHookContext, L as PreToolUseHook, N as PreToolUseHookContext, O as PreToolUseHookResult, P as PrefixedThreadOps, Q as ProcessToolCallsContext, U as RawToolCall, W as RunAgentActivity, X as SandboxInit, Y as SandboxShutdown, S as ScopedPrefix, Z as SerializableToolDefinition, _ as SessionConfig, $ as SessionEndHook, a0 as SessionEndHookContext, a1 as SessionExitReason, a2 as SessionResult, a3 as SessionStartHook, a4 as SessionStartHookContext, a5 as SubagentConfig, a6 as SubagentDefinition, a7 as SubagentFnResult, a8 as SubagentHandlerResponse, a9 as SubagentHooks, aa as SubagentSandboxConfig, ab as SubagentSandboxShutdown, ac as SubagentSessionInput, ad as SubagentWorkflow, ae as SubagentWorkflowInput, af as TaskStatus, ag as ThreadInit, T as ThreadOps, ah as TokenUsage, ai as ToolArgs, aj as ToolCallResult, ak as ToolCallResultUnion, al as ToolDefinition, am as ToolHandler, an as ToolHooks, ao as ToolMap, ap as ToolNames, aq as ToolResult, ar as ToolRouter, as as ToolRouterHooks, at as ToolWithHandler, au as VirtualFileSystem, av as VirtualFileTree, aw as VirtualFsOps, ax as VirtualFsState, ay as WorkflowTask, az as ZeitlichSession, aA as isTerminalStatus } from './types-Bpq5fDI5.cjs';
-import { S as Sandbox, a as SandboxFileSystem, d as SandboxCreateOptions, b as SandboxProvider, f as SandboxSnapshot, P as PrefixedSandboxOps, F as FileStat, D as DirentEntry, E as ExecResult } from './types-AujBIMMn.cjs';
-export { h as ExecOptions, c as SandboxCapabilities, e as SandboxCreateResult, i as SandboxNotFoundError, j as SandboxNotSupportedError, g as SandboxOps } from './types-AujBIMMn.cjs';
+import { B as BashArgs, F as FileEditArgs, G as GlobArgs, a as FileReadArgs, b as FileWriteArgs } from './workflow-hocXpLwg.cjs';
+export { A as AskUserQuestionArgs, c as FileTreeAccessor, d as GrepArgs, O as ObservabilityHooks, R as ReadSkillArgs, S as SessionEndedEvent, e as SessionStartedEvent, f as SubagentArgs, T as TaskCreateArgs, g as TaskGetArgs, h as TaskListArgs, i as TaskUpdateArgs, j as ToolExecutedEvent, k as TurnCompletedEvent, W as WorkflowConfig, l as WorkflowInput, m as WorkflowSessionInput, Z as ZeitlichObservabilitySinks, n as applyVirtualTreeMutations, o as askUserQuestionTool, p as bashTool, q as composeHooks, r as createAgentStateManager, s as createAskUserQuestionHandler, t as createBashToolDescription, u as createObservabilityHooks, v as createReadSkillHandler, w as createReadSkillTool, x as createSession, y as createTaskCreateHandler, z as createTaskGetHandler, C as createTaskListHandler, D as createTaskUpdateHandler, E as createToolRouter, H as defineSubagent, I as defineSubagentWorkflow, J as defineTool, K as defineWorkflow, L as editTool, M as filesWithMimeType, N as formatVirtualFileTree, P as getShortId, Q as globTool, U as grepTool, V as hasDirectory, X as hasFileWithMimeType, Y as hasNoOtherToolCalls, _ as parseSkillFile, $ as proxyRunAgent, a0 as proxyVirtualFsOps, a1 as readFileTool, a2 as taskCreateTool, a3 as taskGetTool, a4 as taskListTool, a5 as taskUpdateTool, a6 as writeFileTool } from './workflow-hocXpLwg.cjs';
+import { R as RouterContext, d as ToolResultConfig, c as ActivityToolHandler, J as JsonValue, b as ToolHandlerResponse, B as BaseAgentState, e as RunAgentConfig, f as SkillProvider, g as SkillMetadata, h as Skill, F as FileEntryMetadata, i as FileResolver, V as VirtualFsContext, j as TreeMutation, k as PrefixedVirtualFsOps } from './types-DlLajQcu.cjs';
+export { l as AgentConfig, m as AgentFile, A as AgentResponse, n as AgentState, o as AgentStateManager, p as AgentStatus, q as AppendToolResultFn, r as FileEntry, H as Hooks, I as InferToolResults, s as JsonPrimitive, t as JsonSerializable, a as ModelInvoker, M as ModelInvokerConfig, u as ParsedToolCall, v as ParsedToolCallUnion, w as PostHumanMessageAppendHook, x as PostHumanMessageAppendHookContext, y as PostToolUseFailureHook, z as PostToolUseFailureHookContext, C as PostToolUseFailureHookResult, D as PostToolUseHook, E as PostToolUseHookContext, G as PreHumanMessageAppendHook, K as PreHumanMessageAppendHookContext, L as PreToolUseHook, N as PreToolUseHookContext, O as PreToolUseHookResult, P as PrefixedThreadOps, Q as ProcessToolCallsContext, U as RawToolCall, W as RunAgentActivity, X as SandboxInit, Y as SandboxShutdown, S as ScopedPrefix, Z as SerializableToolDefinition, _ as SessionConfig, $ as SessionEndHook, a0 as SessionEndHookContext, a1 as SessionExitReason, a2 as SessionResult, a3 as SessionStartHook, a4 as SessionStartHookContext, a5 as SubagentConfig, a6 as SubagentDefinition, a7 as SubagentFnResult, a8 as SubagentHandlerResponse, a9 as SubagentHooks, aa as SubagentSandboxConfig, ab as SubagentSandboxShutdown, ac as SubagentSessionInput, ad as SubagentWorkflow, ae as SubagentWorkflowInput, af as TaskStatus, ag as ThreadInit, T as ThreadOps, ah as TokenUsage, ai as ToolArgs, aj as ToolCallResult, ak as ToolCallResultUnion, al as ToolDefinition, am as ToolHandler, an as ToolHooks, ao as ToolMap, ap as ToolNames, aq as ToolResult, ar as ToolRouter, as as ToolRouterHooks, at as ToolWithHandler, au as VirtualFileSystem, av as VirtualFileTree, aw as VirtualFsOps, ax as VirtualFsState, ay as WorkflowTask, az as ZeitlichSession, aA as isTerminalStatus } from './types-DlLajQcu.cjs';
+import { S as Sandbox, a as SandboxFileSystem, d as SandboxCreateOptions, b as SandboxProvider, f as SandboxSnapshot, P as PrefixedSandboxOps, F as FileStat, D as DirentEntry, E as ExecResult } from './types-DxCpFNv_.cjs';
+export { h as ExecOptions, c as SandboxCapabilities, e as SandboxCreateResult, i as SandboxNotFoundError, j as SandboxNotSupportedError, g as SandboxOps } from './types-DxCpFNv_.cjs';
 import { WorkflowClient } from '@temporalio/client';
-import { a as ThreadManagerConfig, B as BaseThreadManager } from './types-NJDyMyUx.cjs';
-export { P as ProviderThreadManager } from './types-NJDyMyUx.cjs';
+import { a as ThreadManagerConfig, B as BaseThreadManager } from './types-DPAZ3KCs.cjs';
+export { P as ProviderThreadManager } from './types-DPAZ3KCs.cjs';
 import 'zod';
 import '@temporalio/workflow';
 import '@temporalio/common';
@@ -97,27 +97,42 @@ declare function withSandbox<TArgs, TResult, TSandbox extends Sandbox = Sandbox,
     sandboxId: string;
 }) => Promise<ToolHandlerResponse<TResult, TToolResponse>>): ActivityToolHandler<TArgs, TResult | null, RouterContext, TToolResponse | string>;
 
+/**
+ * Safely retrieve Temporal activity heartbeat and cancellation signal.
+ * Returns empty object when called outside a Temporal activity (e.g. tests).
+ */
+declare function getActivityContext(): {
+    heartbeat?: () => void;
+    signal?: AbortSignal;
+};
 /**
  * Query the parent workflow's state from within an activity.
  * Resolves the workflow handle from the current activity context.
  */
 declare function queryParentWorkflowState<T>(client: WorkflowClient): Promise<T>;
 /**
- * Wraps a handler into a `RunAgentActivity` by auto-fetching the parent
- * workflow's agent state before each invocation.
+ * Wraps a handler into a scope-prefixed `RunAgentActivity` by auto-fetching
+ * the parent workflow's agent state before each invocation.
+ *
+ * Returns a `Record` with a single key `run<Scope>` so it can be spread
+ * into the activities object alongside adapter activities.
+ *
+ * @param scope - Workflow scope used to derive the activity name.
+ *   `"myAgentWorkflow"` produces `{ runMyAgentWorkflow: fn }`.
  *
  * @example
  * ```typescript
  * import { createRunAgentActivity } from 'zeitlich';
- * import { createLangChainModelInvoker } from 'zeitlich/adapters/thread/langchain';
  *
- * const invoker = createLangChainModelInvoker({ redis, model });
- * return { runAgent: createRunAgentActivity(client, invoker) };
+ * return {
+ *   ...adapter.createActivities("myAgentWorkflow"),
+ *   ...createRunAgentActivity(client, adapter.invoker, "myAgentWorkflow"),
+ * };
  * ```
  */
 declare function createRunAgentActivity<R, S extends BaseAgentState = BaseAgentState>(client: WorkflowClient, handler: (config: RunAgentConfig & {
     state: S;
-}) => Promise<R>): (config: RunAgentConfig) => Promise<R>;
+}) => Promise<R>, scope: string): Record<string, (config: RunAgentConfig) => Promise<R>>;
 /**
  * Context injected into tool handlers created via {@link withParentWorkflowState}.
  */
@@ -282,6 +297,7 @@ declare class SandboxManager<TOptions extends SandboxCreateOptions = SandboxCrea
     getSandbox(id: string): Promise<TSandbox>;
     destroy(id: string): Promise<void>;
     pause(id: string, ttlSeconds?: number): Promise<void>;
+    resume(id: string): Promise<void>;
     snapshot(id: string): Promise<SandboxSnapshot>;
     restore(snapshot: SandboxSnapshot): Promise<string>;
     fork(sandboxId: string): Promise<string>;
@@ -401,7 +417,7 @@ declare function withVirtualFs<TArgs, TResult, TCtx, TMeta = FileEntryMetadata,
  * const activities = {
  *   ...createVirtualFsActivities(resolver, "CodingAgent"),
  * };
- * // registers: codingAgentResolveFileTree
+ * // registers: virtualFsCodingAgentResolveFileTree
  * ```
  */
 declare function createVirtualFsActivities<S extends string, TCtx = unknown, TMeta = FileEntryMetadata>(resolver: FileResolver<TCtx, TMeta>, scope: S): PrefixedVirtualFsOps<S, TCtx, TMeta>;
@@ -496,4 +512,4 @@ declare const toTree: (fs: SandboxFileSystem, opts?: {
     sort?: boolean;
 }) => Promise<string>;
 
-export { ActivityToolHandler, type AgentStateContext, BaseAgentState, BaseThreadManager, BashArgs, ExecResult, FileEditArgs, FileEntryMetadata, FileReadArgs, FileResolver, FileSystemSkillProvider, FileWriteArgs, GlobArgs, JsonValue, NodeFsSandboxFileSystem, type PreCreateHookResult, PrefixedSandboxOps, PrefixedVirtualFsOps, RouterContext, RunAgentConfig, Sandbox, type SandboxContext, SandboxCreateOptions, DirentEntry as SandboxDirentEntry, FileStat as SandboxFileStat, SandboxFileSystem, SandboxManager, type SandboxManagerHooks, SandboxProvider, SandboxSnapshot, Skill, SkillMetadata, SkillProvider, ThreadManagerConfig, ToolHandlerResponse, ToolResultConfig, TreeMutation, VirtualFsContext, bashHandler, createRunAgentActivity, createThreadManager, createVirtualFsActivities, editHandler, globHandler, queryParentWorkflowState, readFileHandler, toTree, withAutoAppend, withParentWorkflowState, withSandbox, withVirtualFs, writeFileHandler };
+export { ActivityToolHandler, type AgentStateContext, BaseAgentState, BaseThreadManager, BashArgs, ExecResult, FileEditArgs, FileEntryMetadata, FileReadArgs, FileResolver, FileSystemSkillProvider, FileWriteArgs, GlobArgs, JsonValue, NodeFsSandboxFileSystem, type PreCreateHookResult, PrefixedSandboxOps, PrefixedVirtualFsOps, RouterContext, RunAgentConfig, Sandbox, type SandboxContext, SandboxCreateOptions, DirentEntry as SandboxDirentEntry, FileStat as SandboxFileStat, SandboxFileSystem, SandboxManager, type SandboxManagerHooks, SandboxProvider, SandboxSnapshot, Skill, SkillMetadata, SkillProvider, ThreadManagerConfig, ToolHandlerResponse, ToolResultConfig, TreeMutation, VirtualFsContext, bashHandler, createRunAgentActivity, createThreadManager, createVirtualFsActivities, editHandler, getActivityContext, globHandler, queryParentWorkflowState, readFileHandler, toTree, withAutoAppend, withParentWorkflowState, withSandbox, withVirtualFs, writeFileHandler };

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import { B as BashArgs, F as FileEditArgs, G as GlobArgs, a as FileReadArgs, b as FileWriteArgs } from './workflow-D8wK7TJY.js';
-export { A as AskUserQuestionArgs, c as FileTreeAccessor, d as GrepArgs, O as ObservabilityHooks, R as ReadSkillArgs, S as SessionEndedEvent, e as SessionStartedEvent, f as SubagentArgs, T as TaskCreateArgs, g as TaskGetArgs, h as TaskListArgs, i as TaskUpdateArgs, j as ToolExecutedEvent, k as TurnCompletedEvent, W as WorkflowConfig, l as WorkflowInput, m as WorkflowSessionInput, Z as ZeitlichObservabilitySinks, n as applyVirtualTreeMutations, o as askUserQuestionTool, p as bashTool, q as composeHooks, r as createAgentStateManager, s as createAskUserQuestionHandler, t as createBashToolDescription, u as createObservabilityHooks, v as createReadSkillHandler, w as createReadSkillTool, x as createSession, y as createTaskCreateHandler, z as createTaskGetHandler, C as createTaskListHandler, D as createTaskUpdateHandler, E as createToolRouter, H as defineSubagent, I as defineSubagentWorkflow, J as defineTool, K as defineWorkflow, L as editTool, M as filesWithMimeType, N as formatVirtualFileTree, P as getShortId, Q as globTool, U as grepTool, V as hasDirectory, X as hasFileWithMimeType, Y as hasNoOtherToolCalls, _ as parseSkillFile, $ as proxyVirtualFsOps, a0 as readFileTool, a1 as taskCreateTool, a2 as taskGetTool, a3 as taskListTool, a4 as taskUpdateTool, a5 as writeFileTool } from './workflow-D8wK7TJY.js';
-import { R as RouterContext, d as ToolResultConfig, c as ActivityToolHandler, J as JsonValue, b as ToolHandlerResponse, B as BaseAgentState, e as RunAgentConfig, f as SkillProvider, g as SkillMetadata, h as Skill, F as FileEntryMetadata, i as FileResolver, V as VirtualFsContext, j as TreeMutation, k as PrefixedVirtualFsOps } from './types-CheCTLeV.js';
-export { l as AgentConfig, m as AgentFile, A as AgentResponse, n as AgentState, o as AgentStateManager, p as AgentStatus, q as AppendToolResultFn, r as FileEntry, H as Hooks, I as InferToolResults, s as JsonPrimitive, t as JsonSerializable, a as ModelInvoker, M as ModelInvokerConfig, u as ParsedToolCall, v as ParsedToolCallUnion, w as PostHumanMessageAppendHook, x as PostHumanMessageAppendHookContext, y as PostToolUseFailureHook, z as PostToolUseFailureHookContext, C as PostToolUseFailureHookResult, D as PostToolUseHook, E as PostToolUseHookContext, G as PreHumanMessageAppendHook, K as PreHumanMessageAppendHookContext, L as PreToolUseHook, N as PreToolUseHookContext, O as PreToolUseHookResult, P as PrefixedThreadOps, Q as ProcessToolCallsContext, U as RawToolCall, W as RunAgentActivity, X as SandboxInit, Y as SandboxShutdown, S as ScopedPrefix, Z as SerializableToolDefinition, _ as SessionConfig, $ as SessionEndHook, a0 as SessionEndHookContext, a1 as SessionExitReason, a2 as SessionResult, a3 as SessionStartHook, a4 as SessionStartHookContext, a5 as SubagentConfig, a6 as SubagentDefinition, a7 as SubagentFnResult, a8 as SubagentHandlerResponse, a9 as SubagentHooks, aa as SubagentSandboxConfig, ab as SubagentSandboxShutdown, ac as SubagentSessionInput, ad as SubagentWorkflow, ae as SubagentWorkflowInput, af as TaskStatus, ag as ThreadInit, T as ThreadOps, ah as TokenUsage, ai as ToolArgs, aj as ToolCallResult, ak as ToolCallResultUnion, al as ToolDefinition, am as ToolHandler, an as ToolHooks, ao as ToolMap, ap as ToolNames, aq as ToolResult, ar as ToolRouter, as as ToolRouterHooks, at as ToolWithHandler, au as VirtualFileSystem, av as VirtualFileTree, aw as VirtualFsOps, ax as VirtualFsState, ay as WorkflowTask, az as ZeitlichSession, aA as isTerminalStatus } from './types-CheCTLeV.js';
-import { S as Sandbox, a as SandboxFileSystem, d as SandboxCreateOptions, b as SandboxProvider, f as SandboxSnapshot, P as PrefixedSandboxOps, F as FileStat, D as DirentEntry, E as ExecResult } from './types-AujBIMMn.js';
-export { h as ExecOptions, c as SandboxCapabilities, e as SandboxCreateResult, i as SandboxNotFoundError, j as SandboxNotSupportedError, g as SandboxOps } from './types-AujBIMMn.js';
+import { B as BashArgs, F as FileEditArgs, G as GlobArgs, a as FileReadArgs, b as FileWriteArgs } from './workflow-_ZGcacCK.js';
+export { A as AskUserQuestionArgs, c as FileTreeAccessor, d as GrepArgs, O as ObservabilityHooks, R as ReadSkillArgs, S as SessionEndedEvent, e as SessionStartedEvent, f as SubagentArgs, T as TaskCreateArgs, g as TaskGetArgs, h as TaskListArgs, i as TaskUpdateArgs, j as ToolExecutedEvent, k as TurnCompletedEvent, W as WorkflowConfig, l as WorkflowInput, m as WorkflowSessionInput, Z as ZeitlichObservabilitySinks, n as applyVirtualTreeMutations, o as askUserQuestionTool, p as bashTool, q as composeHooks, r as createAgentStateManager, s as createAskUserQuestionHandler, t as createBashToolDescription, u as createObservabilityHooks, v as createReadSkillHandler, w as createReadSkillTool, x as createSession, y as createTaskCreateHandler, z as createTaskGetHandler, C as createTaskListHandler, D as createTaskUpdateHandler, E as createToolRouter, H as defineSubagent, I as defineSubagentWorkflow, J as defineTool, K as defineWorkflow, L as editTool, M as filesWithMimeType, N as formatVirtualFileTree, P as getShortId, Q as globTool, U as grepTool, V as hasDirectory, X as hasFileWithMimeType, Y as hasNoOtherToolCalls, _ as parseSkillFile, $ as proxyRunAgent, a0 as proxyVirtualFsOps, a1 as readFileTool, a2 as taskCreateTool, a3 as taskGetTool, a4 as taskListTool, a5 as taskUpdateTool, a6 as writeFileTool } from './workflow-_ZGcacCK.js';
+import { R as RouterContext, d as ToolResultConfig, c as ActivityToolHandler, J as JsonValue, b as ToolHandlerResponse, B as BaseAgentState, e as RunAgentConfig, f as SkillProvider, g as SkillMetadata, h as Skill, F as FileEntryMetadata, i as FileResolver, V as VirtualFsContext, j as TreeMutation, k as PrefixedVirtualFsOps } from './types-BGLW5Zyj.js';
+export { l as AgentConfig, m as AgentFile, A as AgentResponse, n as AgentState, o as AgentStateManager, p as AgentStatus, q as AppendToolResultFn, r as FileEntry, H as Hooks, I as InferToolResults, s as JsonPrimitive, t as JsonSerializable, a as ModelInvoker, M as ModelInvokerConfig, u as ParsedToolCall, v as ParsedToolCallUnion, w as PostHumanMessageAppendHook, x as PostHumanMessageAppendHookContext, y as PostToolUseFailureHook, z as PostToolUseFailureHookContext, C as PostToolUseFailureHookResult, D as PostToolUseHook, E as PostToolUseHookContext, G as PreHumanMessageAppendHook, K as PreHumanMessageAppendHookContext, L as PreToolUseHook, N as PreToolUseHookContext, O as PreToolUseHookResult, P as PrefixedThreadOps, Q as ProcessToolCallsContext, U as RawToolCall, W as RunAgentActivity, X as SandboxInit, Y as SandboxShutdown, S as ScopedPrefix, Z as SerializableToolDefinition, _ as SessionConfig, $ as SessionEndHook, a0 as SessionEndHookContext, a1 as SessionExitReason, a2 as SessionResult, a3 as SessionStartHook, a4 as SessionStartHookContext, a5 as SubagentConfig, a6 as SubagentDefinition, a7 as SubagentFnResult, a8 as SubagentHandlerResponse, a9 as SubagentHooks, aa as SubagentSandboxConfig, ab as SubagentSandboxShutdown, ac as SubagentSessionInput, ad as SubagentWorkflow, ae as SubagentWorkflowInput, af as TaskStatus, ag as ThreadInit, T as ThreadOps, ah as TokenUsage, ai as ToolArgs, aj as ToolCallResult, ak as ToolCallResultUnion, al as ToolDefinition, am as ToolHandler, an as ToolHooks, ao as ToolMap, ap as ToolNames, aq as ToolResult, ar as ToolRouter, as as ToolRouterHooks, at as ToolWithHandler, au as VirtualFileSystem, av as VirtualFileTree, aw as VirtualFsOps, ax as VirtualFsState, ay as WorkflowTask, az as ZeitlichSession, aA as isTerminalStatus } from './types-BGLW5Zyj.js';
+import { S as Sandbox, a as SandboxFileSystem, d as SandboxCreateOptions, b as SandboxProvider, f as SandboxSnapshot, P as PrefixedSandboxOps, F as FileStat, D as DirentEntry, E as ExecResult } from './types-DxCpFNv_.js';
+export { h as ExecOptions, c as SandboxCapabilities, e as SandboxCreateResult, i as SandboxNotFoundError, j as SandboxNotSupportedError, g as SandboxOps } from './types-DxCpFNv_.js';
 import { WorkflowClient } from '@temporalio/client';
-import { a as ThreadManagerConfig, B as BaseThreadManager } from './types-BxiT8w9d.js';
-export { P as ProviderThreadManager } from './types-BxiT8w9d.js';
+import { a as ThreadManagerConfig, B as BaseThreadManager } from './types-BVUmLYpj.js';
+export { P as ProviderThreadManager } from './types-BVUmLYpj.js';
 import 'zod';
 import '@temporalio/workflow';
 import '@temporalio/common';
@@ -97,27 +97,42 @@ declare function withSandbox<TArgs, TResult, TSandbox extends Sandbox = Sandbox,
     sandboxId: string;
 }) => Promise<ToolHandlerResponse<TResult, TToolResponse>>): ActivityToolHandler<TArgs, TResult | null, RouterContext, TToolResponse | string>;
 
+/**
+ * Safely retrieve Temporal activity heartbeat and cancellation signal.
+ * Returns empty object when called outside a Temporal activity (e.g. tests).
+ */
+declare function getActivityContext(): {
+    heartbeat?: () => void;
+    signal?: AbortSignal;
+};
 /**
  * Query the parent workflow's state from within an activity.
  * Resolves the workflow handle from the current activity context.
  */
 declare function queryParentWorkflowState<T>(client: WorkflowClient): Promise<T>;
 /**
- * Wraps a handler into a `RunAgentActivity` by auto-fetching the parent
- * workflow's agent state before each invocation.
+ * Wraps a handler into a scope-prefixed `RunAgentActivity` by auto-fetching
+ * the parent workflow's agent state before each invocation.
+ *
+ * Returns a `Record` with a single key `run<Scope>` so it can be spread
+ * into the activities object alongside adapter activities.
+ *
+ * @param scope - Workflow scope used to derive the activity name.
+ *   `"myAgentWorkflow"` produces `{ runMyAgentWorkflow: fn }`.
  *
  * @example
  * ```typescript
  * import { createRunAgentActivity } from 'zeitlich';
- * import { createLangChainModelInvoker } from 'zeitlich/adapters/thread/langchain';
  *
- * const invoker = createLangChainModelInvoker({ redis, model });
- * return { runAgent: createRunAgentActivity(client, invoker) };
+ * return {
+ *   ...adapter.createActivities("myAgentWorkflow"),
+ *   ...createRunAgentActivity(client, adapter.invoker, "myAgentWorkflow"),
+ * };
  * ```
  */
 declare function createRunAgentActivity<R, S extends BaseAgentState = BaseAgentState>(client: WorkflowClient, handler: (config: RunAgentConfig & {
     state: S;
-}) => Promise<R>): (config: RunAgentConfig) => Promise<R>;
+}) => Promise<R>, scope: string): Record<string, (config: RunAgentConfig) => Promise<R>>;
 /**
  * Context injected into tool handlers created via {@link withParentWorkflowState}.
  */
@@ -282,6 +297,7 @@ declare class SandboxManager<TOptions extends SandboxCreateOptions = SandboxCrea
     getSandbox(id: string): Promise<TSandbox>;
     destroy(id: string): Promise<void>;
     pause(id: string, ttlSeconds?: number): Promise<void>;
+    resume(id: string): Promise<void>;
     snapshot(id: string): Promise<SandboxSnapshot>;
     restore(snapshot: SandboxSnapshot): Promise<string>;
     fork(sandboxId: string): Promise<string>;
@@ -401,7 +417,7 @@ declare function withVirtualFs<TArgs, TResult, TCtx, TMeta = FileEntryMetadata,
  * const activities = {
  *   ...createVirtualFsActivities(resolver, "CodingAgent"),
  * };
- * // registers: codingAgentResolveFileTree
+ * // registers: virtualFsCodingAgentResolveFileTree
  * ```
  */
 declare function createVirtualFsActivities<S extends string, TCtx = unknown, TMeta = FileEntryMetadata>(resolver: FileResolver<TCtx, TMeta>, scope: S): PrefixedVirtualFsOps<S, TCtx, TMeta>;
@@ -496,4 +512,4 @@ declare const toTree: (fs: SandboxFileSystem, opts?: {
     sort?: boolean;
 }) => Promise<string>;
 
-export { ActivityToolHandler, type AgentStateContext, BaseAgentState, BaseThreadManager, BashArgs, ExecResult, FileEditArgs, FileEntryMetadata, FileReadArgs, FileResolver, FileSystemSkillProvider, FileWriteArgs, GlobArgs, JsonValue, NodeFsSandboxFileSystem, type PreCreateHookResult, PrefixedSandboxOps, PrefixedVirtualFsOps, RouterContext, RunAgentConfig, Sandbox, type SandboxContext, SandboxCreateOptions, DirentEntry as SandboxDirentEntry, FileStat as SandboxFileStat, SandboxFileSystem, SandboxManager, type SandboxManagerHooks, SandboxProvider, SandboxSnapshot, Skill, SkillMetadata, SkillProvider, ThreadManagerConfig, ToolHandlerResponse, ToolResultConfig, TreeMutation, VirtualFsContext, bashHandler, createRunAgentActivity, createThreadManager, createVirtualFsActivities, editHandler, globHandler, queryParentWorkflowState, readFileHandler, toTree, withAutoAppend, withParentWorkflowState, withSandbox, withVirtualFs, writeFileHandler };
+export { ActivityToolHandler, type AgentStateContext, BaseAgentState, BaseThreadManager, BashArgs, ExecResult, FileEditArgs, FileEntryMetadata, FileReadArgs, FileResolver, FileSystemSkillProvider, FileWriteArgs, GlobArgs, JsonValue, NodeFsSandboxFileSystem, type PreCreateHookResult, PrefixedSandboxOps, PrefixedVirtualFsOps, RouterContext, RunAgentConfig, Sandbox, type SandboxContext, SandboxCreateOptions, DirentEntry as SandboxDirentEntry, FileStat as SandboxFileStat, SandboxFileSystem, SandboxManager, type SandboxManagerHooks, SandboxProvider, SandboxSnapshot, Skill, SkillMetadata, SkillProvider, ThreadManagerConfig, ToolHandlerResponse, ToolResultConfig, TreeMutation, VirtualFsContext, bashHandler, createRunAgentActivity, createThreadManager, createVirtualFsActivities, editHandler, getActivityContext, globHandler, queryParentWorkflowState, readFileHandler, toTree, withAutoAppend, withParentWorkflowState, withSandbox, withVirtualFs, writeFileHandler };

package/dist/index.js

@@ -390,23 +390,50 @@ function createSubagentTool(subagents) {
   };
 }
 var childResultSignal = defineSignal("childResult");
+var childSandboxReadySignal = defineSignal("childSandboxReady");
 var destroySandboxSignal = defineSignal("destroySandbox");
 
 // src/lib/subagent/handler.ts
 function resolveSandboxConfig(config) {
-  if (!config || config === "none") return { source: "none" };
-  if (config === "inherit") return { source: "inherit" };
-  if (config === "own") return { source: "own" };
-  return { source: "own", shutdown: config.shutdown };
+  if (!config || config === "none") {
+    return { source: "none", init: "per-call", continuation: "fork" };
+  }
+  if (config.source === "inherit") {
+    return {
+      source: "inherit",
+      init: "per-call",
+      continuation: config.continuation,
+      shutdown: config.shutdown
+    };
+  }
+  return {
+    source: "own",
+    init: config.init ?? "per-call",
+    continuation: config.continuation,
+    shutdown: config.shutdown
+  };
 }
 function createSubagentHandler(subagents) {
   const { taskQueue: parentTaskQueue } = workflowInfo();
   const childResults = /* @__PURE__ */ new Map();
   const pendingDestroys = /* @__PURE__ */ new Map();
   const threadSandboxes = /* @__PURE__ */ new Map();
+  const persistentSandboxes = /* @__PURE__ */ new Map();
+  const persistentSandboxCreating = /* @__PURE__ */ new Set();
+  const lazyCreatorAgent = /* @__PURE__ */ new Map();
   setHandler(childResultSignal, ({ childWorkflowId, result }) => {
     childResults.set(childWorkflowId, result);
   });
+  setHandler(
+    childSandboxReadySignal,
+    ({ childWorkflowId, sandboxId }) => {
+      const agentName = lazyCreatorAgent.get(childWorkflowId);
+      if (agentName && !persistentSandboxes.has(agentName)) {
+        persistentSandboxes.set(agentName, sandboxId);
+        lazyCreatorAgent.delete(childWorkflowId);
+      }
+    }
+  );
   const handler = async (args, context) => {
     const config = subagents.find((s) => s.agentName === args.subagent);
     if (!config) {
@@ -433,21 +460,48 @@ function createSubagentHandler(subagents) {
       };
     }
     let sandbox;
+    let sandboxShutdownOverride;
+    let isLazyCreator = false;
     if (sandboxCfg.source === "inherit" && parentSandboxId) {
-      sandbox = {
-        mode: "inherit",
-        sandboxId: parentSandboxId
-      };
+      if (sandboxCfg.continuation === "fork") {
+        sandbox = { mode: "fork", sandboxId: parentSandboxId };
+      } else {
+        sandbox = { mode: "inherit", sandboxId: parentSandboxId };
+      }
     } else if (sandboxCfg.source === "own") {
-      const prevSbId = continuationThreadId ? threadSandboxes.get(continuationThreadId) : void 0;
-      if (prevSbId) {
-        sandbox = { mode: "fork", sandboxId: prevSbId };
+      const isLazy = sandboxCfg.init === "once";
+      let baseSandboxId;
+      if (isLazy) {
+        baseSandboxId = persistentSandboxes.get(config.agentName);
+        if (!baseSandboxId) {
+          if (persistentSandboxCreating.has(config.agentName)) {
+            await condition(() => persistentSandboxes.has(config.agentName));
+            baseSandboxId = persistentSandboxes.get(config.agentName);
+          } else {
+            persistentSandboxCreating.add(config.agentName);
+            isLazyCreator = true;
+          }
+        }
+      } else if (continuationThreadId) {
+        baseSandboxId = threadSandboxes.get(continuationThreadId);
+      }
+      if (baseSandboxId) {
+        sandbox = {
+          mode: sandboxCfg.continuation === "continue" ? "continue" : "fork",
+          sandboxId: baseSandboxId
+        };
+      }
+      const userShutdown = sandboxCfg.shutdown;
+      const alreadySurvives = userShutdown === "pause-until-parent-close" || userShutdown === "keep-until-parent-close" || userShutdown === "pause" || userShutdown === "keep";
+      const mustSurvive = isLazyCreator || sandboxCfg.continuation === "continue" || isLazy && sandboxCfg.continuation === "fork";
+      if (mustSurvive && !alreadySurvives) {
+        sandboxShutdownOverride = isLazyCreator ? "pause-until-parent-close" : "pause";
       }
     }
     const workflowInput = {
       ...thread && { thread },
       ...sandbox && { sandbox },
-      ...sandboxCfg.shutdown && { sandboxShutdown: sandboxCfg.shutdown }
+      sandboxShutdown: sandboxShutdownOverride ?? sandboxCfg.shutdown ?? void 0
     };
     const resolvedContext = config.context === void 0 ? void 0 : typeof config.context === "function" ? config.context() : config.context;
     const childOpts = {
@@ -455,6 +509,9 @@ function createSubagentHandler(subagents) {
       args: resolvedContext === void 0 ? [args.prompt, workflowInput] : [args.prompt, workflowInput, resolvedContext],
       taskQueue: config.taskQueue ?? parentTaskQueue
     };
+    if (isLazyCreator) {
+      lazyCreatorAgent.set(childWorkflowId, config.agentName);
+    }
     log.info("subagent spawned", {
       subagent: config.agentName,
       childWorkflowId,
@@ -462,10 +519,10 @@ function createSubagentHandler(subagents) {
       sandboxSource: sandboxCfg.source
     });
     const childHandle = await startChild(config.workflow, childOpts);
-    const effectiveShutdown = sandboxCfg.shutdown ?? "destroy";
-    const shouldDeferDestroy = effectiveShutdown === "pause-until-parent-close" && (sandboxCfg.source === "own" || allowsContinuation && sandboxCfg.source !== "inherit");
-    if (shouldDeferDestroy) {
-      pendingDestroys.set(childWorkflowId, childHandle);
+    const effectiveShutdown = sandboxShutdownOverride ?? sandboxCfg.shutdown ?? "destroy";
+    if (effectiveShutdown === "pause-until-parent-close" || effectiveShutdown === "keep-until-parent-close") {
+      const key = isLazyCreator ? `persistent:${config.agentName}` : childWorkflowId;
+      pendingDestroys.set(key, childHandle);
     }
     await Promise.race([
       condition(() => childResults.has(childWorkflowId)),
@@ -499,8 +556,16 @@ function createSubagentHandler(subagents) {
       sandboxId: childSandboxId,
       metadata
     } = childResult;
-    if (allowsContinuation && childSandboxId && childThreadId) {
-      threadSandboxes.set(childThreadId, childSandboxId);
+    if (childSandboxId) {
+      if (sandboxCfg.source === "own" && sandboxCfg.init === "once" && !persistentSandboxes.has(config.agentName)) {
+        persistentSandboxes.set(config.agentName, childSandboxId);
+      } else if (allowsContinuation && childThreadId) {
+        threadSandboxes.set(childThreadId, childSandboxId);
+      }
+    }
+    if (isLazyCreator) {
+      persistentSandboxCreating.delete(config.agentName);
+      lazyCreatorAgent.delete(childWorkflowId);
     }
     if (!toolResponse) {
       return {
@@ -706,6 +771,7 @@ async function createSession({
   thread: threadInit,
   sandbox: sandboxInit,
   sandboxShutdown = "destroy",
+  onSandboxReady,
   virtualFs: virtualFsConfig,
   virtualFsOps
 }) {
@@ -808,6 +874,9 @@ async function createSession({
           });
         }
         sandboxId = sandboxInit.sandboxId;
+        if (sandboxShutdown === "pause-until-parent-close") {
+          await sandboxOps.resumeSandbox(sandboxId);
+        }
         sandboxOwned = true;
       } else if (sandboxMode === "fork") {
         if (!sandboxOps) {
@@ -830,6 +899,9 @@ async function createSession({
           sandboxOwned = true;
         }
       }
+      if (sandboxId && onSandboxReady) {
+        onSandboxReady(sandboxId);
+      }
       if (virtualFsConfig) {
         if (!virtualFsOps) {
           throw ApplicationFailure.create({
@@ -1299,39 +1371,45 @@ function defineSubagent(definition, overrides) {
 function defineSubagentWorkflow(config, fn) {
   const workflow = async (prompt, workflowInput, context) => {
     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 = {
       agentName: config.name,
       sandboxShutdown: effectiveShutdown,
       ...workflowInput.thread && { thread: workflowInput.thread },
-      ...workflowInput.sandbox && { sandbox: workflowInput.sandbox }
+      ...workflowInput.sandbox && { sandbox: workflowInput.sandbox },
+      onSandboxReady: (sandboxId) => {
+        void parentHandle.signal(childSandboxReadySignal, {
+          childWorkflowId: workflowInfo().workflowId,
+          sandboxId
+        });
+      }
     };
     const { destroySandbox, ...result } = await fn(
       prompt,
       sessionInput,
       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
@@ -1410,6 +1488,23 @@ function composeHooks(...fns) {
     return lastResult;
   };
 }
+function proxyRunAgent(scope, options) {
+  const resolvedScope = scope ?? workflowInfo().workflowType;
+  const name = `run${resolvedScope.charAt(0).toUpperCase()}${resolvedScope.slice(1)}`;
+  const acts = proxyActivities(
+    options ?? {
+      startToCloseTimeout: "10m",
+      heartbeatTimeout: "1m",
+      retry: {
+        maximumAttempts: 3,
+        initialInterval: "10s",
+        maximumInterval: "2m",
+        backoffCoefficient: 3
+      }
+    }
+  );
+  return acts[name];
+}
 var SandboxNotSupportedError = class extends ApplicationFailure$1 {
   constructor(operation) {
     super(
@@ -2166,6 +2261,14 @@ function createThreadManager(config) {
     }
   };
 }
+function getActivityContext() {
+  try {
+    const ctx = Context.current();
+    return { heartbeat: () => ctx.heartbeat(), signal: ctx.cancellationSignal };
+  } catch {
+    return {};
+  }
+}
 async function queryParentWorkflowState(client) {
   const { workflowExecution } = Context.current().info;
   const handle = client.getHandle(
@@ -2174,10 +2277,13 @@ async function queryParentWorkflowState(client) {
   );
   return handle.query("getAgentState");
 }
-function createRunAgentActivity(client, handler) {
-  return async (config) => {
-    const state = await queryParentWorkflowState(client);
-    return handler({ ...config, state });
+function createRunAgentActivity(client, handler, scope) {
+  const name = `run${scope.charAt(0).toUpperCase()}${scope.slice(1)}`;
+  return {
+    [name]: async (config) => {
+      const state = await queryParentWorkflowState(client);
+      return handler({ ...config, state });
+    }
   };
 }
 function withParentWorkflowState(client, handler) {
@@ -2234,6 +2340,9 @@ var SandboxManager = class {
   async pause(id, ttlSeconds) {
     await this.provider.pause(id, ttlSeconds);
   }
+  async resume(id) {
+    await this.provider.resume(id);
+  }
   async snapshot(id) {
     return this.provider.snapshot(id);
   }
@@ -2277,6 +2386,9 @@ var SandboxManager = class {
       pauseSandbox: async (sandboxId, ttlSeconds) => {
         await this.pause(sandboxId, ttlSeconds);
       },
+      resumeSandbox: async (sandboxId) => {
+        await this.resume(sandboxId);
+      },
       snapshotSandbox: async (sandboxId) => {
         return this.snapshot(sandboxId);
       },
@@ -2948,6 +3060,6 @@ var toTree = async (fs, opts = {}) => {
   return base + subtree;
 };
 
-export { FileSystemSkillProvider, NodeFsSandboxFileSystem, SandboxManager, SandboxNotFoundError, SandboxNotSupportedError, VirtualFileSystem, applyVirtualTreeMutations, askUserQuestionTool, bashHandler, bashTool, composeHooks, createAgentStateManager, createAskUserQuestionHandler, createBashToolDescription, createObservabilityHooks, createReadSkillHandler, createReadSkillTool, createRunAgentActivity, createSession, createTaskCreateHandler, createTaskGetHandler, createTaskListHandler, createTaskUpdateHandler, createThreadManager, createToolRouter, createVirtualFsActivities, defineSubagent, defineSubagentWorkflow, defineTool, defineWorkflow, editHandler, editTool, filesWithMimeType, formatVirtualFileTree, getShortId, globHandler, globTool, grepTool, hasDirectory, hasFileWithMimeType, hasNoOtherToolCalls, isTerminalStatus, parseSkillFile, proxyVirtualFsOps, queryParentWorkflowState, readFileHandler, readFileTool, taskCreateTool, taskGetTool, taskListTool, taskUpdateTool, toTree, withAutoAppend, withParentWorkflowState, withSandbox, withVirtualFs, writeFileHandler, writeFileTool };
+export { FileSystemSkillProvider, NodeFsSandboxFileSystem, SandboxManager, SandboxNotFoundError, SandboxNotSupportedError, VirtualFileSystem, applyVirtualTreeMutations, askUserQuestionTool, bashHandler, bashTool, composeHooks, createAgentStateManager, createAskUserQuestionHandler, createBashToolDescription, createObservabilityHooks, createReadSkillHandler, createReadSkillTool, createRunAgentActivity, createSession, createTaskCreateHandler, createTaskGetHandler, createTaskListHandler, createTaskUpdateHandler, createThreadManager, createToolRouter, createVirtualFsActivities, defineSubagent, defineSubagentWorkflow, defineTool, defineWorkflow, editHandler, editTool, filesWithMimeType, formatVirtualFileTree, getActivityContext, getShortId, globHandler, globTool, grepTool, hasDirectory, hasFileWithMimeType, hasNoOtherToolCalls, isTerminalStatus, parseSkillFile, proxyRunAgent, proxyVirtualFsOps, queryParentWorkflowState, readFileHandler, readFileTool, taskCreateTool, taskGetTool, taskListTool, taskUpdateTool, toTree, withAutoAppend, withParentWorkflowState, withSandbox, withVirtualFs, writeFileHandler, writeFileTool };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map