@phren/cli 0.3.18 → 0.3.20

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.
Files changed (53) hide show
  1. package/dist/bridge/agent-hooks.d.ts +16 -1
  2. package/dist/bridge/agent-hooks.js +56 -4
  3. package/dist/bridge/changes.d.ts +4 -0
  4. package/dist/bridge/changes.js +25 -2
  5. package/dist/bridge/command.js +24 -6
  6. package/dist/bridge/dispatch-returns.d.ts +11 -0
  7. package/dist/bridge/dispatch-returns.js +47 -7
  8. package/dist/bridge/dispatch.d.ts +19 -0
  9. package/dist/bridge/dispatch.js +164 -5
  10. package/dist/bridge/harnesses.d.ts +1 -1
  11. package/dist/bridge/harnesses.js +9 -2
  12. package/dist/bridge/health.d.ts +3 -2
  13. package/dist/bridge/health.js +4 -3
  14. package/dist/bridge/hook-fast.d.ts +13 -1
  15. package/dist/bridge/hook-fast.js +17 -2
  16. package/dist/bridge/models.d.ts +11 -1
  17. package/dist/bridge/models.js +47 -2
  18. package/dist/bridge/server-launch.d.ts +20 -0
  19. package/dist/bridge/server-launch.js +77 -3
  20. package/dist/bridge/server-routes.d.ts +4 -0
  21. package/dist/bridge/server-routes.js +2 -2
  22. package/dist/bridge/server.js +6 -1
  23. package/dist/bridge/speech-live.d.ts +45 -0
  24. package/dist/bridge/speech-live.js +413 -0
  25. package/dist/bridge/speech-transcribe.d.ts +5 -2
  26. package/dist/bridge/speech-transcribe.js +8 -5
  27. package/dist/bridge/speech-voice.d.ts +22 -1
  28. package/dist/bridge/speech-voice.js +20 -2
  29. package/dist/bridge/speech.d.ts +24 -4
  30. package/dist/bridge/speech.js +115 -14
  31. package/dist/bridge/stalls.d.ts +9 -2
  32. package/dist/bridge/stalls.js +20 -4
  33. package/dist/bridge/terminal-herdr.d.ts +7 -0
  34. package/dist/bridge/terminal-herdr.js +81 -7
  35. package/dist/bridge/terminal-tmux.js +2 -2
  36. package/dist/bridge/terminal.d.ts +3 -0
  37. package/dist/bridge/terminal.js +1 -0
  38. package/dist/bridge/transcript-preview.d.ts +11 -1
  39. package/dist/bridge/transcript-preview.js +37 -11
  40. package/dist/bridge/transcripts.d.ts +2 -1
  41. package/dist/bridge/transcripts.js +7 -3
  42. package/dist/bridge/transport.js +4 -3
  43. package/dist/bridge/turn-records.d.ts +6 -3
  44. package/dist/bridge/turn-records.js +9 -4
  45. package/dist/bridge/usage.d.ts +1 -1
  46. package/dist/bridge/usage.js +4 -3
  47. package/dist/bridge/worker-close.js +2 -1
  48. package/dist/bridge/worker-unfinished.d.ts +37 -0
  49. package/dist/bridge/worker-unfinished.js +145 -0
  50. package/dist/bridge-hook.mjs +2171 -1230
  51. package/dist/cli-registry.js +2 -1
  52. package/dist/modules/registry.js +2 -2
  53. package/package.json +1 -1
@@ -1,4 +1,4 @@
1
- import type { ServerResponse } from "node:http";
1
+ import { type ServerResponse } from "node:http";
2
2
  import { z } from "zod";
3
3
  import { BridgeError, type Json } from "./protocol.js";
4
4
  export { DEFAULT_SPEECH_MODEL, DEFAULT_SPEECH_VOICE, FALLBACK_SPEECH_MODEL } from "./speech-voice.js";
@@ -36,6 +36,7 @@ export declare const FALLBACK_HOLD_MS: number;
36
36
  export declare const speechRequest: z.ZodObject<{
37
37
  text: z.ZodString;
38
38
  timestamps: z.ZodOptional<z.ZodBoolean>;
39
+ stream: z.ZodOptional<z.ZodBoolean>;
39
40
  voice: z.ZodOptional<z.ZodString>;
40
41
  formats: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodEnum<{
41
42
  mp3_44100_128: "mp3_44100_128";
@@ -61,6 +62,8 @@ export declare class SpeechState {
61
62
  * of its last three is over SPEECH_SLOW_MS. */
62
63
  recordLatency(model: string, ms: number): void;
63
64
  }
65
+ /** The Hook's own: /v1/speech and /v1/speech/live learn together. */
66
+ export declare const sharedSpeechState: SpeechState;
64
67
  /** When each character of the voiced text starts and ends, in seconds from
65
68
  * the start of the audio. */
66
69
  export interface SpeechAlignment {
@@ -77,6 +80,9 @@ export interface SpeechOptions {
77
80
  formats?: readonly string[];
78
81
  /** Defaults to this computer's setting (speech-voice.ts). */
79
82
  model?: string;
83
+ /** Where ElevenLabs is, e.g. https://api.elevenlabs.io. Defaults to this
84
+ * computer's region setting (speech-voice.ts). */
85
+ origin?: string;
80
86
  /** Defaults to the Hook's own. */
81
87
  state?: SpeechState;
82
88
  now?: () => number;
@@ -86,6 +92,17 @@ export interface SpeechResult {
86
92
  model: string;
87
93
  format: SpeechFormat;
88
94
  }
95
+ /** How long ElevenLabs may send nothing, before its headers or between two
96
+ * chunks of audio, before the request is given up on: fetch's own limits were
97
+ * 300 s, and the pool's timeout only closes idle sockets. */
98
+ export declare const SPEECH_STALL_MS = 30000;
99
+ /** POSTs to ElevenLabs over the Hook's kept-alive pool and answers a fetch
100
+ * Response whose body is the upstream socket, so audio is passed on chunk by
101
+ * chunk as it arrives. Honours HTTPS_PROXY as fetch does, when
102
+ * NODE_USE_ENV_PROXY is set. A pooled socket ElevenLabs closed while it sat
103
+ * idle fails on its first write; that request is sent once more on a fresh
104
+ * one. */
105
+ export declare function elevenLabsFetch(url: string, init: RequestInit, stallMs?: number): Promise<Response>;
89
106
  /** A fixed message per ElevenLabs failure: its own response text is never
90
107
  * passed on. */
91
108
  export declare function speechError(upstream: Response): Promise<BridgeError>;
@@ -95,8 +112,9 @@ export declare function speechError(upstream: Response): Promise<BridgeError>;
95
112
  * skipped, a link keeps its text and a bare URL becomes "a link". Empty when
96
113
  * nothing speakable is left. */
97
114
  export declare function speakableText(text: string): string;
98
- /** Starts ElevenLabs' streaming synthesis and returns its audio body. */
99
- export declare function synthesizeSpeech(text: string, signal: AbortSignal, options?: SpeechOptions): Promise<SpeechResult & {
115
+ /** Starts ElevenLabs' streaming synthesis and returns its body: the audio,
116
+ * or with `stream/with-timestamps` JSON lines of audio and alignment. */
117
+ export declare function synthesizeSpeech(text: string, signal: AbortSignal, options?: SpeechOptions, endpoint?: "stream" | "stream/with-timestamps"): Promise<SpeechResult & {
100
118
  body: ReadableStream<Uint8Array>;
101
119
  }>;
102
120
  /** Voices the text in one piece with ElevenLabs' character alignment. */
@@ -115,7 +133,9 @@ export declare function alignmentOf(raw: {
115
133
  * format, model, alignment }`, the audio base64 in the format served and the
116
134
  * alignment null when ElevenLabs sent none. The streamed reply names its
117
135
  * format in `X-Phren-Audio` and `X-Phren-Audio-Rate`. A phone that sends no
118
- * `formats` always gets pcm_24000.
136
+ * `formats` always gets pcm_24000. With `timestamps` and `stream`, the
137
+ * streamed reply is `application/x-ndjson`, one `{audio, alignment}` line per
138
+ * chunk (see timedLines), with the same headers.
119
139
  * Failures before the first byte are thrown for the route's JSON error; a
120
140
  * failure mid-stream cuts the response off, which the phone treats as an
121
141
  * error. The phone hanging up cancels the ElevenLabs request. */
@@ -1,8 +1,11 @@
1
1
  import { once } from "node:events";
2
+ import { Agent as HttpAgent, request as httpRequest } from "node:http";
3
+ import { Agent as HttpsAgent, request as httpsRequest } from "node:https";
4
+ import { Readable } from "node:stream";
2
5
  import { z } from "zod";
3
6
  import { BridgeError } from "./protocol.js";
4
7
  import { readSpeechKey } from "./speech-key.js";
5
- import { FALLBACK_SPEECH_MODEL, resolveSpeechModel, resolveSpeechVoice, voiceId } from "./speech-voice.js";
8
+ import { FALLBACK_SPEECH_MODEL, resolveSpeechModel, resolveSpeechRegion, resolveSpeechVoice, voiceId } from "./speech-voice.js";
6
9
  export { DEFAULT_SPEECH_MODEL, DEFAULT_SPEECH_VOICE, FALLBACK_SPEECH_MODEL } from "./speech-voice.js";
7
10
  /** Spoken replies for the phone's talk mode. The phone sends a sentence; the
8
11
  * Hook voices it with ElevenLabs and streams the audio back. The API key is
@@ -46,6 +49,10 @@ export const speechRequest = z.object({
46
49
  /** Answer JSON with the audio and when each character is spoken, so the
47
50
  * phone can highlight the word being read (talk mode's karaoke). */
48
51
  timestamps: z.boolean().optional(),
52
+ /** With `timestamps`, stream the audio and alignment as ElevenLabs makes
53
+ * them, one JSON line per chunk, instead of one JSON reply once the whole
54
+ * sentence is voiced (about 0.6 s later with v4 Turbo). */
55
+ stream: z.boolean().optional(),
49
56
  /** A voice the phone picked; otherwise this computer's setting. */
50
57
  voice: voiceId.optional(),
51
58
  /** The output formats the phone plays (`SPEECH_FORMATS` names). Without
@@ -84,7 +91,65 @@ export class SpeechState {
84
91
  this.bench(model, "slow");
85
92
  }
86
93
  }
87
- const sharedState = new SpeechState();
94
+ /** The Hook's own: /v1/speech and /v1/speech/live learn together. */
95
+ export const sharedSpeechState = new SpeechState();
96
+ /** Idle connections to ElevenLabs are kept this long, so the next sentence's
97
+ * request skips the TCP and TLS handshake. fetch's own pool lets them go
98
+ * after four seconds, shorter than talk mode's pause between replies. */
99
+ const KEEP_ALIVE_MS = 60_000;
100
+ let pool;
101
+ /** How long ElevenLabs may send nothing, before its headers or between two
102
+ * chunks of audio, before the request is given up on: fetch's own limits were
103
+ * 300 s, and the pool's timeout only closes idle sockets. */
104
+ export const SPEECH_STALL_MS = 30_000;
105
+ /** POSTs to ElevenLabs over the Hook's kept-alive pool and answers a fetch
106
+ * Response whose body is the upstream socket, so audio is passed on chunk by
107
+ * chunk as it arrives. Honours HTTPS_PROXY as fetch does, when
108
+ * NODE_USE_ENV_PROXY is set. A pooled socket ElevenLabs closed while it sat
109
+ * idle fails on its first write; that request is sent once more on a fresh
110
+ * one. */
111
+ export function elevenLabsFetch(url, init, stallMs = SPEECH_STALL_MS) {
112
+ const proxyEnv = process.env.NODE_USE_ENV_PROXY === "1" ? process.env : undefined;
113
+ pool ??= {
114
+ http: new HttpAgent({ keepAlive: true, timeout: KEEP_ALIVE_MS, proxyEnv }),
115
+ https: new HttpsAgent({ keepAlive: true, timeout: KEEP_ALIVE_MS, proxyEnv }),
116
+ };
117
+ const target = new URL(url), secure = target.protocol === "https:";
118
+ const body = typeof init.body === "string" ? init.body : "";
119
+ const attempt = (retried) => new Promise((resolve, reject) => {
120
+ let answered = false;
121
+ const request = (secure ? httpsRequest : httpRequest)(target, {
122
+ method: init.method ?? "GET", signal: init.signal ?? undefined, agent: secure ? pool.https : pool.http,
123
+ headers: { ...init.headers, "Content-Length": String(Buffer.byteLength(body)) },
124
+ }, upstream => {
125
+ answered = true;
126
+ const status = upstream.statusCode ?? 0;
127
+ if (status < 200 || status > 599) {
128
+ upstream.destroy();
129
+ reject(new Error(`HTTP ${status}`));
130
+ return;
131
+ }
132
+ // A Response with one of these statuses may not have a body.
133
+ if (status === 204 || status === 205 || status === 304) {
134
+ upstream.resume();
135
+ resolve(new Response(null, { status }));
136
+ return;
137
+ }
138
+ resolve(new Response(Readable.toWeb(upstream), { status }));
139
+ });
140
+ // Covers the wait for the headers and each gap in the body after them.
141
+ request.setTimeout(stallMs, () => request.destroy(new Error("ElevenLabs stalled")));
142
+ request.on("error", error => {
143
+ if (!retried && !answered && request.reusedSocket && error.code === "ECONNRESET") {
144
+ resolve(attempt(true));
145
+ return;
146
+ }
147
+ reject(error);
148
+ });
149
+ request.end(body);
150
+ });
151
+ return attempt(false);
152
+ }
88
153
  /** ElevenLabs' machine-readable reason (`detail.status`), never its text. */
89
154
  async function upstreamCode(upstream) {
90
155
  try {
@@ -143,9 +208,10 @@ export function speakableText(text) {
143
208
  .replace(/\s+/g, " ")
144
209
  .trim();
145
210
  }
146
- /** Starts ElevenLabs' streaming synthesis and returns its audio body. */
147
- export async function synthesizeSpeech(text, signal, options = {}) {
148
- const { upstream, model, format, started } = await elevenLabs("stream", text, signal, options);
211
+ /** Starts ElevenLabs' streaming synthesis and returns its body: the audio,
212
+ * or with `stream/with-timestamps` JSON lines of audio and alignment. */
213
+ export async function synthesizeSpeech(text, signal, options = {}, endpoint = "stream") {
214
+ const { upstream, model, format, started } = await elevenLabs(endpoint, text, signal, options);
149
215
  if (!upstream.body)
150
216
  throw await speechError(upstream);
151
217
  timed(text, model, started, options);
@@ -172,7 +238,7 @@ export async function synthesizeTimedSpeech(text, signal, options = {}) {
172
238
  function timed(text, model, started, options) {
173
239
  if (model === FALLBACK_SPEECH_MODEL || text.length > TIMED_TEXT)
174
240
  return;
175
- (options.state ?? sharedState).recordLatency(model, (options.now ?? Date.now)() - started);
241
+ (options.state ?? sharedSpeechState).recordLatency(model, (options.now ?? Date.now)() - started);
176
242
  }
177
243
  /** ElevenLabs' alignment, kept only when its three lists line up. */
178
244
  export function alignmentOf(raw) {
@@ -185,6 +251,36 @@ export function alignmentOf(raw) {
185
251
  return null;
186
252
  return { characters: characters, starts: starts, ends: ends };
187
253
  }
254
+ /** ElevenLabs' streamed timestamps, one JSON object per line, as the phone's
255
+ * lines: `{audio, alignment}`, the alignment's times in seconds from the
256
+ * start of the whole reply (as ElevenLabs counts them) and null for a chunk
257
+ * with no characters. A chunk without audio is dropped. */
258
+ async function* timedLines(body) {
259
+ const decoder = new TextDecoder();
260
+ let pending = "";
261
+ for await (const bytes of body) {
262
+ pending += decoder.decode(bytes, { stream: true });
263
+ const lines = pending.split("\n");
264
+ pending = lines.pop();
265
+ for (const line of lines) {
266
+ const out = timedLine(line);
267
+ if (out)
268
+ yield out;
269
+ }
270
+ }
271
+ const out = timedLine(pending + decoder.decode());
272
+ if (out)
273
+ yield out;
274
+ }
275
+ function timedLine(line) {
276
+ if (!line.trim())
277
+ return undefined;
278
+ const raw = JSON.parse(line);
279
+ if (typeof raw.audio_base64 !== "string" || !raw.audio_base64)
280
+ return undefined;
281
+ const alignment = alignmentOf(raw.alignment);
282
+ return JSON.stringify({ audio: raw.audio_base64, alignment: alignment?.characters.length ? alignment : null }) + "\n";
283
+ }
188
284
  /** The plan doesn't allow this output format (Creator: "Output format
189
285
  * 'pcm_44100' is only available on the Pro tier and above", 403
190
286
  * `output_format_not_allowed`). */
@@ -207,8 +303,9 @@ async function elevenLabs(endpoint, text, signal, options) {
207
303
  if (!key)
208
304
  throw new BridgeError(503, "Spoken replies aren't set up on this computer: it has no ElevenLabs key.", { code: "speech-unconfigured" });
209
305
  const { voice } = await resolveSpeechVoice(options.voice);
210
- const state = options.state ?? sharedState, now = options.now ?? Date.now;
306
+ const state = options.state ?? sharedSpeechState, now = options.now ?? Date.now;
211
307
  const chosen = options.model ?? (await resolveSpeechModel()).model;
308
+ const origin = options.origin ?? (await resolveSpeechRegion()).origin;
212
309
  const models = chosen === FALLBACK_SPEECH_MODEL ? [chosen] : state.benchedReason(chosen) ? [FALLBACK_SPEECH_MODEL] : [chosen, FALLBACK_SPEECH_MODEL];
213
310
  const accepted = new Set(options.formats ?? []);
214
311
  let failure;
@@ -216,11 +313,11 @@ async function elevenLabs(endpoint, text, signal, options) {
216
313
  // Per model, so a format refused under one isn't tried again under the next.
217
314
  const formats = SPEECH_FORMATS.filter(format => format === BASE_FORMAT || (accepted.has(format) && state.formatAllowed(format)));
218
315
  for (const format of formats) {
219
- const url = `https://api.elevenlabs.io/v1/text-to-speech/${encodeURIComponent(voice)}/${endpoint}?output_format=${format}`;
316
+ const url = `${origin}/v1/text-to-speech/${encodeURIComponent(voice)}/${endpoint}?output_format=${format}`;
220
317
  const started = now();
221
318
  let upstream;
222
319
  try {
223
- upstream = await (options.fetch ?? fetch)(url, {
320
+ upstream = await (options.fetch ?? elevenLabsFetch)(url, {
224
321
  method: "POST", signal,
225
322
  headers: { "xi-api-key": key, "Content-Type": "application/json" },
226
323
  body: JSON.stringify({ text, model_id: model, voice_settings: { stability: 0.6, similarity_boost: 0.75 } }),
@@ -251,7 +348,9 @@ async function elevenLabs(endpoint, text, signal, options) {
251
348
  * format, model, alignment }`, the audio base64 in the format served and the
252
349
  * alignment null when ElevenLabs sent none. The streamed reply names its
253
350
  * format in `X-Phren-Audio` and `X-Phren-Audio-Rate`. A phone that sends no
254
- * `formats` always gets pcm_24000.
351
+ * `formats` always gets pcm_24000. With `timestamps` and `stream`, the
352
+ * streamed reply is `application/x-ndjson`, one `{audio, alignment}` line per
353
+ * chunk (see timedLines), with the same headers.
255
354
  * Failures before the first byte are thrown for the route's JSON error; a
256
355
  * failure mid-stream cuts the response off, which the phone treats as an
257
356
  * error. The phone hanging up cancels the ElevenLabs request. */
@@ -268,7 +367,7 @@ export async function streamSpeech(data, response, options = {}) {
268
367
  const abort = new AbortController();
269
368
  response.once("close", () => { if (!response.writableEnded)
270
369
  abort.abort(); });
271
- if (timestamps) {
370
+ if (timestamps && !request.stream) {
272
371
  const { audio, alignment, model, format } = await synthesizeTimedSpeech(text, abort.signal, options);
273
372
  const info = SPEECH_FORMAT_INFO[format];
274
373
  response.statusCode = 200;
@@ -276,15 +375,17 @@ export async function streamSpeech(data, response, options = {}) {
276
375
  response.end(JSON.stringify({ audio, audioFormat: info.audio, sampleRate: info.sampleRate, format, model, alignment }));
277
376
  return;
278
377
  }
279
- const { body: audio, model, format } = await synthesizeSpeech(text, abort.signal, options);
378
+ const { body: audio, model, format } = await synthesizeSpeech(text, abort.signal, options, timestamps ? "stream/with-timestamps" : "stream");
280
379
  const info = SPEECH_FORMAT_INFO[format];
281
380
  response.statusCode = 200;
282
- response.setHeader("Content-Type", info.contentType);
381
+ response.setHeader("Content-Type", timestamps ? "application/x-ndjson" : info.contentType);
283
382
  response.setHeader("X-Phren-Audio", info.audio);
284
383
  response.setHeader("X-Phren-Audio-Rate", String(info.sampleRate));
285
384
  response.setHeader("X-Phren-Speech-Model", model);
385
+ // The phone sets up its player from these headers while the first audio is still on its way.
386
+ response.flushHeaders();
286
387
  try {
287
- for await (const chunk of audio) {
388
+ for await (const chunk of timestamps ? timedLines(audio) : audio) {
288
389
  if (!response.write(chunk))
289
390
  await once(response, "drain", { signal: abort.signal });
290
391
  }
@@ -12,11 +12,18 @@ export interface StallReaders {
12
12
  }
13
13
  export declare function stallThreshold(): number;
14
14
  /** Requires successful observations of both sources. Identity, terminal, work
15
- * status and either source changing all reset the clock. Missing data is unknown. */
15
+ * status and either source changing all reset the clock. Missing data is unknown.
16
+ * `live` reads the awaited work the pane's turn still waits on (`liveWork`:
17
+ * awaited background shells and monitors, running children). A worker that
18
+ * ended its turn on purpose while a build runs sits still on screen and in its
19
+ * transcript, so once the clock runs out `live` is asked, and any live work
20
+ * starts the clock over instead of reporting a stall, for at most
21
+ * BACKGROUND_STALE_MS: work that never ends (a build deadlocked on a lock, a
22
+ * child that died without its completion record) does not hide a stall forever. */
16
23
  export declare class StallDetector {
17
24
  private readers;
18
25
  private entries;
19
26
  constructor(readers?: StallReaders);
20
- observe(target: Target, pane: Json): Promise<Stall | undefined>;
27
+ observe(target: Target, pane: Json, live?: () => Promise<number | undefined>): Promise<Stall | undefined>;
21
28
  }
22
29
  export declare const sessionStalls: StallDetector;
@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
2
2
  import { open } from "node:fs/promises";
3
3
  import { targetTranscriptPath } from "./transcripts.js";
4
4
  import { terminalProvider } from "./terminal.js";
5
+ import { BACKGROUND_STALE_MS } from "./session-activity.js";
5
6
  export function stallThreshold() {
6
7
  const value = Number(process.env.PHREN_STALL_MS ?? 300_000);
7
8
  return Number.isFinite(value) && value >= 0 ? value : 300_000;
@@ -18,7 +19,14 @@ async function transcriptStamp(target) {
18
19
  }
19
20
  }
20
21
  /** Requires successful observations of both sources. Identity, terminal, work
21
- * status and either source changing all reset the clock. Missing data is unknown. */
22
+ * status and either source changing all reset the clock. Missing data is unknown.
23
+ * `live` reads the awaited work the pane's turn still waits on (`liveWork`:
24
+ * awaited background shells and monitors, running children). A worker that
25
+ * ended its turn on purpose while a build runs sits still on screen and in its
26
+ * transcript, so once the clock runs out `live` is asked, and any live work
27
+ * starts the clock over instead of reporting a stall, for at most
28
+ * BACKGROUND_STALE_MS: work that never ends (a build deadlocked on a lock, a
29
+ * child that died without its completion record) does not hide a stall forever. */
22
30
  export class StallDetector {
23
31
  readers;
24
32
  entries = new Map();
@@ -28,7 +36,7 @@ export class StallDetector {
28
36
  }) {
29
37
  this.readers = readers;
30
38
  }
31
- async observe(target, pane) {
39
+ async observe(target, pane, live) {
32
40
  const key = JSON.stringify([target.server, target.pane]);
33
41
  if (pane.agent_status !== "working" || this.readers.threshold() === 0) {
34
42
  this.entries.delete(key);
@@ -50,8 +58,16 @@ export class StallDetector {
50
58
  }
51
59
  while (this.entries.size > 1024)
52
60
  this.entries.delete(this.entries.keys().next().value);
53
- const since = this.entries.get(key).since;
54
- return now - since >= this.readers.threshold() ? { stalled: true, stalledSince: new Date(since).toISOString(), stallFor: Math.floor((now - since) / 1000) } : undefined;
61
+ const entry = this.entries.get(key), since = entry.since;
62
+ if (now - since < this.readers.threshold())
63
+ return undefined;
64
+ const held = entry.liveSince === undefined || now - entry.liveSince < BACKGROUND_STALE_MS;
65
+ if (live && held && await live().catch(() => undefined)) {
66
+ entry.since = now;
67
+ entry.liveSince ??= since;
68
+ return undefined;
69
+ }
70
+ return { stalled: true, stalledSince: new Date(since).toISOString(), stallFor: Math.floor((now - since) / 1000) };
55
71
  }
56
72
  }
57
73
  export const sessionStalls = new StallDetector();
@@ -1,5 +1,12 @@
1
1
  import { type Json } from "./protocol.js";
2
2
  import type { TerminalPane, TerminalProvider } from "./terminal.js";
3
+ /** Who reports phren-agent's lifecycle to Herdr, which does not detect it itself. */
4
+ export declare const PHREN_REPORT_SOURCE = "phren-hook";
5
+ /** A word for a POSIX shell, quoted only when it needs it. */
6
+ export declare function shellWord(word: string): string;
7
+ /** What the Hook types into a Herdr pane's shell to start phren-agent:
8
+ * the agent, then Herdr's report of it released once it exits. */
9
+ export declare function phrenCommandLine(args: string[]): string;
3
10
  /** A Herdr snapshot's panes in the provider's shape; Herdr's agent report becomes hints. */
4
11
  export declare function herdrPanes(server: string, s: Json): TerminalPane[];
5
12
  export declare const herdrTerminal: TerminalProvider;
@@ -3,8 +3,55 @@
3
3
  // fake, so a test that records Herdr requests sees exactly what it did before
4
4
  // the provider existed.
5
5
  import { herdrSocketPath, rpc, snapshot } from "./herdr.js";
6
- import { object, objects } from "./protocol.js";
6
+ import { BridgeError, object, objects } from "./protocol.js";
7
+ import { agentFromCommand } from "./terminal-tmux.js";
7
8
  const text = (value) => typeof value === "string" && value ? value : undefined;
9
+ /** Who reports phren-agent's lifecycle to Herdr, which does not detect it itself. */
10
+ export const PHREN_REPORT_SOURCE = "phren-hook";
11
+ /** A word for a POSIX shell, quoted only when it needs it. */
12
+ export function shellWord(word) {
13
+ return /^[A-Za-z0-9_./:=@%+,-]+$/.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`;
14
+ }
15
+ /** What the Hook types into a Herdr pane's shell to start phren-agent:
16
+ * the agent, then Herdr's report of it released once it exits. */
17
+ export function phrenCommandLine(args) {
18
+ return [["phren", ...args].map(shellWord).join(" "),
19
+ `herdr pane release-agent "$HERDR_PANE_ID" --source ${PHREN_REPORT_SOURCE} --agent phren >/dev/null 2>&1`].join("; ");
20
+ }
21
+ /** Whether `pane` runs phren-agent as Herdr reports it, for the prompt and key fallbacks below. */
22
+ async function reportedPhren(server, pane) {
23
+ const info = object((await rpc(server, "pane.get", { pane_id: pane }).catch(() => ({}))).pane);
24
+ return info.agent === "phren";
25
+ }
26
+ /** Herdr's `agent.prompt` and `agent.send_keys` take only agents it started;
27
+ * a phren-agent pane it knows by report gets the pane calls instead. */
28
+ function unnamedAgent(error) {
29
+ return error instanceof BridgeError && error.details?.herdrCode === "agent_not_ready" && /not an active named agent/.test(error.message);
30
+ }
31
+ /** Herdr's `agent.start` knows a fixed list of harnesses and phren-agent is
32
+ * not on it. The Hook types `phren agent ...` at the pane's login shell
33
+ * instead, waits for it to be the foreground program, then reports it to
34
+ * Herdr as agent "phren" under the launch name, so the pane reads as an agent
35
+ * like the others. Its own lifecycle hooks keep the status (agent-hooks.ts). */
36
+ async function startPhren(server, pane, { name, args, timeoutMs }) {
37
+ const before = object((await rpc(server, "pane.process_info", { pane_id: pane })).process_info);
38
+ // Same refusal as Herdr's own start, so the caller waits for the shell.
39
+ if (!Number.isSafeInteger(before.shell_pid) || before.foreground_process_group_id !== before.shell_pid)
40
+ throw new BridgeError(409, `Herdr: agent target pane ${pane} is not an available shell`, { herdrCode: "agent_pane_busy" });
41
+ await rpc(server, "pane.send_text", { pane_id: pane, text: phrenCommandLine(args) });
42
+ await rpc(server, "pane.send_keys", { pane_id: pane, keys: ["Enter"] });
43
+ const deadline = Date.now() + Math.min(timeoutMs, 30_000);
44
+ for (;;) {
45
+ const info = object((await rpc(server, "pane.process_info", { pane_id: pane })).process_info);
46
+ if (objects(info.foreground_processes).some(p => typeof p.cmdline === "string" && agentFromCommand(p.cmdline) === "phren"))
47
+ break;
48
+ if (Date.now() >= deadline)
49
+ throw new BridgeError(504, "phren agent did not start in the Herdr pane. Check that phren and @phren/agent are installed on the login shell's PATH.");
50
+ await new Promise(resolve => setTimeout(resolve, 250));
51
+ }
52
+ await rpc(server, "pane.report_agent", { pane_id: pane, source: PHREN_REPORT_SOURCE, agent: "phren", state: "idle" });
53
+ await rpc(server, "agent.rename", { target: pane, name }).catch(() => undefined);
54
+ }
8
55
  /** A Herdr snapshot's panes in the provider's shape; Herdr's agent report becomes hints. */
9
56
  export function herdrPanes(server, s) {
10
57
  return objects(s.panes).filter(p => typeof p.pane_id === "string" && typeof p.tab_id === "string" && typeof p.workspace_id === "string").map(p => {
@@ -36,18 +83,42 @@ export const herdrTerminal = {
36
83
  const answer = object(result.read ?? result);
37
84
  return typeof answer.text === "string" ? answer.text : "";
38
85
  },
39
- async sendKeys(server, pane, keys) { await rpc(server, "agent.send_keys", { target: pane, keys }); },
86
+ async sendKeys(server, pane, keys) {
87
+ try {
88
+ await rpc(server, "agent.send_keys", { target: pane, keys });
89
+ }
90
+ catch (error) {
91
+ if (!unnamedAgent(error) || !await reportedPhren(server, pane))
92
+ throw error;
93
+ await rpc(server, "pane.send_keys", { pane_id: pane, keys });
94
+ }
95
+ },
40
96
  async prompt(server, pane, text, signal) {
41
- if (signal)
42
- await rpc(server, "agent.prompt", { target: pane, text }, signal);
43
- else
44
- await rpc(server, "agent.prompt", { target: pane, text });
97
+ try {
98
+ if (signal)
99
+ await rpc(server, "agent.prompt", { target: pane, text }, signal);
100
+ else
101
+ await rpc(server, "agent.prompt", { target: pane, text });
102
+ }
103
+ catch (error) {
104
+ if (!unnamedAgent(error) || !await reportedPhren(server, pane))
105
+ throw error;
106
+ // One bracketed paste keeps the newlines in phren-agent's composer; Enter submits it.
107
+ await rpc(server, "pane.send_text", { pane_id: pane, text: `\x1b[200~${text}\x1b[201~` }, signal);
108
+ await new Promise(resolve => setTimeout(resolve, 150));
109
+ await rpc(server, "pane.send_keys", { pane_id: pane, keys: ["Enter"] }, signal);
110
+ }
45
111
  },
46
112
  async create(server, { workspace, label, cwd, env }) {
47
113
  await rpc(server, workspace ? "tab.create" : "workspace.create", { workspace_id: workspace, label, cwd, focus: false, env: env ?? {} });
48
114
  },
49
115
  // `agent.start` takes no environment; the pane's shell got it at `create`.
50
- async startAgent(server, pane, { name, kind, args, timeoutMs }) {
116
+ async startAgent(server, pane, agent) {
117
+ const { name, kind, args, timeoutMs } = agent;
118
+ if (kind === "phren") {
119
+ await startPhren(server, pane, agent);
120
+ return;
121
+ }
51
122
  // Herdr waits up to `timeout_ms` for the agent to become ready; the socket waits a little longer.
52
123
  await rpc(server, "agent.start", { name, kind, pane_id: pane, timeout_ms: timeoutMs, ...(args.length ? { args } : {}) }, undefined, timeoutMs + 5_000);
53
124
  },
@@ -55,6 +126,9 @@ export const herdrTerminal = {
55
126
  paneEnv(server, { workspace, tab, pane }) {
56
127
  return { HERDR_ENV: "1", HERDR_SOCKET_PATH: herdrSocketPath(server), HERDR_WORKSPACE_ID: workspace, HERDR_TAB_ID: tab, HERDR_PANE_ID: pane };
57
128
  },
129
+ async reportAgent(server, pane, agent, state) {
130
+ await rpc(server, "pane.report_agent", { pane_id: pane, source: PHREN_REPORT_SOURCE, agent, state });
131
+ },
58
132
  async focusPane(server, pane) { await rpc(server, "pane.focus", { pane_id: pane }); },
59
133
  async closePane(server, pane) { await rpc(server, "pane.close", { pane_id: pane }); },
60
134
  async renamePane(server, pane, label) { await rpc(server, "pane.rename", { pane_id: pane, label }); },
@@ -208,7 +208,7 @@ export function agentFromCommand(command) {
208
208
  return "phren";
209
209
  // `phren agent` runs the same agent through the CLI.
210
210
  const next = words[words.indexOf(program) + 1];
211
- if ((name === "phren" || program.includes("@phren/cli/")) && next === "agent")
211
+ if ((name === "phren" || program.includes("@phren/cli/") || /\/packages\/cli\/dist\/index\.js$/.test(program)) && next === "agent")
212
212
  return "phren";
213
213
  return undefined;
214
214
  }
@@ -437,7 +437,7 @@ export const tmuxTerminal = {
437
437
  await tmux(server, ["new-session", "-d", "-s", sessionName(label, taken), "-x", "200", "-y", "50", ...directory, ...name]);
438
438
  },
439
439
  async startAgent(server, pane, { name, kind, args, timeoutMs, env }) {
440
- if (!["claude", "codex", "copilot", "opencode"].includes(kind))
440
+ if (!["claude", "codex", "copilot", "opencode", "phren"].includes(kind))
441
441
  throw new BridgeError(400, "This agent cannot be started in tmux.");
442
442
  await requireDirectExec();
443
443
  const target = toTmuxId(pane, "p"), row = await paneRow(server, target);
@@ -109,6 +109,9 @@ export interface TerminalProvider {
109
109
  tab: string;
110
110
  pane: string;
111
111
  }): Record<string, string> | undefined;
112
+ /** Tells a multiplexer that watches its agents what one it cannot detect
113
+ * (phren-agent in Herdr) is doing. Absent where the Hook keeps that itself (tmux). */
114
+ reportAgent?(server: string, pane: string, agent: string, state: "idle" | "working" | "blocked"): Promise<void>;
112
115
  focusPane(server: string, pane: string): Promise<void>;
113
116
  /** Sets the pane's own label (Herdr's pane label, a tmux pane option), shown by the Hook as the session's name. */
114
117
  closePane(server: string, pane: string): Promise<void>;
@@ -52,6 +52,7 @@ export const routedTerminal = {
52
52
  create: (server, placement) => route(server).create(server, placement),
53
53
  startAgent: (server, pane, agent) => route(server).startAgent(server, pane, agent),
54
54
  paneEnv: (server, place) => route(server).paneEnv?.(server, place),
55
+ reportAgent: async (server, pane, agent, state) => { await route(server).reportAgent?.(server, pane, agent, state); },
55
56
  focusPane: (server, pane) => route(server).focusPane(server, pane),
56
57
  closePane: (server, pane) => route(server).closePane(server, pane),
57
58
  renamePane: (server, pane, label) => route(server).renamePane(server, pane, label),
@@ -1,8 +1,16 @@
1
1
  import { type Target } from "./protocol.js";
2
2
  import type { Entry } from "./transcripts.js";
3
+ /**
4
+ * The reply being written. `delta` and `streamed` appear only on text built
5
+ * from a harness's own deltas (Codex, OpenCode, phren's agent), never on text
6
+ * read off a terminal: `delta` is what was appended since this socket's
7
+ * previous preview frame (the whole text when the block is new to it).
8
+ */
3
9
  export interface TranscriptPreview {
4
10
  turnStartedAt: string;
5
11
  text: string;
12
+ delta?: string;
13
+ streamed?: true;
6
14
  }
7
15
  export declare const PREVIEW_INTERVAL_MS = 500;
8
16
  /** Only the last Claude reply after the current prompt is eligible. A missing
@@ -92,7 +100,9 @@ export declare class TranscriptPreviewStream {
92
100
  private current;
93
101
  private observedLine;
94
102
  private wasWorking;
95
- private readonly codexCompleted;
103
+ /** Replies that already landed as entries: a sidecar or thread a tick
104
+ * behind them must not bring the same text back as a preview. */
105
+ private readonly completed;
96
106
  private readonly rollout;
97
107
  constructor(target: Target, pane?: () => Promise<string>, delta?: (file?: string) => Promise<TranscriptPreview | null>);
98
108
  observe(entries: Entry[], reset?: boolean): void;