@howaboua/pi-shepherdr 0.2.7 → 0.2.8
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 +7 -0
- package/README.md +10 -3
- package/package.json +1 -1
- package/profiles/reviewer/profile.json +1 -0
- package/src/agents-contract.ts +11 -5
- package/src/agents-discovery.ts +23 -8
- package/src/agents-spawn.ts +5 -2
- package/src/profiles.ts +38 -5
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
# @howaboua/pi-shepherdr
|
|
2
2
|
|
|
3
|
+
## 0.2.8
|
|
4
|
+
|
|
5
|
+
- Agent profiles now control delegation waiting and shared context.
|
|
6
|
+
|
|
7
|
+
- Removed reviewer-name blocking rules. Optional profile `blocking` forces blocking or asynchronous spawns, and help and list report the configured policy with the profile description.
|
|
8
|
+
- Added `share_context: false` for independent subagent notes and history. Existing installed profiles remain unchanged.
|
|
9
|
+
|
|
3
10
|
## 0.2.7
|
|
4
11
|
|
|
5
12
|
- Added opt-in shared notes and history for spawned agents with Pi Codex Conversion.
|
package/README.md
CHANGED
|
@@ -61,7 +61,7 @@ Call the `agents` tool with `action: "help"` before first use, then send flat re
|
|
|
61
61
|
| `watch` | Push future settlement from an existing Pi agent |
|
|
62
62
|
| `unwatch` | Stop reporting an agent |
|
|
63
63
|
|
|
64
|
-
`spawn` and `assign` block by default. Set `blocking: false` when the controller should continue other work immediately. Task completion and blockage are then delivered automatically.
|
|
64
|
+
`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.
|
|
65
65
|
|
|
66
66
|
`answer` requires the pending `ask_id` from `read` or a blocked report. It returns `accepted` only when that exact Ask persisted the supplied responses; an accepted retry sends no input.
|
|
67
67
|
|
|
@@ -69,8 +69,6 @@ Questions, status updates and replies use `send`. It returns after submission, d
|
|
|
69
69
|
|
|
70
70
|
Automatic delegation watches end when the task finishes or fails. Blocked tasks stay watched until resolved. Only an explicit `watch` keeps reporting subsequent work until `unwatch`. Sending an update to your worker preserves its existing task watch without replacing the task.
|
|
71
71
|
|
|
72
|
-
Reviewer spawns always block, even when `blocking: false` is supplied. The controller waits for the review before continuing work on its scope.
|
|
73
|
-
|
|
74
72
|
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.
|
|
75
73
|
|
|
76
74
|
Cancelling a blocking call does not kill its worker. The waiter detaches and the eventual result returns through normal asynchronous delivery.
|
|
@@ -89,6 +87,8 @@ For `answer` inside Code or Notebook Mode, update Pi Ask on workers together wit
|
|
|
89
87
|
|
|
90
88
|
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.
|
|
91
89
|
|
|
90
|
+
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.
|
|
91
|
+
|
|
92
92
|
Pi creates each worker session normally. The worker records its shared identity before Shepherdr delivers the first task; no pre-created session file or launch override is needed.
|
|
93
93
|
|
|
94
94
|
Remote sharing requires Remote storage and the same Codex account on both ends. Local and Tree route through the owning Pi sessions and existing SSH connections. Those owners and intermediate controllers must be running; unavailable routes fail explicitly. Resume the owner and use `/herdr connect` after a connection loss. No note store is copied or silently substituted.
|
|
@@ -126,6 +126,13 @@ That directory is authoritative after initialization. Edit a profile to change i
|
|
|
126
126
|
|
|
127
127
|
`prompt` is read as system-prompt text. An optional `prepare` module may export `prepare({ cwd, message, base, local })` and return the worker message. Preparation runs on the controlling machine before dispatch; `local` says whether that machine also hosts the worker.
|
|
128
128
|
|
|
129
|
+
Optional profile settings:
|
|
130
|
+
|
|
131
|
+
- `blocking`: `true` forces blocking spawns, `false` forces asynchronous spawns. Omission respects the call's `blocking` value, which defaults to `true`. This does not affect `assign` to existing agents.
|
|
132
|
+
- `share_context`: `false` opts new spawns out of shared notes and history. Omission or `true` follows the controller setting.
|
|
133
|
+
|
|
134
|
+
`help` and `list` expose each profile's description and configured settings. Profile names carry no blocking policy. The bundled reviewer profile sets `"blocking": true`; change it to `false` to force asynchronous review, or remove it to choose per call. Existing installed profiles are never overwritten. An existing reviewer without `blocking` now respects the call like any other profile.
|
|
135
|
+
|
|
129
136
|
## Advanced Herdr control
|
|
130
137
|
|
|
131
138
|
Ordinary delegation stays inside `agents`. For workspace, tab, pane, process, focus, layout or raw-terminal operations, run `herdr --skill` and follow the installed Herdr skill. Shepherdr does not duplicate those controls.
|
package/package.json
CHANGED
package/src/agents-contract.ts
CHANGED
|
@@ -2,6 +2,7 @@ import { StringEnum, Type } from "@earendil-works/pi-ai";
|
|
|
2
2
|
import type { Static } from "typebox";
|
|
3
3
|
import { Check } from "typebox/value";
|
|
4
4
|
import { START_PLACEMENTS } from "./launch.js";
|
|
5
|
+
import { loadAgentProfileBlocking } from "./profiles.js";
|
|
5
6
|
|
|
6
7
|
const ACTIONS = [
|
|
7
8
|
"help",
|
|
@@ -75,11 +76,11 @@ const AgentsRequest = Type.Object(
|
|
|
75
76
|
message: Type.Optional(
|
|
76
77
|
Type.String({ description: "Initial task or follow-up" }),
|
|
77
78
|
),
|
|
78
|
-
base: Type.Optional(Type.String({ description: "
|
|
79
|
+
base: Type.Optional(Type.String({ description: "Review base branch" })),
|
|
79
80
|
blocking: Type.Optional(
|
|
80
81
|
Type.Boolean({
|
|
81
82
|
description:
|
|
82
|
-
"Delegation only;
|
|
83
|
+
"Delegation only; profile policy overrides spawn; otherwise defaults true",
|
|
83
84
|
}),
|
|
84
85
|
),
|
|
85
86
|
query: Type.Optional(Type.String()),
|
|
@@ -158,7 +159,12 @@ export function isBlockingAgentsCall(input: unknown): boolean {
|
|
|
158
159
|
try {
|
|
159
160
|
const value = parseAgentsRequest(input);
|
|
160
161
|
if (value.action === "spawn")
|
|
161
|
-
return shouldBlockAgentSpawn(
|
|
162
|
+
return shouldBlockAgentSpawn(
|
|
163
|
+
loadAgentProfileBlocking(
|
|
164
|
+
requiredAgentField(value.agent_type, "agent_type"),
|
|
165
|
+
),
|
|
166
|
+
value.blocking,
|
|
167
|
+
);
|
|
162
168
|
return BLOCKING_ACTIONS.has(value.action) && value.blocking !== false;
|
|
163
169
|
} catch {
|
|
164
170
|
return false;
|
|
@@ -166,8 +172,8 @@ export function isBlockingAgentsCall(input: unknown): boolean {
|
|
|
166
172
|
}
|
|
167
173
|
|
|
168
174
|
export function shouldBlockAgentSpawn(
|
|
169
|
-
|
|
175
|
+
profileBlocking: boolean | undefined,
|
|
170
176
|
blocking: boolean | undefined,
|
|
171
177
|
): boolean {
|
|
172
|
-
return
|
|
178
|
+
return profileBlocking ?? blocking ?? true;
|
|
173
179
|
}
|
package/src/agents-discovery.ts
CHANGED
|
@@ -1,11 +1,28 @@
|
|
|
1
1
|
import type { AgentsParams, READ_SOURCES } from "./agents-contract.js";
|
|
2
2
|
import type { AgentFleet, ConnectedMachine } from "./fleet.js";
|
|
3
|
-
import { loadAgentProfiles } from "./profiles.js";
|
|
3
|
+
import { type AgentProfile, loadAgentProfiles } from "./profiles.js";
|
|
4
4
|
import type { AgentStatus, PaneInfo, SessionSnapshot } from "./types.js";
|
|
5
5
|
|
|
6
6
|
const MAX_LIST_ITEMS = 30;
|
|
7
7
|
const MAX_TERMINAL_READ_CHARS = 36_000;
|
|
8
8
|
|
|
9
|
+
function describeProfiles(profiles: Map<string, AgentProfile>) {
|
|
10
|
+
return Object.fromEntries(
|
|
11
|
+
[...profiles].map(([name, profile]) => [
|
|
12
|
+
name,
|
|
13
|
+
{
|
|
14
|
+
description: profile.description,
|
|
15
|
+
...(profile.blocking === undefined
|
|
16
|
+
? {}
|
|
17
|
+
: { blocking: profile.blocking }),
|
|
18
|
+
...(profile.shareContext === undefined
|
|
19
|
+
? {}
|
|
20
|
+
: { share_context: profile.shareContext }),
|
|
21
|
+
},
|
|
22
|
+
]),
|
|
23
|
+
);
|
|
24
|
+
}
|
|
25
|
+
|
|
9
26
|
export async function agentsHelp(): Promise<Record<string, unknown>> {
|
|
10
27
|
const profiles = await loadAgentProfiles();
|
|
11
28
|
return {
|
|
@@ -32,7 +49,9 @@ export async function agentsHelp(): Promise<Record<string, unknown>> {
|
|
|
32
49
|
send: "Peer questions, updates, replies; submission only, no wait or watch",
|
|
33
50
|
assign: "Delegate a task to an existing agent",
|
|
34
51
|
blocking:
|
|
35
|
-
"spawn/assign default true; false pushes task settlement; never poll
|
|
52
|
+
"spawn/assign default true; profile blocking overrides spawn; false pushes task settlement; never poll",
|
|
53
|
+
share_context:
|
|
54
|
+
"Profile false isolates notes/history; otherwise follows controller sharing setting",
|
|
36
55
|
watch:
|
|
37
56
|
"Explicit watch persists until unwatch; automatic task watches end on finish/failure, not blockage",
|
|
38
57
|
prompt:
|
|
@@ -47,9 +66,7 @@ export async function agentsHelp(): Promise<Record<string, unknown>> {
|
|
|
47
66
|
}
|
|
48
67
|
: {}),
|
|
49
68
|
},
|
|
50
|
-
profiles:
|
|
51
|
-
[...profiles].map(([name, profile]) => [name, profile.description]),
|
|
52
|
-
),
|
|
69
|
+
profiles: describeProfiles(profiles),
|
|
53
70
|
advanced: "herdr --skill: workspace/tab/pane/process/focus/layout/terminal",
|
|
54
71
|
};
|
|
55
72
|
}
|
|
@@ -137,9 +154,7 @@ export async function listFleetAgents(
|
|
|
137
154
|
})),
|
|
138
155
|
);
|
|
139
156
|
return {
|
|
140
|
-
profiles:
|
|
141
|
-
[...profiles].map(([name, profile]) => [name, profile.description]),
|
|
142
|
-
),
|
|
157
|
+
profiles: describeProfiles(profiles),
|
|
143
158
|
machines: machines.map(
|
|
144
159
|
({
|
|
145
160
|
snapshot: _snapshot,
|
package/src/agents-spawn.ts
CHANGED
|
@@ -107,7 +107,10 @@ export async function spawnAgent(
|
|
|
107
107
|
status: "starting",
|
|
108
108
|
});
|
|
109
109
|
const agentArgs = profileAgentArgs(profile, { targetLocal: runtime.local });
|
|
110
|
-
const sharing =
|
|
110
|
+
const sharing =
|
|
111
|
+
profile.shareContext === false
|
|
112
|
+
? undefined
|
|
113
|
+
: await sharedContext.prepare(ctx, runtime, name, agentArgs);
|
|
111
114
|
const started = await startAgent(
|
|
112
115
|
runtime.client,
|
|
113
116
|
startParams,
|
|
@@ -119,7 +122,7 @@ export async function spawnAgent(
|
|
|
119
122
|
let promptAccepted = false;
|
|
120
123
|
let dispatch;
|
|
121
124
|
let shared: { agentName?: string; warning?: string } | undefined;
|
|
122
|
-
const blocking = shouldBlockAgentSpawn(profile.
|
|
125
|
+
const blocking = shouldBlockAgentSpawn(profile.blocking, params.blocking);
|
|
123
126
|
try {
|
|
124
127
|
shared = await sharing?.accept(started.agent);
|
|
125
128
|
dispatch = await dispatchAgentWork(
|
package/src/profiles.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { readFileSync } from "node:fs";
|
|
1
2
|
import {
|
|
2
3
|
cp,
|
|
3
4
|
mkdir,
|
|
@@ -25,6 +26,7 @@ const BUNDLED_PROFILES_DIRECTORY = fileURLToPath(
|
|
|
25
26
|
|
|
26
27
|
export interface AgentProfile {
|
|
27
28
|
accepts: string[];
|
|
29
|
+
blocking?: boolean;
|
|
28
30
|
description: string;
|
|
29
31
|
model: string;
|
|
30
32
|
name: string;
|
|
@@ -32,6 +34,7 @@ export interface AgentProfile {
|
|
|
32
34
|
prepare?: string;
|
|
33
35
|
prompt?: string;
|
|
34
36
|
promptPath?: string;
|
|
37
|
+
shareContext?: boolean;
|
|
35
38
|
thinking: string;
|
|
36
39
|
}
|
|
37
40
|
|
|
@@ -45,11 +48,13 @@ type ProfilePreparationContext = ProfilePreparationInput & { local: boolean };
|
|
|
45
48
|
|
|
46
49
|
interface ProfileFile {
|
|
47
50
|
accepts?: unknown;
|
|
51
|
+
blocking?: unknown;
|
|
48
52
|
description?: unknown;
|
|
49
53
|
model?: unknown;
|
|
50
54
|
pi_args?: unknown;
|
|
51
55
|
prepare?: unknown;
|
|
52
56
|
prompt?: unknown;
|
|
57
|
+
share_context?: unknown;
|
|
53
58
|
thinking?: unknown;
|
|
54
59
|
}
|
|
55
60
|
|
|
@@ -71,14 +76,17 @@ function optionalString(value: unknown, field: string): string | undefined {
|
|
|
71
76
|
return value.trim();
|
|
72
77
|
}
|
|
73
78
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
79
|
+
function optionalBoolean(value: unknown, field: string): boolean | undefined {
|
|
80
|
+
if (value === undefined) return undefined;
|
|
81
|
+
if (typeof value !== "boolean") throw new Error(`${field} must be a boolean`);
|
|
82
|
+
return value;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
function readProfileFile(name: string, directory: string): ProfileFile {
|
|
78
86
|
const path = join(directory, "profile.json");
|
|
79
87
|
let parsed: ProfileFile;
|
|
80
88
|
try {
|
|
81
|
-
parsed = JSON.parse(
|
|
89
|
+
parsed = JSON.parse(readFileSync(path, "utf8")) as ProfileFile;
|
|
82
90
|
} catch (error) {
|
|
83
91
|
throw new Error(
|
|
84
92
|
`invalid ${name} profile: ${error instanceof Error ? error.message : String(error)}`,
|
|
@@ -89,17 +97,40 @@ async function readProfile(
|
|
|
89
97
|
}
|
|
90
98
|
const allowed = new Set([
|
|
91
99
|
"accepts",
|
|
100
|
+
"blocking",
|
|
92
101
|
"description",
|
|
93
102
|
"model",
|
|
94
103
|
"pi_args",
|
|
95
104
|
"prepare",
|
|
96
105
|
"prompt",
|
|
106
|
+
"share_context",
|
|
97
107
|
"thinking",
|
|
98
108
|
]);
|
|
99
109
|
const unknown = Object.keys(parsed).filter((key) => !allowed.has(key));
|
|
100
110
|
if (unknown.length > 0) {
|
|
101
111
|
throw new Error(`unknown ${name} profile field(s): ${unknown.join(", ")}`);
|
|
102
112
|
}
|
|
113
|
+
return parsed;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
// Code/Notebook wait classification is synchronous; read live policy, not a cache.
|
|
117
|
+
export function loadAgentProfileBlocking(name: string): boolean | undefined {
|
|
118
|
+
if (!PROFILE_NAME.test(name))
|
|
119
|
+
throw new Error(`invalid agent profile: ${name}`);
|
|
120
|
+
const parsed = readProfileFile(name, join(PROFILES_DIRECTORY, name));
|
|
121
|
+
return optionalBoolean(parsed.blocking, `${name}.blocking`);
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
async function readProfile(
|
|
125
|
+
name: string,
|
|
126
|
+
directory: string,
|
|
127
|
+
): Promise<AgentProfile> {
|
|
128
|
+
const parsed = readProfileFile(name, directory);
|
|
129
|
+
const blocking = optionalBoolean(parsed.blocking, `${name}.blocking`);
|
|
130
|
+
const shareContext = optionalBoolean(
|
|
131
|
+
parsed.share_context,
|
|
132
|
+
`${name}.share_context`,
|
|
133
|
+
);
|
|
103
134
|
const description = optionalString(parsed.description, `${name}.description`);
|
|
104
135
|
if (!description) throw new Error(`${name}.description is required`);
|
|
105
136
|
const model = optionalString(parsed.model, `${name}.model`);
|
|
@@ -123,6 +154,8 @@ async function readProfile(
|
|
|
123
154
|
description,
|
|
124
155
|
model,
|
|
125
156
|
thinking,
|
|
157
|
+
...(blocking === undefined ? {} : { blocking }),
|
|
158
|
+
...(shareContext === undefined ? {} : { shareContext }),
|
|
126
159
|
accepts: parsed.accepts
|
|
127
160
|
? stringArray(parsed.accepts, `${name}.accepts`)
|
|
128
161
|
: [],
|