From 50ae83a92d76e19789e49260ac73f99dd918b610 Mon Sep 17 00:00:00 2001 From: Ogulcan Celik Date: Sun, 17 May 2026 20:20:10 +0300 Subject: docs: finalize next release docs --- SOCKET_API.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 79 insertions(+), 6 deletions(-) (limited to 'SOCKET_API.md') diff --git a/SOCKET_API.md b/SOCKET_API.md index 51046860..7ffb276e 100644 --- a/SOCKET_API.md +++ b/SOCKET_API.md @@ -9,7 +9,7 @@ if you are teaching an agent that is already running inside herdr, start with [` there are three practical ways to integrate with herdr: - **agent skill** — [`SKILL.md`](./SKILL.md). best when an agent inside herdr just needs to learn the workflow quickly. -- **cli wrappers** — `herdr server stop`, `herdr workspace ...`, `herdr tab ...`, `herdr pane ...`, `herdr wait ...`. best for shell scripts and simple orchestration. +- **cli wrappers** — `herdr server stop`, `herdr workspace ...`, `herdr tab ...`, `herdr agent ...`, `herdr pane ...`, `herdr wait ...`. best for shell scripts and simple orchestration. - **raw socket api** — best when you want direct request/response control or long-lived event subscriptions. these layers are intentionally stacked on top of the same control surface. @@ -141,6 +141,7 @@ for backward compatibility, requests also accept the older positional forms like ```json { "pane_id": "w64e95948145ed1-1", + "terminal_id": "term_64e95948145ed1", "workspace_id": "w64e95948145ed1", "tab_id": "w64e95948145ed1:1", "focused": true, @@ -148,18 +149,42 @@ for backward compatibility, requests also accept the older positional forms like "label": "reviewer", "agent": "pi", "agent_status": "working", + "custom_status": "indexing", "revision": 0 } ``` +`terminal_id` is an opaque terminal identity. during the pane-backed transition each pane has one terminal id, but clients should not derive it from the pane id. + `label` is an optional manual pane name set through `pane.rename`. +`agent_info` responses contain a terminal-facing view of a live agent terminal: + +```json +{ + "terminal_id": "term_64e95948145ed1", + "name": "reviewer", + "agent": "pi", + "agent_status": "working", + "workspace_id": "w64e95948145ed1", + "tab_id": "w64e95948145ed1:1", + "pane_id": "w64e95948145ed1-1", + "focused": true, + "cwd": "/home/can/Projects/herdr", + "revision": 0 +} +``` + +`name` is an optional unique agent alias set by `agent.start` or `agent.rename`. it is separate from the pane `label`: `pane.rename` names a terminal/pane for UI purposes, while `agent.rename` declares or changes the agent-facing name and rejects duplicate active agent names. + `agent` is an optional display label string. - when herdr detects a built-in agent, this is that built-in name like `pi` or `claude` - when a hook or plugin reports a custom agent through `pane.report_agent`, this can be any non-empty label like `hermes` - when no agent identity is known, it is omitted +`custom_status` on `pane_info` and agent-status events is an optional hook-owned display label. It is present only while hook authority is active. It does not change `agent_status`, `done` semantics, waits, notifications, or workspace/tab rollup priority. + `pane_read` responses contain objects like: ```json @@ -203,6 +228,13 @@ for backward compatibility, requests also accept the older positional forms like | `tab.focus` | focus a tab | `tab_info` | | `tab.rename` | rename a tab | `tab_info` | | `tab.close` | close a tab | `ok` | +| `agent.list` | list terminal-backed agents | `agent_list` | +| `agent.get` | inspect one agent by terminal id, unique agent name, detected agent label, or pane id | `agent_info` | +| `agent.read` | read output from one agent terminal | `pane_read` | +| `agent.send` | send literal text to one agent terminal | `ok` | +| `agent.rename` | set or clear the unique agent name | `agent_info` | +| `agent.focus` | show the agent terminal in the TUI | `agent_info` | +| `agent.start` | start a named agent terminal from argv | `agent_started` | | `pane.list` | list panes, optionally filtered by workspace | `pane_list` | | `pane.get` | inspect one pane | `pane_info` | | `pane.rename` | set or clear a manual pane label | `pane_info` | @@ -624,7 +656,8 @@ params: "source": "custom:hermes", "agent": "hermes", "state": "working", - "message": "running tools" + "message": "running tools", + "custom_status": "indexing" } ``` @@ -637,6 +670,9 @@ notes: - while this authority is active, the reported `agent` and `state` override heuristic display for that pane - process detection still owns pane liveness and fallback when hook authority is cleared or released - `message` is optional metadata for the reporting integration +- `custom_status` is an optional short display label such as `scheduled`, `indexing`, or `stuck` +- `custom_status` is visual-only; use `state` for semantic behavior like working or blocked +- omitting `custom_status` clears any previous custom status from this reporting source returns `ok`. @@ -916,12 +952,13 @@ example pushed `pane.agent_status_changed` event: "pane_id": "1-1", "workspace_id": "1", "agent_status": "done", - "agent": "pi" + "agent": "pi", + "custom_status": "scheduled" } } ``` -`agent` in pushed events follows the same rules as `pane_info.agent`: it may be a built-in detected name, a custom hook-reported label, or omitted. +`agent` in pushed events follows the same rules as `pane_info.agent`: it may be a built-in detected name, a custom hook-reported label, or omitted. `custom_status` may be included when the pane has hook-owned custom status metadata at the time of the semantic status transition. ## cli wrappers these commands provide the shell-facing control surface. most command groups talk to the local socket; `status client` only inspects the local executable. @@ -960,6 +997,30 @@ herdr tab rename