@howaboua/pi-shepherdr 0.2.24 → 0.2.26

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 (85) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +20 -12
  3. package/index.ts +2 -2
  4. package/package.json +10 -11
  5. package/src/agent-identity.ts +75 -0
  6. package/src/agents-contract.ts +20 -12
  7. package/src/agents-discovery.ts +79 -34
  8. package/src/agents-focus.ts +15 -9
  9. package/src/agents-spawn.ts +25 -7
  10. package/src/agents-tool.ts +35 -7
  11. package/src/agents-work.ts +2 -2
  12. package/src/attachment-notes.ts +25 -24
  13. package/src/attachment-protocol.ts +35 -15
  14. package/src/attachment-routing.ts +28 -24
  15. package/src/attachment-target.ts +58 -19
  16. package/src/attachment.ts +13 -17
  17. package/src/board/host.ts +19 -20
  18. package/src/board/membership.ts +49 -30
  19. package/src/close-idle.ts +89 -0
  20. package/src/context-routing.ts +196 -0
  21. package/src/control-panel/index.ts +3 -1
  22. package/src/control-panel/items.ts +14 -2
  23. package/src/control-panel/view.ts +6 -2
  24. package/src/controller.ts +11 -2
  25. package/src/core/AGENTS.md +5 -0
  26. package/src/core/backend.ts +266 -0
  27. package/src/core/client.ts +249 -0
  28. package/src/core/context-relay.mjs +111 -0
  29. package/src/core/focus-channel-helper.mjs +165 -0
  30. package/src/core/focus-channel-stream.ts +140 -0
  31. package/src/core/focus-channel-wire.mjs +160 -0
  32. package/src/core/focus-channel.ts +213 -0
  33. package/src/core/focus-window.ts +192 -0
  34. package/src/core/pi-executable.mjs +34 -0
  35. package/src/core/protocol.ts +116 -0
  36. package/src/core/registration.ts +51 -0
  37. package/src/core/remote-endpoint.ts +119 -0
  38. package/src/core/remote-exec.ts +122 -0
  39. package/src/core/remote-helper.mjs +244 -0
  40. package/src/core/remote-reader.ts +67 -0
  41. package/src/core/remote-relay.ts +191 -0
  42. package/src/core/request.ts +124 -0
  43. package/src/core/spawn.ts +177 -0
  44. package/src/core/status.ts +68 -0
  45. package/src/core/terminal.ts +103 -0
  46. package/src/fleet/catalog.ts +83 -0
  47. package/src/fleet/connection.ts +111 -0
  48. package/src/fleet/index.ts +161 -122
  49. package/src/fleet/inspection.ts +19 -1
  50. package/src/fleet/machine.ts +3 -0
  51. package/src/fleet/monitor.ts +18 -4
  52. package/src/fleet/persistence.ts +26 -3
  53. package/src/fleet/setup.ts +54 -13
  54. package/src/herdr.ts +25 -5
  55. package/src/launch-contract.ts +48 -0
  56. package/src/launch-location.ts +151 -0
  57. package/src/launch.ts +30 -183
  58. package/src/messages/attribution.ts +15 -6
  59. package/src/messages/events.ts +10 -4
  60. package/src/messages/focus.ts +11 -2
  61. package/src/messages/guidance.ts +22 -16
  62. package/src/monitor-extension-messages.ts +9 -2
  63. package/src/monitor-record.ts +13 -6
  64. package/src/monitor-state.ts +18 -4
  65. package/src/monitor.ts +31 -0
  66. package/src/peer-commands.ts +11 -0
  67. package/src/peer-inbox-delivery.ts +171 -0
  68. package/src/peer-inbox-focus.ts +113 -0
  69. package/src/peer-inbox.ts +126 -208
  70. package/src/remote/deployment.ts +1 -1
  71. package/src/remote/shepherdr-checkpoints.mjs +20 -2
  72. package/src/remote/shepherdr-context.mjs +15 -3
  73. package/src/remote/shepherdr-peer.mjs +18 -5
  74. package/src/remote/shepherdr-session.mjs +9 -2
  75. package/src/remote/shepherdr.mjs +1 -1
  76. package/src/settlement/collector.ts +2 -2
  77. package/src/settlement/index.ts +12 -0
  78. package/src/shared-context-host.ts +7 -18
  79. package/src/shared-context.ts +139 -12
  80. package/src/spawn-context.ts +10 -5
  81. package/src/spawn-ownership.ts +91 -0
  82. package/src/types.ts +10 -5
  83. package/src/worker-ownership.ts +92 -0
  84. package/src/worker-service.ts +13 -82
  85. package/changelog.ts +0 -337
package/CHANGELOG.md CHANGED
@@ -1,5 +1,31 @@
1
1
  # @howaboua/pi-shepherdr
2
2
 
3
+ ## 0.2.26
4
+
5
+ - Requires Pi 1.5 or newer.
6
+
7
+ Update and restart controllers and workers together for shared Notes and boards.
8
+ - `spawn` and `assign` now return after task submission by default. Set `blocking: true` to wait for the result. A profile's `blocking` setting still overrides `spawn`.
9
+ - Agent references now use Pi session IDs across delegation, Notes and boards. Spawn returns one `agent` reference and sharing flags instead of separate context and board references.
10
+ - Attached Notes reads keep alias paths and read-only warnings consistent across native, Code and Notebook results.
11
+ - Rollover briefings now retain initial scope and the latest instruction without accumulating every message. Full messages remain in session history.
12
+ - Fixed repeated writes of unchanged agent snapshots.
13
+ - Closed workers no longer trigger a misleading notices-unavailable reconnect warning.
14
+ - Removed custom changelog suppression. Updates use Pi's native notices and `collapseChangelog`.
15
+
16
+ ## 0.2.25
17
+
18
+ - When switching from the older Herdr TUI or another Core instance, reselect local watches.
19
+ - Added Herdr Core and Herdr app support for local and remote delegation, focus, voice transfers, shared Notes and boards, including Windows hosts.
20
+ - Added Core session discovery by terminal title, with spaces, hyphens and underscores treated alike.
21
+ - Added `/herdr close-idle` to close idle children spawned by the current session branch, leaving attached and busy sessions open.
22
+ - Spawn results now return `contextAgent` and `boardAgent` inside `sharing` instead of at the top level. The agent `target` is unchanged.
23
+ - Reduced resume delays in sessions with many delegated agents, including closed children.
24
+ - Remote sharing helpers now start only when sharing is used or restored, avoiding idle polling on unrelated machines.
25
+ - Fixed intermediate tool calls being reported as completed agent work.
26
+ - Agent guidance now distinguishes automatic background reports from blocking calls that must be awaited.
27
+ - Agent tool declarations now accept action fields discovered through help, including in native codemode.
28
+
3
29
  ## 0.2.24
4
30
 
5
31
  - - **BREAKING CHANGE:** Shared notes and history now use Notes instead of PCC. Install `@howaboua/pi-notes-compaction` and update participating hosts together to retain sharing. PCC remains optional for native parent linkage and cache affinity. Ordinary agent management requires neither extension.
package/README.md CHANGED
@@ -14,7 +14,9 @@ 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.2.0 or newer, Node.js 22.18 or newer, Herdr 0.9 or newer and the Herdr Pi integration:
17
+ Requires Pi 1.2.0 or newer and Node.js 22.18 or newer. Run Pi inside Herdr Core 0.1.14 or newer, or the Herdr app, to use the new Herdr backend. Shepherdr reports Pi status to Core and discovers other Pi sessions with Shepherdr installed.
18
+
19
+ For the older Herdr TUI, install its Pi integration:
18
20
 
19
21
  ```bash
20
22
  herdr integration install pi
@@ -24,6 +26,10 @@ Do not load Pi Codex's example `agents.toml` custom tool alongside Shepherdr; th
24
26
 
25
27
  Pi Codex is optional. Without it, Shepherdr remains a normal Pi extension.
26
28
 
29
+ Herdr Core workers start as background terminals by default. Explicit new-tab and new-workspace placements appear when an app connected to that Core adopts them. Focus requires a Herdr app window connected to the target Core. Existing Herdr TUI sessions cannot be moved into Core.
30
+
31
+ For remote Core workers, add machines with `hc machine add` and install Node.js, Herdr Core and Shepherdr on each target. Delegation, supervision, shared context and boards work across those machines.
32
+
27
33
  ## Control panel
28
34
 
29
35
  The agent tool is always available in Pi, Code Mode and Notebook Mode. Run Pi inside Herdr to connect the fleet and start monitoring automatically. Open the control panel with:
@@ -32,17 +38,19 @@ The agent tool is always available in Pi, Code Mode and Notebook Mode. Run Pi in
32
38
  /herdr
33
39
  ```
34
40
 
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.
41
+ **Settings** contains orchestration preferences, agent command guidance and the global config path. **Status** shows machine connections and reconnect actions. **Connections** adds SSH machines for the older Herdr TUI. Agents handle discovery, attachment and detachment through the `agents` tool, not this panel.
42
+
43
+ Run `/herdr close-idle` to close idle child sessions spawned by the current session branch. Attached or assigned existing sessions are never included. Busy, blocked, unavailable or unverified children stay open. Children spawned before this feature was installed have no ownership receipt and stay open too. Pi shuts down gracefully before its pane closes.
36
44
 
37
45
  `/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
46
 
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.
47
+ For the older Herdr TUI, add a machine by entering 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
48
 
41
- Shepherdr connects enabled profiles at session startup. **Status** refreshes the catalog and retries failed connections or incomplete monitoring without dropping working connections. A catalog refresh stops watches for disabled or removed profiles without stopping remote agents.
49
+ With the older TUI, Shepherdr connects enabled profiles at session startup. **Status** refreshes the catalog and retries failed connections or incomplete monitoring without dropping working connections. A catalog refresh stops watches for disabled or removed profiles without stopping remote agents.
42
50
 
43
51
  Profiles belong to the host running Pi, not the machine displaying its terminal. Omit `machine` for local agent calls. `list` and `find` search all machines unless filtered. Explicit `local` also means the host running Pi. For remote calls, use the opaque profile ID returned by `list`, not its label or hostname. Renaming a profile changes its label, not its routing identity.
44
52
 
45
- Remote machines connect over noninteractive SSH. The target needs `node` on its SSH PATH, Herdr 0.9 or newer, the Herdr Pi integration and a running Herdr session. Shepherdr installs managed transport helpers under `~/.pi/agent` on each remote, runs them only for the connection lifetime and leaves no remote daemon behind. Herdr's multi-machine UI does not expose a cross-machine automation socket, so Shepherdr still owns its remote transport and Pi transcript reads.
53
+ With the older TUI, remote machines connect over noninteractive SSH. The target needs `node` on its SSH PATH, Herdr 0.9 or newer, the Herdr Pi integration and a running Herdr session. Shepherdr installs managed transport helpers under `~/.pi/agent` on each remote, runs them only for the connection lifetime and leaves no remote daemon behind. Herdr's multi-machine UI does not expose a cross-machine automation socket, so Shepherdr still owns its remote transport and Pi transcript reads.
46
54
 
47
55
  ### Migrating from separate Shepherdr machines
48
56
 
@@ -67,7 +75,7 @@ Call `agents` with `{}` before first use, alone, then send flat request objects
67
75
  | `watch` | Push future settlement from an existing Pi agent |
68
76
  | `unwatch` | Stop reporting an agent |
69
77
 
70
- `spawn` and `assign` block by default. Set `blocking: false` when the controller should continue other work immediately. A profile's `blocking` setting overrides the call for `spawn`. Task completion and blockage are then delivered automatically.
78
+ `spawn` and `assign` return once the task is submitted by default, so consecutive calls can dispatch work to several agents without waiting for the first task to finish. Task completion and blockage arrive automatically. Set `blocking: true` when the call must wait for its result. A profile's `blocking` setting still overrides the call for `spawn`.
71
79
 
72
80
  Blocking calls can run in parallel. In Code or Notebook, use `await Promise.allSettled([...])` to start independent calls together and wait for every result, including failures. Keep blocking enabled when the controller must wait, such as for parallel reviews. Consecutive `await` calls still run one after another; `Promise.all` can exit early on failure.
73
81
 
@@ -75,19 +83,19 @@ Nonblocking extension messages notify the controller once; blocking messages arr
75
83
 
76
84
  `reply` returns the extension's receipt after semantic delivery. Blocking messages also wait for resumed work unless another call already owns that wait. Nonblocking replies do not wait for the worker's task to finish. Shepherdr forwards strings unchanged. The producing extension owns their meaning, validation and retries.
77
85
 
78
- Use `send` for messages and work updates without waiting or adding supervision. Use `assign` when you need the result: it also accepts updates to running work, sharing that work's pending result rather than replacing it. If another call is already waiting, the update returns after submission and leaves that waiter intact. Close finished workers silently instead of waking them with completion acknowledgements or shutdown notices.
86
+ Use `send` for messages and work updates without adding supervision. Use `assign` to delegate work and receive its monitored result, automatically or through an explicit blocking call. It also accepts updates to running work, sharing that work's pending result rather than replacing it. If another call is already waiting, the update returns after submission and leaves that waiter intact. Close finished workers silently instead of waking them with completion acknowledgements or shutdown notices.
79
87
 
80
88
  Delegation and explicit `watch` keep reporting subsequent work until `unwatch` or the agent's pane closes. Finishing or failing a task clears that task, not its watch. Follow-up messages through `send` retain completion reporting without replacing the task.
81
89
 
82
- Every `spawn` needs an `agent_type` and a concise `label`. The label names both the Herdr tab and Pi session; the routing `name` remains optional and is derived from it when omitted.
90
+ Every `spawn` needs an `agent_type` and a concise `label`. The label names the Pi session, and also names the tab in the older Herdr TUI. The routing `name` remains optional and is derived from the label when omitted.
83
91
 
84
92
  Cancelling a blocking call does not kill its worker. The waiter detaches and the eventual result returns through normal asynchronous delivery.
85
93
 
86
94
  After Pi compaction or Notes context rollover, the controller receives its supervised agents' exact machine and target, submitted tasks and follow-up instructions, and last observed status, including settled and blocked workers. Read a target for its reply or pending extension messages. This reminder does not start a turn or bypass normal turn preparation.
87
95
 
88
- Prompts sent through `agents` identify peer messages versus delegated tasks and include the sender's host, session, workspace, tab and pane identity, with current names. Reports include source workspace and tab names too. Raw `herdr agent prompt` calls bypass this attribution. These are runtime locations, not the desktop window showing a pane.
96
+ Prompts sent through `agents` identify peer messages versus delegated tasks and include the sender's host and session identity. The older TUI also includes workspace, tab and pane details. Core reports use terminal addresses and include app location IDs when available. These are runtime locations, not the desktop window showing a pane.
89
97
 
90
- 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.
98
+ 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. On the older TUI, raw `herdr agent prompt` still uses terminal input and does not provide this protection.
91
99
 
92
100
  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.
93
101
 
@@ -242,14 +250,14 @@ That directory is authoritative after initialization. Edit a profile to change i
242
250
  `prompt` is read as system-prompt text. An optional `prepare` module may export `prepare({ cwd, message, base, local })` and return the worker message. Preparation runs on the controlling machine before dispatch; `local` says whether that machine also hosts the worker.
243
251
 
244
252
  Optional profile settings:
245
- - `blocking`: `true` forces blocking spawns, `false` forces asynchronous spawns. Omission respects the call's `blocking` value, which defaults to `true`. This does not affect `assign` to existing agents.
253
+ - `blocking`: `true` forces blocking spawns, `false` forces asynchronous spawns. Omission respects the call's `blocking` value, which defaults to `false`. This does not affect `assign` to existing agents.
246
254
  - `share_context`: `false` opts new spawns out of shared notes and history. Omission or `true` follows the controller setting.
247
255
 
248
256
  `help` and `list` expose each profile's description and configured settings. Profile names carry no blocking policy. The bundled reviewer profile sets `"blocking": true`; change it to `false` to force asynchronous review, or remove it to choose per call. Existing installed profiles are never overwritten. An existing reviewer without `blocking` now respects the call like any other profile.
249
257
 
250
258
  ## Advanced Herdr control
251
259
 
252
- Ordinary delegation stays inside `agents`. For workspace, tab, pane, process, focus, layout or raw-terminal operations, run `herdr --skill` and follow the installed Herdr skill. Shepherdr does not duplicate those controls.
260
+ Ordinary delegation stays inside `agents`. For terminal operations on Core, run `hc --skill`. For window operations, use `herdr-app --skill`. The older TUI provides its own guide through `herdr --skill`.
253
261
 
254
262
  Herdr still owns terminals, layout, agent processes and restored sessions. Shepherdr owns event subscriptions, remote routing, the fleet widget and purple settlement messages.
255
263
 
package/index.ts CHANGED
@@ -1,10 +1,10 @@
1
1
  import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
- import registerPackageChangelog from "./changelog.js";
3
2
  import { isBlockingAgentsCall } from "./src/agents-contract.js";
4
3
  import { acceptFocus, registerFocusArrivals } from "./src/agents-focus.js";
5
4
  import { createAgentsTool } from "./src/agents-tool.js";
6
5
  import { AgentBoard } from "./src/board/host.js";
7
6
  import { registerAgentController } from "./src/controller.js";
7
+ import { registerCoreStatus } from "./src/core/status.js";
8
8
  import { registerDeveloperDelivery } from "./src/delivery.js";
9
9
  import { AgentFleet } from "./src/fleet/index.js";
10
10
  import { registerAgentEventRenderer } from "./src/messages/render.js";
@@ -23,8 +23,8 @@ const CODE_MODE_MODULE = `${CODE_MODE_PACKAGE}/code-mode`;
23
23
  export default async function shepherdrExtension(
24
24
  pi: ExtensionAPI,
25
25
  ): Promise<void> {
26
+ registerCoreStatus(pi);
26
27
  const workerRole = registerWorkerRole(pi);
27
- registerPackageChangelog(pi);
28
28
 
29
29
  await installAgentProfiles();
30
30
  registerProfilePrompt(pi);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@howaboua/pi-shepherdr",
3
- "version": "0.2.24",
3
+ "version": "0.2.26",
4
4
  "description": "Persistent blocking and asynchronous Pi agents through Herdr.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -31,7 +31,6 @@
31
31
  "LICENSE",
32
32
  "tsconfig.json",
33
33
  "biome.json",
34
- "changelog.ts",
35
34
  "CHANGELOG.md"
36
35
  ],
37
36
  "scripts": {
@@ -43,10 +42,10 @@
43
42
  "pack:dry": "npm pack --dry-run"
44
43
  },
45
44
  "peerDependencies": {
46
- "@howaboua/pi-notes-compaction": ">=0.0.10",
47
- "@howaboua/pi-codex-conversion": ">=4.0.5",
45
+ "@howaboua/pi-notes-compaction": ">=0.0.14",
46
+ "@howaboua/pi-codex-conversion": ">=4.0.8",
48
47
  "@earendil-works/pi-ai": ">=1.1.0",
49
- "@earendil-works/pi-coding-agent": ">=1.2.0",
48
+ "@earendil-works/pi-coding-agent": ">=1.5.0",
50
49
  "@earendil-works/pi-tui": ">=1.1.0",
51
50
  "typebox": "*"
52
51
  },
@@ -59,15 +58,15 @@
59
58
  }
60
59
  },
61
60
  "dependencies": {
62
- "@howaboua/pi-agent-board": "0.0.4"
61
+ "@howaboua/pi-agent-board": "0.0.5"
63
62
  },
64
63
  "devDependencies": {
65
- "@howaboua/pi-notes-compaction": "0.0.10",
66
- "@howaboua/pi-codex-conversion": "4.0.5",
64
+ "@howaboua/pi-notes-compaction": "0.0.14",
65
+ "@howaboua/pi-codex-conversion": "4.0.8",
67
66
  "@biomejs/biome": "^2.6.3",
68
- "@earendil-works/pi-ai": "1.4.0",
69
- "@earendil-works/pi-coding-agent": "1.4.0",
70
- "@earendil-works/pi-tui": "1.4.0",
67
+ "@earendil-works/pi-ai": "1.5.0",
68
+ "@earendil-works/pi-coding-agent": "1.5.0",
69
+ "@earendil-works/pi-tui": "1.5.0",
71
70
  "@types/node": "^26.6.5",
72
71
  "typebox": "1.4.3",
73
72
  "typescript": "^7.0.2"
@@ -1,5 +1,80 @@
1
+ import type { AgentFleet } from "./fleet/index.js";
2
+ import { sessionPath } from "./herdr.js";
3
+ import type { HerdrConnection } from "./herdr-client.js";
4
+ import { sessionContextPath } from "./remote/shepherdr-context.mjs";
1
5
  import type { PaneInfo } from "./types.js";
2
6
 
7
+ /** Read the live Pi owner, never infer identity from a filename or terminal ID. */
8
+ export async function nativeAgentName(
9
+ client: HerdrConnection,
10
+ panel: PaneInfo,
11
+ signal?: AbortSignal,
12
+ ): Promise<string> {
13
+ const file = sessionPath(panel);
14
+ if (!file) throw new Error("Agent has no saved Pi session");
15
+ const value = await client.requestContext(
16
+ sessionContextPath(file),
17
+ { operation: "agent-identity" },
18
+ signal,
19
+ );
20
+ if (
21
+ !value ||
22
+ typeof value !== "object" ||
23
+ !("sessionId" in value) ||
24
+ typeof value.sessionId !== "string" ||
25
+ !value.sessionId ||
26
+ /[/\\\u0000]/.test(value.sessionId)
27
+ )
28
+ throw new Error(
29
+ "Agent identity unavailable; update and reload Shepherdr on the target",
30
+ );
31
+ if (value.sessionId === "root")
32
+ throw new Error(
33
+ "Pi session ID root conflicts with the legacy /root reference; start a session with another ID",
34
+ );
35
+ return `/${value.sessionId}`;
36
+ }
37
+
38
+ export async function resolveNativeAgent(
39
+ fleet: AgentFleet,
40
+ name: string,
41
+ machine?: string,
42
+ signal?: AbortSignal,
43
+ ) {
44
+ const snapshots = await fleet.snapshots(machine);
45
+ const candidates = snapshots.flatMap((entry) => {
46
+ if (!entry.snapshot) return [];
47
+ const runtime = fleet.connected(entry.id);
48
+ return entry.snapshot.agents
49
+ .filter((panel) => panel.agent === "pi" && sessionPath(panel))
50
+ .map((panel) => ({ runtime, panel }));
51
+ });
52
+ const found = await Promise.all(
53
+ candidates.map(async (candidate) => {
54
+ try {
55
+ return (await nativeAgentName(
56
+ candidate.runtime.client,
57
+ candidate.panel,
58
+ signal,
59
+ )) === name
60
+ ? candidate
61
+ : undefined;
62
+ } catch {
63
+ signal?.throwIfAborted();
64
+ return undefined;
65
+ }
66
+ }),
67
+ );
68
+ const matches = found.filter((candidate) => candidate !== undefined);
69
+ if (matches.length !== 1)
70
+ throw new Error(
71
+ matches.length
72
+ ? `Multiple live agents use ${name}; select an exact terminal target and machine`
73
+ : `No reachable live agent ${name}; use find for an exact target or reconnect its machine`,
74
+ );
75
+ return matches[0]!;
76
+ }
77
+
3
78
  export function sameAgentIdentity(
4
79
  expected: PaneInfo,
5
80
  current: PaneInfo,
@@ -1,9 +1,12 @@
1
- import { StringEnum, Type } from "@earendil-works/pi-ai";
2
- import type { Static } from "typebox";
1
+ import { type Static, Type } from "typebox";
3
2
  import { Check } from "typebox/value";
4
3
  import { START_PLACEMENTS } from "./launch.js";
5
4
  import { loadAgentProfileBlocking } from "./profiles.js";
6
5
 
6
+ function StringEnum<T extends readonly string[]>(values: T) {
7
+ return Type.Unsafe<T[number]>({ type: "string", enum: values });
8
+ }
9
+
7
10
  const ACTIONS = [
8
11
  "help",
9
12
  "list",
@@ -19,7 +22,6 @@ const ACTIONS = [
19
22
  "read",
20
23
  "reply",
21
24
  ] as const;
22
- const BLOCKING_ACTIONS = new Set<string>(["spawn", "assign", "reply"]);
23
25
  export const READ_SOURCES = ["latest", "visible", "recent"] as const;
24
26
  const STATUSES = ["idle", "working", "blocked", "done", "unknown"] as const;
25
27
 
@@ -81,7 +83,7 @@ const AgentsRequest = Type.Object(
81
83
  blocking: Type.Optional(
82
84
  Type.Boolean({
83
85
  description:
84
- "Delegation only; profile policy overrides spawn; otherwise defaults true",
86
+ "Wait for delegated result; profile policy overrides spawn; default false",
85
87
  }),
86
88
  ),
87
89
  context: Type.Optional(Type.Boolean()),
@@ -97,12 +99,15 @@ const AgentsRequest = Type.Object(
97
99
  { additionalProperties: false },
98
100
  );
99
101
 
100
- export const AgentsParameters = Type.Object({
101
- action: Type.Optional(StringEnum(ACTIONS)),
102
- commands: Type.Optional(Type.Literal(true)),
103
- target: Type.Optional(Type.String()),
104
- machine: Type.Optional(Type.String()),
105
- });
102
+ export const AgentsParameters = Type.Object(
103
+ {
104
+ action: Type.Optional(StringEnum(ACTIONS)),
105
+ commands: Type.Optional(Type.Literal(true)),
106
+ target: Type.Optional(Type.String()),
107
+ machine: Type.Optional(Type.String()),
108
+ },
109
+ { additionalProperties: true },
110
+ );
106
111
 
107
112
  export type AgentsParams = Static<typeof AgentsRequest>;
108
113
  export type AgentsToolParams = Static<typeof AgentsParameters>;
@@ -207,7 +212,10 @@ export function isBlockingAgentsCall(input: unknown): boolean {
207
212
  ),
208
213
  value.blocking,
209
214
  );
210
- return BLOCKING_ACTIONS.has(value.action) && value.blocking !== false;
215
+ return (
216
+ value.action === "reply" ||
217
+ (value.action === "assign" && value.blocking === true)
218
+ );
211
219
  } catch {
212
220
  return false;
213
221
  }
@@ -217,5 +225,5 @@ export function shouldBlockAgentSpawn(
217
225
  profileBlocking: boolean | undefined,
218
226
  blocking: boolean | undefined,
219
227
  ): boolean {
220
- return profileBlocking ?? blocking ?? true;
228
+ return profileBlocking ?? blocking ?? false;
221
229
  }
@@ -1,3 +1,4 @@
1
+ import { nativeAgentName } from "./agent-identity.js";
1
2
  import type { AgentsParams, READ_SOURCES } from "./agents-contract.js";
2
3
  import type { AgentFleet, ConnectedMachine } from "./fleet/index.js";
3
4
  import { type AgentProfile, loadAgentProfiles } from "./profiles.js";
@@ -26,6 +27,7 @@ function describeProfiles(profiles: Map<string, AgentProfile>) {
26
27
  export async function agentsHelp(
27
28
  boardAvailable = false,
28
29
  gpt = false,
30
+ core = false,
29
31
  ): Promise<Record<string, unknown>> {
30
32
  const profiles = await loadAgentProfiles();
31
33
  return {
@@ -57,11 +59,16 @@ export async function agentsHelp(
57
59
  ? "machine omitted=local Pi host; list/find omitted=all machines; remote=list profile ID, NOT label/hostname"
58
60
  : "Omit for local (host running Pi); list/find omit for all machines. Remote: profile ID from list, not label/hostname",
59
61
  target: gpt
60
- ? "spawn/find target EXACT; /root=this family live root"
61
- : "Use spawn/find target exactly; /root selects this family's live root",
62
- label: gpt
63
- ? "Short tab/session name; two words IF useful"
64
- : "Short tab/session name; prefer two words when useful",
62
+ ? "target=agent (same Notes/Board ID) or terminal target; /root=this family live root"
63
+ : "Use agent for the same identity as Notes/Board, or the terminal target; /root selects this family's live root",
64
+ label: core
65
+ ? "Short Pi session name; app tabs use default names"
66
+ : gpt
67
+ ? "Short tab/session name; two words IF useful"
68
+ : "Short tab/session name; prefer two words when useful",
69
+ placement: core
70
+ ? "terminal (default), new_tab, new_workspace; new_tab needs space ID"
71
+ : "new_tab, new_workspace, pane",
65
72
  ...(boardAvailable
66
73
  ? {
67
74
  board_thread_id: gpt
@@ -89,8 +96,8 @@ export async function agentsHelp(
89
96
  ? "Idle target; stop selected membership; counterpart checkpoints remain readonly"
90
97
  : "Stop selected membership; retain counterpart checkpoints read-only; idle target",
91
98
  blocking: gpt
92
- ? "spawn/assign default true; profile overrides spawn; JS parallel+wait: await Promise.allSettled; false ONLY if other work continues; completion/blockage AFTER reply; NO poll/sleep"
93
- : "spawn/assign default true; profile blocking overrides spawn. In JavaScript cells, use await Promise.allSettled for parallel calls that wait for every result, including failures. Use false only to continue other work; completion/blockage arrives after your reply. No polling or sleep waits",
99
+ ? "spawn/assign default false→dispatch then return; true→wait for result; profile overrides spawn. Parallel blocking calls: await Promise.allSettled. Background reports automatic→do other work/end turn, NO poll or await timers/extra Promises"
100
+ : "spawn/assign return after dispatch by default. Set blocking:true to wait for the result; profile blocking overrides spawn. Use await Promise.allSettled for parallel blocking calls, including failures. Background reports arrive automatically: do other work or end this turn, never poll or await timers or extra Promises for reports",
94
101
  share_context: gpt
95
102
  ? "Profile false→isolated notes/history; otherwise→controller sharing setting"
96
103
  : "Profile false isolates notes/history; otherwise follows controller sharing setting",
@@ -113,7 +120,9 @@ export async function agentsHelp(
113
120
  : {}),
114
121
  },
115
122
  profiles: describeProfiles(profiles),
116
- advanced: "herdr --skill: workspace/tab/pane/process/focus/layout/terminal",
123
+ advanced: core
124
+ ? "hc --skill: terminal processes and machines"
125
+ : "herdr --skill: workspace/tab/pane/process/focus/layout/terminal",
117
126
  };
118
127
  }
119
128
 
@@ -141,13 +150,23 @@ function compactAgent(
141
150
  machine,
142
151
  target: agent.pane_id,
143
152
  ...(agent.name ? { name: agent.name } : {}),
144
- ...(agent.label || names.panes.get(agent.pane_id)
145
- ? { label: agent.label ?? names.panes.get(agent.pane_id) }
153
+ ...(agent.label || names.panes.get(agent.pane_id) || agent.title
154
+ ? { label: agent.label || names.panes.get(agent.pane_id) || agent.title }
155
+ : {}),
156
+ ...(agent.title && (agent.label || names.panes.get(agent.pane_id))
157
+ ? { title: agent.title }
146
158
  : {}),
147
159
  status: agent.agent_status,
148
160
  cwd: agent.foreground_cwd ?? agent.cwd ?? null,
149
- workspace: names.workspaces.get(agent.workspace_id) ?? agent.workspace_id,
150
- tab: names.tabs.get(agent.tab_id) ?? agent.tab_id,
161
+ ...(agent.workspace_id
162
+ ? {
163
+ workspace:
164
+ names.workspaces.get(agent.workspace_id) ?? agent.workspace_id,
165
+ }
166
+ : {}),
167
+ ...(agent.tab_id
168
+ ? { tab: names.tabs.get(agent.tab_id) ?? agent.tab_id }
169
+ : {}),
151
170
  monitored,
152
171
  };
153
172
  }
@@ -159,11 +178,15 @@ function matchesAgent(
159
178
  ): boolean {
160
179
  if (status && agent["status"] !== status) return false;
161
180
  if (!query) return true;
162
- const haystack = Object.values(agent)
181
+ const normalize = (value: string) =>
182
+ value
183
+ .toLowerCase()
184
+ .replace(/[-_\s]+/g, " ")
185
+ .trim();
186
+ const needle = normalize(query);
187
+ return Object.values(agent)
163
188
  .filter((value) => typeof value === "string")
164
- .join("\n")
165
- .toLowerCase();
166
- return haystack.includes(query.toLowerCase());
189
+ .some((value) => normalize(value).includes(needle));
167
190
  }
168
191
 
169
192
  export async function listFleetAgents(
@@ -174,24 +197,46 @@ export async function listFleetAgents(
174
197
  loadAgentProfiles(),
175
198
  fleet.snapshots(params.machine),
176
199
  ]);
177
- const agents = machines.flatMap((machine) => {
178
- if (!machine.snapshot) return [];
179
- return machine.snapshot.agents
180
- .filter(
181
- (agent) =>
182
- agent.agent === "pi" &&
183
- (!machine.local || agent.pane_id !== process.env["HERDR_PANE_ID"]),
184
- )
185
- .map((agent) =>
186
- compactAgent(
187
- agent,
188
- machine.snapshot!,
189
- machine.id,
190
- machine.monitoredPaneIds?.has(agent.pane_id) ?? false,
191
- ),
192
- )
193
- .filter((agent) => matchesAgent(agent, params.query, params.status));
194
- });
200
+ const agents = (
201
+ await Promise.all(
202
+ machines.map(async (machine) => {
203
+ if (!machine.snapshot) return [];
204
+ const runtime = fleet.connected(machine.id);
205
+ return (
206
+ await Promise.all(
207
+ machine.snapshot.agents
208
+ .filter(
209
+ (agent) =>
210
+ agent.agent === "pi" &&
211
+ (!machine.local ||
212
+ agent.pane_id !==
213
+ (agent.backend === "core"
214
+ ? process.env["HC_TERMINAL_ID"]
215
+ : process.env["HERDR_PANE_ID"])),
216
+ )
217
+ .map(async (agent) => {
218
+ const result = compactAgent(
219
+ agent,
220
+ machine.snapshot!,
221
+ machine.id,
222
+ machine.monitoredPaneIds?.has(agent.pane_id) ?? false,
223
+ );
224
+ try {
225
+ result["agent"] = await nativeAgentName(
226
+ runtime.client,
227
+ agent,
228
+ );
229
+ } catch {
230
+ // Older or unavailable receivers remain addressable by their terminal.
231
+ result["identityUnavailable"] = true;
232
+ }
233
+ return result;
234
+ }),
235
+ )
236
+ ).filter((agent) => matchesAgent(agent, params.query, params.status));
237
+ }),
238
+ )
239
+ ).flat();
195
240
  const workspaces = machines.flatMap((machine) =>
196
241
  (machine.snapshot?.workspaces ?? []).map((workspace) => ({
197
242
  machine: machine.id,
@@ -52,7 +52,9 @@ export async function focusAgent(
52
52
  const request: FocusRequest = {
53
53
  source: {
54
54
  ...(await local.client.machineIdentity()),
55
- pane: source.pane_id,
55
+ ...(source.backend === "core"
56
+ ? { backend: "core" as const }
57
+ : { pane: source.pane_id }),
56
58
  terminal: source.terminal_id,
57
59
  sessionFile,
58
60
  },
@@ -106,13 +108,7 @@ export function readFocus(value: unknown): FocusRequest {
106
108
  )
107
109
  throw new Error("Invalid focus source");
108
110
  const source = value.source as Record<string, unknown>;
109
- for (const field of [
110
- "host",
111
- "session",
112
- "pane",
113
- "terminal",
114
- "sessionFile",
115
- ] as const) {
111
+ for (const field of ["host", "session", "terminal", "sessionFile"] as const) {
116
112
  if (
117
113
  !(field in source) ||
118
114
  typeof source[field] !== "string" ||
@@ -120,6 +116,13 @@ export function readFocus(value: unknown): FocusRequest {
120
116
  )
121
117
  throw new Error("Invalid focus source");
122
118
  }
119
+ if (source["backend"] !== undefined && source["backend"] !== "core")
120
+ throw new Error("Invalid focus backend");
121
+ if (
122
+ source["backend"] !== "core" &&
123
+ (typeof source["pane"] !== "string" || !source["pane"].trim())
124
+ )
125
+ throw new Error("Invalid focus pane");
123
126
  if ("handoff" in value && typeof value.handoff !== "string")
124
127
  throw new Error("Invalid focus handoff");
125
128
  if ("voice" in value && typeof value.voice !== "boolean")
@@ -150,7 +153,10 @@ export async function acceptFocus(
150
153
  const identity = await runtime.client.machineIdentity();
151
154
  if (identity.host !== source.host || identity.session !== source.session)
152
155
  continue;
153
- const agent = await getAgent(runtime.client, source.pane);
156
+ const agent = await getAgent(
157
+ runtime.client,
158
+ source.backend === "core" ? source.terminal : source.pane!,
159
+ );
154
160
  if (
155
161
  agent.agent === "pi" &&
156
162
  agent.terminal_id === source.terminal &&