@agentprojectcontext/apx 1.80.2 → 1.89.1

package/src/core/tasks/columns.js

@@ -0,0 +1,136 @@
+// Board columns: ONE catalog, shared by every project; each project picks which
+// of them it shows.
+//
+// This settles a real tension in how one person uses one tool. Dev work wants
+// pending → running → in review → blocked; a personal list wants pending and
+// done and nothing else. "Every project the same" makes the second list carry
+// four columns it never uses; "every project its own" means `qa` on one board
+// is a different thing from `qa` on the next, and an agent told to "move it to
+// QA" has to ask which QA. So: the VOCABULARY is global and editable, and the
+// SUBSET is per project.
+//
+// A column is a task `status`. That is why this is cheap: nothing in the daemon
+// branches on the value of `status` — it is a validation whitelist, a label, and
+// something to group by. Making the whitelist configurable is the whole feature.
+//
+// `done` is never in the catalog. It is a task's `state`, not its status, and it
+// is the one column every board ends with — dragging a card there closes the
+// task, dragging it out reopens it. Making it configurable would let someone
+// build a board with no way to finish anything.
+import { TASK_STATUSES, DEFAULT_TASK_STATUS } from "#core/stores/tasks.js";
+
+/** The terminal column every board gets, appended after the configured ones. */
+export const DONE_COLUMN = "done";
+
+/** Shipped catalog — exactly the statuses that existed before this was configurable. */
+export const DEFAULT_TASK_COLUMNS = Object.freeze(
+  TASK_STATUSES.map((id) => Object.freeze({ id, label: null })),
+);
+
+const ID_RE = /^[a-z0-9][a-z0-9_-]{0,31}$/;
+
+/**
+ * The on-enter automation, or nothing. An `agent` is required — an instruction
+ * with nobody to carry it out is not a half-configured hook, it is no hook.
+ */
+function normalizeHook(value) {
+  const agent = String(value?.agent || "").trim().toLowerCase();
+  if (!agent || !ID_RE.test(agent)) return {};
+  const instruction = typeof value?.instruction === "string" ? value.instruction.trim() : "";
+  return { on_enter: { agent, instruction: instruction || null } };
+}
+
+/** A usable column id: slug-shaped, and never the reserved terminal one. */
+export function isColumnId(value) {
+  const id = String(value || "").trim().toLowerCase();
+  return ID_RE.test(id) && id !== DONE_COLUMN;
+}
+
+/**
+ * Clean a catalog coming from config or from an HTTP body. Anything unusable is
+ * dropped rather than rejected: this reads stored data, and one bad row must not
+ * blank out a board.
+ *
+ * `label: null` means "use the built-in translation for this id" — that is how
+ * the four shipped columns stay bilingual while a custom one keeps the exact
+ * words its author typed.
+ *
+ * `on_enter` is the automation: `{ agent, instruction }` means "when a task
+ * lands in this column, hand it to that agent". The slug is resolved against
+ * the TASK'S OWN project, which is what lets one global "QA" column put each
+ * project's own qa agent to work. A project without that agent simply does
+ * nothing — a card that silently summoned a stranger would be worse.
+ */
+export function normalizeColumns(value) {
+  if (!Array.isArray(value)) return [...DEFAULT_TASK_COLUMNS];
+  const seen = new Set();
+  const out = [];
+  for (const raw of value) {
+    const id = String((typeof raw === "string" ? raw : raw?.id) || "").trim().toLowerCase();
+    if (!isColumnId(id) || seen.has(id)) continue;
+    seen.add(id);
+    const label = typeof raw?.label === "string" && raw.label.trim() ? raw.label.trim() : null;
+    out.push({ id, label, ...normalizeHook(raw?.on_enter) });
+  }
+  // A board with no columns is not a board. Falling back beats showing nothing.
+  return out.length ? out : [...DEFAULT_TASK_COLUMNS];
+}
+
+/** The automation configured on a column, or null. */
+export function columnHook(columns, id) {
+  return columns.find((c) => c.id === id)?.on_enter || null;
+}
+
+/** The global catalog: every column name that exists anywhere. */
+export function readColumnCatalog(globalConfig) {
+  return normalizeColumns(globalConfig?.tasks?.columns);
+}
+
+/**
+ * The columns ONE project shows, in order, with `done` appended.
+ *
+ * A project that has chosen nothing shows the whole catalog — that is the old
+ * behaviour, and a board that starts empty would look broken.
+ *
+ * @param {object} globalConfig
+ * @param {object} projectConfig  the project's own `.apc/config.json`
+ * @returns {{id: string, label: string|null}[]}
+ */
+export function projectColumns(globalConfig, projectConfig) {
+  const catalog = readColumnCatalog(globalConfig);
+  const picked = projectConfig?.tasks?.columns;
+  if (!Array.isArray(picked) || picked.length === 0) {
+    return [...catalog, { id: DONE_COLUMN, label: null }];
+  }
+  const byId = new Map(catalog.map((c) => [c.id, c]));
+  const out = [];
+  const seen = new Set();
+  for (const raw of picked) {
+    const id = String(raw?.id || raw || "").trim().toLowerCase();
+    // A project can only pick from the catalog: that is what keeps "QA" the
+    // same thing everywhere. An id removed from the catalog quietly disappears
+    // from the boards that used it, rather than resurrecting a dead column.
+    if (!byId.has(id) || seen.has(id)) continue;
+    seen.add(id);
+    out.push(byId.get(id));
+  }
+  if (!out.length) out.push(...catalog);
+  return [...out, { id: DONE_COLUMN, label: null }];
+}
+
+/**
+ * Where a task sits on the board.
+ *
+ * `done` finishes in the done column. `dropped` does NOT: it was abandoned, not
+ * completed, and it stays in the column it was abandoned in — which is the
+ * useful thing to see when you go looking at what you gave up on and where.
+ * Filing it under "done" would claim it was finished.
+ *
+ * An open task whose status is not a column on THIS board falls into the first
+ * one, so a card is never invisible.
+ */
+export function columnFor(task, columns) {
+  if (task?.state === "done") return DONE_COLUMN;
+  const status = task?.status || DEFAULT_TASK_STATUS;
+  return columns.some((c) => c.id === status) ? status : (columns[0]?.id || DEFAULT_TASK_STATUS);
+}

package/src/core/tasks/comment-turn.js

@@ -0,0 +1,258 @@
+// Comments on a task that can summon an agent.
+//
+// A comment thread is the one place where "who should do this" and "what is
+// this" sit together, so @-mentioning an agent there is the cheapest way to
+// hand work over: drop a card in QA, tag @qa, and it does the QA and writes
+// back what it found. The reply lands as another comment on the same task.
+//
+// TURN-TAKING IS THE GROUP CHAT'S, ON PURPOSE. `parseMentions` is imported from
+// agent/group/turn-resolver.js rather than copied, and the cascade below is the
+// same shape: an agent's reply is scanned for mentions, whoever is named gets a
+// turn, and a ceiling stops the ping-pong. What is NOT reused is the seeding —
+// a group with no mention hands the turn to the first agent in the room, and a
+// comment with no mention must summon nobody. A note to self is a note to self.
+//
+// The ceiling is lower than the group's ten. A room is watched live by the
+// person who opened it; a task thread runs unattended — that is the entire
+// point of leaving work for QA — so the blast radius of a mention loop is a
+// number nobody is sitting there to stop.
+import { resolveAgentModel } from "#core/agent/agent-model.js";
+import { buildAgentSystem } from "#core/agent/build-agent-system.js";
+import { groupToolIters } from "#core/agent/constants.js";
+import { parseMentions } from "#core/agent/group/turn-resolver.js";
+import { runAgentTurn } from "#core/agent/run-turn.js";
+import { readAgents } from "#core/apc/parser.js";
+import { CHANNELS } from "#core/constants/channels.js";
+import { OWNER_ACTOR_ID } from "#core/constants/actors.js";
+import { emitMessageEvent } from "#core/events/bus.js";
+import { addComment, getTask } from "#core/stores/tasks.js";
+import { nowIso } from "#core/util/time.js";
+
+/** One comment can produce at most this many agent replies, cascade included. */
+export const MAX_COMMENT_TURNS = 4;
+
+/** Keep a reply readable in a side panel — see the "no huge deploy" rule below. */
+const REPLY_CHAR_HINT = 700;
+
+const displayName = (a) => a.fields?.Name || a.slug;
+
+/**
+ * Everyone addressable on a task in this project: the owner (who can be named
+ * but never summoned) plus every agent the project declares.
+ */
+export function taskParticipants(projectPath) {
+  let agents = [];
+  try { agents = readAgents(projectPath); } catch { agents = []; }
+  return [
+    { slug: OWNER_ACTOR_ID, name: "Owner", kind: "owner" },
+    ...agents.map((a) => ({ slug: a.slug, name: displayName(a), kind: "agent" })),
+  ];
+}
+
+/**
+ * Agent slugs a comment addresses. Exported so the API can resolve them at
+ * WRITE time and store them on the comment — the roster can change, and the
+ * thread should keep saying who was actually pulled in that day.
+ */
+export function mentionedAgents(text, projectPath, authorSlug = OWNER_ACTOR_ID) {
+  return parseMentions(text || "", taskParticipants(projectPath), authorSlug);
+}
+
+/** The task, rendered for a model that has never seen it. */
+function taskBlock(task, projectName) {
+  const lines = [
+    "## Task",
+    `**${task.title}**`,
+    `id: ${task.id} · project: ${projectName} · state: ${task.state} · status: ${task.status}`,
+  ];
+  if (task.due) lines.push(`due: ${task.due}`);
+  if (task.agent) lines.push(`assigned: @${task.agent}`);
+  if (task.tags?.length) lines.push(`tags: ${task.tags.map((t) => `#${t}`).join(" ")}`);
+  if (task.subtask_count) lines.push(`subtasks: ${task.subtask_done}/${task.subtask_count} done`);
+  if (task.description) lines.push("", "### Description", task.description);
+  // The agent prompt is instructions for whoever RUNS the task, so a summoned
+  // agent needs it. It is not the description and must not be read as one.
+  if (task.body) lines.push("", "### Agent prompt (instructions for running this task)", task.body);
+  return lines.join("\n");
+}
+
+/** The thread so far, oldest first, prefixed by speaker. */
+function threadBlock(task, nameFor) {
+  if (!task.comments?.length) return "";
+  return [
+    "",
+    "## Comments",
+    ...task.comments.map((c) => `${nameFor(c.by)}: ${c.text}`),
+  ].join("\n");
+}
+
+function systemBlock({ me, others, taskTitle }) {
+  const roster = others.length ? others.map((o) => `${o.name} (@${o.slug})`).join(", ") : "(no other agents)";
+  return [
+    "## Task comments",
+    `You were @-mentioned in the comment thread of the task **${taskTitle}**.`,
+    `Reply ONLY as yourself (**${me}**). Your reply is posted as a comment on that task — it is not a chat message.`,
+    "**Do the work first.** You have your real tools. If the comment asks you to check, review, test or fix something, do it and report what you actually found. Do not describe what you would do.",
+    `**Be short.** A comment lives in a side panel next to the task. Aim for a few lines and stay under ~${REPLY_CHAR_HINT} characters. If the detail is long, put the conclusion in the comment and the detail where it belongs (a file, a PR, the task's description).`,
+    `**Handing work over:** the only way another agent gets a turn is writing their exact handle with an @ — ${roster}. Writing just their name does NOT reach them. Mention someone ONLY if they genuinely need to act; if you can close it yourself, cite nobody and the thread ends.`,
+  ].join("\n");
+}
+
+/**
+ * Record an agent→agent handover on the a2a ledger, so a crossing that happened
+ * inside a task still shows up where every other agent-to-agent exchange does.
+ * The work itself already ran through the real turn engine — this is the paper
+ * trail, not the delivery mechanism (an a2a `--deliver` reply has no tools).
+ */
+function logHandover(p, { from, to, taskId, text, model, usage }) {
+  const ts = nowIso();
+  // Attribution rides along: a row filed without `model`/`usage` reopens in the
+  // viewer as "0 tok, no model", which is the regression tests/message-
+  // attribution.test.js exists to stop. The numbers are the summoned agent's
+  // own turn — the one whose reply this row mirrors.
+  const meta = {
+    task: taskId, via: "task_comment",
+    ...(model ? { model } : {}), ...(usage ? { usage } : {}),
+  };
+  try {
+    p.logMessage({
+      agent_slug: from, channel: CHANNELS.A2A, direction: "out",
+      author: from, body: text, meta: { ...meta, to, final: true }, ts,
+    });
+    p.logMessage({
+      agent_slug: to, channel: CHANNELS.A2A, direction: "in",
+      author: from, body: text, meta: { ...meta, from }, ts,
+    });
+  } catch {
+    // The comment is the source of truth; a missing mirror row must never fail
+    // the turn that produced it.
+  }
+}
+
+/** The real thing: one summoned agent's turn, with its own tools. */
+async function runRealTurn({
+  p, agent, slug, from, task, participants, nameFor, projectName,
+  cfg, projects, plugins, registries, signal,
+}) {
+  const modelId = await resolveAgentModel({ agent, config: cfg });
+  if (!modelId) throw new Error(`no model for agent ${slug}`);
+  const me = displayName(agent);
+  const others = participants.filter((x) => x.kind === "agent" && x.slug !== slug);
+  const system = buildAgentSystem(p, agent, {
+    invocation: "engine",
+    caller: from === OWNER_ACTOR_ID ? "user" : from,
+    globalConfig: cfg,
+    extraParts: [systemBlock({ me, others, taskTitle: task.title })],
+  });
+  const directive = from === OWNER_ACTOR_ID
+    ? `The owner tagged you (@${slug}) on this task. Act on the last comment, then reply.`
+    : `${nameFor(from)} tagged you (@${slug}) on this task. Act on the last comment, then reply.`;
+
+  const result = await runAgentTurn({
+    p, agent, modelId, system,
+    prompt: `${taskBlock(task, projectName)}${threadBlock(task, nameFor)}\n\n---\n${directive}`,
+    previousMessages: [],
+    channel: CHANNELS.WEB,
+    // Same reasoning as the group: the channel picks the PROMPT, but one comment
+    // can fan out into several of these runs, so the budget is the fan-out-aware
+    // one.
+    maxIters: groupToolIters(cfg),
+    tools: true,
+    projects, plugins, registries, config: cfg,
+    signal,
+  });
+  return { text: result.text || "", model: result.model || modelId, usage: result.usage };
+}
+
+/**
+ * Run the mention cascade for the newest comment on a task.
+ *
+ * Fire-and-forget from a route: every reply is persisted as it lands, so a
+ * caller that never awaits still gets the full thread on its next read.
+ *
+ * @param {object} args
+ * @param {object} args.p         resolved project (path, storagePath, config, logMessage, id)
+ * @param {string} args.taskId
+ * @param {string[]} args.seed    agent slugs the triggering comment mentioned
+ * @param {string} args.author    who wrote the triggering comment (owner | agent slug)
+ * @param {AbortSignal} [args.signal]
+ * @param {Function} [args.runTurn]
+ *        Injectable model call, same trick the group resolver uses: the cascade
+ *        and its ceiling are the part worth testing, and neither needs an
+ *        engine. Production always uses the real turn.
+ * @returns {Promise<Array<{slug, text}>>}
+ */
+export async function runCommentMentions({
+  p, taskId, seed, author = OWNER_ACTOR_ID,
+  projects, plugins, registries, config, signal = null,
+  maxTurns = MAX_COMMENT_TURNS,
+  runTurn = runRealTurn,
+}) {
+  const participants = taskParticipants(p.path);
+  const agents = new Map();
+  try {
+    for (const a of readAgents(p.path)) agents.set(a.slug, a);
+  } catch { /* no roster → nothing to summon */ }
+
+  const nameFor = (who) =>
+    !who || who === OWNER_ACTOR_ID ? "Owner" : (agents.get(who) ? displayName(agents.get(who)) : who);
+
+  const cfg = p.config || config;
+  const projectName = p.name || p.path || String(p.id);
+  const said = [];
+  const queue = (seed || []).filter((s) => agents.has(s)).map((slug) => ({ slug, from: author }));
+
+  while (queue.length && said.length < maxTurns) {
+    if (signal?.aborted) break;
+    const { slug, from } = queue.shift();
+    const agent = agents.get(slug);
+    if (!agent) continue;
+
+    // Re-read every hop: an earlier speaker's comment is already persisted, so
+    // the next one sees what was just said.
+    const task = getTask(p.storagePath, taskId);
+    if (!task) break;
+
+    let reply = "";
+    let model = null;
+    let usage = null;
+    try {
+      // A test's stub may hand back a bare string; the real one returns what
+      // answered and what it spent.
+      const out = await runTurn({
+        p, agent, slug, from, task, participants, nameFor, projectName,
+        cfg, projects, plugins, registries, signal,
+      });
+      if (typeof out === "string") reply = out.trim();
+      else { reply = (out?.text || "").trim(); model = out?.model || null; usage = out?.usage || null; }
+    } catch (e) {
+      // A failed summon is written into the thread rather than swallowed: a
+      // comment that says "@qa" and is met with silence looks like the feature
+      // is broken, which is worse than reading why it did not run.
+      reply = `⚠️ No pude atender la mención: ${e?.message || String(e)}`;
+    }
+
+    if (!reply) reply = "…";
+    const next = parseMentions(reply, participants, slug);
+    addComment(p.storagePath, taskId, { by: slug, text: reply, mentions: next });
+    said.push({ slug, text: reply });
+    // attribution-exempt: this is the live-feed SIGNAL, not a ledger insertion.
+    // It carries "the thread moved" and nothing else — the row it announces was
+    // written by addComment above, and the a2a mirror below is where the model
+    // and usage are recorded.
+    emitMessageEvent({
+      scope: "project", channel: CHANNELS.A2A, project_root: p.storagePath,
+      agent_slug: slug, direction: "out", type: "agent", thread: taskId, final: true,
+      ts: nowIso(),
+    });
+
+    for (const to of next) {
+      if (!agents.has(to)) continue;
+      if (queue.some((q) => q.slug === to)) continue;
+      logHandover(p, { from: slug, to, taskId, text: reply, model, usage });
+      queue.push({ slug: to, from: slug });
+    }
+  }
+
+  return said;
+}

package/src/core/util/time.js

@@ -7,3 +7,16 @@ export function nowIso() {
 export function isoToMs(iso) {
   return iso ? Date.parse(iso) : 0;
 }
+
+// The two shapes the dated note files use (see core/memory/dated-log.js): a
+// "YYYY-MM-DD" day heading and an "HH:MM" bullet tag. UTC on purpose — the
+// notebook, project memory and routine memory have always been stamped in UTC
+// and they are read against each other, so a per-file timezone would make two
+// notes written a minute apart land on different days.
+export function dayStamp(d = new Date()) {
+  return d.toISOString().slice(0, 10);
+}
+
+export function hourStamp(d = new Date()) {
+  return d.toISOString().slice(11, 16);
+}

package/src/core/voice/engines/index.js

@@ -63,7 +63,8 @@ function ttsConfig(globalConfig) {
   return globalConfig?.voice?.tts || {};
 }
 
-function providerConfig(globalConfig, provider) {
+/** The stored config block for one engine id (custom ids included). */
+export function providerConfig(globalConfig, provider) {
   const tts = ttsConfig(globalConfig);
   if (isCustomId(provider)) return tts?.custom?.[slugOf(provider)] || {};
   return tts?.[provider] || {};
@@ -100,6 +101,58 @@ export function resolveChainOrder(ttsCfg) {
   return full;
 }
 
+/**
+ * Every engine that could handle a synthesize() call, in the order they should
+ * be tried. `selectTtsEngine` returns the first of these; `synthesize()` walks
+ * the whole list so an engine that *looks* usable but fails at request time
+ * (a local server that isn't running) hands off to the next one instead of
+ * sinking the turn.
+ *
+ * WHY THIS EXISTS. isAvailable() is a config probe, not a reachability probe —
+ * a custom endpoint reports itself available on the strength of having a
+ * base_url. That is the right call for the settings UI (it must list an engine
+ * the user configured even while its server is down) but it made "chain" mode
+ * a misnomer: selection stopped at the first *configured* engine and a failure
+ * there never reached the second. Falling back on the real error is both more
+ * accurate than any probe and free.
+ *
+ * @returns {Promise<Array<{provider, adapter, engineConfig}>>}
+ */
+export async function resolveTtsCandidates({ globalConfig, provider }) {
+  const ttsCfg = ttsConfig(globalConfig);
+  const entry = (id) => ({
+    provider: id,
+    adapter: getTtsAdapter(id),
+    engineConfig: providerConfig(globalConfig, id),
+  });
+
+  // An explicit provider means the caller wants THAT engine — the voice
+  // tester, or a retry. No fallback: silently speaking in a different voice
+  // than the one under test would be worse than failing.
+  if (provider && provider !== "auto") return [entry(provider)];
+
+  if (resolveMode(ttsCfg) === "single") {
+    const id = ttsCfg?.provider;
+    if (id && id !== "auto") return [entry(id)];
+    // Misconfigured single mode (no concrete provider) → fall through to chain.
+  }
+
+  const out = [];
+  for (const id of resolveChainOrder(ttsCfg)) {
+    if (id !== "mock" && !isEnabled(ttsCfg, id)) continue;
+    const cfg = providerConfig(globalConfig, id);
+    try {
+      if (id !== "mock" && !(await getTtsAdapter(id).isAvailable(cfg, globalConfig?.engines))) continue;
+    } catch { continue; }
+    out.push(entry(id));
+  }
+  // mock closes the list so synthesize() never throws for want of an engine.
+  // It returns silence, so callers that can tell the user "no voice" should
+  // check the returned `provider` rather than treat it as speech.
+  if (!out.some((c) => c.provider === "mock")) out.push(entry("mock"));
+  return out;
+}
+
 /**
  * Resolve which engine should handle a synthesize() call.
  * Returns { provider, adapter, engineConfig }.

package/src/core/voice/engines/openai.js

@@ -8,9 +8,15 @@
 // OpenAI-compatible speech server (e.g. a Qwen3-TTS / QVox daemon at
 // http://127.0.0.1:5111/v1). When base_url is set we additionally forward the
 // non-OpenAI fields that server understands — `instruct` (the base voice, from
-// the `style` arg), `language` and `temperature`. These extras are NEVER sent
-// to stock OpenAI (only when base_url is present), so the standard path stays
-// byte-for-byte compatible.
+// the `style` arg), `language`, `clone`/`ref_text` and `temperature`. These
+// extras are NEVER sent to stock OpenAI (only when base_url is present), so the
+// standard path stays byte-for-byte compatible.
+//
+// Which of `clone` / `voice` / `instruct` is set decides HOW the server speaks,
+// and they are not additive — QVox reads them in that order and the first one
+// wins. A named speaker carries its own accent, so picking one leaves `style`
+// describing only the delivery; only a cloned reference can carry an accent no
+// preset speaker has.
 
 import fs from "node:fs";
 import path from "node:path";
@@ -59,6 +65,34 @@ export default {
     return Boolean(config.base_url) || Boolean(getKey(config, parentEnginesCfg));
   },
 
+  // Only local endpoints have anything to warm. A cloud API is as ready as it
+  // will ever be, and a hosted server is not ours to spin up — so a stock
+  // OpenAI config skips instead of sending a pointless request.
+  async warmup(config = {}) {
+    if (!config.base_url) return { ok: true, skipped: "not a local endpoint" };
+    const url = config.base_url.replace(/\/+$/, "") + "/warmup";
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...(config.api_key ? { authorization: `Bearer ${config.api_key}` } : {}),
+      },
+      // Say which voice, so the endpoint warms the model that will answer
+      // rather than a sibling of it — these are different multi-gigabyte
+      // checkpoints, and warming one leaves the other exactly as cold. The
+      // clone is named for the same reason: a cloned reference is served by a
+      // third checkpoint again, so a warmup that only ever mentions `voice`
+      // warms nothing the next request will use.
+      body: JSON.stringify({
+        ...(config.voice ? { voice: config.voice } : {}),
+        ...(config.clone ? { clone: config.clone, ref_text: config.ref_text } : {}),
+      }),
+      signal: AbortSignal.timeout(120_000),
+    });
+    if (!res.ok) throw new Error(`warmup ${res.status}`);
+    return await res.json().catch(() => ({ ok: true }));
+  },
+
   async synthesize({ text, voice, language, style, outDir, config = {}, format, signal, parentEnginesCfg }) {
     if (!text) throw new Error("openai-tts: empty text");
     const isCustom = Boolean(config.base_url);
@@ -79,7 +113,19 @@ export default {
     if (isCustom) {
       // QVox / Qwen3-TTS extras (ignored by stock OpenAI, so only sent here).
       if (styleHint) body.instruct = styleHint;
-      if (language) body.language = language;
+      // A caller that names a language wins; otherwise the configured one.
+      // Nothing in the speaking path (Telegram voice notes, the desktop, a
+      // routine) passes one, so without this the server was left to guess from
+      // its own default — right by luck here, wrong for anyone whose local
+      // server defaults elsewhere.
+      const lang = language || config.language;
+      if (lang && lang !== "auto") body.language = lang;
+      // Voice cloning: the endpoint reads the reference itself, so this is a
+      // path on ITS filesystem, not ours. `ref_text` is what the recording
+      // says — optional, and worth setting: telling the model that measured
+      // 15.8 chars/s against 12.9 without it.
+      if (config.clone) body.clone = config.clone;
+      if (config.ref_text) body.ref_text = config.ref_text;
       if (config.temperature != null) body.temperature = config.temperature;
     } else if (styleHint && /gpt-4o.*tts/i.test(model || "")) {
       // Stock OpenAI's newer TTS models accept a natural-language `instructions`.

package/src/core/voice/opus.js

@@ -0,0 +1,67 @@
+// Re-encode synthesized speech into the one container Telegram will render as
+// a VOICE NOTE.
+//
+// This is not a cosmetic detail. `sendVoice` accepts OGG/Opus and nothing
+// else; hand it the WAV that Gemini TTS returns (or the MP3 from OpenAI /
+// ElevenLabs) and the Bot API either rejects the upload or Telegram shows a
+// grey file attachment — which on a phone mounted in a car is unplayable
+// without taking your hand off the wheel. So: one conversion, in one place,
+// and callers that need a voice note ask for one instead of guessing at
+// formats.
+//
+// ffmpeg is the same dependency the transcription path already relies on, and
+// it is reached through envWithPath() for the same reason: a daemon booted by
+// launchd inherits a PATH with no Homebrew in it, and every conversion would
+// otherwise fail with ENOENT (see core/util/path-env.js).
+import fs from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { envWithPath } from "#core/util/path-env.js";
+import { ensureTtsTmpDir } from "./tts.js";
+
+const run = promisify(execFile);
+
+// Telegram voice notes are mono and low-bitrate by convention; Opus at 32 kbps
+// is transparent for speech and keeps a 20-second note around 80 KB.
+const VOICE_BITRATE = "32k";
+const VOICE_SAMPLE_RATE = "48000";
+
+/**
+ * Convert `sourcePath` to OGG/Opus and return the new path. A file that is
+ * already .ogg is returned untouched — every engine that emits Opus natively
+ * (ElevenLabs' ogg formats, Gemini when it answers audio/ogg) skips the
+ * re-encode entirely.
+ *
+ * Returns `null` when ffmpeg is unavailable or fails, so callers can fall back
+ * to plain text rather than dropping the reply. A voice note is an upgrade;
+ * losing the message because the upgrade failed is not acceptable.
+ */
+export async function toVoiceNote(sourcePath) {
+  if (!sourcePath || !fs.existsSync(sourcePath)) return null;
+  if (path.extname(sourcePath).toLowerCase() === ".ogg") return sourcePath;
+
+  const target = path.join(
+    ensureTtsTmpDir(),
+    `${path.basename(sourcePath, path.extname(sourcePath))}.ogg`
+  );
+  try {
+    await run(
+      "ffmpeg",
+      [
+        "-hide_banner", "-loglevel", "error", "-y",
+        "-i", sourcePath,
+        "-vn",
+        "-ac", "1",
+        "-ar", VOICE_SAMPLE_RATE,
+        "-c:a", "libopus",
+        "-b:a", VOICE_BITRATE,
+        target,
+      ],
+      { env: envWithPath(), timeout: 60_000 }
+    );
+  } catch {
+    return null;
+  }
+  return fs.existsSync(target) && fs.statSync(target).size > 0 ? target : null;
+}

package/src/core/voice/pronounceable.js

@@ -0,0 +1,43 @@
+// Text that is about to be spoken aloud, cleaned of what a voice cannot say.
+//
+// A TTS model has to produce *something* for every token it is given, and an
+// emoji has no pronunciation — so it improvises, which comes out as a couple of
+// seconds of humming in the middle of a sentence. Roby ending a reply with 👍
+// is pleasant to read and unlistenable.
+//
+// This is deliberately about speech, not about display: a channel that shows
+// the text as well decides separately whether the reader keeps the emoji.
+
+// Pictographs, plus the pieces that glue them together: variation selectors,
+// zero-width joiners, skin-tone modifiers, keycap marks and the regional
+// indicators that spell out flags.
+// Written as alternatives rather than one character class on purpose: the
+// joiners below are combining marks, and a class that mixes them with the
+// pictographs they attach to is both misleading to read and flagged by lint.
+const EMOJI = new RegExp(
+  [
+    "\\p{Extended_Pictographic}",   // the pictographs themselves
+    "\\p{Regional_Indicator}",      // the letter pairs that spell out flags
+    "[\\u{1F3FB}-\\u{1F3FF}]",     // skin-tone modifiers
+    "\\uFE0F",                     // variation selector (the "render as emoji" flag)
+    "\\u200D",                     // zero-width joiner, glues 👨‍👩‍👧 together
+    "\\u20E3",                     // the enclosing box of a keycap like 1️⃣
+  ].join("|"),
+  "gu"
+);
+
+/**
+ * Remove emoji from text meant to be spoken, and tidy the space they leave.
+ * Returns "" when nothing sayable is left, which lets a caller drop a segment
+ * that was only an emoji instead of synthesizing a shrug.
+ */
+export function stripEmoji(text) {
+  return String(text ?? "")
+    .replace(EMOJI, "")
+    // An emoji sitting between words leaves a double space; one that trailed a
+    // sentence leaves a space before the period.
+    .replace(/[ \t]{2,}/g, " ")
+    .replace(/[ \t]+([,.;:!?…])/g, "$1")
+    .replace(/^[ \t]+|[ \t]+$/gm, "")
+    .trim();
+}