zeitlich 0.2.21 → 0.2.23

package/README.md

@@ -28,20 +28,41 @@ Temporal solves these problems for workflows. Zeitlich brings these guarantees t
 - **Type-safe tools** — Define tools with Zod schemas, get full TypeScript inference
 - **Lifecycle hooks** — Pre/post tool execution, session start/end
 - **Subagent support** — Spawn child agents as Temporal child workflows
+- **Skills** — First-class [agentskills.io](https://agentskills.io) support with progressive disclosure
 - **Filesystem utilities** — In-memory or custom providers for file operations
-- **Model flexibility** — Framework-agnostic model invocation with adapters for LangChain (and more coming)
+- **Model flexibility** — Framework-agnostic model invocation with adapters for LangChain, Vercel AI SDK, or provider-specific SDKs
 
 ## LLM Integration
 
-Zeitlich's core is framework-agnostic — it defines generic interfaces (`ModelInvoker`, `ThreadOps`, `MessageContent`) that work with any LLM SDK. Concrete implementations are provided via adapter packages.
+Zeitlich's core is framework-agnostic — it defines generic interfaces (`ModelInvoker`, `ThreadOps`, `MessageContent`) that work with any LLM SDK. You choose a **thread adapter** (for conversation storage and model invocation) and a **sandbox adapter** (for filesystem operations), then wire them together.
 
-### LangChain Adapter (`zeitlich/adapters/thread/langchain`)
+### Thread Adapters
 
-The built-in LangChain adapter gives you:
+A thread adapter bundles two concerns:
+1. **Thread management** — Storing and retrieving conversation messages in Redis
+2. **Model invocation** — Calling the LLM with the conversation history and tools
 
-- **Provider flexibility** — Use Anthropic, OpenAI, Google, Azure, AWS Bedrock, or any LangChain-supported provider
-- **Consistent interface** — Same tool calling and message format regardless of provider
-- **Easy model swapping** — Change models without rewriting agent logic
+Each adapter exposes the same shape: `createActivities(scope)` for Temporal worker registration, and an `invoker` for model calls. Pick the one matching your preferred SDK:
+
+| Adapter | Import | SDK |
+|---------|--------|-----|
+| LangChain | `zeitlich/adapters/thread/langchain` | `@langchain/core` + any provider package |
+| Google GenAI | `zeitlich/adapters/thread/google-genai` | `@google/genai` |
+
+Vercel AI SDK and other provider-specific adapters can be built by implementing the `ThreadOps` and `ModelInvoker` interfaces.
+
+### Sandbox Adapters
+
+A sandbox adapter provides filesystem access for tools like `Bash`, `Read`, `Write`, and `Edit`:
+
+| Adapter | Import | Use case |
+|---------|--------|----------|
+| In-memory | `zeitlich/adapters/sandbox/inmemory` | Tests and lightweight agents |
+| Virtual | `zeitlich/adapters/sandbox/virtual` | Custom resolvers with path-only ops |
+| Daytona | `zeitlich/adapters/sandbox/daytona` | Remote Daytona workspaces |
+| E2B | `zeitlich/adapters/sandbox/e2b` | E2B cloud sandboxes |
+
+### Example: LangChain Adapter
 
 ```typescript
 import { ChatAnthropic } from "@langchain/anthropic";
@@ -55,19 +76,13 @@ const adapter = createLangChainAdapter({
 
 export function createActivities(client: WorkflowClient) {
   return {
-    ...adapter.threadOps,
+    ...adapter.createActivities("myAgentWorkflow"),
     runAgent: createRunAgentActivity(client, adapter.invoker),
   };
 }
 ```
 
-Install the LangChain package for your chosen provider:
-
-```bash
-npm install @langchain/core @langchain/anthropic  # Anthropic
-npm install @langchain/core @langchain/openai     # OpenAI
-npm install @langchain/core @langchain/google-genai # Google
-```
+All adapters follow the same pattern — `createActivities(scope)` for worker registration and `invoker` for model calls.
 
 ## Installation
 
@@ -78,7 +93,8 @@ npm install zeitlich ioredis
 **Peer dependencies:**
 
 - `ioredis` >= 5.0.0
-- `@langchain/core` >= 1.0.0 (optional — only needed when using `zeitlich/adapters/thread/langchain`)
+- `@langchain/core` >= 1.0.0 (optional — only when using the LangChain adapter)
+- `@google/genai` >= 1.0.0 (optional — only when using the Google GenAI adapter)
 
 **Required infrastructure:**
 
@@ -87,40 +103,40 @@ npm install zeitlich ioredis
 
 ## Import Paths
 
-Zeitlich provides three entry points:
+Zeitlich uses separate entry points for workflow-side and activity-side code:
 
 ```typescript
-// In workflow files — no external dependencies (Redis, LangChain, etc.)
+// In workflow files — no external dependencies (Redis, LLM SDKs, etc.)
 import {
   createSession,
   createAgentStateManager,
-  askUserQuestionTool,
-  bashTool,
   defineTool,
-  defineSubagentWorkflow,
-  defineSubagent,
-  type ModelInvoker,
+  bashTool,
 } from "zeitlich/workflow";
 
+// Adapter workflow proxies (auto-scoped to current workflow)
+import { proxyLangChainThreadOps } from "zeitlich/adapters/thread/langchain/workflow";
+import { proxyInMemorySandboxOps } from "zeitlich/adapters/sandbox/inmemory/workflow";
+
 // In activity files and worker setup — framework-agnostic core
 import {
   createRunAgentActivity,
-  withParentWorkflowState,
+  SandboxManager,
   withSandbox,
   bashHandler,
-  createAskUserQuestionHandler,
-  toTree,
 } from "zeitlich";
 
-// LangChain adapter — unified adapter for LLM invocation and thread management
+// Thread adapter — activity-side
 import { createLangChainAdapter } from "zeitlich/adapters/thread/langchain";
 ```
 
-**Why three entry points?**
+**Entry points:**
 
 - `zeitlich/workflow` — Pure TypeScript, safe for Temporal's V8 sandbox
+- `zeitlich/adapters/*/workflow` — Workflow-side proxies that auto-scope activities to the current workflow
 - `zeitlich` — Activity-side utilities (Redis, filesystem), framework-agnostic
-- `zeitlich/adapters/thread/langchain` — LangChain-specific adapter (model invocation + thread management)
+- `zeitlich/adapters/thread/*` — Activity-side adapters (thread management + model invocation)
+- `zeitlich/adapters/sandbox/*` — Activity-side sandbox providers
 
 ## Examples
 
@@ -145,13 +161,14 @@ export const searchTool: ToolDefinition<"Search", typeof searchSchema> = {
 
 ### 2. Create the Workflow
 
-The system prompt is set via `createAgentStateManager`'s `initialState`, and agent config fields (`agentName`, `maxTurns`, etc.) are spread into `createSession`.
+The workflow wires together a **thread adapter** (for conversation storage / model calls) and a **sandbox adapter** (for filesystem tools). Both are pluggable — swap the proxy import to switch providers.
 
 ```typescript
 import { proxyActivities, workflowInfo } from "@temporalio/workflow";
 import {
   createAgentStateManager,
   createSession,
+  defineWorkflow,
   askUserQuestionTool,
   bashTool,
   defineTool,
@@ -159,6 +176,9 @@ import {
 import { searchTool } from "./tools";
 import type { MyActivities } from "./activities";
 
+import { proxyLangChainThreadOps } from "zeitlich/adapters/thread/langchain/workflow";
+import { proxyInMemorySandboxOps } from "zeitlich/adapters/sandbox/inmemory/workflow";
+
 const {
   runAgentActivity,
   searchHandlerActivity,
@@ -175,64 +195,76 @@ const {
   heartbeatTimeout: "5m",
 });
 
-export async function myAgentWorkflow({ prompt }: { prompt: string }) {
-  const { runId } = workflowInfo();
+export const myAgentWorkflow = defineWorkflow(
+  { name: "myAgentWorkflow" },
+  async ({ prompt }: { prompt: string }, sessionInput) => {
+    const { runId } = workflowInfo();
 
-  const stateManager = createAgentStateManager({
-    initialState: {
-      systemPrompt: "You are a helpful assistant.",
-    },
-    agentName: "my-agent",
-  });
+    const stateManager = createAgentStateManager({
+      initialState: {
+        systemPrompt: "You are a helpful assistant.",
+      },
+      agentName: "my-agent",
+    });
 
-  const session = await createSession({
-    agentName: "my-agent",
-    maxTurns: 20,
-    threadId: runId,
-    runAgent: runAgentActivity,
-    buildContextMessage: () => [{ type: "text", text: prompt }],
-    tools: {
-      Search: defineTool({
-        ...searchTool,
-        handler: searchHandlerActivity,
-      }),
-      AskUserQuestion: defineTool({
-        ...askUserQuestionTool,
-        handler: askUserQuestionHandlerActivity,
-        hooks: {
-          onPostToolUse: () => {
-            stateManager.waitForInput();
+    const session = await createSession({
+      agentName: "my-agent",
+      maxTurns: 20,
+      thread: { mode: "new", threadId: runId },
+      threadOps: proxyLangChainThreadOps(),
+      sandboxOps: proxyInMemorySandboxOps(),
+      runAgent: runAgentActivity,
+      buildContextMessage: () => [{ type: "text", text: prompt }],
+      tools: {
+        Search: defineTool({
+          ...searchTool,
+          handler: searchHandlerActivity,
+        }),
+        AskUserQuestion: defineTool({
+          ...askUserQuestionTool,
+          handler: askUserQuestionHandlerActivity,
+          hooks: {
+            onPostToolUse: () => {
+              stateManager.waitForInput();
+            },
           },
-        },
-      }),
-      Bash: defineTool({
-        ...bashTool,
-        handler: bashHandlerActivity,
-      }),
-    },
-  });
+        }),
+        Bash: defineTool({
+          ...bashTool,
+          handler: bashHandlerActivity,
+        }),
+      },
+      ...sessionInput,
+    });
 
-  const result = await session.runSession({ stateManager });
-  return result;
-}
+    const result = await session.runSession({ stateManager });
+    return result;
+  }
+);
 ```
 
 ### 3. Create Activities
 
-Activities are factory functions that receive infrastructure dependencies (`redis`, `client`). Each returns an object of activity functions registered with the Temporal worker.
+Activities are factory functions that receive infrastructure dependencies (`redis`, `client`). The thread adapter and sandbox provider are configured here — swap imports to change LLM or sandbox backend.
 
 ```typescript
 import type Redis from "ioredis";
 import type { WorkflowClient } from "@temporalio/client";
 import { ChatAnthropic } from "@langchain/anthropic";
 import {
+  SandboxManager,
   withSandbox,
   bashHandler,
   createAskUserQuestionHandler,
   createRunAgentActivity,
 } from "zeitlich";
+import { InMemorySandboxProvider } from "zeitlich/adapters/sandbox/inmemory";
+
 import { createLangChainAdapter } from "zeitlich/adapters/thread/langchain";
 
+const sandboxProvider = new InMemorySandboxProvider();
+const sandboxManager = new SandboxManager(sandboxProvider);
+
 export const createActivities = ({
   redis,
   client,
@@ -240,7 +272,7 @@ export const createActivities = ({
   redis: Redis;
   client: WorkflowClient;
 }) => {
-  const { threadOps, invoker } = createLangChainAdapter({
+  const adapter = createLangChainAdapter({
     redis,
     model: new ChatAnthropic({
       model: "claude-sonnet-4-20250514",
@@ -249,8 +281,9 @@ export const createActivities = ({
   });
 
   return {
-    ...threadOps,
-    runAgentActivity: createRunAgentActivity(client, invoker),
+    ...adapter.createActivities("myAgentWorkflow"),
+    ...sandboxManager.createActivities("myAgentWorkflow"),
+    runAgentActivity: createRunAgentActivity(client, adapter.invoker),
     searchHandlerActivity: async (args: { query: string }) => ({
       toolResponse: JSON.stringify(await performSearch(args.query)),
       data: null,
@@ -382,6 +415,7 @@ import {
   createSession,
   defineSubagentWorkflow,
 } from "zeitlich/workflow";
+import { proxyLangChainThreadOps } from "zeitlich/adapters/thread/langchain/workflow";
 import type { createResearcherActivities } from "./activities";
 
 const { runResearcherActivity } = proxyActivities<
@@ -400,7 +434,8 @@ export const researcherWorkflow = defineSubagentWorkflow(
     });
 
     const session = await createSession({
-      ...sessionInput, // spreads agentName, threadId, continueThread, sandboxId
+      ...sessionInput, // spreads agentName, thread, sandbox, sandboxShutdown
+      threadOps: proxyLangChainThreadOps(), // auto-scoped to "Researcher"
       runAgent: runResearcherActivity,
       buildContextMessage: () => [{ type: "text", text: prompt }],
     });
@@ -427,7 +462,7 @@ export const researcherSubagent = defineSubagent(researcherWorkflow);
 
 // Optionally override parent-specific config
 export const researcherSubagent = defineSubagent(researcherWorkflow, {
-  allowThreadContinuation: true,
+  thread: "fork",
   sandbox: "own",
   hooks: {
     onPostExecution: ({ result }) => console.log("researcher done", result),
@@ -442,38 +477,186 @@ const session = await createSession({
 
 The `Subagent` tool is automatically added when subagents are configured, allowing the LLM to spawn child workflows.
 
-### Thread Continuation
+### Skills
+
+Zeitlich has first-class support for the [agentskills.io](https://agentskills.io) specification. Skills are reusable instruction sets that an agent can load on-demand via the built-in `ReadSkill` tool — progressive disclosure keeps token usage low while giving agents access to rich, domain-specific guidance.
+
+#### Defining a Skill
+
+Each skill lives in its own directory as a `SKILL.md` file with YAML frontmatter:
+
+```
+skills/
+├── code-review/
+│   └── SKILL.md
+├── pdf-processing/
+│   └── SKILL.md
+```
+
+```markdown
+---
+name: code-review
+description: Review pull requests for correctness, style, and security issues
+allowed-tools: Bash Grep Read
+license: MIT
+---
+
+## Instructions
+
+When reviewing code, follow these steps:
+1. Read the diff with `Bash`
+2. Search for related tests with `Grep`
+3. ...
+```
+
+Required fields: `name` and `description`. Optional: `license`, `compatibility`, `allowed-tools` (space-delimited), `metadata` (key-value map).
+
+#### Loading Skills
+
+Use `FileSystemSkillProvider` to load skills from a directory (works with any sandbox filesystem):
+
+```typescript
+import { FileSystemSkillProvider } from "zeitlich";
+import { InMemorySandboxProvider } from "zeitlich/adapters/sandbox/inmemory";
+
+const provider = new InMemorySandboxProvider();
+const { sandbox } = await provider.create({});
+
+const skillProvider = new FileSystemSkillProvider(sandbox.fs, "/skills");
+const skills = await skillProvider.loadAll();
+```
 
-By default, each session initializes a fresh thread. To continue from an existing thread (e.g., resuming a conversation after a workflow completes), pass `continueThread: true` along with the previous `threadId`:
+Or parse a single file directly:
+
+```typescript
+import { parseSkillFile } from "zeitlich/workflow";
+
+const { frontmatter, body } = parseSkillFile(rawMarkdown);
+// frontmatter: SkillMetadata, body: instruction text
+```
+
+#### Passing Skills to a Session
+
+Pass loaded skills to `createSession`. Zeitlich automatically registers a `ReadSkill` tool whose description lists all available skills — the agent discovers them through the tool definition and loads instructions on demand:
 
 ```typescript
 import { createSession } from "zeitlich/workflow";
 
-// First run — threadId defaults to getShortId() if omitted
 const session = await createSession({
-  // threadId is optional, auto-generated if not provided
   // ... other config
+  skills, // Skill[] — loaded via FileSystemSkillProvider or manually
 });
+```
+
+The `ReadSkill` tool accepts a `skill_name` parameter (constrained to an enum of available names) and returns the full instruction body. The handler runs directly in the workflow — no activity needed.
 
-// Later — new workflow forks the previous thread
+#### Building Skills Manually
+
+For advanced use cases, you can construct the tool and handler independently:
+
+```typescript
+import { createReadSkillTool, createReadSkillHandler } from "zeitlich/workflow";
+
+const tool = createReadSkillTool(skills);    // ToolDefinition with enum schema
+const handler = createReadSkillHandler(skills); // Returns skill instructions
+```
+
+### Thread & Sandbox Lifecycle
+
+Every session has a **thread** (conversation history) and an optional **sandbox** (filesystem environment). Both are configured with explicit lifecycle types that control how they are initialized and torn down.
+
+#### Thread Initialization (`ThreadInit`)
+
+The `thread` field on `SessionConfig` (and `WorkflowInput`) accepts one of three modes:
+
+| Mode | Description |
+|------|-------------|
+| `{ mode: "new" }` | Start a fresh thread (default). Optionally pass `threadId` to choose the ID. |
+| `{ mode: "fork", threadId }` | Copy all messages from an existing thread into a new one and continue there. The original is never mutated. |
+| `{ mode: "continue", threadId }` | Append directly to an existing thread in-place. |
+
+```typescript
+import { createSession } from "zeitlich/workflow";
+
+// First run — fresh thread
+const session = await createSession({
+  thread: { mode: "new" },
+  // ... other config
+});
+
+// Later — fork the previous conversation
 const resumedSession = await createSession({
-  threadId: savedThreadId, // the thread to continue from
-  continueThread: true, // fork into a new thread with the old messages
+  thread: { mode: "fork", threadId: savedThreadId },
   // ... other config
 });
-```
 
-When `continueThread` is true the session **forks** the provided thread — it copies all messages into a new thread and operates on the copy. The original thread is never mutated, so multiple sessions can safely continue from the same thread in parallel.
+// Or append directly to the existing thread
+const continuedSession = await createSession({
+  thread: { mode: "continue", threadId: savedThreadId },
+  // ... other config
+});
+```
 
 `getShortId()` produces compact, workflow-deterministic IDs (~12 base-62 chars) that are more token-efficient than UUIDs.
 
-#### Subagent Thread Continuation
+#### Sandbox Initialization (`SandboxInit`)
+
+The `sandbox` field controls how a sandbox is created or reused:
+
+| Mode | Description |
+|------|-------------|
+| `{ mode: "new" }` | Create a fresh sandbox (default when `sandboxOps` is provided). |
+| `{ mode: "continue", sandboxId }` | Resume a previously-paused sandbox. This session takes ownership. |
+| `{ mode: "fork", sandboxId }` | Fork from an existing sandbox. A new sandbox is created and owned by this session. |
+| `{ mode: "inherit", sandboxId }` | Use a sandbox owned by someone else (e.g. a parent agent). Shutdown policy is ignored. |
+
+#### Sandbox Shutdown (`SandboxShutdown`)
+
+The `sandboxShutdown` field controls what happens to the sandbox when the session exits:
 
-Subagents can opt in to thread continuation via `allowThreadContinuation`. When enabled, the parent agent can pass a `threadId` to resume a previous subagent conversation:
+| Value | Description |
+|-------|-------------|
+| `"destroy"` | Tear down the sandbox entirely (default). |
+| `"pause"` | Pause the sandbox so it can be resumed later. |
+| `"keep"` | Leave the sandbox running (no-op on exit). |
+
+Subagents also support `"pause-until-parent-close"` — pause on exit, then wait for the parent workflow to signal when to destroy it.
+
+#### Subagent Thread & Sandbox Config
+
+Subagents configure thread and sandbox strategies via `defineSubagent`:
 
 ```typescript
-import { defineSubagentWorkflow, defineSubagent } from "zeitlich/workflow";
+import { defineSubagent } from "zeitlich/workflow";
+import { researcherWorkflow } from "./researcher.workflow";
+
+// Fresh thread each time, no sandbox (defaults)
+export const researcherSubagent = defineSubagent(researcherWorkflow);
 
+// Allow the parent to continue a previous conversation via fork
+export const researcherSubagent = defineSubagent(researcherWorkflow, {
+  thread: "fork",
+});
+
+// Own sandbox with pause-on-exit
+export const researcherSubagent = defineSubagent(researcherWorkflow, {
+  thread: "fork",
+  sandbox: { source: "own", shutdown: "pause" },
+});
+
+// Inherit the parent's sandbox
+export const researcherSubagent = defineSubagent(researcherWorkflow, {
+  sandbox: "inherit",
+});
+```
+
+The `thread` field accepts `"new"` (default), `"fork"`, or `"continue"`. When set to `"fork"` or `"continue"`, the parent agent can pass a `threadId` in a subsequent `Task` tool call to resume the conversation. The subagent returns its `threadId` in the response (surfaced as `[Thread ID: ...]`), which the parent can use for continuation.
+
+The `sandbox` field accepts `"none"` (default), `"inherit"`, `"own"`, or `{ source: "own", shutdown }` for explicit shutdown policy.
+
+The subagent workflow receives lifecycle fields via `sessionInput`:
+
+```typescript
 export const researcherWorkflow = defineSubagentWorkflow(
   {
     name: "Researcher",
@@ -481,27 +664,17 @@ export const researcherWorkflow = defineSubagentWorkflow(
   },
   async (prompt, sessionInput) => {
     const session = await createSession({
-      ...sessionInput, // threadId/continueThread are provided by parent when resuming
+      ...sessionInput, // spreads agentName, thread, sandbox, sandboxShutdown
+      threadOps: proxyLangChainThreadOps(),
       // ... other config
     });
 
     const { threadId, finalMessage } = await session.runSession({ stateManager });
-    return {
-      toolResponse: finalMessage ? extractText(finalMessage) : "No response",
-      data: null,
-      threadId,
-    };
+    return { toolResponse: extractText(finalMessage), data: null, threadId };
   },
 );
-
-// Enable thread continuation in the parent registration
-export const researcherSubagent = defineSubagent(researcherWorkflow, {
-  allowThreadContinuation: true,
-});
 ```
 
-The subagent returns its `threadId` in the response, which the handler surfaces to the parent LLM as `[Thread ID: ...]`. The parent can then pass that ID back in a subsequent `Subagent` tool call to continue the conversation.
-
 ### Filesystem Utilities
 
 Built-in support for file operations with in-memory or custom filesystem providers (e.g. from [`just-bash`](https://github.com/nicholasgasior/just-bash)).
@@ -547,7 +720,8 @@ import {
 const sandboxManager = new SandboxManager(provider);
 
 export const createActivities = ({ redis, client }) => ({
-  ...sandboxManager.createActivities(),
+  // scope auto-prepends the provider id (e.g. "inMemory", "virtual")
+  ...sandboxManager.createActivities("MyAgentWorkflow"),
   globHandlerActivity: withSandbox(sandboxManager, globHandler),
   editHandlerActivity: withSandbox(sandboxManager, editHandler),
   bashHandlerActivity: withSandbox(sandboxManager, bashHandler),
@@ -617,6 +791,7 @@ Zeitlich provides ready-to-use tool definitions and handlers for common agent op
 | `Grep`            | Search file contents with regex patterns                          |
 | `Bash`            | Execute shell commands                                            |
 | `AskUserQuestion` | Ask the user questions during execution with structured options   |
+| `ReadSkill`       | Load skill instructions on demand (see [Skills](#skills))         |
 | `Task`            | Launch subagents as child workflows (see [Subagents](#subagents)) |
 
 ```typescript
@@ -676,7 +851,10 @@ Safe for use in Temporal workflow files:
 | `getShortId`                | Generate a compact, workflow-deterministic identifier (base-62, 12 chars)                              |
 | Tool definitions            | `askUserQuestionTool`, `globTool`, `grepTool`, `readFileTool`, `writeFileTool`, `editTool`, `bashTool` |
 | Task tools                  | `taskCreateTool`, `taskGetTool`, `taskListTool`, `taskUpdateTool` for workflow task management         |
-| Types                       | `SubagentDefinition`, `SubagentConfig`, `ToolDefinition`, `ToolWithHandler`, `RouterContext`, `SessionConfig`, etc. |
+| Skill utilities             | `parseSkillFile`, `createReadSkillTool`, `createReadSkillHandler`                                      |
+| `defineWorkflow`            | Wraps a main workflow function, translating `WorkflowInput` into session-compatible fields             |
+| Lifecycle types             | `ThreadInit`, `SandboxInit`, `SandboxShutdown`, `SubagentSandboxShutdown`, `SubagentSandboxConfig`     |
+| Types                       | `Skill`, `SkillMetadata`, `SkillProvider`, `SubagentDefinition`, `SubagentConfig`, `ToolDefinition`, `ToolWithHandler`, `RouterContext`, `SessionConfig`, `WorkflowConfig`, `WorkflowInput`, etc. |
 
 ### Activity Entry Point (`zeitlich`)
 
@@ -689,19 +867,29 @@ Framework-agnostic utilities for activities, worker setup, and Node.js code:
 | `createThreadManager`     | Generic Redis-backed thread manager factory                                                   |
 | `toTree`                  | Generate file tree string from an `IFileSystem` instance                                      |
 | `withSandbox`             | Wraps a handler to auto-resolve sandbox from context (pairs with `withAutoAppend`)            |
+| `FileSystemSkillProvider`   | Load skills from a directory following the agentskills.io layout                                  |
 | Tool handlers             | `bashHandler`, `editHandler`, `globHandler`, `readFileHandler`, `writeFileHandler`, `createAskUserQuestionHandler` |
 
-### LangChain Adapter Entry Point (`zeitlich/adapters/thread/langchain`)
+### Thread Adapter Entry Points
 
-LangChain-specific implementations:
+**LangChain** (`zeitlich/adapters/thread/langchain`):
 
 | Export                              | Description                                                            |
 | ----------------------------------- | ---------------------------------------------------------------------- |
-| `createLangChainAdapter`            | Unified adapter returning `threadOps`, `invoker`, `createModelInvoker` |
+| `createLangChainAdapter`            | Unified adapter returning `createActivities`, `invoker`, `createModelInvoker` |
 | `createLangChainModelInvoker`       | Factory that returns a `ModelInvoker` backed by a LangChain chat model |
 | `invokeLangChainModel`              | One-shot model invocation convenience function                         |
 | `createLangChainThreadManager`      | Thread manager with LangChain `StoredMessage` helpers                  |
 
+**Google GenAI** (`zeitlich/adapters/thread/google-genai`):
+
+| Export                              | Description                                                            |
+| ----------------------------------- | ---------------------------------------------------------------------- |
+| `createGoogleGenAIAdapter`          | Unified adapter returning `createActivities`, `invoker`, `createModelInvoker` |
+| `createGoogleGenAIModelInvoker`     | Factory that returns a `ModelInvoker` backed by the `@google/genai` SDK |
+| `invokeGoogleGenAIModel`            | One-shot model invocation convenience function                         |
+| `createGoogleGenAIThreadManager`    | Thread manager with Google GenAI `Content` helpers                     |
+
 ### Types
 
 | Export                  | Description                                                                  |
@@ -716,6 +904,11 @@ LangChain-specific implementations:
 | `RouterContext`          | Base context every tool handler receives (`threadId`, `toolCallId`, `toolName`, `sandboxId?`) |
 | `Hooks`                 | Combined session lifecycle + tool execution hooks                            |
 | `ToolRouterHooks`       | Narrowed hook interface for tool execution only (pre/post/failure)            |
+| `ThreadInit`            | Thread initialization strategy: `"new"`, `"continue"`, or `"fork"`               |
+| `SandboxInit`           | Sandbox initialization strategy: `"new"`, `"continue"`, `"fork"`, or `"inherit"` |
+| `SandboxShutdown`       | Sandbox exit policy: `"destroy" \| "pause" \| "keep"`                            |
+| `SubagentSandboxShutdown` | Extended shutdown with `"pause-until-parent-close"`                             |
+| `SubagentSandboxConfig` | Subagent sandbox strategy: `"none" \| "inherit" \| "own" \| { source, shutdown }` |
 | `SubagentDefinition`    | Callable subagent workflow with embedded metadata (from `defineSubagentWorkflow`) |
 | `SubagentConfig`        | Resolved subagent configuration consumed by `createSession`                  |
 | `AgentState`            | Generic agent state type                                                     |
@@ -743,9 +936,14 @@ LangChain-specific implementations:
 │  └──────────────────────────────────────────────────────────┘  │
 │                              │                                  │
 │  ┌──────────────────────────────────────────────────────────┐  │
-│  │       LLM Adapter (zeitlich/adapters/thread/langchain)           │  │
-│  │  • createLangChainAdapter (thread ops + model invoker)    │  │
-│  │  • createLangChainThreadManager (message helpers)         │  │
+│  │          Thread Adapter (zeitlich/adapters/thread/*)       │  │
+│  │  • LangChain, Google GenAI, or custom                     │  │
+│  │  • Thread ops (message storage) + model invoker            │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │         Sandbox Adapter (zeitlich/adapters/sandbox/*)      │  │
+│  │  • In-memory, Virtual, Daytona, E2B, or custom            │  │
+│  │  • Filesystem ops for agent tools                          │  │
 │  └──────────────────────────────────────────────────────────┘  │
 └─────────────────────────────────────────────────────────────────┘
                               │

package/dist/adapters/sandbox/daytona/index.cjs

@@ -47,7 +47,7 @@ var DaytonaSandboxFileSystem = class {
     await this.sandbox.fs.uploadFiles(
       files.map((f) => ({
         source: Buffer.from(f.content),
-        destination: f.path
+        destination: this.normalisePath(f.path)
       }))
     );
   }
@@ -231,6 +231,12 @@ var DaytonaSandboxProvider = class {
     } catch {
     }
   }
+  async pause(_sandboxId, _ttlSeconds) {
+    throw new SandboxNotSupportedError("pause");
+  }
+  async fork(_sandboxId) {
+    throw new Error("Not implemented");
+  }
   async snapshot(_sandboxId) {
     throw new SandboxNotSupportedError(
       "snapshot (use Daytona's native snapshot API directly)"