@narumitw/pi-herdr 0.2.0 → 0.3.0

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.
@@ -2,450 +2,443 @@ import path from "node:path";
2
2
  import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
3
3
  import { createBestEffortSender, type HerdrRequest } from "./herdr-client.js";
4
4
  import {
5
- createHerdrMetadataClearSnapshot,
6
- createHerdrMetadataRequest,
7
- createHerdrMetadataSnapshot,
8
- HERDR_METADATA_REFRESH_MS,
9
- type HerdrMetadataSnapshot,
10
- herdrMetadataSnapshotsEqual,
5
+ createHerdrMetadataClearSnapshot,
6
+ createHerdrMetadataRequest,
7
+ createHerdrMetadataSnapshot,
8
+ HERDR_METADATA_REFRESH_MS,
9
+ type HerdrMetadataSnapshot,
10
+ herdrMetadataSnapshotsEqual,
11
11
  } from "./herdr-metadata.js";
12
12
  import { createHerdrWidgetObserver, type HerdrWidgetObserver } from "./herdr-observer.js";
13
13
 
14
- import {
15
- createHerdrSettingsController,
16
- type HerdrSettingsOptions,
17
- } from "./herdr-settings-controller.js";
14
+ import { createHerdrSettingsController, type HerdrSettingsOptions } from "./herdr-settings-controller.js";
18
15
 
19
16
  const SOURCE = "herdr:pi";
20
17
 
21
18
  export type AgentState = "working" | "blocked" | "idle";
22
19
 
23
20
  interface HerdrEnvironment {
24
- enabled: boolean;
25
- paneId: string;
26
- socketEndpoint: string;
21
+ enabled: boolean;
22
+ paneId: string;
23
+ socketEndpoint: string;
27
24
  }
28
25
 
29
26
  interface QueuedState {
30
- state: AgentState;
31
- message?: string;
32
- seq: number;
33
- signal: AbortSignal;
27
+ state: AgentState;
28
+ message?: string;
29
+ seq: number;
30
+ signal: AbortSignal;
34
31
  }
35
32
 
36
33
  interface QueuedMetadata {
37
- snapshot: HerdrMetadataSnapshot;
38
- seq: number;
39
- signal: AbortSignal;
40
- generation: number;
34
+ snapshot: HerdrMetadataSnapshot;
35
+ seq: number;
36
+ signal: AbortSignal;
37
+ generation: number;
41
38
  }
42
39
 
43
40
  export interface HerdrAgentStateOptions extends HerdrSettingsOptions {
44
- environment?: HerdrEnvironment;
45
- now?: () => number;
46
- random?: () => number;
47
- sendRequest?: (request: HerdrRequest, signal: AbortSignal) => Promise<void>;
48
- widgetObserver?: HerdrWidgetObserver;
41
+ environment?: HerdrEnvironment;
42
+ now?: () => number;
43
+ random?: () => number;
44
+ sendRequest?: (request: HerdrRequest, signal: AbortSignal) => Promise<void>;
45
+ widgetObserver?: HerdrWidgetObserver;
49
46
  }
50
47
 
51
48
  let reportSeq = Date.now() * 1000;
52
49
 
53
50
  function nextReportSeq(): number {
54
- reportSeq += 1;
55
- return reportSeq;
51
+ reportSeq += 1;
52
+ return reportSeq;
56
53
  }
57
54
 
58
55
  export function resolveSocketEndpoint(
59
- socketPath: string | undefined,
60
- platform: NodeJS.Platform = process.platform,
56
+ socketPath: string | undefined,
57
+ platform: NodeJS.Platform = process.platform,
61
58
  ): string {
62
- if (!socketPath || platform !== "win32") return socketPath ?? "";
63
- const normalized = socketPath.toLowerCase();
64
- if (normalized.startsWith("\\\\.\\pipe\\") || normalized.startsWith("\\\\?\\pipe\\")) {
65
- return socketPath;
66
- }
67
- return `\\\\.\\pipe\\${socketPath}`;
59
+ if (!socketPath || platform !== "win32") return socketPath ?? "";
60
+ const normalized = socketPath.toLowerCase();
61
+ if (normalized.startsWith("\\\\.\\pipe\\") || normalized.startsWith("\\\\?\\pipe\\")) {
62
+ return socketPath;
63
+ }
64
+ return `\\\\.\\pipe\\${socketPath}`;
68
65
  }
69
66
 
70
67
  function readEnvironment(environment: NodeJS.ProcessEnv = process.env): HerdrEnvironment {
71
- const socketPath = environment.HERDR_SOCKET_PATH;
72
- const paneId = environment.HERDR_PANE_ID;
73
- return {
74
- enabled: environment.HERDR_ENV === "1" && !!socketPath && !!paneId,
75
- paneId: paneId ?? "",
76
- socketEndpoint: resolveSocketEndpoint(socketPath),
77
- };
68
+ const socketPath = environment.HERDR_SOCKET_PATH;
69
+ const paneId = environment.HERDR_PANE_ID;
70
+ return {
71
+ enabled: environment.HERDR_ENV === "1" && !!socketPath && !!paneId,
72
+ paneId: paneId ?? "",
73
+ socketEndpoint: resolveSocketEndpoint(socketPath),
74
+ };
78
75
  }
79
76
 
80
- export function createHerdrAgentStateExtension(
81
- options: HerdrAgentStateOptions = {},
82
- ): (pi: ExtensionAPI) => void {
83
- const environment = options.environment ?? readEnvironment();
84
- const now = options.now ?? Date.now;
85
- const random = options.random ?? Math.random;
86
- const sendRequest = options.sendRequest ?? createBestEffortSender(environment.socketEndpoint);
87
- const widgetObserver =
88
- options.widgetObserver ??
89
- createHerdrWidgetObserver({
90
- environment,
91
- now,
92
- random,
93
- });
94
-
95
- return function herdrAgentState(pi: ExtensionAPI): void {
96
- if (!environment.enabled) return;
97
- const widget = createHerdrSettingsController(pi, widgetObserver, options);
98
-
99
- let sessionGeneration = 0;
100
- let sessionController = new AbortController();
101
- let activeSession: ExtensionContext["sessionManager"] | undefined;
102
- let currentAgentSessionId: string | undefined;
103
- let currentAgentSessionPath: string | undefined;
104
- let agentActive = false;
105
- let blockedCount = 0;
106
- let blockedMessage: string | undefined;
107
- let lastState: AgentState | undefined;
108
- let lastMessage: string | undefined;
109
- let rootSession = false;
110
- let queuedState: QueuedState | undefined;
111
- let drainTask: Promise<void> | undefined;
112
- let queuedMetadata: QueuedMetadata | undefined;
113
- let metadataDrainTask: Promise<void> | undefined;
114
- let lastMetadataSnapshot: HerdrMetadataSnapshot | undefined;
115
- let metadataRefreshTimer: ReturnType<typeof setTimeout> | undefined;
116
- let shutdownClearController: AbortController | undefined;
117
- let shutdownSession: ExtensionContext["sessionManager"] | undefined;
118
- let shutdownTask: Promise<void> | undefined;
119
-
120
- function requestId(kind?: "session"): string {
121
- const segment = kind ? `${kind}:` : "";
122
- return `${SOURCE}:${segment}${now()}:${random().toString(36).slice(2)}`;
123
- }
124
-
125
- function updateSessionRef(ctx: ExtensionContext): void {
126
- try {
127
- const file = ctx.sessionManager.getSessionFile();
128
- currentAgentSessionPath =
129
- typeof file === "string" && path.isAbsolute(file) ? file : undefined;
130
- } catch {
131
- currentAgentSessionPath = undefined;
132
- }
133
-
134
- try {
135
- const id = ctx.sessionManager.getSessionId();
136
- currentAgentSessionId = typeof id === "string" && id.length > 0 ? id : undefined;
137
- } catch {
138
- currentAgentSessionId = undefined;
139
- }
140
- }
141
-
142
- function currentSessionRef(): Record<string, unknown> | undefined {
143
- if (currentAgentSessionPath) return { agent_session_path: currentAgentSessionPath };
144
- if (currentAgentSessionId) return { agent_session_id: currentAgentSessionId };
145
- return undefined;
146
- }
147
-
148
- function withSessionRef(params: Record<string, unknown>): Record<string, unknown> {
149
- return { ...params, ...currentSessionRef() };
150
- }
151
-
152
- async function safeSend(request: HerdrRequest, signal: AbortSignal): Promise<void> {
153
- try {
154
- await sendRequest(request, signal);
155
- } catch {
156
- // Herdr reporting is best-effort and must not interrupt Pi.
157
- }
158
- }
159
-
160
- function reportSession(sessionStartSource?: string): Promise<void> {
161
- const sessionRef = currentSessionRef();
162
- if (!sessionRef) return Promise.resolve();
163
- return safeSend(
164
- {
165
- id: requestId("session"),
166
- method: "pane.report_agent_session",
167
- params: {
168
- pane_id: environment.paneId,
169
- source: SOURCE,
170
- agent: "pi",
171
- seq: nextReportSeq(),
172
- session_start_source: sessionStartSource,
173
- ...sessionRef,
174
- },
175
- },
176
- sessionController.signal,
177
- );
178
- }
179
-
180
- function stateRequest(state: QueuedState): HerdrRequest {
181
- return {
182
- id: requestId(),
183
- method: "pane.report_agent",
184
- params: withSessionRef({
185
- pane_id: environment.paneId,
186
- source: SOURCE,
187
- agent: "pi",
188
- state: state.state,
189
- message: state.message,
190
- seq: state.seq,
191
- }),
192
- };
193
- }
194
-
195
- function readMetadataSnapshot(ctx: ExtensionContext): HerdrMetadataSnapshot {
196
- let session: string | undefined;
197
- let contextUsagePercent: number | null | undefined;
198
- try {
199
- session = pi.getSessionName();
200
- } catch {
201
- // Metadata is best-effort and optional Pi fields can be unavailable.
202
- }
203
- try {
204
- contextUsagePercent = ctx.getContextUsage()?.percent;
205
- } catch {
206
- // Clear unknown usage instead of retaining a stale percentage.
207
- }
208
- return createHerdrMetadataSnapshot({
209
- model: ctx.model?.id,
210
- provider: ctx.model?.provider,
211
- thinking: ctx.thinkingLevel,
212
- session,
213
- contextUsagePercent,
214
- });
215
- }
216
-
217
- function metadataRequest(metadata: QueuedMetadata): HerdrRequest {
218
- return createHerdrMetadataRequest({
219
- id: requestId(),
220
- paneId: environment.paneId,
221
- source: SOURCE,
222
- seq: metadata.seq,
223
- snapshot: metadata.snapshot,
224
- });
225
- }
226
-
227
- async function drainStateQueue(): Promise<void> {
228
- while (queuedState) {
229
- const next = queuedState;
230
- queuedState = undefined;
231
- if (!next.signal.aborted) await safeSend(stateRequest(next), next.signal);
232
- }
233
- }
234
-
235
- function queueState(state: AgentState, message?: string): void {
236
- queuedState = {
237
- state,
238
- message,
239
- seq: nextReportSeq(),
240
- signal: sessionController.signal,
241
- };
242
- if (drainTask) return;
243
- drainTask = drainStateQueue().finally(() => {
244
- drainTask = undefined;
245
- if (queuedState) queueState(queuedState.state, queuedState.message);
246
- });
247
- }
248
-
249
- async function drainMetadataQueue(): Promise<void> {
250
- while (queuedMetadata) {
251
- const next = queuedMetadata;
252
- queuedMetadata = undefined;
253
- if (next.signal.aborted || next.generation !== sessionGeneration || !rootSession) {
254
- continue;
255
- }
256
- await safeSend(metadataRequest(next), next.signal);
257
- }
258
- }
259
-
260
- function startMetadataDrain(): void {
261
- if (metadataDrainTask) return;
262
- metadataDrainTask = drainMetadataQueue().finally(() => {
263
- metadataDrainTask = undefined;
264
- if (queuedMetadata) startMetadataDrain();
265
- });
266
- }
267
-
268
- function scheduleMetadataRefresh(generation: number): void {
269
- if (metadataRefreshTimer) clearTimeout(metadataRefreshTimer);
270
- metadataRefreshTimer = setTimeout(() => {
271
- metadataRefreshTimer = undefined;
272
- if (
273
- generation !== sessionGeneration ||
274
- sessionController.signal.aborted ||
275
- !rootSession ||
276
- !lastMetadataSnapshot
277
- ) {
278
- return;
279
- }
280
- queueMetadata(lastMetadataSnapshot, true);
281
- }, HERDR_METADATA_REFRESH_MS);
282
- metadataRefreshTimer.unref?.();
283
- }
284
-
285
- function queueMetadata(snapshot: HerdrMetadataSnapshot, force = false): void {
286
- if (!rootSession || sessionController.signal.aborted) return;
287
- if (!force && herdrMetadataSnapshotsEqual(lastMetadataSnapshot, snapshot)) return;
288
- lastMetadataSnapshot = snapshot;
289
- queuedMetadata = {
290
- snapshot,
291
- seq: nextReportSeq(),
292
- signal: sessionController.signal,
293
- generation: sessionGeneration,
294
- };
295
- scheduleMetadataRefresh(sessionGeneration);
296
- startMetadataDrain();
297
- }
298
-
299
- function owns(ctx: ExtensionContext): boolean {
300
- return rootSession && ctx.sessionManager === activeSession;
301
- }
302
-
303
- function publishMetadata(ctx: ExtensionContext): void {
304
- if (!owns(ctx)) return;
305
- queueMetadata(readMetadataSnapshot(ctx));
306
- }
307
-
308
- function desiredState(): { state: AgentState; message?: string } {
309
- if (blockedCount > 0) return { state: "blocked", message: blockedMessage };
310
- if (agentActive) return { state: "working" };
311
- return { state: "idle" };
312
- }
313
-
314
- function publishState(force = false): void {
315
- const next = desiredState();
316
- if (!force && next.state === lastState && next.message === lastMessage) return;
317
- lastState = next.state;
318
- lastMessage = next.message;
319
- queueState(next.state, next.message);
320
- }
321
-
322
- pi.on("ui_prompt_start", (event, ctx) => {
323
- if (!owns(ctx)) return;
324
- blockedCount += 1;
325
- blockedMessage = event.title?.trim() || event.kind;
326
- publishState();
327
- });
328
-
329
- pi.on("ui_prompt_end", (_event, ctx) => {
330
- if (!owns(ctx)) return;
331
- blockedCount = Math.max(0, blockedCount - 1);
332
- if (blockedCount === 0) blockedMessage = undefined;
333
- publishState();
334
- });
335
-
336
- pi.on("session_start", async (event, ctx) => {
337
- const generation = ++sessionGeneration;
338
- const replaced = new DOMException("Herdr session replaced", "AbortError");
339
- sessionController.abort(replaced);
340
- shutdownClearController?.abort(replaced);
341
- shutdownClearController = undefined;
342
- if (metadataRefreshTimer) clearTimeout(metadataRefreshTimer);
343
- metadataRefreshTimer = undefined;
344
- queuedMetadata = undefined;
345
- lastMetadataSnapshot = undefined;
346
- sessionController = new AbortController();
347
- activeSession = ctx.sessionManager;
348
- rootSession = ctx.mode === "tui";
349
- const widgetStart = widget.start(ctx);
350
- agentActive = false;
351
- blockedCount = 0;
352
- blockedMessage = undefined;
353
- lastState = undefined;
354
- lastMessage = undefined;
355
- if (!rootSession) {
356
- await widgetStart;
357
- return;
358
- }
359
-
360
- updateSessionRef(ctx);
361
- const sessionReport = reportSession(event.reason);
362
- publishMetadata(ctx);
363
- await Promise.all([sessionReport, widgetStart]);
364
- if (generation !== sessionGeneration || sessionController.signal.aborted || !rootSession) {
365
- return;
366
- }
367
- agentActive = !ctx.isIdle();
368
- publishState(true);
369
- });
370
-
371
- pi.on("agent_start", (_event, ctx) => {
372
- if (!owns(ctx)) return;
373
- updateSessionRef(ctx);
374
- void reportSession();
375
- agentActive = true;
376
- publishState();
377
- });
378
-
379
- pi.on("agent_settled", (_event, ctx) => {
380
- if (!owns(ctx)) return;
381
- publishMetadata(ctx);
382
- if (!ctx.isIdle()) return;
383
- agentActive = false;
384
- publishState();
385
- });
386
-
387
- pi.on("session_info_changed", (_event, ctx) => publishMetadata(ctx));
388
- pi.on("model_select", (_event, ctx) => publishMetadata(ctx));
389
- pi.on("thinking_level_select", (_event, ctx) => publishMetadata(ctx));
390
- pi.on("session_compact", (_event, ctx) => publishMetadata(ctx));
391
-
392
- pi.on("session_shutdown", async (_event, ctx) => {
393
- if (ctx.sessionManager !== activeSession) {
394
- await Promise.allSettled([widget.shutdown(ctx)]);
395
- return;
396
- }
397
- if (shutdownTask && shutdownSession === ctx.sessionManager) {
398
- await shutdownTask;
399
- return;
400
- }
401
-
402
- const session = ctx.sessionManager;
403
- const task = (async () => {
404
- const shouldClearMetadata = rootSession;
405
- const shutdownGeneration = ++sessionGeneration;
406
- rootSession = false;
407
- if (metadataRefreshTimer) clearTimeout(metadataRefreshTimer);
408
- metadataRefreshTimer = undefined;
409
- sessionController.abort(new DOMException("Herdr session shut down", "AbortError"));
410
- queuedState = undefined;
411
- queuedMetadata = undefined;
412
- await Promise.allSettled([drainTask, metadataDrainTask, widget.shutdown(ctx)]);
413
- const stillOwnsShutdown =
414
- shutdownGeneration === sessionGeneration && activeSession === session && !rootSession;
415
- if (shouldClearMetadata && stillOwnsShutdown) {
416
- const controller = new AbortController();
417
- shutdownClearController = controller;
418
- await safeSend(
419
- createHerdrMetadataRequest({
420
- id: requestId(),
421
- paneId: environment.paneId,
422
- source: SOURCE,
423
- seq: nextReportSeq(),
424
- snapshot: createHerdrMetadataClearSnapshot(),
425
- }),
426
- controller.signal,
427
- );
428
- if (shutdownClearController === controller) shutdownClearController = undefined;
429
- }
430
- if (shutdownGeneration !== sessionGeneration || activeSession !== session || rootSession) {
431
- return;
432
- }
433
- lastMetadataSnapshot = undefined;
434
- currentAgentSessionId = undefined;
435
- currentAgentSessionPath = undefined;
436
- activeSession = undefined;
437
- })();
438
- shutdownSession = session;
439
- shutdownTask = task;
440
- await task;
441
- if (shutdownTask === task) {
442
- shutdownTask = undefined;
443
- shutdownSession = undefined;
444
- }
445
- });
446
- };
77
+ export function createHerdrAgentStateExtension(options: HerdrAgentStateOptions = {}): (pi: ExtensionAPI) => void {
78
+ const environment = options.environment ?? readEnvironment();
79
+ const now = options.now ?? Date.now;
80
+ const random = options.random ?? Math.random;
81
+ const sendRequest = options.sendRequest ?? createBestEffortSender(environment.socketEndpoint);
82
+ const widgetObserver =
83
+ options.widgetObserver ??
84
+ createHerdrWidgetObserver({
85
+ environment,
86
+ now,
87
+ random,
88
+ });
89
+
90
+ return function herdrAgentState(pi: ExtensionAPI): void {
91
+ if (!environment.enabled) return;
92
+ const widget = createHerdrSettingsController(pi, widgetObserver, options);
93
+
94
+ let sessionGeneration = 0;
95
+ let sessionController = new AbortController();
96
+ let activeSession: ExtensionContext["sessionManager"] | undefined;
97
+ let currentAgentSessionId: string | undefined;
98
+ let currentAgentSessionPath: string | undefined;
99
+ let agentActive = false;
100
+ let blockedCount = 0;
101
+ let blockedMessage: string | undefined;
102
+ let lastState: AgentState | undefined;
103
+ let lastMessage: string | undefined;
104
+ let rootSession = false;
105
+ let queuedState: QueuedState | undefined;
106
+ let drainTask: Promise<void> | undefined;
107
+ let queuedMetadata: QueuedMetadata | undefined;
108
+ let metadataDrainTask: Promise<void> | undefined;
109
+ let lastMetadataSnapshot: HerdrMetadataSnapshot | undefined;
110
+ let metadataRefreshTimer: ReturnType<typeof setTimeout> | undefined;
111
+ let shutdownClearController: AbortController | undefined;
112
+ let shutdownSession: ExtensionContext["sessionManager"] | undefined;
113
+ let shutdownTask: Promise<void> | undefined;
114
+
115
+ function requestId(kind?: "session"): string {
116
+ const segment = kind ? `${kind}:` : "";
117
+ return `${SOURCE}:${segment}${now()}:${random().toString(36).slice(2)}`;
118
+ }
119
+
120
+ function updateSessionRef(ctx: ExtensionContext): void {
121
+ try {
122
+ const file = ctx.sessionManager.getSessionFile();
123
+ currentAgentSessionPath = typeof file === "string" && path.isAbsolute(file) ? file : undefined;
124
+ } catch {
125
+ currentAgentSessionPath = undefined;
126
+ }
127
+
128
+ try {
129
+ const id = ctx.sessionManager.getSessionId();
130
+ currentAgentSessionId = typeof id === "string" && id.length > 0 ? id : undefined;
131
+ } catch {
132
+ currentAgentSessionId = undefined;
133
+ }
134
+ }
135
+
136
+ function currentSessionRef(): Record<string, unknown> | undefined {
137
+ if (currentAgentSessionPath) return { agent_session_path: currentAgentSessionPath };
138
+ if (currentAgentSessionId) return { agent_session_id: currentAgentSessionId };
139
+ return undefined;
140
+ }
141
+
142
+ function withSessionRef(params: Record<string, unknown>): Record<string, unknown> {
143
+ return { ...params, ...currentSessionRef() };
144
+ }
145
+
146
+ async function safeSend(request: HerdrRequest, signal: AbortSignal): Promise<void> {
147
+ try {
148
+ await sendRequest(request, signal);
149
+ } catch {
150
+ // Herdr reporting is best-effort and must not interrupt Pi.
151
+ }
152
+ }
153
+
154
+ function reportSession(sessionStartSource?: string): Promise<void> {
155
+ const sessionRef = currentSessionRef();
156
+ if (!sessionRef) return Promise.resolve();
157
+ return safeSend(
158
+ {
159
+ id: requestId("session"),
160
+ method: "pane.report_agent_session",
161
+ params: {
162
+ pane_id: environment.paneId,
163
+ source: SOURCE,
164
+ agent: "pi",
165
+ seq: nextReportSeq(),
166
+ session_start_source: sessionStartSource,
167
+ ...sessionRef,
168
+ },
169
+ },
170
+ sessionController.signal,
171
+ );
172
+ }
173
+
174
+ function stateRequest(state: QueuedState): HerdrRequest {
175
+ return {
176
+ id: requestId(),
177
+ method: "pane.report_agent",
178
+ params: withSessionRef({
179
+ pane_id: environment.paneId,
180
+ source: SOURCE,
181
+ agent: "pi",
182
+ state: state.state,
183
+ message: state.message,
184
+ seq: state.seq,
185
+ }),
186
+ };
187
+ }
188
+
189
+ function readMetadataSnapshot(ctx: ExtensionContext): HerdrMetadataSnapshot {
190
+ let session: string | undefined;
191
+ let contextUsagePercent: number | null | undefined;
192
+ try {
193
+ session = pi.getSessionName();
194
+ } catch {
195
+ // Metadata is best-effort and optional Pi fields can be unavailable.
196
+ }
197
+ try {
198
+ contextUsagePercent = ctx.getContextUsage()?.percent;
199
+ } catch {
200
+ // Clear unknown usage instead of retaining a stale percentage.
201
+ }
202
+ return createHerdrMetadataSnapshot({
203
+ model: ctx.model?.id,
204
+ provider: ctx.model?.provider,
205
+ thinking: ctx.thinkingLevel,
206
+ session,
207
+ contextUsagePercent,
208
+ });
209
+ }
210
+
211
+ function metadataRequest(metadata: QueuedMetadata): HerdrRequest {
212
+ return createHerdrMetadataRequest({
213
+ id: requestId(),
214
+ paneId: environment.paneId,
215
+ source: SOURCE,
216
+ seq: metadata.seq,
217
+ snapshot: metadata.snapshot,
218
+ });
219
+ }
220
+
221
+ async function drainStateQueue(): Promise<void> {
222
+ while (queuedState) {
223
+ const next = queuedState;
224
+ queuedState = undefined;
225
+ if (!next.signal.aborted) await safeSend(stateRequest(next), next.signal);
226
+ }
227
+ }
228
+
229
+ function queueState(state: AgentState, message?: string): void {
230
+ queuedState = {
231
+ state,
232
+ message,
233
+ seq: nextReportSeq(),
234
+ signal: sessionController.signal,
235
+ };
236
+ if (drainTask) return;
237
+ drainTask = drainStateQueue().finally(() => {
238
+ drainTask = undefined;
239
+ if (queuedState) queueState(queuedState.state, queuedState.message);
240
+ });
241
+ }
242
+
243
+ async function drainMetadataQueue(): Promise<void> {
244
+ while (queuedMetadata) {
245
+ const next = queuedMetadata;
246
+ queuedMetadata = undefined;
247
+ if (next.signal.aborted || next.generation !== sessionGeneration || !rootSession) {
248
+ continue;
249
+ }
250
+ await safeSend(metadataRequest(next), next.signal);
251
+ }
252
+ }
253
+
254
+ function startMetadataDrain(): void {
255
+ if (metadataDrainTask) return;
256
+ metadataDrainTask = drainMetadataQueue().finally(() => {
257
+ metadataDrainTask = undefined;
258
+ if (queuedMetadata) startMetadataDrain();
259
+ });
260
+ }
261
+
262
+ function scheduleMetadataRefresh(generation: number): void {
263
+ if (metadataRefreshTimer) clearTimeout(metadataRefreshTimer);
264
+ metadataRefreshTimer = setTimeout(() => {
265
+ metadataRefreshTimer = undefined;
266
+ if (
267
+ generation !== sessionGeneration ||
268
+ sessionController.signal.aborted ||
269
+ !rootSession ||
270
+ !lastMetadataSnapshot
271
+ ) {
272
+ return;
273
+ }
274
+ queueMetadata(lastMetadataSnapshot, true);
275
+ }, HERDR_METADATA_REFRESH_MS);
276
+ metadataRefreshTimer.unref?.();
277
+ }
278
+
279
+ function queueMetadata(snapshot: HerdrMetadataSnapshot, force = false): void {
280
+ if (!rootSession || sessionController.signal.aborted) return;
281
+ if (!force && herdrMetadataSnapshotsEqual(lastMetadataSnapshot, snapshot)) return;
282
+ lastMetadataSnapshot = snapshot;
283
+ queuedMetadata = {
284
+ snapshot,
285
+ seq: nextReportSeq(),
286
+ signal: sessionController.signal,
287
+ generation: sessionGeneration,
288
+ };
289
+ scheduleMetadataRefresh(sessionGeneration);
290
+ startMetadataDrain();
291
+ }
292
+
293
+ function owns(ctx: ExtensionContext): boolean {
294
+ return rootSession && ctx.sessionManager === activeSession;
295
+ }
296
+
297
+ function publishMetadata(ctx: ExtensionContext): void {
298
+ if (!owns(ctx)) return;
299
+ queueMetadata(readMetadataSnapshot(ctx));
300
+ }
301
+
302
+ function desiredState(): { state: AgentState; message?: string } {
303
+ if (blockedCount > 0) return { state: "blocked", message: blockedMessage };
304
+ if (agentActive) return { state: "working" };
305
+ return { state: "idle" };
306
+ }
307
+
308
+ function publishState(force = false): void {
309
+ const next = desiredState();
310
+ if (!force && next.state === lastState && next.message === lastMessage) return;
311
+ lastState = next.state;
312
+ lastMessage = next.message;
313
+ queueState(next.state, next.message);
314
+ }
315
+
316
+ pi.on("ui_prompt_start", (event, ctx) => {
317
+ if (!owns(ctx)) return;
318
+ blockedCount += 1;
319
+ blockedMessage = event.title?.trim() || event.kind;
320
+ publishState();
321
+ });
322
+
323
+ pi.on("ui_prompt_end", (_event, ctx) => {
324
+ if (!owns(ctx)) return;
325
+ blockedCount = Math.max(0, blockedCount - 1);
326
+ if (blockedCount === 0) blockedMessage = undefined;
327
+ publishState();
328
+ });
329
+
330
+ pi.on("session_start", async (event, ctx) => {
331
+ const generation = ++sessionGeneration;
332
+ const replaced = new DOMException("Herdr session replaced", "AbortError");
333
+ sessionController.abort(replaced);
334
+ shutdownClearController?.abort(replaced);
335
+ shutdownClearController = undefined;
336
+ if (metadataRefreshTimer) clearTimeout(metadataRefreshTimer);
337
+ metadataRefreshTimer = undefined;
338
+ queuedMetadata = undefined;
339
+ lastMetadataSnapshot = undefined;
340
+ sessionController = new AbortController();
341
+ activeSession = ctx.sessionManager;
342
+ rootSession = ctx.mode === "tui";
343
+ const widgetStart = widget.start(ctx);
344
+ agentActive = false;
345
+ blockedCount = 0;
346
+ blockedMessage = undefined;
347
+ lastState = undefined;
348
+ lastMessage = undefined;
349
+ if (!rootSession) {
350
+ await widgetStart;
351
+ return;
352
+ }
353
+
354
+ updateSessionRef(ctx);
355
+ const sessionReport = reportSession(event.reason);
356
+ publishMetadata(ctx);
357
+ await Promise.all([sessionReport, widgetStart]);
358
+ if (generation !== sessionGeneration || sessionController.signal.aborted || !rootSession) {
359
+ return;
360
+ }
361
+ agentActive = !ctx.isIdle();
362
+ publishState(true);
363
+ });
364
+
365
+ pi.on("agent_start", (_event, ctx) => {
366
+ if (!owns(ctx)) return;
367
+ updateSessionRef(ctx);
368
+ void reportSession();
369
+ agentActive = true;
370
+ publishState();
371
+ });
372
+
373
+ pi.on("agent_settled", (_event, ctx) => {
374
+ if (!owns(ctx)) return;
375
+ publishMetadata(ctx);
376
+ if (!ctx.isIdle()) return;
377
+ agentActive = false;
378
+ publishState();
379
+ });
380
+
381
+ pi.on("session_info_changed", (_event, ctx) => publishMetadata(ctx));
382
+ pi.on("model_select", (_event, ctx) => publishMetadata(ctx));
383
+ pi.on("thinking_level_select", (_event, ctx) => publishMetadata(ctx));
384
+ pi.on("session_compact", (_event, ctx) => publishMetadata(ctx));
385
+
386
+ pi.on("session_shutdown", async (_event, ctx) => {
387
+ if (ctx.sessionManager !== activeSession) {
388
+ await Promise.allSettled([widget.shutdown(ctx)]);
389
+ return;
390
+ }
391
+ if (shutdownTask && shutdownSession === ctx.sessionManager) {
392
+ await shutdownTask;
393
+ return;
394
+ }
395
+
396
+ const session = ctx.sessionManager;
397
+ const task = (async () => {
398
+ const shouldClearMetadata = rootSession;
399
+ const shutdownGeneration = ++sessionGeneration;
400
+ rootSession = false;
401
+ if (metadataRefreshTimer) clearTimeout(metadataRefreshTimer);
402
+ metadataRefreshTimer = undefined;
403
+ sessionController.abort(new DOMException("Herdr session shut down", "AbortError"));
404
+ queuedState = undefined;
405
+ queuedMetadata = undefined;
406
+ await Promise.allSettled([drainTask, metadataDrainTask, widget.shutdown(ctx)]);
407
+ const stillOwnsShutdown = shutdownGeneration === sessionGeneration && activeSession === session && !rootSession;
408
+ if (shouldClearMetadata && stillOwnsShutdown) {
409
+ const controller = new AbortController();
410
+ shutdownClearController = controller;
411
+ await safeSend(
412
+ createHerdrMetadataRequest({
413
+ id: requestId(),
414
+ paneId: environment.paneId,
415
+ source: SOURCE,
416
+ seq: nextReportSeq(),
417
+ snapshot: createHerdrMetadataClearSnapshot(),
418
+ }),
419
+ controller.signal,
420
+ );
421
+ if (shutdownClearController === controller) shutdownClearController = undefined;
422
+ }
423
+ if (shutdownGeneration !== sessionGeneration || activeSession !== session || rootSession) {
424
+ return;
425
+ }
426
+ lastMetadataSnapshot = undefined;
427
+ currentAgentSessionId = undefined;
428
+ currentAgentSessionPath = undefined;
429
+ activeSession = undefined;
430
+ })();
431
+ shutdownSession = session;
432
+ shutdownTask = task;
433
+ await task;
434
+ if (shutdownTask === task) {
435
+ shutdownTask = undefined;
436
+ shutdownSession = undefined;
437
+ }
438
+ });
439
+ };
447
440
  }
448
441
 
449
442
  export default function herdrAgentState(pi: ExtensionAPI): void {
450
- createHerdrAgentStateExtension()(pi);
443
+ createHerdrAgentStateExtension()(pi);
451
444
  }