@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/core/engines/openai-compatible.js

@@ -1,5 +1,6 @@
 // Shared OpenAI-compatible chat adapter (OpenAI, Groq, OpenRouter, …).
 import { pingUrl } from "./_health.js";
+import { streamSseDataEvents } from "./_streaming.js";
 
 // Adapters stash provider-private metadata on tool_calls under an underscore
 // prefix (e.g. gemini's `_thoughtSignature`). Strict OpenAI-shaped APIs reject
@@ -14,14 +15,38 @@ function stripPrivateFields(tc) {
   return out;
 }
 
+/** OpenAI multimodal content: text plus any `images` riding on the turn.
+ *  Without this, run-agent's turnImages were silently dropped and a vision
+ *  model (or a text model behind a vision bridge) never saw the photo. */
+function contentForOpenAi(m) {
+  const text = typeof m.content === "string" ? m.content : JSON.stringify(m.content ?? "");
+  const imgs = Array.isArray(m.images)
+    ? m.images.filter((im) => im && im.data && im.mime)
+    : [];
+  if (!imgs.length) return text;
+  return [
+    ...(text ? [{ type: "text", text }] : []),
+    ...imgs.map((im) => ({
+      type: "image_url",
+      image_url: { url: `data:${im.mime};base64,${im.data}` },
+    })),
+  ];
+}
+
 export function createOpenAiCompatibleEngine({
   id,
   defaultBaseUrl,
   apiKeyEnv,
   defaultFallbackModel = null,
+  extraHeaders = {},
+  decorateMessage = null,
+  // Zen free-tier accepts the literal key "public" with the opencode UA.
+  // Without a key the adapter would refuse the call even though the gateway
+  // is happy — so an engine can opt into a built-in default.
+  defaultApiKey = "",
 }) {
   function getKey(config) {
-    return config?.api_key || process.env[apiKeyEnv] || "";
+    return config?.api_key || process.env[apiKeyEnv] || defaultApiKey || "";
   }
 
   function getBaseUrl(config) {
@@ -29,12 +54,29 @@ export function createOpenAiCompatibleEngine({
     return String(raw).replace(/\/$/, "");
   }
 
+  // Headers beyond the ones every call needs. Some gateways gate on something
+  // other than the key — OpenCode Zen serves its free tier only to a caller
+  // that identifies itself as the opencode client — and a self-hosted proxy in
+  // front of a model may want its own. The adapter carries a default per
+  // engine; `engines.<id>.headers` in config adds to or overrides it. The
+  // per-call ones (auth, content-type) always win, so config can't blank out
+  // the key by accident.
+  function buildHeaders(config, perCall = {}) {
+    const merged = { ...extraHeaders, ...(config?.headers || {}), ...perCall };
+    const out = {};
+    for (const [k, v] of Object.entries(merged)) {
+      if (v != null && v !== "") out[String(k).toLowerCase()] = String(v);
+    }
+    return out;
+  }
+
   return {
     id,
     needsApiKey: true,
     apiKeyEnv,
     defaultBaseUrl,
     defaultFallbackModel,
+    buildHeaders,
 
     /**
      * Health: confirm we have a key and the `/models` catalog answers.
@@ -48,7 +90,7 @@ export function createOpenAiCompatibleEngine({
       const base = getBaseUrl(config);
       const res = await pingUrl(`${base}/models`, {
         timeoutMs: Math.max(timeoutMs, 1200),
-        headers: { authorization: `Bearer ${getKey(config)}` },
+        headers: buildHeaders(config, { authorization: `Bearer ${getKey(config)}` }),
       });
       if (res.ok) return { ok: true, provider: id, detail: base };
       // Key present but catalog ping failed — keep going, the chat call will
@@ -72,6 +114,8 @@ export function createOpenAiCompatibleEngine({
       tools,
       toolChoice,
       signal,
+      onToken,
+      onReasoningToken,
     }) {
       const key = getKey(config);
       if (!key) {
@@ -86,16 +130,24 @@ export function createOpenAiCompatibleEngine({
       //   - tool_call_id (tool result turns — Groq / OpenAI strict require
       //                   this to match the assistant's tool_call id)
       //   - name         (some providers prefer it on tool messages)
+      //   - images       (user/tool turns carrying vision bytes — rendered as
+      //                   multimodal content parts; text-only models ignore or
+      //                   400, which the vision bridge in run-agent covers)
       //
       // Dropping any of these is the cause of the
       //   "messages.N.tool_call_id: property 'tool_call_id' is missing"
       // 400 we saw on Groq when llama-3.3 emitted a pseudo-tool call.
+      //
+      // Rebuilding the entry from scratch (rather than spreading `m`) is what
+      // keeps engine-private fields off the wire — strict OpenAI-shaped APIs
+      // reject unknown properties. An engine that needs one of them replayed
+      // for a specific model opts in through `decorateMessage`; see zen.js.
       const fullMessages = [];
       if (system) fullMessages.push({ role: "system", content: system });
       for (const m of messages) {
         const entry = {
           role: m.role,
-          content: typeof m.content === "string" ? m.content : JSON.stringify(m.content),
+          content: contentForOpenAi(m),
         };
         if (m.tool_calls)    entry.tool_calls   = m.tool_calls.map(stripPrivateFields);
         if (m.tool_call_id)  entry.tool_call_id = m.tool_call_id;
@@ -104,6 +156,7 @@ export function createOpenAiCompatibleEngine({
         if (m.role === "tool" && (m.tool_name || m.name)) {
           entry.name = m.name || m.tool_name;
         }
+        if (decorateMessage) decorateMessage(entry, m, { model, config });
         fullMessages.push(entry);
       }
 
@@ -114,6 +167,15 @@ export function createOpenAiCompatibleEngine({
         max_tokens: maxTokens,
       };
 
+      // Thinking, off at the source. A reasoning model spends the token budget
+      // planning before it writes a word, so a small max_tokens comes back with
+      // a full chain of thought and an EMPTY answer — and the operator pays for
+      // both. `thinking: false` on the provider stops it being generated;
+      // `reasoning_effort: "none"` is the knob the OpenAI-shaped gateways read
+      // (verified against Zen: reasoning_tokens drops to 0). Only sent when the
+      // operator asked for it — a provider that never heard of the field 400s.
+      if (config?.thinking === false) body.reasoning_effort = "none";
+
       if (tools && tools.length > 0) {
         body.tools = tools;
         if (toolChoice === "required" || toolChoice === "any") {
@@ -123,34 +185,49 @@ export function createOpenAiCompatibleEngine({
         }
       }
 
+      // Stream when the caller wants tokens as they land. A tool-forced turn is
+      // excluded: it has no prose to stream, only a call to assemble.
+      const wantsStream =
+        typeof onToken === "function" && toolChoice !== "required" && toolChoice !== "any";
+      if (wantsStream) {
+        body.stream = true;
+        // Streamed responses omit usage unless asked. Gateways that don't know
+        // the field ignore it; Zen sends the totals in a final choice-less row.
+        body.stream_options = { include_usage: true };
+      }
+
       const res = await fetch(`${getBaseUrl(config)}/chat/completions`, {
         method: "POST",
-        headers: {
+        headers: buildHeaders(config, {
           "content-type": "application/json",
           authorization: `Bearer ${key}`,
-        },
+        }),
         body: JSON.stringify(body),
         signal,
       });
-      const json = await res.json();
+
       if (!res.ok) {
+        // An error answers as JSON even when the request asked for a stream.
+        const err = await res.json().catch(() => null);
         throw new Error(
-          `${id} ${res.status}: ${json?.error?.message || JSON.stringify(json)}`
+          `${id} ${res.status}: ${err?.error?.message || JSON.stringify(err)}`
         );
       }
 
+      if (wantsStream) return readStream(res, onToken, onReasoningToken);
+
+      const json = await res.json();
       const choice = json.choices?.[0];
-      // Reasoning models on OpenRouter/Groq return their chain of thought in a
-      // SEPARATE field (`reasoning`, or `reasoning_content` on some routers).
-      // It is not an answer and must never reach a channel — fold it into the
-      // <think> form APX already knows how to strip per channel.
-      const reasoning = choice?.message?.reasoning || choice?.message?.reasoning_content || "";
-      const answer = choice?.message?.content || "";
-      const text = reasoning ? `<think>${reasoning}</think>${answer}` : answer;
       const toolCalls = choice?.message?.tool_calls;
 
       return {
-        text,
+        // Reasoning travels in its own field, never folded into the answer.
+        // It used to be wrapped in <think>…</think> and left inside `text` for
+        // each surface to strip; the surfaces that forgot (web, CLI) showed the
+        // model's notes to the user. Keeping the two apart at the boundary
+        // means no surface can leak what it never received.
+        text: choice?.message?.content || "",
+        reasoning: choice?.message?.reasoning || choice?.message?.reasoning_content || "",
         tool_calls: toolCalls?.length > 0 ? toolCalls : undefined,
         finish_reason: choice?.finish_reason,
         usage: {
@@ -162,3 +239,61 @@ export function createOpenAiCompatibleEngine({
     },
   };
 }
+
+/**
+ * Read an OpenAI-shaped SSE stream into the same result object the blocking
+ * path returns. The two channels stay apart the whole way down: `content`
+ * deltas reach `onToken`, reasoning reaches `onReasoningToken`, and a caller
+ * that only passes the first never sees a word of the thinking. tool_calls are
+ * reassembled by index (a call arrives split across rows: the name in one, the
+ * arguments a character at a time after it).
+ */
+async function readStream(res, onToken, onReasoningToken) {
+  let text = "";
+  let reasoning = "";
+  let finishReason;
+  let usage = null;
+  const calls = [];
+
+  for await (const evt of streamSseDataEvents(res)) {
+    if (evt.usage) usage = evt.usage;
+    const choice = evt.choices?.[0];
+    if (!choice) continue;
+    const delta = choice.delta || {};
+
+    if (delta.content) {
+      text += delta.content;
+      onToken(delta.content);
+    }
+    const think = delta.reasoning_content || delta.reasoning;
+    if (think) {
+      reasoning += think;
+      if (typeof onReasoningToken === "function") onReasoningToken(think);
+    }
+
+    for (const tc of delta.tool_calls || []) {
+      const i = Number.isFinite(tc.index) ? tc.index : calls.length;
+      if (!calls[i]) calls[i] = { id: "", type: "function", function: { name: "", arguments: "" } };
+      const slot = calls[i];
+      if (tc.id) slot.id = tc.id;
+      if (tc.type) slot.type = tc.type;
+      if (tc.function?.name) slot.function.name += tc.function.name;
+      if (tc.function?.arguments) slot.function.arguments += tc.function.arguments;
+    }
+
+    if (choice.finish_reason) finishReason = choice.finish_reason;
+  }
+
+  const toolCalls = calls.filter((c) => c?.function?.name);
+  return {
+    text,
+    reasoning,
+    tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
+    finish_reason: finishReason,
+    usage: {
+      input_tokens: usage?.prompt_tokens || 0,
+      output_tokens: usage?.completion_tokens || 0,
+    },
+    raw: null,
+  };
+}

package/src/core/engines/presets.js

@@ -24,34 +24,40 @@ export const ENGINE_PRESETS = {
     default_model: "claude-sonnet-5",
     api_key_env: "ANTHROPIC_API_KEY",
     known_models: [
-      "claude-opus-4-8",
+      "claude-fable-5",
+      "claude-opus-5",
       "claude-sonnet-5",
       "claude-haiku-4-5",
-      "claude-fable-5",
+      "claude-opus-4-8",
+      "claude-sonnet-4-6",
     ],
   },
   openai: {
     base_url: "https://api.openai.com/v1",
-    default_model: "gpt-5.4-mini",
+    default_model: "gpt-5.6-luna",
     api_key_env: "OPENAI_API_KEY",
     known_models: [
+      "gpt-5.6-sol",
+      "gpt-5.6-terra",
+      "gpt-5.6-luna",
       "gpt-5.5",
       "gpt-5.4-mini",
       "gpt-5.4-nano",
-      "gpt-5.1",
-      "gpt-4.1-mini",
     ],
   },
   gemini: {
     base_url: "https://generativelanguage.googleapis.com/v1beta/openai",
-    default_model: "gemini-2.5-flash",
+    default_model: "gemini-3.7-flash",
     api_key_env: "GEMINI_API_KEY",
     known_models: [
+      "gemini-3.7-flash",
+      "gemini-3.6-flash",
       "gemini-3.5-flash",
+      "gemini-3.5-flash-lite",
       "gemini-3.1-pro-preview",
+      "gemini-3.1-flash-lite",
       "gemini-2.5-pro",
       "gemini-2.5-flash",
-      "gemini-2.5-flash-lite",
     ],
   },
   groq: {
@@ -75,9 +81,12 @@ export const ENGINE_PRESETS = {
     known_models: [
       "openrouter/auto",
       "openrouter/free",
+      "anthropic/claude-opus-5",
       "anthropic/claude-sonnet-5",
-      "openai/gpt-5.4-mini",
-      "google/gemini-2.5-flash",
+      "openai/gpt-5.6-sol",
+      "openai/gpt-5.6-terra",
+      "google/gemini-3.7-flash",
+      "qwen/qwen3.8-27b",
     ],
   },
   azure: {
@@ -92,6 +101,24 @@ export const ENGINE_PRESETS = {
     api_key_env: "",
     known_models: [], // dynamic — fetched live from the local Ollama daemon
   },
+  // OpenCode Zen. The free-tier ids are listed first: they bill at zero.
+  // Free models need the opencode User-Agent (see zen.js ZEN_HEADERS) and
+  // accept api_key "public" when no personal key is set. Paid Claude/GPT/
+  // Gemini models on the same base URL need a real Zen key.
+  zen: {
+    base_url: "https://opencode.ai/zen/v1",
+    default_model: "big-pickle",
+    api_key_env: "OPENCODE_ZEN_API_KEY",
+    known_models: [
+      "big-pickle",
+      "nemotron-3-ultra-free",
+      "nemotron-3.5-lightning-free",
+      "deepseek-v4-flash-free",
+      "laguna-s-2.1-free",
+      "mimo-v2.5-free",
+      "hy3-free",
+    ],
+  },
   mock: { base_url: "", default_model: "mock", api_key_env: "", known_models: ["mock"] },
   custom: { base_url: "", default_model: "", api_key_env: "", known_models: [] },
 };

package/src/core/engines/zen.js

@@ -0,0 +1,131 @@
+// OpenCode Zen — an OpenAI-compatible gateway in front of many vendors'
+// models, including a handful the provider serves at no cost.
+//
+// The free models are the reason this engine exists: with a Zen key they bill
+// at zero, which makes them a real option for an agent that runs all day. The
+// key is not optional, though. Zen also fronts paid Claude/GPT/Gemini models on
+// the same base URL, and the same key is what tells the two apart — so it is
+// required here like any other provider's.
+import { createOpenAiCompatibleEngine } from "./openai-compatible.js";
+import { matchesModelGlob, modelListFromConfig } from "./_globs.js";
+
+// The free tier is gated on the caller naming itself as the opencode client,
+// not only on the key: byte-for-byte the same request answers 429
+// FreeUsageLimitError without this User-Agent and 200 with it. So it travels
+// with every Zen call — chat, health and the model catalog. It is a pinned
+// version string, and pins go stale; `engines.zen.headers` overrides it from
+// config when Zen starts asking for a newer one.
+//
+// Pair with api_key "public" (or any Zen key). Missing UA → 429. Missing key
+// with UA still works for free models when the adapter falls back to "public".
+export const ZEN_HEADERS = { "user-agent": "opencode/1.18.18" };
+
+// Which models demand their own thinking back on every subsequent request.
+//
+// DeepSeek's thinking mode treats `reasoning_content` as part of the assistant
+// turn, not as a by-product of it: replay the turn without it and the upstream
+// answers
+//   400 [invalid_request_error] The `reasoning_content` in the thinking mode
+//       must be passed back to the API.
+// The first turn always works, so this only bites once the loop has an
+// assistant turn in history — i.e. the long, tool-heavy turns.
+//
+// Same mechanism as Gemini's thought signatures, and scoped the same way: a
+// glob list, one entry per family. Scoped to v4+ ON PURPOSE — the older
+// reasoners (deepseek-r1, deepseek-v3) do the exact opposite and 400 when
+// `reasoning_content` appears in the context, so widening this to `deepseek-*`
+// would trade one failure for another. v5 is a forward default: the
+// requirement is a family trait, not a per-version quirk.
+export const REASONING_REPLAY_MODELS = ["deepseek-v4*", "deepseek-v5*"];
+
+// Per-install override, no code change required:
+//   engines.zen.reasoning_replay_models: ["deepseek-v4*", "some-new-reasoner*"]
+export function modelReplaysReasoning(model, config = {}) {
+  return matchesModelGlob(
+    model,
+    modelListFromConfig(config?.reasoning_replay_models, REASONING_REPLAY_MODELS)
+  );
+}
+
+/**
+ * Put `reasoning_content` back on assistant turns for the models that require
+ * it. `run-agent.js` stores it as `_reasoning` on the turn it came from; the
+ * underscore keeps it off the wire for every other model, since the shared
+ * serialiser copies only the fields it knows.
+ *
+ * When the field is missing there is nothing to do and nothing to invent — a
+ * turn inherited from another engine after a fallback rotation never had one.
+ * That case is caught by the retry classifier, which rotates off the model
+ * instead of failing the run.
+ */
+function replayReasoningContent(entry, source, { model, config }) {
+  if (entry.role !== "assistant") return;
+  if (!modelReplaysReasoning(model, config)) return;
+  const reasoning = source?._reasoning || source?.reasoning_content;
+  if (typeof reasoning === "string" && reasoning) entry.reasoning_content = reasoning;
+}
+
+// Free-tier key. With ZEN_HEADERS the gateway answers 200 for big-pickle and
+// the other *-free models; without the UA it answers 429 FreeUsageLimitError
+// even when the key is valid. Prefer a real OPENCODE_ZEN_API_KEY / engines.zen
+// api_key when present (paid models need one); fall back to "public" so agents
+// are never left keyless on the free tier.
+export const ZEN_PUBLIC_API_KEY = "public";
+
+const base = createOpenAiCompatibleEngine({
+  id: "zen",
+  defaultBaseUrl: "https://opencode.ai/zen/v1",
+  apiKeyEnv: "OPENCODE_ZEN_API_KEY",
+  defaultFallbackModel: "zen:big-pickle",
+  extraHeaders: ZEN_HEADERS,
+  decorateMessage: replayReasoningContent,
+  defaultApiKey: ZEN_PUBLIC_API_KEY,
+});
+
+/** The cheapest model that still proves a key works: free, one token. */
+const PROBE_MODEL = "big-pickle";
+
+// Zen serves its catalog to anyone — `GET /models` answers 200 with no key at
+// all, and 200 again with a made-up one. The shared health check reads that as
+// "connected", so a typo in the key would show a healthy provider that fails on
+// the first real turn. Here the probe has to be a completion: one token against
+// a free model, which costs nothing and is the only answer the gateway gives
+// that actually depends on the key. Empty config still probes with "public".
+export default {
+  ...base,
+
+  async health(config = {}, { timeoutMs = 800 } = {}) {
+    const key = config?.api_key || process.env.OPENCODE_ZEN_API_KEY || ZEN_PUBLIC_API_KEY;
+    if (!key) return { ok: false, provider: "zen", reason: "no api_key" };
+
+    const url = `${String(config?.base_url || base.defaultBaseUrl).replace(/\/$/, "")}/chat/completions`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), Math.max(timeoutMs, 4000));
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: base.buildHeaders(config, {
+          "content-type": "application/json",
+          authorization: `Bearer ${key}`,
+        }),
+        body: JSON.stringify({
+          model: config?.model || PROBE_MODEL,
+          messages: [{ role: "user", content: "ping" }],
+          max_tokens: 1,
+        }),
+        signal: controller.signal,
+      });
+      if (res.ok) return { ok: true, provider: "zen", detail: url };
+      if (res.status === 401 || res.status === 403) {
+        return { ok: false, provider: "zen", reason: "api_key rechazada por Zen" };
+      }
+      // Anything else (a rate limit, a model that went away) says nothing about
+      // the key, so the chain is allowed to try — flagged, not blocked.
+      return { ok: true, provider: "zen", detail: url, soft: true, reason: `HTTP ${res.status}` };
+    } catch (e) {
+      return { ok: true, provider: "zen", detail: url, soft: true, reason: e.message };
+    } finally {
+      clearTimeout(timer);
+    }
+  },
+};

package/src/core/events/bus.js

@@ -0,0 +1,140 @@
+// The in-process event bus: "this just happened", for anyone in the SAME
+// process who cares.
+//
+// Why it exists: every channel writes its turns through one of two funnels in
+// stores/messages.js. Until now nothing announced those writes, so a surface
+// that wanted to show a conversation as it happens had no choice but to poll —
+// the web inbox re-fetched every 15s and an open thread never re-fetched at
+// all. A message that arrived on Telegram was invisible to a browser sitting
+// on the same conversation until someone reloaded the page.
+//
+// Layering (rule 8): core EMITS and never listens. It knows nothing about
+// WebSockets, clients or the daemon — the emitted event carries only facts core
+// already has (which channel, which day file, which project root). The daemon
+// subscribes in host/daemon/events-ws.js, enriches what it alone knows (a
+// project root is an id there, not here) and fans it out. Moving the emit
+// upward into the adapter was the alternative and it does not work: the writes
+// happen deep inside the Telegram dispatch and the agent loop, not at a route.
+//
+// SCOPE, and its one real limit: an EventEmitter is per PROCESS. Every write
+// that matters happens inside the daemon — it owns the HTTP API, the Telegram
+// poller and the agent loop, and the CLI reaches it over HTTP — so the daemon's
+// subscriber sees them all. A second process writing straight to the JSONL
+// (a script, a test) is NOT announced. That is by design: the bus reports what
+// this process did, it is not a filesystem watcher.
+import { EventEmitter } from "node:events";
+
+const bus = new EventEmitter();
+// One listener per subscriber, but a daemon may hold several (the WS hub today,
+// more later) and Node warns at 10. Raise it rather than leak a real warning.
+bus.setMaxListeners(50);
+
+export const MESSAGE_EVENT = "message";
+
+/**
+ * A message was appended to the ledger.
+ *
+ * @param {object} event
+ *   - scope        "global" (cross-project channel) | "project"
+ *   - channel      telegram | web | desktop | …
+ *   - thread       the day file's id (YYYY-MM-DD) — what a thread is addressed by
+ *   - project_id   for a global write, whatever the record's meta claimed (may be null)
+ *   - project_root for a project write, the storage path — the daemon maps it to an id
+ *   - agent_slug   the agent the turn belongs to, when the write named one
+ *   - direction    in | out
+ *   - type         user | agent | tool | system | compact
+ *   - author       display name of who wrote the row, when the writer had one
+ *   - final        true when this row is the closing message of a turn
+ *   - streamed     true when this row is a mid-turn Telegram chunk
+ *   - ts           the record's timestamp
+ *
+ * Never throws into the caller: an announcement failing must not fail the write
+ * that produced it. The ledger is the source of truth; this is a notification.
+ */
+export function emitMessageEvent(event) {
+  try {
+    bus.emit(MESSAGE_EVENT, event);
+  } catch {
+    /* a broken listener is the listener's problem, not the writer's */
+  }
+}
+
+/** Subscribe to message events. Returns the unsubscribe function. */
+export function onMessageEvent(fn) {
+  bus.on(MESSAGE_EVENT, fn);
+  return () => bus.off(MESSAGE_EVENT, fn);
+}
+
+export const ROUTINE_EVENT = "routine";
+
+/**
+ * A routine run started, moved a step, or ended.
+ *
+ * Same layering as the message event above: core emits the facts it already
+ * has (which project root, which routine, the run record) and never listens.
+ * The daemon subscribes in host/daemon/events-ws.js, maps the root to a project
+ * id and fans it out.
+ *
+ * Unlike a message event this one CARRIES the step, on purpose. A run's steps
+ * are not in the ledger while it runs — they are written once, at the end — so
+ * "re-fetch through the API you already use" has nothing to fetch. The live
+ * record IS the data, exactly like the turn frames in events-ws.js.
+ *
+ * @param {object} event
+ *   - phase        start | progress | end
+ *   - project_root the project's storage path — the daemon maps it to an id
+ *   - routine      the routine's name
+ *   - run          the public run record (core/routines/active-runs.js)
+ */
+export function emitRoutineEvent(event) {
+  try {
+    bus.emit(ROUTINE_EVENT, event);
+  } catch {
+    /* a broken listener is the listener's problem, not the runner's */
+  }
+}
+
+/** Subscribe to routine-run events. Returns the unsubscribe function. */
+export function onRoutineEvent(fn) {
+  bus.on(ROUTINE_EVENT, fn);
+  return () => bus.off(ROUTINE_EVENT, fn);
+}
+
+/** Drop every listener. For tests, and for a clean daemon shutdown. */
+export function resetEventBus() {
+  bus.removeAllListeners();
+}
+
+export const MOBILITY_ALERT_EVENT = "mobility_alert";
+
+/**
+ * A proximity alert is going out, as the CARD rather than as a rendered line.
+ *
+ * This is the one event that carries its whole payload. The message events
+ * above are signals — "thread X moved, go re-fetch" — because a browser can
+ * ask. The phone cannot: it is on a mobile connection, possibly on a head unit,
+ * and the alert has to become a notification with four buttons within a second
+ * of the car passing the place. A round trip to fetch what the frame could have
+ * carried is a round trip that fails in a tunnel.
+ *
+ * It exists so the alert does NOT depend on Telegram. Proximity delivery used
+ * to be a Telegram send whose ledger row Android turned into a card, so a
+ * daemon with no Telegram plugin loaded — or a phone whose owner never wired
+ * one up — got no alert at all, on the surface where it matters most.
+ *
+ * @param {object} card  core/mobility/geofence.js proximityCard() — emoji-free,
+ *                       four labelled actions, two Maps URIs.
+ */
+export function emitMobilityAlert(card) {
+  try {
+    bus.emit(MOBILITY_ALERT_EVENT, card);
+  } catch {
+    /* a broken listener must not fail the alert that produced it */
+  }
+}
+
+/** Subscribe to proximity-alert cards. Returns the unsubscribe function. */
+export function onMobilityAlert(fn) {
+  bus.on(MOBILITY_ALERT_EVENT, fn);
+  return () => bus.off(MOBILITY_ALERT_EVENT, fn);
+}