@howaboua/pi-shepherdr 0.2.16 → 0.2.17

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,9 @@
1
1
  # @howaboua/pi-shepherdr
2
2
 
3
+ ## 0.2.17
4
+
5
+ - Added slash-command discovery with configured descriptions for the current session or another agent, without executing commands or interrupting its work.
6
+
3
7
  ## 0.2.16
4
8
 
5
9
  - ### Breaking changes
package/README.md CHANGED
@@ -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 |
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.17",
4
4
  "description": "Persistent blocking and asynchronous Pi agents through Herdr.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -24,7 +24,7 @@ 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"]),
@@ -65,6 +65,7 @@ const AskAnswerParameters = Type.Object(
65
65
  const AgentsRequest = Type.Object(
66
66
  {
67
67
  action: StringEnum(ACTIONS),
68
+ commands: Type.Optional(Type.Literal(true)),
68
69
  machine: Type.Optional(Type.String()),
69
70
  voice: Type.Optional(Type.Boolean()),
70
71
  handoff: Type.Optional(Type.String()),
@@ -107,6 +108,9 @@ const AgentsRequest = Type.Object(
107
108
 
108
109
  export const AgentsParameters = Type.Object({
109
110
  action: Type.Optional(StringEnum(ACTIONS)),
111
+ commands: Type.Optional(Type.Literal(true)),
112
+ target: Type.Optional(Type.String()),
113
+ machine: Type.Optional(Type.String()),
110
114
  });
111
115
 
112
116
  export type AgentsParams = Static<typeof AgentsRequest>;
@@ -140,16 +144,30 @@ export function parseAgentsRequest(input: unknown): AgentsParams {
140
144
  throw new Error("agents request must be a JSON object");
141
145
  }
142
146
  if (Object.keys(value).length === 0) return { action: "help" };
143
- const action = "action" in value ? value.action : undefined;
147
+ let request = value as Record<string, unknown>;
148
+ if (!("action" in request) && request["commands"] === true)
149
+ request = { ...request, action: "help" };
150
+ const action = request["action"];
144
151
  if (typeof action !== "string" || !Object.hasOwn(ACTION_FIELDS, action)) {
145
152
  throw new Error(`agents action must be one of: ${ACTIONS.join(", ")}`);
146
153
  }
147
- if (action === "send" && "blocking" in value) {
154
+ if (action === "send" && "blocking" in request) {
148
155
  throw new Error(
149
156
  "send is message-only; omit blocking. Use assign to delegate work",
150
157
  );
151
158
  }
152
- const request = value as Record<string, unknown>;
159
+ if ("commands" in request && action !== "help")
160
+ throw new Error("commands requires action=help or no action");
161
+ if (
162
+ action === "help" &&
163
+ request["commands"] !== true &&
164
+ ("target" in request || "machine" in request)
165
+ )
166
+ throw new Error("target and machine require commands:true for help");
167
+ if (action === "help" && "machine" in request && !("target" in request))
168
+ throw new Error(
169
+ "machine requires target for command discovery; omit both for this session",
170
+ );
153
171
  if (
154
172
  (action === "attach" || action === "detach") &&
155
173
  (typeof request["context"] !== "boolean" ||
@@ -166,18 +184,18 @@ export function parseAgentsRequest(input: unknown): AgentsParams {
166
184
  if (action === "answer" && !Array.isArray(request["answers"])) {
167
185
  throw new Error("answers is required for answer");
168
186
  }
169
- const unknown = Object.keys(value).filter(
187
+ const unknown = Object.keys(request).filter(
170
188
  (key) => !ACTION_FIELDS[action as keyof typeof ACTION_FIELDS].has(key),
171
189
  );
172
190
  if (unknown.length > 0) {
173
191
  throw new Error(`unknown ${action} field(s): ${unknown.join(", ")}`);
174
192
  }
175
- if (!Check(AgentsRequest, value)) {
193
+ if (!Check(AgentsRequest, request)) {
176
194
  throw new Error(
177
195
  `invalid ${action} request; call agents help for its contract`,
178
196
  );
179
197
  }
180
- return value as AgentsParams;
198
+ return request as AgentsParams;
181
199
  }
182
200
 
183
201
  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?",
@@ -29,6 +29,7 @@ import type { AgentBoard } from "./board/host.js";
29
29
  import type { AgentFleet } from "./fleet.js";
30
30
  import { resolvePiAgent } from "./herdr.js";
31
31
  import { attributeAgentPrompt, modelAsk } 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](
@@ -2,13 +2,18 @@ import { createConnection } from "node:net";
2
2
  import { hostname } from "node:os";
3
3
  import { openPeerChannel } from "./remote/shepherdr-channel.mjs";
4
4
  import { requestContext } from "./remote/shepherdr-context.mjs";
5
- import { sendPeerFocus, sendPeerMessage } from "./remote/shepherdr-peer.mjs";
5
+ import {
6
+ sendPeerCommands,
7
+ sendPeerFocus,
8
+ sendPeerMessage,
9
+ } from "./remote/shepherdr-peer.mjs";
6
10
  import type {
7
11
  FocusRequest,
8
12
  HerdrEvent,
9
13
  MachineIdentity,
10
14
  PaneInfo,
11
15
  PeerChannel,
16
+ PeerCommand,
12
17
  PeerDelivery,
13
18
  PeerMessage,
14
19
  } from "./types.js";
@@ -75,6 +80,7 @@ export interface HerdrConnection {
75
80
  contextRelayPath(): string;
76
81
  request<T>(method: string, params?: object, timeoutMs?: number): Promise<T>;
77
82
  sendMessage(agent: PaneInfo, message: PeerMessage): Promise<PeerDelivery>;
83
+ commands(agent: PaneInfo): Promise<PeerCommand[]>;
78
84
  subscribe(
79
85
  subscriptions: object[],
80
86
  onEvent: (event: HerdrEvent) => void,
@@ -136,6 +142,13 @@ export class HerdrClient implements HerdrConnection {
136
142
  );
137
143
  }
138
144
 
145
+ commands(agent: PaneInfo): Promise<PeerCommand[]> {
146
+ return sendPeerCommands(
147
+ (method, params) => this.request(method, params),
148
+ agent,
149
+ );
150
+ }
151
+
139
152
  request<T>(
140
153
  method: string,
141
154
  params: object = {},
@@ -26,7 +26,31 @@ export function createPeerCommands(pi: ExtensionAPI) {
26
26
  }
27
27
  >();
28
28
  pi.on("session_shutdown", () => pending.clear());
29
+ const available = (configured?: Record<string, string>) => {
30
+ let allowed: Record<string, string>;
31
+ try {
32
+ allowed = configured ?? readExtensionCommands();
33
+ } catch {
34
+ throw new Error(
35
+ "Command permissions could not be read; built-in commands remain available. Ask the user to check Shepherdr's Agent commands settings",
36
+ );
37
+ }
38
+ return Object.entries(builtins)
39
+ .map(([name, description]) => ({ name, description }))
40
+ .concat(
41
+ pi.getCommands().flatMap((entry) => {
42
+ const description = allowed[entry.name];
43
+ return entry.source === "extension" &&
44
+ Object.hasOwn(allowed, entry.name) &&
45
+ description !== undefined &&
46
+ !Object.hasOwn(builtins, entry.name)
47
+ ? [{ name: entry.name, description }]
48
+ : [];
49
+ }),
50
+ );
51
+ };
29
52
  return {
53
+ available,
30
54
  async handle(args: string, ctx: ExtensionCommandContext): Promise<boolean> {
31
55
  const intent = pending.get(args);
32
56
  if (!intent) return false;
@@ -73,22 +97,12 @@ export function createPeerCommands(pi: ExtensionAPI) {
73
97
  !entry ||
74
98
  (entry.source === "extension" && !Object.hasOwn(allowed, name))
75
99
  ) {
76
- const available = Object.entries(builtins).concat(
77
- commands
78
- .filter(
79
- (entry) =>
80
- entry.source === "extension" &&
81
- Object.hasOwn(allowed, entry.name),
82
- )
83
- .flatMap((entry): [string, string][] => {
84
- const description = allowed[entry.name];
85
- return description === undefined
86
- ? []
87
- : [[entry.name, description]];
88
- }),
89
- );
90
100
  throw new Error(
91
- `Command /${name} is unavailable. Available commands:\n${available.map(([name, description]) => `/${name}: ${description}`).join("\n")}`,
101
+ `Command /${name} is unavailable. Available commands:\n${available(
102
+ allowed,
103
+ )
104
+ .map(({ name, description }) => `/${name}: ${description}`)
105
+ .join("\n")}`,
92
106
  );
93
107
  }
94
108
  return {
package/src/peer-inbox.ts CHANGED
@@ -116,9 +116,11 @@ async function openInbox(
116
116
  ctx.sessionManager.getSessionFile() !== sessionFile ||
117
117
  typeof request["id"] !== "string" ||
118
118
  (request["kind"] !== "focus" &&
119
+ request["kind"] !== "commands" &&
119
120
  request["kind"] !== "message" &&
120
121
  request["kind"] !== "channel") ||
121
122
  (request["kind"] !== "focus" &&
123
+ request["kind"] !== "commands" &&
122
124
  request["kind"] !== "channel" &&
123
125
  (typeof request["text"] !== "string" ||
124
126
  !request["text"].trim() ||
@@ -134,6 +136,18 @@ async function openInbox(
134
136
  });
135
137
  return;
136
138
  }
139
+ if (request["kind"] === "commands") {
140
+ try {
141
+ reply({ ok: true, command: false, commands: commands.available() });
142
+ } catch (error) {
143
+ reply({
144
+ ok: false,
145
+ rejected: true,
146
+ error: error instanceof Error ? error.message : String(error),
147
+ });
148
+ }
149
+ return;
150
+ }
137
151
  if (request["kind"] === "channel") {
138
152
  let focus;
139
153
  try {
@@ -6,7 +6,7 @@ import { createConnection } from "node:net";
6
6
  import { basename, dirname } from "node:path";
7
7
 
8
8
  export const MAX_PEER_FRAME_BYTES = 8 * 1024 * 1024;
9
- export const PEER_PROTOCOL = 3;
9
+ export const PEER_PROTOCOL = 4;
10
10
 
11
11
  /** @param {string} sessionFile @param {string} terminalId */
12
12
  export function peerInboxPath(sessionFile, terminalId) {
@@ -86,19 +86,26 @@ export async function readReceiver(path) {
86
86
  * @param {import("../types.js").PaneInfo} expected
87
87
  * @param {import("../types.js").PeerMessage} message
88
88
  * @param {import("../types.js").FocusRequest} [focus]
89
+ * @param {boolean} [commands]
89
90
  * @returns {Promise<import("../types.js").PeerDelivery>}
90
91
  */
91
- export async function sendPeerMessage(request, expected, message, focus) {
92
+ export async function sendPeerMessage(
93
+ request,
94
+ expected,
95
+ message,
96
+ focus,
97
+ commands = false,
98
+ ) {
92
99
  const { descriptor, sessionFile, agent } = await resolvePeerReceiver(
93
100
  request,
94
101
  expected,
95
- Boolean(focus),
102
+ Boolean(focus) || commands,
96
103
  );
97
104
  const id = randomUUID();
98
105
  const frame =
99
106
  JSON.stringify({
100
107
  protocol: PEER_PROTOCOL,
101
- kind: focus ? "focus" : "message",
108
+ kind: commands ? "commands" : focus ? "focus" : "message",
102
109
  focus,
103
110
  id,
104
111
  token: descriptor.token,
@@ -295,7 +302,13 @@ function deliverPeerFrame(
295
302
  // The receiver retains this socket through session_shutdown.
296
303
  // Only process exit ends it; never close a pane on a timeout.
297
304
  clearTimeout(timer);
298
- } else finish(undefined, { command: reply.command });
305
+ } else
306
+ finish(undefined, {
307
+ command: reply.command,
308
+ ...(reply.commands === undefined
309
+ ? {}
310
+ : { commands: reply.commands }),
311
+ });
299
312
  } else if (reply.ok === false && typeof reply.error === "string")
300
313
  finish(deliveryError(reply.error, reply.rejected === true));
301
314
  else failed();
@@ -320,6 +333,40 @@ export function sendPeerFocus(request, expected, focus) {
320
333
  );
321
334
  }
322
335
 
336
+ /** @param {unknown} value @returns {import("../types.js").PeerCommand[]} */
337
+ export function readPeerCommands(value) {
338
+ if (
339
+ !Array.isArray(value) ||
340
+ !value.every(
341
+ (entry) =>
342
+ entry &&
343
+ typeof entry === "object" &&
344
+ typeof entry.name === "string" &&
345
+ typeof entry.description === "string",
346
+ )
347
+ )
348
+ throw new Error(
349
+ "Command discovery returned an invalid list; ask the user to update and reload Shepherdr in the target session",
350
+ );
351
+ return value.map(({ name, description }) => ({ name, description }));
352
+ }
353
+
354
+ /**
355
+ * @param {(method: string, params: object) => Promise<unknown>} request
356
+ * @param {import("../types.js").PaneInfo} expected
357
+ * @returns {Promise<import("../types.js").PeerCommand[]>}
358
+ */
359
+ export async function sendPeerCommands(request, expected) {
360
+ const receipt = await sendPeerMessage(
361
+ request,
362
+ expected,
363
+ { text: "", sender: "" },
364
+ undefined,
365
+ true,
366
+ );
367
+ return readPeerCommands(receipt.commands);
368
+ }
369
+
323
370
  /**
324
371
  * @param {(method: string, params: object) => Promise<unknown>} request
325
372
  * @param {import("../types.js").PaneInfo} expected
@@ -9,11 +9,15 @@ import {
9
9
  relayContextPath,
10
10
  requestContext,
11
11
  } from "./shepherdr-context.mjs";
12
- import { sendPeerFocus, sendPeerMessage } from "./shepherdr-peer.mjs";
12
+ import {
13
+ sendPeerCommands,
14
+ sendPeerFocus,
15
+ sendPeerMessage,
16
+ } from "./shepherdr-peer.mjs";
13
17
  import { readSessionView } from "./shepherdr-session.mjs";
14
18
  import { watchSessions } from "./shepherdr-session-watch.mjs";
15
19
 
16
- const BRIDGE_VERSION = 18;
20
+ const BRIDGE_VERSION = 19;
17
21
  const MAX_FRAME_BYTES = 8 * 1024 * 1024;
18
22
  const subscriptions = new Map();
19
23
  const contextRelays = new Map();
@@ -329,6 +333,9 @@ async function handle(message) {
329
333
  if (message.op === "focus") {
330
334
  return sendPeerFocus(request, message.agent, message.request);
331
335
  }
336
+ if (message.op === "commands") {
337
+ return sendPeerCommands(request, message.agent);
338
+ }
332
339
  if (message.op === "channel_open") {
333
340
  const channel = await openPeerChannel(
334
341
  request,
@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
5
5
  import type { HerdrConnection } from "./herdr-client.js";
6
6
  import type { SshMachine } from "./machine-catalog.js";
7
7
  import { createBufferedChannel } from "./remote/shepherdr-channel.mjs";
8
+ import { readPeerCommands } from "./remote/shepherdr-peer.mjs";
8
9
  import type { AssistantReader } from "./session-reader.js";
9
10
  import type {
10
11
  HerdrEvent,
@@ -16,7 +17,7 @@ import type {
16
17
  SessionView,
17
18
  } from "./types.js";
18
19
 
19
- const BRIDGE_VERSION = 18;
20
+ const BRIDGE_VERSION = 19;
20
21
  const REMOTE_HELPER = "~/.pi/agent/shepherdr.mjs";
21
22
  const REMOTE_PEER_HELPER = "~/.pi/agent/shepherdr-peer.mjs";
22
23
  const REMOTE_CHANNEL_HELPER = "~/.pi/agent/shepherdr-channel.mjs";
@@ -309,6 +310,11 @@ export class RemoteHerdrClient implements HerdrConnection, AssistantReader {
309
310
  return this.relayPath;
310
311
  }
311
312
 
313
+ async commands(agent: PaneInfo): Promise<import("./types.js").PeerCommand[]> {
314
+ const result = await this.call({ op: "commands", agent }, 26_000);
315
+ return readPeerCommands(result);
316
+ }
317
+
312
318
  async sendMessage(
313
319
  agent: PaneInfo,
314
320
  message: PeerMessage,
package/src/types.ts CHANGED
@@ -8,6 +8,12 @@ export interface PeerMessage {
8
8
 
9
9
  export interface PeerDelivery {
10
10
  command: boolean;
11
+ commands?: PeerCommand[];
12
+ }
13
+
14
+ export interface PeerCommand {
15
+ name: string;
16
+ description: string;
11
17
  }
12
18
 
13
19
  export interface MachineIdentity {