@howaboua/pi-shepherdr 0.2.23 → 0.2.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/CHANGELOG.md +20 -18
  2. package/README.md +80 -69
  3. package/biome.json +1 -1
  4. package/index.ts +4 -2
  5. package/package.json +14 -9
  6. package/src/agents-contract.ts +9 -6
  7. package/src/agents-discovery.ts +78 -37
  8. package/src/agents-focus.ts +17 -11
  9. package/src/agents-reply.ts +1 -1
  10. package/src/agents-spawn.ts +24 -8
  11. package/src/agents-tool.ts +26 -8
  12. package/src/agents-work.ts +5 -5
  13. package/src/attachment-notes.ts +14 -2
  14. package/src/attachment-protocol.ts +21 -4
  15. package/src/attachment-routing.ts +1 -1
  16. package/src/attachment-target.ts +5 -2
  17. package/src/attachment.ts +4 -3
  18. package/src/board/host.ts +5 -3
  19. package/src/board/membership.ts +1 -1
  20. package/src/close-idle.ts +89 -0
  21. package/src/{control-panel-actions.ts → control-panel/actions.ts} +2 -2
  22. package/src/{control-panel.ts → control-panel/index.ts} +7 -5
  23. package/src/{control-panel-items.ts → control-panel/items.ts} +17 -5
  24. package/src/{control-panel-view.ts → control-panel/view.ts} +9 -5
  25. package/src/controller.ts +17 -5
  26. package/src/core/AGENTS.md +5 -0
  27. package/src/core/backend.ts +266 -0
  28. package/src/core/client.ts +249 -0
  29. package/src/core/context-relay.mjs +111 -0
  30. package/src/core/focus-channel-helper.mjs +165 -0
  31. package/src/core/focus-channel-stream.ts +140 -0
  32. package/src/core/focus-channel-wire.mjs +160 -0
  33. package/src/core/focus-channel.ts +213 -0
  34. package/src/core/focus-window.ts +192 -0
  35. package/src/core/pi-executable.mjs +34 -0
  36. package/src/core/protocol.ts +116 -0
  37. package/src/core/registration.ts +51 -0
  38. package/src/core/remote-endpoint.ts +119 -0
  39. package/src/core/remote-exec.ts +122 -0
  40. package/src/core/remote-helper.mjs +244 -0
  41. package/src/core/remote-reader.ts +67 -0
  42. package/src/core/remote-relay.ts +191 -0
  43. package/src/core/request.ts +124 -0
  44. package/src/core/spawn.ts +177 -0
  45. package/src/core/status.ts +68 -0
  46. package/src/core/terminal.ts +103 -0
  47. package/src/fleet/catalog.ts +83 -0
  48. package/src/fleet/connection.ts +111 -0
  49. package/src/fleet/index.ts +413 -0
  50. package/src/fleet/inspection.ts +159 -0
  51. package/src/fleet/machine.ts +55 -0
  52. package/src/fleet/monitor.ts +85 -0
  53. package/src/fleet/persistence.ts +65 -0
  54. package/src/fleet/reconnect.ts +75 -0
  55. package/src/fleet/setup.ts +133 -0
  56. package/src/herdr.ts +25 -5
  57. package/src/launch-contract.ts +48 -0
  58. package/src/launch-location.ts +151 -0
  59. package/src/launch.ts +30 -183
  60. package/src/messages/attachments.ts +39 -0
  61. package/src/messages/attribution.ts +84 -0
  62. package/src/messages/event-details.ts +69 -0
  63. package/src/messages/events.ts +195 -0
  64. package/src/messages/focus.ts +47 -0
  65. package/src/messages/guidance.ts +83 -0
  66. package/src/messages/render.ts +89 -0
  67. package/src/messages/voice-announcements.ts +79 -0
  68. package/src/monitor-record.ts +9 -6
  69. package/src/monitor.ts +33 -2
  70. package/src/peer-commands.ts +11 -0
  71. package/src/peer-inbox-delivery.ts +171 -0
  72. package/src/peer-inbox-focus.ts +113 -0
  73. package/src/peer-inbox.ts +127 -209
  74. package/src/remote/client.ts +127 -0
  75. package/src/remote/context-relay.ts +84 -0
  76. package/src/remote/deployment.ts +179 -0
  77. package/src/remote/focus-channels.ts +89 -0
  78. package/src/remote/shepherdr-context.mjs +1 -1
  79. package/src/remote/shepherdr-peer.mjs +18 -5
  80. package/src/remote/shepherdr-session.mjs +9 -2
  81. package/src/remote/shepherdr.mjs +1 -1
  82. package/src/remote/transport.ts +369 -0
  83. package/src/settlement/collector.ts +122 -0
  84. package/src/settlement/delivery.ts +144 -0
  85. package/src/{settlement.ts → settlement/index.ts} +35 -233
  86. package/src/shared-context-host.ts +40 -14
  87. package/src/shared-context.ts +44 -6
  88. package/src/spawn-context.ts +24 -17
  89. package/src/spawn-ownership.ts +91 -0
  90. package/src/types.ts +9 -5
  91. package/src/voice-handoff.ts +1 -1
  92. package/src/worker-ownership.ts +92 -0
  93. package/src/worker-service.ts +14 -83
  94. package/src/fleet.ts +0 -702
  95. package/src/messages.ts +0 -637
  96. package/src/remote-client.ts +0 -761
@@ -1,5 +1,5 @@
1
1
  import type { AgentsParams, READ_SOURCES } from "./agents-contract.js";
2
- import type { AgentFleet, ConnectedMachine } from "./fleet.js";
2
+ import type { AgentFleet, ConnectedMachine } from "./fleet/index.js";
3
3
  import { type AgentProfile, loadAgentProfiles } from "./profiles.js";
4
4
  import type { AgentStatus, PaneInfo, SessionSnapshot } from "./types.js";
5
5
 
@@ -26,11 +26,12 @@ function describeProfiles(profiles: Map<string, AgentProfile>) {
26
26
  export async function agentsHelp(
27
27
  boardAvailable = false,
28
28
  gpt = false,
29
+ core = false,
29
30
  ): Promise<Record<string, unknown>> {
30
31
  const profiles = await loadAgentProfiles();
31
32
  return {
32
33
  commands: gpt
33
- ? "commands:true lists slash commands/descriptions, never executes. Default this session; target/machine select another"
34
+ ? "commands:true lists slash commands/descriptions, NEVER executes; default=this session; target/machine→another"
34
35
  : "commands: true lists available slash commands with descriptions; defaults to this session, target and machine optionally select another session; does not execute commands",
35
36
  actions: {
36
37
  help: "",
@@ -51,46 +52,66 @@ export async function agentsHelp(
51
52
  },
52
53
  rules: {
53
54
  reply: gpt
54
- ? "Use extension report/read template; send cannot resolve. Blocking waits for resumed work; others return after semantic delivery"
55
+ ? "Extension report/read template required; send≠resolve; blocking waits resumed work; others return after semantic delivery"
55
56
  : "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",
56
- machine:
57
- "Omit for local (host running Pi); list/find omit for all machines. Remote: profile ID from list, not label/hostname",
58
- target:
59
- "Use spawn/find target exactly; /root selects this family's live root",
60
- label: "Short tab/session name; prefer two words when useful",
57
+ machine: gpt
58
+ ? "machine omitted=local Pi host; list/find omitted=all machines; remote=list profile ID, NOT label/hostname"
59
+ : "Omit for local (host running Pi); list/find omit for all machines. Remote: profile ID from list, not label/hostname",
60
+ target: gpt
61
+ ? "spawn/find target EXACT; /root=this family live root"
62
+ : "Use spawn/find target exactly; /root selects this family's live root",
63
+ label: core
64
+ ? "Short Pi session name; app tabs use default names"
65
+ : gpt
66
+ ? "Short tab/session name; two words IF useful"
67
+ : "Short tab/session name; prefer two words when useful",
68
+ placement: core
69
+ ? "terminal (default), new_tab, new_workspace; new_tab needs space ID"
70
+ : "new_tab, new_workspace, pane",
61
71
  ...(boardAvailable
62
72
  ? {
63
- board_thread_id:
64
- "Existing shared-board thread; child receives a read reference",
73
+ board_thread_id: gpt
74
+ ? "Existing board thread→child read ref"
75
+ : "Existing shared-board thread; child receives a read reference",
65
76
  }
66
77
  : {}),
67
- send: "Message or work update; wakes idle agents, no wait/watch. Close finished workers with /quit, not acknowledgement messages",
78
+ send: gpt
79
+ ? "/quit next→NO preceding message; sends wake idle agents; NO wait/watch"
80
+ : "When closing an agent, send /quit without another message first. Messages wake idle agents. No waiting or watching.",
68
81
  assign: gpt
69
- ? "Delegate/update work. Active updates share pending result, never replace existing wait"
82
+ ? "Delegate/update work; active→share pending result, NEVER replace wait"
70
83
  : "Delegate or update work; active updates share its pending result, never replace an existing wait",
71
84
  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"
85
+ ? "Running session; passive arrival+return call, NO task/watch; voice default false, true=async active mic transfer; handoff=context; remote=target Herdr session≠client machine"
73
86
  : "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",
74
87
  attach: boardAvailable
75
- ? "Idle target; context/board booleans choose shared access and board membership independently; no task/watch"
76
- : "Idle target; context shares notes/history; use board:false while shared boards are unavailable; no task/watch",
77
- detach:
78
- "Stop selected membership; retain counterpart checkpoints read-only; idle target",
88
+ ? gpt
89
+ ? "Idle target; context/board=independent sharing/membership; NO task/watch"
90
+ : "Idle target; context/board booleans choose shared access and board membership independently; no task/watch"
91
+ : gpt
92
+ ? "Idle target; context=shared notes/history; boards unavailable→board:false; NO task/watch"
93
+ : "Idle target; context shares notes/history; use board:false while shared boards are unavailable; no task/watch",
94
+ detach: gpt
95
+ ? "Idle target; stop selected membership; counterpart checkpoints remain readonly"
96
+ : "Stop selected membership; retain counterpart checkpoints read-only; idle target",
79
97
  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",
82
- share_context:
83
- "Profile false isolates notes/history; otherwise follows controller sharing setting",
84
- watch:
85
- "Delegation and watch keep reporting subsequent work until unwatch or close",
98
+ ? "spawn/assign default true; profile overrides spawn; await blocking calls; JS parallel: await Promise.allSettled; false ONLY if other work continues; background reports automatic→do other work/end turn, NO poll or await timers/extra Promises"
99
+ : "spawn/assign default true; profile blocking overrides spawn. Await blocking calls; use await Promise.allSettled for parallel calls, including failures. Use false only to continue other work. Background reports arrive automatically: do other work or end this turn, never poll or await timers or extra Promises for reports",
100
+ share_context: gpt
101
+ ? "Profile false→isolated notes/history; otherwise→controller sharing setting"
102
+ : "Profile false isolates notes/history; otherwise follows controller sharing setting",
103
+ watch: gpt
104
+ ? "Delegation/watch→report subsequent work UNTIL unwatch/close"
105
+ : "Delegation and watch keep reporting subsequent work until unwatch or close",
86
106
  prompt: gpt
87
- ? "Distinct worker scope, outcome, project context, issue references. Define success, not forbidden investigations"
107
+ ? "Distinct scope/outcome/project context/issue refs; define success, NOT forbidden investigations"
88
108
  : "Give each worker a distinct scope, desired outcome, relevant project context and issue references. Describe success rather than lists of forbidden investigations",
89
109
  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"
110
+ ? "Leading / routes target commands/skills/templates; commands skip task wait EVEN assign/spawn; blocked→choices; /quit exits Pi+closes pane"
91
111
  : "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",
92
- reuse:
93
- "Reuse only same investigation; reviews independent; new scope = new agent",
112
+ reuse: gpt
113
+ ? "Reuse ONLY same investigation; reviews independent; new scope=new agent"
114
+ : "Reuse only same investigation; reviews independent; new scope = new agent",
94
115
  ...(profiles.has("general")
95
116
  ? {
96
117
  general: "Only when requested/orchestrating",
@@ -98,7 +119,9 @@ export async function agentsHelp(
98
119
  : {}),
99
120
  },
100
121
  profiles: describeProfiles(profiles),
101
- advanced: "herdr --skill: workspace/tab/pane/process/focus/layout/terminal",
122
+ advanced: core
123
+ ? "hc --skill: terminal processes and machines"
124
+ : "herdr --skill: workspace/tab/pane/process/focus/layout/terminal",
102
125
  };
103
126
  }
104
127
 
@@ -126,13 +149,23 @@ function compactAgent(
126
149
  machine,
127
150
  target: agent.pane_id,
128
151
  ...(agent.name ? { name: agent.name } : {}),
129
- ...(agent.label || names.panes.get(agent.pane_id)
130
- ? { label: agent.label ?? names.panes.get(agent.pane_id) }
152
+ ...(agent.label || names.panes.get(agent.pane_id) || agent.title
153
+ ? { label: agent.label || names.panes.get(agent.pane_id) || agent.title }
154
+ : {}),
155
+ ...(agent.title && (agent.label || names.panes.get(agent.pane_id))
156
+ ? { title: agent.title }
131
157
  : {}),
132
158
  status: agent.agent_status,
133
159
  cwd: agent.foreground_cwd ?? agent.cwd ?? null,
134
- workspace: names.workspaces.get(agent.workspace_id) ?? agent.workspace_id,
135
- tab: names.tabs.get(agent.tab_id) ?? agent.tab_id,
160
+ ...(agent.workspace_id
161
+ ? {
162
+ workspace:
163
+ names.workspaces.get(agent.workspace_id) ?? agent.workspace_id,
164
+ }
165
+ : {}),
166
+ ...(agent.tab_id
167
+ ? { tab: names.tabs.get(agent.tab_id) ?? agent.tab_id }
168
+ : {}),
136
169
  monitored,
137
170
  };
138
171
  }
@@ -144,11 +177,15 @@ function matchesAgent(
144
177
  ): boolean {
145
178
  if (status && agent["status"] !== status) return false;
146
179
  if (!query) return true;
147
- const haystack = Object.values(agent)
180
+ const normalize = (value: string) =>
181
+ value
182
+ .toLowerCase()
183
+ .replace(/[-_\s]+/g, " ")
184
+ .trim();
185
+ const needle = normalize(query);
186
+ return Object.values(agent)
148
187
  .filter((value) => typeof value === "string")
149
- .join("\n")
150
- .toLowerCase();
151
- return haystack.includes(query.toLowerCase());
188
+ .some((value) => normalize(value).includes(needle));
152
189
  }
153
190
 
154
191
  export async function listFleetAgents(
@@ -165,7 +202,11 @@ export async function listFleetAgents(
165
202
  .filter(
166
203
  (agent) =>
167
204
  agent.agent === "pi" &&
168
- (!machine.local || agent.pane_id !== process.env["HERDR_PANE_ID"]),
205
+ (!machine.local ||
206
+ agent.pane_id !==
207
+ (agent.backend === "core"
208
+ ? process.env["HC_TERMINAL_ID"]
209
+ : process.env["HERDR_PANE_ID"])),
169
210
  )
170
211
  .map((agent) =>
171
212
  compactAgent(
@@ -7,7 +7,7 @@ import {
7
7
  recordContextBriefing,
8
8
  registerContextBriefing,
9
9
  } from "@howaboua/pi-agent-board/integration";
10
- import type { AgentFleet, ConnectedMachine } from "./fleet.js";
10
+ import type { AgentFleet, ConnectedMachine } from "./fleet/index.js";
11
11
  import {
12
12
  getAgent,
13
13
  getCurrentPane,
@@ -15,7 +15,7 @@ import {
15
15
  sessionPath,
16
16
  } from "./herdr.js";
17
17
  import { isDispatchRejected } from "./herdr-client.js";
18
- import { focusArrivalContent } from "./messages.js";
18
+ import { focusArrivalContent } from "./messages/focus.js";
19
19
  import type { FocusRequest, PaneInfo } from "./types.js";
20
20
  import { activeVoiceService, observeVoiceTransfer } from "./voice-handoff.js";
21
21
 
@@ -52,7 +52,9 @@ export async function focusAgent(
52
52
  const request: FocusRequest = {
53
53
  source: {
54
54
  ...(await local.client.machineIdentity()),
55
- pane: source.pane_id,
55
+ ...(source.backend === "core"
56
+ ? { backend: "core" as const }
57
+ : { pane: source.pane_id }),
56
58
  terminal: source.terminal_id,
57
59
  sessionFile,
58
60
  },
@@ -106,13 +108,7 @@ export function readFocus(value: unknown): FocusRequest {
106
108
  )
107
109
  throw new Error("Invalid focus source");
108
110
  const source = value.source as Record<string, unknown>;
109
- for (const field of [
110
- "host",
111
- "session",
112
- "pane",
113
- "terminal",
114
- "sessionFile",
115
- ] as const) {
111
+ for (const field of ["host", "session", "terminal", "sessionFile"] as const) {
116
112
  if (
117
113
  !(field in source) ||
118
114
  typeof source[field] !== "string" ||
@@ -120,6 +116,13 @@ export function readFocus(value: unknown): FocusRequest {
120
116
  )
121
117
  throw new Error("Invalid focus source");
122
118
  }
119
+ if (source["backend"] !== undefined && source["backend"] !== "core")
120
+ throw new Error("Invalid focus backend");
121
+ if (
122
+ source["backend"] !== "core" &&
123
+ (typeof source["pane"] !== "string" || !source["pane"].trim())
124
+ )
125
+ throw new Error("Invalid focus pane");
123
126
  if ("handoff" in value && typeof value.handoff !== "string")
124
127
  throw new Error("Invalid focus handoff");
125
128
  if ("voice" in value && typeof value.voice !== "boolean")
@@ -150,7 +153,10 @@ export async function acceptFocus(
150
153
  const identity = await runtime.client.machineIdentity();
151
154
  if (identity.host !== source.host || identity.session !== source.session)
152
155
  continue;
153
- const agent = await getAgent(runtime.client, source.pane);
156
+ const agent = await getAgent(
157
+ runtime.client,
158
+ source.backend === "core" ? source.terminal : source.pane!,
159
+ );
154
160
  if (
155
161
  agent.agent === "pi" &&
156
162
  agent.terminal_id === source.terminal &&
@@ -5,7 +5,7 @@ import {
5
5
  settlementResult,
6
6
  toolResult,
7
7
  } from "./agents-work.js";
8
- import type { ConnectedMachine } from "./fleet.js";
8
+ import type { ConnectedMachine } from "./fleet/index.js";
9
9
  import type { PaneInfo } from "./types.js";
10
10
 
11
11
  export async function replyAgent(
@@ -1,5 +1,6 @@
1
1
  import type {
2
2
  AgentToolUpdateCallback,
3
+ ExtensionAPI,
3
4
  ExtensionContext,
4
5
  } from "@earendil-works/pi-coding-agent";
5
6
  import {
@@ -15,22 +16,25 @@ import {
15
16
  toolResult,
16
17
  } from "./agents-work.js";
17
18
  import type { AgentBoard } from "./board/host.js";
18
- import type { AgentFleet, ConnectedMachine } from "./fleet.js";
19
+ import { CoreConnection } from "./core/backend.js";
20
+ import type { AgentFleet, ConnectedMachine } from "./fleet/index.js";
19
21
  import { isDispatchRejected } from "./herdr-client.js";
20
22
  import {
21
23
  resolvePreparationDirectory,
22
24
  rollbackStartedAgent,
23
25
  startAgent,
24
26
  } from "./launch.js";
25
- import { attributeAgentPrompt } from "./messages.js";
27
+ import { attributeAgentPrompt } from "./messages/attribution.js";
26
28
  import {
27
29
  loadAgentProfiles,
28
30
  prepareProfileMessage,
29
31
  profileAgentArgs,
30
32
  } from "./profiles.js";
31
33
  import type { SharedAgentContext } from "./shared-context.js";
34
+ import { prepareSpawnOwnership } from "./spawn-ownership.js";
32
35
 
33
36
  export async function spawnAgent(
37
+ pi: ExtensionAPI,
34
38
  fleet: AgentFleet,
35
39
  runtime: ConnectedMachine,
36
40
  params: AgentsParams,
@@ -40,6 +44,7 @@ export async function spawnAgent(
40
44
  ctx: ExtensionContext,
41
45
  board: AgentBoard,
42
46
  ) {
47
+ const recordSpawn = prepareSpawnOwnership(pi, ctx, runtime);
43
48
  const boardThreadId =
44
49
  params.board_thread_id === undefined
45
50
  ? undefined
@@ -70,9 +75,11 @@ export async function spawnAgent(
70
75
  try {
71
76
  const placement =
72
77
  params.placement ??
73
- (runtime.local && process.env["HERDR_WORKSPACE_ID"]
74
- ? "new_tab"
75
- : "new_workspace");
78
+ (runtime.client instanceof CoreConnection
79
+ ? "terminal"
80
+ : runtime.local && process.env["HERDR_WORKSPACE_ID"]
81
+ ? "new_tab"
82
+ : "new_workspace");
76
83
  const workspace =
77
84
  params.workspace ??
78
85
  (placement === "new_tab" && runtime.local
@@ -150,6 +157,7 @@ export async function spawnAgent(
150
157
  let relationshipWarning: string | undefined;
151
158
  const blocking = shouldBlockAgentSpawn(profile.blocking, params.blocking);
152
159
  try {
160
+ await recordSpawn(started.agent, agentArgs);
153
161
  relationshipWarning = (await relationship?.accept(started.agent))
154
162
  ?.warning;
155
163
  boardAgent = await boardBinding?.accept(started.agent);
@@ -183,8 +191,6 @@ export async function spawnAgent(
183
191
  }
184
192
  return toolResult(
185
193
  {
186
- ...(boardAgent ? { boardAgent } : {}),
187
- ...(shared?.agentName ? { contextAgent: shared.agentName } : {}),
188
194
  ...(dispatch.command
189
195
  ? {
190
196
  spawned: true,
@@ -204,8 +210,18 @@ export async function spawnAgent(
204
210
  target: started.id,
205
211
  name,
206
212
  status: "working",
207
- next: "Converse, do other work or reply now; completion/blockage arrives even after you reply. No polling or sleep waits",
213
+ next: "Do other work or end this turn; completion/blockage arrives automatically. Do not poll or await timers/extra Promises for reports",
208
214
  }),
215
+ ...(boardAgent || shared?.agentName
216
+ ? {
217
+ sharing: {
218
+ ...(boardAgent ? { boardAgent } : {}),
219
+ ...(shared?.agentName
220
+ ? { contextAgent: shared.agentName }
221
+ : {}),
222
+ },
223
+ }
224
+ : {}),
209
225
  },
210
226
  [dispatch.warning, shared?.warning, relationshipWarning]
211
227
  .filter(Boolean)
@@ -26,9 +26,10 @@ import {
26
26
  toolResult,
27
27
  } from "./agents-work.js";
28
28
  import type { AgentBoard } from "./board/host.js";
29
- import type { AgentFleet } from "./fleet.js";
29
+ import { CoreConnection } from "./core/backend.js";
30
+ import type { AgentFleet } from "./fleet/index.js";
30
31
  import { resolvePiAgent } from "./herdr.js";
31
- import { attributeAgentPrompt } from "./messages.js";
32
+ import { attributeAgentPrompt } from "./messages/attribution.js";
32
33
  import type { createPeerCommands } from "./peer-commands.js";
33
34
  import type { SharedAgentContext } from "./shared-context.js";
34
35
 
@@ -43,8 +44,9 @@ export function createAgentsTool(
43
44
  return defineTool({
44
45
  name: "agents",
45
46
  label: "Shepherdr",
46
- description: "Delegate to persistent agents",
47
- promptGuidelines: ["Make the first agents discovery call alone"],
47
+ description:
48
+ "Delegate to persistent agents; {} lists additional action fields",
49
+ promptGuidelines: ["Read agents help alone before first use"],
48
50
  parameters: AgentsParameters,
49
51
  executionMode: "parallel",
50
52
  async execute(_toolCallId, input: AgentsToolParams, signal, onUpdate, ctx) {
@@ -52,7 +54,16 @@ export function createAgentsTool(
52
54
  const executionSignal = signal ?? new AbortController().signal;
53
55
  const update = onUpdate ?? (() => undefined);
54
56
  if (params.action === "help" && !params.commands) {
55
- return toolResult(await agentsHelp(board.enabled(ctx), gpt()));
57
+ return toolResult(
58
+ await agentsHelp(
59
+ board.enabled(ctx),
60
+ gpt(),
61
+ Boolean(
62
+ process.env["HC_TERMINAL_ID"] &&
63
+ process.env["HC_TERMINAL_SOCKET"],
64
+ ),
65
+ ),
66
+ );
56
67
  }
57
68
  if (params.commands && params.target === undefined)
58
69
  return toolResult({ commands: commands.available() });
@@ -66,6 +77,7 @@ export function createAgentsTool(
66
77
  let runtime = fleet.connected(params.machine);
67
78
  if (params.action === "spawn") {
68
79
  return spawnAgent(
80
+ pi,
69
81
  fleet,
70
82
  runtime,
71
83
  params,
@@ -123,7 +135,13 @@ export function createAgentsTool(
123
135
  const panel = await resolvePiAgent(
124
136
  runtime.client,
125
137
  target,
126
- runtime.local ? process.env["HERDR_PANE_ID"] : "",
138
+ runtime.local
139
+ ? process.env[
140
+ runtime.client instanceof CoreConnection
141
+ ? "HC_TERMINAL_ID"
142
+ : "HERDR_PANE_ID"
143
+ ]
144
+ : "",
127
145
  );
128
146
  if (params.commands) {
129
147
  return toolResult({
@@ -149,7 +167,7 @@ export function createAgentsTool(
149
167
  watched: true,
150
168
  machine: runtime.machine,
151
169
  target: panel.pane_id,
152
- next: "Completion or blockage will be delivered automatically; do not poll",
170
+ next: "Do other work or end this turn; completion/blockage arrives automatically. Do not poll or await timers/extra Promises for reports",
153
171
  });
154
172
  }
155
173
  if (params.action === "read") {
@@ -221,7 +239,7 @@ export function createAgentsTool(
221
239
  machine: runtime.machine,
222
240
  target: panel.pane_id,
223
241
  status: "working",
224
- next: "Converse, do other work or reply now; completion/blockage arrives even after you reply. No polling or sleep waits",
242
+ next: "Do other work or end this turn; completion/blockage arrives automatically. Do not poll or await timers/extra Promises for reports",
225
243
  },
226
244
  dispatch.warning,
227
245
  );
@@ -1,11 +1,11 @@
1
1
  import type { AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
2
2
  import { activityTask } from "./activity.js";
3
- import type { ConnectedMachine } from "./fleet.js";
3
+ import type { ConnectedMachine } from "./fleet/index.js";
4
4
  import { getSnapshot } from "./herdr.js";
5
5
  import { type HerdrConnection, isDispatchRejected } from "./herdr-client.js";
6
- import { agentSource } from "./messages.js";
6
+ import { agentSource } from "./messages/attribution.js";
7
7
  import type { WorkAttempt } from "./monitor-state.js";
8
- import type { ClaimedSettlement } from "./settlement.js";
8
+ import type { ClaimedSettlement } from "./settlement/index.js";
9
9
  import type { ExtensionReply, PaneInfo, PeerDelivery } from "./types.js";
10
10
 
11
11
  export function toolResult(value: Record<string, unknown>, warning?: string) {
@@ -93,13 +93,13 @@ export function settlementResult(
93
93
  `${settlement.agent.pane_id} assistant stopped with an error`
94
94
  : undefined;
95
95
  if (workerError && !options.reportWorkerError) throw new Error(workerError);
96
- const { pane, name, ...source } = agentSource(
96
+ const { pane, terminal, name, ...source } = agentSource(
97
97
  settlement.agent,
98
98
  settlement.labels,
99
99
  );
100
100
  return {
101
101
  machine,
102
- target: pane,
102
+ target: pane ?? terminal,
103
103
  ...(name ? { name } : {}),
104
104
  source,
105
105
  status: settlement.status,
@@ -4,7 +4,7 @@ import type {
4
4
  ContextSharingService,
5
5
  SharedContextRequest,
6
6
  SharedContextResult,
7
- } from "@howaboua/pi-codex-conversion/context-sharing";
7
+ } from "@howaboua/pi-notes-compaction/context-sharing";
8
8
 
9
9
  /** Read-only continuity when a live owner disappears. Parsing remains Conversion-owned. */
10
10
  export class AttachmentNotes {
@@ -174,7 +174,19 @@ export class AttachmentNotes {
174
174
  }),
175
175
  };
176
176
  return {
177
- content: [{ type: "text", text: JSON.stringify(details) }],
177
+ content: [
178
+ ...result.content,
179
+ {
180
+ type: "text",
181
+ text: `Read-only checkpoints captured ${details.captured_at}.${
182
+ detached
183
+ ? " Counterpart detached."
184
+ : unavailable
185
+ ? " Live owner and saved updates unavailable; these checkpoints may be stale. Resume the counterpart for current notes."
186
+ : " Live owner unavailable; reading saved checkpoints."
187
+ }`,
188
+ },
189
+ ],
178
190
  details: { codexHistoryNotes: details },
179
191
  };
180
192
  }
@@ -2,7 +2,7 @@ import { isDeepStrictEqual } from "node:util";
2
2
  import { Type } from "@earendil-works/pi-ai";
3
3
  import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
4
4
  import { BindingSchema } from "@howaboua/pi-agent-board/integration";
5
- import type { SharedContextResult } from "@howaboua/pi-codex-conversion/context-sharing";
5
+ import type { SharedContextResult } from "@howaboua/pi-notes-compaction/context-sharing";
6
6
  import type { Static, TSchema } from "typebox";
7
7
  import { Check } from "typebox/value";
8
8
 
@@ -115,8 +115,7 @@ export function remapResult(
115
115
  typeof result.details.codexHistoryNotes["encrypted_output"] === "string" ||
116
116
  ("externalNotesResponses" in result.details &&
117
117
  Array.isArray(result.details.externalNotesResponses) &&
118
- result.details.externalNotesResponses.length > 0) ||
119
- Object.keys(result.details.codexHistoryNotes).length === 0
118
+ result.details.externalNotesResponses.length > 0)
120
119
  ) {
121
120
  const hint = `Source ${from}, access through ${to}. Use ${to}/notes for note paths and ${to} for history agent_name`;
122
121
  // Ciphertext paths cannot be remapped. Preserve host-only provenance on the original details.
@@ -135,7 +134,25 @@ export function remapResult(
135
134
  ) as Record<string, unknown>;
136
135
  return {
137
136
  ...result,
138
- content: [{ type: "text", text: JSON.stringify(details) }],
137
+ // Remap the public payload, never regenerate it from private receipts.
138
+ content: result.content.map((item) => {
139
+ if (item.type !== "text") return item;
140
+ try {
141
+ return {
142
+ ...item,
143
+ text: JSON.stringify(
144
+ JSON.parse(item.text, (key, value: unknown) =>
145
+ (key === "path" || key === "agent_name") &&
146
+ typeof value === "string"
147
+ ? remap(value, from, to)
148
+ : value,
149
+ ),
150
+ ),
151
+ };
152
+ } catch {
153
+ return item;
154
+ }
155
+ }),
139
156
  details: { ...result.details, codexHistoryNotes: details },
140
157
  };
141
158
  }
@@ -4,7 +4,7 @@ import type {
4
4
  ContextSharingService,
5
5
  SharedContextRequest,
6
6
  SharedContextResult,
7
- } from "@howaboua/pi-codex-conversion/context-sharing";
7
+ } from "@howaboua/pi-notes-compaction/context-sharing";
8
8
  import type { AttachmentNotes } from "./attachment-notes.js";
9
9
  import {
10
10
  type AttachmentRoute,
@@ -4,7 +4,7 @@ import type {
4
4
  ExtensionContext,
5
5
  } from "@earendil-works/pi-coding-agent";
6
6
  import { binding } from "@howaboua/pi-agent-board/integration";
7
- import type { ContextSharingService } from "@howaboua/pi-codex-conversion/context-sharing";
7
+ import type { ContextSharingService } from "@howaboua/pi-notes-compaction/context-sharing";
8
8
  import type { Static } from "typebox";
9
9
  import { Check } from "typebox/value";
10
10
  import { AttachmentNotes } from "./attachment-notes.js";
@@ -21,7 +21,10 @@ import {
21
21
  } from "./attachment-protocol.js";
22
22
  import type { AgentBoard } from "./board/host.js";
23
23
  import { sendPolicyMessage } from "./delivery.js";
24
- import { attachmentMessage, detachmentMessage } from "./messages.js";
24
+ import {
25
+ attachmentMessage,
26
+ detachmentMessage,
27
+ } from "./messages/attachments.js";
25
28
 
26
29
  /** Validates and commits attachment membership in the settled target session. */
27
30
  export class AttachmentTarget {
package/src/attachment.ts CHANGED
@@ -5,7 +5,7 @@ import type {
5
5
  ExtensionContext,
6
6
  } from "@earendil-works/pi-coding-agent";
7
7
  import { binding } from "@howaboua/pi-agent-board/integration";
8
- import type { ContextSharingService } from "@howaboua/pi-codex-conversion/context-sharing";
8
+ import type { ContextSharingService } from "@howaboua/pi-notes-compaction/context-sharing";
9
9
  import type { Static } from "typebox";
10
10
  import { Check } from "typebox/value";
11
11
  import type { AgentsParams } from "./agents-contract.js";
@@ -20,7 +20,7 @@ import {
20
20
  import { AttachmentRouting } from "./attachment-routing.js";
21
21
  import { AttachmentTarget } from "./attachment-target.js";
22
22
  import type { AgentBoard } from "./board/host.js";
23
- import type { ConnectedMachine } from "./fleet.js";
23
+ import type { ConnectedMachine } from "./fleet/index.js";
24
24
  import { sessionPath } from "./herdr.js";
25
25
  import { sessionContextPath } from "./remote/shepherdr-context.mjs";
26
26
  import type { PaneInfo } from "./types.js";
@@ -97,6 +97,8 @@ export class AgentAttachment {
97
97
  "Target has different attachment choices; changing an attachment is unsupported",
98
98
  );
99
99
  let route = prior;
100
+ await runtime.prepareSharing();
101
+ await check();
100
102
  if (!route) {
101
103
  const snapshot = await runtime.client.requestContext(
102
104
  sessionContextPath(sessionFile),
@@ -202,7 +204,6 @@ export class AgentAttachment {
202
204
  ...(route.plan.board
203
205
  ? {
204
206
  boardAgent: route.plan.board.desired.agentName,
205
- previousBoard: route.plan.board.previous.boardId,
206
207
  }
207
208
  : {}),
208
209
  };
package/src/board/host.ts CHANGED
@@ -15,9 +15,9 @@ import {
15
15
  type BoardRuntime,
16
16
  discoverBoard,
17
17
  } from "@howaboua/pi-agent-board/runtime";
18
- import type { AgentFleet, ConnectedMachine } from "../fleet.js";
18
+ import type { AgentFleet, ConnectedMachine } from "../fleet/index.js";
19
19
  import { sessionPath } from "../herdr.js";
20
- import { boardBriefing, boardMigrationWarning } from "../messages.js";
20
+ import { boardBriefing, boardMigrationWarning } from "../messages/guidance.js";
21
21
  import {
22
22
  requestContext,
23
23
  sessionContextPath,
@@ -78,6 +78,7 @@ export class AgentBoard {
78
78
  );
79
79
  },
80
80
  propagateEnabled: async (ctx, enabled) => {
81
+ let boardId: string | undefined;
81
82
  await Promise.all(
82
83
  children(ctx).map(async (child) => {
83
84
  try {
@@ -85,7 +86,7 @@ export class AgentBoard {
85
86
  sessionContextPath(child.sessionFile),
86
87
  {
87
88
  operation: "board-enabled",
88
- boardId: binding(ctx).boardId,
89
+ boardId: (boardId ??= binding(ctx).boardId),
89
90
  enabled,
90
91
  },
91
92
  AbortSignal.timeout(750),
@@ -156,6 +157,7 @@ export class AgentBoard {
156
157
  const segment =
157
158
  name.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64) || "agent";
158
159
  const agentName = `${own.agentName}/${segment}-${randomUUID()}`;
160
+ await runtime.prepareSharing();
159
161
  const upstream = runtime.local
160
162
  ? sessionContextPath(file)
161
163
  : runtime.client.contextRelayPath();