# openrouterteam/typescript-agent architecture

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

- Interactive diagram: https://gitdiagram.com/openrouterteam/typescript-agent
- Repository: https://github.com/openrouterteam/typescript-agent

## Overview

The repository provides an OpenRouter TypeScript agent toolkit, with MCP support in the agent package and a separate compatibility facade. The main workflow starts with an application calling `OpenRouter.callModel`, then proceeds through model request/response handling, streamed results and tool execution; callers can resume asynchronous tool results into conversation state. Additional capabilities include hooks, tool context, loop detection, and MCP server connections and tool conversion. Edges reflect the supplied excerpts, SOURCE INDEX references, or README; unsampled subsystems are represented conservatively.

Main entry points: [`packages/agent/src/lib/model-result.ts`](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/model-result.ts) (Response lifecycle), [`packages/agent/src/inner-loop/call-model.ts`](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/inner-loop/call-model.ts) (Model call setup), [`packages/agent/src/lib/tool-executor.ts`](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/tool-executor.ts) (Tool executor), [`packages/agent/src/mcp/rehydrate.ts`](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/mcp/rehydrate.ts) (MCP rehydration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent runtime"]
  node_openrouter["OpenRouter client<br/>[openrouter.ts]"]
  node_callmodel["Model call setup<br/>[call-model.ts]"]
  node_modelresult["Response lifecycle<br/>[model-result.ts]"]
  node_conversation["Conversation state"]
  node_streaming["Stream transforms"]
  node_hooks["Hook management<br/>[hooks-manager.ts]"]
  node_doomloop["Loop detection<br/>[doom-loop.ts]"]
end

subgraph group_tools["Tool execution"]
  node_tooltypes["Tool contracts<br/>[tool-types.ts]"]
  node_toolcheck["Tool checks<br/>[tool-check.ts]"]
  node_toolcontext["Tool context<br/>[tool-context.ts]"]
  node_toolexec["Tool executor<br/>[tool-executor.ts]"]
  node_toolorchestrator["Tool orchestration"]
  node_asynctask["Async tool tasks<br/>[tool-task.ts]"]
  node_resume["Resume tool results"]
end

subgraph group_mcp["MCP integration"]
  node_mcpconnection["MCP connections<br/>[mcp-connection.ts]"]
  node_mcpauth["MCP authentication<br/>[auth-resolver.ts]"]
  node_mcprehydrate["MCP rehydration<br/>[rehydrate.ts]"]
  node_mcpcache[("MCP cache<br/>[cache-store.ts]")]
  node_mcptoolwrap["MCP tool wrapper<br/>[tool-wrapper.ts]"]
end

subgraph group_compat["Compatibility facade"]
  node_facade["MCP facade<br/>[index.ts]"]
end

node_app(("Application"))
node_mcpserver{{"MCP server"}}

node_app -->|"calls"| node_openrouter
node_openrouter -->|"delegates to"| node_callmodel
node_callmodel -->|"creates"| node_modelresult
node_modelresult -->|"consumes stream"| node_streaming
node_modelresult -->|"uses state"| node_conversation
node_modelresult -->|"emits hooks"| node_hooks
node_modelresult -->|"checks loops"| node_doomloop
node_callmodel -->|"filters tools"| node_toolcheck
node_callmodel -->|"formats tools"| node_toolexec
node_modelresult -->|"executes tools"| node_toolexec
node_toolexec -->|"uses context"| node_toolcontext
node_toolexec -->|"updates state"| node_conversation
node_toolorchestrator -->|"dispatches tools"| node_toolexec
node_modelresult -->|"manages tasks"| node_asynctask
node_resume -->|"appends results"| node_conversation
node_resume -->|"continues turn"| node_callmodel
node_mcpconnection -->|"resolves auth"| node_mcpauth
node_mcpconnection -->|"connects to"| node_mcpserver
node_mcprehydrate -->|"reconnects"| node_mcpconnection
node_mcprehydrate -->|"uses cache"| node_mcpcache
node_mcprehydrate -->|"wraps tools"| node_mcptoolwrap
node_mcptoolwrap -->|"creates agent tools"| node_tooltypes
node_facade -->|"re-exports integration"| node_mcprehydrate

click node_openrouter "https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/openrouter.ts"
click node_callmodel "https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/inner-loop/call-model.ts"
click node_modelresult "https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/model-result.ts"
click node_conversation "https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/conversation-state.ts"
click node_streaming "https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/stream-transformers.ts"
click node_hooks "https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/hooks-manager.ts"
click node_doomloop "https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/doom-loop.ts"
click node_tooltypes "https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/tool-types.ts"
click node_toolcheck "https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/tool-check.ts"
click node_toolcontext "https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/tool-context.ts"
click node_toolexec "https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/tool-executor.ts"
click node_toolorchestrator "https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/tool-orchestrator.ts"
click node_asynctask "https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/tool-task.ts"
click node_resume "https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/inner-loop/resume-tool-results.ts"
click node_mcpconnection "https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/mcp/mcp-connection.ts"
click node_mcpauth "https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/mcp/auth/auth-resolver.ts"
click node_mcprehydrate "https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/mcp/rehydrate.ts"
click node_mcpcache "https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/mcp/cache/cache-store.ts"
click node_mcptoolwrap "https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/mcp/tool-wrapper.ts"
click node_facade "https://github.com/openrouterteam/typescript-agent/blob/main/packages/mcp/src/index.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_openrouter,node_callmodel,node_modelresult,node_conversation,node_streaming,node_hooks,node_doomloop toneBlue
class node_tooltypes,node_toolcheck,node_toolcontext,node_toolexec,node_toolorchestrator,node_asynctask,node_resume toneAmber
class node_mcpconnection,node_mcpauth,node_mcprehydrate,node_mcpcache,node_mcptoolwrap,node_mcpserver toneMint
class node_facade toneRose
class node_app toneIndigo
```

## Components

### Agent runtime

- [OpenRouter client](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/openrouter.ts): `packages/agent/src/openrouter.ts`
- [Model call setup](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/inner-loop/call-model.ts): `packages/agent/src/inner-loop/call-model.ts`
- [Response lifecycle](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/model-result.ts): `packages/agent/src/lib/model-result.ts`
- [Conversation state](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/conversation-state.ts): `packages/agent/src/lib/conversation-state.ts`
- [Stream transforms](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/stream-transformers.ts): `packages/agent/src/lib/stream-transformers.ts`
- [Hook management](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/hooks-manager.ts): `packages/agent/src/lib/hooks-manager.ts`
- [Loop detection](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/doom-loop.ts): `packages/agent/src/lib/doom-loop.ts`

### Tool execution

- [Tool contracts](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/tool-types.ts): `packages/agent/src/lib/tool-types.ts`
- [Tool checks](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/tool-check.ts): `packages/agent/src/lib/tool-check.ts`
- [Tool context](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/tool-context.ts): `packages/agent/src/lib/tool-context.ts`
- [Tool executor](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/tool-executor.ts): `packages/agent/src/lib/tool-executor.ts`
- [Tool orchestration](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/tool-orchestrator.ts): `packages/agent/src/lib/tool-orchestrator.ts`
- [Async tool tasks](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/lib/tool-task.ts): `packages/agent/src/lib/tool-task.ts`
- [Resume tool results](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/inner-loop/resume-tool-results.ts): `packages/agent/src/inner-loop/resume-tool-results.ts`

### MCP integration

- [MCP connections](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/mcp/mcp-connection.ts): `packages/agent/src/mcp/mcp-connection.ts`
- [MCP authentication](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/mcp/auth/auth-resolver.ts): `packages/agent/src/mcp/auth/auth-resolver.ts`
- [MCP rehydration](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/mcp/rehydrate.ts): `packages/agent/src/mcp/rehydrate.ts`
- [MCP cache](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/mcp/cache/cache-store.ts): `packages/agent/src/mcp/cache/cache-store.ts`
- [MCP tool wrapper](https://github.com/openrouterteam/typescript-agent/blob/main/packages/agent/src/mcp/tool-wrapper.ts): `packages/agent/src/mcp/tool-wrapper.ts`

### Compatibility facade

- [MCP facade](https://github.com/openrouterteam/typescript-agent/blob/main/packages/mcp/src/index.ts): `packages/mcp/src/index.ts`

### Other components

- **Application**
- **MCP server**

## Connections

- Application → OpenRouter client: calls (evidence: `packages/agent/src/openrouter.ts`)
- OpenRouter client → Model call setup: delegates to (evidence: `packages/agent/src/openrouter.ts`)
- Model call setup → Response lifecycle: creates (evidence: `packages/agent/src/inner-loop/call-model.ts`)
- Response lifecycle → Stream transforms: consumes stream (evidence: `packages/agent/src/lib/model-result.ts`)
- Response lifecycle → Conversation state: uses state (evidence: `packages/agent/src/lib/model-result.ts`)
- Response lifecycle → Hook management: emits hooks (evidence: `packages/agent/src/lib/model-result.ts`)
- Response lifecycle → Loop detection: checks loops (evidence: `packages/agent/src/lib/model-result.ts`)
- Model call setup → Tool checks: filters tools (evidence: `packages/agent/src/inner-loop/call-model.ts`)
- Model call setup → Tool executor: formats tools (evidence: `packages/agent/src/inner-loop/call-model.ts`)
- Response lifecycle → Tool executor: executes tools (evidence: `packages/agent/src/lib/model-result.ts`)
- Tool executor → Tool context: uses context (evidence: `packages/agent/src/lib/tool-executor.ts`)
- Tool executor → Conversation state: updates state (evidence: `packages/agent/src/lib/tool-executor.ts`)
- Tool orchestration → Tool executor: dispatches tools (evidence: `packages/agent/src/lib/tool-orchestrator.ts`)
- Response lifecycle → Async tool tasks: manages tasks (evidence: `packages/agent/src/lib/model-result.ts`)
- Resume tool results → Conversation state: appends results (evidence: `packages/agent/src/inner-loop/resume-tool-results.ts`)
- Resume tool results → Model call setup: continues turn (evidence: `packages/agent/src/inner-loop/resume-tool-results.ts`)
- MCP connections → MCP authentication: resolves auth (evidence: `packages/agent/src/mcp/mcp-connection.ts`)
- MCP connections → MCP server: connects to (evidence: `packages/agent/src/mcp/mcp-connection.ts`)
- MCP rehydration → MCP connections: reconnects (evidence: `packages/agent/src/mcp/rehydrate.ts`)
- MCP rehydration → MCP cache: uses cache (evidence: `packages/agent/src/mcp/rehydrate.ts`)
- MCP rehydration → MCP tool wrapper: wraps tools (evidence: `packages/agent/src/mcp/rehydrate.ts`)
- MCP tool wrapper → Tool contracts: creates agent tools (evidence: `packages/agent/src/mcp/tool-wrapper.ts`)
- MCP facade → MCP rehydration: re-exports integration (evidence: `README.md`)