@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/bash.ts ADDED
@@ -0,0 +1,427 @@
1
+ /**
2
+ * pi's bash, run through herdr-core: every command gets a terminal of its own
3
+ * (`terminal.run`, what `hc run` does), a child of pi's, so any herdr client
4
+ * shows it under pi while it runs: the command as the terminal's title, its
5
+ * command line and output on the screen. The terminal is removed once the
6
+ * command ends.
7
+ *
8
+ * The command runs as with pi's own bash: stdin is /dev/null, stdout and
9
+ * stderr are one pipe, here into `tee`, which prints to the terminal and to a
10
+ * file pi reads. So pi gets the exact output, byte for byte, however much of
11
+ * it there is, and the exit code the command ended with; nothing ever waits
12
+ * on a pager or a prompt.
13
+ *
14
+ * Commands that call `hc wait` run in pi's own process as before: in a
15
+ * terminal of their own they would count among the children they wait for.
16
+ * So does every command herdr-core can't start a terminal for.
17
+ */
18
+
19
+ import { constants } from "node:fs";
20
+ import { access, type FileHandle, mkdtemp, open, rm, writeFile } from "node:fs/promises";
21
+ import { tmpdir } from "node:os";
22
+ import { join } from "node:path";
23
+ import type { BashOperations } from "@earendil-works/pi-coding-agent";
24
+ import { type HcTarget, rpc } from "./hc.ts";
25
+
26
+ /** Who ran the command: the model's bash tool or the person's `!` / `!!`. */
27
+ export type BashSource = "tool" | "user";
28
+
29
+ /**
30
+ * The label marking a terminal as one of pi's bash commands; its value is the
31
+ * {@link BashSource}. Named before pi-herdr became pi-wierdr, and kept for mods
32
+ * that read it.
33
+ */
34
+ export const BASH_LABEL = "pi-herdr.bash";
35
+
36
+ /** Variables herdr-core sets for every terminal itself: its identity, not pi's. */
37
+ const OWN_ENV = new Set([
38
+ "TERM",
39
+ "TERM_PROGRAM",
40
+ "TERM_PROGRAM_VERSION",
41
+ "COLORTERM",
42
+ "HC_TERMINAL_ID",
43
+ "HC_TERMINAL_SOCKET",
44
+ "HC_SCOPE",
45
+ "PWD",
46
+ "OLDPWD",
47
+ "SHLVL",
48
+ "_",
49
+ ]);
50
+
51
+ /** The command's environment for `terminal.run`: what pi would give it, minus the terminal's own identity. */
52
+ export function terminalEnv(env: NodeJS.ProcessEnv): Record<string, string> {
53
+ const out: Record<string, string> = {};
54
+ for (const [key, value] of Object.entries(env)) {
55
+ if (typeof value === "string" && !OWN_ENV.has(key)) out[key] = value;
56
+ }
57
+ return out;
58
+ }
59
+
60
+ /**
61
+ * Whether the command calls `hc wait` (`hc wait --children all`, `hc --json
62
+ * wait t7`). Run in a terminal under pi, it would wait for itself.
63
+ */
64
+ export function waitsOnHc(command: string): boolean {
65
+ return /(?:^|[\s;&|({`/])hc(?:[ \t]+[^\s;&|()]+)*?[ \t]+wait(?=$|[\s;&|)])/m.test(command);
66
+ }
67
+
68
+ /** Printable text for one line of the header or the title: no control characters. */
69
+ const printable = (line: string): string =>
70
+ // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping them is the point
71
+ line.replace(/\t/g, " ").replace(/[\x00-\x1f\x7f-\x9f]/g, "");
72
+
73
+ /** The command's first line, for the terminal's title: `npm test`, `cat > a.ts <<'EOF' …`. */
74
+ export function commandTitle(command: string, max = 80): string {
75
+ const lines = command.split(/\r?\n/).map((l) => printable(l).trim()).filter(Boolean);
76
+ let title = (lines[0] ?? "").replace(/\s+/g, " ");
77
+ const more = lines.length > 1;
78
+ if (title.length > max) title = `${title.slice(0, max - 1)}…`;
79
+ else if (more) title = `${title} …`;
80
+ return title;
81
+ }
82
+
83
+ const RESET = "\x1b[0m";
84
+ /** Tokyo Night blue, bold: the prompt. */
85
+ const PROMPT = "\x1b[1;38;2;122;162;247m";
86
+ const BOLD = "\x1b[1m";
87
+ /** Tokyo Night comment. */
88
+ const DIM = "\x1b[38;2;86;95;137m";
89
+
90
+ /**
91
+ * What the terminal shows before the output: its title (OSC 2) and the
92
+ * command after a `$`, at most `maxLines` lines of it.
93
+ */
94
+ export function commandHeader(command: string, maxLines = 12, maxWidth = 400): string {
95
+ const lines = command
96
+ .replace(/\r\n?/g, "\n")
97
+ .replace(/\n+$/, "")
98
+ .split("\n")
99
+ .map((l) => {
100
+ const text = printable(l);
101
+ return text.length > maxWidth ? `${text.slice(0, maxWidth - 1)}…` : text;
102
+ });
103
+ const shown = lines.slice(0, maxLines).map((line, i) => (i === 0 ? `${PROMPT}$${RESET} ${BOLD}${line}${RESET}` : ` ${BOLD}${line}${RESET}`));
104
+ if (lines.length > maxLines) shown.push(` ${DIM}… ${lines.length - maxLines} more lines${RESET}`);
105
+ return `\x1b]2;${commandTitle(command)}\x07${shown.join("\n")}\n`;
106
+ }
107
+
108
+ /** `'…'` for bash: any text as one word. */
109
+ export const shellQuote = (s: string): string => `'${s.replace(/'/g, `'\\''`)}'`;
110
+
111
+ /** `$'…'` for bash: any text, escape sequences included, as one word. */
112
+ export const ansiCQuote = (s: string): string =>
113
+ // biome-ignore lint/suspicious/noControlCharactersInRegex: escaping them is the point
114
+ `$'${s.replace(/[\\']/g, "\\$&").replace(/[\x00-\x1f\x7f]/g, (c) => `\\x${c.charCodeAt(0).toString(16).padStart(2, "0")}`)}'`;
115
+
116
+ export interface WrapperFiles {
117
+ /** The command, exactly as pi got it. */
118
+ command: string;
119
+ /** Where its output goes, for pi to read. */
120
+ output: string;
121
+ }
122
+
123
+ /** The script the terminal runs (`bash <script>`): the header, then the command through `tee`. */
124
+ export function wrapperScript(o: { shell: string; files: WrapperFiles; parent: string; header: string }): string {
125
+ return [
126
+ "# pi-wierdr: one command of pi's bash. Its output goes to this terminal and to the file pi reads.",
127
+ // The command gets a process group of its own, in front: herdr names the
128
+ // terminal after it, and ctrl+c typed into the terminal stops it alone.
129
+ "set -m",
130
+ // What it leaves running in the background outlives the terminal, as with pi's own bash.
131
+ "trap '' HUP",
132
+ // hc inside acts as pi: what it starts belongs to pi, not to this short-lived terminal.
133
+ `export HC_TERMINAL_ID=${shellQuote(o.parent)}`,
134
+ `printf '%s' ${ansiCQuote(o.header)}`,
135
+ // Read before the pipeline, byte for byte: a command substitution inside
136
+ // it would keep the script itself in front.
137
+ `IFS= read -r -d '' pi_herdr_command <${shellQuote(o.files.command)} || :`,
138
+ `${shellQuote(o.shell)} -c "$pi_herdr_command" </dev/null 2>&1 | tee ${shellQuote(o.files.output)}`,
139
+ 'exit "${PIPESTATUS[0]}"',
140
+ "",
141
+ ].join("\n");
142
+ }
143
+
144
+ /** The exit code of a finished terminal: its program's code, or 128 + the signal that ended it. */
145
+ export function exitCodeOf(t: { exit_code?: number | null; signal?: number | null }): number | null {
146
+ if (typeof t.exit_code === "number") return t.exit_code;
147
+ if (typeof t.signal === "number") return 128 + t.signal;
148
+ return null;
149
+ }
150
+
151
+ /**
152
+ * Follows a file another process appends to, handing each new piece to
153
+ * `onData` as it lands: every `intervalMs`, and once more at `stop()`.
154
+ */
155
+ export class OutputTail {
156
+ private handle: FileHandle | undefined;
157
+ private position = 0;
158
+ private timer: ReturnType<typeof setTimeout> | undefined;
159
+ private reading: Promise<void> = Promise.resolve();
160
+ private stopped = false;
161
+ private readonly buffer = Buffer.allocUnsafe(64 * 1024);
162
+
163
+ constructor(
164
+ private readonly path: string,
165
+ private readonly onData: (data: Buffer) => void,
166
+ private readonly intervalMs = 100,
167
+ ) {}
168
+
169
+ start(): void {
170
+ if (this.stopped || this.timer) return;
171
+ this.timer = setTimeout(() => {
172
+ this.timer = undefined;
173
+ this.reading = this.drain()
174
+ .catch(() => undefined)
175
+ .finally(() => this.start());
176
+ }, this.intervalMs);
177
+ this.timer.unref?.();
178
+ }
179
+
180
+ /** Reads what is left and closes the file. */
181
+ async stop(): Promise<void> {
182
+ this.stopped = true;
183
+ if (this.timer) clearTimeout(this.timer);
184
+ this.timer = undefined;
185
+ await this.reading;
186
+ await this.drain().catch(() => undefined);
187
+ await this.handle?.close().catch(() => undefined);
188
+ this.handle = undefined;
189
+ }
190
+
191
+ private async drain(): Promise<void> {
192
+ this.handle ??= await open(this.path, "r");
193
+ for (;;) {
194
+ const { bytesRead } = await this.handle.read(this.buffer, 0, this.buffer.length, this.position);
195
+ if (bytesRead === 0) return;
196
+ this.position += bytesRead;
197
+ this.onData(Buffer.from(this.buffer.subarray(0, bytesRead)));
198
+ }
199
+ }
200
+ }
201
+
202
+ const sleep = (ms: number, signal: AbortSignal): Promise<void> =>
203
+ new Promise((resolve) => {
204
+ if (signal.aborted) return resolve();
205
+ const done = () => {
206
+ clearTimeout(timer);
207
+ signal.removeEventListener("abort", done);
208
+ resolve();
209
+ };
210
+ const timer = setTimeout(done, ms);
211
+ signal.addEventListener("abort", done, { once: true });
212
+ });
213
+
214
+ const MAX_TIMEOUT_MS = 2_147_483_647;
215
+
216
+ function timeoutMs(timeout: number | undefined): number | undefined {
217
+ if (timeout === undefined) return undefined;
218
+ if (!Number.isFinite(timeout) || timeout <= 0) throw new Error("Invalid timeout: must be a finite number of seconds");
219
+ if (timeout * 1000 > MAX_TIMEOUT_MS) throw new Error(`Invalid timeout: maximum is ${MAX_TIMEOUT_MS / 1000} seconds`);
220
+ return timeout * 1000;
221
+ }
222
+
223
+ export interface HcBashOptions {
224
+ /** Where the per-command folders go (the command, its output, the script). */
225
+ tmpDir?: string;
226
+ /** How often the output file is read. */
227
+ pollMs?: number;
228
+ /** How long one `terminal.wait` may hold before it checks in again (seconds). */
229
+ waitSliceS?: number;
230
+ /** How long herdr-core may stay unreachable while a command runs before pi gives up on it. */
231
+ unreachableMs?: number;
232
+ }
233
+
234
+ export interface CommandSpec {
235
+ /** The shell the command runs in, as pi resolves it (`/bin/bash`). */
236
+ shell: string;
237
+ /** pi's own way to run it: for `hc wait`, and when herdr-core can't start a terminal. */
238
+ local: BashOperations;
239
+ source: BashSource;
240
+ /** settings.json `shellCommandPrefix`, which pi puts before every command: left out of the header. */
241
+ commandPrefix?: string;
242
+ /** Told the terminal's address once it runs, before any of its output. */
243
+ onTerminal?: (address: string) => void;
244
+ }
245
+
246
+ /** Runs pi's bash commands in herdr-core terminals under pi's own. */
247
+ export class HcBash {
248
+ /** Terminals of commands still running, to end with pi. */
249
+ private readonly live = new Set<string>();
250
+ private readonly tmpDir: string;
251
+ private readonly pollMs: number;
252
+ private readonly waitSliceS: number;
253
+ private readonly unreachableMs: number;
254
+
255
+ constructor(
256
+ private readonly target: HcTarget,
257
+ options: HcBashOptions = {},
258
+ ) {
259
+ this.tmpDir = options.tmpDir ?? tmpdir();
260
+ this.pollMs = options.pollMs ?? 100;
261
+ this.waitSliceS = options.waitSliceS ?? 50;
262
+ this.unreachableMs = options.unreachableMs ?? 60_000;
263
+ }
264
+
265
+ /** `BashOperations` for pi's bash tool or `user_bash`. */
266
+ operations(spec: CommandSpec): BashOperations {
267
+ return { exec: (command, cwd, options) => this.exec(spec, command, cwd, options) };
268
+ }
269
+
270
+ /** On quit: end the commands still running and remove their terminals. */
271
+ async shutdown(timeoutMs = 1000): Promise<void> {
272
+ const { socket, terminal } = this.target;
273
+ await Promise.all(
274
+ [...this.live].map(async (address) => {
275
+ await rpc(socket, "terminal.kill", { terminal: address, caller: terminal }, timeoutMs);
276
+ await rpc(socket, "terminal.rm", { terminal: address, caller: terminal }, timeoutMs);
277
+ }),
278
+ );
279
+ this.live.clear();
280
+ }
281
+
282
+ private async exec(
283
+ spec: CommandSpec,
284
+ command: string,
285
+ cwd: string,
286
+ options: Parameters<BashOperations["exec"]>[2],
287
+ ): Promise<{ exitCode: number | null }> {
288
+ const { onData, signal, timeout, env } = options;
289
+ if (signal?.aborted) throw new Error("aborted");
290
+ if (waitsOnHc(command)) return spec.local.exec(command, cwd, options);
291
+ const limitMs = timeoutMs(timeout);
292
+ try {
293
+ await access(cwd, constants.F_OK);
294
+ } catch {
295
+ throw new Error(`Working directory does not exist: ${cwd}\nCannot execute bash commands.`);
296
+ }
297
+
298
+ const { socket, terminal: parent } = this.target;
299
+ const dir = await mkdtemp(join(this.tmpDir, "pi-wierdr-bash-"));
300
+ const files = { command: join(dir, "command"), output: join(dir, "output") };
301
+ const script = join(dir, "run.sh");
302
+ const prefix = spec.commandPrefix ? `${spec.commandPrefix}\n` : "";
303
+ const shown = prefix && command.startsWith(prefix) ? command.slice(prefix.length) : command;
304
+ try {
305
+ await writeFile(files.command, command);
306
+ await writeFile(files.output, "");
307
+ await writeFile(script, wrapperScript({ shell: spec.shell, files, parent, header: commandHeader(shown) }));
308
+ } catch (e) {
309
+ await rm(dir, { recursive: true, force: true }).catch(() => undefined);
310
+ throw e;
311
+ }
312
+
313
+ // Not abortable: once asked, the core may start it, and only its address lets pi end it.
314
+ const started = await rpc(
315
+ socket,
316
+ "terminal.run",
317
+ {
318
+ argv: [spec.shell, script],
319
+ cwd,
320
+ env: terminalEnv(env ?? process.env),
321
+ labels: { [BASH_LABEL]: spec.source },
322
+ caller: parent,
323
+ parent,
324
+ no_notify: true,
325
+ },
326
+ 10_000,
327
+ );
328
+ const address = started.ok ? (started.result as { address?: unknown } | null)?.address : undefined;
329
+ if (typeof address !== "string") {
330
+ await rm(dir, { recursive: true, force: true }).catch(() => undefined);
331
+ // No answer in time: it may have started after all, so running it here could run it twice.
332
+ if (!started.ok && (started.error === "timeout" || started.error === "bad_reply")) {
333
+ throw new Error(`herdr-core did not answer in time (${started.error}); the command may or may not have run`);
334
+ }
335
+ // herdr-core isn't there or refused: run it the way pi does without it.
336
+ return spec.local.exec(command, cwd, options);
337
+ }
338
+ this.live.add(address);
339
+ try {
340
+ spec.onTerminal?.(address);
341
+ } catch {
342
+ // Only for show: never stops the command.
343
+ }
344
+
345
+ const tail = new OutputTail(files.output, onData, this.pollMs);
346
+ tail.start();
347
+ const stop = new AbortController();
348
+ let why: "aborted" | "timeout" | undefined;
349
+ const onAbort = () => {
350
+ why ??= "aborted";
351
+ stop.abort();
352
+ };
353
+ if (signal?.aborted) onAbort();
354
+ else signal?.addEventListener("abort", onAbort, { once: true });
355
+ const timer =
356
+ limitMs !== undefined
357
+ ? setTimeout(() => {
358
+ why ??= "timeout";
359
+ stop.abort();
360
+ }, limitMs)
361
+ : undefined;
362
+
363
+ let exitCode: number | null = null;
364
+ let failure: unknown;
365
+ try {
366
+ exitCode = await this.waitForExit(address, stop.signal);
367
+ } catch (e) {
368
+ if (!why) failure = e;
369
+ } finally {
370
+ if (timer) clearTimeout(timer);
371
+ signal?.removeEventListener("abort", onAbort);
372
+ }
373
+ if (why) await rpc(socket, "terminal.kill", { terminal: address, caller: parent }, 10_000);
374
+ await tail.stop();
375
+ // Unreachable for too long: the terminal may still run; there is nobody to remove it now.
376
+ if (!failure) {
377
+ await rpc(socket, "terminal.rm", { terminal: address, caller: parent }, 5000);
378
+ this.live.delete(address);
379
+ }
380
+ await rm(dir, { recursive: true, force: true }).catch(() => undefined);
381
+
382
+ if (why === "aborted") throw new Error("aborted");
383
+ if (why === "timeout") throw new Error(`timeout:${timeout}`);
384
+ if (failure) throw failure;
385
+ return { exitCode };
386
+ }
387
+
388
+ /**
389
+ * Until the terminal's program exits: its exit code (null when the terminal
390
+ * vanished). Throws when `signal` aborts, or when the core stays unreachable.
391
+ */
392
+ private async waitForExit(address: string, signal: AbortSignal): Promise<number | null> {
393
+ const { socket } = this.target;
394
+ // A program that reports a status word ends `terminal.wait` without
395
+ // exiting; from then on only polling tells when it does.
396
+ let polling = false;
397
+ let unreachableSince: number | undefined;
398
+ for (;;) {
399
+ if (signal.aborted) throw new Error("aborted");
400
+ const reply = polling
401
+ ? await rpc(socket, "terminal.get", { terminal: address }, 5000, signal)
402
+ : await rpc(socket, "terminal.wait", { terminal: address, timeout: this.waitSliceS }, (this.waitSliceS + 10) * 1000, signal);
403
+ if (!reply.ok) {
404
+ if (reply.error === "aborted") throw new Error("aborted");
405
+ // Removed by someone else: nothing left to tell how it ended.
406
+ if (reply.error === "not_found") return null;
407
+ // The core restarting (its programs keep running): ask again shortly.
408
+ unreachableSince ??= Date.now();
409
+ if (Date.now() - unreachableSince > this.unreachableMs) {
410
+ throw new Error(`herdr-core stopped answering while the command ran in terminal ${address} (${reply.error})`);
411
+ }
412
+ await sleep(500, signal);
413
+ continue;
414
+ }
415
+ unreachableSince = undefined;
416
+ const result = reply.result as { ended?: boolean; reason?: string; state?: string; exit_code?: number | null; signal?: number | null };
417
+ if (polling) {
418
+ if (result.state === "finished") return exitCodeOf(result);
419
+ await sleep(250, signal);
420
+ } else if (result.ended && result.reason === "exit") {
421
+ return exitCodeOf(result);
422
+ } else if (result.ended) {
423
+ polling = true;
424
+ }
425
+ }
426
+ }
427
+ }
package/herdr/cache.ts ADDED
@@ -0,0 +1,144 @@
1
+ /**
2
+ * When the prompt cache of the session's current branch expires, and how long
3
+ * it lives from a refresh, as `agent.cache_until` / `agent.cache_ttl`, so herdr
4
+ * can show how much of a pi's cache lifetime is left.
5
+ *
6
+ * Same reading as pi-statusline's countdown (`statusline/cache-timer.ts`),
7
+ * so the agent list and pi's footer agree. A cache entry's lifetime restarts
8
+ * every time a request reads or writes it:
9
+ *
10
+ * - assistant messages: `message.timestamp` is the request start, when the
11
+ * provider refreshes the entry;
12
+ * - pi's cache warming: `usage` entries with `kind: "cache_warm"`;
13
+ * - a real request still streaming (not persisted yet), tracked by
14
+ * `index.ts` from `message_start`.
15
+ *
16
+ * Only requests that reported cache activity (`cacheRead + cacheWrite > 0`)
17
+ * count. The lifetime is the model's `promptCache` tier for the retention pi
18
+ * asks for (`PI_CACHE_RETENTION`); a request that wrote 1h entries
19
+ * (`cacheWrite1h > 0`) is known to use the long tier.
20
+ *
21
+ * Pure functions, plus the small poll that catches a warming refresh landing.
22
+ */
23
+
24
+ export type CacheRetention = "short" | "long";
25
+
26
+ /** Model `promptCache` tiers in seconds (pi-ai's `ModelPromptCache`). */
27
+ export type PromptCacheTiers = Partial<Record<CacheRetention, number>>;
28
+
29
+ /** A model's prompt-cache tiers by provider and model id. */
30
+ export type PromptCacheLookup = (provider: string, modelId: string) => PromptCacheTiers | undefined;
31
+
32
+ interface UsageLike {
33
+ cacheRead: number;
34
+ cacheWrite: number;
35
+ cacheWrite1h?: number;
36
+ }
37
+
38
+ /** The part of a session entry this reads. */
39
+ export type CacheEntry =
40
+ | {
41
+ type: "message";
42
+ message: { role: string; provider?: string; model?: string; timestamp?: number; usage?: UsageLike };
43
+ }
44
+ | { type: "usage"; kind: string; provider: string; model: string; timestamp: string; usage: UsageLike }
45
+ | { type: string };
46
+
47
+ /** A real request that is still streaming. */
48
+ export interface InflightRequest {
49
+ at: number;
50
+ provider: string;
51
+ model: string;
52
+ }
53
+
54
+ /** The retention pi requests by default (`PI_CACHE_RETENTION=long` ⇒ long). */
55
+ export function envRetention(env: Record<string, string | undefined> = process.env): CacheRetention {
56
+ return env.PI_CACHE_RETENTION === "long" ? "long" : "short";
57
+ }
58
+
59
+ function ttlMs(lookup: PromptCacheLookup, provider: string, model: string, retention: CacheRetention): number | undefined {
60
+ const seconds = lookup(provider, model)?.[retention];
61
+ return typeof seconds === "number" && seconds > 0 ? seconds * 1000 : undefined;
62
+ }
63
+
64
+ /** The branch's cache entry: when it expires (epoch ms) and its lifetime from a refresh. */
65
+ export interface CacheWindow {
66
+ until: number;
67
+ ttlMs: number;
68
+ }
69
+
70
+ /**
71
+ * The branch's cache entry; undefined when the branch never touched the
72
+ * cache or the model's cache lifetime is unknown. An expired entry still
73
+ * answers with its (past) expiry: readers compare with now.
74
+ */
75
+ export function cacheWindow(
76
+ entries: readonly CacheEntry[],
77
+ lookup: PromptCacheLookup,
78
+ retention: CacheRetention,
79
+ inflight?: InflightRequest,
80
+ ): CacheWindow | undefined {
81
+ for (let i = entries.length - 1; i >= 0; i--) {
82
+ const entry = entries[i] as CacheEntry;
83
+ let at: number | undefined;
84
+ let provider: string | undefined;
85
+ let model: string | undefined;
86
+ let usage: UsageLike | undefined;
87
+
88
+ if (entry.type === "message" && "message" in entry && entry.message.role === "assistant") {
89
+ ({ provider, model, usage } = entry.message);
90
+ at = entry.message.timestamp;
91
+ } else if (entry.type === "usage" && "kind" in entry && entry.kind === "cache_warm") {
92
+ ({ provider, model, usage } = entry);
93
+ at = Date.parse(entry.timestamp);
94
+ } else {
95
+ continue;
96
+ }
97
+
98
+ if (!usage || usage.cacheRead + usage.cacheWrite <= 0 || !provider || !model) continue;
99
+ if (typeof at !== "number" || !Number.isFinite(at)) continue;
100
+
101
+ const tier: CacheRetention = (usage.cacheWrite1h ?? 0) > 0 ? "long" : retention;
102
+ const ttl = ttlMs(lookup, provider, model, tier);
103
+ if (ttl === undefined) return undefined;
104
+ // A streaming request refreshes the entry at its start; without an entry
105
+ // it only writes one, and its own usage tells once it lands.
106
+ if (inflight && inflight.at > at) {
107
+ const next = ttlMs(lookup, inflight.provider, inflight.model, tier) ?? ttl;
108
+ return { until: inflight.at + next, ttlMs: next };
109
+ }
110
+ return { until: at + ttl, ttlMs: ttl };
111
+ }
112
+ return undefined;
113
+ }
114
+
115
+ /**
116
+ * pi says when it is about to warm the cache (`cache_warming_decision`), not
117
+ * when the refresh landed: its usage entry is appended a moment later. After
118
+ * each decision this polls `check` once a second until the expiry it reports
119
+ * moves, or `tries` run out (the warm was skipped or failed).
120
+ */
121
+ export class WarmWatch {
122
+ private timer: ReturnType<typeof setInterval> | undefined;
123
+
124
+ constructor(
125
+ private readonly check: () => number | undefined,
126
+ private readonly tries = 20,
127
+ private readonly everyMs = 1000,
128
+ ) {}
129
+
130
+ start(): void {
131
+ this.stop();
132
+ const before = this.check();
133
+ let left = this.tries;
134
+ this.timer = setInterval(() => {
135
+ if (this.check() !== before || --left <= 0) this.stop();
136
+ }, this.everyMs);
137
+ this.timer.unref?.();
138
+ }
139
+
140
+ stop(): void {
141
+ if (this.timer) clearInterval(this.timer);
142
+ this.timer = undefined;
143
+ }
144
+ }
package/herdr/hc.ts ADDED
@@ -0,0 +1,126 @@
1
+ /**
2
+ * The smallest herdr-core client this needs, over the JSON-RPC socket
3
+ * herdr-core hands every terminal (`HC_TERMINAL_SOCKET`), one request per
4
+ * connection: `terminal.label` for the agent's labels, `doc.get` / `doc.set`
5
+ * for the shared limits document, `terminal.run` / `wait` / `kill` / `rm` for
6
+ * bash commands. Talking to the socket directly instead of spawning `hc`
7
+ * keeps it cheap enough to run after every reply.
8
+ */
9
+
10
+ import net from "node:net";
11
+
12
+ export interface HcTarget {
13
+ socket: string;
14
+ terminal: string;
15
+ }
16
+
17
+ /** The terminal pi runs in, when herdr-core started it. */
18
+ export function hcTargetFromEnv(env: NodeJS.ProcessEnv = process.env): HcTarget | undefined {
19
+ const socket = env.HC_TERMINAL_SOCKET;
20
+ const terminal = env.HC_TERMINAL_ID;
21
+ if (!socket || !terminal) return undefined;
22
+ return { socket, terminal };
23
+ }
24
+
25
+ /** One answer from herdr-core: its result, or the error kind it gave (`conflict`, `not_found`…). */
26
+ export type RpcReply = { ok: true; result: unknown } | { ok: false; error: string };
27
+
28
+ let nextId = 1;
29
+
30
+ /**
31
+ * Sends one request and resolves with herdr-core's answer. A missing core, a
32
+ * broken reply or no answer within `timeoutMs` resolve as an error too
33
+ * (`unreachable`, `bad_reply`, `timeout`), and so does `signal` aborting
34
+ * (`aborted`: the request may still have reached the core). Never throws: a
35
+ * missing core must not disturb pi.
36
+ */
37
+ export function rpc(
38
+ socketPath: string,
39
+ method: string,
40
+ params: Record<string, unknown>,
41
+ timeoutMs = 1500,
42
+ signal?: AbortSignal,
43
+ ): Promise<RpcReply> {
44
+ const endpoint = process.platform === "win32" ? `\\\\.\\pipe\\${socketPath}` : socketPath;
45
+ const request = { jsonrpc: "2.0", id: nextId++, method, params };
46
+ return new Promise((resolve) => {
47
+ if (signal?.aborted) {
48
+ resolve({ ok: false, error: "aborted" });
49
+ return;
50
+ }
51
+ let done = false;
52
+ let buffer = "";
53
+ const socket = net.createConnection(endpoint);
54
+ const finish = (reply: RpcReply) => {
55
+ if (done) return;
56
+ done = true;
57
+ clearTimeout(timer);
58
+ signal?.removeEventListener("abort", onAbort);
59
+ socket.destroy();
60
+ resolve(reply);
61
+ };
62
+ const onAbort = () => finish({ ok: false, error: "aborted" });
63
+ signal?.addEventListener("abort", onAbort, { once: true });
64
+ const timer = setTimeout(() => finish({ ok: false, error: "timeout" }), timeoutMs);
65
+ timer.unref?.();
66
+ socket.on("error", () => finish({ ok: false, error: "unreachable" }));
67
+ socket.on("end", () => finish({ ok: false, error: "unreachable" }));
68
+ socket.on("connect", () => socket.write(`${JSON.stringify(request)}\n`));
69
+ socket.on("data", (chunk) => {
70
+ buffer += chunk.toString("utf8");
71
+ const newline = buffer.indexOf("\n");
72
+ if (newline === -1) return;
73
+ try {
74
+ const reply = JSON.parse(buffer.slice(0, newline));
75
+ if (reply?.id !== request.id) finish({ ok: false, error: "bad_reply" });
76
+ else if (reply.error !== undefined) finish({ ok: false, error: String(reply.error?.data?.kind ?? reply.error?.message ?? "error") });
77
+ else if (reply.result !== undefined) finish({ ok: true, result: reply.result });
78
+ else finish({ ok: false, error: "bad_reply" });
79
+ } catch {
80
+ finish({ ok: false, error: "bad_reply" });
81
+ }
82
+ });
83
+ });
84
+ }
85
+
86
+ /**
87
+ * Sets (value) or removes (`""`) labels on the terminal. Resolves true once
88
+ * herdr-core answered with a result, false on any error or after `timeoutMs`.
89
+ */
90
+ export async function setLabels(target: HcTarget, labels: Record<string, string>, timeoutMs = 1500): Promise<boolean> {
91
+ const reply = await rpc(target.socket, "terminal.label", { terminal: target.terminal, labels }, timeoutMs);
92
+ return reply.ok;
93
+ }
94
+
95
+ /** A herdr-core document and its version (zero when never written). */
96
+ export interface Doc {
97
+ value: unknown;
98
+ version: number;
99
+ }
100
+
101
+ /** Reads a document from this machine's core; undefined when the core can't be asked. */
102
+ export async function getDoc(socket: string, name: string, timeoutMs = 1500): Promise<Doc | undefined> {
103
+ const reply = await rpc(socket, "doc.get", { name }, timeoutMs);
104
+ if (!reply.ok) return undefined;
105
+ const result = reply.result as { value?: unknown; version?: unknown } | null;
106
+ if (typeof result?.version !== "number") return undefined;
107
+ return { value: result.value ?? null, version: result.version };
108
+ }
109
+
110
+ /**
111
+ * Writes a document if it is still at `version`. Resolves with the new
112
+ * version, `"conflict"` when someone wrote it in between (read it again and
113
+ * retry), or undefined on any other failure.
114
+ */
115
+ export async function setDoc(
116
+ socket: string,
117
+ name: string,
118
+ value: unknown,
119
+ version: number,
120
+ timeoutMs = 1500,
121
+ ): Promise<number | "conflict" | undefined> {
122
+ const reply = await rpc(socket, "doc.set", { name, value, version }, timeoutMs);
123
+ if (!reply.ok) return reply.error === "conflict" ? "conflict" : undefined;
124
+ const next = (reply.result as { version?: unknown } | null)?.version;
125
+ return typeof next === "number" ? next : undefined;
126
+ }