@howaboua/pi-shepherdr 0.1.3 → 0.1.5

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,27 @@
1
1
  # @howaboua/pi-shepherdr
2
2
 
3
+ ## 0.1.5
4
+
5
+ - Make the agents tool always available and start fleet monitoring automatically. `/herdr` now toggles only orchestration guidance, not tool availability.
6
+
7
+ ## 0.1.4
8
+
9
+ - Preserve extension-owned messages while delivering true developer-role policy through compatible Pi Codex Responses adapters.
10
+
11
+ - Add an optional custom-message API that retains caller rendering and restoration fields.
12
+ - Route Shepherdr's unclaimed worker events and orchestration toggles through it, preserving ordinary Pi delivery when unavailable.
13
+ - Send review preface/triage policy and realtime voice start/end guidance as developer messages without elevating raw reviewer findings, spoken delegations, or transcript tails.
14
+ - Keep persisted developer messages in context across model switches, using ordinary Pi conversion on incompatible models.
15
+
16
+ - Fix worker settlement, custom model preservation, and prompt-only image generation.
17
+
18
+ - Settle Shepherdr workers after Pi expands skill or prompt-template invocations.
19
+ - Preserve custom Codex models and `models.json` overrides, including after refresh.
20
+ - Keep optional tool arguments optional in Codex Responses requests while preserving explicit strict sampling.
21
+ - Treat null image selectors as absent, so prompt-only requests generate rather than edit.
22
+ - Honor the details toggle in Notebook Mode to hide duplicate output previews.
23
+ - Show submitted messages without waiting for cached WebSocket warmup, while keeping generation serialized behind it.
24
+
3
25
  ## 0.1.3
4
26
 
5
27
  - Replaced Shepherdr's fire-and-forget tool with persistent blocking and asynchronous agents in normal Pi, Code Mode, and Notebook Mode.
package/README.md CHANGED
@@ -6,6 +6,8 @@ Shepherdr combines a monitored [Herdr](https://herdr.dev) fleet with blocking an
6
6
 
7
7
  Asynchronous calls return after dispatch, then push completion, failure or blockage into the controller with a steer message. The model never has to poll. Blocking calls hold the tool call and return the worker's reply directly.
8
8
 
9
+ With Pi Codex's compatible custom developer-message API active, asynchronous worker reports and orchestration toggles use the Responses developer role while retaining their normal display and session restoration. Without that API or adapter, delivery remains ordinary Pi custom messages. Blocking results stay in the tool response.
10
+
9
11
  ## Install
10
12
 
11
13
  ```bash
@@ -20,17 +22,17 @@ herdr integration install pi
20
22
 
21
23
  Do not load Pi Codex's example `agents.toml` custom tool alongside Shepherdr; they own the same agent surface.
22
24
 
23
- Pi Codex 3.0.24 or newer is optional. Without it, Shepherdr remains a normal Pi extension.
25
+ Pi Codex 3.0.25 or newer is optional. Without it, Shepherdr remains a normal Pi extension.
24
26
 
25
27
  ## Enable orchestration
26
28
 
27
- Pi sessions remain ordinary workers until explicitly promoted. Run Pi inside Herdr, then activate the agent tool and orchestration guidance for the current session:
29
+ The agent tool is always available in Pi, Code Mode and Notebook Mode. Run Pi inside Herdr to connect the fleet and start monitoring automatically. To prioritize orchestration over direct work for the current session:
28
30
 
29
31
  ```text
30
32
  /herdr
31
33
  ```
32
34
 
33
- The command records one visible mode message without triggering a turn. Run `/herdr` again to return to normal guidance while keeping the agent tool available. Resumed controller sessions restore their last mode; new worker sessions in the same directory remain dormant.
35
+ The command only records one visible guidance message without triggering a turn. Run `/herdr` again to return to normal guidance. Resumed sessions restore their last mode; new sessions start with normal guidance. Tool availability and monitoring do not depend on this mode.
34
36
 
35
37
  `/herdr machines` opens the Add/Remove Machine interface. Settings live at `<pi-agent-directory>/shepherdr.json`, where the directory defaults to `~/.pi/agent` and `PI_CODING_AGENT_DIR` overrides it. `/herdr connect [machine]` retries configured remotes after activation.
36
38
 
package/index.ts CHANGED
@@ -3,6 +3,7 @@ import registerPackageChangelog from "./changelog.js";
3
3
  import { isBlockingAgentsCall } from "./src/agents-contract.js";
4
4
  import { createAgentsTool } from "./src/agents-tool.js";
5
5
  import { registerAgentController } from "./src/controller.js";
6
+ import { registerDeveloperDelivery } from "./src/delivery.js";
6
7
  import { AgentFleet } from "./src/fleet.js";
7
8
  import { registerAgentEventRenderer } from "./src/messages.js";
8
9
  import { installAgentProfiles } from "./src/profiles.js";
@@ -15,35 +16,29 @@ export default async function shepherdrExtension(
15
16
  ): Promise<void> {
16
17
  registerPackageChangelog(pi);
17
18
  await installAgentProfiles();
19
+ await registerDeveloperDelivery(pi);
18
20
  const fleet = new AgentFleet(pi);
19
21
  const tool = createAgentsTool(fleet);
20
22
 
21
23
  registerAgentEventRenderer(pi);
22
24
  pi.registerTool(tool);
23
- const registration = await registerAgentsInCodeMode(pi, tool, fleet);
24
- registerAgentController(pi, fleet, {
25
- onActiveChange: () => registration?.refresh(),
26
- });
25
+ await registerAgentsInCodeMode(pi, tool);
26
+ registerAgentController(pi, fleet);
27
27
  }
28
28
 
29
29
  async function registerAgentsInCodeMode(
30
30
  pi: ExtensionAPI,
31
31
  tool: ReturnType<typeof createAgentsTool>,
32
- fleet: AgentFleet,
33
32
  ) {
34
33
  try {
35
34
  const { adaptToolForCodeMode, registerCodeModeExtensionTools } =
36
35
  await import("@howaboua/pi-codex-conversion/code-mode");
37
- const registration = registerCodeModeExtensionTools(
38
- pi,
39
- () => [
40
- adaptToolForCodeMode(tool, {
41
- blocking: isBlockingAgentsCall,
42
- usage: 'await tools.agents({ action: "help" }) // first call alone',
43
- }),
44
- ],
45
- { isActive: () => fleet.isActive() },
46
- );
36
+ const registration = registerCodeModeExtensionTools(pi, () => [
37
+ adaptToolForCodeMode(tool, {
38
+ blocking: isBlockingAgentsCall,
39
+ usage: 'await tools.agents({ action: "help" }) // first call alone',
40
+ }),
41
+ ]);
47
42
  pi.on("session_shutdown", () => registration.unregister());
48
43
  return registration;
49
44
  } catch (error) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@howaboua/pi-shepherdr",
3
- "version": "0.1.3",
3
+ "version": "0.1.5",
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.24",
46
+ "@howaboua/pi-codex-conversion": ">=3.0.29",
47
47
  "@earendil-works/pi-ai": ">=0.84.3",
48
48
  "@earendil-works/pi-coding-agent": ">=0.84.3",
49
49
  "@earendil-works/pi-tui": ">=0.84.3",
@@ -55,11 +55,11 @@
55
55
  }
56
56
  },
57
57
  "devDependencies": {
58
- "@howaboua/pi-codex-conversion": "3.0.24",
58
+ "@howaboua/pi-codex-conversion": "3.0.29",
59
59
  "@biomejs/biome": "^2.5.10",
60
- "@earendil-works/pi-ai": "0.84.4",
61
- "@earendil-works/pi-coding-agent": "0.84.4",
62
- "@earendil-works/pi-tui": "0.84.4",
60
+ "@earendil-works/pi-ai": "0.85.1",
61
+ "@earendil-works/pi-coding-agent": "0.85.1",
62
+ "@earendil-works/pi-tui": "0.85.1",
63
63
  "@types/node": "^26.2.0",
64
64
  "typebox": "1.3.18",
65
65
  "typescript": "^7.0.2"
package/src/activity.ts CHANGED
@@ -33,11 +33,11 @@ export function activityAttemptId(activity: AgentActivity): string | undefined {
33
33
 
34
34
  export function activityExpectedUser(
35
35
  activity: AgentActivity,
36
- ): { after: string | null; text: string } | undefined {
36
+ ): { after: string | null } | undefined {
37
37
  return activity.phase !== "settled" &&
38
38
  activity.expectedUserAfter !== undefined &&
39
39
  activity.task
40
- ? { after: activity.expectedUserAfter, text: activity.task }
40
+ ? { after: activity.expectedUserAfter }
41
41
  : undefined;
42
42
  }
43
43
 
package/src/controller.ts CHANGED
@@ -2,14 +2,11 @@ import type {
2
2
  ExtensionAPI,
3
3
  ExtensionContext,
4
4
  } from "@earendil-works/pi-coding-agent";
5
+ import { sendPolicyMessage } from "./delivery.js";
5
6
  import type { AgentFleet } from "./fleet.js";
6
7
  import { showMachineMenu } from "./machine-menu.js";
7
8
  import { loadAgentProfiles } from "./profiles.js";
8
9
 
9
- interface AgentControllerOptions {
10
- onActiveChange?(): void;
11
- }
12
-
13
10
  const ORCHESTRATION_STATE_TYPE = "pi-shepherdr-orchestration-state";
14
11
  const GENERAL_ORCHESTRATION_MESSAGE =
15
12
  "Your main goal from now on is to orchestrate agents. Fan out suitable work to general agents, synthesize their results, and report the outcome. Work directly only when asked or for routine local tasks.";
@@ -20,13 +17,8 @@ const NORMAL_MESSAGE = "Work normally. Delegate only when useful or requested.";
20
17
  export function registerAgentController(
21
18
  pi: ExtensionAPI,
22
19
  fleet: AgentFleet,
23
- options: AgentControllerOptions = {},
24
20
  ): void {
25
21
  let orchestrationEnabled = false;
26
- const setActive = (active: boolean) => {
27
- setToolActive(pi, "agents", active);
28
- options.onActiveChange?.();
29
- };
30
22
  pi.registerCommand("herdr", {
31
23
  description: "Toggle agent orchestration or manage Herdr machines",
32
24
  getArgumentCompletions: (prefix) =>
@@ -37,15 +29,10 @@ export function registerAgentController(
37
29
  const [rawAction = "", ...rest] = args.trim().split(/\s+/);
38
30
  const action = rawAction.toLowerCase();
39
31
  if (!action) {
40
- orchestrationEnabled = restoreOrchestrationState(ctx).enabled;
41
- if (
42
- !fleet.isActive() &&
43
- !(await activateController(fleet, ctx, setActive))
44
- ) {
45
- return;
46
- }
32
+ orchestrationEnabled = restoreOrchestrationState(ctx);
47
33
  orchestrationEnabled = !orchestrationEnabled;
48
- pi.sendMessage(
34
+ sendPolicyMessage(
35
+ pi,
49
36
  {
50
37
  customType: ORCHESTRATION_STATE_TYPE,
51
38
  content: orchestrationEnabled
@@ -70,8 +57,8 @@ export function registerAgentController(
70
57
  }
71
58
  if (action === "connect") {
72
59
  if (!fleet.isActive()) {
73
- ctx.ui.notify("Run /herdr to activate agents first", "warning");
74
- return;
60
+ await activateController(fleet, ctx);
61
+ if (!fleet.isActive()) return;
75
62
  }
76
63
  try {
77
64
  ctx.ui.notify(fleet.connect(rest[0]), "info");
@@ -88,11 +75,8 @@ export function registerAgentController(
88
75
  });
89
76
 
90
77
  pi.on("session_start", async (_event, ctx) => {
91
- const state = restoreOrchestrationState(ctx);
92
- orchestrationEnabled = state.enabled;
93
- fleet.deactivate();
94
- setActive(false);
95
- if (state.recorded) await activateController(fleet, ctx, setActive);
78
+ orchestrationEnabled = restoreOrchestrationState(ctx);
79
+ await activateController(fleet, ctx);
96
80
  });
97
81
 
98
82
  pi.on("session_shutdown", () => {
@@ -106,12 +90,8 @@ async function orchestrationMessage(): Promise<string> {
106
90
  : ORCHESTRATION_MESSAGE;
107
91
  }
108
92
 
109
- function restoreOrchestrationState(ctx: ExtensionContext): {
110
- enabled: boolean;
111
- recorded: boolean;
112
- } {
93
+ function restoreOrchestrationState(ctx: ExtensionContext): boolean {
113
94
  let enabled = false;
114
- let recorded = false;
115
95
  for (const entry of ctx.sessionManager.getBranch()) {
116
96
  if (
117
97
  (entry.type !== "custom" && entry.type !== "custom_message") ||
@@ -127,52 +107,28 @@ function restoreOrchestrationState(ctx: ExtensionContext): {
127
107
  typeof state.enabled === "boolean"
128
108
  ) {
129
109
  enabled = state.enabled;
130
- recorded = true;
131
110
  }
132
111
  }
133
- return { enabled, recorded };
112
+ return enabled;
134
113
  }
135
114
 
136
115
  async function activateController(
137
116
  fleet: AgentFleet,
138
117
  ctx: ExtensionContext,
139
- setActive: (active: boolean) => void,
140
118
  ): Promise<boolean> {
141
119
  if (process.env["HERDR_ENV"] !== "1" || !process.env["HERDR_SOCKET_PATH"]) {
142
- setActive(false);
143
- ctx.ui.notify(
144
- "Agent orchestration requires Pi to run inside Herdr",
145
- "error",
146
- );
120
+ ctx.ui.notify("Shepherdr requires Pi to run inside Herdr", "error");
147
121
  return false;
148
122
  }
149
123
  try {
150
124
  await fleet.activate(ctx);
151
- setActive(true);
152
125
  return true;
153
126
  } catch (error) {
154
127
  fleet.deactivate();
155
- setActive(false);
156
128
  ctx.ui.notify(
157
- `Agent orchestration could not start: ${error instanceof Error ? error.message : String(error)}`,
129
+ `Shepherdr could not start: ${error instanceof Error ? error.message : String(error)}`,
158
130
  "error",
159
131
  );
160
132
  return false;
161
133
  }
162
134
  }
163
-
164
- function setToolActive(
165
- pi: ExtensionAPI,
166
- toolName: string,
167
- active: boolean,
168
- ): void {
169
- const current = pi.getActiveTools();
170
- const withoutTool = current.filter((name) => name !== toolName);
171
- const next = active ? [...withoutTool, toolName] : withoutTool;
172
- if (
173
- next.length !== current.length ||
174
- next.some((name, index) => name !== current[index])
175
- ) {
176
- pi.setActiveTools(next);
177
- }
178
- }
@@ -0,0 +1,68 @@
1
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
+ import type {
3
+ CodexDeveloperCustomMessage,
4
+ CodexDeveloperMessageOptions,
5
+ trySendCodexDeveloperCustomMessage,
6
+ } from "@howaboua/pi-codex-conversion/developer-messages";
7
+
8
+ const senders = new WeakMap<
9
+ ExtensionAPI,
10
+ typeof trySendCodexDeveloperCustomMessage
11
+ >();
12
+ const PACKAGE = "@howaboua/pi-codex-conversion";
13
+ const MODULE = `${PACKAGE}/developer-messages`;
14
+
15
+ export async function registerDeveloperDelivery(
16
+ pi: ExtensionAPI,
17
+ ): Promise<void> {
18
+ try {
19
+ const api = await import(
20
+ "@howaboua/pi-codex-conversion/developer-messages"
21
+ );
22
+ if (typeof api.trySendCodexDeveloperCustomMessage === "function")
23
+ senders.set(pi, api.trySendCodexDeveloperCustomMessage);
24
+ } catch (error) {
25
+ if (!isUnavailable(error)) throw error;
26
+ }
27
+ }
28
+
29
+ export function sendPolicyMessage(
30
+ pi: ExtensionAPI,
31
+ message: CodexDeveloperCustomMessage,
32
+ options: CodexDeveloperMessageOptions,
33
+ ): void {
34
+ if (senders.get(pi)?.(pi, message, options)) return;
35
+ pi.sendMessage(message, options);
36
+ }
37
+
38
+ function isUnavailable(error: unknown): boolean {
39
+ if (
40
+ !error ||
41
+ typeof error !== "object" ||
42
+ !("code" in error) ||
43
+ !("message" in error) ||
44
+ typeof error.message !== "string"
45
+ )
46
+ return false;
47
+ if (
48
+ error.code === "ERR_MODULE_NOT_FOUND" ||
49
+ error.code === "MODULE_NOT_FOUND"
50
+ ) {
51
+ const missing = error.message.match(
52
+ /Cannot find (?:package|module) ['"]([^'"]+)['"]/,
53
+ )?.[1];
54
+ const normalized = missing?.replaceAll("\\", "/").replace(/\.js$/, "");
55
+ return (
56
+ missing === PACKAGE ||
57
+ normalized === MODULE ||
58
+ normalized?.endsWith(`/${MODULE}`) === true
59
+ );
60
+ }
61
+ return (
62
+ (error.code === "ERR_PACKAGE_PATH_NOT_EXPORTED" ||
63
+ error.code === "ERR_UNSUPPORTED_DIR_IMPORT") &&
64
+ (error.message.includes(MODULE) ||
65
+ (error.message.includes("Package subpath './developer-messages'") &&
66
+ error.message.includes(PACKAGE)))
67
+ );
68
+ }
@@ -94,7 +94,10 @@ export async function showMachineMenu(
94
94
  ]);
95
95
  if (action === "Connect") {
96
96
  if (!fleet.isActive()) {
97
- ctx.ui.notify("Run /herdr to activate agents first", "warning");
97
+ ctx.ui.notify(
98
+ "Fleet unavailable; run /herdr connect to retry",
99
+ "warning",
100
+ );
98
101
  return;
99
102
  }
100
103
  ctx.ui.notify(fleet.connect(name), "info");
package/src/messages.ts CHANGED
@@ -5,6 +5,7 @@ import {
5
5
  } from "@earendil-works/pi-coding-agent";
6
6
  import { Box, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
7
7
  import { activityTask } from "./activity.js";
8
+ import { sendPolicyMessage } from "./delivery.js";
8
9
  import type {
9
10
  LatestAssistant,
10
11
  MonitoredAgent,
@@ -314,7 +315,8 @@ export function injectAgentEvent(
314
315
  const delivery = ctx.isIdle()
315
316
  ? { triggerTurn: true, deliverAs: "steer" as const }
316
317
  : { deliverAs: "steer" as const };
317
- pi.sendMessage(
318
+ sendPolicyMessage(
319
+ pi,
318
320
  {
319
321
  customType: AGENT_EVENT_MESSAGE_TYPE,
320
322
  content: message.content,
package/src/settlement.ts CHANGED
@@ -245,12 +245,12 @@ export class SettlementReporter {
245
245
  if (activityAttemptId(current.activity) !== retryState.attemptId) return;
246
246
  const retryRequest = task ? { ...request, task } : request;
247
247
  const expectedUser = activityExpectedUser(current.activity);
248
+ // Pi persists expanded skills/templates, not the submitted command text.
248
249
  if (
249
250
  expectedUser &&
250
251
  (settlement.session.assistantAfterUser !== true ||
251
252
  !settlement.session.user ||
252
- settlement.session.user.id === expectedUser.after ||
253
- settlement.session.user.text !== expectedUser.text)
253
+ settlement.session.user.id === expectedUser.after)
254
254
  ) {
255
255
  if (!this.retry(lifecycle, retryRequest, retryState)) {
256
256
  this.failReconciliation(