@phren/cli 0.3.11 → 0.3.12

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 (168) hide show
  1. package/dist/bridge/agent-hook-stores.d.ts +3 -0
  2. package/dist/bridge/agent-hook-stores.js +5 -0
  3. package/dist/bridge/agent-hooks.d.ts +159 -5
  4. package/dist/bridge/agent-hooks.js +663 -49
  5. package/dist/bridge/approval-summary.d.ts +16 -0
  6. package/dist/bridge/approval-summary.js +133 -0
  7. package/dist/bridge/authority-command.d.ts +20 -0
  8. package/dist/bridge/authority-command.js +120 -0
  9. package/dist/bridge/authority.d.ts +223 -0
  10. package/dist/bridge/authority.js +231 -0
  11. package/dist/bridge/claude-account-setup.d.ts +14 -0
  12. package/dist/bridge/claude-account-setup.js +69 -0
  13. package/dist/bridge/claude-accounts.d.ts +49 -0
  14. package/dist/bridge/claude-accounts.js +195 -0
  15. package/dist/bridge/code-routes.js +2 -2
  16. package/dist/bridge/codex-app-server.d.ts +144 -0
  17. package/dist/bridge/codex-app-server.js +319 -0
  18. package/dist/bridge/codex-auth-refresh.d.ts +33 -0
  19. package/dist/bridge/codex-auth-refresh.js +71 -0
  20. package/dist/bridge/codex-question-reply.d.ts +16 -0
  21. package/dist/bridge/codex-question-reply.js +57 -0
  22. package/dist/bridge/codex-review-mode.d.ts +10 -0
  23. package/dist/bridge/codex-review-mode.js +74 -0
  24. package/dist/bridge/codex-servers.d.ts +217 -0
  25. package/dist/bridge/codex-servers.js +636 -0
  26. package/dist/bridge/command.js +94 -4
  27. package/dist/bridge/computer-identity.d.ts +75 -0
  28. package/dist/bridge/computer-identity.js +166 -0
  29. package/dist/bridge/conductor-group.d.ts +91 -8
  30. package/dist/bridge/conductor-group.js +105 -9
  31. package/dist/bridge/conductor-role.d.ts +94 -0
  32. package/dist/bridge/conductor-role.js +176 -0
  33. package/dist/bridge/conductor-sets.d.ts +20 -0
  34. package/dist/bridge/conductor-sets.js +59 -0
  35. package/dist/bridge/dispatch-command.d.ts +3 -0
  36. package/dist/bridge/dispatch-command.js +75 -11
  37. package/dist/bridge/dispatch-returns.d.ts +123 -19
  38. package/dist/bridge/dispatch-returns.js +357 -50
  39. package/dist/bridge/dispatch.d.ts +103 -2
  40. package/dist/bridge/dispatch.js +272 -40
  41. package/dist/bridge/fanouts.d.ts +7 -1
  42. package/dist/bridge/fanouts.js +39 -4
  43. package/dist/bridge/folder-trust.d.ts +56 -0
  44. package/dist/bridge/folder-trust.js +195 -0
  45. package/dist/bridge/grants.d.ts +22 -1
  46. package/dist/bridge/grants.js +57 -9
  47. package/dist/bridge/hand-off.d.ts +21 -9
  48. package/dist/bridge/hand-off.js +58 -45
  49. package/dist/bridge/harness-status.d.ts +11 -0
  50. package/dist/bridge/harness-status.js +32 -0
  51. package/dist/bridge/harnesses.d.ts +39 -0
  52. package/dist/bridge/harnesses.js +65 -0
  53. package/dist/bridge/health.d.ts +2 -0
  54. package/dist/bridge/health.js +1 -1
  55. package/dist/bridge/herdr.d.ts +11 -2
  56. package/dist/bridge/herdr.js +98 -23
  57. package/dist/bridge/hook-fast.d.ts +4 -0
  58. package/dist/bridge/hook-fast.js +68 -0
  59. package/dist/bridge/install.d.ts +16 -1
  60. package/dist/bridge/install.js +88 -21
  61. package/dist/bridge/launch-brief.d.ts +96 -0
  62. package/dist/bridge/launch-brief.js +164 -0
  63. package/dist/bridge/model-switch.d.ts +3 -0
  64. package/dist/bridge/model-switch.js +17 -1
  65. package/dist/bridge/models.d.ts +8 -4
  66. package/dist/bridge/models.js +24 -8
  67. package/dist/bridge/mux-wire.d.ts +9 -0
  68. package/dist/bridge/mux-wire.js +19 -0
  69. package/dist/bridge/opencode-pane-server.d.ts +113 -0
  70. package/dist/bridge/opencode-pane-server.js +332 -0
  71. package/dist/bridge/opencode-panes.d.ts +111 -0
  72. package/dist/bridge/opencode-panes.js +295 -0
  73. package/dist/bridge/pane-accounts.d.ts +8 -0
  74. package/dist/bridge/pane-accounts.js +46 -0
  75. package/dist/bridge/prompt-startup.d.ts +5 -0
  76. package/dist/bridge/prompt-startup.js +24 -0
  77. package/dist/bridge/protocol.d.ts +5 -0
  78. package/dist/bridge/protocol.js +4 -0
  79. package/dist/bridge/push.d.ts +5 -4
  80. package/dist/bridge/push.js +6 -4
  81. package/dist/bridge/questions.d.ts +37 -2
  82. package/dist/bridge/questions.js +158 -15
  83. package/dist/bridge/resources.d.ts +9 -3
  84. package/dist/bridge/resources.js +24 -8
  85. package/dist/bridge/schedule-format.d.ts +2 -0
  86. package/dist/bridge/schedule-format.js +3 -0
  87. package/dist/bridge/schedule-launch.d.ts +2 -1
  88. package/dist/bridge/schedule-launch.js +23 -53
  89. package/dist/bridge/schedule-watch.d.ts +10 -1
  90. package/dist/bridge/schedule-watch.js +54 -2
  91. package/dist/bridge/server-launch.d.ts +22 -5
  92. package/dist/bridge/server-launch.js +225 -29
  93. package/dist/bridge/server-overview.d.ts +3 -3
  94. package/dist/bridge/server-overview.js +22 -14
  95. package/dist/bridge/server-pane-routes.d.ts +2 -0
  96. package/dist/bridge/server-pane-routes.js +145 -15
  97. package/dist/bridge/server-routes.d.ts +7 -0
  98. package/dist/bridge/server-routes.js +163 -35
  99. package/dist/bridge/server-stream.d.ts +2 -0
  100. package/dist/bridge/server-stream.js +22 -8
  101. package/dist/bridge/server.d.ts +6 -1
  102. package/dist/bridge/server.js +44 -12
  103. package/dist/bridge/session-activity.d.ts +81 -0
  104. package/dist/bridge/session-activity.js +117 -0
  105. package/dist/bridge/session-rename.d.ts +48 -0
  106. package/dist/bridge/session-rename.js +190 -0
  107. package/dist/bridge/session-servers.js +2 -2
  108. package/dist/bridge/settings-switch.d.ts +60 -0
  109. package/dist/bridge/settings-switch.js +287 -0
  110. package/dist/bridge/speech-voice.d.ts +55 -0
  111. package/dist/bridge/speech-voice.js +132 -0
  112. package/dist/bridge/speech.d.ts +70 -11
  113. package/dist/bridge/speech.js +169 -41
  114. package/dist/bridge/terminal-herdr.js +9 -3
  115. package/dist/bridge/terminal-tmux.d.ts +3 -3
  116. package/dist/bridge/terminal-tmux.js +24 -9
  117. package/dist/bridge/terminal.d.ts +27 -4
  118. package/dist/bridge/terminal.js +8 -1
  119. package/dist/bridge/transcript-claude.js +57 -12
  120. package/dist/bridge/transcript-codex.d.ts +0 -2
  121. package/dist/bridge/transcript-codex.js +29 -4
  122. package/dist/bridge/transcript-preview.d.ts +1 -0
  123. package/dist/bridge/transcript-preview.js +24 -4
  124. package/dist/bridge/transcripts.d.ts +15 -2
  125. package/dist/bridge/transcripts.js +47 -16
  126. package/dist/bridge/turn-records.d.ts +85 -0
  127. package/dist/bridge/turn-records.js +143 -0
  128. package/dist/bridge/uploads.d.ts +3 -0
  129. package/dist/bridge/uploads.js +14 -0
  130. package/dist/bridge/usage.d.ts +39 -10
  131. package/dist/bridge/usage.js +155 -44
  132. package/dist/bridge-hook.mjs +19169 -13176
  133. package/dist/cli/claude-unmanaged.d.ts +12 -0
  134. package/dist/cli/claude-unmanaged.js +105 -0
  135. package/dist/cli/schedules.js +2 -1
  136. package/dist/cli/session-start.js +10 -1
  137. package/dist/cli/session-stop.js +9 -1
  138. package/dist/cli-registry.js +24 -5
  139. package/dist/data/task-receipts.d.ts +19 -0
  140. package/dist/data/task-receipts.js +68 -0
  141. package/dist/data/tasks.js +4 -1
  142. package/dist/generated/memory-ui-graph.browser.js +63 -63
  143. package/dist/graph-core/model.js +24 -3
  144. package/dist/graph-core/types.d.ts +4 -1
  145. package/dist/graph-core/types.js +1 -0
  146. package/dist/init/init-preset.js +7 -3
  147. package/dist/init/init-uninstall.js +2 -11
  148. package/dist/init/teardown.d.ts +3 -0
  149. package/dist/init/teardown.js +47 -0
  150. package/dist/link/context.js +21 -9
  151. package/dist/mcp/plugin-mode.js +1 -1
  152. package/dist/memory-ui-graph.runtime.js +63 -63
  153. package/dist/modules/code-package.d.ts +1 -0
  154. package/dist/modules/code-package.js +36 -7
  155. package/dist/modules/registry.js +14 -13
  156. package/dist/profile-store.d.ts +6 -0
  157. package/dist/profile-store.js +25 -1
  158. package/dist/shell/graph/glyphs.js +4 -0
  159. package/dist/shell/graph/graph-view.js +2 -0
  160. package/dist/status.js +7 -1
  161. package/dist/sync/task-claim.js +3 -2
  162. package/dist/task/lifecycle.js +25 -4
  163. package/dist/test-global-setup.js +5 -0
  164. package/dist/tools/dispatch.js +35 -2
  165. package/dist/tools/tasks.js +10 -1
  166. package/package.json +1 -1
  167. package/plugins/opencode/phren-transcript.js +87 -4
  168. package/starter/global/skills/conductor/SKILL.md +17 -2
@@ -2,43 +2,112 @@ import { once } from "node:events";
2
2
  import { z } from "zod";
3
3
  import { BridgeError } from "./protocol.js";
4
4
  import { readSpeechKey } from "./speech-key.js";
5
+ import { FALLBACK_SPEECH_MODEL, resolveSpeechModel, resolveSpeechVoice, voiceId } from "./speech-voice.js";
6
+ export { DEFAULT_SPEECH_MODEL, DEFAULT_SPEECH_VOICE, FALLBACK_SPEECH_MODEL } from "./speech-voice.js";
5
7
  /** Spoken replies for the phone's talk mode. The phone sends a sentence; the
6
8
  * Hook voices it with ElevenLabs and streams the audio back. The API key is
7
9
  * read on this computer, used only in the request to ElevenLabs, and never
8
10
  * appears in a response, including errors. */
9
- /** Raw signed 16-bit little-endian mono PCM, so the phone can queue it
10
- * straight into its audio engine without decoding. */
11
+ /** What a phone that names no `formats` gets, as every phone did before
12
+ * `speechFormats`: raw signed 16-bit little-endian mono PCM at 24 kHz, which
13
+ * it queues straight into its audio engine without decoding. */
11
14
  export const SPEECH_AUDIO = "pcm_s16le;rate=24000;channels=1";
12
- const OUTPUT_FORMAT = "pcm_24000";
13
- /** ElevenLabs' lowest-latency model. */
14
- export const SPEECH_MODEL = "eleven_flash_v2_5";
15
- /** River: relaxed, neutral and informative. PHREN_SPEECH_VOICE overrides it. */
16
- export const DEFAULT_SPEECH_VOICE = "SAz9YHcvj6GT2YYXdXww";
15
+ /** ElevenLabs output formats the Hook can serve, best first. Each account
16
+ * plan allows some of them (Creator refuses pcm_44100, which is Pro and
17
+ * above); the Hook learns which from ElevenLabs' refusal rather than a
18
+ * hard-coded plan table. pcm_24000 works on every plan and every phone. */
19
+ export const SPEECH_FORMATS = ["pcm_44100", "mp3_44100_192", "pcm_24000"];
20
+ const BASE_FORMAT = "pcm_24000";
21
+ /** How each format is described to the phone: `audioFormat` in the JSON reply
22
+ * and `X-Phren-Audio` on the streamed one, plus the sample rate on its own. */
23
+ export const SPEECH_FORMAT_INFO = {
24
+ pcm_44100: { audio: "pcm_s16le;rate=44100;channels=1", sampleRate: 44_100, contentType: "application/octet-stream" },
25
+ mp3_44100_192: { audio: "mp3;rate=44100;bitrate=192000;channels=1", sampleRate: 44_100, contentType: "audio/mpeg" },
26
+ pcm_24000: { audio: SPEECH_AUDIO, sampleRate: 24_000, contentType: "application/octet-stream" },
27
+ };
28
+ /** Talk mode waits for the whole sentence on the timestamped path, so a model
29
+ * whose recent replies took longer than this to start playing is set aside
30
+ * for FALLBACK_HOLD_MS. Measured 2026-09-28 on a 95-character reply with the
31
+ * owner's voice: v4 Turbo ~200-400 ms to first streamed byte and ~1.1 s for
32
+ * the timestamped reply; Flash v2.5 ~180-460 ms and ~0.4 s. 1.5 s leaves v4
33
+ * Turbo headroom on a normal day and catches a slow one. */
34
+ export const SPEECH_SLOW_MS = 1_500;
35
+ /** Only replies this short are timed: a long one is slow for its length, not
36
+ * because the model is. */
37
+ const TIMED_TEXT = 200;
38
+ /** How long a failing or slow model, or a refused format, is set aside. */
39
+ export const FALLBACK_HOLD_MS = 10 * 60_000;
40
+ const FORMAT_HOLD_MS = 6 * 60 * 60_000;
17
41
  const MAX_TEXT = 2_000;
18
42
  export const speechRequest = z.object({
19
43
  text: z.string().trim().min(1).max(MAX_TEXT),
20
44
  /** Answer JSON with the audio and when each character is spoken, so the
21
45
  * phone can highlight the word being read (talk mode's karaoke). */
22
46
  timestamps: z.boolean().optional(),
47
+ /** A voice the phone picked; otherwise this computer's setting. */
48
+ voice: voiceId.optional(),
49
+ /** The output formats the phone plays (`SPEECH_FORMATS` names). Without
50
+ * it, pcm_24000, which older phones assume. Names this Hook doesn't know
51
+ * (a newer phone's) are dropped before validation, never refused. */
52
+ formats: z.preprocess(value => Array.isArray(value) ? [...new Set(value)].filter(name => SPEECH_FORMATS.includes(name)) : undefined, z.array(z.enum(SPEECH_FORMATS)).max(SPEECH_FORMATS.length).optional()),
23
53
  });
54
+ /** What the Hook learned about this account: formats its plan refused and
55
+ * models set aside for failing or being slow, each until a time, and the
56
+ * recent start-of-audio times per model. One per Hook process. */
57
+ export class SpeechState {
58
+ now;
59
+ refused = new Map();
60
+ benched = new Map();
61
+ latency = new Map();
62
+ constructor(now = Date.now) {
63
+ this.now = now;
64
+ }
65
+ formatAllowed(format) { return (this.refused.get(format) ?? 0) <= this.now(); }
66
+ refuseFormat(format) { this.refused.set(format, this.now() + FORMAT_HOLD_MS); }
67
+ benchedReason(model) {
68
+ const entry = this.benched.get(model);
69
+ return entry && entry.until > this.now() ? entry.reason : undefined;
70
+ }
71
+ bench(model, reason) {
72
+ this.benched.set(model, { until: this.now() + FALLBACK_HOLD_MS, reason });
73
+ this.latency.delete(model);
74
+ }
75
+ /** Records how long a reply took to start; benches the model when the median
76
+ * of its last three is over SPEECH_SLOW_MS. */
77
+ recordLatency(model, ms) {
78
+ const samples = [...(this.latency.get(model) ?? []), ms].slice(-3);
79
+ this.latency.set(model, samples);
80
+ const median = [...samples].sort((a, b) => a - b)[Math.floor(samples.length / 2)];
81
+ if (samples.length === 3 && median > SPEECH_SLOW_MS)
82
+ this.bench(model, "slow");
83
+ }
84
+ }
85
+ const sharedState = new SpeechState();
86
+ /** ElevenLabs' machine-readable reason (`detail.status`), never its text. */
87
+ async function upstreamCode(upstream) {
88
+ try {
89
+ return String((await upstream.json()).detail?.status ?? "");
90
+ }
91
+ catch {
92
+ return "";
93
+ }
94
+ }
24
95
  /** A fixed message per ElevenLabs failure: its own response text is never
25
96
  * passed on. */
26
97
  export async function speechError(upstream) {
27
- let detail = "";
28
- try {
29
- detail = String((await upstream.json()).detail?.status ?? "");
30
- }
31
- catch { /* not JSON */ }
98
+ return speechErrorFor(upstream.status, await upstreamCode(upstream));
99
+ }
100
+ function speechErrorFor(status, detail) {
32
101
  if (detail === "quota_exceeded")
33
102
  return new BridgeError(402, "The ElevenLabs quota on this computer's account is used up.", { code: "speech-quota" });
34
- switch (upstream.status) {
103
+ switch (status) {
35
104
  case 401:
36
105
  case 403: return new BridgeError(502, "ElevenLabs refused this computer's key.", { code: "speech-rejected" });
37
106
  case 404: return new BridgeError(502, "ElevenLabs doesn't know the configured voice.", { code: "speech-voice" });
38
107
  case 400:
39
108
  case 422: return new BridgeError(400, "ElevenLabs couldn't voice this text.", { code: "speech-invalid" });
40
109
  case 429: return new BridgeError(429, "ElevenLabs is busy. Try again shortly.", { code: "speech-busy" });
41
- default: return new BridgeError(502, `ElevenLabs failed (HTTP ${upstream.status}).`, { code: "speech-failed" });
110
+ default: return new BridgeError(502, `ElevenLabs failed (HTTP ${status}).`, { code: "speech-failed" });
42
111
  }
43
112
  }
44
113
  /** A reply as it should sound: markdown the agent wrote for the chat bubble
@@ -74,14 +143,15 @@ export function speakableText(text) {
74
143
  }
75
144
  /** Starts ElevenLabs' streaming synthesis and returns its audio body. */
76
145
  export async function synthesizeSpeech(text, signal, options = {}) {
77
- const upstream = await elevenLabs("stream", text, signal, options);
146
+ const { upstream, model, format, started } = await elevenLabs("stream", text, signal, options);
78
147
  if (!upstream.body)
79
148
  throw await speechError(upstream);
80
- return upstream.body;
149
+ timed(text, model, started, options);
150
+ return { body: upstream.body, model, format };
81
151
  }
82
152
  /** Voices the text in one piece with ElevenLabs' character alignment. */
83
153
  export async function synthesizeTimedSpeech(text, signal, options = {}) {
84
- const upstream = await elevenLabs("with-timestamps", text, signal, options);
154
+ const { upstream, model, format, started } = await elevenLabs("with-timestamps", text, signal, options);
85
155
  let body;
86
156
  try {
87
157
  body = (await upstream.json());
@@ -91,7 +161,16 @@ export async function synthesizeTimedSpeech(text, signal, options = {}) {
91
161
  }
92
162
  if (typeof body.audio_base64 !== "string")
93
163
  throw new BridgeError(502, "ElevenLabs sent an unreadable reply.", { code: "speech-failed" });
94
- return { audio: body.audio_base64, alignment: alignmentOf(body.alignment) };
164
+ // Talk mode plays nothing until this whole reply is in.
165
+ timed(text, model, started, options);
166
+ return { audio: body.audio_base64, alignment: alignmentOf(body.alignment), model, format };
167
+ }
168
+ /** Times a short reply from the chosen model (never the fallback, which has
169
+ * nothing to fall back to). */
170
+ function timed(text, model, started, options) {
171
+ if (model === FALLBACK_SPEECH_MODEL || text.length > TIMED_TEXT)
172
+ return;
173
+ (options.state ?? sharedState).recordLatency(model, (options.now ?? Date.now)() - started);
95
174
  }
96
175
  /** ElevenLabs' alignment, kept only when its three lists line up. */
97
176
  export function alignmentOf(raw) {
@@ -104,31 +183,73 @@ export function alignmentOf(raw) {
104
183
  return null;
105
184
  return { characters: characters, starts: starts, ends: ends };
106
185
  }
186
+ /** The plan doesn't allow this output format (Creator: "Output format
187
+ * 'pcm_44100' is only available on the Pro tier and above", 403
188
+ * `output_format_not_allowed`). */
189
+ function formatRefused(status, code) {
190
+ return (status === 400 || status === 403 || status === 422) && /output_format/.test(code);
191
+ }
192
+ /** A failure another model may not have: the model itself refused or
193
+ * unknown, or ElevenLabs erroring. Not the key, quota, voice or rate limit. */
194
+ function modelFailed(status, code) {
195
+ if (status === 429 || code === "quota_exceeded" || code === "invalid_api_key")
196
+ return false;
197
+ return status >= 500 || /model/.test(code);
198
+ }
199
+ /** Asks ElevenLabs for the best format the phone plays and the plan allows,
200
+ * with the chosen model, then Flash v2.5 when that model fails or has been
201
+ * slow. A refused format is skipped for FORMAT_HOLD_MS, a failed or slow
202
+ * model for FALLBACK_HOLD_MS. */
107
203
  async function elevenLabs(endpoint, text, signal, options) {
108
204
  const key = await (options.key ?? readSpeechKey)();
109
205
  if (!key)
110
206
  throw new BridgeError(503, "Spoken replies aren't set up on this computer: it has no ElevenLabs key.", { code: "speech-unconfigured" });
111
- const voice = options.voice ?? process.env.PHREN_SPEECH_VOICE ?? DEFAULT_SPEECH_VOICE;
112
- const url = `https://api.elevenlabs.io/v1/text-to-speech/${encodeURIComponent(voice)}/${endpoint}?output_format=${OUTPUT_FORMAT}`;
113
- let upstream;
114
- try {
115
- upstream = await (options.fetch ?? fetch)(url, {
116
- method: "POST", signal,
117
- headers: { "xi-api-key": key, "Content-Type": "application/json" },
118
- body: JSON.stringify({ text, model_id: SPEECH_MODEL, voice_settings: { stability: 0.6, similarity_boost: 0.75 } }),
119
- });
120
- }
121
- catch {
122
- throw new BridgeError(502, "Couldn't reach ElevenLabs from this computer.", { code: "speech-unreachable" });
207
+ const { voice } = await resolveSpeechVoice(options.voice);
208
+ const state = options.state ?? sharedState, now = options.now ?? Date.now;
209
+ const chosen = options.model ?? (await resolveSpeechModel()).model;
210
+ const models = chosen === FALLBACK_SPEECH_MODEL ? [chosen] : state.benchedReason(chosen) ? [FALLBACK_SPEECH_MODEL] : [chosen, FALLBACK_SPEECH_MODEL];
211
+ const accepted = new Set(options.formats ?? []);
212
+ let failure;
213
+ models: for (const model of models) {
214
+ // Per model, so a format refused under one isn't tried again under the next.
215
+ const formats = SPEECH_FORMATS.filter(format => format === BASE_FORMAT || (accepted.has(format) && state.formatAllowed(format)));
216
+ for (const format of formats) {
217
+ const url = `https://api.elevenlabs.io/v1/text-to-speech/${encodeURIComponent(voice)}/${endpoint}?output_format=${format}`;
218
+ const started = now();
219
+ let upstream;
220
+ try {
221
+ upstream = await (options.fetch ?? fetch)(url, {
222
+ method: "POST", signal,
223
+ headers: { "xi-api-key": key, "Content-Type": "application/json" },
224
+ body: JSON.stringify({ text, model_id: model, voice_settings: { stability: 0.6, similarity_boost: 0.75 } }),
225
+ });
226
+ }
227
+ catch {
228
+ throw new BridgeError(502, "Couldn't reach ElevenLabs from this computer.", { code: "speech-unreachable" });
229
+ }
230
+ if (upstream.ok)
231
+ return { upstream, model, format, started };
232
+ const code = await upstreamCode(upstream);
233
+ if (format !== BASE_FORMAT && formatRefused(upstream.status, code)) {
234
+ state.refuseFormat(format);
235
+ continue;
236
+ }
237
+ failure = speechErrorFor(upstream.status, code);
238
+ if (model !== FALLBACK_SPEECH_MODEL && modelFailed(upstream.status, code)) {
239
+ state.bench(model, "failed");
240
+ continue models;
241
+ }
242
+ throw failure;
243
+ }
123
244
  }
124
- if (!upstream.ok)
125
- throw await speechError(upstream);
126
- return upstream;
245
+ throw failure ?? new BridgeError(502, "ElevenLabs failed.", { code: "speech-failed" });
127
246
  }
128
247
  /** POST /v1/speech: writes the audio to the phone as ElevenLabs produces it.
129
- * With `timestamps`, answers JSON instead: `{ audio, audioFormat, alignment }`,
130
- * the audio base64 in the same PCM format and the alignment null when
131
- * ElevenLabs sent none.
248
+ * With `timestamps`, answers JSON instead: `{ audio, audioFormat, sampleRate,
249
+ * format, model, alignment }`, the audio base64 in the format served and the
250
+ * alignment null when ElevenLabs sent none. The streamed reply names its
251
+ * format in `X-Phren-Audio` and `X-Phren-Audio-Rate`. A phone that sends no
252
+ * `formats` always gets pcm_24000.
132
253
  * Failures before the first byte are thrown for the route's JSON error; a
133
254
  * failure mid-stream cuts the response off, which the phone treats as an
134
255
  * error. The phone hanging up cancels the ElevenLabs request. */
@@ -139,20 +260,27 @@ export async function streamSpeech(data, response, options = {}) {
139
260
  throw new BridgeError(400, "There is nothing to say in this reply.", { code: "speech-invalid" });
140
261
  // With timestamps, the alignment covers these spoken words, not the markdown.
141
262
  const { timestamps } = request;
263
+ if (request.voice)
264
+ options = { ...options, voice: request.voice };
265
+ options = { ...options, formats: request.formats ?? [] };
142
266
  const abort = new AbortController();
143
267
  response.once("close", () => { if (!response.writableEnded)
144
268
  abort.abort(); });
145
269
  if (timestamps) {
146
- const { audio, alignment } = await synthesizeTimedSpeech(text, abort.signal, options);
270
+ const { audio, alignment, model, format } = await synthesizeTimedSpeech(text, abort.signal, options);
271
+ const info = SPEECH_FORMAT_INFO[format];
147
272
  response.statusCode = 200;
148
273
  response.setHeader("Content-Type", "application/json");
149
- response.end(JSON.stringify({ audio, audioFormat: SPEECH_AUDIO, alignment }));
274
+ response.end(JSON.stringify({ audio, audioFormat: info.audio, sampleRate: info.sampleRate, format, model, alignment }));
150
275
  return;
151
276
  }
152
- const audio = await synthesizeSpeech(text, abort.signal, options);
277
+ const { body: audio, model, format } = await synthesizeSpeech(text, abort.signal, options);
278
+ const info = SPEECH_FORMAT_INFO[format];
153
279
  response.statusCode = 200;
154
- response.setHeader("Content-Type", "application/octet-stream");
155
- response.setHeader("X-Phren-Audio", SPEECH_AUDIO);
280
+ response.setHeader("Content-Type", info.contentType);
281
+ response.setHeader("X-Phren-Audio", info.audio);
282
+ response.setHeader("X-Phren-Audio-Rate", String(info.sampleRate));
283
+ response.setHeader("X-Phren-Speech-Model", model);
156
284
  try {
157
285
  for await (const chunk of audio) {
158
286
  if (!response.write(chunk))
@@ -2,7 +2,7 @@
2
2
  // socket API. It calls herdr.ts's exported `rpc`, the seam the bridge tests
3
3
  // fake, so a test that records Herdr requests sees exactly what it did before
4
4
  // the provider existed.
5
- import { rpc, snapshot } from "./herdr.js";
5
+ import { herdrSocketPath, rpc, snapshot } from "./herdr.js";
6
6
  import { object, objects } from "./protocol.js";
7
7
  const text = (value) => typeof value === "string" && value ? value : undefined;
8
8
  /** A Herdr snapshot's panes in the provider's shape; Herdr's agent report becomes hints. */
@@ -43,14 +43,20 @@ export const herdrTerminal = {
43
43
  else
44
44
  await rpc(server, "agent.prompt", { target: pane, text });
45
45
  },
46
- async create(server, { workspace, label, cwd }) {
47
- await rpc(server, workspace ? "tab.create" : "workspace.create", { workspace_id: workspace, label, cwd, focus: false, env: {} });
46
+ async create(server, { workspace, label, cwd, env }) {
47
+ await rpc(server, workspace ? "tab.create" : "workspace.create", { workspace_id: workspace, label, cwd, focus: false, env: env ?? {} });
48
48
  },
49
+ // `agent.start` takes no environment; the pane's shell got it at `create`.
49
50
  async startAgent(server, pane, { name, kind, args, timeoutMs }) {
50
51
  // Herdr waits up to `timeout_ms` for the agent to become ready; the socket waits a little longer.
51
52
  await rpc(server, "agent.start", { name, kind, pane_id: pane, timeout_ms: timeoutMs, ...(args.length ? { args } : {}) }, undefined, timeoutMs + 5_000);
52
53
  },
54
+ // What Herdr sets in its own panes (herdrPaneFromEnv reads them back).
55
+ paneEnv(server, { workspace, tab, pane }) {
56
+ return { HERDR_ENV: "1", HERDR_SOCKET_PATH: herdrSocketPath(server), HERDR_WORKSPACE_ID: workspace, HERDR_TAB_ID: tab, HERDR_PANE_ID: pane };
57
+ },
53
58
  async focusPane(server, pane) { await rpc(server, "pane.focus", { pane_id: pane }); },
59
+ async renamePane(server, pane, label) { await rpc(server, "pane.rename", { pane_id: pane, label }); },
54
60
  async groupAction(server, operation, { workspace, tab }, label) {
55
61
  await rpc(server, `${tab ? "tab" : "workspace"}.${operation}`, { ...(tab ? { tab_id: tab } : { workspace_id: workspace }), ...(label ? { label } : {}) });
56
62
  },
@@ -60,7 +60,7 @@ interface Proc {
60
60
  args: string;
61
61
  }
62
62
  export declare function parseProcesses(text: string): Proc[];
63
- declare const FIELDS: readonly ["session_id", "session_name", "session_attached", "session_activity", "window_id", "window_name", "window_active", "pane_id", "pane_pid", "pane_tty", "pane_active", "pane_current_path", "pane_current_command", "@phren_agent", "pane_title"];
63
+ declare const FIELDS: readonly ["session_id", "session_name", "session_attached", "session_activity", "window_id", "window_name", "window_active", "pane_id", "pane_pid", "pane_tty", "pane_active", "pane_current_path", "pane_current_command", "@phren_agent", "pane_title", "@phren_label"];
64
64
  type Row = Record<(typeof FIELDS)[number], string>;
65
65
  export declare function parsePanes(text: string): Row[];
66
66
  /** One tmux server in the shape of the Hook's pane snapshot (the shape
@@ -74,8 +74,8 @@ export declare function sendKeysCalls(pane: string, keys: string[]): string[][];
74
74
  export declare const tmuxTerminal: TerminalProvider;
75
75
  /** The tmux servers the Hook drives, as `/v1/muxes` lists servers: the owner's
76
76
  * servers that answer, and (unless `hidden: false`) the hidden server whenever
77
- * tmux is installed (a launch starts it). `kind` stays "herdr", the phone's name for the Hook's
78
- * session protocol; `terminal` names the multiplexer. */
77
+ * tmux is installed (a launch starts it). An already running hidden server
78
+ * remains discoverable beside Herdr too. `kind` names the actual multiplexer. */
79
79
  export declare function tmuxServers(options?: {
80
80
  hidden?: boolean;
81
81
  }): Promise<Json[]>;
@@ -218,7 +218,7 @@ function foreground(processes, paneTty) {
218
218
  return processes.filter(p => (p.tty === tty || `tty${p.tty}` === tty) && p.tpgid > 0 && p.pgid === p.tpgid).sort((a, b) => a.pid - b.pid);
219
219
  }
220
220
  const FIELDS = ["session_id", "session_name", "session_attached", "session_activity", "window_id", "window_name", "window_active",
221
- "pane_id", "pane_pid", "pane_tty", "pane_active", "pane_current_path", "pane_current_command", "@phren_agent", "pane_title"];
221
+ "pane_id", "pane_pid", "pane_tty", "pane_active", "pane_current_path", "pane_current_command", "@phren_agent", "pane_title", "@phren_label"];
222
222
  const FORMAT = FIELDS.map(field => `#{${field}}`).join("\t");
223
223
  export function parsePanes(text) {
224
224
  return text.split("\n").flatMap(line => {
@@ -282,7 +282,7 @@ export async function tmuxSnapshot(server) {
282
282
  const name = row["@phren_agent"] || undefined;
283
283
  const title = row.pane_title && row.pane_title !== host && row.pane_title !== short ? row.pane_title : undefined;
284
284
  panes.push({ pane_id: pane, tab_id: tab, workspace_id: workspace, terminal_id: terminal, cwd: row.pane_current_path || undefined,
285
- foreground_cwd: row.pane_current_path || undefined, title,
285
+ foreground_cwd: row.pane_current_path || undefined, title, ...(row["@phren_label"] ? { label: row["@phren_label"] } : {}),
286
286
  ...(agent ? { agent, agent_status: status?.status ?? (hooked ? "unknown" : "idle"), ...(status?.seq ? { state_change_seq: status.seq } : {}) } : {}),
287
287
  ...(agent && name ? { agent_name: name } : {}) });
288
288
  if (agent && name)
@@ -304,7 +304,7 @@ export async function tmuxSnapshot(server) {
304
304
  /** The Hook's key names as tmux key names; undefined for a literal character. */
305
305
  export function tmuxKey(key) {
306
306
  const named = { enter: "Enter", esc: "Escape", escape: "Escape", up: "Up", down: "Down", left: "Left", right: "Right",
307
- tab: "Tab", space: "Space", backspace: "BSpace", home: "Home", end: "End", pageup: "PPage", pagedown: "NPage" };
307
+ tab: "Tab", "shift+tab": "BTab", space: "Space", backspace: "BSpace", home: "Home", end: "End", pageup: "PPage", pagedown: "NPage" };
308
308
  if ([...key].length === 1)
309
309
  return undefined;
310
310
  const lower = key.toLowerCase();
@@ -427,7 +427,7 @@ export const tmuxTerminal = {
427
427
  const taken = new Set((await tmux(server, ["list-sessions", "-F", "#{session_name}"]).catch(() => "")).split("\n").filter(Boolean));
428
428
  await tmux(server, ["new-session", "-d", "-s", sessionName(label, taken), "-x", "200", "-y", "50", ...directory, ...name]);
429
429
  },
430
- async startAgent(server, pane, { name, kind, args, timeoutMs }) {
430
+ async startAgent(server, pane, { name, kind, args, timeoutMs, env }) {
431
431
  if (!["claude", "codex", "copilot", "opencode"].includes(kind))
432
432
  throw new BridgeError(400, "This agent cannot be started in tmux.");
433
433
  await requireDirectExec();
@@ -440,7 +440,9 @@ export const tmuxTerminal = {
440
440
  // the pane falls back to that shell when it exits. The harness and its
441
441
  // arguments are the script's positional parameters, never script text.
442
442
  const shell = loginShell();
443
- await tmux(server, ["respawn-pane", "-k", "-t", target, ...(row.pane_current_path ? ["-c", row.pane_current_path] : []),
443
+ // Variables for the agent alone (a dispatch id) ride on the respawn.
444
+ const variables = Object.entries(env ?? {}).flatMap(([key, value]) => ["-e", `${key}=${value}`]);
445
+ await tmux(server, ["respawn-pane", "-k", "-t", target, ...(row.pane_current_path ? ["-c", row.pane_current_path] : []), ...variables,
444
446
  "--", shell, "-l", "-c", 'shell="$1"; shift; "$@"; exec "$shell" -l', "phren", shell, kind, ...args]);
445
447
  // Started once the harness is the pane's foreground program.
446
448
  const deadline = Date.now() + Math.min(timeoutMs, 30_000);
@@ -456,6 +458,17 @@ export const tmuxTerminal = {
456
458
  await deps.sleep(250);
457
459
  }
458
460
  },
461
+ // tmuxPaneFromEnv reads the socket from TMUX's first field and the pane
462
+ // from TMUX_PANE; the server pid and session index are not used.
463
+ paneEnv(server, { pane }) {
464
+ const socket = socketOf(server), folder = tmuxSocketFolders()[0];
465
+ const file = socketPaths.get(socket) ?? (folder ? path.join(folder, socket) : undefined);
466
+ return file ? { TMUX: `${file},0,0`, TMUX_PANE: toTmuxId(pane, "p") } : undefined;
467
+ },
468
+ // A pane user option, not `select-pane -T`: agents overwrite the pane title.
469
+ async renamePane(server, pane, label) {
470
+ await tmux(server, ["set-option", "-p", "-t", toTmuxId(pane, "p"), "@phren_label", label.replace(/[\x00-\x1f\x7f]/g, " ")]);
471
+ },
459
472
  async focusPane(server, pane) {
460
473
  const target = toTmuxId(pane, "p");
461
474
  await tmux(server, ["select-window", "-t", target]);
@@ -495,13 +508,15 @@ async function ownerServers() {
495
508
  }
496
509
  /** The tmux servers the Hook drives, as `/v1/muxes` lists servers: the owner's
497
510
  * servers that answer, and (unless `hidden: false`) the hidden server whenever
498
- * tmux is installed (a launch starts it). `kind` stays "herdr", the phone's name for the Hook's
499
- * session protocol; `terminal` names the multiplexer. */
511
+ * tmux is installed (a launch starts it). An already running hidden server
512
+ * remains discoverable beside Herdr too. `kind` names the actual multiplexer. */
500
513
  export async function tmuxServers(options = {}) {
501
514
  if (!deps.binary())
502
515
  return [];
503
- return [...await ownerServers(), ...(options.hidden ?? true ? [TMUX_HIDDEN] : [])]
504
- .map(name => ({ id: `tmux:${name}`, kind: "herdr", terminal: "tmux", session: name, running: true }));
516
+ const includeHidden = options.hidden ?? true;
517
+ const hiddenRunning = includeHidden || await tmux(TMUX_HIDDEN, ["list-sessions", "-F", "#{session_id}"], { timeoutMs: 3_000 }).then(() => true, () => false);
518
+ return [...await ownerServers(), ...(hiddenRunning ? [TMUX_HIDDEN] : [])]
519
+ .map(name => ({ id: `tmux:${name}`, kind: "tmux", terminal: "tmux", session: name, running: true }));
505
520
  }
506
521
  export async function tmuxHealth() {
507
522
  if (process.env.PHREN_TMUX === "off")
@@ -50,22 +50,28 @@ export interface ScreenRead {
50
50
  format?: "ansi";
51
51
  timeoutMs?: number;
52
52
  }
53
- /** A new pane: a tab in `workspace`, or a new workspace when it is absent. */
53
+ /** A new pane: a tab in `workspace`, or a new workspace when it is absent.
54
+ * `env` is added to the pane's shell environment, so an agent started there
55
+ * inherits it (Herdr takes variables only here, at pane creation). */
54
56
  export interface PanePlacement {
55
57
  workspace?: string;
56
58
  label?: string;
57
59
  cwd?: string;
60
+ env?: Record<string, string>;
58
61
  }
59
- /** Starts an agent in an existing, empty pane. */
62
+ /** Starts an agent in an existing, empty pane. `env` is the same variables as
63
+ * the pane's placement, for a provider that starts the agent in a fresh
64
+ * process of its own (tmux respawns the pane). */
60
65
  export interface AgentStart {
61
66
  name: string;
62
67
  kind: string;
63
68
  args: string[];
64
69
  timeoutMs: number;
70
+ env?: Record<string, string>;
65
71
  }
66
72
  /**
67
73
  * Key names are the Hook's vocabulary: "enter", "esc", "up", "down", "tab",
68
- * "space", "alt+Up" and single characters. A provider maps them to its own.
74
+ * "space", "shift+tab", "alt+Up" and single characters. A provider maps them to its own.
69
75
  *
70
76
  * Every method rejects with a BridgeError when the multiplexer refuses or is
71
77
  * unreachable; the message is shown to the phone.
@@ -89,12 +95,23 @@ export interface TerminalProvider {
89
95
  processes(server: string, pane: string): Promise<PaneProcesses>;
90
96
  readScreen(server: string, pane: string, read: ScreenRead): Promise<string>;
91
97
  sendKeys(server: string, pane: string, keys: string[]): Promise<void>;
92
- /** Types `text` into the pane's agent and submits it. */
98
+ /** Types `text` and sends the submit key. Success acknowledges transport,
99
+ * not a submitted turn; the harness must confirm that separately. */
93
100
  prompt(server: string, pane: string, text: string, signal?: AbortSignal): Promise<void>;
94
101
  /** Opens a pane; the caller finds it in the next `listPanes`. */
95
102
  create(server: string, placement: PanePlacement): Promise<void>;
96
103
  startAgent(server: string, pane: string, agent: AgentStart): Promise<void>;
104
+ /** The variables a process started for `pane` outside it needs to be
105
+ * recognized as running there (a Codex app-server whose hooks report the
106
+ * pane). Absent where the multiplexer has none. */
107
+ paneEnv?(server: string, place: {
108
+ workspace: string;
109
+ tab: string;
110
+ pane: string;
111
+ }): Record<string, string> | undefined;
97
112
  focusPane(server: string, pane: string): Promise<void>;
113
+ /** Sets the pane's own label (Herdr's pane label, a tmux pane option), shown by the Hook as the session's name. */
114
+ renamePane(server: string, pane: string, label: string): Promise<void>;
98
115
  /** Focuses, renames or closes a whole tab (when `tab` is set) or workspace. */
99
116
  groupAction(server: string, operation: "focus" | "rename" | "close", group: {
100
117
  workspace?: string;
@@ -107,6 +124,12 @@ export interface TerminalProvider {
107
124
  export declare function terminalKind(server: string): "herdr" | "tmux";
108
125
  /** The multiplexer's name as the phone shows it in messages. */
109
126
  export declare function terminalName(server: string): string;
127
+ /** Stable source identity for overview/pane replies; agent source remains its harness. */
128
+ export declare function terminalMux(server: string): {
129
+ id: string;
130
+ kind: "herdr" | "tmux";
131
+ session: string;
132
+ };
110
133
  /** The provider for each server by its name: Herdr's or tmux's. */
111
134
  export declare const routedTerminal: TerminalProvider;
112
135
  /** True when a start or prompt was refused because the agent is still
@@ -1,5 +1,5 @@
1
1
  // What the Hook needs from the terminal multiplexer its agents run in: Herdr
2
- // (terminal-herdr.ts) or, on a computer without it, tmux (terminal-tmux.ts).
2
+ // (terminal-herdr.ts) and tmux (terminal-tmux.ts), including both on one computer.
3
3
  // Nothing Herdr- or tmux-specific may leak past a provider's own file.
4
4
  //
5
5
  // Identity (which conversation a pane runs) and agent status are not the
@@ -33,6 +33,11 @@ export function terminalKind(server) {
33
33
  }
34
34
  /** The multiplexer's name as the phone shows it in messages. */
35
35
  export function terminalName(server) { return terminalKind(server) === "tmux" ? "tmux" : "Herdr"; }
36
+ /** Stable source identity for overview/pane replies; agent source remains its harness. */
37
+ export function terminalMux(server) {
38
+ const kind = terminalKind(server);
39
+ return { id: `${kind}:${server}`, kind, session: server };
40
+ }
36
41
  const route = (server) => terminalKind(server) === "tmux" ? tmuxTerminal : herdrTerminal;
37
42
  /** The provider for each server by its name: Herdr's or tmux's. */
38
43
  export const routedTerminal = {
@@ -46,7 +51,9 @@ export const routedTerminal = {
46
51
  prompt: (server, pane, text, signal) => route(server).prompt(server, pane, text, signal),
47
52
  create: (server, placement) => route(server).create(server, placement),
48
53
  startAgent: (server, pane, agent) => route(server).startAgent(server, pane, agent),
54
+ paneEnv: (server, place) => route(server).paneEnv?.(server, place),
49
55
  focusPane: (server, pane) => route(server).focusPane(server, pane),
56
+ renamePane: (server, pane, label) => route(server).renamePane(server, pane, label),
50
57
  groupAction: (server, operation, group, label) => route(server).groupAction(server, operation, group, label),
51
58
  };
52
59
  /** True when a start or prompt was refused because the agent is still