How openrouterteam/typescript-agent works
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: model-result.ts Response lifecycle · call-model.ts Model call setup · tool-executor.ts Tool executor · rehydrate.ts MCP rehydration
Components 22
Agent runtime
- OpenRouter client
packages/agent/src/openrouter.ts - Model call setup
packages/agent/src/inner-loop/call-model.ts - Response lifecycle
packages/agent/src/lib/model-result.ts - Conversation state
packages/agent/src/lib/conversation-state.ts - Stream transforms
packages/agent/src/lib/stream-transformers.ts - Hook management
packages/agent/src/lib/hooks-manager.ts - Loop detection
packages/agent/src/lib/doom-loop.ts
Tool execution
- Tool contracts
packages/agent/src/lib/tool-types.ts - Tool checks
packages/agent/src/lib/tool-check.ts - Tool context
packages/agent/src/lib/tool-context.ts - Tool executor
packages/agent/src/lib/tool-executor.ts - Tool orchestration
packages/agent/src/lib/tool-orchestrator.ts - Async tool tasks
packages/agent/src/lib/tool-task.ts - Resume tool results
packages/agent/src/inner-loop/resume-tool-results.ts
MCP integration
- MCP connections
packages/agent/src/mcp/mcp-connection.ts - MCP authentication
packages/agent/src/mcp/auth/auth-resolver.ts - MCP rehydration
packages/agent/src/mcp/rehydrate.ts - MCP cache
packages/agent/src/mcp/cache/cache-store.ts - MCP tool wrapper
packages/agent/src/mcp/tool-wrapper.ts
Compatibility facade
- MCP facade
packages/mcp/src/index.ts
Other components
- Application
- MCP server
Connections 23
- Application → OpenRouter client: calls
packages/agent/src/openrouter.ts - OpenRouter client → Model call setup: delegates to
packages/agent/src/openrouter.ts - Model call setup → Response lifecycle: creates
packages/agent/src/inner-loop/call-model.ts - Response lifecycle → Stream transforms: consumes stream
packages/agent/src/lib/model-result.ts - Response lifecycle → Conversation state: uses state
packages/agent/src/lib/model-result.ts - Response lifecycle → Hook management: emits hooks
packages/agent/src/lib/model-result.ts - Response lifecycle → Loop detection: checks loops
packages/agent/src/lib/model-result.ts - Model call setup → Tool checks: filters tools
packages/agent/src/inner-loop/call-model.ts - Model call setup → Tool executor: formats tools
packages/agent/src/inner-loop/call-model.ts - Response lifecycle → Tool executor: executes tools
packages/agent/src/lib/model-result.ts - Tool executor → Tool context: uses context
packages/agent/src/lib/tool-executor.ts - Tool executor → Conversation state: updates state
packages/agent/src/lib/tool-executor.ts - Tool orchestration → Tool executor: dispatches tools
packages/agent/src/lib/tool-orchestrator.ts - Response lifecycle → Async tool tasks: manages tasks
packages/agent/src/lib/model-result.ts - Resume tool results → Conversation state: appends results
packages/agent/src/inner-loop/resume-tool-results.ts - Resume tool results → Model call setup: continues turn
packages/agent/src/inner-loop/resume-tool-results.ts - MCP connections → MCP authentication: resolves auth
packages/agent/src/mcp/mcp-connection.ts - MCP connections → MCP server: connects to
packages/agent/src/mcp/mcp-connection.ts - MCP rehydration → MCP connections: reconnects
packages/agent/src/mcp/rehydrate.ts - MCP rehydration → MCP cache: uses cache
packages/agent/src/mcp/rehydrate.ts - MCP rehydration → MCP tool wrapper: wraps tools
packages/agent/src/mcp/rehydrate.ts - MCP tool wrapper → Tool contracts: creates agent tools
packages/agent/src/mcp/tool-wrapper.ts - MCP facade → MCP rehydration: re-exports integration
README.md