@narumitw/pi-herdr 0.0.1 โ 0.1.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.
- package/README.md +38 -2
- package/package.json +1 -1
- package/skills/herdr/SKILL.md +2 -2
- package/src/herdr-agent-state.ts +191 -15
- package/src/herdr-metadata.ts +87 -0
- package/src/herdr-widget.ts +7 -7
package/README.md
CHANGED
|
@@ -7,6 +7,7 @@ Connect Pi's interactive lifecycle to Herdr and bundle the operating guidance ne
|
|
|
7
7
|
## โจ Features
|
|
8
8
|
|
|
9
9
|
- Reports Pi session identity and `working`, `blocked`, and `idle` lifecycle states to the current Herdr pane.
|
|
10
|
+
- Publishes bounded `model`, `provider`, `thinking`, `session`, and `context_usage` tokens for Herdr sidebar rows.
|
|
10
11
|
- Shows recognized sibling agents from the current Herdr workspace in a passive widget above Pi's editor.
|
|
11
12
|
- Updates the widget from Herdr pane lifecycle and agent-status events without polling the CLI.
|
|
12
13
|
- Coalesces rapid state changes and retries short-lived local socket failures without interrupting Pi.
|
|
@@ -65,10 +66,40 @@ Local socket delivery is best-effort.
|
|
|
65
66
|
A failed request is retried once with bounded timeouts, and reporting failures never stop Pi.
|
|
66
67
|
Session shutdown aborts in-flight reporting and prevents stale session work from publishing later state.
|
|
67
68
|
|
|
69
|
+
## ๐ท๏ธ Pane metadata
|
|
70
|
+
|
|
71
|
+
The extension publishes only the `model`, `provider`, `thinking`, `session`, and `context_usage` token keys through `pane.report_metadata` under the `herdr:pi` source.
|
|
72
|
+
`model` and `provider` come from Pi's selected model, `thinking` comes from Pi's effective Thinking level, and `session` comes only from Pi's explicit session display name.
|
|
73
|
+
`context_usage` is Pi's current context percentage rounded to the nearest whole percent.
|
|
74
|
+
Every report is a full five-key patch, and an unavailable value is sent as JSON `null` so old data is cleared instead of retained.
|
|
75
|
+
Values are stripped of terminal controls, trimmed, and limited to 80 Unicode characters before crossing the socket.
|
|
76
|
+
The extension never publishes prompts, conversation text, tool arguments, credentials, raw session paths, or inferred session titles as metadata tokens.
|
|
77
|
+
It also never sets Herdr's pane `title`, `display_agent`, `state_labels`, agent lifecycle state, or session restore fields through metadata.
|
|
78
|
+
|
|
79
|
+
Metadata is evaluated after `session_start`, `session_info_changed`, `model_select`, `thinking_level_select`, `agent_settled`, and successful `session_compact` events.
|
|
80
|
+
Unchanged event snapshots are suppressed, rapid changes are coalesced, and the latest unchanged snapshot is refreshed no more often than every 30 minutes.
|
|
81
|
+
Each token has a one-hour TTL, so data from a crashed Pi process expires without steady socket traffic.
|
|
82
|
+
Orderly shutdown sends one best-effort five-key clear patch, while abrupt shutdown and failed clears fall back to the TTL.
|
|
83
|
+
Metadata uses the lifecycle reporter's monotonic sequence allocator and bounded best-effort sender, so older delayed reports cannot replace newer accepted values and socket failures never interrupt Pi.
|
|
84
|
+
|
|
85
|
+
Herdr custom pane tokens use a `$name` row entry.
|
|
86
|
+
For example, this Herdr configuration displays Pi's model context without replacing pane labels or agent identity:
|
|
87
|
+
|
|
88
|
+
```toml
|
|
89
|
+
[ui.sidebar.agents]
|
|
90
|
+
rows = [
|
|
91
|
+
["state_icon", "agent"],
|
|
92
|
+
["$provider", "$model", "$thinking"],
|
|
93
|
+
["$session", "$context_usage"],
|
|
94
|
+
]
|
|
95
|
+
```
|
|
96
|
+
|
|
68
97
|
## ๐ Agent widget
|
|
69
98
|
|
|
70
99
|
The widget lists only recognized agents in the current Herdr workspace and excludes the pane running the current Pi session.
|
|
71
100
|
Each row presents state, agent, pane, and workspace in that order, using theme hierarchy instead of repeating field labels.
|
|
101
|
+
State icons follow Herdr's distinct static symbols: `ร` blocked, `โ` working, `โ` done, `โ` idle, and `ยท` unknown.
|
|
102
|
+
Pi theme roles map blocked to `error`, working to `warning`, done to `accent`, idle to `success`, and unknown to `dim` without hard-coded terminal colors.
|
|
72
103
|
Agent identity prefers the name assigned by `herdr agent rename`, then Herdr display metadata, and finally the detected agent kind.
|
|
73
104
|
Pane identity uses its label or metadata title with a short pane ID, while workspace identity uses its label with a short workspace ID.
|
|
74
105
|
Terminal titles are not used as agent identity.
|
|
@@ -84,7 +115,8 @@ Session replacement and shutdown abort the subscription, pending requests, recon
|
|
|
84
115
|
## ๐ Security and privacy
|
|
85
116
|
|
|
86
117
|
The extension connects only to the Unix socket or Windows named pipe provided by `HERDR_SOCKET_PATH`.
|
|
87
|
-
|
|
118
|
+
Lifecycle reporting sends the current Herdr pane ID, Pi session path or ID, lifecycle state, session start reason, and blocked label to that endpoint.
|
|
119
|
+
Metadata reporting sends the current Herdr pane ID plus only the selected model ID, provider ID, effective Thinking level, explicit Pi session name, and rounded context-usage percentage.
|
|
88
120
|
For the widget, it reads the canonical current pane, current workspace metadata, current workspace pane list, and session agent list, then subscribes to pane creation, closure, movement, exit, agent detection, and agent-status events.
|
|
89
121
|
The session agent list can contain agent metadata from other workspaces, but the extension retains names only for panes in the current workspace list.
|
|
90
122
|
Widget fields can include workspace, tab, pane, terminal, agent, display, name, title, label, state-label, and lifecycle identifiers supplied by Herdr.
|
|
@@ -95,10 +127,11 @@ The package does not authenticate the endpoint, so trust the environment that la
|
|
|
95
127
|
The bundled skill can direct Pi to inspect terminals, create panes, start agents, send input, and run commands through the local `herdr` CLI.
|
|
96
128
|
Those commands execute with the same user permissions as Pi and can affect live terminal sessions.
|
|
97
129
|
The skill requires an explicit user request involving Herdr and stops when `HERDR_ENV` is not `1`.
|
|
130
|
+
It treats a startup-blocked agent as not ready, refuses to prompt an already blocked agent, requires inspecting the blocked UI, and requires asking the user before answering an approval or question dialog.
|
|
98
131
|
|
|
99
132
|
## ๐ง Limitations
|
|
100
133
|
|
|
101
|
-
-
|
|
134
|
+
- Lifecycle reporting, metadata reporting, and the agent widget are disabled in RPC, JSON, and print modes.
|
|
102
135
|
- The widget has no settings for placement, workspace scope, visibility, or row count.
|
|
103
136
|
- The widget cannot show blocked prompt text because Herdr does not expose it through public pane responses.
|
|
104
137
|
- Herdr exposes no rename event, so agent and pane renames appear after the next topology refresh, reconnect, Pi `/reload`, or session start rather than immediately.
|
|
@@ -116,13 +149,16 @@ packages/pi-herdr/
|
|
|
116
149
|
โ โโโ index.ts # Thin Pi entrypoint
|
|
117
150
|
โ โโโ herdr-agent-state.ts # Pi lifecycle and integration ownership
|
|
118
151
|
โ โโโ herdr-client.ts # Bounded Herdr socket transport
|
|
152
|
+
โ โโโ herdr-metadata.ts # Token normalization and request helpers
|
|
119
153
|
โ โโโ herdr-observer.ts # Read-only event subscription lifecycle
|
|
120
154
|
โ โโโ herdr-protocol.ts # Narrow response and event validation
|
|
121
155
|
โ โโโ herdr-widget.ts # Agent state model and presentation
|
|
122
156
|
โโโ test/
|
|
123
157
|
โ โโโ herdr-agent-state.test.ts
|
|
124
158
|
โ โโโ herdr-client.test.ts
|
|
159
|
+
โ โโโ herdr-metadata.test.ts
|
|
125
160
|
โ โโโ herdr-observer.test.ts
|
|
161
|
+
โ โโโ herdr-skill.test.ts
|
|
126
162
|
โ โโโ herdr-widget.test.ts
|
|
127
163
|
โโโ package.json # Pi extension and skill declarations
|
|
128
164
|
โโโ tsconfig.json
|
package/package.json
CHANGED
package/skills/herdr/SKILL.md
CHANGED
|
@@ -117,7 +117,7 @@ Use the kind requested by the user. Run `herdr agent` to inspect the installed k
|
|
|
117
117
|
herdr agent start reviewer --kind codex --pane <returned-pane-id> -- <agent-args...>
|
|
118
118
|
```
|
|
119
119
|
|
|
120
|
-
`agent start` returns only after Herdr detects the expected agent in the same pane and considers it ready for interactive input.
|
|
120
|
+
A successful `agent start` returns only after Herdr detects the expected agent in the same pane and considers it ready for interactive input. If the agent is blocked during startup, the command returns `agent_not_ready` immediately but keeps the name available for `agent read` and `agent send-keys`. Wait until the agent becomes idle before prompting it. Startup defaults to a 30-second timeout.
|
|
121
121
|
|
|
122
122
|
Submit work through the agent surface:
|
|
123
123
|
|
|
@@ -125,7 +125,7 @@ Submit work through the agent surface:
|
|
|
125
125
|
herdr agent prompt reviewer "Review the current diff and report only actionable findings." --wait --timeout 120000
|
|
126
126
|
```
|
|
127
127
|
|
|
128
|
-
`agent prompt`
|
|
128
|
+
`agent prompt` honors the pane's live bracketed-paste mode and sends text followed by encoded Enter after a short delay. It rejects an agent already waiting at an approval or question dialog with `agent_blocked` before sending any input. Inspect the blocked UI and ask the user before answering it. For normal agent work, `--wait` is enough: it waits for the first settled `idle`, `done`, or `blocked` state. Do not repeat those defaults with `--until`.
|
|
129
129
|
|
|
130
130
|
A prompt sent from a non-working state must produce an observed lifecycle change within five seconds. Otherwise Herdr returns `agent_prompt_stalled` instead of waiting indefinitely. This wait tracks lifecycle state, not an individual turn; if the agent is already working, completion of the active turn may satisfy it.
|
|
131
131
|
|
package/src/herdr-agent-state.ts
CHANGED
|
@@ -1,6 +1,14 @@
|
|
|
1
1
|
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
|
+
import {
|
|
5
|
+
createHerdrMetadataClearSnapshot,
|
|
6
|
+
createHerdrMetadataRequest,
|
|
7
|
+
createHerdrMetadataSnapshot,
|
|
8
|
+
HERDR_METADATA_REFRESH_MS,
|
|
9
|
+
type HerdrMetadataSnapshot,
|
|
10
|
+
herdrMetadataSnapshotsEqual,
|
|
11
|
+
} from "./herdr-metadata.js";
|
|
4
12
|
import { createHerdrWidgetObserver, type HerdrWidgetObserver } from "./herdr-observer.js";
|
|
5
13
|
|
|
6
14
|
const SOURCE = "herdr:pi";
|
|
@@ -20,6 +28,13 @@ interface QueuedState {
|
|
|
20
28
|
signal: AbortSignal;
|
|
21
29
|
}
|
|
22
30
|
|
|
31
|
+
interface QueuedMetadata {
|
|
32
|
+
snapshot: HerdrMetadataSnapshot;
|
|
33
|
+
seq: number;
|
|
34
|
+
signal: AbortSignal;
|
|
35
|
+
generation: number;
|
|
36
|
+
}
|
|
37
|
+
|
|
23
38
|
export interface HerdrAgentStateOptions {
|
|
24
39
|
environment?: HerdrEnvironment;
|
|
25
40
|
now?: () => number;
|
|
@@ -77,6 +92,7 @@ export function createHerdrAgentStateExtension(
|
|
|
77
92
|
|
|
78
93
|
let sessionGeneration = 0;
|
|
79
94
|
let sessionController = new AbortController();
|
|
95
|
+
let activeSession: ExtensionContext["sessionManager"] | undefined;
|
|
80
96
|
let currentAgentSessionId: string | undefined;
|
|
81
97
|
let currentAgentSessionPath: string | undefined;
|
|
82
98
|
let agentActive = false;
|
|
@@ -87,6 +103,13 @@ export function createHerdrAgentStateExtension(
|
|
|
87
103
|
let rootSession = false;
|
|
88
104
|
let queuedState: QueuedState | undefined;
|
|
89
105
|
let drainTask: Promise<void> | undefined;
|
|
106
|
+
let queuedMetadata: QueuedMetadata | undefined;
|
|
107
|
+
let metadataDrainTask: Promise<void> | undefined;
|
|
108
|
+
let lastMetadataSnapshot: HerdrMetadataSnapshot | undefined;
|
|
109
|
+
let metadataRefreshTimer: ReturnType<typeof setTimeout> | undefined;
|
|
110
|
+
let shutdownClearController: AbortController | undefined;
|
|
111
|
+
let shutdownSession: ExtensionContext["sessionManager"] | undefined;
|
|
112
|
+
let shutdownTask: Promise<void> | undefined;
|
|
90
113
|
|
|
91
114
|
function requestId(kind?: "session"): string {
|
|
92
115
|
const segment = kind ? `${kind}:` : "";
|
|
@@ -163,6 +186,38 @@ export function createHerdrAgentStateExtension(
|
|
|
163
186
|
};
|
|
164
187
|
}
|
|
165
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
|
+
|
|
166
221
|
async function drainStateQueue(): Promise<void> {
|
|
167
222
|
while (queuedState) {
|
|
168
223
|
const next = queuedState;
|
|
@@ -185,6 +240,65 @@ export function createHerdrAgentStateExtension(
|
|
|
185
240
|
});
|
|
186
241
|
}
|
|
187
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
|
+
|
|
188
302
|
function desiredState(): { state: AgentState; message?: string } {
|
|
189
303
|
if (blockedCount > 0) return { state: "blocked", message: blockedMessage };
|
|
190
304
|
if (agentActive) return { state: "working" };
|
|
@@ -199,15 +313,15 @@ export function createHerdrAgentStateExtension(
|
|
|
199
313
|
queueState(next.state, next.message);
|
|
200
314
|
}
|
|
201
315
|
|
|
202
|
-
pi.on("ui_prompt_start", (event) => {
|
|
203
|
-
if (!
|
|
316
|
+
pi.on("ui_prompt_start", (event, ctx) => {
|
|
317
|
+
if (!owns(ctx)) return;
|
|
204
318
|
blockedCount += 1;
|
|
205
319
|
blockedMessage = event.title?.trim() || event.kind;
|
|
206
320
|
publishState();
|
|
207
321
|
});
|
|
208
322
|
|
|
209
|
-
pi.on("ui_prompt_end", () => {
|
|
210
|
-
if (!
|
|
323
|
+
pi.on("ui_prompt_end", (_event, ctx) => {
|
|
324
|
+
if (!owns(ctx)) return;
|
|
211
325
|
blockedCount = Math.max(0, blockedCount - 1);
|
|
212
326
|
if (blockedCount === 0) blockedMessage = undefined;
|
|
213
327
|
publishState();
|
|
@@ -215,8 +329,16 @@ export function createHerdrAgentStateExtension(
|
|
|
215
329
|
|
|
216
330
|
pi.on("session_start", async (event, ctx) => {
|
|
217
331
|
const generation = ++sessionGeneration;
|
|
218
|
-
|
|
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;
|
|
219
340
|
sessionController = new AbortController();
|
|
341
|
+
activeSession = ctx.sessionManager;
|
|
220
342
|
rootSession = ctx.mode === "tui";
|
|
221
343
|
if (rootSession) widgetObserver.start(ctx);
|
|
222
344
|
agentActive = false;
|
|
@@ -227,7 +349,9 @@ export function createHerdrAgentStateExtension(
|
|
|
227
349
|
if (!rootSession) return;
|
|
228
350
|
|
|
229
351
|
updateSessionRef(ctx);
|
|
230
|
-
|
|
352
|
+
const sessionReport = reportSession(event.reason);
|
|
353
|
+
publishMetadata(ctx);
|
|
354
|
+
await sessionReport;
|
|
231
355
|
if (generation !== sessionGeneration || sessionController.signal.aborted || !rootSession) {
|
|
232
356
|
return;
|
|
233
357
|
}
|
|
@@ -236,7 +360,7 @@ export function createHerdrAgentStateExtension(
|
|
|
236
360
|
});
|
|
237
361
|
|
|
238
362
|
pi.on("agent_start", (_event, ctx) => {
|
|
239
|
-
if (!
|
|
363
|
+
if (!owns(ctx)) return;
|
|
240
364
|
updateSessionRef(ctx);
|
|
241
365
|
void reportSession();
|
|
242
366
|
agentActive = true;
|
|
@@ -244,19 +368,71 @@ export function createHerdrAgentStateExtension(
|
|
|
244
368
|
});
|
|
245
369
|
|
|
246
370
|
pi.on("agent_settled", (_event, ctx) => {
|
|
247
|
-
if (!
|
|
371
|
+
if (!owns(ctx)) return;
|
|
372
|
+
publishMetadata(ctx);
|
|
373
|
+
if (!ctx.isIdle()) return;
|
|
248
374
|
agentActive = false;
|
|
249
375
|
publishState();
|
|
250
376
|
});
|
|
251
377
|
|
|
378
|
+
pi.on("session_info_changed", (_event, ctx) => publishMetadata(ctx));
|
|
379
|
+
pi.on("model_select", (_event, ctx) => publishMetadata(ctx));
|
|
380
|
+
pi.on("thinking_level_select", (_event, ctx) => publishMetadata(ctx));
|
|
381
|
+
pi.on("session_compact", (_event, ctx) => publishMetadata(ctx));
|
|
382
|
+
|
|
252
383
|
pi.on("session_shutdown", async (_event, ctx) => {
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
384
|
+
if (ctx.sessionManager !== activeSession) {
|
|
385
|
+
await Promise.allSettled([widgetObserver.shutdown(ctx)]);
|
|
386
|
+
return;
|
|
387
|
+
}
|
|
388
|
+
if (shutdownTask && shutdownSession === ctx.sessionManager) {
|
|
389
|
+
await shutdownTask;
|
|
390
|
+
return;
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
const session = ctx.sessionManager;
|
|
394
|
+
const task = (async () => {
|
|
395
|
+
const shouldClearMetadata = rootSession;
|
|
396
|
+
const shutdownGeneration = ++sessionGeneration;
|
|
397
|
+
rootSession = false;
|
|
398
|
+
if (metadataRefreshTimer) clearTimeout(metadataRefreshTimer);
|
|
399
|
+
metadataRefreshTimer = undefined;
|
|
400
|
+
sessionController.abort(new DOMException("Herdr session shut down", "AbortError"));
|
|
401
|
+
queuedState = undefined;
|
|
402
|
+
queuedMetadata = undefined;
|
|
403
|
+
await Promise.allSettled([drainTask, metadataDrainTask, widgetObserver.shutdown(ctx)]);
|
|
404
|
+
const stillOwnsShutdown =
|
|
405
|
+
shutdownGeneration === sessionGeneration && activeSession === session && !rootSession;
|
|
406
|
+
if (shouldClearMetadata && stillOwnsShutdown) {
|
|
407
|
+
const controller = new AbortController();
|
|
408
|
+
shutdownClearController = controller;
|
|
409
|
+
await safeSend(
|
|
410
|
+
createHerdrMetadataRequest({
|
|
411
|
+
id: requestId(),
|
|
412
|
+
paneId: environment.paneId,
|
|
413
|
+
source: SOURCE,
|
|
414
|
+
seq: nextReportSeq(),
|
|
415
|
+
snapshot: createHerdrMetadataClearSnapshot(),
|
|
416
|
+
}),
|
|
417
|
+
controller.signal,
|
|
418
|
+
);
|
|
419
|
+
if (shutdownClearController === controller) shutdownClearController = undefined;
|
|
420
|
+
}
|
|
421
|
+
if (shutdownGeneration !== sessionGeneration || activeSession !== session || rootSession) {
|
|
422
|
+
return;
|
|
423
|
+
}
|
|
424
|
+
lastMetadataSnapshot = undefined;
|
|
425
|
+
currentAgentSessionId = undefined;
|
|
426
|
+
currentAgentSessionPath = undefined;
|
|
427
|
+
activeSession = undefined;
|
|
428
|
+
})();
|
|
429
|
+
shutdownSession = session;
|
|
430
|
+
shutdownTask = task;
|
|
431
|
+
await task;
|
|
432
|
+
if (shutdownTask === task) {
|
|
433
|
+
shutdownTask = undefined;
|
|
434
|
+
shutdownSession = undefined;
|
|
435
|
+
}
|
|
260
436
|
});
|
|
261
437
|
};
|
|
262
438
|
}
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
import { sanitizeTerminalText } from "@narumitw/pi-tui-kit/terminal-text";
|
|
2
|
+
import type { HerdrRequest } from "./herdr-client.js";
|
|
3
|
+
|
|
4
|
+
export const HERDR_METADATA_TOKEN_KEYS = [
|
|
5
|
+
"model",
|
|
6
|
+
"provider",
|
|
7
|
+
"thinking",
|
|
8
|
+
"session",
|
|
9
|
+
"context_usage",
|
|
10
|
+
] as const;
|
|
11
|
+
|
|
12
|
+
export type HerdrMetadataTokenKey = (typeof HERDR_METADATA_TOKEN_KEYS)[number];
|
|
13
|
+
export type HerdrMetadataSnapshot = Readonly<Record<HerdrMetadataTokenKey, string | null>>;
|
|
14
|
+
|
|
15
|
+
export const HERDR_METADATA_MAX_CHARACTERS = 80;
|
|
16
|
+
export const HERDR_METADATA_TTL_MS = 60 * 60 * 1000;
|
|
17
|
+
export const HERDR_METADATA_REFRESH_MS = 30 * 60 * 1000;
|
|
18
|
+
|
|
19
|
+
export interface HerdrMetadataInputs {
|
|
20
|
+
model?: unknown;
|
|
21
|
+
provider?: unknown;
|
|
22
|
+
thinking?: unknown;
|
|
23
|
+
session?: unknown;
|
|
24
|
+
contextUsagePercent?: unknown;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export interface HerdrMetadataRequestOptions {
|
|
28
|
+
id: string;
|
|
29
|
+
paneId: string;
|
|
30
|
+
source: string;
|
|
31
|
+
seq: number;
|
|
32
|
+
snapshot: HerdrMetadataSnapshot;
|
|
33
|
+
ttlMs?: number;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export function normalizeHerdrMetadataValue(value: unknown): string | null {
|
|
37
|
+
if (typeof value !== "string") return null;
|
|
38
|
+
const normalized = sanitizeTerminalText(value).trim();
|
|
39
|
+
if (normalized.length === 0) return null;
|
|
40
|
+
return [...normalized].slice(0, HERDR_METADATA_MAX_CHARACTERS).join("");
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
export function formatContextUsagePercent(value: unknown): string | null {
|
|
44
|
+
if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return null;
|
|
45
|
+
return `${Math.round(value)}%`;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
export function createHerdrMetadataSnapshot(inputs: HerdrMetadataInputs): HerdrMetadataSnapshot {
|
|
49
|
+
return Object.freeze({
|
|
50
|
+
model: normalizeHerdrMetadataValue(inputs.model),
|
|
51
|
+
provider: normalizeHerdrMetadataValue(inputs.provider),
|
|
52
|
+
thinking: normalizeHerdrMetadataValue(inputs.thinking),
|
|
53
|
+
session: normalizeHerdrMetadataValue(inputs.session),
|
|
54
|
+
context_usage: formatContextUsagePercent(inputs.contextUsagePercent),
|
|
55
|
+
});
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
export function createHerdrMetadataClearSnapshot(): HerdrMetadataSnapshot {
|
|
59
|
+
return Object.freeze({
|
|
60
|
+
model: null,
|
|
61
|
+
provider: null,
|
|
62
|
+
thinking: null,
|
|
63
|
+
session: null,
|
|
64
|
+
context_usage: null,
|
|
65
|
+
});
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
export function herdrMetadataSnapshotsEqual(
|
|
69
|
+
left: HerdrMetadataSnapshot | undefined,
|
|
70
|
+
right: HerdrMetadataSnapshot,
|
|
71
|
+
): boolean {
|
|
72
|
+
return left !== undefined && HERDR_METADATA_TOKEN_KEYS.every((key) => left[key] === right[key]);
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
export function createHerdrMetadataRequest(options: HerdrMetadataRequestOptions): HerdrRequest {
|
|
76
|
+
return {
|
|
77
|
+
id: options.id,
|
|
78
|
+
method: "pane.report_metadata",
|
|
79
|
+
params: {
|
|
80
|
+
pane_id: options.paneId,
|
|
81
|
+
source: options.source,
|
|
82
|
+
seq: options.seq,
|
|
83
|
+
tokens: { ...options.snapshot },
|
|
84
|
+
ttl_ms: options.ttlMs ?? HERDR_METADATA_TTL_MS,
|
|
85
|
+
},
|
|
86
|
+
};
|
|
87
|
+
}
|
package/src/herdr-widget.ts
CHANGED
|
@@ -225,13 +225,13 @@ export class HerdrWidgetModel {
|
|
|
225
225
|
function stateStyle(theme: Theme, state: HerdrAgentStatus, text: string): string {
|
|
226
226
|
switch (state) {
|
|
227
227
|
case "blocked":
|
|
228
|
-
return theme.fg("
|
|
228
|
+
return theme.fg("error", text);
|
|
229
229
|
case "done":
|
|
230
|
-
return theme.fg("success", text);
|
|
231
|
-
case "working":
|
|
232
230
|
return theme.fg("accent", text);
|
|
231
|
+
case "working":
|
|
232
|
+
return theme.fg("warning", text);
|
|
233
233
|
case "idle":
|
|
234
|
-
return theme.fg("
|
|
234
|
+
return theme.fg("success", text);
|
|
235
235
|
case "unknown":
|
|
236
236
|
return theme.fg("dim", text);
|
|
237
237
|
}
|
|
@@ -240,15 +240,15 @@ function stateStyle(theme: Theme, state: HerdrAgentStatus, text: string): string
|
|
|
240
240
|
function stateSymbol(state: HerdrAgentStatus): string {
|
|
241
241
|
switch (state) {
|
|
242
242
|
case "blocked":
|
|
243
|
-
return "
|
|
243
|
+
return "ร";
|
|
244
244
|
case "done":
|
|
245
245
|
return "โ";
|
|
246
246
|
case "working":
|
|
247
|
-
return "
|
|
247
|
+
return "โ";
|
|
248
248
|
case "idle":
|
|
249
249
|
return "โ";
|
|
250
250
|
case "unknown":
|
|
251
|
-
return "
|
|
251
|
+
return "ยท";
|
|
252
252
|
}
|
|
253
253
|
}
|
|
254
254
|
|