+
+
+llm-coding-tools
+
+ Production-grade coding agent tools in Rust.
+ ~10 MiB. No TUI. Embed it anywhere.
+
+ 
+ 
+ 
+ 
+
+
+
+
+
+---
+
+## Why this project?
+
+[OpenCode] is a fun, fast-moving TUI coding agent - but it ships breaking changes
+regularly. It's a **TypeScript application** that uses ~400 MiB of RAM and runs
+as a separate process. What if you need the same agent tooling for a server? A Discord bot?
+A CI pipeline? Custom software?
+
+**llm-coding-tools** ships the core agent tooling as a **lightweight headless Rust
+library** - same tool set, similar agent format, same system prompts - at a fraction
+of the resource cost.
+
+
+
+
+
+
+
+
+
+## Features
+
+
+
+ ~10 MiB
+ Memory usage
+
+
+ 10
+ Built-in tools
+
+
+ ~2K
+ System prompt tokens
+
+
+6 / 11
+ CI platforms / semver-stable APIs
+
+
+
+## Quick Start
+
+**1.** Add the dependencies:
+
+```toml
+[dependencies]
+llm-coding-tools-serdesai = "0.2"
+llm-coding-tools-agents = "0.1"
+llm-coding-tools-core = "0.2"
+llm-coding-tools-models-dev = "0.1"
+tokio = { version = "1", features = ["full"] }
+```
+
+**2.** Create an agent file (`agents/coder.md`):
+
+```markdown
+---
+name: coder
+mode: all
+description: A coding agent that can read, search, and edit files.
+permission:
+ read: allow
+ write: allow
+ edit: allow
+ glob: allow
+ grep: allow
+ bash: allow
+ webfetch: allow
+ task: deny
+---
+
+You are a coding assistant. Use the available tools to complete the user's task.
+```
+
+**3.** Load the catalog, build the agent, and run:
+
+```rust
+use llm_coding_tools_agents::{AgentCatalog, AgentLoader, AgentRuntimeBuilder};
+use llm_coding_tools_core::CredentialResolver;
+use llm_coding_tools_models_dev::ModelsDevCatalog;
+use llm_coding_tools_serdesai::{AgentBuildContext, AgentDefaults};
+use std::{path::PathBuf, sync::Arc};
+
+#[tokio::main]
+async fn main() -> Result<(), Box
+
+ 📄 File Operations
+Read, write, and edit files with line-numbered output, offset/limit, and exact text replacement.
+
+
+ 🔍 Search
+Glob pattern matching and regex content search with match metadata and configurable limits.
+
+
+ 💻 Shell Execution
+Cross-platform command execution with timeout, captured output, and optional Linux sandboxing.
+
+
+ 🌐 Web Fetch
+Fetch URLs and convert HTML to markdown. Configurable timeouts and size limits.
+
+
+ 🔒 Sandboxing
+Linux bubblewrap profiles for shell isolation. Network isolation, filtered filesystem, scrubbed env.
+
+
+ 🤖 Agent Runtime
+Load agent markdown files based on [OpenCode]'s schema. Multi-agent delegation with recursion depth limits.
+
+
+ 🗄️ Model Catalog
+Sync the models.dev catalog with ETag caching, zstd compression, and offline fallback.
+
+
+ 🔑 Permissions
+Default-deny tool access with ordered rules where the last matching rule takes priority. Wildcard patterns for delegation control.
+
+
+ ⚡ Async + Sync
+Every tool compiles as async (tokio) or blocking. Zero overhead at the call site.
+
+
+🧩 Embeddable
+Framework-agnostic core. Use the SerdesAI integration or build your own with the core primitives.
+
+
+
+## Comparison with OpenCode
+
+
+
+ core
+Framework-agnostic tools for building coding agents. File operations, search, shell, permissions, system prompts - use with any LLM framework.
+
+
+ agents
+Load agent markdown files based on [OpenCode]'s schema into a typed catalog. Default-deny permissions with granular path matching.
+
+
+ serdesai
+Ready-to-use SerdesAI (LLM serialization framework) integration. 15 LLM provider adapters, multi-agent task delegation with recursion depth limits.
+
+
+ bubblewrap
+Sandbox shell execution on Linux. Network-isolated, filesystem-filtered profiles for untrusted input. Two presets included.
+
+
+models-dev
+Sync the models.dev catalog. ETag caching, offline fallback. ~3000 models in ~24 KiB.
+| Aspect | +OpenCode | +llm-coding-tools | +
|---|---|---|
| Language | TypeScript | Rust |
| Runtime | Bun | tokio / blocking |
| Memory | ~400 MiB | ~10 MiB |
| Interface | TUI / Desktop / IDE | Library (headless, no UI) |
| Agent format | Markdown + YAML | Similar format |
| Permissions | Default-allow + interactive ask | Default-deny |
| Tool set | 14 tools | 10 tools (core set) |
| LLM framework | AI SDK (TypeScript) | SerdesAI / bring your own |
| Sandboxing | - | Linux bubblewrap profiles |
| Embeddable | Client/server HTTP API | Rust library (crate) |
+ Write specific rules **last** in your config so they override the catch-all patterns. + + Common patterns: + + - **Default deny, allow specific**: `"**": deny` first, specific `"path/**": allow` last + - **Default allow, deny specific**: `"**": allow` first, specific `"path/**": deny` last + +## Tool overview + +| Tool | Core function | What it does | +| ------------------------------------- | ------------------------ | ------------------------------------------------------- | +| [**read**](#read) | `read_file` | Read a file with offset/limit and optional line numbers | +| [**write**](#write) | `write_file` | Create or overwrite a file at a resolved path | +| [**edit**](#edit) | `edit_file` | Apply exact text replacements (find-and-replace) | +| [**glob**](#glob) | `glob_files` | Match filesystem paths by glob pattern | +| [**grep**](#grep) | `grep_search` | Search file contents by regex with match metadata | +| [**bash**](#bash) | `execute_command` | Execute shell commands with timeout and captured output | +| [**webfetch**](#webfetch) | `fetch_url` | Fetch a URL and return content as text or markdown | +| [**todoread**](#todoread--todowrite) | `read_todos` | Read shared todo list state | +| [**todowrite**](#todoread--todowrite) | `write_todos` | Update shared todo list state | +| [**task**](#task) | `TaskInput`/`TaskOutput` | Delegate work to a named sub-agent | + +### read + +Reads a file, optionally with line numbers and a windowed range. + +**Parameters:** + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------------------------------- | +| `path` | string | yes | Absolute file path (or relative to allowed dirs) | +| `offset` | number | no | Starting line number (1-indexed, default: 1) | +| `limit` | number | no | Max lines to return (default: from tool settings) | + +**Output:** Line-numbered file content. Lines beyond `max_line_length` are +truncated with `...`. + +**Configurable via [tool settings](#tool-settings):** `line_numbers`, `limit`, +`max_line_length` + +### write + +Creates or overwrites a file. Creates parent directories if they don't exist. + +**Parameters:** + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------ | +| `path` | string | yes | File path to write | +| `content` | string | yes | Content to write | + +**Output:** Confirmation message. + +### edit + +Applies exact text replacements to a file. The old text must match exactly +(including whitespace and indentation) or the edit fails. + +**Parameters:** + +| Parameter | Type | Required | Description | +| ---------- | ------ | -------- | ------------------ | +| `path` | string | yes | File path to edit | +| `old_text` | string | yes | Exact text to find | +| `new_text` | string | yes | Replacement text | + +**Output:** Confirmation with the number of replacements made. + +**Behaviour:** + +- If `old_text` matches exactly once, the replacement is applied +- If `old_text` matches multiple times, all occurrences are replaced +- If `old_text` is not found, the edit fails with an error + +### glob + +Matches filesystem paths by glob pattern. Uses the `.gitignore`-aware `ignore` +crate for fast traversal. + +**Parameters:** + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ---------------------------------------------- | +| `pattern` | string | yes | Glob pattern (e.g. `**/*.rs`, `src/**/*.toml`) | +| `path` | string | no | Root directory for the search | + +**Output:** List of matching file paths. + +**Configurable via [tool settings](#tool-settings):** `limit` + +### grep + +Searches file contents by regex pattern. Returns matching lines with metadata. + +**Parameters:** + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | --------------------------------- | +| `pattern` | string | yes | Regex pattern to search for | +| `path` | string | no | File or directory to search in | +| `include` | string | no | File pattern filter (e.g. `*.rs`) | + +**Output:** Matching lines with line numbers and file paths. + +**Configurable via [tool settings](#tool-settings):** `line_numbers`, `limit`, +`max_line_length` + +### bash + +Executes a shell command with timeout and captured output. + +**Parameters:** + +| Parameter | Type | Required | Description | +| ------------ | ------ | -------- | ----------------------------------------------- | +| `command` | string | yes | Shell command to execute | +| `timeout_ms` | number | no | Timeout in milliseconds (default from settings) | +| `workdir` | string | no | Working directory for the command | + +**Output:** Combined stdout and stderr. Non-zero exit codes are included in +the output. + +**Configurable via [tool settings](#tool-settings):** `timeout_ms`, `max_timeout_ms` + +**Sandboxing:** On Linux, you can enable the `linux-bubblewrap` feature to run +commands inside a [bubblewrap] sandbox. See [Sandboxing](sandboxing.md) for details. + +### webfetch + +Fetches a URL and returns the content. HTML pages are automatically converted +to markdown. + +**Parameters:** + +| Parameter | Type | Required | Description | +| ------------ | ------ | -------- | ----------------------- | +| `url` | string | yes | URL to fetch | +| `timeout_ms` | number | no | Timeout in milliseconds | + +**Output:** Page content as text or markdown. + +**Configurable via [tool settings](#tool-settings):** `timeout_ms`, +`max_timeout_ms`, `max_response_size` + +### todoread / todowrite + +Shared todo list state for tracking progress across tool calls. Useful for +agents that plan their work in steps. + +**todoread** returns the current todo list. **todowrite** validates and +replaces it. Both are stateless between agent runs. Create them with shared +state via [`create_todo_tools`][create_todo_tools] so that reads and writes +refer to the same list. + +**todoread parameters:** + +*(none - takes no parameters)* + +**todoread output:** Current todo list as formatted text. + +**todowrite parameters:** + +| Parameter | Type | Required | Description | +| --------- | ----- | -------- | -------------------------------------------------------------- | +| `todos` | array | yes | Complete list of todo items to set (replaces the current list) | + +Each todo item: + +| Field | Type | Required | Values | +| ---------- | ------ | -------- | -------------------------------------------------- | +| `id` | string | yes | Stable, non-empty identifier | +| `content` | string | yes | Short imperative task text | +| `status` | string | yes | `pending`, `in_progress`, `completed`, `cancelled` | +| `priority` | string | yes | `high`, `medium`, `low` | + +**todowrite output:** Confirmation with the number of items set. + +### task + +The task tool enables multi-agent delegation. An agent can invoke a named +sub-agent with a prompt and receive the result. + +**Parameters:** + +| Parameter | Type | Required | Description | +| --------------- | ------ | -------- | ------------------------------------------------------------ | +| `subagent_type` | string | yes | Exact name of the target subagent | +| `prompt` | string | yes | Full instructions for the delegated agent | +| `description` | string | yes | Short task label (3-5 words) | +| `command` | string | no | Optional context string identifying what triggered this task | + +**Output:** The delegated agent's response as a text summary. + +See [Getting Started](getting-started.md) for the full delegation model. + +## Tool Settings + +Some tools expose configurable settings. These are **host-side** constraints, +not parameters the LLM passes per call. + +### read + +| Setting | Type | Default | Min | Description | +| ----------------- | ------- | ------- | --- | --------------------------- | +| `line_numbers` | `bool` | `true` | - | Show line numbers in output | +| `limit` | `usize` | `2000` | `1` | Max lines returned per read | +| `max_line_length` | `usize` | `2000` | `4` | Max characters per line | + +### grep + +| Setting | Type | Default | Min | Description | +| ----------------- | ------- | ------- | --- | ----------------------------- | +| `line_numbers` | `bool` | `true` | - | Show line numbers in output | +| `limit` | `usize` | `100` | `1` | Max matches returned | +| `max_line_length` | `usize` | `2000` | `4` | Max characters per match line | + +### glob + +| Setting | Type | Default | Min | Description | +| ------- | ------- | ------- | --- | ----------------------- | +| `limit` | `usize` | `1000` | `1` | Max file paths returned | + +### bash + +| Setting | Type | Default | Min | Description | +| ---------------- | ----- | -------- | ------ | ------------------------------- | +| `timeout_ms` | `u32` | `120000` | `1000` | Default command timeout (ms) | +| `max_timeout_ms` | `u32` | `600000` | `1` | Max timeout the LLM can request | + +### webfetch + +| Setting | Type | Default | Min | Description | +| ------------------- | ------- | --------- | ------ | ------------------------------- | +| `timeout_ms` | `u32` | `30000` | `1000` | Default fetch timeout (ms) | +| `max_timeout_ms` | `u32` | `600000` | `1` | Max timeout the LLM can request | +| `max_response_size` | `usize` | `5242880` | `1` | Max response body size (bytes) | + +### Setting in agent files + +Override defaults in the agent file front matter under `tool_settings`: + +```yaml +--- +name: my-agent +tool_settings: + read: + line_numbers: false + limit: 500 + bash: + timeout_ms: 60000 + max_timeout_ms: 300000 +--- +``` + +!!! warning "Validation rules" + + - `max_timeout_ms` must be greater than or equal to `timeout_ms` (for both + bash and webfetch). + - `max_line_length` must be at least 4 to accommodate the `...` + truncation suffix plus at least one visible character. + +### Override in code + +There are two levels of API depending on how you use the library. + +**Agent-level settings** (llm-coding-tools-agents): + +Use [`AgentToolSettings`](https://docs.rs/llm-coding-tools-agents/latest/llm_coding_tools_agents/struct.AgentToolSettings.html) +when building an agent from an [`AgentConfig`](https://docs.rs/llm-coding-tools-agents/latest/llm_coding_tools_agents/struct.AgentConfig.html): + +```rust +use llm_coding_tools_agents::{AgentToolSettings, ReadToolSettings}; + +let settings = AgentToolSettings { + read: ReadToolSettings { + line_numbers: false, + limit: 500, + max_line_length: 2000, + }, + ..AgentToolSettings::default() +}; +``` + +**Tool-level settings** (llm-coding-tools-core / llm-coding-tools-serdesai): + +Use the builder pattern on each tool when constructing them individually: + +```rust +use llm_coding_tools_core::tools::ReadSettings; +use llm_coding_tools_serdesai::{ReadTool, AbsolutePathResolver, BashTool}; + +// Read +let settings = ReadSettings::new() + .with_default_limit(500)? + .with_max_line_length(1000)? + .with_line_numbers(false); +let tool = ReadTool::with_settings(AbsolutePathResolver, settings); + +// Bash +let tool = BashTool::new() + .with_timeouts(Some(30_000), Some(120_000)); +``` + +See the [API reference](https://docs.rs/llm-coding-tools-core) for the full +builder API on each settings type. + +## Path resolvers + +File tools (`read`, `write`, `edit`, `glob`, `grep`) are generic over a `PathResolver`. +This controls which paths the tools can access: + +| Resolver | Behaviour | +| ---------------------- | --------------------------------------------------------- | +| `AbsolutePathResolver` | Any absolute path is allowed. No restrictions. | +| `AllowedPathResolver` | Only paths within configured directories. Sandboxed mode. | +| `AllowedGlobResolver` | A workspace directory with glob-based allow/deny rules. | + +Agents use `AllowedGlobResolver` by default. If you don't need glob-based rules, +`AllowedPathResolver` or `AbsolutePathResolver` are slightly faster. + +For a deeper dive into path security, see [Sandboxing](sandboxing.md). + +[bubblewrap]: https://github.com/containers/bubblewrap +[create_todo_tools]: https://docs.rs/llm-coding-tools-serdesai/latest/llm_coding_tools_serdesai/tools/todo/fn.create_todo_tools.html +[llm-coding-tools-core]: https://docs.rs/llm-coding-tools-core +[llm-coding-tools-serdesai]: https://docs.rs/llm-coding-tools-serdesai +[Agents]: agents.md +[agent files]: agents.md diff --git a/docs/src/vendor/Reloaded/Images/Nexus-Heart-40.avif b/docs/src/vendor/Reloaded/Images/Nexus-Heart-40.avif new file mode 100644 index 00000000..65a7eb46 Binary files /dev/null and b/docs/src/vendor/Reloaded/Images/Nexus-Heart-40.avif differ diff --git a/docs/src/vendor/Reloaded/Images/Nexus-Icon-40.avif b/docs/src/vendor/Reloaded/Images/Nexus-Icon-40.avif new file mode 100644 index 00000000..9e3e3b26 Binary files /dev/null and b/docs/src/vendor/Reloaded/Images/Nexus-Icon-40.avif differ diff --git a/docs/src/vendor/Reloaded/Images/Reloaded-Heart-40.avif b/docs/src/vendor/Reloaded/Images/Reloaded-Heart-40.avif new file mode 100644 index 00000000..be000d31 Binary files /dev/null and b/docs/src/vendor/Reloaded/Images/Reloaded-Heart-40.avif differ diff --git a/docs/src/vendor/Reloaded/Images/Reloaded-Icon-40.avif b/docs/src/vendor/Reloaded/Images/Reloaded-Icon-40.avif new file mode 100644 index 00000000..691dc3ea Binary files /dev/null and b/docs/src/vendor/Reloaded/Images/Reloaded-Icon-40.avif differ diff --git a/docs/src/vendor/Reloaded/Stylesheets/reloaded.css b/docs/src/vendor/Reloaded/Stylesheets/reloaded.css new file mode 100644 index 00000000..4812481f --- /dev/null +++ b/docs/src/vendor/Reloaded/Stylesheets/reloaded.css @@ -0,0 +1,584 @@ +/* + Import Title Font: Montserrat + Falls back to Roboto +*/ +@import url('https://fonts.googleapis.com/css2?family=Montserrat:wght@600&display=swap'); + +/* + Nexus Mods Theme +*/ + +:root { + --md-admonition-icon--nexus: url('../Images/Nexus-Icon-40.avif'); + --md-admonition-icon--nexusheart: url('../Images/Nexus-Heart-40.avif'); + --md-admonition-icon--reloaded: url('../Images/Reloaded-Icon-40.avif'); + --md-admonition-icon--reloadedheart: url('../Images/Reloaded-Heart-40.avif'); +} + +/* Slate theme, i.e. dark mode */ + +[data-md-color-scheme="nexus-slate"] { + /* + Default Variables + */ + + /* For reuse later */ + --md-primary-fg-color-rgb: 217, 143, 64; + + /* Primary color shades */ + --md-primary-fg-color: #D98F40; + --md-primary-fg-color--light: #E0A362; + --md-primary-fg-color--dark: #C87B28; + + --md-primary-bg-color: #FFFFFF; + --md-primary-bg-color--light: #FFFFFFB2; + + /* Accent color shades */ + --md-accent-fg-color: #C87B28; + --md-accent-fg-color--transparent: #C87B2810; + + --md-accent-bg-color: #2A2C2B; + --md-accent-bg-color--light: #2A2C2B; + +/* + // Slate's hue in the range [0,360] - change this variable to alter the tone + // of the theme, e.g. to make it more redish or greenish. This is a slate- + // specific variable, but the same approach may be adapted to custom themes. +*/ + --md-hue: 31; + --nexus-background-primary: #101010; + --nexus-background-secondary: #181818; + --nexus-background-tertiary: #222222; + --nexus-background-content-primary: #1C1C1C; + --nexus-background-content-secondary: #2B2D2F; + + --nexus-font-primary: #FFFFFF; /* #FFFFFF */ + --nexus-font-secondary: #AAAAAA; /* #AAAAAA */ + --nexus-font-tertiary: #5A5A5A; /* #5A5A5A */ + + --nexus-font-primary-rgb: 255, 255, 255; /* #FFFFFF */ + --nexus-font-secondary-rgb: 170, 170, 170; /* #AAAAAA */ + --nexus-font-tertiary-rgb: 90, 90, 90; /* #5A5A5A */ + + /* Default color shades */ + --md-default-fg-color: var(--nexus-font-primary); + --md-default-fg-color--light: var(--nexus-font-secondary); + --md-default-fg-color--lighter: var(--nexus-font-tertiary); + --md-default-fg-color--lightest: rgba(var(--nexus-font-primary-rgb), 0.12); + --md-default-bg-color: var(--nexus-background-secondary); + --md-default-bg-color--light: var(--nexus-background-content-primary); + --md-default-bg-color--lighter: var(--nexus-background-tertiary); + --md-default-bg-color--lightest: var(--nexus-background-content-secondary); + + /* Code color shades */ + --md-code-fg-color: hsla(var(--md-hue), 18%, 86%, 1); + --md-code-bg-color: var(--nexus-background-content-secondary); + + /* Code highlighting color shades */ + --md-code-hl-color: #4287ff26; + --md-code-hl-number-color: hsla(219, 74%, 63%, 1); + --md-code-hl-special-color: hsla(340, 83%, 66%, 1); + --md-code-hl-function-color: hsla(219, 57%, 65%, 1); + --md-code-hl-constant-color: hsla(250, 62%, 70%, 1); + --md-code-hl-keyword-color: hsla(var(--md-hue), 66%, 64%, 1); + --md-code-hl-string-color: hsla(150, 58%, 44%, 1); + --md-code-hl-name-color: var(--md-code-fg-color); + --md-code-hl-operator-color: var(--md-default-fg-color--light); + --md-code-hl-punctuation-color: var(--md-default-fg-color--light); + --md-code-hl-comment-color: var(--md-default-fg-color--light); + --md-code-hl-generic-color: var(--md-default-fg-color--light); + --md-code-hl-variable-color: var(--md-default-fg-color--light); + + /* Typeset color shades */ + --md-typeset-color: var(--md-default-fg-color); + + /* Typeset `a` color shades */ + --md-typeset-a-color: var(--md-primary-fg-color); + + /* Typeset `mark` color shades */ + --md-typeset-mark-color: #4287ff4d; + + /* Typeset `kbd` color shades */ + --md-typeset-kbd-color: hsla(var(--md-hue), 15%, 94%, 0.12); + --md-typeset-kbd-accent-color: hsla(var(--md-hue), 15%, 94%, 0.2); + --md-typeset-kbd-border-color: hsla(var(--md-hue), 15%, 14%, 1); + + /* Typeset `table` color shades */ + --md-typeset-table-color: hsla(var(--md-hue), 75%, 95%, 0.12); + --md-typeset-table-color--light: hsla(var(--md-hue), 75%, 95%, 0.035); + + /* Admonition color shades */ + --md-admonition-fg-color: var(--md-default-fg-color); + --md-admonition-bg-color: var(--md-default-bg-color); + + /* Footer color shades */ + --md-footer-bg-color: var(--nexus-background-primary); + --md-footer-bg-color--dark: var(--nexus-background-primary); + + /* Shadow depth 1 */ + --md-shadow-z1: + 0 #{px2rem(4px)} #{px2rem(10px)} hsla(0, 0%, 0%, 0.2), + 0 0 #{px2rem(1px)} hsla(0, 0%, 0%, 0.1); + + /* Shadow depth 2 */ + --md-shadow-z2: + 0 #{px2rem(4px)} #{px2rem(10px)} hsla(0, 0%, 0%, 0.3), + 0 0 #{px2rem(1px)} hsla(0, 0%, 0%, 0.25); + + /* Shadow depth 3 */ + --md-shadow-z3: + 0 #{px2rem(4px)} #{px2rem(10px)} hsla(0, 0%, 0%, 0.4), + 0 0 #{px2rem(1px)} hsla(0, 0%, 0%, 0.35); + + /* Hide images for light mode */ + img[src$="#only-light"], + img[src$="#gh-light-mode-only"] { + display: none; + } + + /* Show images for dark mode */ + img[src$="#only-dark"], + img[src$="#gh-dark-mode-only"] { + display: initial; + } +} + +[data-md-color-scheme="nexus-slate"] .md-header { + background-color: var(--nexus-background-primary); +} + +[data-md-color-scheme="reloaded-slate"] { + /* + Default Variables + */ + + /* For reuse later */ + --md-primary-fg-color-rgb: 182, 99, 99; + + /* Primary color shades */ + --md-primary-fg-color: #793939; + --md-primary-fg-color--light: #B66363; + --md-primary-fg-color--lightest: #d6a8a8; + --md-primary-fg-color--dark: #572929; + + --md-primary-bg-color: #FFFFFF; + --md-primary-bg-color--light: #FFFFFFB2; + + /* Accent color shades */ + --md-accent-fg-color: #793939; + --md-accent-fg-color--transparent: #79393960; + + --md-accent-bg-color: #181818; + --md-accent-bg-color--light: #181818; + + /* + // Slate's hue in the range [0,360] - change this variable to alter the tone + // of the theme, e.g. to make it more redish or greenish. This is a slate- + // specific variable, but the same approach may be adapted to custom themes. + */ + --md-hue: 0; + --nexus-background-primary: #101010; + --nexus-background-secondary: #181818; + --nexus-background-tertiary: #222222; + --nexus-background-content-primary: #1C1C1C; + --nexus-background-content-secondary: #2B2D2F; + + --nexus-font-primary: #FFFFFF; /* #FFFFFF */ + --nexus-font-secondary: #AAAAAA; /* #AAAAAA */ + --nexus-font-tertiary: #5A5A5A; /* #5A5A5A */ + + --nexus-font-primary-rgb: 255, 255, 255; /* #FFFFFF */ + --nexus-font-secondary-rgb: 170, 170, 170; /* #AAAAAA */ + --nexus-font-tertiary-rgb: 90, 90, 90; /* #5A5A5A */ + + /* Default color shades */ + --md-default-fg-color: var(--nexus-font-primary); + --md-default-fg-color--light: var(--nexus-font-secondary); + --md-default-fg-color--lighter: var(--nexus-font-tertiary); + --md-default-fg-color--lightest: rgba(var(--nexus-font-primary-rgb), 0.04); + --md-default-bg-color: var(--nexus-background-secondary); + --md-default-bg-color--light: var(--nexus-background-content-primary); + --md-default-bg-color--lighter: var(--nexus-background-tertiary); + --md-default-bg-color--lightest: var(--nexus-background-content-secondary); + + /* Code color shades */ + --md-code-fg-color: hsla(var(--md-hue), 18%, 86%, 1); + --md-code-bg-color: var(--nexus-background-content-secondary); + + /* Code highlighting color shades */ + --md-code-hl-color: #4287ff26; + --md-code-hl-number-color: hsla(219, 74%, 63%, 1); + --md-code-hl-special-color: hsla(340, 83%, 66%, 1); + --md-code-hl-function-color: hsla(219, 57%, 65%, 1); + --md-code-hl-constant-color: hsla(250, 62%, 70%, 1); + --md-code-hl-keyword-color: hsla(var(--md-hue), 66%, 64%, 1); + --md-code-hl-string-color: hsla(150, 58%, 44%, 1); + --md-code-hl-name-color: var(--md-code-fg-color); + --md-code-hl-operator-color: var(--md-default-fg-color--light); + --md-code-hl-punctuation-color: var(--md-default-fg-color--light); + --md-code-hl-comment-color: var(--md-default-fg-color--light); + --md-code-hl-generic-color: var(--md-default-fg-color--light); + --md-code-hl-variable-color: var(--md-default-fg-color--light); + + /* Typeset color shades */ + --md-typeset-color: var(--md-default-fg-color); + + /* Typeset `a` color shades */ + --md-typeset-a-color: var(--md-primary-fg-color--lightest); + + /* Typeset `mark` color shades */ + --md-typeset-mark-color: #4287ff4d; + + /* Typeset `kbd` color shades */ + --md-typeset-kbd-color: hsla(var(--md-hue), 15%, 94%, 0.12); + --md-typeset-kbd-accent-color: hsla(var(--md-hue), 15%, 94%, 0.2); + --md-typeset-kbd-border-color: hsla(var(--md-hue), 15%, 14%, 1); + + /* Typeset `table` color shades */ + --md-typeset-table-color: hsla(var(--md-hue), 75%, 95%, 0.12); + --md-typeset-table-color--light: hsla(var(--md-hue), 75%, 95%, 0.035); + + /* Admonition color shades */ + --md-admonition-fg-color: var(--md-default-fg-color); + --md-admonition-bg-color: var(--md-default-bg-color); + + /* Footer color shades */ + --md-footer-bg-color: var(--nexus-background-primary); + --md-footer-bg-color--dark: var(--nexus-background-primary); + + /* Shadow depth 1 */ + --md-shadow-z1: + 0 #{px2rem(4px)} #{px2rem(10px)} hsla(0, 0%, 0%, 0.2), + 0 0 #{px2rem(1px)} hsla(0, 0%, 0%, 0.1); + + /* Shadow depth 2 */ + --md-shadow-z2: + 0 #{px2rem(4px)} #{px2rem(10px)} hsla(0, 0%, 0%, 0.3), + 0 0 #{px2rem(1px)} hsla(0, 0%, 0%, 0.25); + + /* Shadow depth 3 */ + --md-shadow-z3: + 0 #{px2rem(4px)} #{px2rem(10px)} hsla(0, 0%, 0%, 0.4), + 0 0 #{px2rem(1px)} hsla(0, 0%, 0%, 0.35); + + /* Hide images for light mode */ + img[src$="#only-light"], + img[src$="#gh-light-mode-only"] { + display: none; + } + + /* Show images for dark mode */ + img[src$="#only-dark"], + img[src$="#gh-dark-mode-only"] { + display: initial; + } +} + +[data-md-color-scheme="reloaded-slate"] .md-typeset a:hover { + color: var(--md-primary-fg-color--light); +} + +[data-md-color-scheme="reloaded-slate"] .md-nav--primary .md-nav__item--active>.md-nav__link:hover { + color: var(--md-primary-fg-color--light); +} + +[data-md-color-scheme="reloaded-slate"] .md-nav__link:hover { + color: var(--md-primary-fg-color--light); +} + + +[data-md-color-scheme="reloaded3-slate"] { + /* + Default Variables + */ + + /* For reuse later */ + --md-primary-fg-color-rgb: 63, 153, 217; + + /* Primary color shades */ + --md-primary-fg-color: #fa7774; + --md-primary-fg-color--light: #fc918b; + --md-primary-fg-color--dark: #e96060; + --md-primary-fg-color--darker: #d74f52; + --md-primary-fg-color--darkest: #c53e44; + + --md-primary-bg-color: #FFFFFF; + --md-primary-bg-color--light: #FFFFFFB2; + + /* Accent color shades */ + --md-accent-fg-color: #e96060; + --md-accent-fg-color--transparent: #e9606030; + + --md-accent-bg-color: #2A2C2B; + --md-accent-bg-color--light: #2A2C2B; + + /* + // Slate's hue in the range [0,360] - change this variable to alter the tone + // of the theme, e.g. to make it more redish or greenish. This is a slate- + // specific variable, but the same approach may be adapted to custom themes. + */ + --md-hue: 1; + --nexus-background-primary: #101010; + --nexus-background-secondary: #181818; + --nexus-background-tertiary: #222222; + --nexus-background-content-primary: #1C1C1C; + --nexus-background-content-secondary: #2B2D2F; + + --nexus-font-primary: #FFFFFF; /* #FFFFFF */ + --nexus-font-secondary: #AAAAAA; /* #AAAAAA */ + --nexus-font-tertiary: #5A5A5A; /* #5A5A5A */ + + --nexus-font-primary-rgb: 255, 255, 255; /* #FFFFFF */ + --nexus-font-secondary-rgb: 170, 170, 170; /* #AAAAAA */ + --nexus-font-tertiary-rgb: 90, 90, 90; /* #5A5A5A */ + + /* Default color shades */ + --md-default-fg-color: var(--nexus-font-primary); + --md-default-fg-color--light: var(--nexus-font-secondary); + --md-default-fg-color--lighter: var(--nexus-font-tertiary); + --md-default-fg-color--lightest: rgba(var(--nexus-font-primary-rgb), 0.12); + --md-default-bg-color: var(--nexus-background-secondary); + --md-default-bg-color--light: var(--nexus-background-content-primary); + --md-default-bg-color--lighter: var(--nexus-background-tertiary); + --md-default-bg-color--lightest: var(--nexus-background-content-secondary); + + /* Code color shades */ + --md-code-fg-color: hsla(var(--md-hue), 18%, 86%, 1); + --md-code-bg-color: var(--nexus-background-content-secondary); + + /* Code highlighting color shades */ + --md-code-hl-color: #4287ff26; + --md-code-hl-number-color: hsla(219, 74%, 63%, 1); + --md-code-hl-special-color: hsla(340, 83%, 66%, 1); + --md-code-hl-function-color: hsla(219, 57%, 65%, 1); + --md-code-hl-constant-color: hsla(250, 62%, 70%, 1); + --md-code-hl-keyword-color: hsla(var(--md-hue), 66%, 64%, 1); + --md-code-hl-string-color: hsla(150, 58%, 44%, 1); + --md-code-hl-name-color: var(--md-code-fg-color); + --md-code-hl-operator-color: var(--md-default-fg-color--light); + --md-code-hl-punctuation-color: var(--md-default-fg-color--light); + --md-code-hl-comment-color: var(--md-default-fg-color--light); + --md-code-hl-generic-color: var(--md-default-fg-color--light); + --md-code-hl-variable-color: var(--md-default-fg-color--light); + + /* Typeset color shades */ + --md-typeset-color: var(--md-default-fg-color); + + /* Typeset `a` color shades */ + --md-typeset-a-color: var(--md-primary-fg-color); + + /* Typeset `mark` color shades */ + --md-typeset-mark-color: #4287ff4d; + + /* Typeset `kbd` color shades */ + --md-typeset-kbd-color: hsla(var(--md-hue), 15%, 94%, 0.12); + --md-typeset-kbd-accent-color: hsla(var(--md-hue), 15%, 94%, 0.2); + --md-typeset-kbd-border-color: hsla(var(--md-hue), 15%, 14%, 1); + + /* Typeset `table` color shades */ + --md-typeset-table-color: hsla(var(--md-hue), 75%, 95%, 0.12); + --md-typeset-table-color--light: hsla(var(--md-hue), 75%, 95%, 0.035); + + /* Admonition color shades */ + --md-admonition-fg-color: var(--md-default-fg-color); + --md-admonition-bg-color: var(--md-default-bg-color); + + /* Footer color shades */ + --md-footer-bg-color: var(--nexus-background-primary); + --md-footer-bg-color--dark: var(--nexus-background-primary); + + /* Shadow depth 1 */ + --md-shadow-z1: + 0 #{px2rem(4px)} #{px2rem(10px)} hsla(0, 0%, 0%, 0.2), + 0 0 #{px2rem(1px)} hsla(0, 0%, 0%, 0.1); + + /* Shadow depth 2 */ + --md-shadow-z2: + 0 #{px2rem(4px)} #{px2rem(10px)} hsla(0, 0%, 0%, 0.3), + 0 0 #{px2rem(1px)} hsla(0, 0%, 0%, 0.25); + + /* Shadow depth 3 */ + --md-shadow-z3: + 0 #{px2rem(4px)} #{px2rem(10px)} hsla(0, 0%, 0%, 0.4), + 0 0 #{px2rem(1px)} hsla(0, 0%, 0%, 0.35); + + /* Hide images for light mode */ + img[src$="#only-light"], + img[src$="#gh-light-mode-only"] { + display: none; + } + + /* Show images for dark mode */ + img[src$="#only-dark"], + img[src$="#gh-dark-mode-only"] { + display: initial; + } +} + +[data-md-color-scheme="reloaded3-slate"] .md-header { + background-color: var(--md-primary-fg-color--darker); +} + +@media screen and (max-width: 76.1875em) { + /* Title in Drawer */ + [data-md-color-scheme="reloaded3-slate"] .md-nav--primary .md-nav__title[for=__drawer] { + background-color: var(--md-primary-fg-color--darker); + color: var(--md-primary-bg-color); + font-weight: 700; + } +} + +[data-md-color-scheme="reloaded3-slate"] .md-nav__source { + background-color: var(--md-primary-fg-color--darkest); + color: var(--md-primary-bg-color); +} + +.md-nav__title { + color: var(--md-default-fg-color); +} + +.md-nav__link { + color: var(--md-default-fg-color--light); +} + +/* Custom 'nexus' admonition */ +.md-typeset .admonition.nexus, +.md-typeset details.nexus { + border-color: var(--md-primary-fg-color); +} +.md-typeset .nexus > .admonition-title, +.md-typeset .nexus > summary { + background-color: rgba(var(--md-primary-fg-color-rgb), 0.1); +} +.md-typeset .nexus > .admonition-title::before, +.md-typeset .nexus > summary::before { + background-color: unset; + -webkit-mask-image: unset; + background-image: var(--md-admonition-icon--nexus); + background-size: contain; + background-repeat: no-repeat; + background-position: center; +} + +/* Custom 'nexus heart' admonition */ +.md-typeset .admonition.nexusheart, +.md-typeset details.nexusheart { + border-color: var(--md-primary-fg-color); +} +.md-typeset .nexusheart > .admonition-title, +.md-typeset .nexusheart > summary { + background-color: rgba(var(--md-primary-fg-color-rgb), 0.1); +} +.md-typeset .nexusheart > .admonition-title::before, +.md-typeset .nexusheart > summary::before { + background-color: unset; + -webkit-mask-image: unset; + background-image: var(--md-admonition-icon--nexusheart); + background-size: contain; + background-repeat: no-repeat; + background-position: center; +} + +/* Custom 'reloaded' admonition */ + +.md-typeset .admonition.reloaded, +.md-typeset details.reloaded { + border-color: var(--md-primary-fg-color); +} +.md-typeset .reloaded > .admonition-title, +.md-typeset .reloaded > summary { + background-color: rgba(var(--md-primary-fg-color-rgb), 0.1); +} +.md-typeset .reloaded > .admonition-title::before, +.md-typeset .reloaded > summary::before { + background-color: unset; + -webkit-mask-image: unset; + background-image: var(--md-admonition-icon--reloaded); + background-size: contain; + background-repeat: no-repeat; + background-position: center; +} + +/* Custom 'nexus heart' admonition */ +.md-typeset .admonition.reloadedheart, +.md-typeset details.reloadedheart { + border-color: var(--md-primary-fg-color); +} +.md-typeset .reloadedheart > .admonition-title, +.md-typeset .reloadedheart > summary { + background-color: rgba(var(--md-primary-fg-color-rgb), 0.1); +} +.md-typeset .reloadedheart > .admonition-title::before, +.md-typeset .reloadedheart > summary::before { + background-color: unset; + -webkit-mask-image: unset; + background-image: var(--md-admonition-icon--reloadedheart); + background-size: contain; + background-repeat: no-repeat; + background-position: center; +} + +/* Headers */ +[data-md-color-scheme="nexus-slate"] .md-typeset h1 { + color: var(--md-default-fg-color); + font-family: "Montserrat",Roboto; + font-weight: 600; +} + +[data-md-color-scheme="nexus-slate"] .md-typeset h2 { + color: var(--md-default-fg-color); + font-family: "Montserrat",Roboto; + font-weight: 600; +} + +[data-md-color-scheme="nexus-slate"] .md-typeset h3 { + color: var(--md-default-fg-color); + font-family: "Montserrat",Roboto; + font-weight: 600; +} + +[data-md-color-scheme="nexus-slate"] .md-typeset h4 { + color: var(--md-default-fg-color); + font-family: "Montserrat",Roboto; + font-weight: 600; +} + +[data-md-color-scheme="nexus-slate"] .md-typeset h5 { + color: var(--md-default-fg-color); + font-family: "Montserrat",Roboto; + font-weight: 600; +} + +[data-md-color-scheme="reloaded-slate"] .md-typeset h1 { + color: var(--md-default-fg-color); +} + +[data-md-color-scheme="reloaded3-slate"] .md-typeset h1 { + color: var(--md-default-fg-color); + font-family: "Montserrat",Roboto; + font-weight: 600; +} + +[data-md-color-scheme="reloaded3-slate"] .md-typeset h2 { + color: var(--md-default-fg-color); + font-family: "Montserrat",Roboto; + font-weight: 600; +} + +[data-md-color-scheme="reloaded3-slate"] .md-typeset h3 { + color: var(--md-default-fg-color); + font-family: "Montserrat",Roboto; + font-weight: 600; +} + +[data-md-color-scheme="reloaded3-slate"] .md-typeset h4 { + color: var(--md-default-fg-color); + font-family: "Montserrat",Roboto; + font-weight: 600; +} + +[data-md-color-scheme="reloaded3-slate"] .md-typeset h5 { + color: var(--md-default-fg-color); + font-family: "Montserrat",Roboto; + font-weight: 600; +} \ No newline at end of file diff --git a/docs/start_docs.py b/docs/start_docs.py new file mode 100755 index 00000000..49c96121 --- /dev/null +++ b/docs/start_docs.py @@ -0,0 +1,95 @@ +#!/usr/bin/env python3 +""" +Script to set up virtual environment and start MkDocs live server for documentation. + +Usage: + python start_docs.py # Start docs server + python start_docs.py --docs-dir . # Same as above (explicit) +""" + +import subprocess +import sys +import os +from pathlib import Path + + +def run_command(cmd, cwd=None): + """Run a command and handle errors.""" + print(f"Running: {' '.join(cmd)}") + try: + result = subprocess.run(cmd, cwd=cwd, check=True, capture_output=False) + return result + except subprocess.CalledProcessError as e: + print(f"Error running command: {e}") + sys.exit(1) + + +def main(): + """Main function to set up docs environment.""" + import argparse + + parser = argparse.ArgumentParser(description="Set up documentation environment") + parser.add_argument( + "--docs-dir", + type=str, + help="Documentation directory containing mkdocs.yml (default: script directory)", + ) + parser.add_argument( + "--project-name", + type=str, + default="llm-coding-tools", + help="Project name for messages", + ) + args = parser.parse_args() + + # Use docs directory if provided, otherwise use script directory + if args.docs_dir: + script_dir = Path(args.docs_dir) + else: + script_dir = Path(__file__).parent + + venv_dir = script_dir / "venv" + + print(f"Setting up {args.project_name} documentation...") + + # Create virtual environment if it doesn't exist + if not venv_dir.exists(): + print("Creating virtual environment...") + run_command([sys.executable, "-m", "venv", "venv"], cwd=script_dir) + else: + print("Virtual environment already exists.") + + # Determine the python executable in the venv + if os.name == "nt": # Windows + python_exe = venv_dir / "Scripts" / "python.exe" + pip_exe = venv_dir / "Scripts" / "pip.exe" + else: # Unix-like + python_exe = venv_dir / "bin" / "python" + pip_exe = venv_dir / "bin" / "pip" + + # Install required packages + print("Installing required packages...") + + # Look for requirements.txt in the docs directory + requirements_file = script_dir / "requirements.txt" + if requirements_file.exists(): + print(f"Installing from {requirements_file}...") + run_command( + [str(pip_exe), "install", "-r", str(requirements_file)], cwd=script_dir + ) + else: + print(f"Warning: No requirements.txt found at {requirements_file}") + + # Start MkDocs live server + print("Starting MkDocs live server...") + print( + "Documentation will be available at http://127.0.0.1:8000 (paste into browser address bar)" + ) + print("Press Ctrl+C to stop the server") + run_command( + [str(python_exe), "-m", "mkdocs", "serve", "--livereload"], cwd=script_dir + ) + + +if __name__ == "__main__": + main() diff --git a/src/Cargo.lock b/src/Cargo.lock index b31ee981..2e174bad 100644 --- a/src/Cargo.lock +++ b/src/Cargo.lock @@ -1917,7 +1917,7 @@ dependencies = [ "cesu8", "cfg-if", "combine", - "jni-sys", + "jni-sys 0.3.1", "log", "thiserror 1.0.69", "walkdir", @@ -1926,9 +1926,31 @@ dependencies = [ [[package]] name = "jni-sys" -version = "0.3.0" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "41a652e1f9b6e0275df1f15b32661cf0d4b78d4d87ddec5e0c3c20f097433258" +dependencies = [ + "jni-sys 0.4.1", +] + +[[package]] +name = "jni-sys" +version = "0.4.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8eaf4bc02d17cbdd7ff4c7438cafcdf7fb9a4613313ad11b4f8fefe7d3fa0130" +checksum = "c6377a88cb3910bee9b0fa88d4f42e1d2da8e79915598f65fb0c7ee14c878af2" +dependencies = [ + "jni-sys-macros", +] + +[[package]] +name = "jni-sys-macros" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "38c0b942f458fe50cdac086d2f946512305e5631e720728f2a61aabcd47a6264" +dependencies = [ + "quote", + "syn", +] [[package]] name = "jobserver" @@ -2956,7 +2978,7 @@ dependencies = [ "security-framework", "security-framework-sys", "webpki-root-certs", - "windows-sys 0.61.2", + "windows-sys 0.52.0", ] [[package]] @@ -4189,9 +4211,9 @@ dependencies = [ [[package]] name = "webpki-root-certs" -version = "1.0.5" +version = "1.0.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "36a29fc0408b113f68cf32637857ab740edfafdf460c326cd2afaa2d84cc05dc" +checksum = "804f18a4ac2676ffb4e8b5b5fa9ae38af06df08162314f96a68d2a363e21a8ca" dependencies = [ "rustls-pki-types", ] diff --git a/src/Cargo.toml b/src/Cargo.toml index 479e530f..dde3f896 100644 --- a/src/Cargo.toml +++ b/src/Cargo.toml @@ -9,6 +9,85 @@ members = [ "llm-coding-tools-bubblewrap", ] +[workspace.dependencies] +# Serialization +serde = { version = "1.0", features = ["derive"] } +serde_json = "1.0" +serde_yaml = "0.9" +bitcode = "0.6.9" +bitflags = "2.11.0" + +# Error handling +thiserror = "2.0" + +# Async/Runtime +tokio = { version = "1.51", features = ["fs", "io-util", "process", "time"] } +maybe-async = "0.2" +async-trait = "0.1" +futures = "0.3" + +# HTTP/Network +reqwest = { version = "0.13", default-features = false, features = ["rustls", "rustls-native-certs"] } +html-to-markdown-rs = "3.1" + +# Filesystem/Path +shellexpand = "3.1.2" +soft-canonicalize = "0.5.5" +dirs = "6" +tempfile = "3.27" +ignore = "0.4.25" + +# Data structures +hashbrown = "0.17" +indexmap = { version = "2", features = ["serde"] } +tinyvec = { version = "1.11", features = ["alloc"] } +lite-strtab = "0.2" +ahash = { version = "0.8", features = ["serde"] } +parking_lot = "0.12" + +# Bit operations +bitfields = "1.0.3" + +# Grep/Glob tools +globset = "0.4.18" +grep-regex = "0.1.14" +grep-searcher = "0.1.16" +memchr = "2.8.0" + +# Process management +process-wrap = { version = "9.1", default-features = false } + +# String formatting +const_format = "0.2.35" +crlf-to-lf-inplace = "0.2" + +# Schema/Validation +schemars = "1.2" + +# Compression/Encoding +zstd = "0.13.3" +endian-writer = "2.2.0" +endian-writer-derive = "0.1.0" + +# serdes-ai ecosystem +serdes-ai = { version = "0.2.6", default-features = false } +serdes-ai-models = { version = "0.2.6", default-features = false } +serdes-ai-streaming = "0.2" + +# Internal crates +llm-coding-tools-core = { version = "0.2.0", path = "llm-coding-tools-core" } +llm-coding-tools-bubblewrap = { version = "0.1.0", path = "llm-coding-tools-bubblewrap" } +llm-coding-tools-agents = { version = "0.1.0", path = "llm-coding-tools-agents" } +llm-coding-tools-models-dev = { version = "0.1.0", path = "llm-coding-tools-models-dev" } + +# Dev dependencies +criterion = "0.8" +rstest = "0.26" +serial_test = "3" +wiremock = "0.6" +indoc = "2" +temp-env = "0.3.6" + # Profile Build [profile.profile] inherits = "release" diff --git a/src/llm-coding-tools-agents/ARCHITECTURE.md b/src/llm-coding-tools-agents/ARCHITECTURE.md index d090e58c..dcc8da56 100644 --- a/src/llm-coding-tools-agents/ARCHITECTURE.md +++ b/src/llm-coding-tools-agents/ARCHITECTURE.md @@ -43,7 +43,7 @@ loader.add_directory(&mut catalog, Path::new("agents"))?; // 2. Build the runtime let runtime = AgentRuntimeBuilder::new() .catalog(catalog) - .defaults(AgentDefaults::with_model("openai/gpt-4o")) + .defaults(AgentDefaults::with_model("openai/gpt-5.4")) .build(); // 3. Use the runtime (e.g., look up agents by name) @@ -60,7 +60,7 @@ Agent definitions live in markdown files with YAML frontmatter: name: code-reviewer mode: subagent description: Reviews code and flags high-risk issues -model: openrouter/openai/gpt-4o +model: ollama-cloud/minimax-m2.7 permission: read: allow bash: deny diff --git a/src/llm-coding-tools-agents/Cargo.toml b/src/llm-coding-tools-agents/Cargo.toml index c1f23f33..77d39df0 100644 --- a/src/llm-coding-tools-agents/Cargo.toml +++ b/src/llm-coding-tools-agents/Cargo.toml @@ -2,7 +2,7 @@ name = "llm-coding-tools-agents" version = "0.1.0" edition = "2021" -description = "Agent configuration loading from OpenCode-style markdown files with YAML frontmatter" +description = "Agent configuration loading from markdown files with YAML frontmatter (similar to OpenCode)" repository = "https://github.com/Sewer56/llm-coding-tools" license = "Apache-2.0" include = ["src/**/*", "README.md"] @@ -10,37 +10,36 @@ readme = "README.md" [dependencies] # YAML parsing for frontmatter -serde = { version = "1.0", features = ["derive"] } -serde_yaml = "0.9" -serde_json = "1.0" +serde = { workspace = true } +serde_yaml = { workspace = true } +serde_json = { workspace = true } # Preserve insertion order for permission maps -indexmap = { version = "2", features = ["serde"] } +indexmap = { workspace = true } # Error handling -thiserror = "2.0" +thiserror = { workspace = true } # Fast CRLF to LF conversion -crlf-to-lf-inplace = "0.2" - +crlf-to-lf-inplace = { workspace = true } # Directory scanning with gitignore support -ignore = "0.4.25" +ignore = { workspace = true } # High-performance hashing (sync version with core crate) -ahash = { version = "0.8", features = ["serde"] } +ahash = { workspace = true } # Core library for permissions and tool types -llm-coding-tools-core = { path = "../llm-coding-tools-core", version = "0.2.0" } +llm-coding-tools-core = { workspace = true } # Canonicalizes paths, resolving symlinks without requiring the full path to exist -soft-canonicalize = "0.5" +soft-canonicalize = { workspace = true } [dev-dependencies] -tempfile = "3.27" -criterion = "0.8" -indoc = "2" -rstest = "0.26" +tempfile = { workspace = true } +criterion = { workspace = true } +indoc = { workspace = true } +rstest = { workspace = true } [[bench]] name = "parser" diff --git a/src/llm-coding-tools-agents/README.md b/src/llm-coding-tools-agents/README.md index d3b0da4e..0c4b804b 100644 --- a/src/llm-coding-tools-agents/README.md +++ b/src/llm-coding-tools-agents/README.md @@ -2,10 +2,12 @@ [](https://crates.io/crates/llm-coding-tools-agents) [](https://docs.rs/llm-coding-tools-agents) -Load agent markdown files compatible with the [OpenCode agent schema]: +Load agent markdown files into a typed catalog with runtime defaults and permission evaluation. -- **Mostly drop-in** - agent files work out of the box -- **One exception** - [default-deny permissions](#️-default-deny-permissions) (OpenCode uses default-allow) +[Documentation] · [API Reference] + +The agent file format mirrors [OpenCode]'s schema - similar enough that many +files are drop-in compatible, but [not identical](#differences-from-opencode). ## Loading agents @@ -30,7 +32,7 @@ for agent in catalog.iter() { Agent files are markdown with YAML frontmatter. -The format is based on OpenCode's agent schema; so fields like [`mode`], +The format is similar to [OpenCode]'s agent schema; so fields like [`mode`], [`model`] and [`permissions`] should be familiar. ### Complete example @@ -56,15 +58,6 @@ You are a code search assistant. Use grep to find relevant files and code patter then read the matching files to extract and summarize the content. ``` -### ⚠️ Default-Deny Permissions - -Unlike OpenCode, this library **denies tools unless explicitly allowed**. - -This is because `llm-coding-tools` was designed towards automation/servers, -where determinism is more valuable. - -For default-allow behaviour, [open a PR]. - ### Frontmatter fields **Required:** @@ -110,12 +103,52 @@ permission: task: allow # Required to delegate to subagents ``` -**Glob patterns in permissions:** Permission values use globs (`*` = one component, `**` = any depth). -Bare `allow` equals `**`. Patterns are workspace-relative. +Several tools support **pattern-based rules** instead of a simple `allow`/`deny`. +Evaluation uses **last-match-wins**: the final matching rule takes effect. + +| Tool(s) | Pattern matches against | Supports patterns | +| ----------------------------- | -------------------------------- | -------------------- | +| read, write, edit, glob, grep | File path (relative or absolute) | yes | +| bash | Command string | yes | +| task | Target agent name | yes | +| webfetch, todoread, todowrite | - | no (allow/deny only) | -**Note:** `task` is special - when omitted, it allows delegation to all callable -subagents for OpenCode compatibility. To disable delegation, explicitly set -`task: deny`. +**File tools** - patterns match against the path as given. Absolute paths +start with `/` or a drive letter like `C:/`. Relative paths have no such +prefix. `**` matches any file at any depth, relative to the workspace root (catch-all). +`*` matches files in the workspace root only. `/**` matches any file on the +system, including other drives on Windows. + +```yaml +permission: + read: + "src/**": allow + "secrets/**": deny + "**": allow +``` + +**Bash** - patterns match against the command string: + +```yaml +permission: + bash: + "rm *": deny + "curl *": deny + "*": allow +``` + +**Task delegation** - patterns match against the target agent name: + +```yaml +permission: + task: + "reader-*": allow + "*": deny +``` + +**Note:** `task` is special - when omitted entirely (not just set to a pattern), +it allows delegation to all callable subagents for [OpenCode] compatibility. +To disable delegation, explicitly set `task: deny`. #### Tool settings @@ -144,20 +177,20 @@ tool_settings: **Setting reference:** -| Tool | Setting | Type | Default | Min | Description | -| -------- | ----------------------- | ----- | -------- | ---- | ------------------------------------------------------- | -| read | `line_numbers` | bool | `true` | — | Show line numbers in output | -| read | `limit` | usize | `2000` | 1 | Max lines per file read | -| read | `max_line_length` | usize | `2000` | 4 | Max characters per line (truncates longer lines) | -| grep | `line_numbers` | bool | `true` | — | Show line numbers in output | -| grep | `limit` | usize | `100` | 1 | Max matches returned | -| grep | `max_line_length` | usize | `2000` | 4 | Max characters per match line | -| glob | `limit` | usize | `1000` | 1 | Max files returned | -| bash | `timeout_ms` | usize | `120000` | 1000 | Default command timeout in milliseconds | -| bash | `max_timeout_ms` | usize | `600000` | * | Maximum timeout LLM can request (must be >= timeout_ms) | -| webfetch | `timeout_ms` | usize | `30000` | 1000 | Fetch timeout in milliseconds | -| webfetch | `max_timeout_ms` | usize | `600000` | * | Maximum timeout LLM can request (must be >= timeout_ms) | -| webfetch | `max_response_size` | usize | `5242880`| 1 | Max response body size in bytes | +| Tool | Setting | Type | Default | Min | Description | +| -------- | ------------------- | ----- | --------- | ---- | ------------------------------------------------------- | +| read | `line_numbers` | bool | `true` | - | Show line numbers in output | +| read | `limit` | usize | `2000` | 1 | Max lines per file read | +| read | `max_line_length` | usize | `2000` | 4 | Max characters per line (truncates longer lines) | +| grep | `line_numbers` | bool | `true` | - | Show line numbers in output | +| grep | `limit` | usize | `100` | 1 | Max matches returned | +| grep | `max_line_length` | usize | `2000` | 4 | Max characters per match line | +| glob | `limit` | usize | `1000` | 1 | Max files returned | +| bash | `timeout_ms` | usize | `120000` | 1000 | Default command timeout in milliseconds | +| bash | `max_timeout_ms` | usize | `600000` | * | Maximum timeout LLM can request (must be >= timeout_ms) | +| webfetch | `timeout_ms` | usize | `30000` | 1000 | Fetch timeout in milliseconds | +| webfetch | `max_timeout_ms` | usize | `600000` | * | Maximum timeout LLM can request (must be >= timeout_ms) | +| webfetch | `max_response_size` | usize | `5242880` | 1 | Max response body size in bytes | **Output format:** @@ -230,7 +263,7 @@ loader.add_directory(&mut catalog, "/home/user/.opencode")?; let runtime = AgentRuntimeBuilder::new() .catalog(catalog) - .defaults(AgentDefaults::with_model("openai/gpt-4o-mini")) + .defaults(AgentDefaults::with_model("openai/gpt-5.4")) // .max_task_depth(5) // optional; defaults to 3 Task hops // .tools(my_custom_tools) // optional; defaults to read/write/edit/glob/grep/bash/webfetch/todoread/todowrite/task .build(); @@ -239,16 +272,37 @@ let runtime = AgentRuntimeBuilder::new() # Ok::<(), llm_coding_tools_agents::AgentLoadError>(()) ``` -## Compatibility notes +## Differences from OpenCode -This library does not provide interactive UX extensions (for example, TUI -approval flows). +The agent file format mirrors [OpenCode]'s. Many files are drop-in +compatible, but there are differences: -To avoid false expectations, settings that require interaction are rejected, -while settings with no runtime effect are accepted and ignored: +### Default-deny permissions + +This library **denies tools unless explicitly allowed**. OpenCode uses +default-allow. This is because `llm-coding-tools` targets +automation/servers, where determinism is more valuable. + +For default-allow behaviour, [open a PR]. + +### File path matching + +File tool patterns (`read`, `write`, `edit`, `glob`, `grep`) match against +the path as given, supporting both absolute (`/home/user/...`, `C:/...`) +and relative paths. OpenCode instead provides `external_directory` for +granting access outside the workspace. This library omits that in favour +of more granular pattern control. + +### Interactive settings + +This library does not provide interactive UX extensions (for example, TUI +approval flows). To avoid false expectations, settings that require +interaction are rejected, while settings with no runtime effect are +accepted and ignored: -- `permission.task: ask` - Rejected with a schema validation error (`allow`/`deny` - only), because `ask` is an interactive approval mode in OpenCode. +- `permission.task: ask` - Rejected with a schema validation error + (`allow`/`deny` only), because `ask` is an interactive approval mode in + [OpenCode]. - `hidden` - Accepted for compatibility, but ignored at runtime. For the internal architecture, see [ARCHITECTURE.md](https://github.com/Sewer56/llm-coding-tools/blob/main/src/llm-coding-tools-agents/ARCHITECTURE.md). @@ -259,3 +313,6 @@ For the internal architecture, see [ARCHITECTURE.md](https://github.com/Sewer56/ [models.dev]: https://models.dev [OpenCode agent schema]: https://opencode.ai/docs/agents/ [open a PR]: https://github.com/Sewer56/llm-coding-tools/pulls +[OpenCode]: https://opencode.ai/ +[Documentation]: https://sewer56.github.io/llm-coding-tools/agents +[API Reference]: https://docs.rs/llm-coding-tools-agents diff --git a/src/llm-coding-tools-agents/benches/fixtures/orchestrator-quality-gate-gpt5.md b/src/llm-coding-tools-agents/benches/fixtures/orchestrator-quality-gate-gpt5.md index 7a99341d..6d1f4294 100644 --- a/src/llm-coding-tools-agents/benches/fixtures/orchestrator-quality-gate-gpt5.md +++ b/src/llm-coding-tools-agents/benches/fixtures/orchestrator-quality-gate-gpt5.md @@ -24,7 +24,7 @@ think hard - `objectives_path` (optional): additional objectives file - Review context from orchestrator: - Task intent (one-line summary) - - Coder's concerns (areas of uncertainty — focus review here) + - Coder's concerns (areas of uncertainty - focus review here) - Related files reviewed by coder # Process @@ -48,7 +48,7 @@ think hard ## 4) Review code semantics -Analyze each changed file deeply. Reason through whether issues exist before concluding — don't just scan for patterns. Be comprehensive; flag anything suspicious. +Analyze each changed file deeply. Reason through whether issues exist before concluding - don't just scan for patterns. Be comprehensive; flag anything suspicious. Severity levels: - CRITICAL: immediate security vulnerabilities, data loss risks, system crashes @@ -64,7 +64,7 @@ Severity levels: ## 5) Review coder concerns If the coder flagged concerns, examine those areas with extra scrutiny. -These are areas where the implementer was uncertain — validate the approach or flag issues. +These are areas where the implementer was uncertain - validate the approach or flag issues. ## 6) Review objectives - Read all objectives from prompt file @@ -96,12 +96,12 @@ Provide this exact structure in the final message: # QUALITY GATE REPORT (GPT-5) ## Summary -[PASS|PARTIAL|FAIL] — X files, C critical, H high, M medium, L low +[PASS|PARTIAL|FAIL] - X files, C critical, H high, M medium, L low ## Objectives ### "Objective description" -[MET|NOT_MET|PARTIAL] — evidence: file:line or explanation +[MET|NOT_MET|PARTIAL] - evidence: file:line or explanation Issue: ... (if not met) Suggestion: ... (if not met) @@ -114,7 +114,7 @@ Description of issue ## Code Review Findings -### path/to/file:line — Title +### path/to/file:line - Title [SECURITY|CORRECTNESS|PERFORMANCE|ERROR_HANDLING|ARCHITECTURE|CROSS_FILE] [CRITICAL|HIGH|MEDIUM|LOW] Detailed explanation of the problem and why it matters **Impact:** What could go wrong @@ -124,7 +124,7 @@ Detailed explanation of the problem and why it matters ``` ## Test Issues -[basic|no] — [PASS|FAIL|FORBIDDEN_TESTS_FOUND] +[basic|no] - [PASS|FAIL|FORBIDDEN_TESTS_FOUND] ### path/to/test:line [DUPLICATE|NON_DETERMINISTIC|MISSING_COVERAGE|OVERENGINEERED] @@ -133,19 +133,19 @@ Description ## Verification Checks ### Formatting -[PASS|FAIL] — X issues +[PASS|FAIL] - X issues Details if failed ### Linting -[PASS|FAIL] — X errors, Y warnings +[PASS|FAIL] - X errors, Y warnings Details if failed ### Type/Build -[PASS|FAIL] — X errors +[PASS|FAIL] - X errors Details if failed ### Tests -[PASS|FAIL|SKIPPED|FORBIDDEN_TESTS_FOUND] — X passed, Y failed +[PASS|FAIL|SKIPPED|FORBIDDEN_TESTS_FOUND] - X passed, Y failed Details if failed ## Recommendation diff --git a/src/llm-coding-tools-agents/src/runtime/mod.rs b/src/llm-coding-tools-agents/src/runtime/mod.rs index 9f18208e..a0e990a5 100644 --- a/src/llm-coding-tools-agents/src/runtime/mod.rs +++ b/src/llm-coding-tools-agents/src/runtime/mod.rs @@ -33,7 +33,7 @@ //! # fn main() -> Result<(), Box