@howaboua/pi-shepherdr 0.2.17 → 0.2.19

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 CHANGED
@@ -1,5 +1,21 @@
1
1
  # @howaboua/pi-shepherdr
2
2
 
3
+ ## 0.2.19
4
+
5
+ - Added Codex parent-child metadata for workers when used with PCC, preserved on resume and independent of shared notes.
6
+
7
+ Agent-read help and invalid-source errors now list supported sources.
8
+
9
+ ## 0.2.18
10
+
11
+ - Replaced the Ask-specific `answer` action with `reply` for extension replies. Update and reload Ask and Shepherdr together on controllers and workers.
12
+
13
+ - Assignments now update running agents without losing pending results or replacing existing waiters. Messages and assignments also reach blocked workers.
14
+ - Extension messages and reply templates now travel between local and remote agents. Replies reach the owning extension without an extra model turn, including while a worker is busy or blocked.
15
+ - Pending extension messages remain visible until their producer closes them. Blocking messages arrive with the blocked result. Nonblocking messages notify separately once.
16
+ - Context rollover now retains supervised workers and their full follow-up instructions.
17
+ - Spawn labels no longer have a word-count restriction.
18
+
3
19
  ## 0.2.17
4
20
 
5
21
  - Added slash-command discovery with configured descriptions for the current session or another agent, without executing commands or interrupting its work.
package/README.md CHANGED
@@ -63,25 +63,25 @@ Call `agents` with `{}` before first use, alone, then send flat request objects
63
63
  | `attach` | Share context or join a board with an existing idle agent |
64
64
  | `detach` | Leave selected membership and retain read-only counterpart checkpoints |
65
65
  | `read` | Read the latest assistant reply or bounded terminal output |
66
- | `answer` | Answer a worker's blocking or asynchronous Pi Ask |
66
+ | `reply` | Deliver an opaque reply to a worker's extension |
67
67
  | `watch` | Push future settlement from an existing Pi agent |
68
68
  | `unwatch` | Stop reporting an agent |
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
- `answer` requires the pending `ask_id` from `read` or a question report. It handles both blocking and asynchronous Ask prompts. It returns `accepted` only when that exact Ask persisted the supplied responses; an accepted retry sends no input. Answering an asynchronous question does not wait for the worker's task to finish.
72
+ 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
73
 
74
- Asynchronous Ask prompts notify the controller while the worker keeps working. Session-file events drive local and remote notifications without marking the worker blocked or settling its task. Duplicate notifications are suppressed across controller restoration. Update Pi Ask on workers together with Shepherdr on controllers.
74
+ `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.
75
75
 
76
- Needed input and work changes use `send`. It returns after submission, does not accept `blocking`, and never creates or changes a watch or task. Use `assign` only to delegate work whose result you need, not to exchange coordination messages. Close finished workers silently instead of waking them with completion acknowledgements or shutdown notices.
76
+ Use `send` for messages and work updates without waiting or adding supervision. Use `assign` when you need the result: it also accepts updates to running work, sharing that work's pending result rather than replacing it. If another call is already waiting, the update returns after submission and leaves that waiter intact. Close finished workers silently instead of waking them with completion acknowledgements or shutdown notices.
77
77
 
78
78
  Delegation and explicit `watch` keep reporting subsequent work until `unwatch` or the agent's pane closes. Finishing or failing a task clears that task, not its watch. Follow-up messages through `send` retain completion reporting without replacing the task.
79
79
 
80
- Every `spawn` needs an `agent_type` and a concise two- or three-word `label`. The label names both the Herdr tab and Pi session; the routing `name` remains optional and is derived from it when omitted.
80
+ Every `spawn` needs an `agent_type` and a concise `label`. The label names both the Herdr tab and Pi session; the routing `name` remains optional and is derived from it when omitted.
81
81
 
82
82
  Cancelling a blocking call does not kill its worker. The waiter detaches and the eventual result returns through normal asynchronous delivery.
83
83
 
84
- After Pi compaction or Pi Codex context rollover, the controller receives its active agents' exact machine and target, full delegated task and last observed status. Existing work stays assigned instead of being delegated again. This reminder does not start a turn or bypass normal turn preparation.
84
+ After Pi compaction or Pi Codex context rollover, the controller receives its supervised agents' exact machine and target, submitted tasks and follow-up instructions, and last observed status, including settled and blocked workers. Read a target for its reply or pending extension messages. This reminder does not start a turn or bypass normal turn preparation.
85
85
 
86
86
  Prompts sent through `agents` identify peer messages versus delegated tasks and include the sender's host, session, workspace, tab and pane identity, with current names. Reports include source workspace and tab names too. Raw `herdr agent prompt` calls bypass this attribution. These are runtime locations, not the desktop window showing a pane.
87
87
 
@@ -122,7 +122,37 @@ Blocked commands return the built-in commands and currently registered, allowed
122
122
 
123
123
  Idle messages start a prepared user turn. Messages arriving during a run use steering, promoted to developer messages when Pi Codex developer delivery is active. Otherwise they remain ordinary Pi custom messages.
124
124
 
125
- For `answer` inside Code or Notebook Mode, update Pi Ask on workers together with Shepherdr on controllers.
125
+ ### Extension messages
126
+
127
+ An extension can publish a durable message without importing Shepherdr:
128
+
129
+ ```ts
130
+ pi.appendEntry("shepherdr-extension-message", {
131
+ version: 1,
132
+ extension: "your-extension",
133
+ id: "unique-message-id",
134
+ state: "pending",
135
+ message: "Extension-authored text for the controller",
136
+ reply: "Extension-authored reply template", // optional
137
+ blocking: false,
138
+ });
139
+ ```
140
+
141
+ Use a unique ID per message within the extension. `blocking` says whether replying should wait for resumed work. Omit `reply` for messages requiring human handling. Close a message with another entry using the same `version`, `extension` and `id`, and `state: "closed"`. Local and remote readers follow the active session branch and expose every pending record.
142
+
143
+ Register the reply handler on Pi's event bus:
144
+
145
+ ```ts
146
+ pi.events.on("@howaboua/pi-shepherdr/extension-reply/v1", event => {
147
+ const { extension, id, message, respond } = event;
148
+ if (extension !== "your-extension") return;
149
+ respond(handleReply(id, message));
150
+ });
151
+ ```
152
+
153
+ Claim synchronously with `respond(string | Promise<string>)`. Resolve only after delivering the response and persisting its resulting state. Reject through that promise for validation or delivery errors. Shepherdr returns the opaque result string. Each extension owns one handler and must guard its session lifetime and retry semantics.
154
+
155
+ Replies use the authenticated peer connection, including across machines, and can reach busy or blocked workers without starting a model turn. Missing handlers fail visibly. An unacknowledged delivery can still have reached its handler, so inspect the target before retrying. Update and reload Shepherdr on both ends and any producing extension that used the previous Ask-specific integration.
126
156
 
127
157
  ### Attach existing agents
128
158
 
@@ -164,6 +194,8 @@ Child board calls use the owning Pi sessions and existing SSH connections, not a
164
194
 
165
195
  ## Shared notes and history
166
196
 
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 ID. This relationship works with shared notes disabled and does not grant notes access. Resume preserves it; forks and profiles selecting existing sessions do not acquire an inherited relationship. Older PCC versions without the optional capability retain ordinary delegation. The [extension API guide](../../docs/extension-apis.md#parent-and-worker-relationships) documents PCC's `bindRelationship` service contract for other orchestrators. Shepherdr owns transport, not a separate public relationship RPC API.
198
+
167
199
  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.
168
200
 
169
201
  Set `"share_context": false` in a profile to keep its new workers' notes and history independent even when controller sharing is enabled. Omission or `true` follows the controller setting, never turns sharing on itself. This separates context, not filesystem permissions or information included in the task.
package/biome.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "$schema": "https://biomejs.dev/schemas/2.5.10/schema.json",
2
+ "$schema": "https://biomejs.dev/schemas/2.5.15/schema.json",
3
3
  "vcs": {
4
4
  "enabled": true,
5
5
  "clientKind": "git",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@howaboua/pi-shepherdr",
3
- "version": "0.2.17",
3
+ "version": "0.2.19",
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": ">=3.0.48",
46
+ "@howaboua/pi-codex-conversion": ">=3.0.51",
47
47
  "@earendil-works/pi-ai": ">=1.1.0",
48
48
  "@earendil-works/pi-coding-agent": ">=1.1.0",
49
49
  "@earendil-works/pi-tui": ">=1.1.0",
@@ -58,13 +58,13 @@
58
58
  "@howaboua/pi-agent-board": "0.0.1"
59
59
  },
60
60
  "devDependencies": {
61
- "@howaboua/pi-codex-conversion": "3.0.48",
62
- "@biomejs/biome": "^2.5.10",
61
+ "@howaboua/pi-codex-conversion": "3.0.51",
62
+ "@biomejs/biome": "^2.5.15",
63
63
  "@earendil-works/pi-ai": "1.1.0",
64
64
  "@earendil-works/pi-coding-agent": "1.1.0",
65
65
  "@earendil-works/pi-tui": "1.1.0",
66
- "@types/node": "^26.2.0",
67
- "typebox": "1.3.18",
66
+ "@types/node": "^26.6.5",
67
+ "typebox": "1.3.36",
68
68
  "typescript": "^7.0.2"
69
69
  },
70
70
  "pi": {
@@ -0,0 +1,17 @@
1
+ import type { PaneInfo } from "./types.js";
2
+
3
+ export function sameAgentIdentity(
4
+ expected: PaneInfo,
5
+ current: PaneInfo,
6
+ ): boolean {
7
+ return (
8
+ current.pane_id === expected.pane_id &&
9
+ current.workspace_id === expected.workspace_id &&
10
+ current.tab_id === expected.tab_id &&
11
+ current.terminal_id === expected.terminal_id &&
12
+ current.agent_session?.agent === expected.agent_session?.agent &&
13
+ current.agent_session?.kind === expected.agent_session?.kind &&
14
+ current.agent_session?.source === expected.agent_session?.source &&
15
+ current.agent_session?.value === expected.agent_session?.value
16
+ );
17
+ }
@@ -17,9 +17,9 @@ const ACTIONS = [
17
17
  "attach",
18
18
  "detach",
19
19
  "read",
20
- "answer",
20
+ "reply",
21
21
  ] as const;
22
- const BLOCKING_ACTIONS = new Set<string>(["spawn", "assign", "answer"]);
22
+ const BLOCKING_ACTIONS = new Set<string>(["spawn", "assign", "reply"]);
23
23
  export const READ_SOURCES = ["latest", "visible", "recent"] as const;
24
24
  const STATUSES = ["idle", "working", "blocked", "done", "unknown"] as const;
25
25
 
@@ -50,18 +50,9 @@ const ACTION_FIELDS: Record<(typeof ACTIONS)[number], ReadonlySet<string>> = {
50
50
  attach: new Set(["action", "machine", "target", "context", "board"]),
51
51
  detach: new Set(["action", "machine", "target", "context", "board"]),
52
52
  read: new Set(["action", "machine", "target", "source", "lines"]),
53
- answer: new Set(["action", "machine", "target", "ask_id", "answers"]),
53
+ reply: new Set(["action", "machine", "target", "extension", "id", "message"]),
54
54
  };
55
55
 
56
- const AskAnswerParameters = Type.Object(
57
- {
58
- selections: Type.Optional(Type.Array(Type.String())),
59
- other: Type.Optional(Type.String()),
60
- comment: Type.Optional(Type.String()),
61
- },
62
- { additionalProperties: false },
63
- );
64
-
65
56
  const AgentsRequest = Type.Object(
66
57
  {
67
58
  action: StringEnum(ACTIONS),
@@ -84,7 +75,7 @@ const AgentsRequest = Type.Object(
84
75
  pane: Type.Optional(Type.String()),
85
76
  cwd: Type.Optional(Type.String()),
86
77
  message: Type.Optional(
87
- Type.String({ description: "Initial task or follow-up" }),
78
+ Type.String({ description: "Task, follow-up or extension reply" }),
88
79
  ),
89
80
  base: Type.Optional(Type.String({ description: "Review base branch" })),
90
81
  blocking: Type.Optional(
@@ -100,8 +91,8 @@ const AgentsRequest = Type.Object(
100
91
  status: Type.Optional(StringEnum(STATUSES)),
101
92
  source: Type.Optional(StringEnum(READ_SOURCES)),
102
93
  lines: Type.Optional(Type.Integer({ minimum: 1, maximum: 200 })),
103
- ask_id: Type.Optional(Type.String()),
104
- answers: Type.Optional(Type.Array(AskAnswerParameters)),
94
+ extension: Type.Optional(Type.String()),
95
+ id: Type.Optional(Type.String()),
105
96
  },
106
97
  { additionalProperties: false },
107
98
  );
@@ -177,12 +168,13 @@ export function parseAgentsRequest(input: unknown): AgentsParams {
177
168
  throw new Error(
178
169
  `${action} requires context and board booleans; enable at least one`,
179
170
  );
180
- const askId = request["ask_id"];
181
- if (action === "answer" && (typeof askId !== "string" || !askId.trim())) {
182
- throw new Error("ask_id is required for answer");
183
- }
184
- if (action === "answer" && !Array.isArray(request["answers"])) {
185
- throw new Error("answers is required for answer");
171
+ if (action === "reply") {
172
+ for (const field of ["extension", "id", "target"]) {
173
+ if (typeof request[field] !== "string" || !request[field].trim())
174
+ throw new Error(`${field} is required for reply`);
175
+ }
176
+ if (typeof request["message"] !== "string")
177
+ throw new Error("message is required for reply");
186
178
  }
187
179
  const unknown = Object.keys(request).filter(
188
180
  (key) => !ACTION_FIELDS[action as keyof typeof ACTION_FIELDS].has(key),
@@ -190,6 +182,13 @@ export function parseAgentsRequest(input: unknown): AgentsParams {
190
182
  if (unknown.length > 0) {
191
183
  throw new Error(`unknown ${action} field(s): ${unknown.join(", ")}`);
192
184
  }
185
+ if (
186
+ action === "read" &&
187
+ "source" in request &&
188
+ !READ_SOURCES.some((source) => source === request["source"])
189
+ ) {
190
+ throw new Error(`read source must be one of: ${READ_SOURCES.join(", ")}`);
191
+ }
193
192
  if (!Check(AgentsRequest, request)) {
194
193
  throw new Error(
195
194
  `invalid ${action} request; call agents help for its contract`,
@@ -44,25 +44,26 @@ export async function agentsHelp(
44
44
  assign: "target message machine? blocking?",
45
45
  attach: "target context board machine?",
46
46
  detach: "target context board machine?",
47
- read: "target machine? source? lines?",
48
- answer: "target ask_id answers machine?",
47
+ read: "target machine? source=latest|visible|recent? lines?",
48
+ reply: "target extension id message machine?",
49
49
  },
50
50
  rules: {
51
+ reply:
52
+ "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",
51
53
  machine:
52
54
  "Omit for local (host running Pi); list/find omit for all machines. Remote: profile ID from list, not label/hostname",
53
55
  target:
54
56
  "Use spawn/find target exactly; /root selects this family's live root",
55
- label: "2-3 words; tab/session",
57
+ label: "Concise tab/session name",
56
58
  ...(boardAvailable
57
59
  ? {
58
60
  board_thread_id:
59
61
  "Existing shared-board thread; child receives a read reference",
60
62
  }
61
63
  : {}),
62
- answers: "[{selections?:string[],other?:string,comment?:string}]",
63
- ask_id: "Exact pending Ask ID",
64
- send: "Only needed input or work changes; wakes idle agents, no wait/watch. Close finished workers with /quit, not acknowledgement messages",
65
- assign: "Delegate a task to an existing agent",
64
+ send: "Message or work update; wakes idle agents, no wait/watch. Close finished workers with /quit, not acknowledgement messages",
65
+ assign:
66
+ "Delegate or update work; active updates share its pending result, never replace an existing wait",
66
67
  focus:
67
68
  "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",
68
69
  attach: boardAvailable
@@ -0,0 +1,68 @@
1
+ import type { AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
2
+ import type { AgentsParams } from "./agents-contract.js";
3
+ import {
4
+ dispatchAgentWork,
5
+ settlementResult,
6
+ toolResult,
7
+ } from "./agents-work.js";
8
+ import type { ConnectedMachine } from "./fleet.js";
9
+ import type { PaneInfo } from "./types.js";
10
+
11
+ export async function replyAgent(
12
+ runtime: ConnectedMachine,
13
+ panel: PaneInfo,
14
+ params: AgentsParams,
15
+ signal: AbortSignal,
16
+ onUpdate: AgentToolUpdateCallback<Record<string, unknown>>,
17
+ ) {
18
+ const reply = {
19
+ extension: params.extension!,
20
+ id: params.id!,
21
+ message: params.message!,
22
+ };
23
+ const view = await runtime.monitor.view(panel);
24
+ const pending = view.extensionMessages?.find(
25
+ (message) =>
26
+ message.extension === reply.extension && message.id === reply.id,
27
+ );
28
+ signal.throwIfAborted();
29
+ let result: string | undefined;
30
+ const send = async () => {
31
+ result = await runtime.client.replyExtension(panel, reply);
32
+ };
33
+ if (!pending?.blocking) {
34
+ await send();
35
+ return toolResult({
36
+ machine: runtime.machine,
37
+ target: panel.pane_id,
38
+ extension: reply.extension,
39
+ id: reply.id,
40
+ result,
41
+ });
42
+ }
43
+ const { settlement, warning } = await dispatchAgentWork(
44
+ runtime,
45
+ panel,
46
+ `Reply to ${reply.extension}`,
47
+ true,
48
+ signal,
49
+ onUpdate,
50
+ send,
51
+ { replyingTo: reply },
52
+ );
53
+ return toolResult(
54
+ {
55
+ ...(settlement
56
+ ? settlementResult(runtime.machine, settlement, {
57
+ reportWorkerError: true,
58
+ })
59
+ : {}),
60
+ machine: runtime.machine,
61
+ target: panel.pane_id,
62
+ extension: reply.extension,
63
+ id: reply.id,
64
+ result,
65
+ },
66
+ warning,
67
+ );
68
+ }
@@ -30,15 +30,6 @@ import {
30
30
  } from "./profiles.js";
31
31
  import type { SharedAgentContext } from "./shared-context.js";
32
32
 
33
- function agentLabel(value: string | undefined): string {
34
- const label = required(value, "label");
35
- const words = label.split(/\s+/u);
36
- if (words.length < 2 || words.length > 3) {
37
- throw new Error("label must contain 2 or 3 words");
38
- }
39
- return label;
40
- }
41
-
42
33
  export async function spawnAgent(
43
34
  fleet: AgentFleet,
44
35
  runtime: ConnectedMachine,
@@ -73,7 +64,7 @@ export async function spawnAgent(
73
64
  `unknown agent_type ${JSON.stringify(profileName)}; available: ${[...profiles.keys()].join(", ")}`,
74
65
  );
75
66
  }
76
- const label = agentLabel(params.label);
67
+ const label = required(params.label, "label");
77
68
  const name = params.name?.trim() || (await allocateAgentName(runtime, label));
78
69
  const placement =
79
70
  params.placement ??
@@ -132,6 +123,11 @@ export async function spawnAgent(
132
123
  status: "starting",
133
124
  });
134
125
  const agentArgs = profileAgentArgs(profile, { targetLocal: runtime.local });
126
+ const relationship = sharedContext.prepareRelationship(
127
+ ctx,
128
+ runtime,
129
+ agentArgs,
130
+ );
135
131
  const sharing =
136
132
  profile.shareContext === false
137
133
  ? undefined
@@ -149,8 +145,10 @@ export async function spawnAgent(
149
145
  let dispatch;
150
146
  let shared: { agentName?: string; warning?: string } | undefined;
151
147
  let boardAgent: string | undefined;
148
+ let relationshipWarning: string | undefined;
152
149
  const blocking = shouldBlockAgentSpawn(profile.blocking, params.blocking);
153
150
  try {
151
+ relationshipWarning = (await relationship?.accept(started.agent))?.warning;
154
152
  boardAgent = await boardBinding?.accept(started.agent);
155
153
  shared = await sharing?.accept(started.agent);
156
154
  dispatch = await dispatchAgentWork(
@@ -206,6 +204,8 @@ export async function spawnAgent(
206
204
  next: "Converse, do other work or reply now; completion/blockage arrives even after you reply. No polling or sleep waits",
207
205
  }),
208
206
  },
209
- [dispatch.warning, shared?.warning].filter(Boolean).join("\n") || undefined,
207
+ [dispatch.warning, shared?.warning, relationshipWarning]
208
+ .filter(Boolean)
209
+ .join("\n") || undefined,
210
210
  );
211
211
  }
@@ -4,7 +4,6 @@ import {
4
4
  getMarkdownTheme,
5
5
  } from "@earendil-works/pi-coding-agent";
6
6
  import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
7
- import { answerAgent } from "./agents-answer.js";
8
7
  import {
9
8
  AgentsParameters,
10
9
  type AgentsParams,
@@ -19,6 +18,7 @@ import {
19
18
  readAgentTerminal,
20
19
  } from "./agents-discovery.js";
21
20
  import { focusAgent } from "./agents-focus.js";
21
+ import { replyAgent } from "./agents-reply.js";
22
22
  import { spawnAgent } from "./agents-spawn.js";
23
23
  import {
24
24
  dispatchAgentWork,
@@ -28,7 +28,7 @@ import {
28
28
  import type { AgentBoard } from "./board/host.js";
29
29
  import type { AgentFleet } from "./fleet.js";
30
30
  import { resolvePiAgent } from "./herdr.js";
31
- import { attributeAgentPrompt, modelAsk } from "./messages.js";
31
+ import { attributeAgentPrompt } from "./messages.js";
32
32
  import type { createPeerCommands } from "./peer-commands.js";
33
33
  import type { SharedAgentContext } from "./shared-context.js";
34
34
 
@@ -165,21 +165,12 @@ export function createAgentsTool(
165
165
  ...(view.assistant
166
166
  ? { reply: view.assistant.text }
167
167
  : { reply: null }),
168
- ...(view.ask &&
169
- (panel.agent_status === "blocked" || view.ask.delivery === "steer")
170
- ? {
171
- ask: modelAsk(view.ask),
172
- }
168
+ ...(view.extensionMessages
169
+ ? { extensionMessages: view.extensionMessages }
173
170
  : {}),
174
171
  });
175
172
  }
176
173
  if (params.action === "send" || params.action === "assign") {
177
- if (panel.agent_status === "blocked") {
178
- const view = await runtime.monitor.view(panel);
179
- throw new Error(
180
- `${panel.pane_id} is blocked${view.ask ? " on ask; use action=answer" : ""}`,
181
- );
182
- }
183
174
  const message = required(params.message, "message");
184
175
  const attributedMessage = await attributeAgentPrompt(
185
176
  fleet.connected().client,
@@ -192,6 +183,8 @@ export function createAgentsTool(
192
183
  panel,
193
184
  attributedMessage,
194
185
  );
186
+ if (!receipt.command)
187
+ runtime.monitor.noteMessage(panel.pane_id, message);
195
188
  return toolResult({
196
189
  sent: true,
197
190
  ...(receipt.command ? { commandSubmitted: true } : {}),
@@ -231,8 +224,8 @@ export function createAgentsTool(
231
224
  dispatch.warning,
232
225
  );
233
226
  }
234
- if (params.action === "answer") {
235
- return answerAgent(runtime, panel, params, executionSignal, update);
227
+ if (params.action === "reply") {
228
+ return replyAgent(runtime, panel, params, executionSignal, update);
236
229
  }
237
230
  throw new Error(`unsupported action ${params.action}`);
238
231
  },
@@ -294,20 +287,10 @@ export function createAgentsTool(
294
287
  if (!options.expanded) return title;
295
288
  const reply =
296
289
  typeof details["reply"] === "string" ? details["reply"] : undefined;
297
- const ask =
298
- typeof details["ask"] === "object" && details["ask"] !== null
299
- ? (details["ask"] as { prompts?: unknown })
300
- : undefined;
301
290
  const informational = Object.fromEntries(
302
- Object.entries(details).filter(
303
- ([key]) => key !== "reply" && key !== "ask",
304
- ),
291
+ Object.entries(details).filter(([key]) => key !== "reply"),
305
292
  );
306
- if (
307
- !reply &&
308
- !Array.isArray(ask?.prompts) &&
309
- Object.keys(informational).length === 0
310
- ) {
293
+ if (!reply && Object.keys(informational).length === 0) {
311
294
  return title;
312
295
  }
313
296
  const container = new Container();
@@ -322,22 +305,7 @@ export function createAgentsTool(
322
305
  container.addChild(new Spacer(1));
323
306
  container.addChild(new Markdown(reply, 0, 0, getMarkdownTheme()));
324
307
  }
325
- if (Array.isArray(ask?.prompts)) {
326
- const titles = ask.prompts
327
- .flatMap((prompt) =>
328
- typeof prompt === "object" &&
329
- prompt !== null &&
330
- "title" in prompt &&
331
- typeof prompt.title === "string"
332
- ? [prompt.title]
333
- : [],
334
- )
335
- .join(", ");
336
- if (titles) {
337
- container.addChild(new Spacer(1));
338
- container.addChild(new Text(theme.fg("warning", titles), 0, 0));
339
- }
340
- }
308
+
341
309
  return container;
342
310
  },
343
311
  });
@@ -3,10 +3,10 @@ import { activityTask } from "./activity.js";
3
3
  import type { ConnectedMachine } from "./fleet.js";
4
4
  import { getSnapshot } from "./herdr.js";
5
5
  import { isDispatchRejected } from "./herdr-client.js";
6
- import { agentSource, modelAsk } from "./messages.js";
6
+ import { agentSource } from "./messages.js";
7
7
  import type { WorkAttempt } from "./monitor-state.js";
8
8
  import type { ClaimedSettlement } from "./settlement.js";
9
- import type { PaneInfo, PeerDelivery } from "./types.js";
9
+ import type { ExtensionReply, PaneInfo, PeerDelivery } from "./types.js";
10
10
 
11
11
  export function toolResult(value: Record<string, unknown>, warning?: string) {
12
12
  if (warning) value = { ...value, next: warning };
@@ -81,15 +81,15 @@ export function settlementResult(
81
81
  status: settlement.status,
82
82
  ...(workerError ? { worker_error: workerError } : {}),
83
83
  ...(settlement.reply ? { reply: settlement.reply.text } : {}),
84
- ...(settlement.ask
85
- ? {
86
- ask: modelAsk(settlement.ask),
87
- }
84
+ ...(settlement.extensionMessages
85
+ ? { extensionMessages: settlement.extensionMessages }
88
86
  : {}),
89
87
  ...(settlement.blockedMessage
90
88
  ? { blocked_on: settlement.blockedMessage }
91
89
  : {}),
92
- ...(settlement.status === "done" && !settlement.reply && !settlement.ask
90
+ ...(settlement.status === "done" &&
91
+ !settlement.reply &&
92
+ !settlement.extensionMessages?.length
93
93
  ? { completed: true }
94
94
  : {}),
95
95
  };
@@ -103,7 +103,7 @@ export async function dispatchAgentWork(
103
103
  signal: AbortSignal,
104
104
  onUpdate: AgentToolUpdateCallback<Record<string, unknown>>,
105
105
  send: () => Promise<PeerDelivery | void>,
106
- options: { expectUserMessage?: boolean; answeringAskId?: string } = {},
106
+ options: { expectUserMessage?: boolean; replyingTo?: ExtensionReply } = {},
107
107
  ): Promise<{
108
108
  settlement?: ClaimedSettlement;
109
109
  command?: true;
@@ -133,14 +133,14 @@ export async function dispatchAgentWork(
133
133
  );
134
134
  if (!attempt) throw new Error(`${panel.pane_id} is not monitored`);
135
135
  settlement = blocking
136
- ? runtime.monitor.claimWork(attempt, signal, options.answeringAskId)
136
+ ? runtime.monitor.claimWork(attempt, signal, options.replyingTo)
137
137
  : undefined;
138
138
  void settlement?.catch(() => undefined);
139
139
  signal.throwIfAborted();
140
140
  sendStarted = true;
141
141
  receipt = await send();
142
142
  } catch (error) {
143
- runtime.monitor.releaseWorkClaim(attempt, error);
143
+ if (settlement) runtime.monitor.releaseWorkClaim(attempt, error);
144
144
  if (sendStarted) await runtime.monitor.handleWorkFailure(attempt, error);
145
145
  else runtime.monitor.rejectWork(attempt);
146
146
  if (addedWatch && (!sendStarted || isDispatchRejected(error))) {
@@ -162,10 +162,11 @@ export async function dispatchAgentWork(
162
162
  }
163
163
  try {
164
164
  if (receipt?.command) {
165
- runtime.monitor.releaseWorkClaim(
166
- attempt,
167
- new Error("Command submitted without task waiting"),
168
- );
165
+ if (settlement)
166
+ runtime.monitor.releaseWorkClaim(
167
+ attempt,
168
+ new Error("Command submitted without task waiting"),
169
+ );
169
170
  runtime.monitor.rejectWork(attempt);
170
171
  if (addedWatch) {
171
172
  const record = runtime.monitor
@@ -174,21 +175,24 @@ export async function dispatchAgentWork(
174
175
  if (record?.scope === "task" && !activityTask(record.activity))
175
176
  await runtime.monitor.unwatch(record.paneId);
176
177
  }
177
- } else runtime.monitor.acceptWork(attempt);
178
+ } else {
179
+ runtime.monitor.acceptWork(attempt);
180
+ runtime.monitor.noteMessage(panel.pane_id, task);
181
+ }
178
182
  await runtime.monitor.reconcileNow();
179
183
  } catch (error) {
180
- runtime.monitor.releaseWorkClaim(attempt, error);
184
+ if (settlement) runtime.monitor.releaseWorkClaim(attempt, error);
181
185
  return {
182
186
  ...(receipt?.command ? { command: true } : {}),
183
187
  warning: `Submitted, but monitoring refresh failed: ${error instanceof Error ? error.message : String(error)}. Inspect the target before resubmitting`,
184
188
  };
185
189
  }
186
190
  if (receipt?.command) return { command: true };
187
- if (!blocking) return {};
191
+ if (!settlement) return {};
188
192
  reportProgress(onUpdate, `Waiting for ${panel.name ?? panel.pane_id}`, {
189
193
  machine: runtime.machine,
190
194
  target: panel.pane_id,
191
195
  status: "working",
192
196
  });
193
- return { settlement: await settlement! };
197
+ return { settlement: await settlement };
194
198
  }
package/src/controller.ts CHANGED
@@ -108,7 +108,7 @@ export function registerAgentController(
108
108
  registerContextBriefing(
109
109
  pi,
110
110
  "active agents",
111
- () => fleet.list().some((agent) => agent.activity.phase !== "settled"),
111
+ () => fleet.list().length > 0,
112
112
  async (ctx, windowId) => {
113
113
  if (!hasContextRollover(ctx)) return;
114
114
  const key = JSON.stringify([