OpenHands/OpenHands

Agent Canvas is a frontend that delegates the agent loop to a backend Agent Server (Python, software-agent-sdk). Canvas builds the start-conversation payload in src/api/agent-server-adapter.ts (lines 1072–1091), which selects between two agent kinds: OpenHands (direct LLM via LiteLLM) or ACP (external CLI subprocess like Claude Code/Codex/Gemini). The payload includes max_iterations (default 500, line 147), stuck_detection: true, a confirmation_policy, and a security_analyzer. A second local planner agent is spawned via buildStartPlanningConversationRequest (lines 1450–1572) with a PlanningFileEditorAction tool operating on PLAN.md; it uses its own LLMSummarizingCondenser (max_size: 100, keep_first: 6, lines 1520–1525). Once the conversation is created, the frontend communicates over a WebSocket (conversation-websocket-context.tsx, line 1–86) that streams events: user messages, actions (tool calls), observations (tool results), and conversation state updates. The turn structure flows as: user sends a message → ConversationClient.sendEvent (api line 464–468) → server processes → events stream back over WebSocket → the frontend renders them. The action type system (src/types/agent-server/core/base/action.ts, lines 6–370) defines ~20 tool types including ExecuteBashAction, FileEditorAction, GlobAction, GrepAction, BrowserNavigateAction, TaskAction (for sub-agents), SwitchLLMAction, and MCPToolAction. Sub-agents are launched via TaskAction with fields prompt, subagent_type, description, and resume (lines 282–299); their results arrive as TaskObservation with task_id, subagent, and status (observation.ts lines 305–326). Stop conditions are expressed through ExecutionStatus (common.ts lines 67–75): idle, running, paused, waiting_for_confirmation, finished, error, stuck.

Context management has three main mechanisms. 1. Skills (knowledge context): Bundled public skills from @openhands/extensions are loaded into agent_context.skills (agent-server-adapter.ts lines 828–853) alongside user- and project-authored skills. Skills are filtered via allow/deny lists (buildSkillEnablementFilter, line 878) and invoked by keyword triggers or explicit name. 2. Search/grep tools: The agent has GlobAction (pattern + path) and GrepAction (regex + path + glob filter) at its disposal (action.ts lines 249–273), plus FileEditorAction with a view command that reads file ranges (view_range, lines 89–94). There is no separate embeddings-based retrieval or repo-map generation in the Canvas frontend — the agent-server SDK handles those if configured. 3. Context-window compaction: Two compaction strategies exist. The LLMSummarizingCondenser is a server-side rolling summarizer configured on the planning agent (agent-server-adapter.ts lines 1520–1525: max_size: 100, keep_first: 6) and on OpenHands agents via settings (condenser: { enabled: true, max_size: 240 }, services/settings.ts lines 43–46). It fires automatically as the conversation grows, emitting CondensationEvent objects (condensation-event.ts lines 5–27: forgotten_event_ids and summary). The manual compact action (use-compact-context-action.ts lines 26–119) lets the user request compaction on demand via useCondenseConversation; it captures a baseline token count, posts a condense request, and awaits the resulting CondensationEvent with fewer tokens. The context-window state is displayed via useContextWindowUsage which reads per_turn_token and context_window from the metrics store. Token usage is tracked per usage-id (usage_to_metrics in conversation-state-event.ts lines 47–53), including caching stats (cache_read_tokens, cache_write_tokens).

Code editing is done through the FileEditorAction tool (action.ts lines 65–95). It supports five commands: view, create, str_replace, insert, and undo_edit. The str_replace command takes old_str and new_str (exact string replacement — not a diff/patch format). The insert command inserts new_str after line insert_line. The create command takes file_text for the full file body. There is also a StrReplaceEditorAction (lines 96–125) with the same command set as a separate tool name, and a PlanningFileEditorAction (lines 218–247) used exclusively by the local planner to edit PLAN.md. Each edit returns a FileEditorObservation (observation.ts lines 111–146) carrying command, output, path, prev_exist (whether the file existed before), old_content, new_content, and error. The undo_edit command reverts the last edit to a single file — the old_content/new_content fields let the agent see the delta. Edits are validated server-side by the agent-server's file editor implementation (not by Canvas's frontend): there is no separate lint-run or test-run step in the tool chain visible in this codebase. Git integration is available through the workspace: the frontend provides a diff view via the Files tab (referenced in the Canvas UI tool description at canvas-ui-client-tool.ts lines 39–40: "The Files tab automatically renders a diff view when the workspace has uncommitted git changes"), and there are git_service endpoints on the agent-server, but there is no client-side git-commit-after-edit hook in the Canvas UI code.

Safety is enforced through layered mechanisms. 1. Confirmation policies are set per conversation at creation time (agent-server-adapter.ts lines 730–755): NeverConfirm (no prompts), ConfirmRisky (threshold HIGH + confirm unknown), or AlwaysConfirm. The policy is sent in the start-conversation payload as confirmation_policy (line 1358). 2. Security analyzers (line 744–755) can be LLMSecurityAnalyzer (an LLM judges command risk), PatternSecurityAnalyzer (pattern/rule-based), or PolicyRailSecurityAnalyzer. The default is security_analyzer: "llm" (services/settings.ts line 14) and confirmation_mode: false (line 13). The settings page lives at verification-settings.tsx (lines 1–44). 3. Execution runtime modes are reported by the agent-server as execution_runtime: "local" | "docker" (agent-server-compatibility.ts line 38). Docker mode uses DockerExecutionWorkspace with working dir /workspace (adapter.ts lines 517–522), providing container-level isolation. Local mode uses LocalWorkspace with the configured working_dir. 4. Secrets are encrypted (Fernet tokens with prefix gAAAAA, adapter.ts line 643) and decrypted server-side. They flow as LookupSecret objects (lines 1144–1149) rather than plaintext env vars — the agent-server resolves them from its own store. 5. Network restrictions: Docker mode sandboxes the agent inside a container, naturally restricting network access. Checkpoint/sandbox lifecycle (pause, resume, missing) is managed via the cloud SandboxService (cloud/sandbox-service.api.ts). There is no separate Landlock/seatbelt mechanism visible in Canvas — that is an agent-server concern.

Two agent kinds determine model support. OpenHands agents use LiteLLM, which makes any LLM accessible via its provider prefix (e.g. openai/gpt-5.6-sol, the default at services/settings.ts line 6). The model config includes model, api_key, base_url, and supports subscriptions (ChatGPT via LLMSubscriptionService, subscription-service.ts lines 1–30, with a device-OAuth flow). ACP agents delegate to external CLI subprocesses: Claude Code (claude-code), Codex (codex), Gemini CLI (gemini-cli), or a custom command. These are defined in acp-providers.ts (lines 1–80) which reads from @openhands/typescript-client's ACP registry. ACP models use acp_model, acp_command, acp_server fields (adapter.ts lines 959–1027). Model routing is done through saved LLM profiles (named model configs) and meta-profiles (classifier-based routers). The SwitchLLMAction (action.ts lines 301–310) allows mid-conversation model switching via profile_name + reason, returning a SwitchLLMObservation with active_model. The ClassifyAndSwitchLLMObservation (observation.ts lines 364–387) supports the Model Router meta-profile feature: a classifier selects from saved LLM profiles. The route_task_to_model tool is attached by the agent-server when a meta-profile is active, gated by run_router_at_conversation_start (adapter.ts lines 364–379). Cost tracking is handled by MetricsSnapshot (conversation-state-event.ts lines 25–41) with per-usage-id costs, token counts, response latencies, and prompt/completion/cache breakdowns. An LLMBalanceService (llm-balance-service.ts lines 1–50) provides credit-balance queries for OpenRouter. The default model is openai/gpt-5.6-sol (settings.ts line 6). Support for stream: true is forced for both OpenHands and ACP agents (adapter.ts lines 1041, 1470).

Extensibility is built at multiple levels. 1. MCP (Model Context Protocol): The mcp_config setting supports stdio, SSE, and HTTP servers, including OAuth2 device-auth flows. The MCPService (mcp-service.api.ts, lines 1–100) proxies test/ping/health operations for both local and cloud backends. MCP health monitoring runs via probe-mcp-server-health.ts. 2. Canvas Extensions (the "Apps" system): Plugins defined by a canvas-extension.json manifest can contribute custom pages (CanvasExtensionPageContribution in canvas-extension.ts lines 4–11). Extensions are installed from git sources or local paths through CanvasExtensionsService (canvas-extensions-service.ts lines 1–60), which has an app-backend bridge capability. They render in iframes with validated session tokens (canvas-extension-app-view.ts lines 32–59). 3. Skills: Public skills are bundled at build time from @openhands/extensions (agent-server-adapter.ts lines 828–853, using the SKILLS_CATALOG). User and project skills are loaded from disk by the agent-server (load_user_skills: true, load_project_skills: true, line 909–910). Skills use the AGENTS.md format with keyword triggers, descriptions, and compatibility constraints. 4. Hooks system: Workspace hooks are loaded from .openhands/hooks.json by HooksService (hooks-service.ts lines 1–50). Hooks fire on stop, pre_tool_use, post_tool_use events (types lines 264–271), with command or prompt executors and configurable timeouts. 5. Client tools: The ClientToolSpec interface (canvas-ui-client-tool.ts lines 9–20) allows registering custom tools with JSON Schema parameters and annotations (readOnlyHint, destructiveHint, etc.). Two built-in client tools are canvas_ui_control (UI navigation) and launch_child_conversation (spawn sub-conversations). 6. SDK: The @openhands/typescript-client npm package provides typed API clients for headless use. The ACP Protocol lets any external agent (Claude Code, Codex, Gemini, custom ACP) be used as a backend.