@narumitw/pi-herdr 0.2.0 → 0.3.1

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.
@@ -4,284 +4,282 @@ export const MAX_HERDR_FRAME_BYTES = 1024 * 1024;
4
4
  const MAX_PENDING_SUBSCRIPTION_EVENTS = 1024;
5
5
 
6
6
  export interface HerdrRequest {
7
- id: string;
8
- method: string;
9
- params: Record<string, unknown>;
7
+ id: string;
8
+ method: string;
9
+ params: Record<string, unknown>;
10
10
  }
11
11
 
12
12
  export interface HerdrSubscription {
13
- closed: Promise<void>;
14
- close(): void;
13
+ closed: Promise<void>;
14
+ close(): void;
15
15
  }
16
16
 
17
17
  class NdjsonFrames {
18
- private buffer = Buffer.alloc(0);
18
+ private buffer = Buffer.alloc(0);
19
19
 
20
- push(chunk: Buffer): unknown[] {
21
- this.buffer = Buffer.concat([this.buffer, chunk]);
22
- if (this.buffer.length > MAX_HERDR_FRAME_BYTES && this.buffer.indexOf(0x0a) < 0) {
23
- throw new Error("Herdr response frame exceeded the size limit");
24
- }
20
+ push(chunk: Buffer): unknown[] {
21
+ this.buffer = Buffer.concat([this.buffer, chunk]);
22
+ if (this.buffer.length > MAX_HERDR_FRAME_BYTES && this.buffer.indexOf(0x0a) < 0) {
23
+ throw new Error("Herdr response frame exceeded the size limit");
24
+ }
25
25
 
26
- const frames: unknown[] = [];
27
- while (true) {
28
- const newline = this.buffer.indexOf(0x0a);
29
- if (newline < 0) break;
30
- if (newline > MAX_HERDR_FRAME_BYTES) {
31
- throw new Error("Herdr response frame exceeded the size limit");
32
- }
33
- const line = this.buffer.subarray(0, newline);
34
- this.buffer = this.buffer.subarray(newline + 1);
35
- if (line.length === 0) continue;
36
- try {
37
- frames.push(JSON.parse(line.toString("utf8")));
38
- } catch {
39
- throw new Error("Herdr returned invalid JSON");
40
- }
41
- }
42
- return frames;
43
- }
26
+ const frames: unknown[] = [];
27
+ while (true) {
28
+ const newline = this.buffer.indexOf(0x0a);
29
+ if (newline < 0) break;
30
+ if (newline > MAX_HERDR_FRAME_BYTES) {
31
+ throw new Error("Herdr response frame exceeded the size limit");
32
+ }
33
+ const line = this.buffer.subarray(0, newline);
34
+ this.buffer = this.buffer.subarray(newline + 1);
35
+ if (line.length === 0) continue;
36
+ try {
37
+ frames.push(JSON.parse(line.toString("utf8")));
38
+ } catch {
39
+ throw new Error("Herdr returned invalid JSON");
40
+ }
41
+ }
42
+ return frames;
43
+ }
44
44
  }
45
45
 
46
46
  function isRecord(value: unknown): value is Record<string, unknown> {
47
- return typeof value === "object" && value !== null && !Array.isArray(value);
47
+ return typeof value === "object" && value !== null && !Array.isArray(value);
48
48
  }
49
49
 
50
50
  function abortReason(signal: AbortSignal): Error {
51
- return signal.reason instanceof Error
52
- ? signal.reason
53
- : new DOMException("Herdr request aborted", "AbortError");
51
+ return signal.reason instanceof Error ? signal.reason : new DOMException("Herdr request aborted", "AbortError");
54
52
  }
55
53
 
56
54
  function responseError(frame: Record<string, unknown>): Error | undefined {
57
- if (!isRecord(frame.error)) return undefined;
58
- const message = typeof frame.error.message === "string" ? frame.error.message : "request failed";
59
- return new Error(`Herdr ${message}`);
55
+ if (!isRecord(frame.error)) return undefined;
56
+ const message = typeof frame.error.message === "string" ? frame.error.message : "request failed";
57
+ return new Error(`Herdr ${message}`);
60
58
  }
61
59
 
62
60
  function sendRequestAttempt(
63
- socketEndpoint: string,
64
- request: HerdrRequest,
65
- timeoutMs: number,
66
- signal: AbortSignal,
61
+ socketEndpoint: string,
62
+ request: HerdrRequest,
63
+ timeoutMs: number,
64
+ signal: AbortSignal,
67
65
  ): Promise<boolean> {
68
- if (signal.aborted) return Promise.resolve(false);
66
+ if (signal.aborted) return Promise.resolve(false);
69
67
 
70
- return new Promise((resolve) => {
71
- let finished = false;
72
- let timeout: ReturnType<typeof setTimeout> | undefined;
73
- const socket = net.createConnection(socketEndpoint);
68
+ return new Promise((resolve) => {
69
+ let finished = false;
70
+ let timeout: ReturnType<typeof setTimeout> | undefined;
71
+ const socket = net.createConnection(socketEndpoint);
74
72
 
75
- const finish = (delivered: boolean) => {
76
- if (finished) return;
77
- finished = true;
78
- if (timeout) clearTimeout(timeout);
79
- signal.removeEventListener("abort", abort);
80
- socket.destroy();
81
- resolve(delivered);
82
- };
83
- const abort = () => finish(false);
73
+ const finish = (delivered: boolean) => {
74
+ if (finished) return;
75
+ finished = true;
76
+ if (timeout) clearTimeout(timeout);
77
+ signal.removeEventListener("abort", abort);
78
+ socket.destroy();
79
+ resolve(delivered);
80
+ };
81
+ const abort = () => finish(false);
84
82
 
85
- signal.addEventListener("abort", abort, { once: true });
86
- socket.on("error", () => finish(false));
87
- socket.on("connect", () => socket.write(`${JSON.stringify(request)}\n`));
88
- socket.on("data", () => finish(true));
89
- socket.on("end", () => finish(false));
90
- socket.on("close", () => finish(false));
91
- timeout = setTimeout(() => finish(false), timeoutMs);
92
- timeout.unref?.();
93
- });
83
+ signal.addEventListener("abort", abort, { once: true });
84
+ socket.on("error", () => finish(false));
85
+ socket.on("connect", () => socket.write(`${JSON.stringify(request)}\n`));
86
+ socket.on("data", () => finish(true));
87
+ socket.on("end", () => finish(false));
88
+ socket.on("close", () => finish(false));
89
+ timeout = setTimeout(() => finish(false), timeoutMs);
90
+ timeout.unref?.();
91
+ });
94
92
  }
95
93
 
96
94
  export function createBestEffortSender(socketEndpoint: string) {
97
- return async (request: HerdrRequest, signal: AbortSignal): Promise<void> => {
98
- if (await sendRequestAttempt(socketEndpoint, request, 500, signal)) return;
99
- if (signal.aborted) return;
100
- await sendRequestAttempt(socketEndpoint, request, 1500, signal);
101
- };
95
+ return async (request: HerdrRequest, signal: AbortSignal): Promise<void> => {
96
+ if (await sendRequestAttempt(socketEndpoint, request, 500, signal)) return;
97
+ if (signal.aborted) return;
98
+ await sendRequestAttempt(socketEndpoint, request, 1500, signal);
99
+ };
102
100
  }
103
101
 
104
102
  export function requestHerdr(
105
- socketEndpoint: string,
106
- request: HerdrRequest,
107
- signal: AbortSignal,
108
- timeoutMs = 1500,
103
+ socketEndpoint: string,
104
+ request: HerdrRequest,
105
+ signal: AbortSignal,
106
+ timeoutMs = 1500,
109
107
  ): Promise<unknown> {
110
- if (signal.aborted) return Promise.reject(abortReason(signal));
108
+ if (signal.aborted) return Promise.reject(abortReason(signal));
111
109
 
112
- return new Promise((resolve, reject) => {
113
- const socket = net.createConnection(socketEndpoint);
114
- const parser = new NdjsonFrames();
115
- let finished = false;
116
- const timeout = setTimeout(() => finish(new Error("Herdr request timed out")), timeoutMs);
117
- timeout.unref?.();
110
+ return new Promise((resolve, reject) => {
111
+ const socket = net.createConnection(socketEndpoint);
112
+ const parser = new NdjsonFrames();
113
+ let finished = false;
114
+ const timeout = setTimeout(() => finish(new Error("Herdr request timed out")), timeoutMs);
115
+ timeout.unref?.();
118
116
 
119
- const cleanup = () => {
120
- clearTimeout(timeout);
121
- signal.removeEventListener("abort", abort);
122
- socket.destroy();
123
- };
124
- const finish = (error?: Error, result?: unknown) => {
125
- if (finished) return;
126
- finished = true;
127
- cleanup();
128
- if (error) reject(error);
129
- else resolve(result);
130
- };
131
- const abort = () => finish(abortReason(signal));
117
+ const cleanup = () => {
118
+ clearTimeout(timeout);
119
+ signal.removeEventListener("abort", abort);
120
+ socket.destroy();
121
+ };
122
+ const finish = (error?: Error, result?: unknown) => {
123
+ if (finished) return;
124
+ finished = true;
125
+ cleanup();
126
+ if (error) reject(error);
127
+ else resolve(result);
128
+ };
129
+ const abort = () => finish(abortReason(signal));
132
130
 
133
- signal.addEventListener("abort", abort, { once: true });
134
- socket.on("connect", () => socket.write(`${JSON.stringify(request)}\n`));
135
- socket.on("error", (error) => finish(error));
136
- socket.on("end", () => finish(new Error("Herdr closed the request before responding")));
137
- socket.on("close", () => finish(new Error("Herdr request socket closed")));
138
- socket.on("data", (chunk: Buffer) => {
139
- try {
140
- for (const value of parser.push(chunk)) {
141
- if (!isRecord(value)) continue;
142
- const uncorrelatedError = responseError(value);
143
- if (uncorrelatedError && (value.id === "" || value.id === undefined)) {
144
- finish(uncorrelatedError);
145
- return;
146
- }
147
- if (value.id !== request.id) continue;
148
- const error = responseError(value);
149
- if (error) {
150
- finish(error);
151
- return;
152
- }
153
- if (!("result" in value)) {
154
- finish(new Error("Herdr response did not include a result"));
155
- return;
156
- }
157
- finish(undefined, value.result);
158
- return;
159
- }
160
- } catch (error) {
161
- finish(error instanceof Error ? error : new Error(String(error)));
162
- }
163
- });
164
- });
131
+ signal.addEventListener("abort", abort, { once: true });
132
+ socket.on("connect", () => socket.write(`${JSON.stringify(request)}\n`));
133
+ socket.on("error", (error) => finish(error));
134
+ socket.on("end", () => finish(new Error("Herdr closed the request before responding")));
135
+ socket.on("close", () => finish(new Error("Herdr request socket closed")));
136
+ socket.on("data", (chunk: Buffer) => {
137
+ try {
138
+ for (const value of parser.push(chunk)) {
139
+ if (!isRecord(value)) continue;
140
+ const uncorrelatedError = responseError(value);
141
+ if (uncorrelatedError && (value.id === "" || value.id === undefined)) {
142
+ finish(uncorrelatedError);
143
+ return;
144
+ }
145
+ if (value.id !== request.id) continue;
146
+ const error = responseError(value);
147
+ if (error) {
148
+ finish(error);
149
+ return;
150
+ }
151
+ if (!("result" in value)) {
152
+ finish(new Error("Herdr response did not include a result"));
153
+ return;
154
+ }
155
+ finish(undefined, value.result);
156
+ return;
157
+ }
158
+ } catch (error) {
159
+ finish(error instanceof Error ? error : new Error(String(error)));
160
+ }
161
+ });
162
+ });
165
163
  }
166
164
 
167
165
  export async function openHerdrSubscription(
168
- socketEndpoint: string,
169
- request: HerdrRequest,
170
- signal: AbortSignal,
171
- onEvent: (frame: unknown) => void,
172
- timeoutMs = 1500,
166
+ socketEndpoint: string,
167
+ request: HerdrRequest,
168
+ signal: AbortSignal,
169
+ onEvent: (frame: unknown) => void,
170
+ timeoutMs = 1500,
173
171
  ): Promise<HerdrSubscription> {
174
- if (signal.aborted) throw abortReason(signal);
172
+ if (signal.aborted) throw abortReason(signal);
175
173
 
176
- const socket = net.createConnection(socketEndpoint);
177
- const parser = new NdjsonFrames();
178
- const pendingEvents: unknown[] = [];
179
- let ready = false;
180
- let finished = false;
181
- let intentionalClose = false;
182
- let resolveReady!: () => void;
183
- let rejectReady!: (error: Error) => void;
184
- let resolveClosed!: () => void;
185
- let rejectClosed!: (error: Error) => void;
186
- const readyPromise = new Promise<void>((resolve, reject) => {
187
- resolveReady = resolve;
188
- rejectReady = reject;
189
- });
190
- const closed = new Promise<void>((resolve, reject) => {
191
- resolveClosed = resolve;
192
- rejectClosed = reject;
193
- });
194
- void closed.catch(() => undefined);
195
- const timeout = setTimeout(() => finish(new Error("Herdr subscription timed out")), timeoutMs);
196
- timeout.unref?.();
174
+ const socket = net.createConnection(socketEndpoint);
175
+ const parser = new NdjsonFrames();
176
+ const pendingEvents: unknown[] = [];
177
+ let ready = false;
178
+ let finished = false;
179
+ let intentionalClose = false;
180
+ let resolveReady!: () => void;
181
+ let rejectReady!: (error: Error) => void;
182
+ let resolveClosed!: () => void;
183
+ let rejectClosed!: (error: Error) => void;
184
+ const readyPromise = new Promise<void>((resolve, reject) => {
185
+ resolveReady = resolve;
186
+ rejectReady = reject;
187
+ });
188
+ const closed = new Promise<void>((resolve, reject) => {
189
+ resolveClosed = resolve;
190
+ rejectClosed = reject;
191
+ });
192
+ void closed.catch(() => undefined);
193
+ const timeout = setTimeout(() => finish(new Error("Herdr subscription timed out")), timeoutMs);
194
+ timeout.unref?.();
197
195
 
198
- const cleanup = () => {
199
- clearTimeout(timeout);
200
- signal.removeEventListener("abort", abort);
201
- socket.destroy();
202
- };
203
- const finish = (error?: Error) => {
204
- if (finished) return;
205
- finished = true;
206
- cleanup();
207
- if (!ready) {
208
- if (error && !intentionalClose) rejectReady(error);
209
- else rejectReady(abortReason(signal));
210
- resolveClosed();
211
- return;
212
- }
213
- if (error && !intentionalClose) rejectClosed(error);
214
- else resolveClosed();
215
- };
216
- const deliver = (frame: unknown) => {
217
- try {
218
- onEvent(frame);
219
- } catch (error) {
220
- finish(error instanceof Error ? error : new Error(String(error)));
221
- }
222
- };
223
- const abort = () => {
224
- intentionalClose = true;
225
- finish();
226
- };
196
+ const cleanup = () => {
197
+ clearTimeout(timeout);
198
+ signal.removeEventListener("abort", abort);
199
+ socket.destroy();
200
+ };
201
+ const finish = (error?: Error) => {
202
+ if (finished) return;
203
+ finished = true;
204
+ cleanup();
205
+ if (!ready) {
206
+ if (error && !intentionalClose) rejectReady(error);
207
+ else rejectReady(abortReason(signal));
208
+ resolveClosed();
209
+ return;
210
+ }
211
+ if (error && !intentionalClose) rejectClosed(error);
212
+ else resolveClosed();
213
+ };
214
+ const deliver = (frame: unknown) => {
215
+ try {
216
+ onEvent(frame);
217
+ } catch (error) {
218
+ finish(error instanceof Error ? error : new Error(String(error)));
219
+ }
220
+ };
221
+ const abort = () => {
222
+ intentionalClose = true;
223
+ finish();
224
+ };
227
225
 
228
- signal.addEventListener("abort", abort, { once: true });
229
- socket.on("connect", () => socket.write(`${JSON.stringify(request)}\n`));
230
- socket.on("error", (error) => finish(error));
231
- socket.on("end", () => finish(new Error("Herdr subscription closed")));
232
- socket.on("close", () => finish(new Error("Herdr subscription socket closed")));
233
- socket.on("data", (chunk: Buffer) => {
234
- try {
235
- for (const value of parser.push(chunk)) {
236
- if (!ready) {
237
- if (isRecord(value)) {
238
- const uncorrelatedError = responseError(value);
239
- if (uncorrelatedError && (value.id === "" || value.id === undefined)) {
240
- finish(uncorrelatedError);
241
- return;
242
- }
243
- }
244
- if (isRecord(value) && value.id === request.id) {
245
- const error = responseError(value);
246
- if (error) {
247
- finish(error);
248
- return;
249
- }
250
- if (!isRecord(value.result) || value.result.type !== "subscription_started") {
251
- finish(new Error("Herdr returned an invalid subscription acknowledgement"));
252
- return;
253
- }
254
- ready = true;
255
- clearTimeout(timeout);
256
- resolveReady();
257
- for (const event of pendingEvents.splice(0)) deliver(event);
258
- continue;
259
- }
260
- if (pendingEvents.length >= MAX_PENDING_SUBSCRIPTION_EVENTS) {
261
- finish(new Error("Too many Herdr events arrived before subscription acknowledgement"));
262
- return;
263
- }
264
- pendingEvents.push(value);
265
- continue;
266
- }
267
- deliver(value);
268
- }
269
- } catch (error) {
270
- finish(error instanceof Error ? error : new Error(String(error)));
271
- }
272
- });
226
+ signal.addEventListener("abort", abort, { once: true });
227
+ socket.on("connect", () => socket.write(`${JSON.stringify(request)}\n`));
228
+ socket.on("error", (error) => finish(error));
229
+ socket.on("end", () => finish(new Error("Herdr subscription closed")));
230
+ socket.on("close", () => finish(new Error("Herdr subscription socket closed")));
231
+ socket.on("data", (chunk: Buffer) => {
232
+ try {
233
+ for (const value of parser.push(chunk)) {
234
+ if (!ready) {
235
+ if (isRecord(value)) {
236
+ const uncorrelatedError = responseError(value);
237
+ if (uncorrelatedError && (value.id === "" || value.id === undefined)) {
238
+ finish(uncorrelatedError);
239
+ return;
240
+ }
241
+ }
242
+ if (isRecord(value) && value.id === request.id) {
243
+ const error = responseError(value);
244
+ if (error) {
245
+ finish(error);
246
+ return;
247
+ }
248
+ if (!isRecord(value.result) || value.result.type !== "subscription_started") {
249
+ finish(new Error("Herdr returned an invalid subscription acknowledgement"));
250
+ return;
251
+ }
252
+ ready = true;
253
+ clearTimeout(timeout);
254
+ resolveReady();
255
+ for (const event of pendingEvents.splice(0)) deliver(event);
256
+ continue;
257
+ }
258
+ if (pendingEvents.length >= MAX_PENDING_SUBSCRIPTION_EVENTS) {
259
+ finish(new Error("Too many Herdr events arrived before subscription acknowledgement"));
260
+ return;
261
+ }
262
+ pendingEvents.push(value);
263
+ continue;
264
+ }
265
+ deliver(value);
266
+ }
267
+ } catch (error) {
268
+ finish(error instanceof Error ? error : new Error(String(error)));
269
+ }
270
+ });
273
271
 
274
- await readyPromise;
275
- if (signal.aborted) {
276
- intentionalClose = true;
277
- finish();
278
- throw abortReason(signal);
279
- }
280
- return {
281
- closed,
282
- close() {
283
- intentionalClose = true;
284
- finish();
285
- },
286
- };
272
+ await readyPromise;
273
+ if (signal.aborted) {
274
+ intentionalClose = true;
275
+ finish();
276
+ throw abortReason(signal);
277
+ }
278
+ return {
279
+ closed,
280
+ close() {
281
+ intentionalClose = true;
282
+ finish();
283
+ },
284
+ };
287
285
  }
package/src/herdr-menu.ts CHANGED
@@ -1,55 +1,54 @@
1
1
  import type { MenuDefinition } from "@narumitw/pi-tui-kit";
2
2
 
3
3
  export function createHerdrMenu(options: {
4
- settingsPath: string;
5
- isEnabled(): boolean;
6
- toggle(signal: AbortSignal): Promise<boolean>;
4
+ settingsPath: string;
5
+ isEnabled(): boolean;
6
+ toggle(signal: AbortSignal): Promise<boolean>;
7
7
  }): MenuDefinition<undefined, "main" | "status" | "help", "toggle"> {
8
- return {
9
- start: "main",
10
- screens: {
11
- // One setting stays on the main menu, matching /tool rather than adding a submenu.
12
- main: () => ({
13
- kind: "actions",
14
- title: "Herdr",
15
- items: [
16
- {
17
- id: "widget",
18
- label: `Agent widget: ${options.isEnabled() ? "On" : "Off"}`,
19
- description: "Show or hide sibling agents above the editor",
20
- action: "toggle",
21
- },
22
- { id: "status", label: "Status", to: "status" },
23
- { id: "help", label: "Help", to: "help" },
24
- { id: "close", label: "Close", close: true },
25
- ],
26
- hint: "close",
27
- }),
28
- status: () => ({
29
- kind: "detail",
30
- title: "Herdr Status",
31
- lines: [
32
- `Agent widget setting: ${options.isEnabled() ? "on" : "off"}`,
33
- "The widget appears only in TUI mode with recognized sibling agents.",
34
- "Lifecycle and metadata reporting are independent of this setting.",
35
- `User settings file: ${options.settingsPath}`,
36
- ],
37
- hint: "back",
38
- }),
39
- help: () => ({
40
- kind: "detail",
41
- title: "Herdr Help",
42
- lines: [
43
- "Toggle Agent widget from /herdr. Changes are saved immediately; closing does not undo them.",
44
- "Manual pi-herdr.json changes apply after /reload or the next session start.",
45
- "The widget defaults to on. Project overrides are not read.",
46
- ],
47
- hint: "back",
48
- }),
49
- },
50
- actions: {
51
- toggle: async ({ signal }) =>
52
- (await options.toggle(signal)) ? { kind: "stay" } : { kind: "rejected" },
53
- },
54
- };
8
+ return {
9
+ start: "main",
10
+ screens: {
11
+ // One setting stays on the main menu, matching /tool rather than adding a submenu.
12
+ main: () => ({
13
+ kind: "actions",
14
+ title: "Herdr",
15
+ items: [
16
+ {
17
+ id: "widget",
18
+ label: `Agent widget: ${options.isEnabled() ? "On" : "Off"}`,
19
+ description: "Show or hide sibling agents above the editor",
20
+ action: "toggle",
21
+ },
22
+ { id: "status", label: "Status", to: "status" },
23
+ { id: "help", label: "Help", to: "help" },
24
+ { id: "close", label: "Close", close: true },
25
+ ],
26
+ hint: "close",
27
+ }),
28
+ status: () => ({
29
+ kind: "detail",
30
+ title: "Herdr Status",
31
+ lines: [
32
+ `Agent widget setting: ${options.isEnabled() ? "on" : "off"}`,
33
+ "The widget appears only in TUI mode with recognized sibling agents.",
34
+ "Lifecycle and metadata reporting are independent of this setting.",
35
+ `User settings file: ${options.settingsPath}`,
36
+ ],
37
+ hint: "back",
38
+ }),
39
+ help: () => ({
40
+ kind: "detail",
41
+ title: "Herdr Help",
42
+ lines: [
43
+ "Toggle Agent widget from /herdr. Changes are saved immediately; closing does not undo them.",
44
+ "Manual pi-herdr.json changes apply after /reload or the next session start.",
45
+ "The widget defaults to on. Project overrides are not read.",
46
+ ],
47
+ hint: "back",
48
+ }),
49
+ },
50
+ actions: {
51
+ toggle: async ({ signal }) => ((await options.toggle(signal)) ? { kind: "stay" } : { kind: "rejected" }),
52
+ },
53
+ };
55
54
  }