How codeany-ai/open-agent-sdk-typescript works
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: engine.ts Engine · tools/index.ts Tools Index · src/index.ts Index · session.ts Session
Components 20
Public API
Package entrypoints and reusable agent surface.
- Index · Main re-export surface for the SDK.
src/index.ts
Runtime
Agent orchestration, sessions, hooks, and execution loop.
- Agent · Reusable agent interface and session-facing API.
src/agent.ts - Engine · Runs the agent loop, turns, model calls, and tool coordination.
src/engine.ts - Session · Conversation persistence, resume, continue, and fork support.
src/session.ts - Hooks · Interception points for policy, telemetry, and behavior changes.
src/hooks.ts - Tool Helper · Higher-level tool definition and validation helpers.
src/tool-helper.ts
Capabilities
Tooling and MCP integration used by the agent loop.
- Tools Index · Central export and composition point for built-in tools.
src/tools/index.ts - Tool Types · Shared tool definitions and typing for the tool layer.
src/tools/types.ts - Shell Tool · Representative local execution capability for command and file operations.
src/tools/bash.ts - File Tools · Read, write, edit, glob, and grep style file capabilities.
src/tools/read.ts - Task Tools · Planning, tasks, todos, messaging, and subagent workflows.
src/tools/task-tools.ts - MCP Server · In-process MCP server exposure for local tools.
src/sdk-mcp-server.ts - MCP Client · Client integration for external MCP servers and transports.
src/mcp/client.ts
Support
Context, messaging, caching, retry, and token utilities.
- Context · Builds repo-aware system context from project signals.
src/utils/context.ts - Compaction · Auto-compaction and micro-compaction for long runs.
src/utils/compact.ts - Tokens · Token estimation and context budgeting helpers.
src/utils/tokens.ts - Messages · Internal message and event shapes for model/tool exchange.
src/utils/messages.ts - Retry · Transient failure retry behavior for API and tool workflows.
src/utils/retry.ts - File Cache · Cached file reads to reduce repeated disk access.
src/utils/fileCache.ts
Examples
Usage samples and browser demo.
- Web Demo · Lightweight browser UI and local server for end-to-end testing.
examples/web/server.ts
Connections 24
- 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.