@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.
- package/CHANGELOG.md +26 -0
- package/README.md +20 -12
- package/index.ts +2 -2
- package/package.json +10 -11
- package/src/agent-identity.ts +75 -0
- package/src/agents-contract.ts +20 -12
- package/src/agents-discovery.ts +79 -34
- package/src/agents-focus.ts +15 -9
- package/src/agents-spawn.ts +25 -7
- package/src/agents-tool.ts +35 -7
- package/src/agents-work.ts +2 -2
- package/src/attachment-notes.ts +25 -24
- package/src/attachment-protocol.ts +35 -15
- package/src/attachment-routing.ts +28 -24
- package/src/attachment-target.ts +58 -19
- package/src/attachment.ts +13 -17
- package/src/board/host.ts +19 -20
- package/src/board/membership.ts +49 -30
- package/src/close-idle.ts +89 -0
- package/src/context-routing.ts +196 -0
- package/src/control-panel/index.ts +3 -1
- package/src/control-panel/items.ts +14 -2
- package/src/control-panel/view.ts +6 -2
- package/src/controller.ts +11 -2
- package/src/core/AGENTS.md +5 -0
- package/src/core/backend.ts +266 -0
- package/src/core/client.ts +249 -0
- package/src/core/context-relay.mjs +111 -0
- package/src/core/focus-channel-helper.mjs +165 -0
- package/src/core/focus-channel-stream.ts +140 -0
- package/src/core/focus-channel-wire.mjs +160 -0
- package/src/core/focus-channel.ts +213 -0
- package/src/core/focus-window.ts +192 -0
- package/src/core/pi-executable.mjs +34 -0
- package/src/core/protocol.ts +116 -0
- package/src/core/registration.ts +51 -0
- package/src/core/remote-endpoint.ts +119 -0
- package/src/core/remote-exec.ts +122 -0
- package/src/core/remote-helper.mjs +244 -0
- package/src/core/remote-reader.ts +67 -0
- package/src/core/remote-relay.ts +191 -0
- package/src/core/request.ts +124 -0
- package/src/core/spawn.ts +177 -0
- package/src/core/status.ts +68 -0
- package/src/core/terminal.ts +103 -0
- package/src/fleet/catalog.ts +83 -0
- package/src/fleet/connection.ts +111 -0
- package/src/fleet/index.ts +161 -122
- package/src/fleet/inspection.ts +19 -1
- package/src/fleet/machine.ts +3 -0
- package/src/fleet/monitor.ts +18 -4
- package/src/fleet/persistence.ts +26 -3
- package/src/fleet/setup.ts +54 -13
- package/src/herdr.ts +25 -5
- package/src/launch-contract.ts +48 -0
- package/src/launch-location.ts +151 -0
- package/src/launch.ts +30 -183
- package/src/messages/attribution.ts +15 -6
- package/src/messages/events.ts +10 -4
- package/src/messages/focus.ts +11 -2
- package/src/messages/guidance.ts +22 -16
- package/src/monitor-extension-messages.ts +9 -2
- package/src/monitor-record.ts +13 -6
- package/src/monitor-state.ts +18 -4
- package/src/monitor.ts +31 -0
- package/src/peer-commands.ts +11 -0
- package/src/peer-inbox-delivery.ts +171 -0
- package/src/peer-inbox-focus.ts +113 -0
- package/src/peer-inbox.ts +126 -208
- package/src/remote/deployment.ts +1 -1
- package/src/remote/shepherdr-checkpoints.mjs +20 -2
- package/src/remote/shepherdr-context.mjs +15 -3
- package/src/remote/shepherdr-peer.mjs +18 -5
- package/src/remote/shepherdr-session.mjs +9 -2
- package/src/remote/shepherdr.mjs +1 -1
- package/src/settlement/collector.ts +2 -2
- package/src/settlement/index.ts +12 -0
- package/src/shared-context-host.ts +7 -18
- package/src/shared-context.ts +139 -12
- package/src/spawn-context.ts +10 -5
- package/src/spawn-ownership.ts +91 -0
- package/src/types.ts +10 -5
- package/src/worker-ownership.ts +92 -0
- package/src/worker-service.ts +13 -82
- 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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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`
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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 `
|
|
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
|
|
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.
|
|
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.
|
|
47
|
-
"@howaboua/pi-codex-conversion": ">=4.0.
|
|
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.
|
|
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.
|
|
61
|
+
"@howaboua/pi-agent-board": "0.0.5"
|
|
63
62
|
},
|
|
64
63
|
"devDependencies": {
|
|
65
|
-
"@howaboua/pi-notes-compaction": "0.0.
|
|
66
|
-
"@howaboua/pi-codex-conversion": "4.0.
|
|
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.
|
|
69
|
-
"@earendil-works/pi-coding-agent": "1.
|
|
70
|
-
"@earendil-works/pi-tui": "1.
|
|
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"
|
package/src/agent-identity.ts
CHANGED
|
@@ -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,
|
package/src/agents-contract.ts
CHANGED
|
@@ -1,9 +1,12 @@
|
|
|
1
|
-
import {
|
|
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
|
-
"
|
|
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
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
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
|
|
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 ??
|
|
228
|
+
return profileBlocking ?? blocking ?? false;
|
|
221
229
|
}
|
package/src/agents-discovery.ts
CHANGED
|
@@ -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
|
-
? "
|
|
61
|
-
: "Use
|
|
62
|
-
label:
|
|
63
|
-
? "Short
|
|
64
|
-
:
|
|
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
|
|
93
|
-
: "spawn/assign default true; profile blocking overrides spawn.
|
|
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:
|
|
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
|
|
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
|
-
|
|
150
|
-
|
|
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
|
|
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
|
-
.
|
|
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 =
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
(
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
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,
|
package/src/agents-focus.ts
CHANGED
|
@@ -52,7 +52,9 @@ export async function focusAgent(
|
|
|
52
52
|
const request: FocusRequest = {
|
|
53
53
|
source: {
|
|
54
54
|
...(await local.client.machineIdentity()),
|
|
55
|
-
|
|
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(
|
|
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 &&
|