core/go-ai
8
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
go-ai/docs/tools.md
Snider 9016e2ee7d docs: graduate TODO/FINDINGS into production documentation 
Replace internal task tracking (TODO.md, FINDINGS.md) with four
structured documentation files covering architecture, tool reference,
development guide, and project history. Trim CLAUDE.md to agent
instructions only — all detailed content now lives in docs/.

- docs/architecture.md: subsystem plugin model, transports, IDE bridge,
  AI facade, full package layout
- docs/tools.md: all 49 MCP tools with parameters and descriptions
- docs/development.md: prerequisites, test patterns, adding tools/subsystems
- docs/history.md: split history, 5 phases with commit hashes, known issues

Co-Authored-By: Virgil <virgil@lethean.io>
2026-02-20 14:54:05 +00:00

1447 lines
44 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# go-ai MCP Tool Reference
**Module**: `forge.lthn.ai/core/go-ai`
This document is the authoritative reference for every MCP tool exposed by the go-ai hub. It is generated from the source definitions in `mcp/` and `mcp/ide/`.
---
## Overview
go-ai exposes **49 tools** across 13 functional groups via the [Model Context Protocol](https://modelcontextprotocol.io/). The server can be started in two modes:
- **Stdio** (default): `core mcp serve` — standard MCP transport for use with Claude, Cursor, and other MCP clients.
- **TCP**: `MCP_ADDR=:9000 core mcp serve` — listens on a TCP socket for programmatic access.
### Registration model
Tools are registered in two tiers:
1. **Built-in tools** (registered unconditionally in `mcp.New()`): file operations, directory operations, language detection, RAG, metrics, and webview tools. These are always present regardless of configuration.
2. **Subsystem tools** (registered via `WithSubsystem()`): ML, process management, WebSocket, and IDE tools. These require the corresponding backend service to be provided via an `Option` at construction time. Process and WebSocket tools are silently omitted if their respective services are not supplied. IDE tools are provided by the `ide.Subsystem` subsystem.
### Workspace sandboxing
All file and directory tools operate within a sandboxed filesystem medium. By default the sandbox root is the current working directory at the time `mcp.New()` is called. The root can be changed with `WithWorkspaceRoot(path)`. All paths supplied to file tools are validated to remain within this root — path traversal attempts are rejected.
### Audit logging
Every tool execution is logged. Tools that perform writes, process control, or browser automation are logged at `Security` level. Read-only tools are logged at `Info` level.
---
## Tool Groups
| Group | Tools | File |
|---|---|---|
| File Operations | 6 | `mcp/mcp.go` |
| Directory Operations | 2 | `mcp/mcp.go` |
| Language Detection | 2 | `mcp/mcp.go` |
| RAG — Vector Search | 3 | `mcp/tools_rag.go` |
| ML — Inference & Scoring | 5 | `mcp/tools_ml.go` |
| Metrics | 2 | `mcp/tools_metrics.go` |
| Process Management | 6 | `mcp/tools_process.go` |
| WebSocket | 2 | `mcp/tools_ws.go` |
| Browser Automation | 10 | `mcp/tools_webview.go` |
| IDE Chat | 5 | `mcp/ide/tools_chat.go` |
| IDE Build | 3 | `mcp/ide/tools_build.go` |
| IDE Dashboard | 3 | `mcp/ide/tools_dashboard.go` |
---
## File Operations
Six tools for reading, writing, editing, renaming, deleting, and checking files. All paths are resolved relative to the configured workspace root and must not escape it.
---
### `file_read`
Read the contents of a file.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Path | `string` | `path` | Yes | Path to the file, relative to workspace root |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Content | `string` | `content` | Full file contents |
| Language | `string` | `language` | Detected language ID (see `lang_detect`) |
| Path | `string` | `path` | Echoed input path |
**Notes**
The language field is populated by extension-based detection and will be `"plaintext"` for unrecognised extensions. The call fails if the path does not exist or points outside the workspace root.
---
### `file_write`
Write content to a file, creating it and any intermediate directories if they do not exist.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Path | `string` | `path` | Yes | Destination path, relative to workspace root |
| Content | `string` | `content` | Yes | Content to write |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Success | `bool` | `success` | Whether the write succeeded |
| Path | `string` | `path` | Echoed input path |
**Notes**
Overwrites any existing file at the given path without warning. Parent directories are created automatically. Logged at `Security` level.
---
### `file_edit`
Edit a file by replacing one occurrence (or all occurrences) of `old_string` with `new_string`. The file must already exist.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Path | `string` | `path` | Yes | Path to the file |
| OldString | `string` | `old_string` | Yes | Exact string to find; must not be empty |
| NewString | `string` | `new_string` | Yes | Replacement string (may be empty to delete) |
| ReplaceAll | `bool` | `replace_all` | No | Replace every occurrence; default is first only |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Path | `string` | `path` | Echoed input path |
| Success | `bool` | `success` | Whether the edit succeeded |
| Replacements | `int` | `replacements` | Number of occurrences replaced |
**Notes**
Returns an error if `old_string` is empty or is not found in the file. With `replace_all=false` (default) only the first occurrence is replaced and `replacements` will be `1`. With `replace_all=true` all occurrences are replaced and `replacements` reflects the total count.
---
### `file_delete`
Delete a file or empty directory.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Path | `string` | `path` | Yes | Path to delete |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Success | `bool` | `success` | Whether the deletion succeeded |
| Path | `string` | `path` | Echoed input path |
**Notes**
Non-empty directories are not deleted; use multiple calls or a process tool to remove them recursively. Logged at `Security` level.
---
### `file_rename`
Rename or move a file within the workspace.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| OldPath | `string` | `oldPath` | Yes | Current path |
| NewPath | `string` | `newPath` | Yes | Destination path |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Success | `bool` | `success` | Whether the rename succeeded |
| OldPath | `string` | `oldPath` | Echoed source path |
| NewPath | `string` | `newPath` | Echoed destination path |
**Notes**
Both paths must remain within the workspace root. Can be used to move files between subdirectories. Logged at `Security` level.
---
### `file_exists`
Check whether a path exists and whether it is a file or directory.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Path | `string` | `path` | Yes | Path to check |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Exists | `bool` | `exists` | Whether the path exists |
| IsDir | `bool` | `isDir` | Whether the path is a directory |
| Path | `string` | `path` | Echoed input path |
**Notes**
Returns `exists=false` for paths that do not exist or are inaccessible. Does not distinguish between a missing path and a permission error.
---
## Directory Operations
Two tools for listing and creating directories within the workspace.
---
### `dir_list`
List the contents of a directory.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Path | `string` | `path` | Yes | Directory path, relative to workspace root |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Entries | `[]DirectoryEntry` | `entries` | List of entries |
| Path | `string` | `path` | Echoed input path |
**DirectoryEntry fields**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Name | `string` | `name` | Entry name (filename only) |
| Path | `string` | `path` | Entry path (joined with input path) |
| IsDir | `bool` | `isDir` | Whether the entry is a directory |
| Size | `int64` | `size` | File size in bytes; 0 for directories |
**Notes**
Lists only the immediate children; not recursive. The `path` field in each entry preserves the relative form of the input path.
---
### `dir_create`
Create a new directory, including any necessary parent directories.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Path | `string` | `path` | Yes | Directory path to create |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Success | `bool` | `success` | Whether the directory was created |
| Path | `string` | `path` | Echoed input path |
**Notes**
Behaves like `mkdir -p`; does not fail if the directory already exists.
---
## Language Detection
Two tools for working with the built-in language registry.
---
### `lang_detect`
Detect the programming language of a file based on its extension or name.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Path | `string` | `path` | Yes | File path (the file need not exist; only the name is inspected) |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Language | `string` | `language` | Detected language ID |
| Path | `string` | `path` | Echoed input path |
**Notes**
Detection is purely extension-based. `Dockerfile` (exact name, no extension) is detected as `"dockerfile"`. Unknown extensions return `"plaintext"`.
---
### `lang_list`
Get the list of all supported programming languages.
**Parameters**
None.
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Languages | `[]LanguageInfo` | `languages` | All supported language entries |
**LanguageInfo fields**
| Field | Type | JSON key | Description |
|---|---|---|---|
| ID | `string` | `id` | Language identifier used throughout the API |
| Name | `string` | `name` | Human-readable display name |
| Extensions | `[]string` | `extensions` | File extensions that map to this language |
**Supported languages**
`typescript`, `javascript`, `go`, `python`, `rust`, `java`, `php`, `ruby`, `html`, `css`, `json`, `yaml`, `markdown`, `sql`, `shell`
The full detection set (including `c`, `cpp`, `csharp`, `scss`, `xml`, `swift`, `kotlin`, `dockerfile`) is available via `lang_detect` but is not enumerated by `lang_list`.
---
## RAG — Vector Search
Three tools for semantic document retrieval and ingestion. These tools require:
- **Qdrant** running at `localhost:6334` (default gRPC port)
- **Ollama** running at `localhost:11434` for embedding generation
The default collection name is `hostuk-docs`.
---
### `rag_query`
Query the RAG vector database for relevant documentation. Returns semantically similar content based on the query.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Question | `string` | `question` | Yes | The natural-language query |
| Collection | `string` | `collection` | No | Collection name; default `hostuk-docs` |
| TopK | `int` | `topK` | No | Number of results to return; default `5` |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Results | `[]RAGQueryResult` | `results` | Ordered list of matching chunks |
| Query | `string` | `query` | Echoed question |
| Collection | `string` | `collection` | Collection used |
| Context | `string` | `context` | Pre-formatted context string suitable for injection into a prompt |
**RAGQueryResult fields**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Content | `string` | `content` | The chunk text |
| Source | `string` | `source` | Original source file or URL |
| Section | `string` | `section` | Section heading within the source (if available) |
| Category | `string` | `category` | Category tag (if available) |
| ChunkIndex | `int` | `chunkIndex` | Chunk position within the source document |
| Score | `float32` | `score` | Cosine similarity score |
**Notes**
Returns an error if `question` is empty. Results are ordered by descending similarity score. The `context` field is ready for direct use in a system prompt.
---
### `rag_ingest`
Ingest documents into the RAG vector database. Supports both single files and entire directories.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Path | `string` | `path` | Yes | File or directory path to ingest |
| Collection | `string` | `collection` | No | Target collection; default `hostuk-docs` |
| Recreate | `bool` | `recreate` | No | Drop and recreate the collection before ingestion |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Success | `bool` | `success` | Whether ingestion succeeded |
| Path | `string` | `path` | Echoed input path |
| Collection | `string` | `collection` | Collection used |
| Chunks | `int` | `chunks` | Number of chunks indexed (file only; `0` for directory) |
| Message | `string` | `message` | Human-readable summary |
**Notes**
The path is validated against the workspace medium (sandboxed). For directory ingestion the chunk count is not returned. Setting `recreate=true` destroys all existing vectors in the collection before ingesting. Logged at `Security` level.
---
### `rag_collections`
List all available collections in the Qdrant vector database.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| ShowStats | `bool` | `show_stats` | No | Include point count and status for each collection |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Collections | `[]CollectionInfo` | `collections` | List of collections |
**CollectionInfo fields**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Name | `string` | `name` | Collection name |
| PointsCount | `uint64` | `points_count` | Total vectors stored (only present when `show_stats=true`) |
| Status | `string` | `status` | Qdrant collection status (only present when `show_stats=true`) |
**Notes**
Opens a short-lived Qdrant client connection per call. Stats are fetched per-collection and failures for individual collections are logged and skipped rather than aborting the entire response.
---
## ML — Inference & Scoring
Five tools for text generation, response scoring, capability probing, pipeline status, and backend enumeration. These tools are provided by the `MLSubsystem` and require a configured `go-ml` service instance (`ml.Service`).
The generation path is: `go-ai` → `go-ml.Service.Generate` → `InferenceAdapter` → `inference.TextModel` (from `go-inference`).
---
### `ml_generate`
Generate text via a configured ML inference backend.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Prompt | `string` | `prompt` | Yes | The input prompt |
| Backend | `string` | `backend` | No | Backend name; uses service default if omitted |
| Model | `string` | `model` | No | Model override for backends that support multiple models |
| Temperature | `float64` | `temperature` | No | Sampling temperature |
| MaxTokens | `int` | `max_tokens` | No | Maximum tokens to generate |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Response | `string` | `response` | Generated text |
| Backend | `string` | `backend` | Backend used |
| Model | `string` | `model` | Model used (if applicable) |
**Notes**
Returns an error if `prompt` is empty. Backend selection falls through to the service default when `backend` is not specified. Available backends can be queried with `ml_backends`.
---
### `ml_score`
Score a prompt/response pair using one or more scoring suites.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Prompt | `string` | `prompt` | Yes | The original prompt |
| Response | `string` | `response` | Yes | The model response to evaluate |
| Suites | `string` | `suites` | No | Comma-separated suite names; default `heuristic` |
Available suites: `heuristic`, `semantic`
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Heuristic | `*ml.HeuristicScores` | `heuristic` | Length, structure, and format heuristics (present when requested) |
| Semantic | `*ml.SemanticScores` | `semantic` | LLM judge scores (present when requested) |
| Content | `*ml.ContentScores` | `content` | Content scores (not available via this tool; use `ml_probe`) |
**Notes**
`heuristic` scoring requires no backend. `semantic` scoring requires a judge backend to be configured in the ML service; the call returns an error if none is present. The `content` suite is not supported by this tool — use `ml_probe` instead. Both `prompt` and `response` must be non-empty.
---
### `ml_probe`
Run capability probes against an inference backend. Each probe sends a structured prompt to the backend and records the response.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Backend | `string` | `backend` | No | Backend name; uses service default if omitted |
| Categories | `string` | `categories` | No | Comma-separated category names to filter probes; all categories run if omitted |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Total | `int` | `total` | Number of probes executed |
| Results | `[]MLProbeResultItem` | `results` | Per-probe results |
**MLProbeResultItem fields**
| Field | Type | JSON key | Description |
|---|---|---|---|
| ID | `string` | `id` | Probe identifier |
| Category | `string` | `category` | Probe category |
| Response | `string` | `response` | Backend response, or an error string prefixed with `"error: "` |
**Notes**
Probes are drawn from `ml.CapabilityProbes` defined in `go-ml`. Individual probe failures are captured as error strings in the response rather than aborting the entire run. Temperature is fixed at `0.7` and `MaxTokens` at `2048` for all probes.
---
### `ml_status`
Show training and generation progress from InfluxDB.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| InfluxURL | `string` | `influx_url` | No | InfluxDB URL; default `http://localhost:8086` |
| InfluxDB | `string` | `influx_db` | No | Database name; default `lem` |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Status | `string` | `status` | Formatted status report as a multi-line string |
**Notes**
Connects to InfluxDB on each call. Returns an error if the InfluxDB instance is unreachable.
---
### `ml_backends`
List available inference backends and their status.
**Parameters**
None.
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Backends | `[]MLBackendInfo` | `backends` | All registered backends |
| Default | `string` | `default` | Name of the default backend |
**MLBackendInfo fields**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Name | `string` | `name` | Backend identifier |
| Available | `bool` | `available` | Whether the backend is currently available |
**Notes**
Queries the `go-inference` global registry directly, bypassing `go-ml.Service`. This is the canonical source of truth for which backends are compiled in and available at runtime.
---
## Metrics
Two tools for recording and querying agent activity events. Events are stored in daily JSONL files on the local filesystem via the `go-ai/ai` package.
---
### `metrics_record`
Record a metrics event for AI or security tracking.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Type | `string` | `type` | Yes | Event type identifier |
| AgentID | `string` | `agent_id` | No | Agent identifier |
| Repo | `string` | `repo` | No | Repository name associated with the event |
| Data | `map[string]any` | `data` | No | Arbitrary additional event data |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Success | `bool` | `success` | Whether the event was recorded |
| Timestamp | `time.Time` | `timestamp` | Server-assigned event timestamp |
**Notes**
The timestamp is assigned by the server at the moment of recording; any timestamp in `data` is treated as user data only. Returns an error if `type` is empty.
---
### `metrics_query`
Query metrics events and get aggregated statistics by type, repository, and agent.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Since | `string` | `since` | No | Lookback window; default `7d` |
Supported duration formats: `Nd` (days), `Nh` (hours), `Nm` (minutes). Examples: `"7d"`, `"24h"`, `"30m"`.
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Total | `int` | `total` | Total events in window |
| ByType | `[]MetricCount` | `by_type` | Event counts grouped by type |
| ByRepo | `[]MetricCount` | `by_repo` | Event counts grouped by repository |
| ByAgent | `[]MetricCount` | `by_agent` | Event counts grouped by agent ID |
| Events | `[]MetricEventBrief` | `events` | The 10 most recent events, newest first |
**MetricCount fields**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Key | `string` | `key` | Group key (type name, repo name, or agent ID) |
| Count | `int` | `count` | Number of events in this group |
**MetricEventBrief fields**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Type | `string` | `type` | Event type |
| Timestamp | `time.Time` | `timestamp` | Event timestamp |
| AgentID | `string` | `agent_id` | Agent identifier (if set) |
| Repo | `string` | `repo` | Repository name (if set) |
**Notes**
Returns an error if the `since` value cannot be parsed. The duration unit must be a single character: `d`, `h`, or `m`. Durations must be positive integers.
---
## Process Management
Six tools for starting, stopping, and interacting with external processes. These tools are only registered when a `process.Service` instance is provided via `WithProcessService()` at construction time.
All process-control operations (`process_start`, `process_stop`, `process_kill`, `process_input`) are logged at `Security` level.
---
### `process_start`
Start a new external process. Returns a process ID for tracking.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Command | `string` | `command` | Yes | The executable to run |
| Args | `[]string` | `args` | No | Command-line arguments |
| Dir | `string` | `dir` | No | Working directory for the process |
| Env | `[]string` | `env` | No | Additional environment variables in `KEY=VALUE` format |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| ID | `string` | `id` | Unique process identifier used in subsequent calls |
| PID | `int` | `pid` | Operating system process ID |
| Command | `string` | `command` | Echoed command |
| Args | `[]string` | `args` | Echoed arguments |
| StartedAt | `time.Time` | `startedAt` | Process start time |
**Notes**
Returns an error if `command` is empty. The process is managed by the `process.Service`; its output is captured and available via `process_output`.
---
### `process_stop`
Gracefully stop a running process by ID.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| ID | `string` | `id` | Yes | Process ID returned by `process_start` |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| ID | `string` | `id` | Echoed process ID |
| Success | `bool` | `success` | Whether the stop signal was sent |
| Message | `string` | `message` | Status message |
**Notes**
The current implementation sends `SIGKILL`. A SIGTERM-first approach may be introduced in a future version. If the process does not respond, use `process_kill`.
---
### `process_kill`
Force kill a process by ID.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| ID | `string` | `id` | Yes | Process ID returned by `process_start` |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| ID | `string` | `id` | Echoed process ID |
| Success | `bool` | `success` | Whether the kill succeeded |
| Message | `string` | `message` | Status message |
**Notes**
Sends an unconditional kill signal via `process.Service.Kill()`. Use when `process_stop` does not succeed within an acceptable time.
---
### `process_list`
List all managed processes.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| RunningOnly | `bool` | `running_only` | No | Return only actively running processes; default `false` |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Processes | `[]ProcessInfo` | `processes` | List of process records |
| Total | `int` | `total` | Number of records returned |
**ProcessInfo fields**
| Field | Type | JSON key | Description |
|---|---|---|---|
| ID | `string` | `id` | Process identifier |
| Command | `string` | `command` | Executable name |
| Args | `[]string` | `args` | Arguments |
| Dir | `string` | `dir` | Working directory |
| Status | `string` | `status` | Process status string |
| PID | `int` | `pid` | OS process ID |
| ExitCode | `int` | `exitCode` | Exit code (meaningful only after termination) |
| StartedAt | `time.Time` | `startedAt` | Process start time |
| Duration | `time.Duration` | `duration` | Elapsed or total runtime |
---
### `process_output`
Get the captured stdout/stderr output of a process by ID.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| ID | `string` | `id` | Yes | Process ID |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| ID | `string` | `id` | Echoed process ID |
| Output | `string` | `output` | Captured output as a single string |
**Notes**
Output is buffered by `process.Service`. For streaming output in real time, connect a WebSocket subscriber via `ws_start` and subscribe to the process channel.
---
### `process_input`
Send text to the stdin of a running process.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| ID | `string` | `id` | Yes | Process ID |
| Input | `string` | `input` | Yes | Text to write to stdin |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| ID | `string` | `id` | Echoed process ID |
| Success | `bool` | `success` | Whether the input was delivered |
| Message | `string` | `message` | Status message |
**Notes**
Returns an error if the process is not found or if `input` is empty. Does not append a newline automatically; include `"\n"` in `input` if required.
---
## WebSocket
Two tools for starting and inspecting the WebSocket hub used for real-time process output streaming. These tools are only registered when a `ws.Hub` instance is provided via `WithWSHub()` at construction time.
The WebSocket endpoint is served at `/ws` on the configured address.
---
### `ws_start`
Start the WebSocket server for real-time process output streaming.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Addr | `string` | `addr` | No | Listen address in `host:port` format; default `":8080"` |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Success | `bool` | `success` | Whether the server started (or was already running) |
| Addr | `string` | `addr` | Actual address the server is bound to |
| Message | `string` | `message` | Status message including the full WebSocket URL |
**Notes**
If the server is already running, returns the existing address without error. The WebSocket URL takes the form `ws://<addr>/ws`. Logged at `Security` level because it opens a network listener.
---
### `ws_info`
Get WebSocket hub statistics.
**Parameters**
None.
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Clients | `int` | `clients` | Number of currently connected WebSocket clients |
| Channels | `int` | `channels` | Number of active subscription channels |
---
## Browser Automation
Ten tools for controlling a Chrome browser via the Chrome DevTools Protocol (CDP). All browser tools share a single global `webview.Webview` instance; `webview_connect` must be called before any other browser tool in a session.
**Prerequisite**: start Chrome with remote debugging enabled:
```
google-chrome --remote-debugging-port=9222
```
`webview_connect`, `webview_eval`, and `webview_navigate` are logged at `Security` level due to their capability to exfiltrate data or execute arbitrary code.
---
### `webview_connect`
Connect to a running Chrome instance via the Chrome DevTools Protocol.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| DebugURL | `string` | `debug_url` | Yes | Chrome DevTools URL, e.g. `http://localhost:9222` |
| Timeout | `int` | `timeout` | No | Default operation timeout in seconds; default `30` |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Success | `bool` | `success` | Whether the connection was established |
| Message | `string` | `message` | Status message |
**Notes**
Closes any existing connection before establishing a new one. Returns an error if `debug_url` is empty or if Chrome is not reachable at the given address.
---
### `webview_disconnect`
Disconnect from Chrome DevTools and release the connection.
**Parameters**
None.
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Success | `bool` | `success` | Whether the disconnection succeeded |
| Message | `string` | `message` | Status message |
**Notes**
Returns `success=true` with message `"No active connection"` if no connection was open. Safe to call multiple times.
---
### `webview_navigate`
Navigate the browser to a URL.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| URL | `string` | `url` | Yes | Fully qualified URL to navigate to |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Success | `bool` | `success` | Whether navigation was initiated |
| URL | `string` | `url` | Echoed URL |
**Notes**
Returns an error if not connected. Navigation is initiated but this tool does not wait for the page to finish loading; use `webview_wait` to synchronise on a page element after navigation.
---
### `webview_click`
Click on an element identified by a CSS selector.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Selector | `string` | `selector` | Yes | CSS selector for the target element |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Success | `bool` | `success` | Whether the click was performed |
**Notes**
Returns an error if not connected or if `selector` is empty. The selector must match at least one element; the first match is clicked.
---
### `webview_type`
Type text into an element identified by a CSS selector.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Selector | `string` | `selector` | Yes | CSS selector for the target element |
| Text | `string` | `text` | Yes | Text to type into the element |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Success | `bool` | `success` | Whether the text was typed |
**Notes**
Returns an error if not connected or if `selector` is empty. Appends to any existing content in the element rather than replacing it; clear the field first if a fresh value is required.
---
### `webview_query`
Query DOM elements by CSS selector.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Selector | `string` | `selector` | Yes | CSS selector |
| All | `bool` | `all` | No | Return all matching elements; default returns first match only |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Found | `bool` | `found` | Whether any elements matched |
| Count | `int` | `count` | Number of elements matched |
| Elements | `[]WebviewElementInfo` | `elements` | Element details |
**WebviewElementInfo fields**
| Field | Type | JSON key | Description |
|---|---|---|---|
| NodeID | `int` | `nodeId` | CDP node identifier |
| TagName | `string` | `tagName` | HTML tag name |
| Attributes | `map[string]string` | `attributes` | Element attributes |
| BoundingBox | `*webview.BoundingBox` | `boundingBox` | Element position and dimensions |
**Notes**
With `all=false` (default), returns at most one element and `found=false` when no match exists. With `all=true`, returns all matches. A zero-result `all=true` query returns `found=false` and an empty slice rather than an error.
---
### `webview_console`
Get browser console messages captured since the last call.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Clear | `bool` | `clear` | No | Clear the console buffer after reading; default `false` |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Messages | `[]WebviewConsoleMessage` | `messages` | Captured console messages |
| Count | `int` | `count` | Number of messages |
**WebviewConsoleMessage fields**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Type | `string` | `type` | Message level: `log`, `warn`, `error`, etc. |
| Text | `string` | `text` | Message content |
| Timestamp | `string` | `timestamp` | RFC 3339 timestamp |
| URL | `string` | `url` | Source URL (if available) |
| Line | `int` | `line` | Source line number (if available) |
**Notes**
Returns an error if not connected. Messages accumulate in a buffer; use `clear=true` to reset the buffer after reading to avoid receiving duplicate messages on subsequent calls.
---
### `webview_eval`
Evaluate a JavaScript expression in the browser context.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Script | `string` | `script` | Yes | JavaScript expression or statement to evaluate |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Success | `bool` | `success` | Whether evaluation succeeded |
| Result | `any` | `result` | Return value of the expression (JSON-serialisable) |
| Error | `string` | `error` | Error message if evaluation failed |
**Notes**
Returns an error if not connected or if `script` is empty. JavaScript errors are captured in the `error` field with `success=false` rather than being returned as tool-level errors. Logged at `Security` level.
---
### `webview_screenshot`
Capture a screenshot of the current browser viewport.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Format | `string` | `format` | No | Image format: `"png"` or `"jpeg"`; default `"png"` |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Success | `bool` | `success` | Whether the screenshot was captured |
| Data | `string` | `data` | Base64-encoded image data |
| Format | `string` | `format` | Format used |
**Notes**
Returns an error if not connected. The `data` field is standard base64 (not URL-safe); decode with standard base64 to obtain the raw image bytes.
---
### `webview_wait`
Wait for an element matching a CSS selector to appear in the DOM.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Selector | `string` | `selector` | Yes | CSS selector to wait for |
| Timeout | `int` | `timeout` | No | Maximum wait time in seconds |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Success | `bool` | `success` | Whether the element appeared within the timeout |
| Message | `string` | `message` | Status message including the matched selector |
**Notes**
Returns an error if not connected or if `selector` is empty. If the element does not appear before the timeout, an error is returned. The default timeout is inherited from the connection timeout set during `webview_connect`.
---
## IDE Chat
Five tools for interacting with agent chat sessions via the Laravel WebSocket bridge. These tools are provided by the `ide.Subsystem` and require a `ws.Hub` instance for real-time forwarding.
**Implementation status**: The Laravel backend integration is currently a stub. Tool calls emit bridge messages and return placeholder responses. Live data is delivered asynchronously via WebSocket subscriptions.
---
### `ide_chat_send`
Send a message to an agent chat session.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| SessionID | `string` | `sessionId` | Yes | Target session identifier |
| Message | `string` | `message` | Yes | Message content to send |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Sent | `bool` | `sent` | Whether the message was forwarded to the bridge |
| SessionID | `string` | `sessionId` | Echoed session ID |
| Timestamp | `time.Time` | `timestamp` | Server-assigned send timestamp |
**Notes**
The bridge forwards the message on the `chat:<sessionId>` channel. The agent's reply arrives asynchronously via the WebSocket connection. Returns an error if the bridge is not available.
---
### `ide_chat_history`
Retrieve message history for a chat session.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| SessionID | `string` | `sessionId` | Yes | Session identifier |
| Limit | `int` | `limit` | No | Maximum number of messages to return |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| SessionID | `string` | `sessionId` | Echoed session ID |
| Messages | `[]ChatMessage` | `messages` | Message list (currently empty; data arrives via WebSocket) |
**ChatMessage fields**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Role | `string` | `role` | `"user"` or `"assistant"` |
| Content | `string` | `content` | Message text |
| Timestamp | `time.Time` | `timestamp` | Message timestamp |
**Notes**
Currently returns an empty `messages` array. The history request is forwarded to the Laravel backend via the bridge; data is returned asynchronously.
---
### `ide_session_list`
List active agent sessions.
**Parameters**
None.
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Sessions | `[]Session` | `sessions` | Active sessions (currently empty; data arrives via WebSocket) |
**Session fields**
| Field | Type | JSON key | Description |
|---|---|---|---|
| ID | `string` | `id` | Session identifier |
| Name | `string` | `name` | Human-readable session name |
| Status | `string` | `status` | Session status string |
| CreatedAt | `time.Time` | `createdAt` | Session creation time |
---
### `ide_session_create`
Create a new agent session.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Name | `string` | `name` | Yes | Human-readable name for the new session |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Session | `Session` | `session` | The new session record |
**Notes**
Currently returns a placeholder session with `status="creating"` and no `id`. The actual session is created asynchronously by the Laravel backend; the final record arrives via WebSocket.
---
### `ide_plan_status`
Get the current plan status for an agent session.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| SessionID | `string` | `sessionId` | Yes | Session identifier |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| SessionID | `string` | `sessionId` | Echoed session ID |
| Status | `string` | `status` | Plan status; currently `"unknown"` |
| Steps | `[]PlanStep` | `steps` | Plan steps (currently empty) |
**PlanStep fields**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Name | `string` | `name` | Step name |
| Status | `string` | `status` | Step status |
---
## IDE Build
Three tools for querying CI build status and logs. Provided by `ide.Subsystem`; data is sourced from the Laravel backend via the WebSocket bridge.
**Implementation status**: Stub. Tool calls emit bridge messages and return placeholder responses.
---
### `ide_build_status`
Get the status of a specific build.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| BuildID | `string` | `buildId` | Yes | Build identifier |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Build | `BuildInfo` | `build` | Build record |
**BuildInfo fields**
| Field | Type | JSON key | Description |
|---|---|---|---|
| ID | `string` | `id` | Build identifier |
| Repo | `string` | `repo` | Repository name |
| Branch | `string` | `branch` | Git branch |
| Status | `string` | `status` | Build status; currently `"unknown"` |
| Duration | `string` | `duration` | Build duration (if complete) |
| StartedAt | `time.Time` | `startedAt` | Build start time |
---
### `ide_build_list`
List recent builds, optionally filtered by repository.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Repo | `string` | `repo` | No | Filter by repository name |
| Limit | `int` | `limit` | No | Maximum number of builds to return |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Builds | `[]BuildInfo` | `builds` | Build records (currently empty) |
---
### `ide_build_logs`
Retrieve log output for a build.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| BuildID | `string` | `buildId` | Yes | Build identifier |
| Tail | `int` | `tail` | No | Return only the last N lines |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| BuildID | `string` | `buildId` | Echoed build identifier |
| Lines | `[]string` | `lines` | Log lines (currently empty) |
---
## IDE Dashboard
Three tools for querying platform-wide overview, activity, and aggregate metrics. Provided by `ide.Subsystem`; data is sourced from the Laravel backend via the WebSocket bridge.
**Implementation status**: `ide_dashboard_overview` returns live bridge connectivity status. The other two tools are stubs that forward requests and return placeholder responses.
---
### `ide_dashboard_overview`
Get a high-level overview of the platform.
**Parameters**
None.
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Overview | `DashboardOverview` | `overview` | Platform summary |
**DashboardOverview fields**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Repos | `int` | `repos` | Number of repositories (stub; currently `0`) |
| Services | `int` | `services` | Number of services (stub; currently `0`) |
| ActiveSessions | `int` | `activeSessions` | Active agent sessions (stub; currently `0`) |
| RecentBuilds | `int` | `recentBuilds` | Recent build count (stub; currently `0`) |
| BridgeOnline | `bool` | `bridgeOnline` | Whether the Laravel WebSocket bridge is currently connected |
**Notes**
`BridgeOnline` is the only live field. All other fields return `0` until the Laravel backend integration is complete.
---
### `ide_dashboard_activity`
Get the recent activity feed.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Limit | `int` | `limit` | No | Maximum number of events to return |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Events | `[]ActivityEvent` | `events` | Activity events (currently empty) |
**ActivityEvent fields**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Type | `string` | `type` | Event category |
| Message | `string` | `message` | Human-readable description |
| Timestamp | `time.Time` | `timestamp` | Event timestamp |
---
### `ide_dashboard_metrics`
Get aggregate build and agent metrics for a time period.
**Parameters**
| Field | Type | JSON key | Required | Description |
|---|---|---|---|---|
| Period | `string` | `period` | No | Time period: `"1h"`, `"24h"`, or `"7d"`; default `"24h"` |
**Response**
| Field | Type | JSON key | Description |
|---|---|---|---|
| Period | `string` | `period` | Echoed period |
| Metrics | `DashboardMetrics` | `metrics` | Aggregate metrics |
**DashboardMetrics fields**
| Field | Type | JSON key | Description |
|---|---|---|---|
| BuildsTotal | `int` | `buildsTotal` | Total builds in period |
| BuildsSuccess | `int` | `buildsSuccess` | Successful builds |
| BuildsFailed | `int` | `buildsFailed` | Failed builds |
| AvgBuildTime | `string` | `avgBuildTime` | Average build duration |
| AgentSessions | `int` | `agentSessions` | Agent sessions created |
| MessagesTotal | `int` | `messagesTotal` | Total chat messages |
| SuccessRate | `float64` | `successRate` | Build success ratio (0.0–1.0) |
**Notes**
All fields currently return zero values. Data will be populated once the Laravel backend integration is complete.
Reference in a new issue View git blame Copy permalink