@wierdbytes/pi-wierdr 0.0.0-stage → 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/herdr/index.ts ADDED
@@ -0,0 +1,187 @@
1
+ /**
2
+ * pi-wierdr's herdr side (formerly @wierdbytes/pi-herdr) — tells herdr which model, reasoning effort and
3
+ * context size a pi session runs with, as `agent.*` labels on its
4
+ * herdr-core terminal. Herdr's agent lists can then show
5
+ * `Opus 5.5 @high · 228k` under each pi, next to the status pi already
6
+ * reports over OSC 7501.
7
+ *
8
+ * It also folds the subscription limits every provider response carries
9
+ * (Claude, Codex) into herdr-core's `limits` document, so every herdr client
10
+ * can show them.
11
+ *
12
+ * And it runs bash commands (the model's and `!`) in herdr-core terminals
13
+ * under pi's, so herdr clients show each command live while it runs.
14
+ *
15
+ * Wiring only; the labels are built in `meta.ts`, written in `publisher.ts`;
16
+ * the limits are read in `limits.ts`, written in `limits-publisher.ts`; bash
17
+ * runs in `bash.ts`, wired in `bash-tool.ts`.
18
+ */
19
+
20
+ import { hostname } from "node:os";
21
+ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
22
+ import { registerHcBash } from "./bash-tool.ts";
23
+ import { type CacheEntry, type CacheWindow, cacheWindow, envRetention, type InflightRequest, WarmWatch } from "./cache.ts";
24
+ import { getDoc, hcTargetFromEnv, setDoc, setLabels } from "./hc.ts";
25
+ import {
26
+ isLimitStreamEvent,
27
+ type LimitReading,
28
+ LIMITS_DOC,
29
+ readingFromHeaders,
30
+ readingFromStreamEvent,
31
+ resolveAccount,
32
+ } from "./limits.ts";
33
+ import { LimitsPublisher } from "./limits-publisher.ts";
34
+ import { collectLabels, type MetaModel } from "./meta.ts";
35
+ import { LabelPublisher } from "./publisher.ts";
36
+ import { loadSettings } from "./settings.ts";
37
+ import { SubagentCounter } from "./subagents.ts";
38
+
39
+ export default function piHerdr(pi: ExtensionAPI) {
40
+ const target = hcTargetFromEnv();
41
+ if (!target) return;
42
+
43
+ // Every pi runs its commands in herdr terminals, `pi -p` and sub-agents too:
44
+ // each under the terminal it runs in.
45
+ const bash = loadSettings().bash && process.platform !== "win32" ? registerHcBash(pi, target) : undefined;
46
+
47
+ const publisher = new LabelPublisher((labels) => setLabels(target, labels));
48
+ const limits = new LimitsPublisher(
49
+ {
50
+ get: () => getDoc(target.socket, LIMITS_DOC),
51
+ set: (value, version) => setDoc(target.socket, LIMITS_DOC, value, version),
52
+ },
53
+ { host: hostname() },
54
+ );
55
+ const recordLimits = (reading: LimitReading | null) => {
56
+ if (reading) limits.record(reading, resolveAccount(reading));
57
+ };
58
+ // Every pi reads limits, not only the interactive one: `pi -p` runs and
59
+ // sub-agents spend the same subscription.
60
+ pi.on("after_provider_response", async (event) => {
61
+ try {
62
+ recordLimits(readingFromHeaders(event.headers));
63
+ } catch {
64
+ // A reading pi can't parse must not disturb the reply.
65
+ }
66
+ });
67
+ // Fires for every stream delta: only the two Codex events carry limits.
68
+ pi.on("provider_stream_event", (event) => {
69
+ if (!isLimitStreamEvent(event.data)) return;
70
+ try {
71
+ recordLimits(readingFromStreamEvent(event.data));
72
+ } catch {
73
+ // As above.
74
+ }
75
+ });
76
+ // pi-subagents emits from its own session_start, so listen from load on.
77
+ const subagents = new SubagentCounter(() => update());
78
+ subagents.start(pi.events);
79
+
80
+ /** The interactive session's latest ctx; unset until it starts, and for `pi -p` / RPC / sub-agents. */
81
+ let ctx: ExtensionContext | undefined;
82
+ let model: MetaModel | undefined;
83
+ /** A reply still streaming: it refreshed the prompt cache at its start. */
84
+ let inflight: InflightRequest | undefined;
85
+ /** The prompt cache last published, for the warming poll. */
86
+ let cache: CacheWindow | undefined;
87
+ const warm = new WarmWatch(() => {
88
+ update();
89
+ return cache?.until;
90
+ });
91
+
92
+ function update(next?: ExtensionContext, nextModel?: MetaModel): void {
93
+ if (!ctx) return;
94
+ if (next) ctx = next;
95
+ let context: { tokens: number | null; contextWindow: number } | undefined;
96
+ let session: string | undefined;
97
+ try {
98
+ context = ctx.getContextUsage();
99
+ // Only a session saved to a file can be opened again (`pi --session <id>`).
100
+ if (ctx.sessionManager.getSessionFile()) session = ctx.sessionManager.getSessionId();
101
+ model = nextModel ?? (ctx.model as MetaModel | undefined) ?? model;
102
+ const registry = ctx.modelRegistry;
103
+ cache = cacheWindow(
104
+ ctx.sessionManager.getBranch() as readonly CacheEntry[],
105
+ (provider, modelId) => registry?.find(provider, modelId)?.promptCache,
106
+ envRetention(),
107
+ inflight,
108
+ );
109
+ } catch {
110
+ // A replaced session's ctx goes stale; the next event brings a fresh one.
111
+ return;
112
+ }
113
+ publisher.publish(
114
+ collectLabels({
115
+ pid: process.pid,
116
+ model,
117
+ thinkingLevel: pi.getThinkingLevel?.(),
118
+ context,
119
+ subagents: subagents.count,
120
+ session,
121
+ cache,
122
+ }),
123
+ );
124
+ }
125
+
126
+ pi.on("session_start", async (_event, next) => {
127
+ // Only the interactive pi owns the terminal: `pi -p` runs, RPC hosts and
128
+ // sub-agents started inside this terminal must not overwrite its labels.
129
+ if (next.mode !== "tui") return;
130
+ ctx = next;
131
+ update();
132
+ await publisher.flush();
133
+ });
134
+ pi.on("model_select", async (event, next) => update(next, event.model as MetaModel));
135
+ pi.on("thinking_level_select", async (_event, next) => update(next));
136
+ pi.on("message_start", async (event, next) => {
137
+ const message = event.message as { role?: string; provider?: string; model?: string; timestamp?: number };
138
+ if (message.role !== "assistant" || !message.provider || !message.model) return;
139
+ inflight = {
140
+ at: typeof message.timestamp === "number" ? message.timestamp : Date.now(),
141
+ provider: message.provider,
142
+ model: message.model,
143
+ };
144
+ update(next);
145
+ });
146
+ // Every message, not only replies: a tool result or the person's prompt
147
+ // lands in the context the moment it ends, long before the turn does.
148
+ pi.on("message_end", async (event, next) => {
149
+ if (event.message.role === "assistant") inflight = undefined;
150
+ update(next);
151
+ });
152
+ pi.on("turn_end", async (_event, next) => update(next));
153
+ pi.on("agent_end", async (_event, next) => {
154
+ // An aborted stream must not leave a request in flight.
155
+ inflight = undefined;
156
+ update(next);
157
+ });
158
+ pi.on("agent_settled", async (_event, next) => update(next));
159
+ pi.on("session_compact", async (_event, next) => update(next));
160
+ pi.on("session_tree", async (_event, next) => update(next));
161
+ // pi is about to refresh the cache; its usage entry lands a moment later.
162
+ pi.on("cache_warming_decision", async () => {
163
+ if (ctx) warm.start();
164
+ });
165
+
166
+ pi.on("session_shutdown", async (event) => {
167
+ const owned = ctx !== undefined;
168
+ ctx = undefined;
169
+ inflight = undefined;
170
+ warm.stop();
171
+ if (event.reason === "quit") {
172
+ subagents.dispose();
173
+ // The last reading is worth a moment; never more than a second.
174
+ await Promise.race([
175
+ Promise.all([limits.flush(), bash?.shutdown(1000)]),
176
+ new Promise((resolve) => setTimeout(resolve, 1000).unref?.()),
177
+ ]);
178
+ limits.cancel();
179
+ if (owned) await publisher.clear();
180
+ return;
181
+ }
182
+ // Switching sessions or reloading: the next session republishes at its
183
+ // start, so leave the labels in place instead of flickering.
184
+ subagents.reset();
185
+ publisher.cancel();
186
+ });
187
+ }
@@ -0,0 +1,118 @@
1
+ /**
2
+ * Writes the limits pi reads from provider responses into herdr-core's
3
+ * `limits` document, cheaply and without losing anyone's writes:
4
+ *
5
+ * - every reading is written, even with the same numbers: `at` says when
6
+ * a provider last confirmed them, so readers tell live data from stale;
7
+ * - readings inside the debounce window go out as one write;
8
+ * - every write reads the document, folds into it and writes it back at
9
+ * the version it read; when another pi wrote in between, it reads again
10
+ * and retries;
11
+ * - a failed write is dropped, not retried: the next response carries a
12
+ * fresh reading anyway.
13
+ *
14
+ * Never throws and never blocks pi: hooks only queue.
15
+ */
16
+
17
+ import type { Doc } from "./hc.ts";
18
+ import {
19
+ asLimitsDoc,
20
+ foldReading,
21
+ type LimitAccount,
22
+ type LimitReading,
23
+ type LimitsDoc,
24
+ } from "./limits.ts";
25
+
26
+ export interface DocStore {
27
+ get(): Promise<Doc | undefined>;
28
+ /** The new version, `"conflict"` when the document moved on, undefined on failure. */
29
+ set(value: LimitsDoc, version: number): Promise<number | "conflict" | undefined>;
30
+ }
31
+
32
+ export interface LimitsPublisherOptions {
33
+ debounceMs?: number;
34
+ /** Writes tried per flush before giving up on conflicts. */
35
+ attempts?: number;
36
+ /** The machine name stored with each reading. */
37
+ host?: string;
38
+ now?: () => number;
39
+ }
40
+
41
+ interface Pending {
42
+ reading: LimitReading;
43
+ account: LimitAccount;
44
+ at: number;
45
+ }
46
+
47
+ export class LimitsPublisher {
48
+ private pending: Pending[] = [];
49
+ private timer: ReturnType<typeof setTimeout> | undefined;
50
+ private draining: Promise<void> | undefined;
51
+ private again = false;
52
+ private readonly debounceMs: number;
53
+ private readonly attempts: number;
54
+ private readonly now: () => number;
55
+
56
+ constructor(
57
+ private readonly store: DocStore,
58
+ private readonly options: LimitsPublisherOptions = {},
59
+ ) {
60
+ this.debounceMs = options.debounceMs ?? 500;
61
+ this.attempts = options.attempts ?? 5;
62
+ this.now = options.now ?? Date.now;
63
+ }
64
+
65
+ /** Queue a reading; it is written within the debounce window. */
66
+ record(reading: LimitReading, account: LimitAccount): void {
67
+ this.pending.push({ reading, account, at: this.now() });
68
+ if (this.timer) return;
69
+ this.timer = setTimeout(() => {
70
+ this.timer = undefined;
71
+ void this.flush();
72
+ }, this.debounceMs);
73
+ this.timer.unref?.();
74
+ }
75
+
76
+ /** Write what is queued now. Resolves once it landed or the write failed. */
77
+ flush(): Promise<void> {
78
+ if (this.timer) {
79
+ clearTimeout(this.timer);
80
+ this.timer = undefined;
81
+ }
82
+ if (this.draining) {
83
+ this.again = true;
84
+ return this.draining;
85
+ }
86
+ this.draining = this.drain().finally(() => {
87
+ this.draining = undefined;
88
+ });
89
+ return this.draining;
90
+ }
91
+
92
+ /** Drop what is queued (pi is quitting and can't wait). */
93
+ cancel(): void {
94
+ if (this.timer) clearTimeout(this.timer);
95
+ this.timer = undefined;
96
+ this.pending = [];
97
+ }
98
+
99
+ private async drain(): Promise<void> {
100
+ do {
101
+ this.again = false;
102
+ const batch = this.pending;
103
+ this.pending = [];
104
+ if (batch.length) await this.write(batch).catch(() => undefined);
105
+ } while (this.again);
106
+ }
107
+
108
+ private async write(batch: Pending[]): Promise<void> {
109
+ for (let attempt = 0; attempt < this.attempts; attempt++) {
110
+ const current = await this.store.get();
111
+ if (!current) return;
112
+ let doc = asLimitsDoc(current.value);
113
+ for (const p of batch) doc = foldReading(doc, p.reading, p.account, Math.floor(p.at / 1000), this.options.host);
114
+ const result = await this.store.set(doc, current.version);
115
+ if (result !== "conflict") return;
116
+ }
117
+ }
118
+ }