@howaboua/pi-shepherdr 0.2.13 → 0.2.14
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 +10 -0
- package/README.md +11 -5
- package/package.json +6 -6
- package/src/agents-answer.ts +22 -0
- package/src/agents-discovery.ts +2 -2
- package/src/agents-tool.ts +2 -1
- package/src/ask-answer.ts +32 -18
- package/src/board/awareness.ts +115 -0
- package/src/board/host.ts +46 -6
- package/src/board/tool.ts +0 -3
- package/src/context-briefing.ts +226 -0
- package/src/controller.ts +81 -14
- package/src/delivery.ts +33 -0
- package/src/messages.ts +86 -15
- package/src/monitor-questions.ts +249 -0
- package/src/monitor-record.ts +6 -0
- package/src/monitor-state.ts +10 -4
- package/src/monitor.ts +40 -2
- package/src/remote/shepherdr-session-watch.mjs +72 -0
- package/src/remote/shepherdr-session.mjs +32 -2
- package/src/remote/shepherdr.mjs +21 -1
- package/src/remote-client.ts +66 -24
- package/src/session-reader.ts +49 -3
- package/src/types.ts +2 -0
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
import { randomUUID } from "node:crypto";
|
|
2
|
+
import {
|
|
3
|
+
buildSessionContext,
|
|
4
|
+
type ExtensionAPI,
|
|
5
|
+
type ExtensionContext,
|
|
6
|
+
} from "@earendil-works/pi-coding-agent";
|
|
7
|
+
import type {
|
|
8
|
+
CODEX_CONTEXT_BRIEFING_TYPE,
|
|
9
|
+
CodexContextBriefing,
|
|
10
|
+
CodexContextBriefingHandler,
|
|
11
|
+
} from "@howaboua/pi-codex-conversion/developer-messages";
|
|
12
|
+
import { registerInferenceBriefing } from "./delivery.js";
|
|
13
|
+
|
|
14
|
+
// Conversion projects this durable protocol in inference, compaction and native replay.
|
|
15
|
+
const BRIEFING: typeof CODEX_CONTEXT_BRIEFING_TYPE = "codex-context-briefing";
|
|
16
|
+
|
|
17
|
+
export function registerContextBriefing(
|
|
18
|
+
pi: ExtensionAPI,
|
|
19
|
+
name: string,
|
|
20
|
+
relevant: (ctx: ExtensionContext) => boolean,
|
|
21
|
+
record: CodexContextBriefingHandler,
|
|
22
|
+
) {
|
|
23
|
+
const hosted = registerInferenceBriefing(pi, record);
|
|
24
|
+
const warned = new Set<string>();
|
|
25
|
+
pi.on("context_with_system", async (event, ctx) => {
|
|
26
|
+
if (hosted.hosted()) return;
|
|
27
|
+
if (
|
|
28
|
+
hosted.outdated &&
|
|
29
|
+
relevant(ctx) &&
|
|
30
|
+
!warned.has(ctx.sessionManager.getSessionId())
|
|
31
|
+
) {
|
|
32
|
+
warned.add(ctx.sessionManager.getSessionId());
|
|
33
|
+
ctx.ui.notify(
|
|
34
|
+
`Update Codex Conversion and reload to preserve ${name} briefings through its context rollover and native replay. Native Pi briefings and other agent tools remain available.`,
|
|
35
|
+
"warning",
|
|
36
|
+
);
|
|
37
|
+
}
|
|
38
|
+
try {
|
|
39
|
+
await record(ctx, undefined, event.messages);
|
|
40
|
+
return { messages: projectNative(ctx, event.messages) };
|
|
41
|
+
} catch (error) {
|
|
42
|
+
ctx.abort();
|
|
43
|
+
throw error;
|
|
44
|
+
}
|
|
45
|
+
});
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
export function contextBriefingWindow(
|
|
49
|
+
ctx: ExtensionContext,
|
|
50
|
+
windowId?: string,
|
|
51
|
+
) {
|
|
52
|
+
const branch = ctx.sessionManager.getBranch();
|
|
53
|
+
const compaction = branch.findLastIndex(
|
|
54
|
+
(entry) =>
|
|
55
|
+
entry.type === "compaction" &&
|
|
56
|
+
!(
|
|
57
|
+
entry.details &&
|
|
58
|
+
typeof entry.details === "object" &&
|
|
59
|
+
"strategy" in entry.details &&
|
|
60
|
+
entry.details.strategy === "codex-context-window"
|
|
61
|
+
),
|
|
62
|
+
);
|
|
63
|
+
const boundary = branch.findLastIndex(
|
|
64
|
+
(entry) =>
|
|
65
|
+
entry.type === "custom_message" &&
|
|
66
|
+
entry.customType === "codex-context-window" &&
|
|
67
|
+
entry.details &&
|
|
68
|
+
typeof entry.details === "object" &&
|
|
69
|
+
"contextManagement" in entry.details &&
|
|
70
|
+
entry.details.contextManagement &&
|
|
71
|
+
typeof entry.details.contextManagement === "object" &&
|
|
72
|
+
"kind" in entry.details.contextManagement &&
|
|
73
|
+
entry.details.contextManagement.kind === "window",
|
|
74
|
+
);
|
|
75
|
+
return compaction > boundary
|
|
76
|
+
? branch[compaction]!.id
|
|
77
|
+
: (windowId ?? ctx.sessionManager.getSessionId());
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
export function hasContextRollover(ctx: ExtensionContext): boolean {
|
|
81
|
+
return ctx.sessionManager.getBranch().some((entry) => {
|
|
82
|
+
if (entry.type === "compaction") return true;
|
|
83
|
+
if (
|
|
84
|
+
entry.type !== "custom_message" ||
|
|
85
|
+
entry.customType !== "codex-context-window" ||
|
|
86
|
+
!entry.details ||
|
|
87
|
+
typeof entry.details !== "object" ||
|
|
88
|
+
!("contextManagement" in entry.details)
|
|
89
|
+
)
|
|
90
|
+
return false;
|
|
91
|
+
const window = entry.details.contextManagement;
|
|
92
|
+
return Boolean(
|
|
93
|
+
window &&
|
|
94
|
+
typeof window === "object" &&
|
|
95
|
+
"kind" in window &&
|
|
96
|
+
window.kind === "window" &&
|
|
97
|
+
"windowNumber" in window &&
|
|
98
|
+
typeof window.windowNumber === "number" &&
|
|
99
|
+
window.windowNumber > 0,
|
|
100
|
+
);
|
|
101
|
+
});
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
export async function recordContextBriefing(
|
|
105
|
+
pi: ExtensionAPI,
|
|
106
|
+
ctx: ExtensionContext,
|
|
107
|
+
owner: string,
|
|
108
|
+
key: string,
|
|
109
|
+
content: () => Promise<string | undefined>,
|
|
110
|
+
) {
|
|
111
|
+
const saved = ctx.sessionManager
|
|
112
|
+
.getEntries()
|
|
113
|
+
.findLast(
|
|
114
|
+
(entry) =>
|
|
115
|
+
entry.type === "custom" &&
|
|
116
|
+
entry.customType === BRIEFING &&
|
|
117
|
+
readBriefing(entry.data).owner === owner &&
|
|
118
|
+
readBriefing(entry.data).key === key,
|
|
119
|
+
);
|
|
120
|
+
if (saved?.type === "custom") {
|
|
121
|
+
// Tree may select an ancestor before its metadata child. Reuse immutable bytes/ID.
|
|
122
|
+
if (
|
|
123
|
+
!ctx.sessionManager
|
|
124
|
+
.getBranch()
|
|
125
|
+
.some(
|
|
126
|
+
(entry) =>
|
|
127
|
+
entry.type === "custom" &&
|
|
128
|
+
entry.customType === BRIEFING &&
|
|
129
|
+
readBriefing(entry.data).owner === owner &&
|
|
130
|
+
readBriefing(entry.data).key === key,
|
|
131
|
+
)
|
|
132
|
+
)
|
|
133
|
+
pi.appendEntry(BRIEFING, readBriefing(saved.data));
|
|
134
|
+
return;
|
|
135
|
+
}
|
|
136
|
+
const value = await content();
|
|
137
|
+
if (value === undefined) return;
|
|
138
|
+
pi.appendEntry(BRIEFING, {
|
|
139
|
+
protocol: 1,
|
|
140
|
+
id: randomUUID(),
|
|
141
|
+
owner,
|
|
142
|
+
key,
|
|
143
|
+
content: value,
|
|
144
|
+
} satisfies CodexContextBriefing);
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
function projectNative(
|
|
148
|
+
ctx: ExtensionContext,
|
|
149
|
+
messages: NativeMessage[],
|
|
150
|
+
): NativeMessage[] {
|
|
151
|
+
const entries = ctx.sessionManager.getBranch().map((entry) => {
|
|
152
|
+
if (entry.type !== "custom" || entry.customType !== BRIEFING) return entry;
|
|
153
|
+
const briefing = readBriefing(entry.data);
|
|
154
|
+
return {
|
|
155
|
+
...entry,
|
|
156
|
+
type: "custom_message" as const,
|
|
157
|
+
content: briefing.content,
|
|
158
|
+
display: false,
|
|
159
|
+
details: briefing,
|
|
160
|
+
};
|
|
161
|
+
});
|
|
162
|
+
const reconstructed = buildSessionContext(entries).messages;
|
|
163
|
+
const positions = new Map<string, number[]>();
|
|
164
|
+
messages.forEach((message, index) => {
|
|
165
|
+
const key = messageKey(message);
|
|
166
|
+
const indices = positions.get(key) ?? [];
|
|
167
|
+
indices.push(index);
|
|
168
|
+
positions.set(key, indices);
|
|
169
|
+
});
|
|
170
|
+
const insertions = new Map<number, NativeMessage[]>();
|
|
171
|
+
let pending: NativeMessage[] = [];
|
|
172
|
+
let last = messages[0]?.role === "system" ? 0 : -1;
|
|
173
|
+
const insert = (index: number) => {
|
|
174
|
+
if (!pending.length) return;
|
|
175
|
+
const position =
|
|
176
|
+
messages[0]?.role === "system" ? Math.max(1, index) : index;
|
|
177
|
+
insertions.set(position, [...(insertions.get(position) ?? []), ...pending]);
|
|
178
|
+
pending = [];
|
|
179
|
+
};
|
|
180
|
+
for (const message of reconstructed) {
|
|
181
|
+
const index = positions.get(messageKey(message))?.shift();
|
|
182
|
+
if (index !== undefined) {
|
|
183
|
+
insert(index);
|
|
184
|
+
last = index;
|
|
185
|
+
} else if (message.role === "custom" && message.customType === BRIEFING) {
|
|
186
|
+
pending.push(message);
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
insert(last + 1);
|
|
190
|
+
return messages
|
|
191
|
+
.flatMap((message, index) => [...(insertions.get(index) ?? []), message])
|
|
192
|
+
.concat(insertions.get(messages.length) ?? []);
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
type NativeMessage = ReturnType<typeof buildSessionContext>["messages"][number];
|
|
196
|
+
function messageKey(message: NativeMessage) {
|
|
197
|
+
return JSON.stringify([
|
|
198
|
+
message.role,
|
|
199
|
+
message.timestamp,
|
|
200
|
+
message.role === "custom"
|
|
201
|
+
? message.customType === BRIEFING
|
|
202
|
+
? readBriefing(message.details).id
|
|
203
|
+
: message.customType
|
|
204
|
+
: message.role === "toolResult"
|
|
205
|
+
? message.toolCallId
|
|
206
|
+
: undefined,
|
|
207
|
+
]);
|
|
208
|
+
}
|
|
209
|
+
function readBriefing(value: unknown): CodexContextBriefing {
|
|
210
|
+
if (
|
|
211
|
+
!value ||
|
|
212
|
+
typeof value !== "object" ||
|
|
213
|
+
!("protocol" in value) ||
|
|
214
|
+
value.protocol !== 1 ||
|
|
215
|
+
!("id" in value) ||
|
|
216
|
+
typeof value.id !== "string" ||
|
|
217
|
+
!("owner" in value) ||
|
|
218
|
+
typeof value.owner !== "string" ||
|
|
219
|
+
!("key" in value) ||
|
|
220
|
+
typeof value.key !== "string" ||
|
|
221
|
+
!("content" in value) ||
|
|
222
|
+
typeof value.content !== "string"
|
|
223
|
+
)
|
|
224
|
+
throw new Error("Invalid saved context briefing");
|
|
225
|
+
return value as CodexContextBriefing;
|
|
226
|
+
}
|
package/src/controller.ts
CHANGED
|
@@ -3,17 +3,19 @@ import type {
|
|
|
3
3
|
ExtensionContext,
|
|
4
4
|
} from "@earendil-works/pi-coding-agent";
|
|
5
5
|
import type { AgentBoard } from "./board/host.js";
|
|
6
|
+
import {
|
|
7
|
+
contextBriefingWindow,
|
|
8
|
+
hasContextRollover,
|
|
9
|
+
recordContextBriefing,
|
|
10
|
+
registerContextBriefing,
|
|
11
|
+
} from "./context-briefing.js";
|
|
6
12
|
import { controlPanelStatus, openControlPanel } from "./control-panel.js";
|
|
7
13
|
import { sendPolicyMessage } from "./delivery.js";
|
|
8
14
|
import type { AgentFleet } from "./fleet.js";
|
|
15
|
+
import { activeAgentsBriefing, orchestrationGuidance } from "./messages.js";
|
|
9
16
|
import { loadAgentProfiles } from "./profiles.js";
|
|
10
17
|
|
|
11
18
|
const ORCHESTRATION_STATE_TYPE = "pi-shepherdr-orchestration-state";
|
|
12
|
-
const GENERAL_ORCHESTRATION_MESSAGE =
|
|
13
|
-
"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.";
|
|
14
|
-
const ORCHESTRATION_MESSAGE =
|
|
15
|
-
"Your main goal from now on is to orchestrate agents. Fan out suitable work, synthesize agent results, and report the outcome. Work directly only when asked or for routine local tasks.";
|
|
16
|
-
const NORMAL_MESSAGE = "Work normally. Delegate only when useful or requested.";
|
|
17
19
|
|
|
18
20
|
export function registerAgentController(
|
|
19
21
|
pi: ExtensionAPI,
|
|
@@ -33,7 +35,7 @@ export function registerAgentController(
|
|
|
33
35
|
signal: AbortSignal,
|
|
34
36
|
) => {
|
|
35
37
|
const sessionId = ctx.sessionManager.getSessionId();
|
|
36
|
-
const content =
|
|
38
|
+
const content = await orchestrationMessage(enabled);
|
|
37
39
|
signal.throwIfAborted();
|
|
38
40
|
if (ctx.sessionManager.getSessionId() !== sessionId)
|
|
39
41
|
throw new Error("Session changed; retry /herdr");
|
|
@@ -64,6 +66,64 @@ export function registerAgentController(
|
|
|
64
66
|
signal.throwIfAborted();
|
|
65
67
|
return fleet.connect(machine);
|
|
66
68
|
};
|
|
69
|
+
registerContextBriefing(
|
|
70
|
+
pi,
|
|
71
|
+
"orchestration",
|
|
72
|
+
(ctx) => restoreOrchestrationState(ctx).enabled,
|
|
73
|
+
async (ctx, windowId, messages) => {
|
|
74
|
+
const sessionId = ctx.sessionManager.getSessionId();
|
|
75
|
+
const state = restoreOrchestrationState(ctx);
|
|
76
|
+
const window = contextBriefingWindow(ctx, windowId);
|
|
77
|
+
// Initialization and compaction may keep earlier messages. Only actual
|
|
78
|
+
// selected context proves a toggle still supplies this window's guidance.
|
|
79
|
+
if (
|
|
80
|
+
state.visible &&
|
|
81
|
+
messages?.some(
|
|
82
|
+
(message) =>
|
|
83
|
+
message.role === "custom" &&
|
|
84
|
+
message.customType === ORCHESTRATION_STATE_TYPE &&
|
|
85
|
+
message.timestamp === state.timestamp,
|
|
86
|
+
)
|
|
87
|
+
)
|
|
88
|
+
return;
|
|
89
|
+
const key = JSON.stringify([sessionId, window, state.id]);
|
|
90
|
+
await recordContextBriefing(
|
|
91
|
+
pi,
|
|
92
|
+
ctx,
|
|
93
|
+
"shepherdr-orchestration",
|
|
94
|
+
key,
|
|
95
|
+
async () => {
|
|
96
|
+
const content = await orchestrationMessage(state.enabled);
|
|
97
|
+
if (
|
|
98
|
+
ctx.sessionManager.getSessionId() !== sessionId ||
|
|
99
|
+
restoreOrchestrationState(ctx).id !== state.id
|
|
100
|
+
)
|
|
101
|
+
throw new Error("Orchestration changed during its briefing");
|
|
102
|
+
ctx.signal?.throwIfAborted();
|
|
103
|
+
return content;
|
|
104
|
+
},
|
|
105
|
+
);
|
|
106
|
+
},
|
|
107
|
+
);
|
|
108
|
+
registerContextBriefing(
|
|
109
|
+
pi,
|
|
110
|
+
"active agents",
|
|
111
|
+
() => fleet.list().some((agent) => agent.activity.phase !== "settled"),
|
|
112
|
+
async (ctx, windowId) => {
|
|
113
|
+
if (!hasContextRollover(ctx)) return;
|
|
114
|
+
const key = JSON.stringify([
|
|
115
|
+
ctx.sessionManager.getSessionId(),
|
|
116
|
+
contextBriefingWindow(ctx, windowId),
|
|
117
|
+
]);
|
|
118
|
+
await recordContextBriefing(
|
|
119
|
+
pi,
|
|
120
|
+
ctx,
|
|
121
|
+
"shepherdr-active-agents",
|
|
122
|
+
key,
|
|
123
|
+
async () => activeAgentsBriefing(fleet.list(), fleet.statuses()),
|
|
124
|
+
);
|
|
125
|
+
},
|
|
126
|
+
);
|
|
67
127
|
pi.registerCommand("herdr", {
|
|
68
128
|
description: "Shepherdr settings, status and SSH setup",
|
|
69
129
|
handler: async (args, ctx) => {
|
|
@@ -86,7 +146,7 @@ export function registerAgentController(
|
|
|
86
146
|
reconnect(ctx, machine, signal),
|
|
87
147
|
signal: commandSignal,
|
|
88
148
|
};
|
|
89
|
-
orchestrationEnabled = restoreOrchestrationState(ctx);
|
|
149
|
+
orchestrationEnabled = restoreOrchestrationState(ctx).enabled;
|
|
90
150
|
try {
|
|
91
151
|
if (ctx.mode === "tui") {
|
|
92
152
|
const panel = openControlPanel(ctx, options);
|
|
@@ -105,7 +165,7 @@ export function registerAgentController(
|
|
|
105
165
|
|
|
106
166
|
pi.on("session_start", async (_event, ctx) => {
|
|
107
167
|
resetLifetime();
|
|
108
|
-
orchestrationEnabled = restoreOrchestrationState(ctx);
|
|
168
|
+
orchestrationEnabled = restoreOrchestrationState(ctx).enabled;
|
|
109
169
|
await activateController(fleet, ctx);
|
|
110
170
|
});
|
|
111
171
|
|
|
@@ -116,14 +176,18 @@ export function registerAgentController(
|
|
|
116
176
|
});
|
|
117
177
|
}
|
|
118
178
|
|
|
119
|
-
async function orchestrationMessage(): Promise<string> {
|
|
120
|
-
return (
|
|
121
|
-
|
|
122
|
-
|
|
179
|
+
async function orchestrationMessage(enabled: boolean): Promise<string> {
|
|
180
|
+
return orchestrationGuidance(
|
|
181
|
+
enabled,
|
|
182
|
+
enabled && (await loadAgentProfiles()).has("general"),
|
|
183
|
+
);
|
|
123
184
|
}
|
|
124
185
|
|
|
125
|
-
function restoreOrchestrationState(ctx: ExtensionContext)
|
|
186
|
+
function restoreOrchestrationState(ctx: ExtensionContext) {
|
|
126
187
|
let enabled = false;
|
|
188
|
+
let timestamp: number | undefined;
|
|
189
|
+
let id = "normal";
|
|
190
|
+
let visible = false;
|
|
127
191
|
for (const entry of ctx.sessionManager.getBranch()) {
|
|
128
192
|
if (
|
|
129
193
|
(entry.type !== "custom" && entry.type !== "custom_message") ||
|
|
@@ -139,9 +203,12 @@ function restoreOrchestrationState(ctx: ExtensionContext): boolean {
|
|
|
139
203
|
typeof state.enabled === "boolean"
|
|
140
204
|
) {
|
|
141
205
|
enabled = state.enabled;
|
|
206
|
+
timestamp = Date.parse(entry.timestamp);
|
|
207
|
+
id = entry.id;
|
|
208
|
+
visible = entry.type === "custom_message";
|
|
142
209
|
}
|
|
143
210
|
}
|
|
144
|
-
return enabled;
|
|
211
|
+
return { enabled, timestamp, id, visible };
|
|
145
212
|
}
|
|
146
213
|
|
|
147
214
|
async function activateController(
|
package/src/delivery.ts
CHANGED
|
@@ -3,8 +3,11 @@ import type {
|
|
|
3
3
|
ExtensionContext,
|
|
4
4
|
} from "@earendil-works/pi-coding-agent";
|
|
5
5
|
import type {
|
|
6
|
+
CodexContextBriefingHandler,
|
|
6
7
|
CodexDeveloperCustomMessage,
|
|
7
8
|
CodexDeveloperMessageOptions,
|
|
9
|
+
hasCodexContextBriefingHost,
|
|
10
|
+
registerCodexContextBriefing,
|
|
8
11
|
trySendCodexDeveloperCustomMessage,
|
|
9
12
|
tryStartCodexPreparedIdleKickoff,
|
|
10
13
|
tryStartCodexPreparedIdlePrompt,
|
|
@@ -26,6 +29,14 @@ const preparedPrompts = new WeakMap<
|
|
|
26
29
|
ExtensionAPI,
|
|
27
30
|
typeof tryStartCodexPreparedIdlePrompt
|
|
28
31
|
>();
|
|
32
|
+
const briefingHosts = new WeakMap<
|
|
33
|
+
ExtensionAPI,
|
|
34
|
+
{
|
|
35
|
+
register: typeof registerCodexContextBriefing;
|
|
36
|
+
available: typeof hasCodexContextBriefingHost;
|
|
37
|
+
}
|
|
38
|
+
>();
|
|
39
|
+
const outdatedBriefingHosts = new WeakSet<ExtensionAPI>();
|
|
29
40
|
const PACKAGE = "@howaboua/pi-codex-conversion";
|
|
30
41
|
const MODULE = `${PACKAGE}/developer-messages`;
|
|
31
42
|
|
|
@@ -42,6 +53,15 @@ export async function registerDeveloperDelivery(
|
|
|
42
53
|
preparedKickoffs.set(pi, api.tryStartCodexPreparedIdleKickoff);
|
|
43
54
|
if (typeof api.tryStartCodexPreparedIdlePrompt === "function")
|
|
44
55
|
preparedPrompts.set(pi, api.tryStartCodexPreparedIdlePrompt);
|
|
56
|
+
if (
|
|
57
|
+
typeof api.registerCodexContextBriefing === "function" &&
|
|
58
|
+
typeof api.hasCodexContextBriefingHost === "function"
|
|
59
|
+
)
|
|
60
|
+
briefingHosts.set(pi, {
|
|
61
|
+
register: api.registerCodexContextBriefing,
|
|
62
|
+
available: api.hasCodexContextBriefingHost,
|
|
63
|
+
});
|
|
64
|
+
else outdatedBriefingHosts.add(pi);
|
|
45
65
|
} catch (error) {
|
|
46
66
|
if (!isUnavailable(error)) throw error;
|
|
47
67
|
}
|
|
@@ -89,6 +109,19 @@ export async function registerDeveloperDelivery(
|
|
|
89
109
|
});
|
|
90
110
|
}
|
|
91
111
|
|
|
112
|
+
export function registerInferenceBriefing(
|
|
113
|
+
pi: ExtensionAPI,
|
|
114
|
+
handler: CodexContextBriefingHandler,
|
|
115
|
+
) {
|
|
116
|
+
const host = briefingHosts.get(pi);
|
|
117
|
+
const unregister = host?.register(pi, handler);
|
|
118
|
+
pi.on("session_shutdown", () => unregister?.());
|
|
119
|
+
return {
|
|
120
|
+
hosted: () => host?.available(pi) ?? false,
|
|
121
|
+
outdated: outdatedBriefingHosts.has(pi),
|
|
122
|
+
};
|
|
123
|
+
}
|
|
124
|
+
|
|
92
125
|
export function startPreparedIdleTurn(
|
|
93
126
|
pi: ExtensionAPI,
|
|
94
127
|
ctx: Pick<ExtensionContext, "ui" | "sessionManager">,
|
package/src/messages.ts
CHANGED
|
@@ -12,10 +12,12 @@ import { getCurrentPane, getSnapshot } from "./herdr.js";
|
|
|
12
12
|
import type { HerdrConnection } from "./herdr-client.js";
|
|
13
13
|
import type {
|
|
14
14
|
LatestAssistant,
|
|
15
|
+
MachineStatus,
|
|
15
16
|
MonitoredAgent,
|
|
16
17
|
PaneInfo,
|
|
17
18
|
PeerMessage,
|
|
18
19
|
PendingAsk,
|
|
20
|
+
ScopedMonitoredAgent,
|
|
19
21
|
SettledAgentStatus,
|
|
20
22
|
} from "./types.js";
|
|
21
23
|
|
|
@@ -25,6 +27,52 @@ const REALTIME_VOICE_PROMPT_CHANNEL =
|
|
|
25
27
|
const MAX_REALTIME_VOICE_PROMPT_BYTES = 8 * 1_024;
|
|
26
28
|
const DELEGATED_WORKER_GUIDANCE =
|
|
27
29
|
"If blocked mid-run, use a question-asking tool, not peer messages. Without one, end with the blocker. Finish with an assistant reply, not a separate send report; never watch your parent.";
|
|
30
|
+
export function orchestrationGuidance(enabled: boolean, general: boolean) {
|
|
31
|
+
if (!enabled) return "Work normally. Delegate only when useful or requested.";
|
|
32
|
+
return general
|
|
33
|
+
? "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."
|
|
34
|
+
: "Your main goal from now on is to orchestrate agents. Fan out suitable work, synthesize agent results, and report the outcome. Work directly only when asked or for routine local tasks.";
|
|
35
|
+
}
|
|
36
|
+
export function activeAgentsBriefing(
|
|
37
|
+
agents: ScopedMonitoredAgent[],
|
|
38
|
+
machines: MachineStatus[],
|
|
39
|
+
): string | undefined {
|
|
40
|
+
const active = agents.filter((agent) => agent.activity.phase !== "settled");
|
|
41
|
+
if (!active.length) return;
|
|
42
|
+
return [
|
|
43
|
+
"Existing agents after context rollover. Do not duplicate their work. Status is last observed; use these machine/target values for updates.",
|
|
44
|
+
JSON.stringify(
|
|
45
|
+
active.map((agent) => ({
|
|
46
|
+
machine: agent.machine,
|
|
47
|
+
target: agent.paneId,
|
|
48
|
+
...(agent.name ? { name: agent.name } : {}),
|
|
49
|
+
status: agent.activity.phase,
|
|
50
|
+
connection:
|
|
51
|
+
machines.find((machine) => machine.id === agent.machine)?.status ??
|
|
52
|
+
"unavailable",
|
|
53
|
+
...(agent.cwd ? { cwd: agent.cwd } : {}),
|
|
54
|
+
...(activityTask(agent.activity)
|
|
55
|
+
? { task: activityTask(agent.activity) }
|
|
56
|
+
: {}),
|
|
57
|
+
})),
|
|
58
|
+
),
|
|
59
|
+
].join("\n");
|
|
60
|
+
}
|
|
61
|
+
export function boardBriefing(
|
|
62
|
+
member: boolean,
|
|
63
|
+
population: "empty" | "populated" | "unavailable",
|
|
64
|
+
) {
|
|
65
|
+
const state =
|
|
66
|
+
population === "populated"
|
|
67
|
+
? "Your shared board has posts. Read relevant threads and contribute useful plans, decisions and findings."
|
|
68
|
+
: population === "empty"
|
|
69
|
+
? "Shared board available; no posts yet."
|
|
70
|
+
: "Shared board status unavailable. Check board help and retry reading when available.";
|
|
71
|
+
const setup = member
|
|
72
|
+
? "The root agent owns setup; follow your assigned task."
|
|
73
|
+
: "You own setup. Before delegating, consider posting shared context if useful.";
|
|
74
|
+
return `${state} ${setup} Use agents for assignments and urgent messages.`;
|
|
75
|
+
}
|
|
28
76
|
|
|
29
77
|
export function attachmentMessage(
|
|
30
78
|
controllerContextAgent?: string,
|
|
@@ -141,12 +189,13 @@ interface AgentEventOptions {
|
|
|
141
189
|
operatorPrefix: string;
|
|
142
190
|
record: MonitoredAgent;
|
|
143
191
|
reply?: LatestAssistant;
|
|
144
|
-
status: SettledAgentStatus;
|
|
192
|
+
status: SettledAgentStatus | "question";
|
|
145
193
|
}
|
|
146
194
|
|
|
147
195
|
export function modelAsk(ask: PendingAsk) {
|
|
148
196
|
return {
|
|
149
197
|
ask_id: ask.toolCallId,
|
|
198
|
+
...(ask.delivery ? { delivery: ask.delivery } : {}),
|
|
150
199
|
handoff: ask.handoff,
|
|
151
200
|
prompts: ask.prompts,
|
|
152
201
|
};
|
|
@@ -161,7 +210,7 @@ interface AgentEventDetails {
|
|
|
161
210
|
name?: string;
|
|
162
211
|
paneId: string;
|
|
163
212
|
response?: string;
|
|
164
|
-
state: "blocked" | "failed" | "finished";
|
|
213
|
+
state: "blocked" | "failed" | "finished" | "question";
|
|
165
214
|
tab?: string;
|
|
166
215
|
task?: string;
|
|
167
216
|
workspace?: string;
|
|
@@ -210,6 +259,7 @@ function eventAsk(value: unknown): PendingAsk | undefined {
|
|
|
210
259
|
if (prompts.length === 0) return undefined;
|
|
211
260
|
return {
|
|
212
261
|
toolCallId: record["toolCallId"],
|
|
262
|
+
...(record["delivery"] === "steer" ? { delivery: "steer" as const } : {}),
|
|
213
263
|
handoff: record["handoff"],
|
|
214
264
|
prompts,
|
|
215
265
|
};
|
|
@@ -232,9 +282,11 @@ function agentVoicePrompt(details: AgentEventDetails): string {
|
|
|
232
282
|
];
|
|
233
283
|
if (details.task?.trim()) lines.push(`Task:\n${details.task.trim()}`);
|
|
234
284
|
let instruction: string;
|
|
235
|
-
if (details.state === "blocked") {
|
|
285
|
+
if (details.state === "blocked" || details.state === "question") {
|
|
236
286
|
instruction =
|
|
237
|
-
|
|
287
|
+
details.state === "question"
|
|
288
|
+
? "Briefly tell the user what this worker asks while it continues working."
|
|
289
|
+
: "Briefly tell the user why this monitored worker is blocked and what attention may be required.";
|
|
238
290
|
if (details.blockedOn?.trim())
|
|
239
291
|
lines.push(`Reason:\n${details.blockedOn.trim()}`);
|
|
240
292
|
if (details.ask) {
|
|
@@ -316,6 +368,7 @@ function eventDetails(value: unknown): AgentEventDetails | undefined {
|
|
|
316
368
|
(details["machine"] !== undefined &&
|
|
317
369
|
typeof details["machine"] !== "string") ||
|
|
318
370
|
(details["state"] !== "blocked" &&
|
|
371
|
+
details["state"] !== "question" &&
|
|
319
372
|
details["state"] !== "failed" &&
|
|
320
373
|
details["state"] !== "finished")
|
|
321
374
|
) {
|
|
@@ -362,13 +415,16 @@ function agentEvent(options: AgentEventOptions): {
|
|
|
362
415
|
} = options;
|
|
363
416
|
const task = activityTask(record.activity);
|
|
364
417
|
const blocked = status === "blocked";
|
|
418
|
+
const question = status === "question";
|
|
365
419
|
const failed = !blocked && reply?.stopReason === "error";
|
|
366
420
|
const cwd = agent.foreground_cwd ?? agent.cwd ?? record.cwd;
|
|
367
|
-
const tag =
|
|
368
|
-
? "
|
|
369
|
-
:
|
|
370
|
-
? "
|
|
371
|
-
:
|
|
421
|
+
const tag = question
|
|
422
|
+
? "herdr_agent_question"
|
|
423
|
+
: blocked
|
|
424
|
+
? "herdr_agent_blocked"
|
|
425
|
+
: failed
|
|
426
|
+
? "herdr_agent_failed"
|
|
427
|
+
: "herdr_agent_result";
|
|
372
428
|
const attributes = sourceAttributes({
|
|
373
429
|
machine,
|
|
374
430
|
machine_name: machineLabel !== machine ? machineLabel : undefined,
|
|
@@ -381,7 +437,7 @@ function agentEvent(options: AgentEventOptions): {
|
|
|
381
437
|
if (blockedMessage) {
|
|
382
438
|
lines.push(`<blocked_on>${xml(blockedMessage)}</blocked_on>`);
|
|
383
439
|
}
|
|
384
|
-
if (blocked && ask) {
|
|
440
|
+
if ((blocked || question) && ask) {
|
|
385
441
|
lines.push(`<ask>${xml(JSON.stringify(modelAsk(ask)))}</ask>`);
|
|
386
442
|
}
|
|
387
443
|
if (blocked) {
|
|
@@ -389,6 +445,11 @@ function agentEvent(options: AgentEventOptions): {
|
|
|
389
445
|
`<operator_hint>${xml(blockedOperatorHint(agentToolName, machine, operatorPrefix, agent.pane_id))}</operator_hint>`,
|
|
390
446
|
);
|
|
391
447
|
}
|
|
448
|
+
if (question && ask) {
|
|
449
|
+
lines.push(
|
|
450
|
+
`<operator_hint>${xml(`Worker continues. Answer via ${agentToolName} action=answer machine=${JSON.stringify(machine)} target=${JSON.stringify(agent.pane_id)} ask_id=${JSON.stringify(ask.toolCallId)} answers=[...]`)}</operator_hint>`,
|
|
451
|
+
);
|
|
452
|
+
}
|
|
392
453
|
if (failed) {
|
|
393
454
|
lines.push(
|
|
394
455
|
`<operator_hint>${xml(failedOperatorHint(agentToolName, machine, operatorPrefix, agent.pane_id))}</operator_hint>`,
|
|
@@ -403,8 +464,14 @@ function agentEvent(options: AgentEventOptions): {
|
|
|
403
464
|
machine,
|
|
404
465
|
machineLabel,
|
|
405
466
|
paneId: agent.pane_id,
|
|
406
|
-
state:
|
|
407
|
-
|
|
467
|
+
state: question
|
|
468
|
+
? "question"
|
|
469
|
+
: blocked
|
|
470
|
+
? "blocked"
|
|
471
|
+
: failed
|
|
472
|
+
? "failed"
|
|
473
|
+
: "finished",
|
|
474
|
+
...((blocked || question) && ask ? { ask } : {}),
|
|
408
475
|
...(agent.name || record.name ? { name: agent.name || record.name } : {}),
|
|
409
476
|
...(cwd ? { cwd } : {}),
|
|
410
477
|
...(labels.workspace ? { workspace: labels.workspace } : {}),
|
|
@@ -466,13 +533,14 @@ export function registerAgentEventRenderer(pi: ExtensionAPI): void {
|
|
|
466
533
|
}
|
|
467
534
|
const blocked = details?.state === "blocked";
|
|
468
535
|
const failed = details?.state === "failed";
|
|
536
|
+
const question = details.state === "question";
|
|
469
537
|
const agentIdentity = details?.name
|
|
470
538
|
? `${details.name} (${details.paneId})`
|
|
471
539
|
: (details?.paneId ?? "unknown");
|
|
472
540
|
const identity = `${details.machineLabel ?? details.machine} / ${agentIdentity}`;
|
|
473
541
|
const title = theme.fg(
|
|
474
542
|
blocked || failed ? "error" : "success",
|
|
475
|
-
`Herdr agent ${identity} · ${blocked ? "blocked" : failed ? "failed" : "finished"}`,
|
|
543
|
+
`Herdr agent ${identity} · ${question ? "question pending, worker continues" : blocked ? "blocked" : failed ? "failed" : "finished"}`,
|
|
476
544
|
);
|
|
477
545
|
const location = [details?.workspace, details?.tab]
|
|
478
546
|
.filter(Boolean)
|
|
@@ -483,13 +551,16 @@ export function registerAgentEventRenderer(pi: ExtensionAPI): void {
|
|
|
483
551
|
);
|
|
484
552
|
box.addChild(new Text(title, 0, 0));
|
|
485
553
|
if (metadata) box.addChild(new Text(theme.fg("dim", metadata), 0, 0));
|
|
486
|
-
if (blocked) {
|
|
554
|
+
if (blocked || question) {
|
|
487
555
|
box.addChild(new Spacer(1));
|
|
488
556
|
box.addChild(
|
|
489
557
|
new Text(
|
|
490
558
|
theme.fg(
|
|
491
559
|
"warning",
|
|
492
|
-
details?.blockedOn ??
|
|
560
|
+
details?.blockedOn ??
|
|
561
|
+
(question
|
|
562
|
+
? "Question pending"
|
|
563
|
+
: "Agent needs input or approval"),
|
|
493
564
|
),
|
|
494
565
|
0,
|
|
495
566
|
0,
|