@howaboua/pi-shepherdr 0.2.16 → 0.2.18

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,19 @@
1
1
  # @howaboua/pi-shepherdr
2
2
 
3
+ ## 0.2.18
4
+
5
+ - Replaced the Ask-specific `answer` action with `reply` for extension replies. Update and reload Ask and Shepherdr together on controllers and workers.
6
+
7
+ - Assignments now update running agents without losing pending results or replacing existing waiters. Messages and assignments also reach blocked workers.
8
+ - 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.
9
+ - Pending extension messages remain visible until their producer closes them. Blocking messages arrive with the blocked result. Nonblocking messages notify separately once.
10
+ - Context rollover now retains supervised workers and their full follow-up instructions.
11
+ - Spawn labels no longer have a word-count restriction.
12
+
13
+ ## 0.2.17
14
+
15
+ - Added slash-command discovery with configured descriptions for the current session or another agent, without executing commands or interrupting its work.
16
+
3
17
  ## 0.2.16
4
18
 
5
19
  - ### Breaking changes
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
 
@@ -91,6 +91,8 @@ Messages beginning with `/` use the target Pi session's command, skill and promp
91
91
 
92
92
  ### Agent commands
93
93
 
94
+ Call `agents` with `{ commands: true }` to list this session's available slash commands and descriptions without executing them. Add `target` and optionally `machine` to inspect another session, including a busy one. Current-session discovery also works outside Herdr. `machine` alone is rejected because it does not identify a session. Skills and prompt templates are not included.
95
+
94
96
  These built-in commands are available through agent messages without an allowlist:
95
97
 
96
98
  | Command | Result |
@@ -120,7 +122,37 @@ Blocked commands return the built-in commands and currently registered, allowed
120
122
 
121
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.
122
124
 
123
- 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.
124
156
 
125
157
  ### Attach existing agents
126
158
 
package/index.ts CHANGED
@@ -33,7 +33,7 @@ export default async function shepherdrExtension(
33
33
  const board = AgentBoard.create(pi, fleet);
34
34
  registerPeerInbox(pi, peerCommands, fleet, (ctx) => board.promptCatchup(ctx));
35
35
  const sharedContext = await registerSharedAgentContext(pi, fleet, board);
36
- const tool = createAgentsTool(fleet, sharedContext, board, pi);
36
+ const tool = createAgentsTool(fleet, sharedContext, board, pi, peerCommands);
37
37
 
38
38
  registerAgentEventRenderer(pi);
39
39
  pi.registerTool(tool);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@howaboua/pi-shepherdr",
3
- "version": "0.2.16",
3
+ "version": "0.2.18",
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.50",
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,7 +58,7 @@
58
58
  "@howaboua/pi-agent-board": "0.0.1"
59
59
  },
60
60
  "devDependencies": {
61
- "@howaboua/pi-codex-conversion": "3.0.48",
61
+ "@howaboua/pi-codex-conversion": "3.0.50",
62
62
  "@biomejs/biome": "^2.5.10",
63
63
  "@earendil-works/pi-ai": "1.1.0",
64
64
  "@earendil-works/pi-coding-agent": "1.1.0",
@@ -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,14 +17,14 @@ 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
 
26
26
  const ACTION_FIELDS: Record<(typeof ACTIONS)[number], ReadonlySet<string>> = {
27
- help: new Set(["action"]),
27
+ help: new Set(["action", "commands", "target", "machine"]),
28
28
  list: new Set(["action", "machine"]),
29
29
  find: new Set(["action", "machine", "query", "status"]),
30
30
  focus: new Set(["action", "machine", "target", "voice", "handoff"]),
@@ -50,21 +50,13 @@ 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),
59
+ commands: Type.Optional(Type.Literal(true)),
68
60
  machine: Type.Optional(Type.String()),
69
61
  voice: Type.Optional(Type.Boolean()),
70
62
  handoff: Type.Optional(Type.String()),
@@ -83,7 +75,7 @@ const AgentsRequest = Type.Object(
83
75
  pane: Type.Optional(Type.String()),
84
76
  cwd: Type.Optional(Type.String()),
85
77
  message: Type.Optional(
86
- Type.String({ description: "Initial task or follow-up" }),
78
+ Type.String({ description: "Task, follow-up or extension reply" }),
87
79
  ),
88
80
  base: Type.Optional(Type.String({ description: "Review base branch" })),
89
81
  blocking: Type.Optional(
@@ -99,14 +91,17 @@ const AgentsRequest = Type.Object(
99
91
  status: Type.Optional(StringEnum(STATUSES)),
100
92
  source: Type.Optional(StringEnum(READ_SOURCES)),
101
93
  lines: Type.Optional(Type.Integer({ minimum: 1, maximum: 200 })),
102
- ask_id: Type.Optional(Type.String()),
103
- answers: Type.Optional(Type.Array(AskAnswerParameters)),
94
+ extension: Type.Optional(Type.String()),
95
+ id: Type.Optional(Type.String()),
104
96
  },
105
97
  { additionalProperties: false },
106
98
  );
107
99
 
108
100
  export const AgentsParameters = Type.Object({
109
101
  action: Type.Optional(StringEnum(ACTIONS)),
102
+ commands: Type.Optional(Type.Literal(true)),
103
+ target: Type.Optional(Type.String()),
104
+ machine: Type.Optional(Type.String()),
110
105
  });
111
106
 
112
107
  export type AgentsParams = Static<typeof AgentsRequest>;
@@ -140,16 +135,30 @@ export function parseAgentsRequest(input: unknown): AgentsParams {
140
135
  throw new Error("agents request must be a JSON object");
141
136
  }
142
137
  if (Object.keys(value).length === 0) return { action: "help" };
143
- const action = "action" in value ? value.action : undefined;
138
+ let request = value as Record<string, unknown>;
139
+ if (!("action" in request) && request["commands"] === true)
140
+ request = { ...request, action: "help" };
141
+ const action = request["action"];
144
142
  if (typeof action !== "string" || !Object.hasOwn(ACTION_FIELDS, action)) {
145
143
  throw new Error(`agents action must be one of: ${ACTIONS.join(", ")}`);
146
144
  }
147
- if (action === "send" && "blocking" in value) {
145
+ if (action === "send" && "blocking" in request) {
148
146
  throw new Error(
149
147
  "send is message-only; omit blocking. Use assign to delegate work",
150
148
  );
151
149
  }
152
- const request = value as Record<string, unknown>;
150
+ if ("commands" in request && action !== "help")
151
+ throw new Error("commands requires action=help or no action");
152
+ if (
153
+ action === "help" &&
154
+ request["commands"] !== true &&
155
+ ("target" in request || "machine" in request)
156
+ )
157
+ throw new Error("target and machine require commands:true for help");
158
+ if (action === "help" && "machine" in request && !("target" in request))
159
+ throw new Error(
160
+ "machine requires target for command discovery; omit both for this session",
161
+ );
153
162
  if (
154
163
  (action === "attach" || action === "detach") &&
155
164
  (typeof request["context"] !== "boolean" ||
@@ -159,25 +168,26 @@ export function parseAgentsRequest(input: unknown): AgentsParams {
159
168
  throw new Error(
160
169
  `${action} requires context and board booleans; enable at least one`,
161
170
  );
162
- const askId = request["ask_id"];
163
- if (action === "answer" && (typeof askId !== "string" || !askId.trim())) {
164
- throw new Error("ask_id is required for answer");
165
- }
166
- if (action === "answer" && !Array.isArray(request["answers"])) {
167
- 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");
168
178
  }
169
- const unknown = Object.keys(value).filter(
179
+ const unknown = Object.keys(request).filter(
170
180
  (key) => !ACTION_FIELDS[action as keyof typeof ACTION_FIELDS].has(key),
171
181
  );
172
182
  if (unknown.length > 0) {
173
183
  throw new Error(`unknown ${action} field(s): ${unknown.join(", ")}`);
174
184
  }
175
- if (!Check(AgentsRequest, value)) {
185
+ if (!Check(AgentsRequest, request)) {
176
186
  throw new Error(
177
187
  `invalid ${action} request; call agents help for its contract`,
178
188
  );
179
189
  }
180
- return value as AgentsParams;
190
+ return request as AgentsParams;
181
191
  }
182
192
 
183
193
  export function isBlockingAgentsCall(input: unknown): boolean {
@@ -28,6 +28,8 @@ export async function agentsHelp(
28
28
  ): Promise<Record<string, unknown>> {
29
29
  const profiles = await loadAgentProfiles();
30
30
  return {
31
+ commands:
32
+ "commands: true lists available slash commands with descriptions; defaults to this session, target and machine optionally select another session; does not execute commands",
31
33
  actions: {
32
34
  help: "",
33
35
  list: "machine?",
@@ -43,24 +45,25 @@ export async function agentsHelp(
43
45
  attach: "target context board machine?",
44
46
  detach: "target context board machine?",
45
47
  read: "target machine? source? lines?",
46
- answer: "target ask_id answers machine?",
48
+ reply: "target extension id message machine?",
47
49
  },
48
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",
49
53
  machine:
50
54
  "Omit for local (host running Pi); list/find omit for all machines. Remote: profile ID from list, not label/hostname",
51
55
  target:
52
56
  "Use spawn/find target exactly; /root selects this family's live root",
53
- label: "2-3 words; tab/session",
57
+ label: "Concise tab/session name",
54
58
  ...(boardAvailable
55
59
  ? {
56
60
  board_thread_id:
57
61
  "Existing shared-board thread; child receives a read reference",
58
62
  }
59
63
  : {}),
60
- answers: "[{selections?:string[],other?:string,comment?:string}]",
61
- ask_id: "Exact pending Ask ID",
62
- send: "Only needed input or work changes; wakes idle agents, no wait/watch. Close finished workers with /quit, not acknowledgement messages",
63
- 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",
64
67
  focus:
65
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",
66
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 ??
@@ -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,8 @@ 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
+ import type { createPeerCommands } from "./peer-commands.js";
32
33
  import type { SharedAgentContext } from "./shared-context.js";
33
34
 
34
35
  export function createAgentsTool(
@@ -36,6 +37,7 @@ export function createAgentsTool(
36
37
  sharedContext: SharedAgentContext,
37
38
  board: AgentBoard,
38
39
  pi: ExtensionAPI,
40
+ commands: ReturnType<typeof createPeerCommands>,
39
41
  ) {
40
42
  return defineTool({
41
43
  name: "agents",
@@ -47,9 +49,11 @@ export function createAgentsTool(
47
49
  const params = parseAgentsRequest(input);
48
50
  const executionSignal = signal ?? new AbortController().signal;
49
51
  const update = onUpdate ?? (() => undefined);
50
- if (params.action === "help") {
52
+ if (params.action === "help" && !params.commands) {
51
53
  return toolResult(await agentsHelp(board.enabled(ctx)));
52
54
  }
55
+ if (params.commands && params.target === undefined)
56
+ return toolResult({ commands: commands.available() });
53
57
  if (params.action === "list") {
54
58
  return toolResult(await listFleetAgents(fleet, params));
55
59
  }
@@ -119,6 +123,13 @@ export function createAgentsTool(
119
123
  target,
120
124
  runtime.local ? process.env["HERDR_PANE_ID"] : "",
121
125
  );
126
+ if (params.commands) {
127
+ return toolResult({
128
+ machine: runtime.machine,
129
+ target: panel.pane_id,
130
+ commands: await runtime.client.commands(panel),
131
+ });
132
+ }
122
133
  if (params.action === "attach" || params.action === "detach") {
123
134
  return toolResult(
124
135
  await sharedContext.attachment[params.action](
@@ -154,21 +165,12 @@ export function createAgentsTool(
154
165
  ...(view.assistant
155
166
  ? { reply: view.assistant.text }
156
167
  : { reply: null }),
157
- ...(view.ask &&
158
- (panel.agent_status === "blocked" || view.ask.delivery === "steer")
159
- ? {
160
- ask: modelAsk(view.ask),
161
- }
168
+ ...(view.extensionMessages
169
+ ? { extensionMessages: view.extensionMessages }
162
170
  : {}),
163
171
  });
164
172
  }
165
173
  if (params.action === "send" || params.action === "assign") {
166
- if (panel.agent_status === "blocked") {
167
- const view = await runtime.monitor.view(panel);
168
- throw new Error(
169
- `${panel.pane_id} is blocked${view.ask ? " on ask; use action=answer" : ""}`,
170
- );
171
- }
172
174
  const message = required(params.message, "message");
173
175
  const attributedMessage = await attributeAgentPrompt(
174
176
  fleet.connected().client,
@@ -181,6 +183,8 @@ export function createAgentsTool(
181
183
  panel,
182
184
  attributedMessage,
183
185
  );
186
+ if (!receipt.command)
187
+ runtime.monitor.noteMessage(panel.pane_id, message);
184
188
  return toolResult({
185
189
  sent: true,
186
190
  ...(receipt.command ? { commandSubmitted: true } : {}),
@@ -220,8 +224,8 @@ export function createAgentsTool(
220
224
  dispatch.warning,
221
225
  );
222
226
  }
223
- if (params.action === "answer") {
224
- return answerAgent(runtime, panel, params, executionSignal, update);
227
+ if (params.action === "reply") {
228
+ return replyAgent(runtime, panel, params, executionSignal, update);
225
229
  }
226
230
  throw new Error(`unsupported action ${params.action}`);
227
231
  },
@@ -283,20 +287,10 @@ export function createAgentsTool(
283
287
  if (!options.expanded) return title;
284
288
  const reply =
285
289
  typeof details["reply"] === "string" ? details["reply"] : undefined;
286
- const ask =
287
- typeof details["ask"] === "object" && details["ask"] !== null
288
- ? (details["ask"] as { prompts?: unknown })
289
- : undefined;
290
290
  const informational = Object.fromEntries(
291
- Object.entries(details).filter(
292
- ([key]) => key !== "reply" && key !== "ask",
293
- ),
291
+ Object.entries(details).filter(([key]) => key !== "reply"),
294
292
  );
295
- if (
296
- !reply &&
297
- !Array.isArray(ask?.prompts) &&
298
- Object.keys(informational).length === 0
299
- ) {
293
+ if (!reply && Object.keys(informational).length === 0) {
300
294
  return title;
301
295
  }
302
296
  const container = new Container();
@@ -311,22 +305,7 @@ export function createAgentsTool(
311
305
  container.addChild(new Spacer(1));
312
306
  container.addChild(new Markdown(reply, 0, 0, getMarkdownTheme()));
313
307
  }
314
- if (Array.isArray(ask?.prompts)) {
315
- const titles = ask.prompts
316
- .flatMap((prompt) =>
317
- typeof prompt === "object" &&
318
- prompt !== null &&
319
- "title" in prompt &&
320
- typeof prompt.title === "string"
321
- ? [prompt.title]
322
- : [],
323
- )
324
- .join(", ");
325
- if (titles) {
326
- container.addChild(new Spacer(1));
327
- container.addChild(new Text(theme.fg("warning", titles), 0, 0));
328
- }
329
- }
308
+
330
309
  return container;
331
310
  },
332
311
  });