@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.
- package/dist/bridge/agent-hooks.d.ts +16 -1
- package/dist/bridge/agent-hooks.js +56 -4
- package/dist/bridge/changes.d.ts +4 -0
- package/dist/bridge/changes.js +25 -2
- package/dist/bridge/command.js +24 -6
- package/dist/bridge/dispatch-returns.d.ts +11 -0
- package/dist/bridge/dispatch-returns.js +47 -7
- package/dist/bridge/dispatch.d.ts +19 -0
- package/dist/bridge/dispatch.js +164 -5
- package/dist/bridge/harnesses.d.ts +1 -1
- package/dist/bridge/harnesses.js +9 -2
- package/dist/bridge/health.d.ts +3 -2
- package/dist/bridge/health.js +4 -3
- package/dist/bridge/hook-fast.d.ts +13 -1
- package/dist/bridge/hook-fast.js +17 -2
- package/dist/bridge/models.d.ts +11 -1
- package/dist/bridge/models.js +47 -2
- package/dist/bridge/server-launch.d.ts +20 -0
- package/dist/bridge/server-launch.js +77 -3
- package/dist/bridge/server-routes.d.ts +4 -0
- package/dist/bridge/server-routes.js +2 -2
- package/dist/bridge/server.js +6 -1
- package/dist/bridge/speech-live.d.ts +45 -0
- package/dist/bridge/speech-live.js +413 -0
- package/dist/bridge/speech-transcribe.d.ts +5 -2
- package/dist/bridge/speech-transcribe.js +8 -5
- package/dist/bridge/speech-voice.d.ts +22 -1
- package/dist/bridge/speech-voice.js +20 -2
- package/dist/bridge/speech.d.ts +24 -4
- package/dist/bridge/speech.js +115 -14
- package/dist/bridge/stalls.d.ts +9 -2
- package/dist/bridge/stalls.js +20 -4
- package/dist/bridge/terminal-herdr.d.ts +7 -0
- package/dist/bridge/terminal-herdr.js +81 -7
- package/dist/bridge/terminal-tmux.js +2 -2
- package/dist/bridge/terminal.d.ts +3 -0
- package/dist/bridge/terminal.js +1 -0
- package/dist/bridge/transcript-preview.d.ts +11 -1
- package/dist/bridge/transcript-preview.js +37 -11
- package/dist/bridge/transcripts.d.ts +2 -1
- package/dist/bridge/transcripts.js +7 -3
- package/dist/bridge/transport.js +4 -3
- package/dist/bridge/turn-records.d.ts +6 -3
- package/dist/bridge/turn-records.js +9 -4
- package/dist/bridge/usage.d.ts +1 -1
- package/dist/bridge/usage.js +4 -3
- package/dist/bridge/worker-close.js +2 -1
- package/dist/bridge/worker-unfinished.d.ts +37 -0
- package/dist/bridge/worker-unfinished.js +145 -0
- package/dist/bridge-hook.mjs +2171 -1230
- package/dist/cli-registry.js +2 -1
- package/dist/modules/registry.js +2 -2
- package/package.json +1 -1
package/dist/bridge/speech.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type
|
|
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
|
|
99
|
-
|
|
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. */
|
package/dist/bridge/speech.js
CHANGED
|
@@ -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
|
-
|
|
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
|
|
147
|
-
|
|
148
|
-
|
|
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 ??
|
|
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 ??
|
|
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 =
|
|
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 ??
|
|
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
|
}
|
package/dist/bridge/stalls.d.ts
CHANGED
|
@@ -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;
|
package/dist/bridge/stalls.js
CHANGED
|
@@ -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
|
|
54
|
-
|
|
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) {
|
|
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
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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,
|
|
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>;
|
package/dist/bridge/terminal.js
CHANGED
|
@@ -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
|
-
|
|
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;
|