@turmind/halo 2.0.8 → 2.1.0

package/bundled-docs/dev/tools.md

@@ -535,6 +535,63 @@ The remotes configured on this server (the same list in every workspace) — eac
 
 Returns `{ "code": 0, "remotes": [{ name, agent, description, skills }], "pending": [{ remote, context_id, task_id, since }] }`.
 
+## Node tools
+
+File: `packages/server/src/nodes/tools.ts` (`buildNodeTools`). Design notes in [design/node.md](../design/node.md); user guide [guide/node.md](../guide/node.md).
+
+Act on the user's **linked machines** — computers running `halo node`, paired with this workspace in Admin → Channels → Linked machines. Each node tool mirrors one local workspace tool and runs **that same tool** on the machine (same arguments, same output), plus a required `node` argument naming the machine:
+
+| Tool | Mirrors | Extra / different args |
+|---|---|---|
+| `node_list` | — | none |
+| `node_read` | `file_read` | `node` |
+| `node_write` | `file_write` | `node` |
+| `node_edit` | `file_edit` | `node` |
+| `node_list_dir` | `file_list` | `node` |
+| `node_grep` | `grep` | `node` |
+| `node_glob` | `glob` | `node` |
+| `node_run` | `shell_exec` | `node`, `command`, `cwd` (default: the machine's folder) |
+
+**Enabling**: opt-in by the single name `node_list` in `agent.yaml`'s `tools:` — it brings all eight; the other seven names are not recognised on their own. **Full-access sessions only** (`accessLevel === null`). The bundled `default` agent lists it. The admin tool picker shows one `node_list` chip naming the set. Names, descriptions and schemas are constants — which machines are online never changes the tool list or the system prompt (prompt-cache invariant); online state is only in `node_list`'s result.
+
+**Paths**: a machine shares one folder (`--root`; `root` in `node_list`) — relative paths resolve against it, paths that resolve outside it (symlinks included) are refused: `"<p>" is outside this machine's shared folder (<root>) — node tools can only reach paths inside it`. A whole-machine node (`root: null, wholeMachine: true`) has no such check; relative paths resolve against its `base`.
+
+**Runtime**: in `halo server` calls go over the machine's WebSocket; cron runs (a `halo cli` child) reach it through the server's loopback relay. In the standalone CLI / TUI, the evo sandbox and AgentCore mode the tools are listed but every one — `node_list` included — returns `linked machines are not available in this runtime — only \`halo server\` accepts \`halo node\` connections. This is permanent for this runtime, not a temporary outage: do not retry. …`.
+
+**Errors** (returned as the tool error text):
+
+| Case | Message |
+|---|---|
+| Machine linked but not connected | `machine "<n>" is offline (\`halo node\` is not connected). Do not retry in a loop — tell the user to start it.` |
+| Name not linked to this workspace | `unknown machine "<n>" — machines linked to this workspace: <a, b \| (none)> (see node_list)` |
+| Link dropped mid-call | `machine "<n>" went offline during the call (connection lost). The operation may or may not have completed on the machine — check its state before retrying.` |
+| No answer in time (120 s; node_run: shell timeout + 15 s) | `machine "<n>" did not answer within <s>s — the call was cancelled; it may or may not have taken effect.` |
+| node_run without `--allow-shell` | `node_run is disabled on this machine — the user must restart \`halo node\` with --allow-shell to allow commands` |
+| Request over 8 MB | `request too large to send to the machine (<x> MB > 8 MB limit)` |
+
+Results over 256K chars are cut on the machine (`[Content truncated on the machine: N chars total]`); the usual tool-result budget then applies.
+
+### node_list
+
+The machines linked to this workspace and whether each is online. No arguments. Its description doubles as the usage note for the whole set.
+
+Returns `{ "code": 0, "nodes": [...] }`, one entry per linked machine:
+
+- offline: `{ "name": "nas", "online": false }`
+- online: `{ "name": "mbp", "online": true, "root": "/Users/a/proj", "shell": true, "shellTimeoutSec": 120, "os": "darwin", "since": "<ISO>" }` — whole-machine: `"root": null, "wholeMachine": true, "base": "<start dir>"`; `shellTimeoutSec` only when `shell` is true.
+
+No machines at all → `"nodes": []` plus `"hint": "No machines linked — create a token in Admin → Channels → Linked machines, then run \`halo node\` on the machine."`.
+
+### node_run
+
+`shell_exec` on the machine; needs `shell: true` in `node_list`. Runs unsandboxed as the machine's user in `cwd` (default: its folder; in folder mode `cwd` must stay inside it, the command itself is not confined). Killed after `shellTimeoutSec`; output capped like `shell_exec` (~8000 chars to the model) — redirect large output to a file, start long jobs with `nohup … &`. `{{ns.params.x}}` placeholders are not substituted.
+
+| Arg | Type | Required | Description |
+|---|---|---|---|
+| `node` | string | yes | Machine name from `node_list` |
+| `command` | string | yes | Shell command |
+| `cwd` | string | no | Directory to run in, like `path` (default: the machine's folder) |
+
 ## Tool assignment
 
 Workspace tools are enabled strictly by name in `agent.yaml`'s `tools` list:
@@ -547,7 +604,7 @@ skills:
   - code-review    # auto-injects activate_skill
 ```
 
-Tools not listed are not injected. Session/delegation tools do **not** go in `tools:` — they ride on a non-empty `team` (see [Session tools](#session-tools) above). `activate_skill` is auto-injected whenever the YAML lists `skills` (no need to put it in `tools`), and `continue_task` is auto-injected for **every** agent unconditionally (see [continue_task](#continue_task)). The relay and A2A sets are the two name-gated bundles: listing `relay_send` alone brings `relay_interrupt` / `relay_stop` / `relay_read` / `relay_list` with it, full-access sessions only (see [Relay tools](#relay-tools)); listing `a2a_send` alone brings `a2a_stop` / `a2a_read` / `a2a_list`, at every access level except the A2A read-only profile (see [A2A tools](#a2a-tools)).
+Tools not listed are not injected. Session/delegation tools do **not** go in `tools:` — they ride on a non-empty `team` (see [Session tools](#session-tools) above). `activate_skill` is auto-injected whenever the YAML lists `skills` (no need to put it in `tools`), and `continue_task` is auto-injected for **every** agent unconditionally (see [continue_task](#continue_task)). The relay, A2A and node sets are the three name-gated bundles: listing `relay_send` alone brings `relay_interrupt` / `relay_stop` / `relay_read` / `relay_list` with it, full-access sessions only (see [Relay tools](#relay-tools)); listing `a2a_send` alone brings `a2a_stop` / `a2a_read` / `a2a_list`, at every access level except the A2A read-only profile (see [A2A tools](#a2a-tools)); listing `node_list` alone brings the other seven `node_*` tools, full-access sessions only (see [Node tools](#node-tools)).
 
 There is **no implicit default tool set**: `filterTools()` (in `agent-loader.ts`) returns only the tools whose names appear in `agent.yaml`'s `tools:` list. If the field is absent or empty, the agent has zero workspace tools. The admin UI's "Create agent" form scaffolds a fresh agent with an empty `tools: []` for the same reason — fill it in deliberately. The `default` agent's bundled `agent.yaml` lists the common set (`file_read` / `file_write` / `file_edit` / `view_image` / `file_list` / `shell_exec` / `grep` / `glob` / `web_fetch`) that most agents will want; copy that line if you're starting from scratch.
 

package/bundled-docs/guide/README.md

@@ -24,6 +24,10 @@ Aimed at Halo end-users. Pick the doc that matches your situation.
 - [WeChat](channels/wechat.md) — QR-scan iLink bot
 - [ACP](channels/acp.md) — Zed / JetBrains or other ACP clients driving a remote halo
 
+## Linked machines
+
+[node.md](node.md) — run `halo node` on your own computer so a workspace's agents can work on files there.
+
 ## Related docs
 
 - Development: [dev/](../dev/) — environment, API, tool reference

package/bundled-docs/guide/agents.md

@@ -69,7 +69,7 @@ team:                 # a non-empty team is what enables delegation
   - executor          # the agent ids this one may spawn
 ```
 
-**Workspace tools**: `file_read / view_image / file_write / file_edit / file_list / shell_exec / grep / glob / web_fetch` — listed by name under `tools`.
+**Workspace tools**: `file_read / view_image / file_write / file_edit / file_list / shell_exec / grep / glob / web_fetch` — listed by name under `tools`. `node_list` switches on the eight `node_*` tools for [linked machines](node.md) as one set (full-access sessions only).
 
 **Session tools**: `start_session / session_list / query_session / interrupt_session / stop_session / archive_session / get_session_output / query_agent` — **not** listed under `tools`. The whole bundle is granted automatically the moment an agent declares a non-empty `team`; an empty/absent `team` means no delegation (no session tools, no roster). To let a sub-agent delegate further, give it its own `team`. Add the agent's own id to its `team` to enable parallel self-spawn.
 

package/bundled-docs/guide/cli.md

@@ -308,6 +308,29 @@ the caller-side `auth: sigv4` remote, session dirs and ops notes:
 [design/agentcore.md](../design/agentcore.md). The hub skill `agentcore-deploy`
 builds the image and creates the runtime for you.
 
+## Linked machine (`halo node`)
+
+```bash
+HALO_NODE_TOKEN=<token> halo node --server https://halo.example.com --root ~/proj [--allow-shell]
+```
+
+Links this machine to a workspace on a halo server, so that workspace's
+full-access agents can work on files here with the `node_*` tools. Runs in the
+foreground, reconnects on its own, Ctrl-C to stop. Needs no `halo setup` and
+no model keys — nothing is written under `~/.halo/`. Create the token in
+Admin → Channels → Linked machines.
+
+| Flag / env | Meaning |
+|---|---|
+| `--server <url>` | Server address, `http(s)://host:port` (`ws(s)://` also accepted) — required |
+| `--token <t>` / `HALO_NODE_TOKEN` | Pairing token — required; prefer the env var (flags show up in `ps`) |
+| `--root <dir>` | Folder to share; every path must stay inside it. Omit (or `/`) for whole-machine mode: any path this user can reach, relative paths from the current dir |
+| `--allow-shell` | Let agents run commands (`node_run`) as this user, not sandboxed. Off by default |
+| `--header "Name: value"` | Repeatable. Extra header on the connection, for an auth proxy in front of the server |
+
+Exits 1 on a rejected / revoked token, a deleted workspace or a protocol
+mismatch; retries everything else. Full guide: [node.md](node.md).
+
 ## Architecture
 
 ```

package/bundled-docs/guide/delegation-and-access.md

@@ -94,7 +94,7 @@ Three session levels, stored per session (`agent_sessions.access_level`; `full`
 
 | Level | Tools the agent can get (from its `tools:` list) | Sandbox |
 |---|---|---|
-| `full` | all 9 workspace tools | none (the `rm` guard still applies) |
+| `full` | all 9 workspace tools, plus the full-only bundles `relay_send` and `node_list` (linked machines) when listed | none (the `rm` guard still applies) |
 | `workspace` | all 9 | writes only inside the workspace; credentials and workspace runtime state are hidden |
 | `readonly` | all 9 with an OS sandbox (writes fail); only `file_read`, `view_image`, `file_list`, `grep`, `glob` without one | nothing writable |
 
@@ -103,7 +103,7 @@ Extra rules:
 - A readonly `shell_exec` gets no secret substitution — `{{…params…}}` / `<<ENV>>` placeholders stay literal.
 - `view_image` also needs a vision-capable model.
 - A skill with `requiresAccess` above the session level is hidden (no metadata, no `activate_skill`).
-- Relay tools are only built for `full` sessions. A2A tools (`a2a_send` in `tools:`) are built at every level except the A2A read-only profile; a non-full session's `files` must sit in the workspace or the temp dir ([dev/tools.md → A2A tools](../dev/tools.md#a2a-tools)).
+- Relay tools and linked-machine tools (`node_list` in `tools:` → the eight `node_*` tools, [node.md](node.md)) are only built for `full` sessions. A2A tools (`a2a_send` in `tools:`) are built at every level except the A2A read-only profile; a non-full session's `files` must sit in the workspace or the temp dir ([dev/tools.md → A2A tools](../dev/tools.md#a2a-tools)).
 - Hidden from `workspace` / `readonly` sessions only (Full sessions, the admin file explorer and the terminal see everything): a built-in list that is always included (`~/.halo/secrets`, `~/.aws`, `~/.ssh`, `~/.gnupg`, `~/.docker`, `~/.config/gh`, `~/.gitconfig`, `~/.git-credentials`, `~/.npmrc`, `~/.netrc`, the global evo/cron/runs databases, internal-session transcripts, logs, …), any extra paths added in `general.sandbox.hidden_dirs` / `hidden_files` (they add to the built-in list, never replace it), plus the workspace's own `.halo/sessions`, `.halo/logs`, `.halo/evo`, `.halo/halo.db*` (fixed in code). The rest of `.halo/` stays readable.
 
 ### Where a session's level comes from

package/bundled-docs/guide/node.md

@@ -0,0 +1,86 @@
+# Linked machines (`halo node`)
+
+Let a workspace's agents work on files on **your own computer** — a laptop, a desktop, a box behind NAT — while the agents themselves keep running on the halo server. You run `halo node` on that machine; it dials out to the server (no port to open), and the workspace's agents get `node_*` tools that read, write, search and (if you allow it) run commands there.
+
+```
+[your laptop]                               [server]
+halo node --root ~/proj ──WebSocket──────▶ halo server ── agent in workspace W
+  (files, optional shell)                     node_read / node_write / … / node_run
+```
+
+The machine needs only the `halo` package — no `halo setup`, no model keys, nothing under `~/.halo/`.
+
+Supported: **macOS and Linux**. Windows works on a best-effort basis (not regularly tested; `node_run` commands go to `cmd.exe`).
+
+## 1. Create a token
+
+Admin → **Channels → Linked machines** → **Add machine**. Pick the workspace and a machine name (`a-z 0-9 -`, e.g. `mbp`; unique within the workspace — the agent uses it to address the machine). The dialog shows a command to copy:
+
+```bash
+HALO_NODE_TOKEN=<token> halo node --server https://halo.example.com --root <folder>
+```
+
+The token stays on the list row (copy button). Deleting the row revokes it at once and disconnects the machine.
+
+## 2. Run `halo node` on the machine
+
+```bash
+npm install -g @turmind/halo                   # once
+export HALO_NODE_TOKEN=<token>                 # better than --token: flags show up in ps / shell history
+halo node --server https://halo.example.com --root ~/proj
+```
+
+It runs in the foreground and logs each call (`[Node] read src/app.ts`, `[Node] refused write ../x: outside root`). Ctrl-C stops it. It reconnects by itself after network drops or a server restart; it exits on a bad / revoked token or when the workspace is gone.
+
+The admin row turns green (live, no refresh) and shows `folder · shell on/off · os`.
+
+### Folder mode vs whole-machine mode
+
+- **`--root <folder>`** — share one folder. Every path the agent passes must stay inside it (symlinks pointing out are refused too); relative paths start from it.
+- **No `--root`** (or `--root /`) — **whole-machine mode**: the agent can reach every path your user can, like a full-access local session. Relative paths start from the directory you ran `halo node` in. A startup line warns about it, and the admin shows "Whole machine".
+
+Prefer `--root` unless you really mean the whole machine.
+
+### `--allow-shell`
+
+Off by default — `node_run` then refuses with "restart `halo node` with --allow-shell". With it, agents can run **any command as your user, not sandboxed**. In folder mode only the command's working directory is held inside the folder; the command itself (`cat ~/.ssh/...`, `curl ...`) can reach anything your user can. Turn it on only for agents and workspaces you trust. Commands are killed after the shell timeout (120 s, or `HALO_SHELL_TIMEOUT` in ms on the machine).
+
+### What the agent can see
+
+Everything inside the shared folder — including `.env` files, keys, credentials and git history. Don't share a folder that holds secrets you wouldn't paste into the chat. Whole-machine mode exposes your whole home directory.
+
+### Behind a login proxy
+
+`halo node` sends a bearer token, nothing else. If the server sits behind an auth proxy (Cloudflare Access, an SSO gateway, basic auth), either point `--server` at an address the machine can reach directly, or pass the proxy's credentials with `--header` (repeatable, `Name: value`, split on the first colon):
+
+```bash
+halo node --server https://halo.example.com --root ~/proj \
+  --header "CF-Access-Client-Id: <id>" --header "CF-Access-Client-Secret: <secret>"
+```
+
+## 3. Let the agent use it
+
+Node tools are enabled per agent by **`node_list`** in `agent.yaml`'s `tools:` — that one name brings all eight (`node_list`, `node_read`, `node_write`, `node_edit`, `node_list_dir`, `node_grep`, `node_glob`, `node_run`). The bundled `default` agent lists it. If your workspace overrides the default agent (`<workspace>/.halo/agents/default/agent.yaml`), or you use another agent, add it yourself:
+
+```yaml
+tools:
+  - file_read
+  # …
+  - node_list   # linked machines (whole node_* set)
+```
+
+Only **Full** access sessions get node tools — a Workspace or Readonly session listing `node_list` gets none. Cron jobs in the workspace can use them too.
+
+Then just ask: "list my machines", "read `notes/todo.md` on mbp", "run the tests on mbp". The agent calls `node_list` first to see which machines are online.
+
+## Troubleshooting
+
+| Message | Meaning |
+|---|---|
+| `token rejected by the server (401)` | Wrong / deleted token — create a new one. 5 bad tries in 15 min lock the address out for a while (429). |
+| `the workspace this token is bound to no longer exists (404)` | The workspace folder was removed on the server. |
+| `protocol mismatch (426)` | `halo` versions too far apart — upgrade the older side. |
+| `this token is already connected from another process` | Another `halo node` with the same token is running; this one keeps retrying until that one stops. Also normal right after the machine rebooted or woke from sleep: the server needs 40–60 s to notice the old connection is dead, so the new process backs off and can take up to ~90 s to come online. |
+| agent: `machine "mbp" is offline` | `halo node` isn't running / connected. |
+| agent: `went offline during the call` | The connection dropped mid-call; the operation may or may not have happened. Running commands on the machine were stopped. |
+| agent: `not available in this runtime` | You're in the standalone CLI / TUI — linked machines only work through `halo server` (admin UI or a channel). |

package/bundled-docs/requirements/agent.md

@@ -60,7 +60,7 @@ Same id present in both scopes: workspace wins; the overridden global is greyed
 
 ### Tool selection
 - **Session tools**: `start_session` / `session_list` / `query_session` / `interrupt_session` / `stop_session` / `archive_session` / `get_session_output` / `query_agent` — **not** selected by name; the whole bundle is granted automatically by a non-empty `team` (see below). Listing them under `agent.yaml tools` has no effect.
-- **Workspace tools**: `file_read` / `view_image` / `file_write` / `file_edit` / `file_list` / `shell_exec` / `grep` / `glob` / `web_fetch`, plus the single `relay_send` chip (grants the whole cross-workspace relay set, full-access sessions only) and the single `a2a_send` chip (grants the cross-server A2A set — `a2a_send` / `a2a_stop` / `a2a_read` / `a2a_list` — at every access level except the A2A read-only profile), returned by `GET /api/agent-configs/tools`. `view_image` is dropped at runtime when the model can't take images (the form dims it)
+- **Workspace tools**: `file_read` / `view_image` / `file_write` / `file_edit` / `file_list` / `shell_exec` / `grep` / `glob` / `web_fetch`, plus the single `relay_send` chip (grants the whole cross-workspace relay set, full-access sessions only) the single `a2a_send` chip (grants the cross-server A2A set — `a2a_send` / `a2a_stop` / `a2a_read` / `a2a_list` — at every access level except the A2A read-only profile) and the single `node_list` chip (grants the eight linked-machine `node_*` tools, full-access sessions only — see [design/node.md](../design/node.md)), returned by `GET /api/agent-configs/tools`. `view_image` is dropped at runtime when the model can't take images (the form dims it)
 - **`activate_skill`**: auto-injected when the YAML lists at least one usable skill (not disabled, allowed at the session's access level); loads the full SKILL.md on demand
 
 ### Team (delegation switch + whitelist)

package/bundled-docs/requirements/workspace.md

@@ -67,6 +67,8 @@ Two tabs:
 
 Current tab stored in `editorStore.bottomTab`.
 
+The middle of the tab bar shows the current tab's title — the session title on Chat ("New session" for a draft, "Untitled session" until it has one), the active terminal's name on Terminal. It is truncated with an ellipsis when it doesn't fit (full text on hover) and hidden when the bar is too narrow.
+
 ### Floating mode
 The tab bar has a maximize button and, at the far right, a float button. Toggling the float button detaches the panel into a draggable window:
 - **Default position/size**: bottom-right corner, 480×640 with a 24px margin

package/dist/evo-wrapper.js

@@ -211,6 +211,9 @@ function cleanChildEnv() {
   const env = { ...process.env };
   delete env.HALO_PASSWORD;
   delete env.HALO_JWT_SECRET;
+  delete env.HALO_NODE_RELAY_URL;
+  delete env.HALO_NODE_RELAY_TOKEN;
+  delete env.HALO_NODE_TOKEN;
   for (const key of settingsOtelEnvKeys)
     delete env[key];
   return env;