zeitlich 0.2.13 → 0.2.14

package/dist/index.d.ts

@@ -1,96 +1,283 @@
-import { GlobArgs, FileEditArgs, BashArgs } from './workflow.js';
-export { AgentState, AgentStateManager, AskUserQuestionArgs, FileReadArgs, FileWriteArgs, GrepArgs, JsonPrimitive, JsonSerializable, JsonValue, ReadSkillArgs, SessionLifecycleHooks, TaskCreateArgs, TaskGetArgs, TaskListArgs, TaskUpdateArgs, ZeitlichSession, askUserQuestionTool, bashTool, createAgentStateManager, createAskUserQuestionHandler, createBashToolDescription, createReadSkillHandler, createReadSkillTool, createSession, createTaskCreateHandler, createTaskGetHandler, createTaskListHandler, createTaskUpdateHandler, editTool, getShortId, globTool, grepTool, parseSkillFile, proxyDefaultThreadOps, readFileTool, taskCreateTool, taskGetTool, taskListTool, taskUpdateTool, writeFileTool } from './workflow.js';
-import { M as ModelInvoker, R as RunAgentConfig, A as AgentResponse, b as ActivityToolHandler, S as SkillProvider, c as SkillMetadata, d as Skill } from './model-invoker-y_zlyMqu.js';
-export { e as AgentConfig, f as AgentFile, g as AgentStatus, h as AppendToolResultFn, B as BaseAgentState, C as ContentPart, H as Hooks, I as InferToolResults, i as MessageContent, a as ModelInvokerConfig, P as ParsedToolCall, j as ParsedToolCallUnion, k as PostHumanMessageAppendHook, l as PostHumanMessageAppendHookContext, m as PostToolUseFailureHook, n as PostToolUseFailureHookContext, o as PostToolUseFailureHookResult, p as PostToolUseHook, q as PostToolUseHookContext, r as PreHumanMessageAppendHook, s as PreHumanMessageAppendHookContext, t as PreToolUseHook, u as PreToolUseHookContext, v as PreToolUseHookResult, w as ProcessToolCallsContext, x as RawToolCall, y as RunAgentActivity, z as SessionConfig, D as SessionEndHook, E as SessionEndHookContext, F as SessionExitReason, G as SessionStartHook, J as SessionStartHookContext, K as SubagentArgs, L as SubagentConfig, N as SubagentHooks, O as SubagentInput, Q as SubagentWorkflow, U as TaskStatus, T as ThreadOps, V as TokenUsage, W as ToolArgs, X as ToolCallResult, Y as ToolCallResultUnion, Z as ToolDefinition, _ as ToolHandler, $ as ToolHandlerContext, a0 as ToolHandlerResponse, a1 as ToolHooks, a2 as ToolMap, a3 as ToolMessageContent, a4 as ToolNames, a5 as ToolResult, a6 as ToolResultConfig, a7 as ToolRouter, a8 as ToolWithHandler, a9 as WorkflowTask, aa as agentQueryName, ab as agentStateChangeUpdateName, ac as createSubagentTool, ad as createToolRouter, ae as defineSubagent, af as defineTool, ag as hasNoOtherToolCalls, ah as isTerminalStatus, ai as withAutoAppend } from './model-invoker-y_zlyMqu.js';
-export { B as BaseThreadManager, T as ThreadManagerConfig, c as createThreadManager } from './thread-manager-qc0g5Rvd.js';
+import { BashArgs, FileEditArgs, GlobArgs, FileReadArgs, FileWriteArgs } from './workflow.js';
+export { AskUserQuestionArgs, GrepArgs, ReadSkillArgs, SubagentArgs, TaskCreateArgs, TaskGetArgs, TaskListArgs, TaskUpdateArgs, applyVirtualTreeMutations, askUserQuestionTool, bashTool, createAgentStateManager, createAskUserQuestionHandler, createBashToolDescription, createReadSkillHandler, createReadSkillTool, createSession, createTaskCreateHandler, createTaskGetHandler, createTaskListHandler, createTaskUpdateHandler, createToolRouter, defineSubagent, defineTool, editTool, formatVirtualFileTree, getShortId, globTool, grepTool, hasNoOtherToolCalls, parseSkillFile, proxyDefaultThreadOps, proxySandboxOps, readFileTool, taskCreateTool, taskGetTool, taskListTool, taskUpdateTool, writeFileTool } from './workflow.js';
+import { S as SkillProvider, b as SkillMetadata, c as Skill } from './types-B4C9txdq.js';
+export { A as AgentResponse, d as AgentState, e as AgentStateManager, H as Hooks, J as JsonPrimitive, f as JsonSerializable, g as JsonValue, M as ModelInvoker, a as ModelInvokerConfig, P as PostHumanMessageAppendHook, h as PostHumanMessageAppendHookContext, i as PreHumanMessageAppendHook, j as PreHumanMessageAppendHookContext, R as RunAgentActivity, k as SessionConfig, l as SessionEndHook, m as SessionEndHookContext, n as SessionStartHook, o as SessionStartHookContext, p as SubagentConfig, q as SubagentHandlerResponse, r as SubagentHooks, s as SubagentInput, t as SubagentWorkflow, T as ThreadOps, Z as ZeitlichSession } from './types-B4C9txdq.js';
+import { T as ThreadManagerConfig, B as BaseThreadManager } from './types-B9ljZewB.js';
+import { R as RouterContext, j as ToolResultConfig, A as ActivityToolHandler, c as ToolHandlerResponse, B as BaseAgentState, g as RunAgentConfig } from './types-BMXzv7TN.js';
+export { l as AgentConfig, m as AgentFile, h as AgentStatus, n as AppendToolResultFn, C as ContentPart, I as InferToolResults, M as MessageContent, o as ParsedToolCall, p as ParsedToolCallUnion, q as PostToolUseFailureHook, r as PostToolUseFailureHookContext, d as PostToolUseFailureHookResult, s as PostToolUseHook, t as PostToolUseHookContext, u as PreToolUseHook, v as PreToolUseHookContext, P as PreToolUseHookResult, w as ProcessToolCallsContext, e as RawToolCall, x as SerializableToolDefinition, S as SessionExitReason, y as TaskStatus, f as TokenUsage, z as ToolArgs, D as ToolCallResult, k as ToolCallResultUnion, i as ToolDefinition, E as ToolHandler, F as ToolHooks, a as ToolMap, T as ToolMessageContent, G as ToolNames, H as ToolResult, J as ToolRouter, b as ToolRouterHooks, K as ToolWithHandler, W as WorkflowTask, L as isTerminalStatus } from './types-BMXzv7TN.js';
+import { S as Sandbox, a as SandboxFileSystem, d as SandboxCreateOptions, b as SandboxProvider, f as SandboxSnapshot, g as SandboxOps, E as ExecResult } from './types-CDubRtad.js';
+export { h as ExecOptions, c as SandboxCapabilities, e as SandboxCreateResult, D as SandboxDirentEntry, F as SandboxFileStat, i as SandboxNotFoundError, j as SandboxNotSupportedError } from './types-CDubRtad.js';
 import { WorkflowClient } from '@temporalio/client';
-import { IFileSystem, BashOptions } from 'just-bash';
+export { c as FileEntry, F as FileEntryMetadata, a as FileResolver, T as TreeMutation, e as VirtualFileTree, g as VirtualSandboxState } from './types-CwwgQ_9H.js';
 import '@temporalio/workflow';
-import '@temporalio/common/lib/interfaces';
 import 'zod';
 import '@temporalio/common';
+import '@temporalio/common/lib/interfaces';
 import 'ioredis';
 
+/**
+ * Creates a generic thread manager for handling conversation state in Redis.
+ * Framework-agnostic — works with any serializable message type.
+ */
+declare function createThreadManager<T>(config: ThreadManagerConfig<T>): BaseThreadManager<T>;
+
+/**
+ * Wraps a tool handler to automatically append its result directly to the
+ * thread and sets `resultAppended: true` on the response.
+ *
+ * Use this for tools whose responses may exceed Temporal's activity payload
+ * limit. The wrapper appends to the thread inside the activity (where Redis
+ * is available), then replaces `toolResponse` with an empty string so the
+ * large payload never travels through the Temporal workflow boundary.
+ *
+ * @param getThread - Factory that returns a thread manager for the given threadId
+ * @param handler   - The original tool handler
+ * @returns A wrapped handler that auto-appends and flags the response
+ *
+ * @example
+ * ```typescript
+ * import { withAutoAppend } from '@bead-ai/zeitlich/workflow';
+ * import { createThreadManager } from '@bead-ai/zeitlich';
+ *
+ * const handler = withAutoAppend(
+ *   (threadId) => createThreadManager({ redis, threadId }),
+ *   async (args, ctx) => ({
+ *     toolResponse: JSON.stringify(largeResult), // appended directly to Redis
+ *     data: { summary: "..." },                  // small data for workflow
+ *   }),
+ * );
+ * ```
+ */
+declare function withAutoAppend<TArgs, TResult, TContext extends RouterContext = RouterContext>(threadHandler: (config: ToolResultConfig) => Promise<void>, handler: ActivityToolHandler<TArgs, TResult, TContext>): ActivityToolHandler<TArgs, TResult, TContext>;
+
+/**
+ * Extended router context with a resolved {@link Sandbox} instance.
+ *
+ * Handlers typed with this context are guaranteed to have a live sandbox
+ * and a non-optional `sandboxId`. Use with {@link withSandbox} to
+ * automatically resolve the sandbox from the manager.
+ */
+interface SandboxContext extends RouterContext {
+    sandbox: Sandbox;
+    sandboxId: string;
+}
+/**
+ * Wraps a tool handler that requires a {@link Sandbox}, automatically
+ * resolving it from the manager via the `sandboxId` on the router context.
+ *
+ * If no `sandboxId` is present the wrapper short-circuits with an error
+ * response and `data: null`, so the inner handler never runs without a
+ * valid sandbox.
+ *
+ * The sandbox type parameter `TSandbox` is inferred from the manager's
+ * `getSandbox` return type, allowing handlers to receive provider-specific
+ * sandbox subtypes (e.g. `DaytonaSandbox`) without manual casting.
+ *
+ * @param manager - Any object with a `getSandbox` method (e.g. {@link SandboxManager})
+ * @param handler - The inner handler that expects a sandbox context
+ * @returns A standard `ActivityToolHandler` that can be registered on the router
+ *
+ * @example
+ * ```typescript
+ * import { withSandbox, type SandboxContext } from 'zeitlich';
+ *
+ * // Generic sandbox — works with any provider:
+ * const bashHandler: ActivityToolHandler<BashArgs, ExecResult, SandboxContext> =
+ *   async (args, { sandbox }) => {
+ *     const result = await sandbox.exec(args.command);
+ *     return { toolResponse: result.stdout, data: result };
+ *   };
+ * const handler = withSandbox(manager, bashHandler);
+ *
+ * // Provider-specific sandbox — use SandboxManager<DaytonaSandbox>:
+ * const daytonaManager = new SandboxManager<DaytonaSandbox>(provider);
+ * const handler2 = withSandbox(daytonaManager, async (args, { sandbox }) => {
+ *   // sandbox is typed as DaytonaSandbox here
+ *   await sandbox.fs.uploadFiles([...]);
+ *   return { toolResponse: 'ok', data: null };
+ * });
+ * ```
+ */
+declare function withSandbox<TArgs, TResult, TSandbox extends Sandbox = Sandbox>(manager: {
+    getSandbox(id: string): Promise<TSandbox>;
+}, handler: (args: TArgs, context: RouterContext & {
+    sandbox: TSandbox;
+    sandboxId: string;
+}) => Promise<ToolHandlerResponse<TResult>>): ActivityToolHandler<TArgs, TResult | null>;
+
 /**
  * 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, queryName: string): Promise<T>;
+declare function queryParentWorkflowState<T>(client: WorkflowClient): Promise<T>;
 /**
- * Wraps a `ModelInvoker` into a `RunAgentActivity` by automatically
- * loading tool definitions from the parent workflow state via query.
- *
- * This is the generic bridge between any provider-specific model invoker
- * and the session's `runAgent` contract.
+ * Wraps a handler into a `RunAgentActivity` by auto-fetching the parent
+ * workflow's agent state before each invocation.
  *
  * @example
  * ```typescript
  * import { createRunAgentActivity } from 'zeitlich';
- * import { createLangChainModelInvoker } from 'zeitlich/adapters/langchain';
+ * import { createLangChainModelInvoker } from 'zeitlich/adapters/thread/langchain';
  *
  * const invoker = createLangChainModelInvoker({ redis, model });
  * return { runAgent: createRunAgentActivity(client, invoker) };
  * ```
  */
-declare function createRunAgentActivity<M>(client: WorkflowClient, invoker: ModelInvoker<M>): (config: RunAgentConfig) => Promise<AgentResponse<M>>;
+declare function createRunAgentActivity<R, S extends BaseAgentState = BaseAgentState>(client: WorkflowClient, handler: (config: RunAgentConfig & {
+    state: S;
+}) => Promise<R>): (config: RunAgentConfig) => Promise<R>;
+/**
+ * Context injected into tool handlers created via {@link withParentWorkflowState}.
+ */
+interface AgentStateContext<S extends BaseAgentState = BaseAgentState> extends RouterContext {
+    state: S;
+}
+/**
+ * Wraps a tool handler into an `ActivityToolHandler` by auto-fetching the
+ * parent workflow's agent state before each invocation.
+ *
+ * @typeParam S - Custom agent state type (defaults to `BaseAgentState`)
+ *
+ * @example
+ * ```typescript
+ * import { withParentWorkflowState, type AgentStateContext } from 'zeitlich';
+ *
+ * // With custom state:
+ * interface MyState extends BaseAgentState { customField: string }
+ * const myHandler = withParentWorkflowState<MyArgs, MyResult, MyState>(
+ *   client,
+ *   async (args, ctx) => {
+ *     console.log(ctx.state.customField);
+ *     return { toolResponse: 'done', data: null };
+ *   },
+ * );
+ * ```
+ */
+declare function withParentWorkflowState<TArgs, TResult, S extends BaseAgentState = BaseAgentState>(client: WorkflowClient, handler: (args: TArgs, context: AgentStateContext<S>) => Promise<ToolHandlerResponse<TResult>>): ActivityToolHandler<TArgs, TResult>;
 
 /**
- * Result of a glob operation
+ * Loads skills from a directory following the agentskills.io layout:
+ *
+ * ```
+ * skills/
+ * ├── code-review/
+ * │   └── SKILL.md
+ * ├── pdf-processing/
+ * │   └── SKILL.md
+ * ```
+ *
+ * Uses the sandbox filesystem abstraction — works with any backend
+ * (in-memory, host FS, Wasmer, Daytona, etc.).
  */
-interface GlobResult {
-    files: string[];
+declare class FileSystemSkillProvider implements SkillProvider {
+    private readonly fs;
+    private readonly baseDir;
+    constructor(fs: SandboxFileSystem, baseDir: string);
+    listSkills(): Promise<SkillMetadata[]>;
+    getSkill(name: string): Promise<Skill>;
+    /**
+     * Convenience method to load all skills with full instructions.
+     * Returns `Skill[]` ready to pass into a workflow.
+     */
+    loadAll(): Promise<Skill[]>;
+    private discoverSkillDirs;
 }
+
 /**
- * Creates a glob handler that searches within the scoped file tree.
+ * Stateless facade over a {@link SandboxProvider}.
  *
- * @param fs - File system implementation for I/O operations
- * @returns An ActivityToolHandler for glob tool calls
+ * Delegates all lifecycle operations to the provider, which is responsible
+ * for its own instance management strategy (e.g. in-memory map, remote API).
+ *
+ * @example
+ * ```typescript
+ * const manager = new SandboxManager(new InMemorySandboxProvider());
+ * const activities = {
+ *   ...manager.createActivities(),
+ *   bashHandler: withSandbox(manager, bashHandler),
+ * };
+ * ```
  */
-declare function createGlobHandler(fs: IFileSystem): ActivityToolHandler<GlobArgs, GlobResult>;
+declare class SandboxManager<TOptions extends SandboxCreateOptions = SandboxCreateOptions, TSandbox extends Sandbox = Sandbox> {
+    private provider;
+    constructor(provider: SandboxProvider<TOptions, TSandbox>);
+    create(options?: TOptions): Promise<{
+        sandboxId: string;
+        stateUpdate?: Record<string, unknown>;
+    }>;
+    getSandbox(id: string): Promise<TSandbox>;
+    destroy(id: string): Promise<void>;
+    snapshot(id: string): Promise<SandboxSnapshot>;
+    restore(snapshot: SandboxSnapshot): Promise<string>;
+    /**
+     * Returns Temporal activity functions matching {@link SandboxOps}.
+     * Spread these into your worker's activity map.
+     */
+    createActivities(): SandboxOps<TOptions>;
+}
 
 /**
- * Result of an edit operation
+ * Bash tool handler — executes shell commands inside a {@link Sandbox}.
+ *
+ * Wrap with {@link withSandbox} at activity registration time to inject the
+ * sandbox automatically.
  */
+declare const bashHandler: ActivityToolHandler<BashArgs, ExecResult | null, SandboxContext>;
+
 interface EditResult {
     path: string;
     success: boolean;
     replacements: number;
 }
 /**
- * Creates an edit handler that edits files within the scoped file tree.
+ * Edit tool handler — performs string replacements in sandbox files.
  *
- * @param fs - File system implementation for I/O operations
- * @returns An ActivityToolHandler for edit tool calls
+ * Wrap with {@link withSandbox} at activity registration time to inject the
+ * sandbox automatically.
  */
-declare function createEditHandler(fs: IFileSystem): ActivityToolHandler<FileEditArgs, EditResult>;
+declare const editHandler: ActivityToolHandler<FileEditArgs, EditResult, SandboxContext>;
 
-type BashExecOut = {
-    exitCode: number;
-    stderr: string;
-    stdout: string;
-};
-/** BashOptions with `fs` required */
-type BashToolOptions = Required<Pick<BashOptions, "fs">> & Omit<BashOptions, "fs">;
+interface GlobResult {
+    files: string[];
+}
 /**
- * Creates a Bash tool handler that executes shell commands in a sandboxed environment.
+ * Glob tool handler — searches files within a {@link Sandbox} filesystem.
  *
- * @param bashOptions - Options including a required `fs` (file system implementation from `just-bash`)
- * @returns Activity tool handler for Bash tool calls
+ * Wrap with {@link withSandbox} at activity registration time to inject the
+ * sandbox automatically.
+ */
+declare const globHandler: ActivityToolHandler<GlobArgs, GlobResult, SandboxContext>;
+
+interface ReadFileResult {
+    path: string;
+    content: string;
+    totalLines?: number;
+}
+/**
+ * Read-file tool handler — reads files from a {@link Sandbox} filesystem.
  *
- * @example
- * ```typescript
- * import { createBashHandler } from 'zeitlich';
+ * Wrap with {@link withSandbox} at activity registration time to inject the
+ * sandbox automatically.
+ */
+declare const readFileHandler: ActivityToolHandler<FileReadArgs, ReadFileResult | null, SandboxContext>;
+
+interface WriteFileResult {
+    path: string;
+    success: boolean;
+}
+/**
+ * Write-file tool handler — writes files to a {@link Sandbox} filesystem.
  *
- * const bashHandlerActivity = createBashHandler({ fs: inMemoryFileSystem });
- * ```
+ * Wrap with {@link withSandbox} at activity registration time to inject the
+ * sandbox automatically.
  */
-declare const createBashHandler: (bashOptions: BashToolOptions) => ActivityToolHandler<BashArgs, BashExecOut | null>;
+declare const writeFileHandler: ActivityToolHandler<FileWriteArgs, WriteFileResult, SandboxContext>;
 
 /**
- * Generates a formatted file tree string from an `IFileSystem` instance.
+ * Generates a formatted file tree string from a {@link SandboxFileSystem}.
  * Useful for including filesystem context in agent prompts.
  *
- * @param fs - File system implementation (e.g. from `just-bash`)
+ * @param fs - Sandbox filesystem implementation
  * @param opts - Optional configuration for tree generation
  * @param opts.dir - Root directory to start from (defaults to `/`)
  * @param opts.separator - Path separator (`/` or `\\`, defaults to `/`)
@@ -102,7 +289,7 @@ declare const createBashHandler: (bashOptions: BashToolOptions) => ActivityToolH
  * ```typescript
  * import { toTree } from 'zeitlich';
  *
- * const fileTree = await toTree(inMemoryFileSystem);
+ * const fileTree = await toTree(sandbox.fs);
  * // Returns:
  * // /
  * // ├─ src/
@@ -111,7 +298,7 @@ declare const createBashHandler: (bashOptions: BashToolOptions) => ActivityToolH
  * // └─ package.json
  * ```
  */
-declare const toTree: (fs: IFileSystem, opts?: {
+declare const toTree: (fs: SandboxFileSystem, opts?: {
     dir?: string;
     separator?: "/" | "\\";
     depth?: number;
@@ -119,30 +306,4 @@ declare const toTree: (fs: IFileSystem, opts?: {
     sort?: boolean;
 }) => Promise<string>;
 
-/**
- * Loads skills from a filesystem directory following the agentskills.io layout:
- *
- * ```
- * skills/
- * ├── code-review/
- * │   └── SKILL.md
- * ├── pdf-processing/
- * │   └── SKILL.md
- * ```
- *
- * Activity-side only — cannot be used in Temporal workflow code.
- */
-declare class FileSystemSkillProvider implements SkillProvider {
-    private readonly baseDir;
-    constructor(baseDir: string);
-    listSkills(): Promise<SkillMetadata[]>;
-    getSkill(name: string): Promise<Skill>;
-    /**
-     * Convenience method to load all skills with full instructions.
-     * Returns `Skill[]` ready to pass into a workflow.
-     */
-    loadAll(): Promise<Skill[]>;
-    private discoverSkillDirs;
-}
-
-export { ActivityToolHandler, AgentResponse, BashArgs, FileEditArgs, FileSystemSkillProvider, GlobArgs, ModelInvoker, RunAgentConfig, Skill, SkillMetadata, SkillProvider, createBashHandler, createEditHandler, createGlobHandler, createRunAgentActivity, queryParentWorkflowState, toTree };
+export { ActivityToolHandler, type AgentStateContext, BaseAgentState, BaseThreadManager, BashArgs, ExecResult, FileEditArgs, FileReadArgs, FileSystemSkillProvider, FileWriteArgs, GlobArgs, RouterContext, RunAgentConfig, Sandbox, type SandboxContext, SandboxCreateOptions, SandboxFileSystem, SandboxManager, SandboxOps, SandboxProvider, SandboxSnapshot, Skill, SkillMetadata, SkillProvider, ThreadManagerConfig, ToolHandlerResponse, ToolResultConfig, bashHandler, createRunAgentActivity, createThreadManager, editHandler, globHandler, queryParentWorkflowState, readFileHandler, toTree, withAutoAppend, withParentWorkflowState, withSandbox, writeFileHandler };