@phren/cli 0.3.19 → 0.3.21

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 (76) hide show
  1. package/dist/bridge/agent-hooks.d.ts +38 -20
  2. package/dist/bridge/agent-hooks.js +100 -37
  3. package/dist/bridge/approval-summary.d.ts +4 -0
  4. package/dist/bridge/approval-summary.js +12 -1
  5. package/dist/bridge/changes.d.ts +4 -0
  6. package/dist/bridge/changes.js +25 -2
  7. package/dist/bridge/code-note.d.ts +1 -0
  8. package/dist/bridge/code-note.js +2 -2
  9. package/dist/bridge/codex-binary.d.ts +5 -0
  10. package/dist/bridge/codex-binary.js +7 -0
  11. package/dist/bridge/command.js +24 -6
  12. package/dist/bridge/dispatch-command.js +1 -1
  13. package/dist/bridge/dispatch-returns.d.ts +14 -2
  14. package/dist/bridge/dispatch-returns.js +72 -16
  15. package/dist/bridge/dispatch.d.ts +23 -0
  16. package/dist/bridge/dispatch.js +169 -8
  17. package/dist/bridge/folder-trust.d.ts +13 -3
  18. package/dist/bridge/folder-trust.js +42 -4
  19. package/dist/bridge/hand-off.js +2 -1
  20. package/dist/bridge/herdr.js +6 -5
  21. package/dist/bridge/hook-fast.d.ts +13 -1
  22. package/dist/bridge/hook-fast.js +17 -2
  23. package/dist/bridge/launch-brief.d.ts +3 -1
  24. package/dist/bridge/launch-brief.js +3 -1
  25. package/dist/bridge/memory-store.d.ts +7 -0
  26. package/dist/bridge/memory-store.js +37 -1
  27. package/dist/bridge/models.d.ts +11 -1
  28. package/dist/bridge/models.js +47 -2
  29. package/dist/bridge/schedule-format.d.ts +1 -1
  30. package/dist/bridge/schedule-format.js +1 -1
  31. package/dist/bridge/schedule-launch.js +5 -0
  32. package/dist/bridge/schedule-watch.d.ts +5 -2
  33. package/dist/bridge/schedule-watch.js +59 -20
  34. package/dist/bridge/server-launch.d.ts +26 -0
  35. package/dist/bridge/server-launch.js +122 -12
  36. package/dist/bridge/server-pane-routes.js +20 -13
  37. package/dist/bridge/server-routes.d.ts +5 -0
  38. package/dist/bridge/server-routes.js +2 -2
  39. package/dist/bridge/server-stream.js +12 -0
  40. package/dist/bridge/server.js +8 -3
  41. package/dist/bridge/session-activity.d.ts +6 -0
  42. package/dist/bridge/session-activity.js +16 -0
  43. package/dist/bridge/settings-switch.d.ts +7 -0
  44. package/dist/bridge/settings-switch.js +15 -0
  45. package/dist/bridge/speech-live.d.ts +45 -0
  46. package/dist/bridge/speech-live.js +413 -0
  47. package/dist/bridge/speech-transcribe.d.ts +13 -3
  48. package/dist/bridge/speech-transcribe.js +26 -8
  49. package/dist/bridge/speech-voice.d.ts +22 -1
  50. package/dist/bridge/speech-voice.js +20 -2
  51. package/dist/bridge/speech.d.ts +24 -4
  52. package/dist/bridge/speech.js +115 -14
  53. package/dist/bridge/stalls.d.ts +9 -2
  54. package/dist/bridge/stalls.js +20 -4
  55. package/dist/bridge/transcript-claude.js +39 -10
  56. package/dist/bridge/transcript-preview.d.ts +11 -1
  57. package/dist/bridge/transcript-preview.js +37 -11
  58. package/dist/bridge/transcripts.d.ts +2 -1
  59. package/dist/bridge/transcripts.js +7 -3
  60. package/dist/bridge/turn-records.d.ts +6 -3
  61. package/dist/bridge/turn-records.js +9 -4
  62. package/dist/bridge/usage.d.ts +1 -1
  63. package/dist/bridge/usage.js +4 -3
  64. package/dist/bridge/worker-close.js +3 -1
  65. package/dist/bridge/worker-unfinished.d.ts +43 -0
  66. package/dist/bridge/worker-unfinished.js +178 -0
  67. package/dist/bridge-hook.mjs +2458 -1351
  68. package/dist/cli-registry.js +3 -2
  69. package/dist/home-paths.d.ts +2 -0
  70. package/dist/home-paths.js +4 -0
  71. package/dist/modules/registry.js +2 -2
  72. package/dist/test-global-setup.js +2 -1
  73. package/dist/test-sandbox.d.ts +15 -0
  74. package/dist/test-sandbox.js +36 -0
  75. package/package.json +1 -1
  76. package/starter/global/skills/conductor/SKILL.md +2 -1
@@ -79,6 +79,24 @@ export async function resolveSpeechModel(file = speechVoiceFile()) {
79
79
  const stored = await readStoredModel(file);
80
80
  return stored ? { model: stored, source: "setting" } : { model: DEFAULT_SPEECH_MODEL, source: "default" };
81
81
  }
82
+ /** Where this computer reaches ElevenLabs. `global` is api.elevenlabs.io,
83
+ * which routes to the nearest region; `us` is ElevenLabs' US-only endpoint.
84
+ * `phren bridge speech-region us|global` stores it in the same `speech.json`
85
+ * as the voice and model; unset is global. Read on every reply. */
86
+ export const SPEECH_REGIONS = { global: "https://api.elevenlabs.io", us: "https://api.us.elevenlabs.io" };
87
+ export const DEFAULT_SPEECH_REGION = "global";
88
+ export const speechRegion = z.enum(Object.keys(SPEECH_REGIONS));
89
+ export async function resolveSpeechRegion(file = speechVoiceFile()) {
90
+ const parsed = speechRegion.safeParse((await readSettings(file)).region);
91
+ const region = parsed.success ? parsed.data : DEFAULT_SPEECH_REGION;
92
+ return { region, origin: SPEECH_REGIONS[region], source: parsed.success ? "setting" : "default" };
93
+ }
94
+ /** Global is the default, so choosing it removes the key. */
95
+ export async function writeSpeechRegion(region, file = speechVoiceFile()) {
96
+ const value = speechRegion.parse(region);
97
+ await updateSettings(file, "region", value === DEFAULT_SPEECH_REGION ? undefined : value);
98
+ return value;
99
+ }
82
100
  /** The voice to speak with: the request's own, the stored setting, the old
83
101
  * environment override (copied into the setting on first use), else the
84
102
  * default. */
@@ -99,10 +117,10 @@ export async function resolveSpeechVoice(requested, paths = {}) {
99
117
  /** The voices this computer's ElevenLabs account can speak with, for the
100
118
  * phone's picker: id, name and a short description, never the account's
101
119
  * other details. */
102
- export async function listSpeechVoices(key, fetcher = fetch, signal) {
120
+ export async function listSpeechVoices(key, fetcher = fetch, signal, origin) {
103
121
  let upstream;
104
122
  try {
105
- upstream = await fetcher("https://api.elevenlabs.io/v1/voices", { headers: { "xi-api-key": key }, signal });
123
+ upstream = await fetcher(`${origin ?? (await resolveSpeechRegion()).origin}/v1/voices`, { headers: { "xi-api-key": key }, signal });
106
124
  }
107
125
  catch {
108
126
  throw new BridgeError(502, "Couldn't reach ElevenLabs from this computer.", { code: "speech-unreachable" });
@@ -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();
@@ -4,9 +4,10 @@ import { createInterface } from "node:readline";
4
4
  import { createHash } from "node:crypto";
5
5
  import path from "node:path";
6
6
  import { object, objects } from "./protocol.js";
7
- /** Claude Code's transcript reader: Task sidechains and named teammates as
8
- * child agents, and the public rows of a conversation. */
9
7
  const claudeRelationCache = new Map();
8
+ const copyRows = (rows) => ({ launches: new Map([...rows.launches].map(([id, launch]) => [id, { ...launch }])),
9
+ skills: new Set(rows.skills), workflows: new Map([...rows.workflows].map(([id, workflow]) => [id, { ...workflow }])),
10
+ teammates: new Map([...rows.teammates].map(([name, launch]) => [name, { ...launch }])) });
10
11
  const claudeChildModelCache = new Map();
11
12
  function cacheClaudeChildModel(file, entry) {
12
13
  claudeChildModelCache.set(file, entry);
@@ -91,6 +92,12 @@ export async function claudeChildAgents(file, session) {
91
92
  cached.relations = await withClaudeChildModels(cached.relations);
92
93
  return cached.relations;
93
94
  }
95
+ // A recheck of an unchanged parent (a launch whose transcript was not there
96
+ // yet, a background skill or workflow still running) reads only the children.
97
+ const rows = cached?.signature === signature && cached.rows ? cached.rows : await claudeParentRows(file);
98
+ return claudeChildRelations(file, session, signature, rows);
99
+ }
100
+ async function claudeParentRows(file) {
94
101
  const launches = new Map();
95
102
  const stops = new Map();
96
103
  // A background skill (`/code-review` run as `@code-review`) is announced in
@@ -177,15 +184,26 @@ export async function claudeChildAgents(file, session) {
177
184
  previous.state = "completed";
178
185
  }
179
186
  }
180
- if (content.includes("<teammate-message")) {
181
- const from = /<teammate-message teammate_id="([A-Za-z0-9][A-Za-z0-9_-]{0,63})"/.exec(content)?.[1];
182
- const teammate = from && teammates.get(from);
187
+ // One row can carry several messages (a shutdown approval and the
188
+ // system's termination notice together). Idle, an approved shutdown
189
+ // and termination end a teammate; anything else it says wakes it.
190
+ for (const match of content.includes("<teammate-message") ? content.matchAll(/<teammate-message teammate_id="([A-Za-z0-9][A-Za-z0-9_-]{0,63})"[^>]*>([\s\S]*?)<\/teammate-message>/g) : []) {
191
+ const [, from, body] = match;
192
+ const type = /"type":"([a-z_]+)"/.exec(body)?.[1];
193
+ const ended = from === "system" && type === "teammate_terminated" ? /"message":"([A-Za-z0-9][A-Za-z0-9_-]{0,63}) has shut down/.exec(body)?.[1] : undefined;
194
+ const teammate = teammates.get(ended ?? from);
183
195
  if (teammate)
184
- teammate.state = content.includes("\"type\":\"idle_notification\"") ? "completed" : "running";
196
+ teammate.state = ended || type === "idle_notification" || type === "shutdown_approved" ? "completed" : "running";
185
197
  }
186
198
  }
187
199
  catch { /* Ignore unrelated/malformed rows. */ }
188
200
  }
201
+ return { launches, skills, workflows, teammates };
202
+ }
203
+ async function claudeChildRelations(file, session, signature, rows) {
204
+ // Kept as the parent wrote them: what follows marks finished children.
205
+ const kept = copyRows(rows);
206
+ const { launches, workflows, teammates } = copyRows(rows);
189
207
  const relations = [];
190
208
  // Claude Code records the launch in the parent before the child's own
191
209
  // file exists. A launch without a transcript yet is looked for again
@@ -201,7 +219,9 @@ export async function claudeChildAgents(file, session) {
201
219
  awaiting = true;
202
220
  continue;
203
221
  }
204
- if (skills.has(agentId) && launch.state === "running") {
222
+ // A skill never gets a notification, and any child loses its own when the
223
+ // session that ran it was restarted or continued: its transcript decides.
224
+ if (launch.state === "running") {
205
225
  if (await claudeSkillFinished(childFile).catch(() => false))
206
226
  launch.state = "completed";
207
227
  else
@@ -237,6 +257,14 @@ export async function claudeChildAgents(file, session) {
237
257
  }
238
258
  // The meta file names the model as the launcher chose it ("sonnet");
239
259
  // the transcript's first assistant turn carries the full id and wins.
260
+ // A teammate that never said it was idle or shut down (its session was
261
+ // restarted or continued) ends the same way: a finished reply, or quiet.
262
+ if (launch.state === "running") {
263
+ if (await claudeSkillFinished(childFile).catch(() => false))
264
+ launch.state = "completed";
265
+ else
266
+ live = true;
267
+ }
240
268
  const meta = await readFile(childFile.slice(0, -".jsonl".length) + ".meta.json", "utf8").then(v => object(JSON.parse(v))).catch(() => ({}));
241
269
  const model = await claudeChildModel(childFile).catch(() => undefined) ?? (typeof meta.model === "string" && meta.model ? meta.model.slice(0, 200) : undefined);
242
270
  const checkout = await claudeChildCheckout(childFile).catch(() => ({}));
@@ -258,7 +286,7 @@ export async function claudeChildAgents(file, session) {
258
286
  }
259
287
  }
260
288
  }
261
- claudeRelationCache.set(file, { signature, relations, ...(awaiting || live ? { recheckAt: Date.now() + (awaiting ? 2_000 : 5_000) } : {}) });
289
+ claudeRelationCache.set(file, { signature, relations, ...(awaiting || live ? { recheckAt: Date.now() + (awaiting ? 2_000 : 5_000), rows: kept } : {}) });
262
290
  while (claudeRelationCache.size > 64)
263
291
  claudeRelationCache.delete(claudeRelationCache.keys().next().value);
264
292
  return relations;
@@ -267,8 +295,9 @@ export async function claudeChildAgents(file, session) {
267
295
  * taken as finished: the parent records no end for it, and a session that
268
296
  * exited mid-skill leaves it without a final reply. */
269
297
  export const CLAUDE_SKILL_QUIET_MS = 30 * 60 * 1000;
270
- /** A background skill is done once its transcript ends on a finished reply,
271
- * or has not changed for CLAUDE_SKILL_QUIET_MS. */
298
+ /** A background child (a skill, or a sub-agent or teammate whose end the
299
+ * parent never recorded) is done once its transcript ends on a finished
300
+ * reply, or has not changed for CLAUDE_SKILL_QUIET_MS. */
272
301
  async function claudeSkillFinished(file, now = Date.now()) {
273
302
  const metadata = await stat(file);
274
303
  if (now - metadata.mtimeMs >= CLAUDE_SKILL_QUIET_MS)
@@ -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;
@@ -5,6 +5,8 @@ import { readPaneText } from "./pane-text.js";
5
5
  import { object, objects } from "./protocol.js";
6
6
  import { withTranscriptIndex } from "./transcript-index.js";
7
7
  import { stripTerminal } from "../terminal-text.js";
8
+ /** Harnesses whose preview text is the reply's own Markdown, from their deltas. */
9
+ const STREAMED_SOURCES = new Set(["codex", "opencode", "phren"]);
8
10
  export const PREVIEW_INTERVAL_MS = 500;
9
11
  const MAX_TEXT = 32_768;
10
12
  // A JSON-escaped UTF-16 code unit takes at most six bytes, plus metadata.
@@ -351,7 +353,9 @@ export async function readDeltaPreview(target, file, rollout) {
351
353
  if (target.source === "codex")
352
354
  return await codexThreadPreview(target.session)
353
355
  ?? (file && rollout ? await rollout.read(file).catch(() => null) : null);
354
- if (target.source !== "opencode" || !file)
356
+ // OpenCode's plugin and phren's agent write the same sidecar beside their
357
+ // event log (packages/agent/src/session/preview.ts).
358
+ if ((target.source !== "opencode" && target.source !== "phren") || !file)
355
359
  return null;
356
360
  try {
357
361
  const handle = await open(file + ".preview.json", constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
@@ -402,7 +406,9 @@ export class TranscriptPreviewStream {
402
406
  current = null;
403
407
  observedLine = -1;
404
408
  wasWorking = false;
405
- codexCompleted = new Set();
409
+ /** Replies that already landed as entries: a sidecar or thread a tick
410
+ * behind them must not bring the same text back as a preview. */
411
+ completed = new Set();
406
412
  rollout = new CodexRolloutPreview();
407
413
  constructor(target, pane = () => readPreviewPane(target), delta = file => readDeltaPreview(target, file, this.rollout)) {
408
414
  this.target = target;
@@ -416,7 +422,7 @@ export class TranscriptPreviewStream {
416
422
  this.landed = false;
417
423
  this.ended = false;
418
424
  this.wasWorking = false;
419
- this.codexCompleted.clear();
425
+ this.completed.clear();
420
426
  }
421
427
  for (const { raw, line } of entries) {
422
428
  if (line <= this.observedLine)
@@ -428,25 +434,40 @@ export class TranscriptPreviewStream {
428
434
  const payload = object(raw.payload);
429
435
  if (raw.type === "event_msg" && payload.type === "task_started") {
430
436
  this.ended = false;
431
- this.codexCompleted.clear();
437
+ this.completed.clear();
432
438
  }
433
439
  else if (raw.type === "response_item" && payload.type === "message" && payload.role === "user" && !raw.phrenQueued) {
434
440
  this.ended = false;
435
- this.codexCompleted.clear();
441
+ this.completed.clear();
436
442
  }
437
443
  else if (raw.type === "response_item" && payload.type === "message" && payload.role === "assistant") {
438
444
  const text = (typeof payload.content === "string" ? payload.content
439
445
  : objects(payload.content).map(block => typeof block.text === "string" ? block.text : "").join("\n")).trim();
440
446
  if (text) {
441
- this.codexCompleted.add(text);
442
- if (this.codexCompleted.size > 32)
443
- this.codexCompleted.delete(this.codexCompleted.values().next().value);
447
+ this.completed.add(text);
448
+ if (this.completed.size > 32)
449
+ this.completed.delete(this.completed.values().next().value);
444
450
  }
445
451
  }
446
452
  else if (raw.type === "event_msg" && ["task_complete", "task_completed", "turn_aborted", "task_aborted"].includes(String(payload.type)))
447
453
  this.ended = true;
448
454
  continue;
449
455
  }
456
+ if (this.target.source === "phren") {
457
+ const data = object(raw.data), message = object(data.message);
458
+ if (raw.type === "user/message")
459
+ this.completed.clear();
460
+ else if (raw.type === "assistant/message") {
461
+ const text = (typeof message.content === "string" ? message.content
462
+ : objects(message.content).filter(block => block.type === "text").map(block => String(block.text ?? "")).join("\n")).trim();
463
+ if (text) {
464
+ this.completed.add(text);
465
+ if (this.completed.size > 32)
466
+ this.completed.delete(this.completed.values().next().value);
467
+ }
468
+ }
469
+ continue;
470
+ }
450
471
  if (this.target.source === "copilot") {
451
472
  // A prompt starts the turn; idle or abort ends it (Copilot writes a
452
473
  // turn_start/turn_end pair per model call, not per prompt).
@@ -497,14 +518,14 @@ export class TranscriptPreviewStream {
497
518
  let next = null;
498
519
  if (status === "working") {
499
520
  this.wasWorking = true;
500
- if (this.target.source === "codex" || this.target.source === "opencode") {
521
+ if (STREAMED_SOURCES.has(this.target.source)) {
501
522
  // These harnesses own a delta source. Never scrape their pane, even
502
523
  // when the source is temporarily empty or unavailable.
503
524
  if (!this.ended)
504
525
  next = await this.delta(file);
505
- if (this.target.source === "codex" && next) {
526
+ if (this.target.source !== "opencode" && next) {
506
527
  const text = next.text.trim();
507
- if (text && [...this.codexCompleted].some(completed => completed.startsWith(text)))
528
+ if (text && [...this.completed].some(completed => completed.startsWith(text)))
508
529
  next = null;
509
530
  }
510
531
  }
@@ -552,6 +573,11 @@ export class TranscriptPreviewStream {
552
573
  return undefined;
553
574
  if ((next || !previewChanged) && sentAt - this.lastSent < PREVIEW_INTERVAL_MS)
554
575
  return undefined;
576
+ if (next && STREAMED_SOURCES.has(this.target.source)) {
577
+ const before = this.current?.turnStartedAt === next.turnStartedAt ? this.current.text : "";
578
+ next = { turnStartedAt: next.turnStartedAt, text: next.text,
579
+ delta: before && next.text.startsWith(before) ? next.text.slice(before.length) : next.text, streamed: true };
580
+ }
555
581
  this.current = next;
556
582
  this.sentActivity = activity;
557
583
  if (next || activityChanged)