From 86adf88351e17c6a11cac253714b169eac0db233 Mon Sep 17 00:00:00 2001 From: Ogulcan Celik Date: Sun, 17 May 2026 01:41:16 +0300 Subject: feat: add terminal identity and agent cli facade --- SOCKET_API.md | 46 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) (limited to 'SOCKET_API.md') diff --git a/SOCKET_API.md b/SOCKET_API.md index 51046860..fe6aed2d 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, @@ -152,8 +153,29 @@ for backward compatibility, requests also accept the older positional forms like } ``` +`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 the same live pane-backed 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 the manual pane label treated as the terminal/agent name by `agent.*` commands. `agent.rename` rejects duplicate active names; `pane.rename` remains backward-compatible and can still create duplicates. + `agent` is an optional display label string. - when herdr detects a built-in agent, this is that built-in name like `pi` or `claude` @@ -203,6 +225,12 @@ 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 named or detected terminal-backed agents | `agent_list` | +| `agent.get` | inspect one terminal-backed agent by terminal id, unique name, or pane id | `agent_info` | +| `agent.read` | read output from one terminal-backed agent | `pane_read` | +| `agent.send` | send literal text to one terminal-backed agent | `ok` | +| `agent.rename` | set or clear the unique agent/terminal name | `agent_info` | +| `agent.focus` | show the terminal-backed agent in the TUI | `agent_info` | | `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` | @@ -960,6 +988,19 @@ herdr tab rename