zeitlich 0.2.22 → 0.2.24

package/README.md

@@ -28,20 +28,42 @@ 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 |
+| Bedrock | `zeitlich/adapters/sandbox/bedrock` | AWS Bedrock AgentCore Code Interpreter |
+
+### Example: LangChain Adapter
 
 ```typescript
 import { ChatAnthropic } from "@langchain/anthropic";
@@ -55,20 +77,13 @@ const adapter = createLangChainAdapter({
 
 export function createActivities(client: WorkflowClient) {
   return {
-    // scope must match the workflow name (used by the proxy to resolve activity names)
     ...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
 
@@ -79,7 +94,9 @@ 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)
+- `@aws-sdk/client-bedrock-agentcore` >= 3.900.0 (optional — only when using the Bedrock adapter)
 
 **Required infrastructure:**
 
@@ -91,7 +108,7 @@ npm install zeitlich ioredis
 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,
@@ -99,7 +116,7 @@ import {
   bashTool,
 } from "zeitlich/workflow";
 
-// Adapter-specific workflow proxies (auto-scoped to current 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";
 
@@ -111,7 +128,7 @@ import {
   bashHandler,
 } from "zeitlich";
 
-// LangChain adapter — activity-side (thread management + model invocation)
+// Thread adapter — activity-side
 import { createLangChainAdapter } from "zeitlich/adapters/thread/langchain";
 ```
 
@@ -146,7 +163,7 @@ 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";
@@ -158,10 +175,12 @@ import {
   bashTool,
   defineTool,
 } from "zeitlich/workflow";
-import { proxyLangChainThreadOps } from "zeitlich/adapters/thread/langchain/workflow";
 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,
@@ -190,12 +209,12 @@ export const myAgentWorkflow = defineWorkflow(
       agentName: "my-agent",
     });
 
-    // threadOps auto-scopes to "myAgentWorkflow" via workflowInfo().workflowType
     const session = await createSession({
       agentName: "my-agent",
       maxTurns: 20,
-      threadId: runId,
+      thread: { mode: "new", threadId: runId },
       threadOps: proxyLangChainThreadOps(),
+      sandboxOps: proxyInMemorySandboxOps(),
       runAgent: runAgentActivity,
       buildContextMessage: () => [{ type: "text", text: prompt }],
       tools: {
@@ -228,20 +247,26 @@ export const myAgentWorkflow = defineWorkflow(
 
 ### 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,
@@ -258,8 +283,8 @@ export const createActivities = ({
   });
 
   return {
-    // "myAgentWorkflow" must match the workflow name in defineWorkflow()
     ...adapter.createActivities("myAgentWorkflow"),
+    ...sandboxManager.createActivities("myAgentWorkflow"),
     runAgentActivity: createRunAgentActivity(client, adapter.invoker),
     searchHandlerActivity: async (args: { query: string }) => ({
       toolResponse: JSON.stringify(await performSearch(args.query)),
@@ -411,7 +436,7 @@ 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 }],
@@ -439,7 +464,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),
@@ -454,39 +479,218 @@ 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. A skill directory can also contain **resource files** — supporting documents, templates, or data that the agent can read from the sandbox filesystem:
+
+```
+skills/
+├── code-review/
+│   ├── SKILL.md
+│   └── resources/
+│       └── checklist.md
+├── pdf-processing/
+│   ├── SKILL.md
+│   └── templates/
+│       └── extraction-prompt.txt
+```
+
+```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. Read the checklist from `resources/checklist.md`
+4. ...
+```
+
+Required fields: `name` and `description`. Optional: `license`, `compatibility`, `allowed-tools` (space-delimited), `metadata` (key-value map).
+
+Resource files are any non-`SKILL.md` files inside the skill directory (discovered recursively). When loaded via `FileSystemSkillProvider`, their contents are stored in `skill.resourceContents` — a `Record<string, string>` keyed by relative path (e.g. `"resources/checklist.md"`).
+
+#### Loading Skills
+
+Use `FileSystemSkillProvider` to load skills from a directory. It accepts any `SandboxFileSystem` implementation. `loadAll()` eagerly reads `SKILL.md` instructions **and** all resource file contents into each `Skill` object:
+
+```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();
+// Each skill has: { name, description, instructions, resourceContents }
+// resourceContents: { "resources/checklist.md": "...", ... }
+```
 
-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`:
+**Loading from the local filesystem (activity-side):** Use `NodeFsSandboxFileSystem` to read skills from the worker's disk. This is the simplest option when skill files are bundled alongside your application code:
+
+```typescript
+import { NodeFsSandboxFileSystem, FileSystemSkillProvider } from "zeitlich";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fs = new NodeFsSandboxFileSystem(join(__dirname, "skills"));
+const skillProvider = new FileSystemSkillProvider(fs, "/");
+const skills = await skillProvider.loadAll();
+```
+
+For lightweight discovery without reading file contents, use `listSkills()`:
+
+```typescript
+const metadata = await skillProvider.listSkills();
+// SkillMetadata[] — name, description, location only
+```
+
+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:
+
+1. Registers a `ReadSkill` tool whose description lists all available skills — the agent discovers them through the tool definition and loads instructions on demand.
+2. Seeds `resourceContents` into the sandbox as `initialFiles` (when `sandboxOps` is configured), so the agent can read resource files with its `Read` tool without any extra setup.
 
 ```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 plus a list of available resource file paths. The handler runs directly in the workflow — no activity needed. Resource file contents are not included in the `ReadSkill` response (progressive disclosure); the agent reads them from the sandbox filesystem on demand.
+
+#### 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
+```
 
-// Later — new workflow forks the previous thread
+### 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:
+
+| 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.
 
-Subagents can opt in to thread continuation via `allowThreadContinuation`. When enabled, the parent agent can pass a `threadId` to resume a previous subagent conversation:
+#### Subagent Thread & Sandbox Config
+
+Subagents configure thread and sandbox strategies via `defineSubagent`:
 
 ```typescript
-import { defineSubagentWorkflow, defineSubagent, createSession } from "zeitlich/workflow";
-import { proxyLangChainThreadOps } from "zeitlich/adapters/thread/langchain/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",
@@ -494,28 +698,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)).
@@ -632,6 +825,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
@@ -691,7 +885,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`)
 
@@ -704,11 +901,13 @@ 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`)            |
+| `NodeFsSandboxFileSystem`   | `node:fs` adapter for `SandboxFileSystem` — read skills from the worker's local disk              |
+| `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                                                            |
 | ----------------------------------- | ---------------------------------------------------------------------- |
@@ -717,6 +916,15 @@ LangChain-specific implementations:
 | `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                                                                  |
@@ -731,6 +939,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                                                     |
@@ -748,6 +961,7 @@ LangChain-specific implementations:
 │  │  │ • Turns        │  │  • Tool routing & hooks       │   │  │
 │  │  │ • Custom state │  │  • Prompts (system, context)  │   │  │
 │  │  └────────────────┘  │  • Subagent coordination      │   │  │
+│  │                      │  • Skills (progressive load)   │   │  │
 │  │                      └───────────────────────────────┘   │  │
 │  └──────────────────────────────────────────────────────────┘  │
 │                              │                                  │
@@ -758,9 +972,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, Bedrock, or custom   │  │
+│  │  • Filesystem ops for agent tools                          │  │
 │  └──────────────────────────────────────────────────────────┘  │
 └─────────────────────────────────────────────────────────────────┘
                               │