From fa0653c399cdec5635b096ac638a1cecf8329cd2 Mon Sep 17 00:00:00 2001 From: Steven Enamakel Date: Sat, 9 May 2026 06:58:55 +0000 Subject: [PATCH] GITBOOK-46: No subject --- gitbooks/SUMMARY.md | 5 +- gitbooks/developing/README.md | 4 +- gitbooks/developing/coding-harness.md | 177 ------------------ .../{developing => features}/cloud-deploy.md | 0 4 files changed, 4 insertions(+), 182 deletions(-) delete mode 100644 gitbooks/developing/coding-harness.md rename gitbooks/{developing => features}/cloud-deploy.md (100%) diff --git a/gitbooks/SUMMARY.md b/gitbooks/SUMMARY.md index c3fbbbfa2..e616ebe3b 100644 --- a/gitbooks/SUMMARY.md +++ b/gitbooks/SUMMARY.md @@ -29,6 +29,7 @@ * [Subconscious Loop](features/subconscious.md) * [Privacy & Security](features/privacy-and-security.md) * [Platform & Availability](features/platform.md) +* [Cloud Deploy](features/cloud-deploy.md) ## Developing @@ -37,14 +38,12 @@ * [Testing Strategy](developing/testing-strategy.md) * [E2E Testing](developing/e2e-testing.md) * [Release Policy](developing/release-policy.md) -* [Cloud Deploy](developing/cloud-deploy.md) * [Chromium Embedded Framework](developing/cef.md) -* [Coding Harness](developing/coding-harness.md) * [Agent Observability](developing/agent-observability.md) * [Architecture](developing/architecture/README.md) + * [Agent Harness](developing/architecture/agent-harness.md) * [Frontend (app/src/)](developing/architecture/frontend.md) * [Tauri Shell (app/src-tauri/)](developing/architecture/tauri-shell.md) - * [Agent Harness](developing/architecture/agent-harness.md) ## Legal diff --git a/gitbooks/developing/README.md b/gitbooks/developing/README.md index a7e288683..6c90a05cc 100644 --- a/gitbooks/developing/README.md +++ b/gitbooks/developing/README.md @@ -49,13 +49,13 @@ PRs must clear the **≥ 80% coverage on changed lines** gate. Add tests for new ## Shipping * [**Release Policy**](release-policy.md). Version policy, release cadence, OAuth + installer rules. -* [**Cloud Deploy**](cloud-deploy.md). Backend/cloud-side deployment when a change crosses the desktop boundary. +* [**Cloud Deploy**](../features/cloud-deploy.md). Backend/cloud-side deployment when a change crosses the desktop boundary. *** ## Going deeper -* [**Coding Harness**](coding-harness.md). The agent's code-focused tool surface and how to extend it. +* [**Coding Harness**](/broken/pages/RRYmjibvEbtqRSPntgPX). The agent's code-focused tool surface and how to extend it. * [**Chromium Embedded Framework**](cef.md). How embedded provider webviews work, why they don't run injected JS, and what the per-provider scanners do instead. For features still being built, the [Subconscious Loop](../features/subconscious.md) page covers the background task evaluation system end-to-end. diff --git a/gitbooks/developing/coding-harness.md b/gitbooks/developing/coding-harness.md deleted file mode 100644 index 47341667a..000000000 --- a/gitbooks/developing/coding-harness.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -description: The agent's code-focused tool surface — what's exposed, where to add more. -icon: code ---- - -# Coding-harness tool surface - -OpenHuman exposes a coherent baseline of code-focused tools to its -agents. This page is the canonical map: which tool the model should -reach for, what permissions it needs, and where the implementation -lives. - -It is intentionally a flat catalog, not a guide on how the agent -loop dispatches tools. For that, see -[`gitbooks/developing/architecture.md`](architecture.md) and -[`src/openhuman/tools/`](../../src/openhuman/tools/). - -Tracking issue: [#1205](https://github.com/tinyhumansai/openhuman/issues/1205). - -## Surface at a glance - -| Category | Tool | Permission | Source | -| --- | --- | --- | --- | -| **Navigation** | `file_read` | ReadOnly | `tools/impl/filesystem/file_read.rs` | -| | `grep` | ReadOnly | `tools/impl/filesystem/grep.rs` | -| | `glob` | ReadOnly | `tools/impl/filesystem/glob_search.rs` | -| | `list` | ReadOnly | `tools/impl/filesystem/list_files.rs` | -| **Editing** | `file_write` | Write | `tools/impl/filesystem/file_write.rs` | -| | `edit` | Write | `tools/impl/filesystem/edit_file.rs` | -| | `apply_patch` | Write | `tools/impl/filesystem/apply_patch.rs` | -| **Execution** | `shell` | Execute | `tools/impl/system/shell.rs` | -| **Interaction** | `ask_clarification` (`question`) | None | `tools/impl/agent/ask_clarification.rs` | -| | `spawn_subagent` (`task`) | varies | `tools/impl/agent/spawn_subagent.rs` | -| | `todowrite` | None | `tools/impl/agent/todo_write.rs` | -| | `plan_exit` | None | `tools/impl/agent/plan_exit.rs` | -| **Web research** | `web_search` (`websearch`) | ReadOnly | `tools/impl/network/web_search.rs` | -| | `web_fetch` (`webfetch`) | ReadOnly | `tools/impl/network/web_fetch.rs` | -| | `http_request`, `curl` (richer HTTP) | ReadOnly | `tools/impl/network/` | -| **Code intel** | `lsp` *(capability-gated)* | ReadOnly | `tools/impl/system/lsp.rs` | - -Names in parentheses are the canonical coding-harness names from issue #1205. -The Rust struct and registration name match the column on the left; the -alias in parentheses is the conceptual role. - -## What each tool does - -### Navigation - -- **`file_read { path }`**. read a workspace-relative file (≤10 MB). - Path-sandboxed and symlink-escape blocked. -- **`grep { pattern, path?, max_matches?, case_insensitive? }`**. - regex search across files. Returns `path:line:text` lines, capped. - Skips `.git`, `node_modules`, `target`, `.next`, `dist`, `build`, - `.cache`. -- **`glob { pattern, max_results? }`**. list files matching a glob - (e.g. `src/**/*.rs`). Sorted newest-first. Same skip set as `grep`. -- **`list { path? }`**. non-recursive directory listing. Each line is - `\t` where kind is `dir`, `file`, or `link`. - -### Editing - -- **`file_write { path, content }`**. overwrite (or create) a file. -- **`edit { path, old_string, new_string, replace_all? }`**. exact - string-replace. By default `old_string` must be unique in the file - (so the model can't accidentally rewrite every occurrence); set - `replace_all` to override. -- **`apply_patch { edits[] }`**. atomic batch of `edit` operations - across one or more files. Validation runs over the whole batch - first; if any edit fails (path not allowed, non-unique match, file - too large, …) **no** files are written. - -### Execution - -- **`shell { command }`**. run a vetted shell command. Use this only - when the right primitive doesn't already exist (e.g. `grep` should - almost always replace `shell { command: "grep ..." }`). - -### Interaction & control flow - -- **`ask_clarification` (canonical `question`)**. pause the run and - ask the user a structured question. Resumes with the answer once - the user replies. -- **`spawn_subagent` (canonical `task`)**. delegate a focused unit of - work to a child agent. Returns a single text result. -- **`todowrite { todos[] }`**. replace the agent's lightweight todo - list. Each item is `{content, status}` where `status ∈ - {pending, in_progress, completed}`. Only one `in_progress` allowed. -- **`plan_exit { plan }`**. emit a `[plan_exit]` marker plus the - plan text, signaling that the plan-mode pass is done and the - harness should hand off to a build-mode pass. The plan→build - switch on the harness side is follow-up work; the marker is stable - today so prompts can be written against it. - -### Web research - -- **`web_search` (canonical `websearch`)**. backend-proxied search - via Parallel. Returns ranked excerpts. -- **`web_fetch` (canonical `webfetch`)**. single-purpose `GET` → - text body, capped. Reuses the same `allowed_domains` gate as - `http_request`. Reach for `web_fetch` when reading docs/READMEs; - reach for `http_request` only when you need methods, headers, or - a body. - -### Code intelligence - -- **`lsp { kind, language, file, line?, character?, symbol? }`**. - capability-gated. Registered only when `OPENHUMAN_LSP_ENABLED=1`. - Schema is stable; the language-server backend is a follow-up, the - current implementation returns a clear `not yet implemented` error - when called, so callers can feature-detect. - -## Permissions and modes - -Permissions live on the [`Tool` -trait](../../src/openhuman/tools/traits.rs). Each tool returns one of: -`None`, `ReadOnly`, `Write`, `Execute`, `Dangerous`. Channels can set -a maximum permission level, anything above is rejected before -execution. - -Today's coding-harness mapping: - -| Permission | Tools | -| --- | --- | -| **None** | `todowrite`, `plan_exit`, `ask_clarification` | -| **ReadOnly** | `file_read`, `grep`, `glob`, `list`, `web_search`, `web_fetch`, `http_request`, `lsp` | -| **Write** | `file_write`, `edit`, `apply_patch` | -| **Execute** | `shell` | - -### Plan mode vs build mode - -`plan_exit` is the seam where a plan-mode pass hands off to a -build-mode pass. The marker (`[plan_exit]`) is stable; the harness -that consumes the marker and switches modes is a follow-up. Until -that lands, a single agent can still call `plan_exit` to log the -plan and then proceed to execution in the same pass. - -In a future plan-mode runner, the rules will be: - -- Plan mode allows only `None` and `ReadOnly` tools, plus - `plan_exit`. -- Build mode allows the full surface (subject to the channel cap). - -The permission machinery is already in place; only the mode-runner -wrapper is missing. - -## When to add a new tool - -If the question is "should this be a new tool or just `shell` with -a longer command?", prefer a new tool when: - -- The operation is one the model gets wrong from `shell` (e.g. - pattern-matching tasks where regex syntax differs across - platforms). -- The operation needs structured input/output the LLM can rely on - (e.g. `apply_patch`'s atomic semantics). -- The operation has security gates that are easier to enforce in - Rust than in shell quoting (e.g. `web_fetch`'s allowed-domains - gate). - -If the answer is yes, follow the existing pattern under -`src/openhuman/tools/impl//`, register in -`src/openhuman/tools/ops.rs`, and add unit tests in the same file. - -## Follow-up work - -These items from issue #1205 are explicitly out of scope for this -baseline PR: - -- Plan-mode and build-mode runners that consume `[plan_exit]`. -- Child-session-backed `task` execution with stable session ids. -- Real LSP backend behind the `lsp` tool. -- Richer permission model (per-tool channel allowlists, per-call - approval policies). -- Controller-registry exposure of the new agent-only tools to - JSON-RPC. Today they remain agent-only, the registry already - exposes `tools_web_search` (and friends) where the Tauri shell - needs them. diff --git a/gitbooks/developing/cloud-deploy.md b/gitbooks/features/cloud-deploy.md similarity index 100% rename from gitbooks/developing/cloud-deploy.md rename to gitbooks/features/cloud-deploy.md