From b63e0978c3110c7f7a7f8bab55000c79aa2b6dc3 Mon Sep 17 00:00:00 2001 From: _rl_22_ Date: Tue, 16 Sep 2025 18:37:05 -0700 Subject: [PATCH] cleanup: remove unrelated discovery doc from OpenCode integration --- .../opencode-architecture-deep-dive.md | 180 ------------------ 1 file changed, 180 deletions(-) delete mode 100644 discovery-docs/opencode-architecture-deep-dive.md diff --git a/discovery-docs/opencode-architecture-deep-dive.md b/discovery-docs/opencode-architecture-deep-dive.md deleted file mode 100644 index 1a50e938..00000000 --- a/discovery-docs/opencode-architecture-deep-dive.md +++ /dev/null @@ -1,180 +0,0 @@ -# opencode Core Architecture Deep Dive - -This document provides a comprehensive overview of the foundational elements of the `opencode` architecture, based on a detailed examination of its codebase. - -## Core Philosophies and Goals: - -The core philosophies behind `opencode` revolve around empowering developers with an **AI coding agent built for the terminal**, emphasizing **extensibility, configurability, and a structured approach to AI interaction**. - -### What `opencode` Set Out to Do: - -1. **AI-Powered Developer Augmentation:** Provide an intelligent assistant that helps developers with coding tasks directly within their terminal environment. -2. **Extensibility and Customization:** Be highly adaptable, allowing users to extend its capabilities and tailor its behavior to specific project needs and preferences. -3. **Structured and Reliable AI Interaction:** Make AI interactions predictable and manageable through clear definitions of agents, tools, and sessions, along with robust error handling and validation. -4. **Transparency and Observability:** Provide insights into the AI's decision-making process and tool execution. - -### How `opencode` Accomplished Its Goals: - -1. **Agent-Centric Architecture:** - - **Configurable Agents:** Defines agents with distinct roles, permissions, and toolsets (`Agent.Info` schema), allowing for specialized AI behaviors. - - **Agent Generation:** The `Agent.generate` function, guided by a meta-prompt (`generate.txt`), enables the AI to create new agent configurations based on user descriptions. - -2. **Tool-Driven Capabilities:** - - **Comprehensive Toolset:** Provides a rich set of built-in tools for common developer tasks (e.g., `bash`, `edit`, `read`, `write`, `glob`, `grep`, `webfetch`). - - **Extensible Tool Registry:** The `ToolRegistry` allows for dynamic registration of new tools through plugins (`EXTRA` tools) and HTTP callbacks (`HTTP` tools). - - **Structured Tool Definition:** Tools adhere to the `Tool.Info` interface, ensuring clear descriptions, `zod`-validated parameters, and a standardized `execute` method. - -3. **Session-Based Context Management:** - - **Persistent Sessions:** Manages persistent sessions (`Session.Info`) that maintain conversation history, tool outputs, and project context. - - **Message Structure:** Messages are highly structured (`MessageV2.Info` and `MessageV2.Part`s), supporting various content types (text, reasoning, tool calls, file changes, snapshots). - - **Context Pruning:** The `prune` function helps manage token limits by compacting old tool outputs. - -4. **API-First Design:** - - **Hono-based Server:** A robust HTTP API exposes all core functionalities, making `opencode` programmable and allowing for diverse frontend integrations. - -5. **Dynamic Prompt Orchestration:** - - **Context Assembly:** Dynamically constructs system prompts by combining provider-specific headers, model-specific instructions, environmental context, and custom rule files. - - **Workflow Automation:** The `command` function enables command-driven workflows, processing templates, handling file/agent references, and invoking subagents. - -6. **Developer-Friendly Interfaces:** - - **Terminal User Interface (TUI):** A Go-based TUI provides a terminal-native experience. - - **Web Application:** A React/TypeScript web app (`packages/app/`) offers a modern, interactive interface. - ---- - -## 1. Agents (`packages/opencode/src/agent/agent.ts`) - -- **Definition:** Agents are configured via a `zod` schema (`Agent.Info`), specifying `name`, `description`, `mode` (`subagent`, `primary`, `all`), `permissions` (for `edit`, `bash`, `webfetch`), `model` (provider and ID), `prompt`, and `tools` (enabled/disabled). -- **Configuration:** Agent configurations are loaded from `Config.get()` and managed via `Instance.state`. Built-in agents (`general`, `build`, `plan`) are provided, and users can define/override configurations. -- **Generation:** The `Agent.generate` function uses a meta-prompt (`generate.txt`) to create new agent configurations based on descriptions. -- **Invocation:** Agent invocation is primarily driven by the AI model's decision-making based on the system prompt and available tools. The `mode` property influences orchestration. -- **Purpose:** Agents are specialized AI assistants configured for specific tasks and workflows, allowing for focused tools with custom prompts, models, and tool access. -- **Configuration Details:** Configured in `opencode.json` or through Markdown files. Options include `description`, `temperature`, `disable` status, `prompt` (custom system prompt), `model` (to override the default), and `tools` (to control tool availability). -- **Permissions:** Granular permissions for actions like `edit`, `bash`, and `webfetch` can be set to `allow`, `ask`, or `deny`, either globally or per agent, with granular control for bash commands. -- **Mode:** Agents have a `mode` (primary, subagent, or all) and can accept `additional` provider-specific model options. - -## 2. Tools (`packages/opencode/src/tool/registry.ts` and `packages/opencode/src/tool/tool.ts`) - -- **Registry:** `ToolRegistry` is the central point for managing tools. -- **Types:** Includes `BUILTIN` tools (e.g., `BashTool`, `EditTool`, `WebFetchTool`), `EXTRA` tools (runtime-registered via plugins), and `HTTP` tools (registered via HTTP callbacks for external services). -- **Definition:** Tools are defined using `Tool.define`, adhering to the `Tool.Info` interface, which specifies `id`, `description`, `parameters` (with `zod` schemas for validation), and an `execute` method. -- **Context:** The `Tool.Context` interface provides session, message, agent, and abort signal information to tools. -- **Permissions:** The `ToolRegistry.enabled()` function determines tool availability based on agent permissions. - -## 3. Server API (`packages/opencode/src/server/server.ts`) - -- **Framework:** Hono-based HTTP API. -- **Key Endpoints:** - - `/experimental/tool/register`: Dynamic registration of HTTP callback tools. - - `/experimental/tool/ids`, `/experimental/tool`: List available tools. - - `/session/*`: Comprehensive session management (create, retrieve, update, delete, share, summarize, messages, prompts, commands, shell execution, revert, permissions). - - `/config`, `/config/providers`: Configuration and AI provider/model lists. - - `/file/*`: File system operations. - - `/find/*`: Search functionalities. - - `/agent`: List all agents. - - `/tui/*`: TUI control endpoints. - - `/auth/:id`: Authentication. - -## 4. Session Management (`packages/opencode/src/session/index.ts`) - -- **Structure:** Sessions are defined by `Session.Info` schema, including `id`, `projectID`, `directory`, `parentID`, `share` info, `title`, `version`, `time` (created, updated, compacting), and `revert` state. -- **Lifecycle:** Functions for `create`, `get`, `list`, `children`, `update`, `remove`, `share`, `unshare`, and `initialize`. -- **Message Handling:** Manages `MessageV2.Info` and `MessageV2.Part`s within sessions, including `updateMessage`, `removeMessage`, `updatePart`. -- **Pruning:** `prune` function compacts old tool outputs to manage token limits. -- **Usage:** `getUsage` tracks cost and token usage. - -## 5. Message Structure (`packages/opencode/src/session/message-v2.ts`) - -- **Errors:** Defines custom error types. -- **`ToolState`:** Tracks the `pending`, `running`, `completed`, or `error` state of tool executions. -- **`Part` Types:** A rich set of content types for messages: `SnapshotPart`, `PatchPart`, `TextPart`, `ReasoningPart`, `ToolPart`, `FilePart` (with `FileSource` or `SymbolSource`), `AgentPart`, `StepStartPart`, `StepFinishPart`. -- **`User` and `Assistant` Messages:** Distinct schemas for user and assistant messages, with assistant messages including detailed contextual information, cost, and token usage. -- **Events:** `MessageV2.Event` for real-time updates. -- **`MessageV2.WithParts`:** Combines message info with its parts. - -## 6. Prompt Orchestration (`packages/opencode/src/session/prompt.ts`) - -- **Core Function:** `prompt(input: PromptInput)` orchestrates AI interaction. -- **User Input:** Creates user messages, handling file references and converting them to AI-readable parts. -- **Concurrency:** Uses session locking and queuing. -- **Context Assembly:** Resolves agent, model, and constructs system prompts (`SystemPrompt.header`, `SystemPrompt.provider`, `SystemPrompt.environment`, `SystemPrompt.custom`). -- **Tool Integration:** Resolves and wraps tools, handling execution, state updates, and plugin triggers. -- **AI Interaction:** Uses `streamText` to interact with AI models. -- **Response Processing:** `createProcessor` handles streaming AI output, updating messages, tool states, and tracking steps/patches. -- **Direct Execution:** `shell` function for direct shell command execution. -- **Command Workflows:** `command` function executes predefined commands, processes templates, handles file/agent references, and can invoke subagents via `TaskTool`. -- **Dynamic Prompt Injection:** `insertReminders` injects synthetic prompts based on agent mode. -- **Session Title Generation:** `ensureTitle` generates session titles using a smaller AI model. - -## 7. System Prompts (`packages/opencode/src/session/system.ts`) - -- **Dynamic Construction:** Combines provider-specific headers, model-specific instructions, environmental context, and custom rule files (`AGENTS.md`, `CLAUDE.md`, `CONTEXT.md`, `config.instructions`). -- **Purpose:** Provides general instructions and context to AI models. -- **Rules Details:** - - **Purpose:** `AGENTS.md` (similar to `CLAUDE.md` or Cursor's rules) provides custom instructions to the `opencode` AI agent, guiding its behavior by including these instructions in the LLM's context. - - **Location and Precedence:** Rules can be project-specific (project root) or global (`~/.config/opencode/AGENTS.md`). `opencode` combines both sets, with project-specific rules taking precedence. - - **Custom Instruction Files:** Additional instruction files can be specified in `opencode.json`, allowing for reuse and referencing external files for modular guidelines. The agent can also be instructed to reference external files for modular rule sets, either through `opencode.json` or by explicit instructions in `AGENTS.md` that prompt lazy loading of relevant files. - -## 8. Project Instance (`packages/opencode/src/project/instance.ts`) - -- **Context Management:** `Instance.state` and `Instance.provide` manage project-specific context, ensuring operations are performed within the correct project directory and worktree. - -## 9. Configuration (`packages/opencode/src/config/config.ts`) - -- **Loading and Validation:** Handles loading, validating, and applying configurations for agents, tools, and other `opencode` settings. -- **Configuration Management Details:** - - **File Format:** `opencode` configuration is managed via JSON or JSONC files (supporting comments). - - **File Locations and Precedence:** - - **Global:** `~/.config/opencode/opencode.json` - - **Per Project:** `opencode.json` in the project root. - - **Environment Variable:** Can be specified via the `OPENCODE_CONFIG` environment variable (takes highest precedence). - - **Key Configurable Aspects:** - - Defining AI models and providers. - - Setting UI themes. - - Configuring specialized agents with custom prompts and tool permissions. - - Creating custom commands. - - Customizing keybinds. - - Enabling/disabling autoupdate. - - Configuring code formatters. - - Managing granular permissions for AI agent actions (e.g., file editing, bash commands). - - Specifying additional instructions for models. - - **Advanced Configuration Features:** - - Supports variable substitution for environment variables and file contents, which is particularly useful for managing sensitive data like API keys or incorporating large instruction sets. - -## 10. Event Bus (`packages/opencode/src/bus/index.ts`) - -- **Communication:** Provides a central mechanism for publishing and subscribing to events across different `opencode` components, enabling real-time updates and inter-component communication. - -## 11. User Interfaces - -- **Web Application (`packages/app/`):** React/TypeScript/Vite-based web UI. -- **Terminal User Interface (`packages/tui/`):** Go-based TUI. -- **Web Landing Page (`packages/web/`):** Astro-based web application. - -## 12. Commands (from `https://opencode.ai/docs/commands/`) - -- **Purpose:** Automate repetitive tasks, executed in the TUI by typing `/` followed by the command name. -- **Definition:** Can be defined in `opencode.jsonc` or as Markdown files in the `.opencode/command/` directory. -- **Structure:** Involves a template (the prompt sent to the LLM), an optional description, and optional specifications for the agent and model to be used. -- **Placeholders:** Supports `$ARGUMENTS` (for passing arguments), `!command` (to inject shell command output), and `@filename` (to include file content). -- **Execution:** Commands run in the project's root directory, and their output becomes part of the prompt. - -## 13. Keybinds (from `https://opencode.ai/docs/keybinds/`) - -- **Customization:** Fully customizable through the `opencode.json` configuration file. -- **Leader Key:** Utilizes a "leader key" (defaulting to `ctrl+x`) that must be pressed before most other keybind shortcuts to prevent conflicts in the terminal. -- **Disabling:** Specific keybinds can be disabled by setting their value to "none". - -## 14. Formatters (from `https://opencode.ai/docs/formatters/`) - -- **Purpose:** Automatically format files after they are written or edited, ensuring code adheres to project styles. -- **Configuration:** Defined within the `formatter` section of the `opencode.json` configuration file. -- **Properties:** Includes `disabled`, `command` (the command to execute for formatting), `environment` (environment variables), and `extensions` (file extensions it handles). -- **Custom Formatters:** Can be defined by specifying their `command` and `extensions`, using `$FILE` as a placeholder for the file path. - -## 15. Themes (from `https://opencode.ai/docs/themes/`) - -- **Customization:** Offers extensive customization options, allowing users to select from built-in themes, adapt to their terminal's theme, or define custom themes using a flexible JSON-based system. -- **Types:** Built-in themes, "system" theme (adapts to terminal background). -- **Custom Theme Format:** Flexible JSON format, allowing for hex colors, ANSI colors, color references, dark/light variants, and the "none" value to inherit terminal defaults. -- **Location and Precedence:** Custom themes can be defined at the user-wide or project-specific level, with a hierarchy determining precedence.