@howaboua/pi-shepherdr 0.2.21 → 0.2.23
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 +25 -0
- package/README.md +27 -1
- package/index.ts +34 -2
- package/package.json +4 -4
- package/src/agents-discovery.ts +23 -15
- package/src/agents-spawn.ts +141 -135
- package/src/agents-tool.ts +13 -4
- package/src/agents-work.ts +30 -6
- package/src/board/host.ts +3 -2
- package/src/launch.ts +43 -13
- package/src/messages.ts +24 -6
- package/src/monitor-extension-messages.ts +14 -1
- package/src/monitor.ts +2 -0
- package/src/profile-prompt.ts +32 -0
- package/src/profiles.ts +5 -22
- package/src/remote-client.ts +12 -2
- package/src/spawn-context.ts +14 -2
- package/src/worker-role.ts +83 -0
- package/src/worker-service.ts +397 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,30 @@
|
|
|
1
1
|
# @howaboua/pi-shepherdr
|
|
2
2
|
|
|
3
|
+
## 0.2.23
|
|
4
|
+
|
|
5
|
+
- - Worker roles now follow shared project instructions, preserving a longer common startup prefix and exact role whitespace across machines. Update and reload Shepherdr on controllers and worker hosts together.
|
|
6
|
+
- Fixed broken remote connections causing unhandled pipe errors and leaving requests pending.
|
|
7
|
+
- Worker-notice warnings now identify the affected machine and explain how to reconnect.
|
|
8
|
+
- GPT-mode Board briefings use denser guidance.
|
|
9
|
+
- Blocking agent calls can run in parallel while the controller waits for their results.
|
|
10
|
+
- Launched workers identify themselves to compatible extensions so human-only features can stay off.
|
|
11
|
+
|
|
12
|
+
## 0.2.22
|
|
13
|
+
|
|
14
|
+
- **Worker integrations**
|
|
15
|
+
|
|
16
|
+
- Fresh workers now share their parent's cache routing with compatible Codex Conversion. Shared notes remain optional, and native sessions and histories remain separate.
|
|
17
|
+
- Fresh workers inherit the live Board setting before their first request, keeping Board tools and guidance available from startup.
|
|
18
|
+
- Added an optional Pulses runner with persistent workers, saved-session reuse and completion reports that wake the parent.
|
|
19
|
+
|
|
20
|
+
**Agent tools and guidance**
|
|
21
|
+
|
|
22
|
+
- Expanded tool calls now show outgoing tasks, messages, replies and focus handoffs in full.
|
|
23
|
+
- Added compact agent help and hosted Board briefings for PCC GPT prompt mode.
|
|
24
|
+
- Agent discovery now uses the same help contract across native, Code and Notebook tools.
|
|
25
|
+
- Added delegation guidance for distinct scopes, shared project context and combined validation.
|
|
26
|
+
- Invalid spawn names now explain naming limits and how to use a longer label. Spawn guidance favours short two-word names.
|
|
27
|
+
|
|
3
28
|
## 0.2.21
|
|
4
29
|
|
|
5
30
|
- Fixed duplicate sessions showing a stack trace instead of a warning explaining how to restore shared context.
|
package/README.md
CHANGED
|
@@ -69,6 +69,8 @@ Call `agents` with `{}` before first use, alone, then send flat request objects
|
|
|
69
69
|
|
|
70
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.
|
|
71
71
|
|
|
72
|
+
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
|
+
|
|
72
74
|
Nonblocking extension messages notify the controller once; blocking messages arrive with the worker's blocked result. Both remain visible in `read` and later task reports until the producer closes them. Each replyable message includes a ready `reply` call with its machine, target, extension and message ID. Fill in the extension's reply template. `send` does not resolve an extension message.
|
|
73
75
|
|
|
74
76
|
`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.
|
|
@@ -194,7 +196,7 @@ Child board calls use the owning Pi sessions and existing SSH connections, not a
|
|
|
194
196
|
|
|
195
197
|
## Shared notes and history
|
|
196
198
|
|
|
197
|
-
With compatible Pi Codex Conversion on both ends, Shepherdr marks fresh spawned workers before their first task with their immediate parent's native Pi session ID and `subagentKind: "collab_spawn"`. Each worker keeps its own native session
|
|
199
|
+
With compatible Pi Codex Conversion on both ends, Shepherdr marks fresh spawned workers before their first task with their immediate parent's native Pi session ID and `subagentKind: "collab_spawn"`. Workers also inherit the parent's effective cache routing identity, including nested and remote spawns. Each worker keeps its own native session, sockets and history. Cache routing works with shared notes disabled and does not grant notes access or copy the parent's transcript. Only matching prompt prefixes can benefit. Resume preserves the relationship; forks and profiles selecting existing sessions do not acquire it. Older PCC versions retain ordinary delegation and any supported parent linkage. The [extension API guide](../../docs/extension-apis.md#parent-and-worker-relationships) documents PCC's service contract for other orchestrators. Shepherdr owns transport, not a separate public relationship RPC API.
|
|
198
200
|
|
|
199
201
|
With Pi Codex Conversion 3.0.40 or newer and notes-based continuity, enable **Share subagent context** under `/codex context` in the controller. It is off by default. Shared `spawn` gives each child a unique context identity before its first turn; `contextAgent` in the result identifies its notes and history. Shared nested spawns stay in the same family. Turning sharing off affects new spawns only; existing identity survives resume. `assign` and independently started agents remain unchanged. Older compatible Conversion versions keep ordinary delegation without sharing.
|
|
200
202
|
|
|
@@ -250,6 +252,30 @@ Ordinary delegation stays inside `agents`. For workspace, tab, pane, process, fo
|
|
|
250
252
|
|
|
251
253
|
Herdr still owns terminals, layout, agent processes and restored sessions. Shepherdr owns event subscriptions, remote routing, the fleet widget and purple settlement messages.
|
|
252
254
|
|
|
255
|
+
## Worker role integration
|
|
256
|
+
|
|
257
|
+
Every Shepherdr launch carries `--shepherdr-worker`, including remote workers, profiles without prompts and resumed workers. The role survives session resume after the first task. Forks do not inherit the saved role, but a fork opened inside a flagged worker process is still a worker. Existing agents reached through `assign` or `attach` are not automatically classified as workers. Pi Codex Conversion is not required.
|
|
258
|
+
|
|
259
|
+
Other extensions can query the current role synchronously through public Pi events, including during `session_start`:
|
|
260
|
+
|
|
261
|
+
```ts
|
|
262
|
+
let worker = false;
|
|
263
|
+
pi.events.emit("shepherdr:worker-role:v1", {
|
|
264
|
+
sessionManager: ctx.sessionManager,
|
|
265
|
+
reply: (value: boolean) => { worker = value; },
|
|
266
|
+
});
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
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.
|
|
270
|
+
|
|
271
|
+
## Pulse runner
|
|
272
|
+
|
|
273
|
+
Shepherdr implements Pulses' optional detached-runner contract through Pi events. Pulses owns scheduling. Each worker runs in a separate Pi process, so the main agent remains available. Its final response returns through the same monitored waking delivery as asynchronous `agents` calls, including ordinary kickoff preparation and rollover admission. There is no passive-result or blocking execution mode.
|
|
274
|
+
|
|
275
|
+
The adapter reuses owned saved sessions, refuses overlapping work and verifies parent session, branch and pane identity. Worker receipts are opaque to Pulses. Use ordinary Shepherdr controls to manage worker panes. Detached pulse workers cannot become schedulers themselves.
|
|
276
|
+
|
|
277
|
+
Fresh and restored workers use the `general` profile's model, thinking level and explicit Pi arguments without its implementation-role prompt. Ordinary agent spawns still use the complete profile. Fresh workers inherit the existing family board independently of their working directory, alongside optional shared Notes and cache affinity. The adapter does not choose an output destination or keep the controlling Pi alive.
|
|
278
|
+
|
|
253
279
|
## License
|
|
254
280
|
|
|
255
281
|
MIT
|
package/index.ts
CHANGED
|
@@ -10,9 +10,12 @@ import { AgentFleet } from "./src/fleet.js";
|
|
|
10
10
|
import { registerAgentEventRenderer } from "./src/messages.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";
|
|
13
14
|
import { installAgentProfiles } from "./src/profiles.js";
|
|
14
15
|
import { registerSharedAgentContext } from "./src/shared-context-host.js";
|
|
15
16
|
import { registerVoiceFocusReceiver } from "./src/voice-handoff.js";
|
|
17
|
+
import { registerWorkerRole } from "./src/worker-role.js";
|
|
18
|
+
import { registerWorkerService } from "./src/worker-service.js";
|
|
16
19
|
|
|
17
20
|
const CODE_MODE_PACKAGE = "@howaboua/pi-codex-conversion";
|
|
18
21
|
const CODE_MODE_MODULE = `${CODE_MODE_PACKAGE}/code-mode`;
|
|
@@ -20,9 +23,11 @@ const CODE_MODE_MODULE = `${CODE_MODE_PACKAGE}/code-mode`;
|
|
|
20
23
|
export default async function shepherdrExtension(
|
|
21
24
|
pi: ExtensionAPI,
|
|
22
25
|
): Promise<void> {
|
|
26
|
+
const workerRole = registerWorkerRole(pi);
|
|
23
27
|
registerPackageChangelog(pi);
|
|
24
28
|
|
|
25
29
|
await installAgentProfiles();
|
|
30
|
+
registerProfilePrompt(pi);
|
|
26
31
|
registerDeveloperDelivery(pi);
|
|
27
32
|
const peerCommands = createPeerCommands(pi);
|
|
28
33
|
const fleet = new AgentFleet(pi);
|
|
@@ -33,10 +38,37 @@ export default async function shepherdrExtension(
|
|
|
33
38
|
const board = AgentBoard.create(pi, fleet);
|
|
34
39
|
registerPeerInbox(pi, peerCommands, fleet, (ctx) => board.promptCatchup(ctx));
|
|
35
40
|
const sharedContext = await registerSharedAgentContext(pi, fleet, board);
|
|
36
|
-
|
|
41
|
+
registerWorkerService(pi, fleet, sharedContext, board, workerRole);
|
|
42
|
+
let promptMode: { readonly active: boolean } | undefined;
|
|
43
|
+
const tool = createAgentsTool(
|
|
44
|
+
fleet,
|
|
45
|
+
sharedContext,
|
|
46
|
+
board,
|
|
47
|
+
pi,
|
|
48
|
+
peerCommands,
|
|
49
|
+
() => promptMode?.active ?? false,
|
|
50
|
+
);
|
|
37
51
|
|
|
38
52
|
registerAgentEventRenderer(pi);
|
|
39
53
|
pi.registerTool(tool);
|
|
54
|
+
try {
|
|
55
|
+
const { registerGptPromptMode } = await import(
|
|
56
|
+
"@howaboua/pi-codex-conversion/prompt-mode"
|
|
57
|
+
);
|
|
58
|
+
promptMode = registerGptPromptMode(pi, () => [tool]);
|
|
59
|
+
} catch (error) {
|
|
60
|
+
if (
|
|
61
|
+
!(error instanceof Error) ||
|
|
62
|
+
!("code" in error) ||
|
|
63
|
+
![
|
|
64
|
+
"ERR_MODULE_NOT_FOUND",
|
|
65
|
+
"MODULE_NOT_FOUND",
|
|
66
|
+
"ERR_PACKAGE_PATH_NOT_EXPORTED",
|
|
67
|
+
].includes(String(error.code)) ||
|
|
68
|
+
!error.message.includes(CODE_MODE_PACKAGE)
|
|
69
|
+
)
|
|
70
|
+
throw error;
|
|
71
|
+
}
|
|
40
72
|
await registerAgentsInCodeMode(pi, tool);
|
|
41
73
|
registerAgentController(pi, fleet, peerCommands);
|
|
42
74
|
}
|
|
@@ -52,7 +84,7 @@ async function registerAgentsInCodeMode(
|
|
|
52
84
|
adaptToolForCodeMode(tool, {
|
|
53
85
|
prepareInput: (input) => (input === undefined ? {} : input),
|
|
54
86
|
blocking: isBlockingAgentsCall,
|
|
55
|
-
|
|
87
|
+
discovery: "help",
|
|
56
88
|
}),
|
|
57
89
|
]);
|
|
58
90
|
pi.on("session_shutdown", () => {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@howaboua/pi-shepherdr",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.23",
|
|
4
4
|
"description": "Persistent blocking and asynchronous Pi agents through Herdr.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -43,7 +43,7 @@
|
|
|
43
43
|
"pack:dry": "npm pack --dry-run"
|
|
44
44
|
},
|
|
45
45
|
"peerDependencies": {
|
|
46
|
-
"@howaboua/pi-codex-conversion": ">=4.0.
|
|
46
|
+
"@howaboua/pi-codex-conversion": ">=4.0.3",
|
|
47
47
|
"@earendil-works/pi-ai": ">=1.1.0",
|
|
48
48
|
"@earendil-works/pi-coding-agent": ">=1.2.0",
|
|
49
49
|
"@earendil-works/pi-tui": ">=1.1.0",
|
|
@@ -55,10 +55,10 @@
|
|
|
55
55
|
}
|
|
56
56
|
},
|
|
57
57
|
"dependencies": {
|
|
58
|
-
"@howaboua/pi-agent-board": "0.0.
|
|
58
|
+
"@howaboua/pi-agent-board": "0.0.3"
|
|
59
59
|
},
|
|
60
60
|
"devDependencies": {
|
|
61
|
-
"@howaboua/pi-codex-conversion": "4.0.
|
|
61
|
+
"@howaboua/pi-codex-conversion": "4.0.3",
|
|
62
62
|
"@biomejs/biome": "^2.5.15",
|
|
63
63
|
"@earendil-works/pi-ai": "1.3.0",
|
|
64
64
|
"@earendil-works/pi-coding-agent": "1.3.0",
|
package/src/agents-discovery.ts
CHANGED
|
@@ -25,11 +25,13 @@ function describeProfiles(profiles: Map<string, AgentProfile>) {
|
|
|
25
25
|
|
|
26
26
|
export async function agentsHelp(
|
|
27
27
|
boardAvailable = false,
|
|
28
|
+
gpt = false,
|
|
28
29
|
): Promise<Record<string, unknown>> {
|
|
29
30
|
const profiles = await loadAgentProfiles();
|
|
30
31
|
return {
|
|
31
|
-
commands:
|
|
32
|
-
"commands:
|
|
32
|
+
commands: gpt
|
|
33
|
+
? "commands:true lists slash commands/descriptions, never executes. Default this session; target/machine select another"
|
|
34
|
+
: "commands: true lists available slash commands with descriptions; defaults to this session, target and machine optionally select another session; does not execute commands",
|
|
33
35
|
actions: {
|
|
34
36
|
help: "",
|
|
35
37
|
list: "machine?",
|
|
@@ -48,13 +50,14 @@ export async function agentsHelp(
|
|
|
48
50
|
reply: "target extension id message machine?",
|
|
49
51
|
},
|
|
50
52
|
rules: {
|
|
51
|
-
reply:
|
|
52
|
-
"Use
|
|
53
|
+
reply: gpt
|
|
54
|
+
? "Use extension report/read template; send cannot resolve. Blocking waits for resumed work; others return after semantic delivery"
|
|
55
|
+
: "Use the extension-authored template from its report/read; send does not resolve it. Blocking messages wait for resumed work; other replies return after semantic delivery",
|
|
53
56
|
machine:
|
|
54
57
|
"Omit for local (host running Pi); list/find omit for all machines. Remote: profile ID from list, not label/hostname",
|
|
55
58
|
target:
|
|
56
59
|
"Use spawn/find target exactly; /root selects this family's live root",
|
|
57
|
-
label: "
|
|
60
|
+
label: "Short tab/session name; prefer two words when useful",
|
|
58
61
|
...(boardAvailable
|
|
59
62
|
? {
|
|
60
63
|
board_thread_id:
|
|
@@ -62,25 +65,30 @@ export async function agentsHelp(
|
|
|
62
65
|
}
|
|
63
66
|
: {}),
|
|
64
67
|
send: "Message or work update; wakes idle agents, no wait/watch. Close finished workers with /quit, not acknowledgement messages",
|
|
65
|
-
assign:
|
|
66
|
-
"Delegate
|
|
67
|
-
|
|
68
|
-
|
|
68
|
+
assign: gpt
|
|
69
|
+
? "Delegate/update work. Active updates share pending result, never replace existing wait"
|
|
70
|
+
: "Delegate or update work; active updates share its pending result, never replace an existing wait",
|
|
71
|
+
focus: gpt
|
|
72
|
+
? "Running session; passive arrival+return call, no task/watch. voice=false default; true transfers active mic asynchronously. handoff=context. Remote selects target Herdr session, not client machine"
|
|
73
|
+
: "Select a running session; passive arrival with return call, no task/watch. voice defaults false; true carries the active microphone asynchronously. handoff adds context. Remote focus selects the target's Herdr session, not the client's machine",
|
|
69
74
|
attach: boardAvailable
|
|
70
75
|
? "Idle target; context/board booleans choose shared access and board membership independently; no task/watch"
|
|
71
76
|
: "Idle target; context shares notes/history; use board:false while shared boards are unavailable; no task/watch",
|
|
72
77
|
detach:
|
|
73
78
|
"Stop selected membership; retain counterpart checkpoints read-only; idle target",
|
|
74
|
-
blocking:
|
|
75
|
-
"spawn/assign default true; profile
|
|
79
|
+
blocking: gpt
|
|
80
|
+
? "spawn/assign default true; profile overrides spawn. JS cells parallel+wait: await Promise.allSettled. false=continue other work; completion/blockage after reply. No polling/sleep waits"
|
|
81
|
+
: "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",
|
|
76
82
|
share_context:
|
|
77
83
|
"Profile false isolates notes/history; otherwise follows controller sharing setting",
|
|
78
84
|
watch:
|
|
79
85
|
"Delegation and watch keep reporting subsequent work until unwatch or close",
|
|
80
|
-
prompt:
|
|
81
|
-
"
|
|
82
|
-
|
|
83
|
-
|
|
86
|
+
prompt: gpt
|
|
87
|
+
? "Distinct worker scope, outcome, project context, issue references. Define success, not forbidden investigations"
|
|
88
|
+
: "Give each worker a distinct scope, desired outcome, relevant project context and issue references. Describe success rather than lists of forbidden investigations",
|
|
89
|
+
slash: gpt
|
|
90
|
+
? "Leading / routes target commands/skills/templates. Commands skip task waiting including assign/spawn; blocked returns choices. /quit exits Pi and closes pane"
|
|
91
|
+
: "Leading / routes target commands/skills/templates. Commands skip task waiting, even with assign/spawn; blocked commands return available choices. /quit shuts down Pi and closes its pane",
|
|
84
92
|
reuse:
|
|
85
93
|
"Reuse only same investigation; reviews independent; new scope = new agent",
|
|
86
94
|
...(profiles.has("general")
|
package/src/agents-spawn.ts
CHANGED
|
@@ -8,9 +8,9 @@ import {
|
|
|
8
8
|
shouldBlockAgentSpawn,
|
|
9
9
|
} from "./agents-contract.js";
|
|
10
10
|
import {
|
|
11
|
-
allocateAgentName,
|
|
12
11
|
dispatchAgentWork,
|
|
13
12
|
reportProgress,
|
|
13
|
+
reserveAgentName,
|
|
14
14
|
settlementResult,
|
|
15
15
|
toolResult,
|
|
16
16
|
} from "./agents-work.js";
|
|
@@ -65,147 +65,153 @@ export async function spawnAgent(
|
|
|
65
65
|
);
|
|
66
66
|
}
|
|
67
67
|
const label = required(params.label, "label");
|
|
68
|
-
const
|
|
69
|
-
const
|
|
70
|
-
params.placement ??
|
|
71
|
-
(runtime.local && process.env["HERDR_WORKSPACE_ID"]
|
|
72
|
-
? "new_tab"
|
|
73
|
-
: "new_workspace");
|
|
74
|
-
const workspace =
|
|
75
|
-
params.workspace ??
|
|
76
|
-
(placement === "new_tab" && runtime.local
|
|
77
|
-
? process.env["HERDR_WORKSPACE_ID"]
|
|
78
|
-
: undefined);
|
|
79
|
-
const startParams = {
|
|
80
|
-
name,
|
|
81
|
-
label,
|
|
82
|
-
placement,
|
|
83
|
-
...(workspace ? { workspace } : {}),
|
|
84
|
-
...(params.pane ? { pane: params.pane } : {}),
|
|
85
|
-
...(params.cwd ? { cwd: params.cwd } : {}),
|
|
86
|
-
};
|
|
87
|
-
const cwd = await resolvePreparationDirectory(
|
|
88
|
-
runtime.client,
|
|
89
|
-
startParams,
|
|
90
|
-
runtime.fallbackCwd,
|
|
91
|
-
runtime.resolveDirectory,
|
|
92
|
-
);
|
|
93
|
-
const input = required(params.message, "message");
|
|
94
|
-
const message = await prepareProfileMessage(
|
|
95
|
-
profile,
|
|
96
|
-
{
|
|
97
|
-
cwd,
|
|
98
|
-
message: input,
|
|
99
|
-
...(params.base ? { base: params.base } : {}),
|
|
100
|
-
},
|
|
101
|
-
{ targetLocal: runtime.local },
|
|
102
|
-
);
|
|
103
|
-
const attributedMessage = await attributeAgentPrompt(
|
|
104
|
-
fleet.connected().client,
|
|
105
|
-
input.startsWith("/") ? input : message,
|
|
106
|
-
"task",
|
|
107
|
-
);
|
|
108
|
-
if (input.startsWith("/") && message !== input)
|
|
109
|
-
attributedMessage.context = [attributedMessage.context, message]
|
|
110
|
-
.filter(Boolean)
|
|
111
|
-
.join("\n\n");
|
|
112
|
-
if (boardThreadId !== undefined)
|
|
113
|
-
attributedMessage.context = [
|
|
114
|
-
attributedMessage.context,
|
|
115
|
-
`Read shared board thread with board({action:"read_thread",thread_id:${JSON.stringify(boardThreadId)}}) for task context`,
|
|
116
|
-
]
|
|
117
|
-
.filter(Boolean)
|
|
118
|
-
.join("\n\n");
|
|
119
|
-
reportProgress(onUpdate, `Spawning ${label}`, {
|
|
120
|
-
machine: runtime.machine,
|
|
121
|
-
name,
|
|
122
|
-
profile: profile.name,
|
|
123
|
-
status: "starting",
|
|
124
|
-
});
|
|
125
|
-
const agentArgs = profileAgentArgs(profile, { targetLocal: runtime.local });
|
|
126
|
-
const relationship = sharedContext.spawns.prepareRelationship(
|
|
127
|
-
ctx,
|
|
128
|
-
runtime,
|
|
129
|
-
agentArgs,
|
|
130
|
-
);
|
|
131
|
-
const sharing =
|
|
132
|
-
profile.shareContext === false
|
|
133
|
-
? undefined
|
|
134
|
-
: await sharedContext.spawns.prepare(ctx, runtime, name, agentArgs);
|
|
135
|
-
const boardBinding = await board.prepare(ctx, runtime, name, agentArgs);
|
|
136
|
-
const started = await startAgent(
|
|
137
|
-
runtime.client,
|
|
138
|
-
startParams,
|
|
139
|
-
runtime.fallbackCwd,
|
|
140
|
-
runtime.resolveDirectory,
|
|
141
|
-
{ agentArgs },
|
|
142
|
-
);
|
|
143
|
-
let promptSubmissionStarted = false;
|
|
144
|
-
let promptAccepted = false;
|
|
145
|
-
let dispatch;
|
|
146
|
-
let shared: { agentName?: string; warning?: string } | undefined;
|
|
147
|
-
let boardAgent: string | undefined;
|
|
148
|
-
let relationshipWarning: string | undefined;
|
|
149
|
-
const blocking = shouldBlockAgentSpawn(profile.blocking, params.blocking);
|
|
68
|
+
const reservation = await reserveAgentName(runtime, label, params.name);
|
|
69
|
+
const { name } = reservation;
|
|
150
70
|
try {
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
71
|
+
const placement =
|
|
72
|
+
params.placement ??
|
|
73
|
+
(runtime.local && process.env["HERDR_WORKSPACE_ID"]
|
|
74
|
+
? "new_tab"
|
|
75
|
+
: "new_workspace");
|
|
76
|
+
const workspace =
|
|
77
|
+
params.workspace ??
|
|
78
|
+
(placement === "new_tab" && runtime.local
|
|
79
|
+
? process.env["HERDR_WORKSPACE_ID"]
|
|
80
|
+
: undefined);
|
|
81
|
+
const startParams = {
|
|
82
|
+
name,
|
|
83
|
+
label,
|
|
84
|
+
placement,
|
|
85
|
+
...(workspace ? { workspace } : {}),
|
|
86
|
+
...(params.pane ? { pane: params.pane } : {}),
|
|
87
|
+
...(params.cwd ? { cwd: params.cwd } : {}),
|
|
88
|
+
};
|
|
89
|
+
const cwd = await resolvePreparationDirectory(
|
|
90
|
+
runtime.client,
|
|
91
|
+
startParams,
|
|
92
|
+
runtime.fallbackCwd,
|
|
93
|
+
runtime.resolveDirectory,
|
|
94
|
+
);
|
|
95
|
+
const input = required(params.message, "message");
|
|
96
|
+
const message = await prepareProfileMessage(
|
|
97
|
+
profile,
|
|
98
|
+
{
|
|
99
|
+
cwd,
|
|
100
|
+
message: input,
|
|
101
|
+
...(params.base ? { base: params.base } : {}),
|
|
169
102
|
},
|
|
170
|
-
{
|
|
103
|
+
{ targetLocal: runtime.local },
|
|
104
|
+
);
|
|
105
|
+
const attributedMessage = await attributeAgentPrompt(
|
|
106
|
+
fleet.connected().client,
|
|
107
|
+
input.startsWith("/") ? input : message,
|
|
108
|
+
"task",
|
|
109
|
+
);
|
|
110
|
+
if (input.startsWith("/") && message !== input)
|
|
111
|
+
attributedMessage.context = [attributedMessage.context, message]
|
|
112
|
+
.filter(Boolean)
|
|
113
|
+
.join("\n\n");
|
|
114
|
+
if (boardThreadId !== undefined)
|
|
115
|
+
attributedMessage.context = [
|
|
116
|
+
attributedMessage.context,
|
|
117
|
+
`Read shared board thread with board({action:"read_thread",thread_id:${JSON.stringify(boardThreadId)}}) for task context`,
|
|
118
|
+
]
|
|
119
|
+
.filter(Boolean)
|
|
120
|
+
.join("\n\n");
|
|
121
|
+
reportProgress(onUpdate, `Spawning ${label}`, {
|
|
122
|
+
machine: runtime.machine,
|
|
123
|
+
name,
|
|
124
|
+
profile: profile.name,
|
|
125
|
+
status: "starting",
|
|
126
|
+
});
|
|
127
|
+
const agentArgs = profileAgentArgs(profile);
|
|
128
|
+
const relationship = sharedContext.spawns.prepareRelationship(
|
|
129
|
+
ctx,
|
|
130
|
+
runtime,
|
|
131
|
+
agentArgs,
|
|
132
|
+
);
|
|
133
|
+
const sharing =
|
|
134
|
+
profile.shareContext === false
|
|
135
|
+
? undefined
|
|
136
|
+
: await sharedContext.spawns.prepare(ctx, runtime, name, agentArgs);
|
|
137
|
+
const boardBinding = await board.prepare(ctx, runtime, name, agentArgs);
|
|
138
|
+
const started = await startAgent(
|
|
139
|
+
runtime.client,
|
|
140
|
+
startParams,
|
|
141
|
+
runtime.fallbackCwd,
|
|
142
|
+
runtime.resolveDirectory,
|
|
143
|
+
{ agentArgs },
|
|
171
144
|
);
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
145
|
+
let promptSubmissionStarted = false;
|
|
146
|
+
let promptAccepted = false;
|
|
147
|
+
let dispatch;
|
|
148
|
+
let shared: { agentName?: string; warning?: string } | undefined;
|
|
149
|
+
let boardAgent: string | undefined;
|
|
150
|
+
let relationshipWarning: string | undefined;
|
|
151
|
+
const blocking = shouldBlockAgentSpawn(profile.blocking, params.blocking);
|
|
152
|
+
try {
|
|
153
|
+
relationshipWarning = (await relationship?.accept(started.agent))
|
|
154
|
+
?.warning;
|
|
155
|
+
boardAgent = await boardBinding?.accept(started.agent);
|
|
156
|
+
shared = await sharing?.accept(started.agent);
|
|
157
|
+
dispatch = await dispatchAgentWork(
|
|
158
|
+
runtime,
|
|
159
|
+
started.agent,
|
|
160
|
+
message,
|
|
161
|
+
blocking,
|
|
162
|
+
signal,
|
|
163
|
+
onUpdate,
|
|
164
|
+
async () => {
|
|
165
|
+
promptSubmissionStarted = true;
|
|
166
|
+
const receipt = await runtime.client.sendMessage(
|
|
167
|
+
started.agent,
|
|
168
|
+
attributedMessage,
|
|
169
|
+
);
|
|
170
|
+
promptAccepted = true;
|
|
171
|
+
return receipt;
|
|
172
|
+
},
|
|
173
|
+
{ expectUserMessage: true },
|
|
174
|
+
);
|
|
175
|
+
} catch (error) {
|
|
176
|
+
if (
|
|
177
|
+
!promptAccepted &&
|
|
178
|
+
(!promptSubmissionStarted || isDispatchRejected(error))
|
|
179
|
+
) {
|
|
180
|
+
return await rollbackStartedAgent(runtime.client, started, error);
|
|
181
|
+
}
|
|
182
|
+
throw error;
|
|
178
183
|
}
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
...(shared?.agentName ? { contextAgent: shared.agentName } : {}),
|
|
185
|
-
...(dispatch.command
|
|
186
|
-
? {
|
|
187
|
-
spawned: true,
|
|
188
|
-
commandSubmitted: true,
|
|
189
|
-
machine: runtime.machine,
|
|
190
|
-
target: started.id,
|
|
191
|
-
name,
|
|
192
|
-
}
|
|
193
|
-
: dispatch.settlement
|
|
184
|
+
return toolResult(
|
|
185
|
+
{
|
|
186
|
+
...(boardAgent ? { boardAgent } : {}),
|
|
187
|
+
...(shared?.agentName ? { contextAgent: shared.agentName } : {}),
|
|
188
|
+
...(dispatch.command
|
|
194
189
|
? {
|
|
195
190
|
spawned: true,
|
|
196
|
-
|
|
197
|
-
}
|
|
198
|
-
: {
|
|
199
|
-
spawned: true,
|
|
191
|
+
commandSubmitted: true,
|
|
200
192
|
machine: runtime.machine,
|
|
201
193
|
target: started.id,
|
|
202
194
|
name,
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
195
|
+
}
|
|
196
|
+
: dispatch.settlement
|
|
197
|
+
? {
|
|
198
|
+
spawned: true,
|
|
199
|
+
...settlementResult(runtime.machine, dispatch.settlement),
|
|
200
|
+
}
|
|
201
|
+
: {
|
|
202
|
+
spawned: true,
|
|
203
|
+
machine: runtime.machine,
|
|
204
|
+
target: started.id,
|
|
205
|
+
name,
|
|
206
|
+
status: "working",
|
|
207
|
+
next: "Converse, do other work or reply now; completion/blockage arrives even after you reply. No polling or sleep waits",
|
|
208
|
+
}),
|
|
209
|
+
},
|
|
210
|
+
[dispatch.warning, shared?.warning, relationshipWarning]
|
|
211
|
+
.filter(Boolean)
|
|
212
|
+
.join("\n") || undefined,
|
|
213
|
+
);
|
|
214
|
+
} finally {
|
|
215
|
+
reservation.release();
|
|
216
|
+
}
|
|
211
217
|
}
|
package/src/agents-tool.ts
CHANGED
|
@@ -38,19 +38,21 @@ export function createAgentsTool(
|
|
|
38
38
|
board: AgentBoard,
|
|
39
39
|
pi: ExtensionAPI,
|
|
40
40
|
commands: ReturnType<typeof createPeerCommands>,
|
|
41
|
+
gpt: () => boolean = () => false,
|
|
41
42
|
) {
|
|
42
43
|
return defineTool({
|
|
43
44
|
name: "agents",
|
|
44
45
|
label: "Shepherdr",
|
|
45
|
-
description: "Delegate to persistent agents
|
|
46
|
+
description: "Delegate to persistent agents",
|
|
47
|
+
promptGuidelines: ["Make the first agents discovery call alone"],
|
|
46
48
|
parameters: AgentsParameters,
|
|
47
|
-
executionMode: "
|
|
49
|
+
executionMode: "parallel",
|
|
48
50
|
async execute(_toolCallId, input: AgentsToolParams, signal, onUpdate, ctx) {
|
|
49
51
|
const params = parseAgentsRequest(input);
|
|
50
52
|
const executionSignal = signal ?? new AbortController().signal;
|
|
51
53
|
const update = onUpdate ?? (() => undefined);
|
|
52
54
|
if (params.action === "help" && !params.commands) {
|
|
53
|
-
return toolResult(await agentsHelp(board.enabled(ctx)));
|
|
55
|
+
return toolResult(await agentsHelp(board.enabled(ctx), gpt()));
|
|
54
56
|
}
|
|
55
57
|
if (params.commands && params.target === undefined)
|
|
56
58
|
return toolResult({ commands: commands.available() });
|
|
@@ -242,7 +244,7 @@ export function createAgentsTool(
|
|
|
242
244
|
params?.name ??
|
|
243
245
|
params?.agent_type ??
|
|
244
246
|
"";
|
|
245
|
-
|
|
247
|
+
const title = new Text(
|
|
246
248
|
theme.fg(
|
|
247
249
|
context && "isBlocked" in context && context.isBlocked === true
|
|
248
250
|
? "warning"
|
|
@@ -252,6 +254,13 @@ export function createAgentsTool(
|
|
|
252
254
|
0,
|
|
253
255
|
0,
|
|
254
256
|
);
|
|
257
|
+
const message = params?.message ?? params?.handoff;
|
|
258
|
+
if (!context?.expanded || !message) return title;
|
|
259
|
+
const container = new Container();
|
|
260
|
+
container.addChild(title);
|
|
261
|
+
container.addChild(new Spacer(1));
|
|
262
|
+
container.addChild(new Text(message, 0, 0));
|
|
263
|
+
return container;
|
|
255
264
|
},
|
|
256
265
|
renderResult(toolResult, options, theme) {
|
|
257
266
|
const details =
|
package/src/agents-work.ts
CHANGED
|
@@ -2,7 +2,7 @@ import type { AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
|
|
|
2
2
|
import { activityTask } from "./activity.js";
|
|
3
3
|
import type { ConnectedMachine } from "./fleet.js";
|
|
4
4
|
import { getSnapshot } from "./herdr.js";
|
|
5
|
-
import { isDispatchRejected } from "./herdr-client.js";
|
|
5
|
+
import { type HerdrConnection, isDispatchRejected } from "./herdr-client.js";
|
|
6
6
|
import { agentSource } from "./messages.js";
|
|
7
7
|
import type { WorkAttempt } from "./monitor-state.js";
|
|
8
8
|
import type { ClaimedSettlement } from "./settlement.js";
|
|
@@ -38,14 +38,38 @@ function slugify(value: string): string {
|
|
|
38
38
|
return named.slice(0, 32).replace(/-+$/u, "") || "agent";
|
|
39
39
|
}
|
|
40
40
|
|
|
41
|
-
|
|
41
|
+
const startingNames = new WeakMap<HerdrConnection, Set<string>>();
|
|
42
|
+
|
|
43
|
+
export async function reserveAgentName(
|
|
42
44
|
runtime: ConnectedMachine,
|
|
43
45
|
label: string,
|
|
44
|
-
|
|
46
|
+
requested?: string,
|
|
47
|
+
): Promise<{ name: string; release(): void }> {
|
|
45
48
|
const snapshot = await getSnapshot(runtime.client);
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
+
let reserved = startingNames.get(runtime.client);
|
|
50
|
+
if (!reserved) {
|
|
51
|
+
reserved = new Set<string>();
|
|
52
|
+
startingNames.set(runtime.client, reserved);
|
|
53
|
+
}
|
|
54
|
+
const names = new Set([
|
|
55
|
+
...snapshot.agents.flatMap((agent) => (agent.name ? [agent.name] : [])),
|
|
56
|
+
...reserved,
|
|
57
|
+
]);
|
|
58
|
+
const name = requested?.trim() || availableAgentName(names, label);
|
|
59
|
+
if (names.has(name))
|
|
60
|
+
throw new Error(
|
|
61
|
+
`Agent name ${JSON.stringify(name)} is already in use; omit name or choose another`,
|
|
62
|
+
);
|
|
63
|
+
reserved.add(name);
|
|
64
|
+
return {
|
|
65
|
+
name,
|
|
66
|
+
release: () => {
|
|
67
|
+
reserved.delete(name);
|
|
68
|
+
},
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
function availableAgentName(names: ReadonlySet<string>, label: string): string {
|
|
49
73
|
const base = slugify(label);
|
|
50
74
|
if (!names.has(base)) return base;
|
|
51
75
|
for (let suffix = 2; suffix < 10_000; suffix += 1) {
|