zeitlich 0.2.9 → 0.2.12

package/README.md

@@ -29,39 +29,44 @@ Temporal solves these problems for workflows. Zeitlich brings these guarantees t
 - **Lifecycle hooks** — Pre/post tool execution, session start/end
 - **Subagent support** — Spawn child agents as Temporal child workflows
 - **Filesystem utilities** — In-memory or custom providers for file operations
-- **Model flexibility** — Use any LLM provider via LangChain
+- **Model flexibility** — Framework-agnostic model invocation with adapters for LangChain (and more coming)
 
 ## LLM Integration
 
-Zeitlich uses [LangChain](https://js.langchain.com/) as the abstraction layer for LLM execution. This gives you:
+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.
+
+### LangChain Adapter (`zeitlich/adapters/langchain`)
+
+The built-in LangChain adapter gives you:
 
 - **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
-- **Soon** — Support native provider SDKs directly
 
 ```typescript
 import { ChatAnthropic } from "@langchain/anthropic";
-import { ChatOpenAI } from "@langchain/openai";
-import { ChatGoogleGenerativeAI } from "@langchain/google-genai";
+import { createLangChainAdapter } from "zeitlich/adapters/langchain";
+import { createRunAgentActivity } from "zeitlich";
 
-// Use any LangChain chat model
-const anthropic = new ChatAnthropic({ model: "claude-sonnet-4-20250514" });
-const openai = new ChatOpenAI({ model: "gpt-4o" });
-const google = new ChatGoogleGenerativeAI({ model: "gemini-1.5-pro" });
+const adapter = createLangChainAdapter({
+  redis,
+  model: new ChatAnthropic({ model: "claude-sonnet-4-20250514" }),
+});
 
-// Pass to invokeModel in your activity
-return {
-  runAgent: (config) => invokeModel({ config, model: anthropic, redis, client }),
-};
+export function createActivities(client: WorkflowClient) {
+  return {
+    ...adapter.threadOps,
+    runAgent: createRunAgentActivity(client, adapter.invoker),
+  };
+}
 ```
 
 Install the LangChain package for your chosen provider:
 
 ```bash
-npm install @langchain/anthropic  # Anthropic
-npm install @langchain/openai     # OpenAI
-npm install @langchain/google-genai # Google
+npm install @langchain/core @langchain/anthropic  # Anthropic
+npm install @langchain/core @langchain/openai     # OpenAI
+npm install @langchain/core @langchain/google-genai # Google
 ```
 
 ## Installation
@@ -73,6 +78,7 @@ npm install zeitlich ioredis
 **Peer dependencies:**
 
 - `ioredis` >= 5.0.0
+- `@langchain/core` >= 1.0.0 (optional — only needed when using `zeitlich/adapters/langchain`)
 
 **Required infrastructure:**
 
@@ -81,21 +87,37 @@ npm install zeitlich ioredis
 
 ## Import Paths
 
-Zeitlich provides two entry points to work with Temporal's workflow sandboxing:
+Zeitlich provides three entry points:
 
 ```typescript
-// In workflow files - no external dependencies (Redis, LangChain, etc.)
+// In workflow files — no external dependencies (Redis, LangChain, etc.)
 import {
   createSession,
   createAgentStateManager,
   askUserQuestionTool,
+  bashTool,
+  defineTool,
+  type SubagentWorkflow,
+  type ModelInvoker,
 } from "zeitlich/workflow";
 
-// In activity files and worker setup - full functionality
-import { ZeitlichPlugin, invokeModel, toTree } from "zeitlich";
+// In activity files and worker setup — framework-agnostic core
+import {
+  createRunAgentActivity,
+  createBashHandler,
+  createAskUserQuestionHandler,
+  toTree,
+} from "zeitlich";
+
+// LangChain adapter — unified adapter for LLM invocation and thread management
+import { createLangChainAdapter } from "zeitlich/adapters/langchain";
 ```
 
-**Why?** Temporal workflows run in an isolated V8 sandbox that cannot import modules with Node.js APIs or external dependencies. The `/workflow` entry point contains only pure TypeScript code safe for workflow use.
+**Why three entry points?**
+
+- `zeitlich/workflow` — Pure TypeScript, safe for Temporal's V8 sandbox
+- `zeitlich` — Activity-side utilities (Redis, filesystem), framework-agnostic
+- `zeitlich/adapters/langchain` — LangChain-specific adapter (model invocation + thread management)
 
 ## Examples
 
@@ -118,54 +140,28 @@ export const searchTool: ToolDefinition<"Search", typeof searchSchema> = {
 };
 ```
 
-### 2. Create Activities
+### 2. Create the Workflow
 
-```typescript
-import type Redis from "ioredis";
-import type { WorkflowClient } from "@temporalio/client";
-import { ChatAnthropic } from "@langchain/anthropic";
-import { invokeModel, type InvokeModelConfig } from "zeitlich";
-
-export const createActivities = ({
-  redis,
-  client,
-}: {
-  redis: Redis;
-  client: WorkflowClient;
-}) => {
-  const model = new ChatAnthropic({
-    model: "claude-sonnet-4-20250514",
-    maxTokens: 4096,
-  });
-
-  return {
-    runAgent: (config: InvokeModelConfig) =>
-      invokeModel({ config, model, redis, client }),
-
-    handleSearchResult: async ({ args }) => {
-      const results = await performSearch(args.query);
-      return { result: { results } };
-    },
-  };
-};
-
-export type MyActivities = ReturnType<typeof createActivities>;
-```
-
-### 3. Create the Workflow
+The system prompt is set via `createAgentStateManager`'s `initialState`, and agent config fields (`agentName`, `maxTurns`, etc.) are spread into `createSession`.
 
 ```typescript
 import { proxyActivities, workflowInfo } from "@temporalio/workflow";
 import {
   createAgentStateManager,
   createSession,
+  askUserQuestionTool,
+  bashTool,
   defineTool,
-  proxyDefaultThreadOps,
 } from "zeitlich/workflow";
 import { searchTool } from "./tools";
 import type { MyActivities } from "./activities";
 
-const { runAgent, handleSearchResult } = proxyActivities<MyActivities>({
+const {
+  runAgentActivity,
+  searchHandlerActivity,
+  bashHandlerActivity,
+  askUserQuestionHandlerActivity,
+} = proxyActivities<MyActivities>({
   startToCloseTimeout: "30m",
   retry: {
     maximumAttempts: 6,
@@ -179,51 +175,109 @@ const { runAgent, handleSearchResult } = proxyActivities<MyActivities>({
 export async function myAgentWorkflow({ prompt }: { prompt: string }) {
   const { runId } = workflowInfo();
 
-  const stateManager = createAgentStateManager({});
+  const stateManager = createAgentStateManager({
+    initialState: {
+      systemPrompt: "You are a helpful assistant.",
+    },
+    agentName: "my-agent",
+  });
 
   const session = await createSession({
-    threadId: runId,
     agentName: "my-agent",
     maxTurns: 20,
-    systemPrompt: "You are a helpful assistant.",
-    runAgent,
-    threadOps: proxyDefaultThreadOps(),
+    threadId: runId,
+    runAgent: runAgentActivity,
     buildContextMessage: () => [{ type: "text", text: prompt }],
     tools: {
       Search: defineTool({
         ...searchTool,
-        handler: handleSearchResult,
+        handler: searchHandlerActivity,
+      }),
+      AskUserQuestion: defineTool({
+        ...askUserQuestionTool,
+        handler: askUserQuestionHandlerActivity,
+        hooks: {
+          onPostToolUse: () => {
+            stateManager.waitForInput();
+          },
+        },
+      }),
+      Bash: defineTool({
+        ...bashTool,
+        handler: bashHandlerActivity,
       }),
     },
   });
 
-  await session.runSession({ stateManager });
-  return stateManager.getCurrentState();
+  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.
+
+```typescript
+import type Redis from "ioredis";
+import type { WorkflowClient } from "@temporalio/client";
+import { ChatAnthropic } from "@langchain/anthropic";
+import {
+  createBashHandler,
+  createAskUserQuestionHandler,
+  createRunAgentActivity,
+} from "zeitlich";
+import { createLangChainAdapter } from "zeitlich/adapters/langchain";
+
+export const createActivities = ({
+  redis,
+  client,
+}: {
+  redis: Redis;
+  client: WorkflowClient;
+}) => {
+  const { threadOps, invoker } = createLangChainAdapter({
+    redis,
+    model: new ChatAnthropic({
+      model: "claude-sonnet-4-20250514",
+      maxTokens: 4096,
+    }),
+  });
+
+  return {
+    ...threadOps,
+    runAgentActivity: createRunAgentActivity(client, invoker),
+    searchHandlerActivity: async (args: { query: string }) => ({
+      toolResponse: JSON.stringify(await performSearch(args.query)),
+      data: null,
+    }),
+    bashHandlerActivity: createBashHandler({ fs: inMemoryFileSystem }),
+    askUserQuestionHandlerActivity: createAskUserQuestionHandler(),
+  };
+};
+
+export type MyActivities = ReturnType<typeof createActivities>;
+```
+
 ### 4. Set Up the Worker
 
 ```typescript
 import { Worker, NativeConnection } from "@temporalio/worker";
-import { Client } from "@temporalio/client";
-import { ZeitlichPlugin } from "zeitlich";
 import Redis from "ioredis";
+import { fileURLToPath } from "node:url";
 import { createActivities } from "./activities";
 
 async function run() {
   const connection = await NativeConnection.connect({
     address: "localhost:7233",
   });
-  const client = new Client({ connection });
   const redis = new Redis({ host: "localhost", port: 6379 });
 
   const worker = await Worker.create({
-    plugins: [new ZeitlichPlugin({ redis })],
     connection,
     taskQueue: "my-agent",
-    workflowsPath: require.resolve("./workflows"),
-    activities: createActivities({ redis, client: client.workflow }),
+    workflowsPath: fileURLToPath(new URL("./workflows.ts", import.meta.url)),
+    activities: createActivities({ redis, client }),
   });
 
   await worker.run();
@@ -234,13 +288,17 @@ async function run() {
 
 ### Agent State Manager
 
-Manages workflow state with automatic versioning and status tracking:
+Manages workflow state with automatic versioning and status tracking. Requires `agentName` to register Temporal query/update handlers, and accepts an optional `initialState` for system prompt and custom fields:
 
 ```typescript
 import { createAgentStateManager } from "zeitlich/workflow";
 
 const stateManager = createAgentStateManager({
-  customField: "value",
+  initialState: {
+    systemPrompt: "You are a helpful assistant.",
+    customField: "value",
+  },
+  agentName: "my-agent",
 });
 
 // State operations
@@ -310,63 +368,174 @@ const session = await createSession({
 
 ### Subagents
 
-Spawn child agents as Temporal child workflows:
+Spawn child agents as Temporal child workflows. Each subagent is a workflow typed with `SubagentWorkflow` that returns `{ toolResponse, data }`:
 
 ```typescript
-// Define subagent workflows (each is a Temporal workflow that returns string | null)
+import { proxyActivities, workflowInfo } from "@temporalio/workflow";
+import {
+  createAgentStateManager,
+  createSession,
+  type SubagentWorkflow,
+} from "zeitlich/workflow";
+import { agentConfig } from "./config";
+import type { createResearcherActivities } from "./activities";
+
+const { runResearcherActivity } = proxyActivities<
+  ReturnType<typeof createResearcherActivities>
+>({ startToCloseTimeout: "30m", heartbeatTimeout: "5m" });
+
+// Subagent workflow typed as SubagentWorkflow
+export const researcherSubagentWorkflow: SubagentWorkflow = async ({
+  prompt,
+}) => {
+  const { runId } = workflowInfo();
+
+  const stateManager = createAgentStateManager({
+    initialState: { systemPrompt: agentConfig.systemPrompt },
+    agentName: agentConfig.agentName,
+  });
+
+  const session = await createSession({
+    ...agentConfig,
+    threadId: runId,
+    runAgent: runResearcherActivity,
+    buildContextMessage: () => [{ type: "text", text: prompt }],
+  });
+
+  const { finalMessage } = await session.runSession({ stateManager });
+  return {
+    toolResponse: finalMessage ? extractText(finalMessage) : "No response",
+    data: null,
+  };
+};
+
+// Register the subagent for the parent workflow
 export const researcherSubagent = {
-  name: "researcher",
-  description: "Researches topics and returns findings",
-  workflow: researcherWorkflow,
+  agentName: agentConfig.agentName,
+  description: agentConfig.description,
+  workflow: researcherSubagentWorkflow,
 };
+```
+
+In the parent workflow, pass subagents to `createSession`:
 
-// In the main agent workflow
+```typescript
 const session = await createSession({
   // ... other config
   subagents: [researcherSubagent, codeReviewerSubagent],
 });
 ```
 
-The `Task` tool is automatically added when subagents are configured, allowing the agent to spawn child workflows.
+The `Subagent` tool is automatically added when subagents are configured, allowing the LLM to spawn child workflows.
 
-### Filesystem Utilities
+### Thread Continuation
 
-Built-in support for file operations. Use `buildFileTree` to generate a file tree string that's included in the agent's context:
+By default, each session initializes a fresh thread. To continue an existing thread (e.g., resuming a conversation after a workflow completes), pass `continueThread: true` along with the previous `threadId`:
 
 ```typescript
-// In activities
-export const createActivities = () => ({
-  generateFileTree: async (): Promise<string> => {
-    // Return a formatted file tree string
-    return toTree("/path/to/workspace");
-  },
-});
+import { createSession } from "zeitlich/workflow";
 
-// In workflow
+// First run — threadId defaults to getShortId() if omitted
 const session = await createSession({
+  // threadId is optional, auto-generated if not provided
+  // ... other config
+});
+
+// Later — new workflow picks up the same thread
+const resumedSession = await createSession({
+  threadId: savedThreadId, // pass the ID from the first run
+  continueThread: true, // skip thread init + system prompt
   // ... other config
-  buildFileTree: generateFileTree, // Called at session start
 });
 ```
 
-For more advanced file operations, use the built-in tool handler factories:
+`getShortId()` produces compact, workflow-deterministic IDs (~12 base-62 chars) that are more token-efficient than UUIDs.
+
+#### Subagent Thread Continuation
+
+Subagents can opt in to thread continuation via `allowThreadContinuation`. When enabled, the parent agent can pass a `threadId` to resume a previous subagent conversation:
 
 ```typescript
-import { createGlobHandler, createEditHandler, toTree } from "zeitlich";
+import { getShortId, type SubagentWorkflow } from "zeitlich/workflow";
 
-export const createActivities = () => ({
-  generateFileTree: () => toTree("/workspace"),
-  globHandlerActivity: createGlobHandler("/workspace"),
-  editHandlerActivity: createEditHandler("/workspace"),
-});
+// Subagent workflow that supports continuation
+export const researcherWorkflow: SubagentWorkflow = async ({
+  prompt,
+  threadId,
+}) => {
+  const effectiveThreadId = threadId ?? getShortId();
+
+  const session = await createSession({
+    threadId: effectiveThreadId,
+    continueThread: !!threadId,
+    // ... other config
+  });
+
+  const { finalMessage } = await session.runSession({ stateManager });
+  return {
+    toolResponse: finalMessage ? extractText(finalMessage) : "No response",
+    data: null,
+    threadId: effectiveThreadId,
+  };
+};
+
+// Register with allowThreadContinuation
+export const researcherSubagent = {
+  agentName: "Researcher",
+  description: "Researches topics and gathers information",
+  workflow: researcherWorkflow,
+  allowThreadContinuation: true,
+};
 ```
 
-`toTree` also accepts an in-memory filesystem object (e.g. from [`just-bash`](https://github.com/nicholasgasior/just-bash)):
+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)).
+
+`toTree` generates a file tree string from an `IFileSystem` instance:
 
 ```typescript
 import { toTree } from "zeitlich";
 
-const fileTree = toTree(inMemoryFileSystem);
+// In activities - generate a file tree string for agent context
+export const createActivities = ({ redis, client }) => ({
+  generateFileTreeActivity: async () => toTree(inMemoryFileSystem),
+  // ...
+});
+```
+
+Use the tree in `buildContextMessage` to give the agent filesystem awareness:
+
+```typescript
+// In workflow
+const fileTree = await generateFileTreeActivity();
+
+const session = await createSession({
+  // ... other config
+  buildContextMessage: () => [
+    { type: "text", text: `Files in the filesystem: ${fileTree}` },
+    { type: "text", text: prompt },
+  ],
+});
+```
+
+For file operations, use the built-in tool handler factories. All handlers accept an `IFileSystem`:
+
+```typescript
+import {
+  createGlobHandler,
+  createEditHandler,
+  createBashHandler,
+} from "zeitlich";
+
+export const createActivities = ({ redis, client }) => ({
+  generateFileTreeActivity: async () => toTree(inMemoryFileSystem),
+  globHandlerActivity: createGlobHandler(inMemoryFileSystem),
+  editHandlerActivity: createEditHandler(inMemoryFileSystem),
+  bashHandlerActivity: createBashHandler({ fs: inMemoryFileSystem }),
+});
 ```
 
 ### Built-in Tools
@@ -429,33 +598,50 @@ const session = await createSession({
 
 Safe for use in Temporal workflow files:
 
-| Export                    | Description                                                                                    |
-| ------------------------- | ---------------------------------------------------------------------------------------------- |
-| `createSession`           | Creates an agent session with tools, prompts, subagents, and hooks                             |
-| `createAgentStateManager` | Creates a state manager for workflow state                                                     |
-| `createToolRouter`        | Creates a tool router (used internally by session, or for advanced use)                        |
-| `createTaskTool`          | Creates the Task tool for subagent support                                                     |
-| Tool definitions          | `askUserQuestionTool`, `globTool`, `grepTool`, `readTool`, `writeTool`, `editTool`, `bashTool` |
-| Task tools                | `taskCreateTool`, `taskGetTool`, `taskListTool`, `taskUpdateTool` for workflow task management |
-| Types                     | All TypeScript types and interfaces                                                            |
+| Export                    | Description                                                                                            |
+| ------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `createSession`           | Creates an agent session with tools, prompts, subagents, and hooks                                     |
+| `createAgentStateManager` | Creates a state manager for workflow state with query/update handlers                                  |
+| `createToolRouter`        | Creates a tool router (used internally by session, or for advanced use)                                |
+| `defineTool`              | Identity function for type-safe tool definition with handler and hooks                                 |
+| `defineSubagent`          | Identity function for type-safe subagent configuration                                                 |
+| `getShortId`              | Generate a compact, workflow-deterministic identifier (base-62, 12 chars)                              |
+| `createSubagentTool`      | Creates the Subagent tool for spawning child workflows                                                 |
+| Tool definitions          | `askUserQuestionTool`, `globTool`, `grepTool`, `readFileTool`, `writeFileTool`, `editTool`, `bashTool` |
+| Task tools                | `taskCreateTool`, `taskGetTool`, `taskListTool`, `taskUpdateTool` for workflow task management         |
+| Types                     | `SubagentWorkflow`, `ToolDefinition`, `ToolWithHandler`, `AgentConfig`, `SessionConfig`, etc.          |
 
 ### Activity Entry Point (`zeitlich`)
 
-For use in activities, worker setup, and Node.js code:
+Framework-agnostic utilities for activities, worker setup, and Node.js code:
+
+| Export                    | Description                                                                                   |
+| ------------------------- | --------------------------------------------------------------------------------------------- |
+| `createRunAgentActivity`  | Wraps a `ModelInvoker` into a `RunAgentActivity` with automatic tool loading                  |
+| `createThreadManager`     | Generic Redis-backed thread manager factory                                                   |
+| `toTree`                  | Generate file tree string from an `IFileSystem` instance                                      |
+| Tool handlers             | `createGlobHandler`, `createEditHandler`, `createBashHandler`, `createAskUserQuestionHandler` |
+
+### LangChain Adapter Entry Point (`zeitlich/adapters/langchain`)
 
-| Export                   | Description                                                                       |
-| ------------------------ | --------------------------------------------------------------------------------- |
-| `ZeitlichPlugin`         | Temporal worker plugin that registers shared activities                           |
-| `createSharedActivities` | Creates thread management activities                                              |
-| `invokeModel`            | Core LLM invocation utility (requires Redis + LangChain)                          |
-| `toTree`                 | Generate file tree string from a directory path                                   |
-| Tool handlers            | `createGlobHandler`, `createEditHandler`, `createBashHandler`, `createAskUserQuestionHandler` |
+LangChain-specific implementations:
+
+| Export                              | Description                                                            |
+| ----------------------------------- | ---------------------------------------------------------------------- |
+| `createLangChainAdapter`            | Unified adapter returning `threadOps`, `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                  |
 
 ### Types
 
 | Export                  | Description                                                                  |
 | ----------------------- | ---------------------------------------------------------------------------- |
 | `AgentStatus`           | `"RUNNING" \| "WAITING_FOR_INPUT" \| "COMPLETED" \| "FAILED" \| "CANCELLED"` |
+| `MessageContent`        | Framework-agnostic message content (`string \| ContentPart[]`)               |
+| `ToolMessageContent`    | Content returned by a tool handler (`string`)                                |
+| `ModelInvoker`          | Generic model invocation contract                                            |
+| `ModelInvokerConfig`    | Configuration passed to a model invoker                                      |
 | `ToolDefinition`        | Tool definition with name, description, and Zod schema                       |
 | `ToolWithHandler`       | Tool definition combined with its handler                                    |
 | `SubagentConfig`        | Configuration for subagent workflows                                         |
@@ -468,25 +654,26 @@ For use in activities, worker setup, and Node.js code:
 ┌─────────────────────────────────────────────────────────────────┐
 │                        Temporal Worker                          │
 │  ┌──────────────────────────────────────────────────────────┐  │
-│  │                    ZeitlichPlugin                         │  │
-│  │  • Registers shared activities (thread management)        │  │
-│  └──────────────────────────────────────────────────────────┘  │
-│                              │                                  │
-│  ┌──────────────────────────────────────────────────────────┐  │
-│  │                      Workflow                             │  │
+│  │              Workflow (zeitlich/workflow)                  │  │
 │  │  ┌────────────────┐  ┌───────────────────────────────┐   │  │
 │  │  │ State Manager  │  │           Session             │   │  │
 │  │  │ • Status       │  │  • Agent loop                 │   │  │
 │  │  │ • Turns        │  │  • Tool routing & hooks       │   │  │
 │  │  │ • Custom state │  │  • Prompts (system, context)  │   │  │
 │  │  └────────────────┘  │  • Subagent coordination      │   │  │
-│  │                      └───────────────────────────────────┘   │  │
+│  │                      └───────────────────────────────┘   │  │
 │  └──────────────────────────────────────────────────────────┘  │
 │                              │                                  │
 │  ┌──────────────────────────────────────────────────────────┐  │
-│  │                      Activities                           │  │
-│  │  • runAgent (LLM invocation)                              │  │
+│  │                Activities (zeitlich)                       │  │
 │  │  • Tool handlers (search, file ops, bash, etc.)           │  │
+│  │  • Generic thread manager (BaseThreadManager<T>)          │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│                              │                                  │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │       LLM Adapter (zeitlich/adapters/langchain)           │  │
+│  │  • createLangChainAdapter (thread ops + model invoker)    │  │
+│  │  • createLangChainThreadManager (message helpers)         │  │
 │  └──────────────────────────────────────────────────────────┘  │
 └─────────────────────────────────────────────────────────────────┘
                               │