mirror of
https://github.com/tinyhumansai/openhuman.git
synced 2026-07-27 21:08:00 +00:00
GITBOOK-46: No subject
This commit is contained in:
Steven Enamakel
+2
-3
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
`<kind>\t<name>` 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/<category>/`, 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.
|
||||
Reference in New Issue
Block a user