@howaboua/pi-shepherdr 0.2.15 → 0.2.16

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.
Files changed (51) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +40 -33
  3. package/index.ts +16 -26
  4. package/package.json +11 -11
  5. package/src/agents-contract.ts +11 -1
  6. package/src/agents-discovery.ts +21 -7
  7. package/src/agents-focus.ts +242 -0
  8. package/src/agents-spawn.ts +23 -0
  9. package/src/agents-tool.ts +34 -5
  10. package/src/attachment-protocol.ts +7 -3
  11. package/src/attachment-target.ts +3 -1
  12. package/src/attachment.ts +3 -1
  13. package/src/board/host.ts +98 -366
  14. package/src/board/membership.ts +14 -8
  15. package/src/command-config.ts +51 -0
  16. package/src/control-panel-actions.ts +0 -20
  17. package/src/control-panel-items.ts +8 -36
  18. package/src/control-panel-view.ts +2 -11
  19. package/src/control-panel.ts +2 -11
  20. package/src/controller.ts +5 -5
  21. package/src/delivery.ts +0 -33
  22. package/src/herdr-client.ts +39 -6
  23. package/src/messages.ts +61 -61
  24. package/src/monitor-events.ts +24 -2
  25. package/src/monitor-questions.ts +12 -3
  26. package/src/monitor.ts +2 -2
  27. package/src/peer-channel.ts +39 -0
  28. package/src/peer-commands.ts +173 -0
  29. package/src/peer-inbox.ts +218 -55
  30. package/src/remote/shepherdr-channel.mjs +225 -0
  31. package/src/remote/shepherdr-checkpoints.mjs +5 -3
  32. package/src/remote/shepherdr-peer.mjs +151 -22
  33. package/src/remote/shepherdr.mjs +56 -8
  34. package/src/remote-client.ts +115 -11
  35. package/src/settlement.ts +1 -0
  36. package/src/shared-context.ts +104 -1
  37. package/src/types.ts +23 -0
  38. package/src/voice-handoff.ts +177 -0
  39. package/src/board/archive.ts +0 -77
  40. package/src/board/awareness.ts +0 -115
  41. package/src/board/config.ts +0 -121
  42. package/src/board/contract.ts +0 -181
  43. package/src/board/identity.ts +0 -169
  44. package/src/board/paging.ts +0 -55
  45. package/src/board/protocol.ts +0 -73
  46. package/src/board/queries.ts +0 -176
  47. package/src/board/response.ts +0 -56
  48. package/src/board/store.ts +0 -327
  49. package/src/board/tool.ts +0 -23
  50. package/src/board/turns.ts +0 -100
  51. package/src/context-briefing.ts +0 -226
@@ -1,100 +0,0 @@
1
- import { randomUUID } from "node:crypto";
2
- import type {
3
- ExtensionAPI,
4
- ExtensionContext,
5
- } from "@earendil-works/pi-coding-agent";
6
- import { sendPolicyMessage } from "../delivery.js";
7
- import { type BoardBinding, binding } from "./identity.js";
8
- import type { BoardEnvelope } from "./protocol.js";
9
-
10
- type ActiveEnvelope = Extract<BoardEnvelope, { operation: "board-active" }>;
11
- type NoticeEnvelope = Extract<BoardEnvelope, { operation: "board-notify" }>;
12
-
13
- /** Turn IDs are transient capabilities. A stale snapshot cannot reach a later turn. */
14
- export class BoardTurns {
15
- private current: { ctx: ExtensionContext; turnId: string } | undefined;
16
- readonly active = new Map<string, { sessionId: string; turnId: string }>();
17
- constructor(
18
- pi: ExtensionAPI,
19
- register: (
20
- ctx: ExtensionContext,
21
- request: ActiveEnvelope,
22
- ) => Promise<unknown>,
23
- ) {
24
- pi.on("session_start", () => {
25
- this.current = undefined;
26
- this.active.clear();
27
- });
28
- pi.on("agent_start", async (_event, ctx) => {
29
- const own = binding(ctx);
30
- if (!own.enabled) return;
31
- const turnId = randomUUID();
32
- this.current = { ctx, turnId };
33
- try {
34
- await register(ctx, { operation: "board-active", caller: own, turnId });
35
- } catch (error) {
36
- ctx.ui.notify(
37
- `Board notifications unavailable: ${String(error)}`,
38
- "warning",
39
- );
40
- }
41
- });
42
- const stop = async () => {
43
- const current = this.current;
44
- this.current = undefined;
45
- if (!current) return;
46
- try {
47
- await register(current.ctx, {
48
- operation: "board-active",
49
- caller: binding(current.ctx),
50
- turnId: null,
51
- previousTurnId: current.turnId,
52
- });
53
- } catch {
54
- /* No retry or delayed removal may affect a later turn. */
55
- }
56
- };
57
- pi.on("agent_end", stop);
58
- pi.on("agent_settled", stop);
59
- pi.on("session_shutdown", async () => {
60
- await stop();
61
- this.active.clear();
62
- });
63
- this.deliver = (request) => {
64
- const current = this.current;
65
- if (!current || current.turnId !== request.turnId || current.ctx.isIdle())
66
- return false;
67
- const own = binding(current.ctx);
68
- if (
69
- !own.enabled ||
70
- own.boardId !== request.boardId ||
71
- own.sessionId !== request.sessionId ||
72
- own.agentName !== request.target
73
- )
74
- return false;
75
- // No await between running-turn check and steering. Never use the idle kickoff.
76
- sendPolicyMessage(
77
- pi,
78
- {
79
- customType: "shepherdr-board-post",
80
- content: `Board post ${JSON.stringify(request.notice)}`,
81
- display: true,
82
- },
83
- { deliverAs: "steer" },
84
- );
85
- return true;
86
- };
87
- }
88
- readonly deliver: (request: NoticeEnvelope) => boolean;
89
- register(caller: BoardBinding, request: ActiveEnvelope) {
90
- if (request.turnId)
91
- this.active.set(caller.agentName, {
92
- sessionId: caller.sessionId,
93
- turnId: request.turnId,
94
- });
95
- else if (
96
- this.active.get(caller.agentName)?.turnId === request.previousTurnId
97
- )
98
- this.active.delete(caller.agentName);
99
- }
100
- }
@@ -1,226 +0,0 @@
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
- }