@howaboua/pi-shepherdr 0.2.28-core.12.1.gda85fa2e8a0f → 1.0.0
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 +24 -0
- package/README.md +34 -5
- package/biome.json +1 -1
- package/index.ts +5 -2
- package/package.json +19 -14
- package/src/agents-contract.ts +80 -61
- package/src/agents-discovery.ts +14 -10
- package/src/agents-focus.ts +7 -0
- package/src/agents-reply.ts +3 -12
- package/src/agents-spawn.ts +26 -2
- package/src/agents-tool.ts +57 -21
- package/src/agents-work.ts +9 -4
- package/src/ancestry-record.ts +116 -0
- package/src/attachment-notes.ts +3 -2
- package/src/attachment-protocol.ts +124 -68
- package/src/attachment-target.ts +8 -7
- package/src/attachment.ts +3 -3
- package/src/board/records.ts +50 -36
- package/src/close-idle.ts +2 -2
- package/src/controller.ts +5 -4
- package/src/core/backend.ts +26 -3
- package/src/core/helper-bootstrap.mjs +1 -1
- package/src/core/helper-core.mjs +4 -3
- package/src/core/helper-lifetime.mjs +199 -0
- package/src/core/remote-endpoint.ts +10 -3
- package/src/core/remote-helper.ts +3 -0
- package/src/core/remote-service.mjs +9 -0
- package/src/core/remote-transport.ts +11 -1
- package/src/core/spawn.ts +1 -1
- package/src/core/terminal-peer.mjs +26 -5
- package/src/core/terminal.ts +2 -1
- package/src/fleet/connection.ts +4 -0
- package/src/fleet/index.ts +24 -3
- package/src/launch-contract.ts +1 -0
- package/src/launch.ts +40 -3
- package/src/messages/attribution.ts +14 -5
- package/src/messages/focus.ts +4 -3
- package/src/messages/peer-sharing.ts +34 -20
- package/src/monitor-events.ts +10 -10
- package/src/monitor-extension-messages.ts +1 -0
- package/src/monitor.ts +5 -5
- package/src/profiles.ts +1 -8
- package/src/remote/shepherdr-session.mjs +43 -0
- package/src/settlement/delivery.ts +32 -14
- package/src/settlement/index.ts +3 -0
- package/src/shared-context.ts +4 -100
- package/src/spawn-ancestry.ts +103 -0
- package/src/spawn-ownership.ts +93 -5
- package/src/types.ts +1 -0
- package/src/worker-ownership.ts +41 -32
- package/src/worker-resume.ts +231 -0
- package/src/worker-role.ts +9 -35
- package/src/worker-service.ts +95 -59
- package/worker-api.ts +38 -0
- package/src/profile-prompt.ts +0 -32
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,29 @@
|
|
|
1
1
|
# @howaboua/pi-shepherdr
|
|
2
2
|
|
|
3
|
+
## 1.0.0
|
|
4
|
+
|
|
5
|
+
### Breaking changes
|
|
6
|
+
|
|
7
|
+
- Removed the legacy Herdr backend and SSH bridge. Requires Herdr Core 0.1.18+, Pi 1.5+ and Node.js 22.19+. Legacy Herdr TUI is unsupported. Its last supported release, Shepherdr 0.2.27, is unmaintained, with [source available for forks](https://github.com/IgorWarzocha/howaboua-pi-stuff/tree/5ede06bdc32da2b513f0709966af1f32908f243c/packages/pi-shepherdr). Update and restart controllers and workers together. Start fresh Core terminals for older Herdr sessions and reselect watches when changing Core namespaces. Replace pane placement with terminal, new-tab or new-workspace placement.
|
|
8
|
+
- Shepherdr now runs without other extensions. Optional sharing supports Agent Comms or standalone Notes Compaction and Agent Board, preserving saved notes and boards.
|
|
9
|
+
- Agent calls now accept current Core machine names or stable IDs. Saved routes and watches survive renames. Connections adds machines through `hc machine add`.
|
|
10
|
+
- Remote supervision and sharing now use persistent Core attachments. Saved checkpoints remain readable after workers and intermediate controllers close, including older sessions across connected machines.
|
|
11
|
+
- Concurrent Pi sessions now share machine-local launch and saved-session read limits, with calls remaining pending until their normal result is available.
|
|
12
|
+
- Ordinary workers now end with their parent's program. Active remote connections enforce cross-machine cleanup. Detached workers remain independent.
|
|
13
|
+
- Added a public worker API with saved-session reuse and caller-selected detached lifetime.
|
|
14
|
+
- `/root` now follows saved spawn ancestry independently of sharing. Older workers without saved ancestry must use exact session references.
|
|
15
|
+
- Sending or assigning work to a closed, owned worker now resumes its saved Pi session before delivery.
|
|
16
|
+
- The widget now shows watched peers without repeating supervised workers. Monitoring warnings remain visible. Shells retaining old Pi labels no longer appear as live agents.
|
|
17
|
+
- Fixed completed replies being hidden by empty notice turns, and closed agents causing collection warnings or settlement retries.
|
|
18
|
+
- Agent replies now return when the extension accepts the answer instead of blocking later questions until resumed work finishes.
|
|
19
|
+
- Attachment and detachment now accept context or Board sharing independently. Incoming messages identify sender access, distinguishing machine IDs from Pi agent references.
|
|
20
|
+
- Monitoring notices now describe delayed or unavailable agent updates and automatic retry without duplicate internal errors during Core restarts.
|
|
21
|
+
- Agent help now asks callers to trust worker judgement instead of over-prescribing restrictions or narrowing the task unnecessarily.
|
|
22
|
+
- Worker profiles now brief only the initial assignment instead of pinning restrictions in the standing prompt. Later assignments and model-role changes can reuse the same agent and its notes.
|
|
23
|
+
- Agent help now keeps each agent available until its task is verified complete, with corrections returned to the same agent before closing it.
|
|
24
|
+
- Agent help now directs callers to skip acknowledgements, status-only updates and standby reminders that needlessly wake idle agents.
|
|
25
|
+
- Removed the TypeBox installation requirement.
|
|
26
|
+
|
|
3
27
|
## 0.2.27
|
|
4
28
|
|
|
5
29
|
- New remote workers retain their Core parent link for sidebar nesting.
|
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.5 or newer, Node.js 22.
|
|
17
|
+
Requires Pi 1.5 or newer, Node.js 22.19 or newer and Herdr Core 0.1.18 or newer. Run Pi in a Core terminal, through `hc` or a Herdr app connected to that Core. Shepherdr reports Pi status to Core and discovers other Pi sessions with Shepherdr installed. No separate Pi integration is needed.
|
|
18
18
|
|
|
19
19
|
Do not load Pi Codex's example `agents.toml` custom tool alongside Shepherdr; they own the same agent surface.
|
|
20
20
|
|
|
@@ -22,10 +22,14 @@ Shepherdr installs and runs on its own. Pi Codex, shared Notes and boards are op
|
|
|
22
22
|
|
|
23
23
|
Workers start as background Core terminals by default. Use `placement: "new_workspace"` for a new app workspace, or `placement: "new_tab"` with a `workspace` ID advertised by a live terminal on the target Core. A connected Herdr app adopts these terminals. Pane placement is no longer supported. Focus requires a Herdr app window running on the target Core's machine and connected to that Core.
|
|
24
24
|
|
|
25
|
+
Ordinary workers end when their parent's program exits. Active remote connections also verify Core's parent links and close ordinary children when Core misses cross-machine cleanup. Detached workers remain independent. Restoring a Pi session preserves its saved worker identity. `/root` follows saved spawn ancestry, not shared Notes or Board membership. Older workers without saved ancestry must use exact session references for messages.
|
|
26
|
+
|
|
25
27
|
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.
|
|
26
28
|
|
|
27
29
|
### Migrating from the older Herdr TUI
|
|
28
30
|
|
|
31
|
+
Current Shepherdr is Core-native and is not backward-compatible with the legacy Herdr TUI. Shepherdr 0.2.27 was the last release supporting it. Its [source is available for forks](https://github.com/IgorWarzocha/howaboua-pi-stuff/tree/5ede06bdc32da2b513f0709966af1f32908f243c/packages/pi-shepherdr), but the legacy version is unmaintained.
|
|
32
|
+
|
|
29
33
|
Update and restart controllers and workers together. The older Herdr backend, SSH bridge, machine catalogue and legacy environment overrides are no longer used. Existing Herdr TUI sessions cannot migrate to Core. Start fresh Core terminals and configure remote machines with `hc machine add` on the host running Pi.
|
|
30
34
|
|
|
31
35
|
When switching from the older TUI or another Core namespace, explicitly select the agents you want to watch again. Saved addresses from the previous namespace are not transferable.
|
|
@@ -52,6 +56,8 @@ Machines belong to the host running Pi, not the machine displaying its terminal.
|
|
|
52
56
|
|
|
53
57
|
Remote file watches, Notes, shared-context calls and peer messages use a private Core-owned helper, started lazily and kept alive over a flow-controlled terminal attachment. Shepherdr does not install SSH bridge files or poll through `machine.exec`. Voice focus uses a separate private helper so large Notes transfers do not block its channel. Monitoring uses each Core's own snapshot rather than treating a missing machine in an aggregate terminal list as closed agents.
|
|
54
58
|
|
|
59
|
+
The same connection supervises native remote-parent lifetimes while active. A brief closing grace makes a best-effort check for Pi exiting. No separate background service is installed. A disconnected or unreachable parent is not treated as dead. Failed checks leave existing agents available and produce a warning while the connection is active. Reconnect the parent Core or close its children explicitly. Closing checks have no persistent warning report. This does not guarantee cleanup after an OS failure or a prolonged Pi shutdown.
|
|
60
|
+
|
|
55
61
|
## Agent calls
|
|
56
62
|
|
|
57
63
|
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.
|
|
@@ -81,6 +87,8 @@ Nonblocking extension messages notify the controller once; blocking messages arr
|
|
|
81
87
|
|
|
82
88
|
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.
|
|
83
89
|
|
|
90
|
+
When a parent sends or assigns work to one of its closed workers, Shepherdr reopens that worker's saved Pi session before delivering the message. Use its session reference, previous terminal target or saved routing name. The result reports `resumed: true` and the current target. This applies only to children recorded in the parent's selected session branch, not arbitrary peers or attachments. The saved session and its original machine must remain accessible. `/quit` never reopens a closed worker.
|
|
91
|
+
|
|
84
92
|
Delegation and explicit `watch` keep reporting subsequent work until `unwatch` or the agent's terminal closes. Finishing or failing a task clears that task, not its watch. Follow-up messages through `send` retain completion reporting without replacing the task.
|
|
85
93
|
|
|
86
94
|
Every `spawn` needs an `agent_type` and a concise `label`. The label names the Pi session. The routing `name` remains optional and is derived from the label when omitted.
|
|
@@ -222,10 +230,13 @@ Shepherdr works without Notes or PCC. A target without active Notes sharing stil
|
|
|
222
230
|
## Profiles
|
|
223
231
|
|
|
224
232
|
On first load, Shepherdr installs three editable profiles:
|
|
233
|
+
|
|
225
234
|
- `general` uses `openai-codex/gpt-6-sol` with `high` thinking for implementation
|
|
226
235
|
- `explorer` uses `openai-codex/gpt-6-luna` with `high` thinking for read-only discovery
|
|
227
236
|
- `reviewer` uses `openai-codex/gpt-6-luna` with `xhigh` thinking for generic read-only review
|
|
228
237
|
|
|
238
|
+
Profiles set starting defaults, not a permanent role. Their instructions accompany the initial assignment, so the same agent can take on different work later. Notes model roles can change its model and reasoning at context rollover without replacing the agent or discarding its saved notes.
|
|
239
|
+
|
|
229
240
|
Use `general` sparingly, mainly when requested or while orchestration is active. For work in the controller's repository, create and prepare a dedicated worktree, then pass it as `cwd`.
|
|
230
241
|
|
|
231
242
|
Profiles live under:
|
|
@@ -250,6 +261,7 @@ That directory is authoritative after initialization. Edit a profile to change i
|
|
|
250
261
|
`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.
|
|
251
262
|
|
|
252
263
|
Optional profile settings:
|
|
264
|
+
|
|
253
265
|
- `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.
|
|
254
266
|
- `share_context`: `false` opts new spawns out of shared notes and history. Omission or `true` follows the controller setting.
|
|
255
267
|
|
|
@@ -279,13 +291,30 @@ pi.events.emit("shepherdr:worker-role:v1", {
|
|
|
279
291
|
|
|
280
292
|
No reply means Shepherdr is unavailable. The query adds no model instructions or tools. Worker launch flags describe the process, so new sessions opened inside that process remain workers.
|
|
281
293
|
|
|
282
|
-
##
|
|
294
|
+
## Worker API
|
|
295
|
+
|
|
296
|
+
Extensions can discover the worker service through Pi events. The public types are exported from `@howaboua/pi-shepherdr/worker-api`. A type-only import keeps Shepherdr optional:
|
|
297
|
+
|
|
298
|
+
```ts
|
|
299
|
+
import type { WorkerService } from "@howaboua/pi-shepherdr/worker-api";
|
|
300
|
+
|
|
301
|
+
const protocol: WorkerService["protocol"] = "@howaboua/pi-shepherdr/workers/v1";
|
|
302
|
+
let workers: WorkerService | undefined;
|
|
303
|
+
pi.events.emit(`${protocol}/request`, {
|
|
304
|
+
protocol,
|
|
305
|
+
accept: (service: WorkerService) => {
|
|
306
|
+
workers = service;
|
|
307
|
+
},
|
|
308
|
+
});
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
No reply means the service is unavailable. Discover again after extension reload. Start work after session startup and resource discovery in a TUI session. Callers own scheduling, eligibility and whether to use `isWorker(ctx)` to exclude workers from their workflow.
|
|
283
312
|
|
|
284
|
-
|
|
313
|
+
`start(ctx, { scope, key, requestId, title, prompt, cwd, workerId?, lifetime? })` submits one task and returns `{ workerId, state }`. Use a stable extension-specific `scope`, a reusable worker `key` and a fresh `requestId` per task. Repeating the latest acknowledged request ID returns its existing status without resending. Persist the receipt before attempting another request. A failed call may have submitted work unless its error has `dispatched: false`. Never retry an uncertain rejection, even with the same ID. Request IDs do not make failed calls replay-safe. Inspection helps establish the outcome but does not clear the uncertain admission.
|
|
285
314
|
|
|
286
|
-
The
|
|
315
|
+
The default lifetime is `parent`. Set `lifetime: "detached"` explicitly to keep the worker running after its parent exits. Lifetime and working directory cannot change for an existing key. `inspect(ctx, scope, workerId)` reports `working`, `idle` or `closed`; `subscribe(listener)` provides change notifications and returns an unsubscribe function. Ownership is restricted to the caller's selected native session branch and scope, not an access-control boundary between trusted extensions.
|
|
287
316
|
|
|
288
|
-
|
|
317
|
+
Workers run in separate Pi processes. Their final responses use the same monitored delivery as asynchronous `agents` calls, including normal kickoff preparation and rollover admission. The service reuses owned saved sessions and refuses overlapping work. Fresh workers use the `general` profile without its role prompt; resumed sessions retain their saved model, thinking level and name. Fresh workers inherit the family Board and optional shared Notes and cache affinity. Use ordinary Shepherdr controls to manage worker terminals. No automation extension is required.
|
|
289
318
|
|
|
290
319
|
## License
|
|
291
320
|
|
package/biome.json
CHANGED
package/index.ts
CHANGED
|
@@ -10,7 +10,6 @@ import { AgentFleet } from "./src/fleet/index.js";
|
|
|
10
10
|
import { registerAgentEventRenderer } from "./src/messages/render.js";
|
|
11
11
|
import { createPeerCommands } from "./src/peer-commands.js";
|
|
12
12
|
import { registerPeerInbox } from "./src/peer-inbox.js";
|
|
13
|
-
import { registerProfilePrompt } from "./src/profile-prompt.js";
|
|
14
13
|
import { installAgentProfiles } from "./src/profiles.js";
|
|
15
14
|
import { registerSharedAgentContext } from "./src/shared-context-host.js";
|
|
16
15
|
import { registerVoiceFocusReceiver } from "./src/voice-handoff.js";
|
|
@@ -27,7 +26,11 @@ export default async function shepherdrExtension(
|
|
|
27
26
|
const workerRole = registerWorkerRole(pi);
|
|
28
27
|
|
|
29
28
|
await installAgentProfiles();
|
|
30
|
-
|
|
29
|
+
// Older saved launch commands may still carry this flag. It no longer pins a role.
|
|
30
|
+
pi.registerFlag("shepherdr-profile-prompt", {
|
|
31
|
+
type: "string",
|
|
32
|
+
description: "Legacy worker profile option (ignored)",
|
|
33
|
+
});
|
|
31
34
|
registerDeveloperDelivery(pi);
|
|
32
35
|
const peerCommands = createPeerCommands(pi);
|
|
33
36
|
const fleet = new AgentFleet(pi);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@howaboua/pi-shepherdr",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "1.0.0",
|
|
4
4
|
"description": "Persistent blocking and asynchronous Pi agents through Herdr.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -25,6 +25,7 @@
|
|
|
25
25
|
],
|
|
26
26
|
"files": [
|
|
27
27
|
"index.ts",
|
|
28
|
+
"worker-api.ts",
|
|
28
29
|
"src",
|
|
29
30
|
"profiles",
|
|
30
31
|
"README.md",
|
|
@@ -42,11 +43,10 @@
|
|
|
42
43
|
"pack:dry": "npm pack --dry-run"
|
|
43
44
|
},
|
|
44
45
|
"peerDependencies": {
|
|
45
|
-
"@howaboua/pi-codex-conversion": ">=4.0.
|
|
46
|
+
"@howaboua/pi-codex-conversion": ">=4.0.10",
|
|
46
47
|
"@earendil-works/pi-ai": ">=1.1.0",
|
|
47
48
|
"@earendil-works/pi-coding-agent": ">=1.5.0",
|
|
48
|
-
"@earendil-works/pi-tui": ">=1.1.0"
|
|
49
|
-
"typebox": "*"
|
|
49
|
+
"@earendil-works/pi-tui": ">=1.1.0"
|
|
50
50
|
},
|
|
51
51
|
"peerDependenciesMeta": {
|
|
52
52
|
"@howaboua/pi-codex-conversion": {
|
|
@@ -54,14 +54,13 @@
|
|
|
54
54
|
}
|
|
55
55
|
},
|
|
56
56
|
"devDependencies": {
|
|
57
|
-
"@howaboua/pi-agent-comms": "0.0.
|
|
58
|
-
"@howaboua/pi-codex-conversion": "4.0.
|
|
59
|
-
"@biomejs/biome": "^2.6.
|
|
60
|
-
"@earendil-works/pi-ai": "1.5.
|
|
61
|
-
"@earendil-works/pi-coding-agent": "1.5.
|
|
62
|
-
"@earendil-works/pi-tui": "1.5.
|
|
63
|
-
"@types/node": "^26.6.
|
|
64
|
-
"typebox": "1.4.3",
|
|
57
|
+
"@howaboua/pi-agent-comms": "0.0.1",
|
|
58
|
+
"@howaboua/pi-codex-conversion": "4.0.10",
|
|
59
|
+
"@biomejs/biome": "^2.6.6",
|
|
60
|
+
"@earendil-works/pi-ai": "1.5.2",
|
|
61
|
+
"@earendil-works/pi-coding-agent": "1.5.2",
|
|
62
|
+
"@earendil-works/pi-tui": "1.5.2",
|
|
63
|
+
"@types/node": "^26.6.6",
|
|
65
64
|
"typescript": "^7.0.2"
|
|
66
65
|
},
|
|
67
66
|
"pi": {
|
|
@@ -70,11 +69,17 @@
|
|
|
70
69
|
]
|
|
71
70
|
},
|
|
72
71
|
"engines": {
|
|
73
|
-
"node": ">=22.
|
|
72
|
+
"node": ">=22.19.0"
|
|
74
73
|
},
|
|
75
74
|
"main": "index.ts",
|
|
76
|
-
"exports":
|
|
75
|
+
"exports": {
|
|
76
|
+
".": "./index.ts",
|
|
77
|
+
"./worker-api": "./worker-api.ts"
|
|
78
|
+
},
|
|
77
79
|
"publishConfig": {
|
|
78
80
|
"access": "public"
|
|
81
|
+
},
|
|
82
|
+
"dependencies": {
|
|
83
|
+
"@earendil-works/pi-schema": "1.5.2"
|
|
79
84
|
}
|
|
80
85
|
}
|
package/src/agents-contract.ts
CHANGED
|
@@ -1,12 +1,17 @@
|
|
|
1
|
-
import {
|
|
2
|
-
|
|
1
|
+
import {
|
|
2
|
+
bool,
|
|
3
|
+
compile,
|
|
4
|
+
int,
|
|
5
|
+
lit,
|
|
6
|
+
obj,
|
|
7
|
+
oneOf,
|
|
8
|
+
opt,
|
|
9
|
+
type Static,
|
|
10
|
+
str,
|
|
11
|
+
} from "@earendil-works/pi-schema";
|
|
3
12
|
import { START_PLACEMENTS } from "./launch.js";
|
|
4
13
|
import { loadAgentProfileBlocking } from "./profiles.js";
|
|
5
14
|
|
|
6
|
-
function StringEnum<T extends readonly string[]>(values: T) {
|
|
7
|
-
return Type.Unsafe<T[number]>({ type: "string", enum: values });
|
|
8
|
-
}
|
|
9
|
-
|
|
10
15
|
const ACTIONS = [
|
|
11
16
|
"help",
|
|
12
17
|
"list",
|
|
@@ -53,58 +58,75 @@ const ACTION_FIELDS: Record<(typeof ACTIONS)[number], ReadonlySet<string>> = {
|
|
|
53
58
|
read: new Set(["action", "machine", "target", "source", "lines"]),
|
|
54
59
|
reply: new Set(["action", "machine", "target", "extension", "id", "message"]),
|
|
55
60
|
};
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
61
|
+
const AgentsRequest = obj({
|
|
62
|
+
action: {
|
|
63
|
+
...oneOf(ACTIONS),
|
|
64
|
+
type: "string",
|
|
65
|
+
},
|
|
66
|
+
commands: opt({
|
|
67
|
+
...lit(true),
|
|
68
|
+
type: "boolean",
|
|
69
|
+
}),
|
|
70
|
+
machine: opt(str()),
|
|
71
|
+
voice: opt(bool()),
|
|
72
|
+
handoff: opt(str()),
|
|
73
|
+
target: opt(str()),
|
|
74
|
+
agent_type: opt(str()),
|
|
75
|
+
name: opt(
|
|
76
|
+
str({
|
|
77
|
+
description: "Agent name; derived from label when omitted",
|
|
78
|
+
}),
|
|
79
|
+
),
|
|
80
|
+
label: opt(str()),
|
|
81
|
+
placement: opt({
|
|
82
|
+
...oneOf(START_PLACEMENTS),
|
|
83
|
+
type: "string",
|
|
84
|
+
}),
|
|
85
|
+
workspace: opt(str()),
|
|
86
|
+
cwd: opt(str()),
|
|
87
|
+
message: opt(str({ description: "Task, follow-up or extension reply" })),
|
|
88
|
+
base: opt(str({ description: "Review base branch" })),
|
|
89
|
+
blocking: opt(
|
|
90
|
+
bool({
|
|
91
|
+
description:
|
|
92
|
+
"Wait for delegated result; profile policy overrides spawn; default false",
|
|
93
|
+
}),
|
|
94
|
+
),
|
|
95
|
+
context: opt(bool()),
|
|
96
|
+
board: opt(bool()),
|
|
97
|
+
board_thread_id: opt(str({ minLength: 1 })),
|
|
98
|
+
query: opt(str()),
|
|
99
|
+
status: opt({
|
|
100
|
+
...oneOf(STATUSES),
|
|
101
|
+
type: "string",
|
|
102
|
+
}),
|
|
103
|
+
source: opt({
|
|
104
|
+
...oneOf(READ_SOURCES),
|
|
105
|
+
type: "string",
|
|
106
|
+
}),
|
|
107
|
+
lines: opt(int({ minimum: 1, maximum: 200 })),
|
|
108
|
+
extension: opt(str()),
|
|
109
|
+
id: opt(str()),
|
|
110
|
+
});
|
|
111
|
+
const checkAgentsRequest = compile(AgentsRequest).check;
|
|
112
|
+
export const AgentsParameters = {
|
|
113
|
+
...obj(
|
|
114
|
+
{
|
|
115
|
+
action: opt({
|
|
116
|
+
...oneOf(ACTIONS),
|
|
117
|
+
type: "string",
|
|
69
118
|
}),
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
workspace: Type.Optional(Type.String()),
|
|
74
|
-
cwd: Type.Optional(Type.String()),
|
|
75
|
-
message: Type.Optional(
|
|
76
|
-
Type.String({ description: "Task, follow-up or extension reply" }),
|
|
77
|
-
),
|
|
78
|
-
base: Type.Optional(Type.String({ description: "Review base branch" })),
|
|
79
|
-
blocking: Type.Optional(
|
|
80
|
-
Type.Boolean({
|
|
81
|
-
description:
|
|
82
|
-
"Wait for delegated result; profile policy overrides spawn; default false",
|
|
119
|
+
commands: opt({
|
|
120
|
+
...lit(true),
|
|
121
|
+
type: "boolean",
|
|
83
122
|
}),
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
lines: Type.Optional(Type.Integer({ minimum: 1, maximum: 200 })),
|
|
92
|
-
extension: Type.Optional(Type.String()),
|
|
93
|
-
id: Type.Optional(Type.String()),
|
|
94
|
-
},
|
|
95
|
-
{ additionalProperties: false },
|
|
96
|
-
);
|
|
97
|
-
|
|
98
|
-
export const AgentsParameters = Type.Object(
|
|
99
|
-
{
|
|
100
|
-
action: Type.Optional(StringEnum(ACTIONS)),
|
|
101
|
-
commands: Type.Optional(Type.Literal(true)),
|
|
102
|
-
target: Type.Optional(Type.String()),
|
|
103
|
-
machine: Type.Optional(Type.String()),
|
|
104
|
-
},
|
|
105
|
-
{ additionalProperties: true },
|
|
106
|
-
);
|
|
107
|
-
|
|
123
|
+
target: opt(str()),
|
|
124
|
+
machine: opt(str()),
|
|
125
|
+
},
|
|
126
|
+
{ open: true },
|
|
127
|
+
),
|
|
128
|
+
additionalProperties: true,
|
|
129
|
+
};
|
|
108
130
|
export type AgentsParams = Static<typeof AgentsRequest>;
|
|
109
131
|
export type AgentsToolParams = Static<typeof AgentsParameters>;
|
|
110
132
|
|
|
@@ -190,7 +212,7 @@ export function parseAgentsRequest(input: unknown): AgentsParams {
|
|
|
190
212
|
) {
|
|
191
213
|
throw new Error(`read source must be one of: ${READ_SOURCES.join(", ")}`);
|
|
192
214
|
}
|
|
193
|
-
if (!
|
|
215
|
+
if (!checkAgentsRequest(request)) {
|
|
194
216
|
throw new Error(
|
|
195
217
|
`invalid ${action} request; call agents help for its contract`,
|
|
196
218
|
);
|
|
@@ -208,10 +230,7 @@ export function isBlockingAgentsCall(input: unknown): boolean {
|
|
|
208
230
|
),
|
|
209
231
|
value.blocking,
|
|
210
232
|
);
|
|
211
|
-
return
|
|
212
|
-
value.action === "reply" ||
|
|
213
|
-
(value.action === "assign" && value.blocking === true)
|
|
214
|
-
);
|
|
233
|
+
return value.action === "assign" && value.blocking === true;
|
|
215
234
|
} catch {
|
|
216
235
|
return false;
|
|
217
236
|
}
|
package/src/agents-discovery.ts
CHANGED
|
@@ -59,14 +59,17 @@ export async function agentsHelp(
|
|
|
59
59
|
? "latest(default)=last reply+pending extension messages; visible=current TUI screen; recent=TUI scrollback, lines default 40. Findings→returned Notes path if shared Notes available"
|
|
60
60
|
: "latest (default) returns the last reply and pending extension messages; visible reads the current TUI screen; recent reads TUI scrollback, lines default 40. For findings, read the returned Notes path when shared Notes is available",
|
|
61
61
|
reply: gpt
|
|
62
|
-
? "Extension report/read template required; send≠resolve;
|
|
63
|
-
: "Use the extension-authored template from its report/read; send does not resolve it.
|
|
62
|
+
? "Extension report/read template required; send≠resolve; returns after acceptance, never waits resumed work"
|
|
63
|
+
: "Use the extension-authored template from its report/read; send does not resolve it. Replies return after acceptance, without waiting for resumed work",
|
|
64
64
|
machine: gpt
|
|
65
65
|
? "machine omitted=local Pi host; list/find omitted=all machines; select current machine name or ID from list"
|
|
66
66
|
: "Omit for local (host running Pi); list/find omit for all machines. Select a current machine name or ID from list",
|
|
67
67
|
target: gpt
|
|
68
|
-
? "target=
|
|
69
|
-
: "Use
|
|
68
|
+
? "target=Pi session reference or terminal; /root=live spawn root"
|
|
69
|
+
: "Use the Pi session reference or terminal target; /root selects the live root of saved spawn ancestry",
|
|
70
|
+
resume: gpt
|
|
71
|
+
? "send/assign to owned closed worker→resume saved session; /quit never resumes"
|
|
72
|
+
: "Sending or assigning to a closed worker recorded by this parent resumes its saved session; /quit never resumes",
|
|
70
73
|
label: "Short Pi session name; app tabs use default names",
|
|
71
74
|
placement:
|
|
72
75
|
"terminal (default), new_tab, new_workspace; new_tab needs space ID",
|
|
@@ -78,8 +81,8 @@ export async function agentsHelp(
|
|
|
78
81
|
}
|
|
79
82
|
: {}),
|
|
80
83
|
send: gpt
|
|
81
|
-
? "
|
|
82
|
-
: "
|
|
84
|
+
? "Messages wake idle agents; send ONLY to change recipient next action, NO acknowledgements/status-only/standby. Close→/quit directly, NO preceding message or wait/watch"
|
|
85
|
+
: "Messages wake idle agents. Send only when it changes the recipient's next action; skip acknowledgements, status-only updates and standby reminders. Close with /quit directly, without another message first. No waiting or watching.",
|
|
83
86
|
assign: gpt
|
|
84
87
|
? "Delegate/update work; active→share pending result, NEVER replace wait"
|
|
85
88
|
: "Delegate or update work; active updates share its pending result, never replace an existing wait",
|
|
@@ -106,14 +109,14 @@ export async function agentsHelp(
|
|
|
106
109
|
? "Delegation/watch→report subsequent work UNTIL unwatch/close"
|
|
107
110
|
: "Delegation and watch keep reporting subsequent work until unwatch or close",
|
|
108
111
|
prompt: gpt
|
|
109
|
-
? "
|
|
110
|
-
: "Give
|
|
112
|
+
? "Task + necessary context; trust agent to choose approach. Avoid unnecessary restrictions and overly narrow scope"
|
|
113
|
+
: "Give the task and necessary context. Trust the agent to choose its approach. Avoid unnecessary restrictions and overly narrow scope",
|
|
111
114
|
slash: gpt
|
|
112
115
|
? "Leading / routes target commands/skills/templates; commands skip task wait EVEN assign/spawn; blocked→choices; /quit exits Pi+closes terminal"
|
|
113
116
|
: "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 terminal",
|
|
114
117
|
reuse: gpt
|
|
115
|
-
? "
|
|
116
|
-
: "
|
|
118
|
+
? "Keep each agent until task verified complete; corrections→same agent; then close. Unrelated task→new agent; reviews independent"
|
|
119
|
+
: "Keep each agent available until its task is verified complete; return corrections to it before closing. Use separate agents for unrelated work and independent reviews.",
|
|
117
120
|
...(profiles.has("general")
|
|
118
121
|
? {
|
|
119
122
|
general: "Only when requested/orchestrating",
|
|
@@ -246,6 +249,7 @@ export async function listFleetAgents(
|
|
|
246
249
|
({
|
|
247
250
|
snapshot: _snapshot,
|
|
248
251
|
monitoredPaneIds: _monitoredPaneIds,
|
|
252
|
+
session: _session,
|
|
249
253
|
...machine
|
|
250
254
|
}) => machine,
|
|
251
255
|
),
|
package/src/agents-focus.ts
CHANGED
|
@@ -54,6 +54,7 @@ export async function focusAgent(
|
|
|
54
54
|
const request: FocusRequest = {
|
|
55
55
|
source: {
|
|
56
56
|
...(await local.client.machineIdentity()),
|
|
57
|
+
agent: `/${ctx.sessionManager.getSessionId()}`,
|
|
57
58
|
backend: "core",
|
|
58
59
|
terminal: source.terminal_id,
|
|
59
60
|
sessionFile,
|
|
@@ -116,6 +117,12 @@ export function readFocus(value: unknown): FocusRequest {
|
|
|
116
117
|
)
|
|
117
118
|
throw new Error("Invalid focus source");
|
|
118
119
|
}
|
|
120
|
+
if (
|
|
121
|
+
"agent" in source &&
|
|
122
|
+
(typeof source["agent"] !== "string" ||
|
|
123
|
+
!/^\/[^/\\\u0000]+$/.test(source["agent"]))
|
|
124
|
+
)
|
|
125
|
+
throw new Error("Invalid focus agent");
|
|
119
126
|
if (source["backend"] !== "core")
|
|
120
127
|
throw new Error(
|
|
121
128
|
"Focus return requires a Core session; focus again from the source session",
|
package/src/agents-reply.ts
CHANGED
|
@@ -1,10 +1,6 @@
|
|
|
1
1
|
import type { AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
|
|
2
2
|
import type { AgentsParams } from "./agents-contract.js";
|
|
3
|
-
import {
|
|
4
|
-
dispatchAgentWork,
|
|
5
|
-
settlementResult,
|
|
6
|
-
toolResult,
|
|
7
|
-
} from "./agents-work.js";
|
|
3
|
+
import { dispatchAgentWork, toolResult } from "./agents-work.js";
|
|
8
4
|
import type { ConnectedMachine } from "./fleet/index.js";
|
|
9
5
|
import type { PaneInfo } from "./types.js";
|
|
10
6
|
|
|
@@ -40,11 +36,11 @@ export async function replyAgent(
|
|
|
40
36
|
result,
|
|
41
37
|
});
|
|
42
38
|
}
|
|
43
|
-
const {
|
|
39
|
+
const { warning } = await dispatchAgentWork(
|
|
44
40
|
runtime,
|
|
45
41
|
panel,
|
|
46
42
|
`Reply to ${reply.extension}`,
|
|
47
|
-
|
|
43
|
+
false,
|
|
48
44
|
signal,
|
|
49
45
|
onUpdate,
|
|
50
46
|
send,
|
|
@@ -52,11 +48,6 @@ export async function replyAgent(
|
|
|
52
48
|
);
|
|
53
49
|
return toolResult(
|
|
54
50
|
{
|
|
55
|
-
...(settlement
|
|
56
|
-
? settlementResult(runtime.machine, settlement, {
|
|
57
|
-
reportWorkerError: true,
|
|
58
|
-
})
|
|
59
|
-
: {}),
|
|
60
51
|
machine: runtime.machine,
|
|
61
52
|
target: panel.pane_id,
|
|
62
53
|
extension: reply.extension,
|
package/src/agents-spawn.ts
CHANGED
|
@@ -31,6 +31,7 @@ import {
|
|
|
31
31
|
} from "./profiles.js";
|
|
32
32
|
import { isDispatchRejected } from "./remote/shepherdr-peer.mjs";
|
|
33
33
|
import type { SharedAgentContext } from "./shared-context.js";
|
|
34
|
+
import { prepareLaunchAncestry } from "./spawn-ancestry.js";
|
|
34
35
|
import { prepareSpawnOwnership } from "./spawn-ownership.js";
|
|
35
36
|
|
|
36
37
|
export async function spawnAgent(
|
|
@@ -99,8 +100,10 @@ export async function spawnAgent(
|
|
|
99
100
|
);
|
|
100
101
|
const attributedMessage = await attributeAgentPrompt(
|
|
101
102
|
fleet.connected().client,
|
|
103
|
+
ctx.sessionManager.getSessionId(),
|
|
102
104
|
input.startsWith("/") ? input : message,
|
|
103
105
|
"task",
|
|
106
|
+
profile.prompt,
|
|
104
107
|
);
|
|
105
108
|
if (input.startsWith("/") && message !== input)
|
|
106
109
|
attributedMessage.context = [attributedMessage.context, message]
|
|
@@ -139,7 +142,11 @@ export async function spawnAgent(
|
|
|
139
142
|
startParams,
|
|
140
143
|
runtime.fallbackCwd,
|
|
141
144
|
runtime.resolveDirectory,
|
|
142
|
-
{
|
|
145
|
+
{
|
|
146
|
+
agentArgs,
|
|
147
|
+
signal,
|
|
148
|
+
ancestry: await prepareLaunchAncestry(ctx, fleet, signal),
|
|
149
|
+
},
|
|
143
150
|
);
|
|
144
151
|
let promptSubmissionStarted = false;
|
|
145
152
|
let promptAccepted = false;
|
|
@@ -148,10 +155,10 @@ export async function spawnAgent(
|
|
|
148
155
|
let boardShared: { agentName?: string; warning?: string } | undefined;
|
|
149
156
|
let agentName: string | undefined;
|
|
150
157
|
let relationshipWarning: string | undefined;
|
|
158
|
+
let ownershipWarning: string | undefined;
|
|
151
159
|
const blocking = shouldBlockAgentSpawn(profile.blocking, params.blocking);
|
|
152
160
|
try {
|
|
153
161
|
agentName = await nativeAgentName(runtime.client, started.agent, signal);
|
|
154
|
-
await recordSpawn(started.agent, agentArgs);
|
|
155
162
|
relationshipWarning = (await relationship?.accept(started.agent))
|
|
156
163
|
?.warning;
|
|
157
164
|
boardShared = await boardBinding?.accept(started.agent);
|
|
@@ -175,6 +182,12 @@ export async function spawnAgent(
|
|
|
175
182
|
attributedMessage,
|
|
176
183
|
);
|
|
177
184
|
promptAccepted = true;
|
|
185
|
+
try {
|
|
186
|
+
await recordSpawn(started.agent, agentArgs, agentName, startParams);
|
|
187
|
+
} catch {
|
|
188
|
+
ownershipWarning =
|
|
189
|
+
"Submitted, but saved worker ownership could not be recorded. Automatic resume is unavailable; use its current target and do not resend the task";
|
|
190
|
+
}
|
|
178
191
|
return receipt;
|
|
179
192
|
},
|
|
180
193
|
{ expectUserMessage: true },
|
|
@@ -186,6 +199,16 @@ export async function spawnAgent(
|
|
|
186
199
|
) {
|
|
187
200
|
return await rollbackStartedAgent(runtime.client, started, error);
|
|
188
201
|
}
|
|
202
|
+
if (!promptAccepted) {
|
|
203
|
+
try {
|
|
204
|
+
await recordSpawn(started.agent, agentArgs, agentName, startParams);
|
|
205
|
+
} catch (ownershipError) {
|
|
206
|
+
throw new AggregateError(
|
|
207
|
+
[error, ownershipError],
|
|
208
|
+
"Worker delivery is unconfirmed and its ownership could not be saved. Inspect the target before sending the task again",
|
|
209
|
+
);
|
|
210
|
+
}
|
|
211
|
+
}
|
|
189
212
|
throw error;
|
|
190
213
|
}
|
|
191
214
|
return toolResult(
|
|
@@ -226,6 +249,7 @@ export async function spawnAgent(
|
|
|
226
249
|
boardShared?.warning,
|
|
227
250
|
shared?.warning,
|
|
228
251
|
relationshipWarning,
|
|
252
|
+
ownershipWarning,
|
|
229
253
|
]
|
|
230
254
|
.filter(Boolean)
|
|
231
255
|
.join("\n") || undefined,
|