# codeany-ai/open-agent-sdk-typescript architecture

> Architecture diagram of the GitHub repository codeany-ai/open-agent-sdk-typescript, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codeany-ai/open-agent-sdk-typescript
- Repository: https://github.com/codeany-ai/open-agent-sdk-typescript

## Overview

1. **Repository purpose**
   - This is an **in-process TypeScript agent SDK** for Node.js 18+.
   - It exposes reusable agent APIs (`query`, `createAgent`, tool helpers, session helpers) rather than a standalone CLI or subprocess-based runtime.

2. **Public entry point**
   - `src/index.ts` is the main package surface.
   - It re-exports the agent API, tool definitions, MCP server helpers, session utilities, and likely the built-in tool set so applications can import from one module.

3. **Core execution path**
   - The main data flow is: **application prompt → Agent → QueryEngine → model API + tools/MCP → streamed messages/result**.
   - `src/agent.ts` appears to manage the reusable agent façade and session state.
   - `src/engine.ts` is the orchestration layer that runs the agentic loop, handles turns, and coordinates tool execution and model calls.

4. **Conversation/session boundary**
   - `src/session.ts` is the persistence boundary for conversation history.
   - The repo supports **multi-turn state**, **resume**, **continue**, and **forking** sessions, which means the agent state is not transient and can be reused across invocations.

5. **Model/provider integration**
   - The SDK talks to an external LLM API using streaming requests, with support for `CODEANY_API_KEY`, `CODEANY_MODEL`, and `CODEANY_BASE_URL`.
   - The architecture is provider-flexible: default Codeany API behavior, plus third-party endpoints such as OpenRouter through a base URL override.

6. **Tool subsystem**
   - Built-in tools live under `src/tools/` and cover filesystem, shell, search, planning, task management, subagents, messaging, worktrees, notebooks, LSP, web fetch/search, cron, config, and more.
   - Tool definitions are centralized in `src/tools/index.ts` and typed in `src/tools/types.ts`.
   - There are two tool-definition styles: a higher-level validated tool helper and a lower-level `defineTool` path.

7. **Tool execution and permission boundary**
   - Tool invocation is gated by permission logic, allow/deny lists, and custom callbacks.
   - This is a key security boundary: the model can request tool use, but the SDK decides whether a tool is allowed to run.
   - The README’s `permissionMode`, `allowedTools`, `disallowedTools`, and `canUseTool` are all part of this control plane.

8. **MCP integration**
   - `src/mcp/client.ts` and `src/sdk-mcp-server.ts` implement Model Context Protocol integration.
   - The SDK can connect to external MCP servers or create an **in-process MCP server** from local tools.
   - This forms a bridge between the agent loop and external capabilities exposed over stdio/SSE/HTTP/SDK-style transports.

9. **Hooks and lifecycle events**
   - `src/hooks.ts` provides lifecycle interception around the agent loop.
   - Hooks are used for policy, telemetry, logging, and behavior changes at points like session start, before/after tool use, and other agent events.

10. **Context and prompt assembly**
   - `src/utils/context.ts` and related utilities inject repository/project context into the system prompt.
   - The README highlights automatic inclusion of **Git status** and **AGENT.md/project settings**, which means prompt construction is context-aware and repo-sensitive.

11. **Context management and robustness**
   - `src/utils/compact.ts`, `src/utils/tokens.ts`, and `src/utils/retry.ts` support the reliability layer.
   - The engine uses **auto-compaction** and **micro-compaction** to stay within context limits, estimates token usage for budgeting, and retries transient API failures.

12. **File and message utilities**
   - `src/utils/fileCache.ts` suggests cached file reads to reduce repeated disk I/O.
   - `src/utils/messages.ts` and `src/types.ts` define the internal message/event formats used between the model, tools, and caller.

13. **Examples and integration surfaces**
   - The `examples/` directory is a usage map for the architecture: streaming query, multi-tool orchestration, sessions, custom prompts, MCP integration, subagents, permissions, and custom tools.
   - `examples/web/` adds a lightweight browser UI with a local server, useful for testing the agent loop and streaming interaction end-to-end.

14. **Overall architectural shape**
   - The repository is organized as a **single SDK runtime** with clear boundaries:
     - application-facing API,
     - agent/session orchestration,
     - model-provider client,
     - tool/MCP capability layer,
     - lifecycle hooks and safety controls,
     - utilities for context, caching, retry, and compaction.
   - The architecture diagram should emphasize that the agent loop runs **inside the host process** and coordinates model calls, tool execution, and persisted conversation state.

Main entry points: [`src/engine.ts`](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/engine.ts) (Engine), [`src/tools/index.ts`](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/tools/index.ts) (Tools Index), [`src/index.ts`](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/index.ts) (Index), [`src/session.ts`](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/session.ts) (Session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_index["Index<br/>package entry<br/>[index.ts]"]
end

subgraph group_runtime["Runtime"]
  node_agent["Agent<br/>façade<br/>[agent.ts]"]
  node_engine["Engine<br/>orchestrator<br/>[engine.ts]"]
  node_session[("Session<br/>state boundary<br/>[session.ts]")]
  node_hooks["Hooks<br/>lifecycle<br/>[hooks.ts]"]
  node_toolhelper["Tool Helper<br/>tool builder<br/>[tool-helper.ts]"]
end

subgraph group_capabilities["Capabilities"]
  node_toolindex["Tools Index<br/>tool registry<br/>[index.ts]"]
  node_tooltypes["Tool Types<br/>tool contracts<br/>[types.ts]"]
  node_shelltool["Shell Tool<br/>execution tool<br/>[bash.ts]"]
  node_filetools["File Tools<br/>filesystem tools<br/>[read.ts]"]
  node_tasktools["Task Tools<br/>coordination tools<br/>[task-tools.ts]"]
  node_mcpserver["MCP Server<br/>bridge<br/>[sdk-mcp-server.ts]"]
  node_mcpclient["MCP Client<br/>connector<br/>[client.ts]"]
end

subgraph group_support["Support"]
  node_contextutil["Context<br/>prompt assembly<br/>[context.ts]"]
  node_compact["Compaction<br/>context control<br/>[compact.ts]"]
  node_tokens["Tokens<br/>budgeting<br/>[tokens.ts]"]
  node_messages["Messages<br/>event model<br/>[messages.ts]"]
  node_retry["Retry<br/>resilience<br/>[retry.ts]"]
  node_filecache["File Cache<br/>io cache<br/>[fileCache.ts]"]
end

subgraph group_examples["Examples"]
  node_webexample["Web Demo<br/>example app<br/>[server.ts]"]
end

node_index -->|"re-exports"| node_agent
node_index -->|"re-exports"| node_engine
node_index -->|"re-exports"| node_session
node_index -->|"re-exports"| node_toolindex
node_index -->|"re-exports"| node_mcpserver
node_agent -->|"drives"| node_engine
node_engine -->|"loads/saves"| node_session
node_engine -->|"emits"| node_hooks
node_engine -->|"builds prompt"| node_contextutil
node_engine -->|"budgets"| node_tokens
node_engine -->|"compacts"| node_compact
node_engine -->|"retries"| node_retry
node_engine -->|"streams"| node_messages
node_engine -->|"invokes"| node_toolindex
node_toolindex -->|"typed by"| node_tooltypes
node_toolindex -->|"includes"| node_shelltool
node_toolindex -->|"includes"| node_filetools
node_toolindex -->|"includes"| node_tasktools
node_toolhelper -->|"defines"| node_tooltypes
node_mcpserver -->|"exposes"| node_toolindex
node_mcpclient -->|"extends"| node_engine
node_contextutil -->|"uses"| node_filecache
node_webexample -->|"demonstrates"| node_engine
node_webexample -->|"demonstrates"| node_session

click node_index "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/index.ts"
click node_agent "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/agent.ts"
click node_engine "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/engine.ts"
click node_session "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/session.ts"
click node_hooks "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/hooks.ts"
click node_toolhelper "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/tool-helper.ts"
click node_toolindex "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/tools/index.ts"
click node_tooltypes "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/tools/types.ts"
click node_shelltool "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/tools/bash.ts"
click node_filetools "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/tools/read.ts"
click node_tasktools "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/tools/task-tools.ts"
click node_mcpserver "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/sdk-mcp-server.ts"
click node_mcpclient "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/mcp/client.ts"
click node_contextutil "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/utils/context.ts"
click node_compact "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/utils/compact.ts"
click node_tokens "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/utils/tokens.ts"
click node_messages "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/utils/messages.ts"
click node_retry "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/utils/retry.ts"
click node_filecache "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/utils/fileCache.ts"
click node_webexample "https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/examples/web/server.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index toneBlue
class node_agent,node_engine,node_session,node_hooks,node_toolhelper toneAmber
class node_toolindex,node_tooltypes,node_shelltool,node_filetools,node_tasktools,node_mcpserver,node_mcpclient toneMint
class node_contextutil,node_compact,node_tokens,node_messages,node_retry,node_filecache toneRose
class node_webexample toneIndigo
```

## Components

### Public API

Package entrypoints and reusable agent surface.

- [Index](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/index.ts): package entry · Main re-export surface for the SDK. · `src/index.ts`

### Runtime

Agent orchestration, sessions, hooks, and execution loop.

- [Agent](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/agent.ts): façade · Reusable agent interface and session-facing API. · `src/agent.ts`
- [Engine](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/engine.ts): orchestrator · Runs the agent loop, turns, model calls, and tool coordination. · `src/engine.ts`
- [Session](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/session.ts): state boundary · Conversation persistence, resume, continue, and fork support. · `src/session.ts`
- [Hooks](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/hooks.ts): lifecycle · Interception points for policy, telemetry, and behavior changes. · `src/hooks.ts`
- [Tool Helper](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/tool-helper.ts): tool builder · Higher-level tool definition and validation helpers. · `src/tool-helper.ts`

### Capabilities

Tooling and MCP integration used by the agent loop.

- [Tools Index](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/tools/index.ts): tool registry · Central export and composition point for built-in tools. · `src/tools/index.ts`
- [Tool Types](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/tools/types.ts): tool contracts · Shared tool definitions and typing for the tool layer. · `src/tools/types.ts`
- [Shell Tool](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/tools/bash.ts): execution tool · Representative local execution capability for command and file operations. · `src/tools/bash.ts`
- [File Tools](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/tools/read.ts): filesystem tools · Read, write, edit, glob, and grep style file capabilities. · `src/tools/read.ts`
- [Task Tools](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/tools/task-tools.ts): coordination tools · Planning, tasks, todos, messaging, and subagent workflows. · `src/tools/task-tools.ts`
- [MCP Server](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/sdk-mcp-server.ts): bridge · In-process MCP server exposure for local tools. · `src/sdk-mcp-server.ts`
- [MCP Client](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/mcp/client.ts): connector · Client integration for external MCP servers and transports. · `src/mcp/client.ts`

### Support

Context, messaging, caching, retry, and token utilities.

- [Context](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/utils/context.ts): prompt assembly · Builds repo-aware system context from project signals. · `src/utils/context.ts`
- [Compaction](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/utils/compact.ts): context control · Auto-compaction and micro-compaction for long runs. · `src/utils/compact.ts`
- [Tokens](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/utils/tokens.ts): budgeting · Token estimation and context budgeting helpers. · `src/utils/tokens.ts`
- [Messages](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/utils/messages.ts): event model · Internal message and event shapes for model/tool exchange. · `src/utils/messages.ts`
- [Retry](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/utils/retry.ts): resilience · Transient failure retry behavior for API and tool workflows. · `src/utils/retry.ts`
- [File Cache](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/src/utils/fileCache.ts): io cache · Cached file reads to reduce repeated disk access. · `src/utils/fileCache.ts`

### Examples

Usage samples and browser demo.

- [Web Demo](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/examples/web/server.ts): example app · Lightweight browser UI and local server for end-to-end testing. · `examples/web/server.ts`

## Connections

- Index → Agent: re-exports · Package surface exposes the agent API.
- Index → Engine: re-exports · Package surface exposes orchestration helpers.
- Index → Session: re-exports · Package surface exposes session helpers.
- Index → Tools Index: re-exports · Package surface exposes built-in tools.
- Index → MCP Server: re-exports · Package surface exposes MCP server helpers.
- Agent → Engine: drives · Agent delegates execution to the engine loop.
- Engine → Session: loads/saves · Engine reads and persists conversation state.
- Engine → Hooks: emits · Lifecycle events flow through hooks.
- Engine → Context: builds prompt · Engine assembles repo-aware context for the system prompt.
- Engine → Tokens: budgets · Engine estimates and manages context usage.
- Engine → Compaction: compacts · Engine triggers compaction when context grows.
- Engine → Retry: retries · Engine retries transient provider failures.
- Engine → Messages: streams · Engine exchanges structured messages with callers.
- Engine → Tools Index: invokes · Engine selects built-in tools for model requests.
- Tools Index → Tool Types: typed by · Tool registry uses shared tool contracts.
- Tools Index → Shell Tool: includes · Registry aggregates shell capability.
- Tools Index → File Tools: includes · Registry aggregates file manipulation capabilities.
- Tools Index → Task Tools: includes · Registry aggregates planning and coordination tools.
- Tool Helper → Tool Types: defines · Higher-level helper builds validated tool definitions.
- MCP Server → Tools Index: exposes · Local tools can be surfaced through MCP.
- MCP Client → Engine: extends · External MCP capabilities feed the agent loop.
- Context → File Cache: uses · Context assembly reuses cached file reads.
- Web Demo → Engine: demonstrates · Browser demo exercises the streaming agent runtime.
- Web Demo → Session: demonstrates · Demo shows multi-turn state handling.
