docs: add module-level AGENTS.md for mcp-oauth, atlas, rules-injector, background-task, call-omo-agent, lsp
🤖 Generated with assistance of [OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode)
This commit is contained in:
YeonGyu-Kim
@@ -0,0 +1,53 @@
|
||||
# src/tools/background-task/ — Background Task Tool Wrappers
|
||||
|
||||
**Generated:** 2026-02-19
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
18 files. Tool-layer wrappers for `background_output` and `background_cancel`. Does NOT implement the background execution engine — that lives in `src/features/background-agent/`. This directory provides the LLM-facing tool interface.
|
||||
|
||||
## THREE TOOLS
|
||||
|
||||
| Tool | Factory | Purpose |
|
||||
|------|---------|---------|
|
||||
| `background_output` | `createBackgroundOutput` | Get results from a running/completed background task |
|
||||
| `background_cancel` | `createBackgroundCancel` | Cancel running task(s) |
|
||||
| `createBackgroundTask` | internal | Shared factory used by both |
|
||||
|
||||
## KEY FILES
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `create-background-output.ts` | `background_output` tool: fetch task results by task_id |
|
||||
| `create-background-cancel.ts` | `background_cancel` tool: cancel by taskId or all=true |
|
||||
| `create-background-task.ts` | Shared tool factory with common params |
|
||||
| `clients.ts` | Client interfaces for background output and cancel |
|
||||
| `session-messages.ts` | Fetch session messages from OpenCode |
|
||||
| `full-session-format.ts` | Format full session output (messages, thinking blocks) |
|
||||
| `task-result-format.ts` | Format task result for LLM consumption |
|
||||
| `task-status-format.ts` | Format task status (running/completed/error) |
|
||||
| `message-dir.ts` | Temp directory for message exchange |
|
||||
| `truncate-text.ts` | Truncate large output to fit context |
|
||||
| `time-format.ts` | Human-readable duration formatting |
|
||||
| `delay.ts` | Polling delay utility |
|
||||
| `types.ts` | `BackgroundTaskOptions`, result/status types |
|
||||
| `constants.ts` | Timeout defaults, polling intervals |
|
||||
|
||||
## BACKGROUND OUTPUT MODES
|
||||
|
||||
```
|
||||
background_output(task_id, block=false) → check current status/result
|
||||
background_output(task_id, block=true) → wait until complete (timeout default: 120s)
|
||||
background_output(task_id, full_session=true) → return full session transcript
|
||||
background_output(task_id, message_limit=N) → last N messages only
|
||||
background_output(task_id, include_thinking=true) → include thinking blocks
|
||||
```
|
||||
|
||||
## RELATIONSHIP TO BACKGROUND ENGINE
|
||||
|
||||
```
|
||||
tools/background-task/ ← LLM tool interface
|
||||
features/background-agent/ ← execution engine (BackgroundManager)
|
||||
```
|
||||
|
||||
`createBackgroundOutput` queries `BackgroundManager.getTask(task_id)` — it does not manage task state.
|
||||
@@ -0,0 +1,51 @@
|
||||
# src/tools/call-omo-agent/ — Direct Agent Invocation Tool
|
||||
|
||||
**Generated:** 2026-02-19
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
23 files. The `call_omo_agent` tool — direct invocation of named agents (explore, librarian only). Distinct from `delegate-task`: no category system, no skill loading, no model selection. Fixed agent set, same execution modes (background/sync).
|
||||
|
||||
## DISTINCTION FROM delegate-task
|
||||
|
||||
| Aspect | `call_omo_agent` | `delegate-task` (`task`) |
|
||||
|--------|-----------------|--------------------------|
|
||||
| Agent selection | Named agent (explore/librarian) | Category or subagent_type |
|
||||
| Skill loading | None | `load_skills[]` supported |
|
||||
| Model selection | From agent's fallback chain | From category config |
|
||||
| Use case | Quick contextual grep | Full delegation with skills |
|
||||
|
||||
## ALLOWED AGENTS
|
||||
|
||||
Only `explore` and `librarian` — enforced via `ALLOWED_AGENTS` constant in `constants.ts`. Case-insensitive validation.
|
||||
|
||||
## EXECUTION MODES
|
||||
|
||||
Same two modes as delegate-task:
|
||||
|
||||
| Mode | File | Description |
|
||||
|------|------|-------------|
|
||||
| **Background** | `background-agent-executor.ts` | Async via `BackgroundManager` |
|
||||
| **Sync** | `sync-executor.ts` | Create session → wait for idle → return result |
|
||||
|
||||
## KEY FILES
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `tools.ts` | `createCallOmoAgent()` factory — validates agent, routes to executor |
|
||||
| `background-executor.ts` | Routes to background or sync based on `run_in_background` |
|
||||
| `background-agent-executor.ts` | Launch via `BackgroundManager.launch()` |
|
||||
| `sync-executor.ts` | Synchronous session: create → send prompt → poll → fetch result |
|
||||
| `session-creator.ts` | Create OpenCode session for sync execution |
|
||||
| `subagent-session-creator.ts` | Create session with agent-specific config |
|
||||
| `subagent-session-prompter.ts` | Inject prompt into session |
|
||||
| `completion-poller.ts` | Poll until session idle |
|
||||
| `session-completion-poller.ts` | Session-specific completion check |
|
||||
| `session-message-output-extractor.ts` | Extract last assistant message as result |
|
||||
| `message-processor.ts` | Process raw message content |
|
||||
| `message-dir.ts` + `message-storage-directory.ts` | Temp storage for message exchange |
|
||||
| `types.ts` | `CallOmoAgentArgs`, `AllowedAgentType`, `ToolContextWithMetadata` |
|
||||
|
||||
## SESSION CONTINUATION
|
||||
|
||||
Pass `session_id` to resume an existing session rather than create a new one — handled in both executors.
|
||||
@@ -0,0 +1,70 @@
|
||||
# src/tools/lsp/ — LSP Tool Implementations
|
||||
|
||||
**Generated:** 2026-02-19
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
32 files. Full LSP (Language Server Protocol) client stack exposed as 6 tools. Custom implementation that manages server processes, opens files, and forwards requests — does NOT delegate to OpenCode's built-in LSP.
|
||||
|
||||
## TOOL EXPOSURE
|
||||
|
||||
| Tool | File | What It Does |
|
||||
|------|------|--------------|
|
||||
| `lsp_goto_definition` | `goto-definition-tool.ts` | Jump to symbol definition |
|
||||
| `lsp_find_references` | `find-references-tool.ts` | All usages of a symbol |
|
||||
| `lsp_symbols` | `symbols-tool.ts` | Document outline or workspace symbol search |
|
||||
| `lsp_diagnostics` | `diagnostics-tool.ts` | Errors/warnings from language server |
|
||||
| `lsp_prepare_rename` | `rename-tools.ts` | Validate rename before applying |
|
||||
| `lsp_rename` | `rename-tools.ts` | Apply safe rename across workspace |
|
||||
|
||||
All 6 are direct `ToolDefinition` objects (not factory functions) — registered directly in `tool-registry.ts`.
|
||||
|
||||
## ARCHITECTURE
|
||||
|
||||
```
|
||||
tools.ts (6 ToolDefinition exports)
|
||||
↓ uses
|
||||
LspClientWrapper (lsp-client-wrapper.ts)
|
||||
↓ wraps
|
||||
LSPClient (lsp-client.ts) extends LSPClientConnection (lsp-client-connection.ts)
|
||||
↓ communicates via
|
||||
LSPClientTransport (lsp-client-transport.ts)
|
||||
↓ talks to
|
||||
LSPProcess (lsp-process.ts) — spawns server binary
|
||||
```
|
||||
|
||||
## KEY FILES
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `lsp-client-wrapper.ts` | High-level entry: resolves server, opens file, runs request |
|
||||
| `lsp-client.ts` | `LSPClient` — file tracking, document sync (`didOpen`/`didChange`) |
|
||||
| `lsp-client-connection.ts` | JSON-RPC request/response/notification layer |
|
||||
| `lsp-client-transport.ts` | stdin/stdout byte-stream framing |
|
||||
| `lsp-process.ts` | Spawn + cleanup of LSP server process |
|
||||
| `lsp-manager-process-cleanup.ts` | Reap orphan LSP processes on exit |
|
||||
| `lsp-manager-temp-directory-cleanup.ts` | Clean temp dirs used by some servers |
|
||||
| `server-definitions.ts` | 40+ builtin servers synced from OpenCode's `server.ts` |
|
||||
| `server-config-loader.ts` | Load custom server config from `.opencode/lsp.json` |
|
||||
| `server-resolution.ts` | Resolve which server handles a file extension |
|
||||
| `server-installation.ts` | Detect missing binaries, surface install hints |
|
||||
| `language-mappings.ts` | Extension → language ID mapping |
|
||||
| `lsp-formatters.ts` | Format LSP responses into human-readable strings |
|
||||
| `workspace-edit.ts` | Apply `WorkspaceEdit` results to disk (for rename) |
|
||||
| `types.ts` | `LSPServerConfig`, `Position`, `Range`, `Location`, `Diagnostic` etc. |
|
||||
|
||||
## SERVER RESOLUTION
|
||||
|
||||
```
|
||||
file.ts → extension (.ts) → language-mappings → server ID (typescript)
|
||||
→ server-resolution: check user config (.opencode/lsp.json) → fall back to server-definitions.ts
|
||||
→ server-installation: verify binary exists (warn with install hint if not)
|
||||
→ LSPProcess.spawn(command[])
|
||||
```
|
||||
|
||||
## NOTES
|
||||
|
||||
- File must be opened via `didOpen` before any LSP request — `LSPClient.openFile()` handles this
|
||||
- 1s delay after `didOpen` for server initialization before sending requests
|
||||
- `lsp_servers` tool was removed — duplicates OpenCode's built-in `LspServers` tool
|
||||
- Synced with OpenCode's `server.ts` — when adding servers, check upstream first
|
||||
Reference in New Issue
Block a user