@howaboua/pi-shepherdr 0.2.15 → 0.2.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +40 -33
  3. package/index.ts +16 -26
  4. package/package.json +11 -11
  5. package/src/agents-contract.ts +11 -1
  6. package/src/agents-discovery.ts +21 -7
  7. package/src/agents-focus.ts +242 -0
  8. package/src/agents-spawn.ts +23 -0
  9. package/src/agents-tool.ts +34 -5
  10. package/src/attachment-protocol.ts +7 -3
  11. package/src/attachment-target.ts +3 -1
  12. package/src/attachment.ts +3 -1
  13. package/src/board/host.ts +98 -366
  14. package/src/board/membership.ts +14 -8
  15. package/src/command-config.ts +51 -0
  16. package/src/control-panel-actions.ts +0 -20
  17. package/src/control-panel-items.ts +8 -36
  18. package/src/control-panel-view.ts +2 -11
  19. package/src/control-panel.ts +2 -11
  20. package/src/controller.ts +5 -5
  21. package/src/delivery.ts +0 -33
  22. package/src/herdr-client.ts +39 -6
  23. package/src/messages.ts +61 -61
  24. package/src/monitor-events.ts +24 -2
  25. package/src/monitor-questions.ts +12 -3
  26. package/src/monitor.ts +2 -2
  27. package/src/peer-channel.ts +39 -0
  28. package/src/peer-commands.ts +173 -0
  29. package/src/peer-inbox.ts +218 -55
  30. package/src/remote/shepherdr-channel.mjs +225 -0
  31. package/src/remote/shepherdr-checkpoints.mjs +5 -3
  32. package/src/remote/shepherdr-peer.mjs +151 -22
  33. package/src/remote/shepherdr.mjs +56 -8
  34. package/src/remote-client.ts +115 -11
  35. package/src/settlement.ts +1 -0
  36. package/src/shared-context.ts +104 -1
  37. package/src/types.ts +23 -0
  38. package/src/voice-handoff.ts +177 -0
  39. package/src/board/archive.ts +0 -77
  40. package/src/board/awareness.ts +0 -115
  41. package/src/board/config.ts +0 -121
  42. package/src/board/contract.ts +0 -181
  43. package/src/board/identity.ts +0 -169
  44. package/src/board/paging.ts +0 -55
  45. package/src/board/protocol.ts +0 -73
  46. package/src/board/queries.ts +0 -176
  47. package/src/board/response.ts +0 -56
  48. package/src/board/store.ts +0 -327
  49. package/src/board/tool.ts +0 -23
  50. package/src/board/turns.ts +0 -100
  51. package/src/context-briefing.ts +0 -226
package/CHANGELOG.md CHANGED
@@ -1,5 +1,26 @@
1
1
  # @howaboua/pi-shepherdr
2
2
 
3
+ ## 0.2.16
4
+
5
+ - ### Breaking changes
6
+ - **BREAKING CHANGE:** Boards moved to `@howaboua/pi-agent-board`. Install it in every participating session and reload Pi. Existing archives, session bindings and subscriptions are preserved. Board settings now live under `/board`, not `/herdr`. The board extension requires Pi 1.1 or newer and Node.js 22.18 or newer.
7
+ - **BREAKING CHANGE:** Custom extension commands sent through `agents` require an `extensionCommands` allowlist in the receiving session's global `pi-shepherdr.json`. Add the commands you use, then update and reload both controllers and receiving agents. `/herdr` Settings shows the config path and format.
8
+
9
+ ### Features
10
+ - Route `/quit`, `/model`, `/thinking`, `/name`, `/new`, `/reload`, `/resume` and `/compact` to agents. `/quit` shuts down Pi before closing its pane. Blocked commands return available commands instead of becoming model prompts. Skills and prompt templates remain supported.
11
+ - Focus running Pi sessions with `agents focus`, optionally transferring voice through GipPity Control, Codex Conversion or Grok Realtime. Handoffs retain the microphone and browser connection, identify the source device, session and pane without exposing session-file paths, and offer a return action without starting an agent task. Remote focus selects the destination's Herdr session. Client machine selection remains manual.
12
+ - Pass a shared-board thread to a spawned agent with `board_thread_id` so its initial task can read that context.
13
+ - Support shared and attached agents with different notes owners. Local checkpoints remain available after detachment.
14
+ - Accept `/root` as the live root of an agent's own family, including across connected machines. Missing or ambiguous roots fail explicitly. Exact spawn and find targets remain unchanged.
15
+
16
+ ### Improvements
17
+ - Agents returns help when called without arguments, including an empty structured object.
18
+ - Delegation guidance keeps task ownership with either the parent or its delegated agent, avoiding duplicated work.
19
+
20
+ ### Fixes
21
+ - Reduce redundant monitoring warnings when workers close, move or are unwatched. Retire question watches and suppress late collection failures.
22
+ - Coalesce repeated board-owner outage warnings until connectivity recovers. Preserve Herdr event-stream error details locally and over SSH.
23
+
3
24
  ## 0.2.15
4
25
 
5
26
  - Show a quiet, theme-aware notice with the channel name after an agent successfully posts to the board. Notices remain visible in restored history without adding model context.
package/README.md CHANGED
@@ -14,7 +14,7 @@ With Pi Codex's compatible custom developer-message API active, asynchronous wor
14
14
  pi install npm:@howaboua/pi-shepherdr
15
15
  ```
16
16
 
17
- Requires Pi 1.0.0 or newer, Herdr 0.9 or newer and the Herdr Pi integration:
17
+ Requires Pi 1.1.0 or newer, Node.js 22.18 or newer, Herdr 0.9 or newer and the Herdr Pi integration:
18
18
 
19
19
  ```bash
20
20
  herdr integration install pi
@@ -32,9 +32,9 @@ The agent tool is always available in Pi, Code Mode and Notebook Mode. Run Pi in
32
32
  /herdr
33
33
  ```
34
34
 
35
- **Settings** contains orchestration and board preferences. **Status** shows machine connections and reconnect actions. **Connections** adds SSH machines through Herdr's setup flow. Agents handle discovery, attachment and detachment through the `agents` tool, not this panel.
35
+ **Settings** contains orchestration preferences, agent command guidance and the global config path. **Status** shows machine connections and reconnect actions. **Connections** adds SSH machines through Herdr's setup flow. Agents handle discovery, attachment and detachment through the `agents` tool, not this panel.
36
36
 
37
- `/herdr` is the only entry point; board, connect and orchestration subcommands are replaced by panel controls. Outside the TUI, it reports status without changing it. An orchestration change records one visible guidance message without triggering a turn. Resumed sessions restore their last mode; new sessions start with normal guidance. The current guidance returns when a new model context no longer contains it, including turns started by worker messages. Tool availability and monitoring do not depend on this mode.
37
+ `/herdr` is Shepherdr's only entry point. Outside the TUI, it reports status without changing it. An orchestration change records one visible guidance message without triggering a turn. Resumed sessions restore their last mode; new sessions start with normal guidance. The current guidance returns when a new model context no longer contains it, including turns started by worker messages. Tool availability and monitoring do not depend on this mode.
38
38
 
39
39
  To add a machine, enter an SSH target or alias, a label and an optional remote session under **Connections**. Herdr performs setup in the terminal and asks before installing or replacing its remote server. OpenSSH owns authentication; Shepherdr does not store credentials. Profiles remain in Herdr's existing catalog, where they can also be renamed, disabled or removed.
40
40
 
@@ -50,7 +50,7 @@ Remote machines connect over noninteractive SSH. The target needs `node` on its
50
50
 
51
51
  ## Agent calls
52
52
 
53
- Call the `agents` tool with `action: "help"` before first use, then send flat request objects. Code and Notebook Mode expose the same router as `await tools.agents({ action: "help" })`; every call requires `action`.
53
+ Call `agents` with `{}` before first use, alone, then send flat request objects with `action`. Code and Notebook Mode use `await tools.agents()`. Explicit `action: "help"` also returns help.
54
54
 
55
55
  | Action | Result |
56
56
  | --- | --- |
@@ -87,7 +87,36 @@ Prompts sent through `agents` identify peer messages versus delegated tasks and
87
87
 
88
88
  Messages sent through `agents` bypass the receiving Pi editor, preserving unsent drafts. Update and reload Shepherdr on receiving agents as well as controllers. If a receiver is unavailable, delivery fails without pasting into its terminal. Raw `herdr agent prompt` still uses terminal input and does not provide this protection.
89
89
 
90
- Messages beginning with `/` use the target Pi session's command, skill and prompt-template expansion, with sender attribution kept out of the arguments. Skills and templates retain normal task waiting. Registered extension commands return `commandSubmitted: true` without waiting or adding a task watch, even through `spawn` or `assign`; submission does not confirm command success. TUI-only commands such as `/model` and `/settings` are not available through this route. When Pi Codex Conversion is installed, update and reload it too.
90
+ Messages beginning with `/` use the target Pi session's command, skill and prompt-template expansion, with sender attribution kept out of the arguments. Skills and templates retain normal task waiting. Prompt templates remain supported, but you must tell your agent which templates exist separately. When Pi Codex Conversion is installed, update and reload it too.
91
+
92
+ ### Agent commands
93
+
94
+ These built-in commands are available through agent messages without an allowlist:
95
+
96
+ | Command | Result |
97
+ | --- | --- |
98
+ | `/quit` | Shut down Pi gracefully and close its Herdr pane |
99
+ | `/model <provider/model>` | Change the model |
100
+ | `/thinking <level>` | Change the thinking level |
101
+ | `/name <name>` | Rename the session |
102
+ | `/new` | Start a new session |
103
+ | `/reload` | Reload Pi resources |
104
+ | `/resume <path>` | Resume the session at the supplied path |
105
+ | `/compact [instructions]` | Compact the session with optional instructions |
106
+
107
+ Custom extension commands must be both registered in the receiving Pi session and allowed in its global user config. **Settings → Agent commands** shows the actual config path. The file is `pi-shepherdr.json` in Pi's agent directory, normally `~/.pi/agent`. Add `extensionCommands`, preserving any existing fields:
108
+
109
+ ```json
110
+ {
111
+ "extensionCommands": {
112
+ "my-command": "Run my custom extension action"
113
+ }
114
+ }
115
+ ```
116
+
117
+ Keys are command names without `/`; values are nonempty descriptions. Only the global user config grants permission. A repository's `.pi/pi-shepherdr.json` cannot allow commands. The config is read on each call. A missing allowlist allows no custom extension commands; malformed config grants none.
118
+
119
+ Blocked commands return the built-in commands and currently registered, allowed extension commands. Commands return `commandSubmitted: true` without adding a task watch, even through `spawn` or `assign`. Submission does not confirm command success, except `/quit`, which waits for Pi to exit and its pane to close. Built-in commands other than `/quit` require an idle target. Skills and prompt templates keep their existing behavior.
91
120
 
92
121
  Idle messages start a prepared user turn. Messages arriving during a run use steering, promoted to developer messages when Pi Codex developer delivery is active. Otherwise they remain ordinary Pi custom messages.
93
122
 
@@ -107,7 +136,7 @@ Context attachment requires updated Codex Conversion with Local, Tree or Remote
107
136
 
108
137
  An account mismatch rejects context sharing. Each agent keeps its own notes and history. If the account changes after attachment, pinned Remote notes become unavailable, including native Remote notes. Notes do not move to a new account or another store. Use messages to exchange the context the other agent needs.
109
138
 
110
- `board: true` joins the controller's enabled board and returns `boardAgent` for subscriptions and notifications. The target's previous board archive stays untouched. If the folders differ, that archive remains in its original folder rather than becoming part of the controller's archive. Board-only attachment works without Codex Conversion and with Remote context storage.
139
+ `board: true` requires Pi Agent Board loaded in both sessions. It joins the controller's enabled board and returns `boardAgent` for subscriptions and notifications. The target's previous board archive stays untouched. If the folders differ, that archive remains in its original folder rather than becoming part of the controller's archive. Board-only attachment works without Codex Conversion and with Remote context storage.
111
140
 
112
141
  The target must be idle and both Pi sessions must be saved. Existing shared-context members and controllers with context children cannot be context targets. Existing board members and roots with board children cannot switch boards. A target supports one controller and one fixed set of attachment choices. Attachment starts no task or watch; `assign` and `send` never attach implicitly.
113
142
 
@@ -119,37 +148,15 @@ If an attached owner closes or dies, Local and Tree notes reads first use its la
119
148
 
120
149
  ## Message board
121
150
 
122
- The board is off by default. Open `/herdr` → **Settings** in the root session and choose a session override, a remembered folder default, or a global default. Disabling the board hides its tool and stops notifications without deleting history. Board storage requires Node.js 22.13 or newer. Pi Codex Conversion is not required.
123
-
124
- Session overrides survive resume but do not carry into new root sessions or forks. Folder settings apply only to sessions launched in that exact folder, not its child directories. Global enablement is a separate setting. Precedence is session, folder, then global. Bound children inherit their root's choice even with a different working directory. Orchestration mode and shared notes remain independent.
151
+ Boards are provided by the separate [Pi Agent Board](../pi-agent-board) extension. Install it in every participating Pi session, then reload:
125
152
 
126
- The menu saves folder settings in `<launch-folder>/.pi/pi-shepherdr.json`:
127
-
128
- ```json
129
- { "board": { "enabled": true } }
130
- ```
131
-
132
- The extension creates `pi-shepherdr.json` in Pi's global agent directory with this default:
133
-
134
- ```json
135
- { "board": { "enabledGlobally": false } }
153
+ ```sh
154
+ pi install npm:@howaboua/pi-agent-board
136
155
  ```
137
156
 
138
- The agent directory defaults to `~/.pi/agent` and respects `PI_CODING_AGENT_DIR`. Enabling a board in the home folder writes `~/.pi/pi-shepherdr.json`, not the global setting. It does not enable boards in other folders. Storage location never implies activation scope. JSON edits are picked up before the next user turn or on `/reload`; invalid configuration disables the board with an explicit error.
139
-
140
- If the global agent directory is the launch folder's `.pi` directory, that file is only global configuration. Use a session override instead of a folder default there.
141
-
142
- Agents call `board` with `action: "help"` to discover channels, posts, replies, search, subscriptions and bounded reads. Code and Notebook Mode use `tools.board`. Agents choose when discussions are useful. Enabling the board, starting sessions, reading history and spawning children do not create an empty board. The first successful channel creation or post to a new channel creates it.
143
-
144
- Agents receive a board briefing once per context window, including after compaction. It distinguishes an empty board from existing posts, leaves setup to the main agent, and points members to relevant discussion. Joining or re-enabling a board adds a briefing at the next model request. Resuming the same window does not repeat it. Post text stays behind the board tool.
145
-
146
- Results fit 8,000 serialized UTF-8 bytes, including JSON escaping and metadata. Reads may return smaller pages or text slices than requested. Continue with the returned cursor or `next_offset_chars`. A search with `after_message_id` requires a post in the selected board, even before an archive exists.
147
-
148
- One archive at `<owning-folder>/.pi/agent-message-board.sqlite` retains all boards for that folder. Each root Pi session has an isolated board; resume keeps it and new root sessions get separate boards. Children spawned while the board is enabled inherit its location and board ID even with another working directory. The spawn result's `boardAgent` is their address for subscriptions and explicit notifications, distinct from a pane or shared-notes identity. Independently started agents, existing `assign` targets and children spawned while it is off do not join automatically; use explicit `attach` to join an existing agent. Board identity is independent of shared notes and `share_context`.
149
-
150
- Calls default to the current board. `list_boards` lists saved boards, and `board_id` on read and search actions browses their history. Writes and subscriptions always target the current board. There is no task assignment, post editing or board deletion tool. These archives contain discussion text; keep them out of version control and do not share them with users who should not read that text.
157
+ The same discussions, subscriptions and saved history continue without migration. Pi Agent Board owns the `board` tool, settings and `/board` browser viewer. Shepherdr has no fallback board or board controls under `/herdr`. If a saved board setting is on but the extension is missing, Shepherdr displays an installation warning once per session. Saved settings and archives remain untouched. Pi Codex Conversion is optional.
151
158
 
152
- Posting subscribes its author to discussion replies unless the author explicitly unsubscribed. Channel subscriptions concern only new first posts. Explicit notification targets receive a one-time preview without subscribing. Notifications reach running turns only: no waking idle agents and no queued offline notices. Full text remains available through reads.
159
+ Shepherdr supplies family membership, attachments and remote routing. Children spawned while the board is enabled inherit its location and board ID even with another working directory. The spawn result's `boardAgent` is their address for subscriptions and explicit notifications, distinct from a pane or shared-notes identity. Independently started agents, existing `assign` targets and children spawned while it is off do not join automatically. Use explicit `attach` to join an existing agent. Board identity is independent of orchestration mode, shared notes and `share_context`.
153
160
 
154
161
  Child board calls use the owning Pi sessions and existing SSH connections, not a separately provisioned service. The root and intermediate controllers must be running as processes, but need not be in an active model turn. Resume the owner and reconnect under `/herdr` → **Status** after a lost connection. Future root sessions can browse the archive even when the old owner is offline. A fork starts a new independent identity. Profiles selecting an existing session cannot bind to an enabled board through `spawn`; use `attach` followed by `assign` instead.
155
162
 
package/index.ts CHANGED
@@ -1,17 +1,18 @@
1
1
  import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
2
  import registerPackageChangelog from "./changelog.js";
3
3
  import { isBlockingAgentsCall } from "./src/agents-contract.js";
4
+ import { acceptFocus, registerFocusArrivals } from "./src/agents-focus.js";
4
5
  import { createAgentsTool } from "./src/agents-tool.js";
5
- import { ensureBoardConfig } from "./src/board/config.js";
6
6
  import { AgentBoard } from "./src/board/host.js";
7
- import { createBoardTool } from "./src/board/tool.js";
8
7
  import { registerAgentController } from "./src/controller.js";
9
8
  import { registerDeveloperDelivery } from "./src/delivery.js";
10
9
  import { AgentFleet } from "./src/fleet.js";
11
10
  import { registerAgentEventRenderer } from "./src/messages.js";
11
+ import { createPeerCommands } from "./src/peer-commands.js";
12
12
  import { registerPeerInbox } from "./src/peer-inbox.js";
13
13
  import { installAgentProfiles } from "./src/profiles.js";
14
14
  import { registerSharedAgentContext } from "./src/shared-context.js";
15
+ import { registerVoiceFocusReceiver } from "./src/voice-handoff.js";
15
16
 
16
17
  const CODE_MODE_PACKAGE = "@howaboua/pi-codex-conversion";
17
18
  const CODE_MODE_MODULE = `${CODE_MODE_PACKAGE}/code-mode`;
@@ -20,53 +21,42 @@ export default async function shepherdrExtension(
20
21
  pi: ExtensionAPI,
21
22
  ): Promise<void> {
22
23
  registerPackageChangelog(pi);
23
- ensureBoardConfig();
24
+
24
25
  await installAgentProfiles();
25
26
  await registerDeveloperDelivery(pi);
26
- registerPeerInbox(pi);
27
+ const peerCommands = createPeerCommands(pi);
27
28
  const fleet = new AgentFleet(pi);
28
- const board = new AgentBoard(pi, fleet);
29
+ registerFocusArrivals(pi);
30
+ registerVoiceFocusReceiver(pi, (ctx, pane, request) =>
31
+ acceptFocus(pi, ctx, fleet, pane, request),
32
+ );
33
+ const board = AgentBoard.create(pi, fleet);
34
+ registerPeerInbox(pi, peerCommands, fleet, (ctx) => board.promptCatchup(ctx));
29
35
  const sharedContext = await registerSharedAgentContext(pi, fleet, board);
30
- const tool = createAgentsTool(fleet, sharedContext, board);
31
- const boardTool = createBoardTool(board);
36
+ const tool = createAgentsTool(fleet, sharedContext, board, pi);
32
37
 
33
38
  registerAgentEventRenderer(pi);
34
39
  pi.registerTool(tool);
35
- pi.registerTool(boardTool);
36
- await registerAgentsInCodeMode(pi, tool, boardTool, board);
37
- registerAgentController(pi, fleet, board);
40
+ await registerAgentsInCodeMode(pi, tool);
41
+ registerAgentController(pi, fleet, peerCommands);
38
42
  }
39
43
 
40
44
  async function registerAgentsInCodeMode(
41
45
  pi: ExtensionAPI,
42
46
  tool: ReturnType<typeof createAgentsTool>,
43
- boardTool: ReturnType<typeof createBoardTool>,
44
- board: AgentBoard,
45
47
  ) {
46
48
  try {
47
49
  const { adaptToolForCodeMode, registerCodeModeExtensionTools } =
48
50
  await import("@howaboua/pi-codex-conversion/code-mode");
49
51
  const registration = registerCodeModeExtensionTools(pi, () => [
50
52
  adaptToolForCodeMode(tool, {
53
+ prepareInput: (input) => (input === undefined ? {} : input),
51
54
  blocking: isBlockingAgentsCall,
52
- usage:
53
- 'await tools.agents({ action: "help" }) // Persistent agents; first call alone',
55
+ usage: "await tools.agents() // Persistent agents; first call alone",
54
56
  }),
55
57
  ]);
56
- const boardRegistration = registerCodeModeExtensionTools(
57
- pi,
58
- () => [
59
- adaptToolForCodeMode(boardTool, {
60
- usage:
61
- 'await tools.board({ action: "help" }) // Shared discussion archive',
62
- }),
63
- ],
64
- { isActive: (ctx) => board.enabled(ctx) },
65
- );
66
- board.setToolRefresh(() => boardRegistration.refresh());
67
58
  pi.on("session_shutdown", () => {
68
59
  registration.unregister();
69
- boardRegistration.unregister();
70
60
  });
71
61
  return registration;
72
62
  } catch (error) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@howaboua/pi-shepherdr",
3
- "version": "0.2.15",
3
+ "version": "0.2.16",
4
4
  "description": "Persistent blocking and asynchronous Pi agents through Herdr.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -43,10 +43,10 @@
43
43
  "pack:dry": "npm pack --dry-run"
44
44
  },
45
45
  "peerDependencies": {
46
- "@howaboua/pi-codex-conversion": ">=3.0.47",
47
- "@earendil-works/pi-ai": ">=1.0.0",
48
- "@earendil-works/pi-coding-agent": ">=1.0.0",
49
- "@earendil-works/pi-tui": ">=1.0.0",
46
+ "@howaboua/pi-codex-conversion": ">=3.0.48",
47
+ "@earendil-works/pi-ai": ">=1.1.0",
48
+ "@earendil-works/pi-coding-agent": ">=1.1.0",
49
+ "@earendil-works/pi-tui": ">=1.1.0",
50
50
  "typebox": "*"
51
51
  },
52
52
  "peerDependenciesMeta": {
@@ -55,14 +55,14 @@
55
55
  }
56
56
  },
57
57
  "dependencies": {
58
- "unicode-case-folding": "1.1.2"
58
+ "@howaboua/pi-agent-board": "0.0.1"
59
59
  },
60
60
  "devDependencies": {
61
- "@howaboua/pi-codex-conversion": "3.0.47",
61
+ "@howaboua/pi-codex-conversion": "3.0.48",
62
62
  "@biomejs/biome": "^2.5.10",
63
- "@earendil-works/pi-ai": "1.0.4",
64
- "@earendil-works/pi-coding-agent": "1.0.4",
65
- "@earendil-works/pi-tui": "1.0.4",
63
+ "@earendil-works/pi-ai": "1.1.0",
64
+ "@earendil-works/pi-coding-agent": "1.1.0",
65
+ "@earendil-works/pi-tui": "1.1.0",
66
66
  "@types/node": "^26.2.0",
67
67
  "typebox": "1.3.18",
68
68
  "typescript": "^7.0.2"
@@ -73,7 +73,7 @@
73
73
  ]
74
74
  },
75
75
  "engines": {
76
- "node": ">=20.6.0"
76
+ "node": ">=22.18.0"
77
77
  },
78
78
  "main": "index.ts",
79
79
  "exports": "./index.ts",
@@ -8,6 +8,7 @@ const ACTIONS = [
8
8
  "help",
9
9
  "list",
10
10
  "find",
11
+ "focus",
11
12
  "spawn",
12
13
  "watch",
13
14
  "unwatch",
@@ -26,6 +27,7 @@ const ACTION_FIELDS: Record<(typeof ACTIONS)[number], ReadonlySet<string>> = {
26
27
  help: new Set(["action"]),
27
28
  list: new Set(["action", "machine"]),
28
29
  find: new Set(["action", "machine", "query", "status"]),
30
+ focus: new Set(["action", "machine", "target", "voice", "handoff"]),
29
31
  spawn: new Set([
30
32
  "action",
31
33
  "machine",
@@ -39,6 +41,7 @@ const ACTION_FIELDS: Record<(typeof ACTIONS)[number], ReadonlySet<string>> = {
39
41
  "message",
40
42
  "base",
41
43
  "blocking",
44
+ "board_thread_id",
42
45
  ]),
43
46
  watch: new Set(["action", "machine", "target"]),
44
47
  unwatch: new Set(["action", "machine", "target"]),
@@ -63,6 +66,8 @@ const AgentsRequest = Type.Object(
63
66
  {
64
67
  action: StringEnum(ACTIONS),
65
68
  machine: Type.Optional(Type.String()),
69
+ voice: Type.Optional(Type.Boolean()),
70
+ handoff: Type.Optional(Type.String()),
66
71
  target: Type.Optional(
67
72
  Type.String({ description: "Agent name or pane ID" }),
68
73
  ),
@@ -89,6 +94,7 @@ const AgentsRequest = Type.Object(
89
94
  ),
90
95
  context: Type.Optional(Type.Boolean()),
91
96
  board: Type.Optional(Type.Boolean()),
97
+ board_thread_id: Type.Optional(Type.String({ minLength: 1 })),
92
98
  query: Type.Optional(Type.String()),
93
99
  status: Type.Optional(StringEnum(STATUSES)),
94
100
  source: Type.Optional(StringEnum(READ_SOURCES)),
@@ -99,7 +105,9 @@ const AgentsRequest = Type.Object(
99
105
  { additionalProperties: false },
100
106
  );
101
107
 
102
- export const AgentsParameters = Type.Object({ action: StringEnum(ACTIONS) });
108
+ export const AgentsParameters = Type.Object({
109
+ action: Type.Optional(StringEnum(ACTIONS)),
110
+ });
103
111
 
104
112
  export type AgentsParams = Static<typeof AgentsRequest>;
105
113
  export type AgentsToolParams = Static<typeof AgentsParameters>;
@@ -113,6 +121,7 @@ export function requiredAgentField(
113
121
  }
114
122
 
115
123
  export function parseAgentsRequest(input: unknown): AgentsParams {
124
+ if (input === undefined) return { action: "help" };
116
125
  let value = input;
117
126
  if (typeof input === "string") {
118
127
  const text = input.trim();
@@ -130,6 +139,7 @@ export function parseAgentsRequest(input: unknown): AgentsParams {
130
139
  if (typeof value !== "object" || value === null || Array.isArray(value)) {
131
140
  throw new Error("agents request must be a JSON object");
132
141
  }
142
+ if (Object.keys(value).length === 0) return { action: "help" };
133
143
  const action = "action" in value ? value.action : undefined;
134
144
  if (typeof action !== "string" || !Object.hasOwn(ACTION_FIELDS, action)) {
135
145
  throw new Error(`agents action must be one of: ${ACTIONS.join(", ")}`);
@@ -23,15 +23,19 @@ function describeProfiles(profiles: Map<string, AgentProfile>) {
23
23
  );
24
24
  }
25
25
 
26
- export async function agentsHelp(): Promise<Record<string, unknown>> {
26
+ export async function agentsHelp(
27
+ boardAvailable = false,
28
+ ): Promise<Record<string, unknown>> {
27
29
  const profiles = await loadAgentProfiles();
28
30
  return {
29
31
  actions: {
30
32
  help: "",
31
33
  list: "machine?",
32
34
  find: "query? status? machine?",
35
+ focus: "target machine? voice? handoff?",
33
36
  spawn:
34
- "agent_type label message name? machine? placement? workspace? pane? cwd? base? blocking?",
37
+ "agent_type label message name? machine? placement? workspace? pane? cwd? base? blocking?" +
38
+ (boardAvailable ? " board_thread_id?" : ""),
35
39
  watch: "target machine?",
36
40
  unwatch: "target machine?",
37
41
  send: "target message machine?",
@@ -44,14 +48,24 @@ export async function agentsHelp(): Promise<Record<string, unknown>> {
44
48
  rules: {
45
49
  machine:
46
50
  "Omit for local (host running Pi); list/find omit for all machines. Remote: profile ID from list, not label/hostname",
47
- target: "Use spawn/find target exactly",
51
+ target:
52
+ "Use spawn/find target exactly; /root selects this family's live root",
48
53
  label: "2-3 words; tab/session",
54
+ ...(boardAvailable
55
+ ? {
56
+ board_thread_id:
57
+ "Existing shared-board thread; child receives a read reference",
58
+ }
59
+ : {}),
49
60
  answers: "[{selections?:string[],other?:string,comment?:string}]",
50
61
  ask_id: "Exact pending Ask ID",
51
- send: "Only needed input or work changes; wakes idle agents, no wait/watch. Never wake finished workers to acknowledge completion or announce closure; close finished panes silently with host controls",
62
+ send: "Only needed input or work changes; wakes idle agents, no wait/watch. Close finished workers with /quit, not acknowledgement messages",
52
63
  assign: "Delegate a task to an existing agent",
53
- attach:
54
- "Idle target; context/board booleans choose shared access and board membership independently; no task/watch",
64
+ focus:
65
+ "Select a running session; passive arrival with return call, no task/watch. voice defaults false; true carries the active microphone asynchronously. handoff adds context. Remote focus selects the target's Herdr session, not the client's machine",
66
+ attach: boardAvailable
67
+ ? "Idle target; context/board booleans choose shared access and board membership independently; no task/watch"
68
+ : "Idle target; context shares notes/history; use board:false while shared boards are unavailable; no task/watch",
55
69
  detach:
56
70
  "Stop selected membership; retain counterpart checkpoints read-only; idle target",
57
71
  blocking:
@@ -63,7 +77,7 @@ export async function agentsHelp(): Promise<Record<string, unknown>> {
63
77
  prompt:
64
78
  "Only task + inaccessible context; no method/evidence/reporting boilerplate",
65
79
  slash:
66
- "Leading / uses target Pi commands/skills/templates; extension commands are submission-only, even with assign/spawn; TUI-only commands unavailable",
80
+ "Leading / routes target commands/skills/templates. Commands skip task waiting, even with assign/spawn; blocked commands return available choices. /quit shuts down Pi and closes its pane",
67
81
  reuse:
68
82
  "Reuse only same investigation; reviews independent; new scope = new agent",
69
83
  ...(profiles.has("general")