niahere 0.4.6 → 0.5.1

package/src/agent/registry.ts

@@ -1,51 +1,76 @@
+import { existsSync } from "fs";
 import type { AgentBackend } from "./types";
+import type { ChainEntry } from "./chain";
 import { ClaudeBackend } from "./backends/claude";
-import { CodexBackend } from "./backends/codex";
+import { CodexBackend, resolveCodexBin } from "./backends/codex";
 import { getConfig } from "../utils/config";
+import { resolveModel, providerDefault, PROVIDER_ORDER, type ProviderName } from "./models";
 
-/**
- * Backend selection — the ONE place backend identity is resolved. Consumers call
- * `getBackend()` and depend only on the `AgentBackend` interface, so no
- * `if (backend === …)` ever leaks into the orchestration loop.
- *
- * Phase 1: always the in-process Claude backend. Phase 2+ adds Codex/Gemini and
- * a role/per-job selector; Phase 3 adds the ordered-fallback failover list.
- */
+/** The ONE place backend identity is resolved. */
 let claudeBackend: ClaudeBackend | null = null;
 let codexBackend: CodexBackend | null = null;
 let override: AgentBackend | null = null;
-let chainOverride: AgentBackend[] | null = null;
+let chainOverride: ChainEntry[] | null = null;
 
-export function getBackend(name?: "claude" | "codex" | "gemini"): AgentBackend {
+export function getBackend(name?: ProviderName): AgentBackend {
   if (override) return override;
-  if (name === "codex") {
-    if (!codexBackend) codexBackend = new CodexBackend();
-    return codexBackend;
-  }
-  if (!claudeBackend) claudeBackend = new ClaudeBackend();
-  return claudeBackend;
+  if (name === "codex") return (codexBackend ??= new CodexBackend());
+  return (claudeBackend ??= new ClaudeBackend());
 }
 
-/** Test seam: force `getBackend()` to return a specific backend; pass null to reset. */
+/** Test seam: force `getBackend()` to return a specific backend; null resets. */
 export function setBackend(backend: AgentBackend | null): void {
   override = backend;
 }
 
-/** Test seam: force `resolveBackends()` to return a specific chain; null resets. */
-export function setBackendChain(backends: AgentBackend[] | null): void {
-  chainOverride = backends;
+/** Test seam: force `resolveChain()` to return a specific chain; null resets. */
+export function setBackendChain(chain: ChainEntry[] | null): void {
+  chainOverride = chain;
+}
+
+/** Gemini is resolvable in config but has no adapter yet. */
+const IMPLEMENTED: ProviderName[] = ["claude", "codex"];
+
+function isAvailable(provider: ProviderName): boolean {
+  if (provider === "claude") return true;
+  if (provider === "codex") return existsSync(resolveCodexBin());
+  return false;
+}
+
+export interface ChainDeps {
+  available: (provider: ProviderName) => boolean;
 }
 
 /**
- * The ordered backend chain for a run: the configured primary first, then any
- * fallbacks (provider-down failover), de-duplicated. Consumers try each in order
- * until one isn't provider-down.
+ * Providers the config never named are appended with their default model, so a
+ * bare config still has somewhere to go — but only if they can run here.
+ * Configured models are always kept, so a misconfiguration surfaces as a real
+ * error rather than vanishing.
  */
-export function resolveBackends(): AgentBackend[] {
+export function buildChain(
+  model: string,
+  fallbackModels: string[],
+  deps: ChainDeps = { available: isAvailable },
+): ChainEntry[] {
+  const configured = [model, ...fallbackModels].map(resolveModel);
+  const named = new Set(configured.map((r) => r.provider));
+  const implicit = PROVIDER_ORDER.filter((p) => !named.has(p) && deps.available(p)).map(providerDefault);
+
+  const seen = new Set<string>();
+  const entries: ChainEntry[] = [];
+  for (const ref of [...configured, ...implicit]) {
+    if (!IMPLEMENTED.includes(ref.provider)) continue;
+    const key = `${ref.provider}:${ref.model ?? ""}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    entries.push({ backend: getBackend(ref.provider), model: ref.model });
+  }
+  return entries;
+}
+
+export function resolveChain(): ChainEntry[] {
   if (chainOverride) return chainOverride;
-  if (override) return [override];
+  if (override) return [{ backend: override }];
   const cfg = getConfig();
-  const seen = new Set<string>();
-  const names = [cfg.runner, ...cfg.fallback].filter((n) => !seen.has(n) && seen.add(n));
-  return names.map((n) => getBackend(n));
+  return buildChain(cfg.model, cfg.fallback_models);
 }

package/src/agent/types.ts

@@ -32,9 +32,11 @@ export interface AgentUsage {
  * - `text`/`thinking`: streamed reply / status (→ onStream / onActivity).
  * - `tool`: a tool-call activity line.
  * - `result`/`error`: terminal events ending a turn.
- * - `error.retryable` (transient API failure → the backend may retry internally)
- *   and `error.providerDown` (the provider is unavailable → failover trigger) are
- *   INDEPENDENT predicates.
+ * - `error.retryable` (the backend may retry in place) is independent of
+ *   `error.failover`, which scopes how far the chain skips:
+ *   `"model"` advances one entry (possibly the same provider, another model),
+ *   `"provider"` skips that provider's remaining entries, absent stops the
+ *   chain because the task itself failed.
  */
 export type AgentEvent =
   | { type: "session"; backendSessionId: string }
@@ -52,7 +54,10 @@ export type AgentEvent =
        *  Opaque to the orchestrator. */
       metadata?: Record<string, unknown>;
     }
-  | { type: "error"; message: string; retryable: boolean; providerDown: boolean; terminalReason?: string };
+  | { type: "error"; message: string; retryable: boolean; failover?: FailoverScope; terminalReason?: string };
+
+/** How far the chain skips after a failure. See `AgentEvent`. */
+export type FailoverScope = "model" | "provider";
 
 export function isResultEvent(ev: AgentEvent): ev is Extract<AgentEvent, { type: "result" }> {
   return ev.type === "result";

package/src/channels/common/chat-session.ts

@@ -54,3 +54,63 @@ export async function rotateRoom(
 export function chainLock(state: ChatState, fn: () => Promise<void>): void {
   state.lock = state.lock.then(fn, fn);
 }
+
+/** Seam so the registry is testable without a database. */
+export interface SessionOpener {
+  open(prefix: string, build: EngineFactory): Promise<ChatState>;
+  rotate(prefix: string, prev: ChatState | undefined, build: EngineFactory): Promise<ChatState>;
+}
+
+const defaultOpener: SessionOpener = { open: openChatEngine, rotate: rotateRoom };
+
+/**
+ * A channel's per-sender chat sessions. Every message-driven channel keeps one
+ * of these keyed by sender, and they all want the same four things: open on
+ * first use, reuse after, rotate on `/reset`, close everything on shutdown.
+ */
+export class ChatSessions<K> {
+  private readonly states = new Map<K, ChatState>();
+
+  constructor(
+    private readonly prefixFor: (key: K) => string,
+    private readonly build: EngineFactory,
+    private readonly opener: SessionOpener = defaultOpener,
+  ) {}
+
+  /** `build` overrides the default options for this call — Slack needs it to
+   *  thread watch behavior and thread context into a newly opened engine. */
+  async get(key: K, build: EngineFactory = this.build): Promise<ChatState> {
+    const existing = this.states.get(key);
+    if (existing) return existing;
+    const state = await this.opener.open(this.prefixFor(key), build);
+    this.states.set(key, state);
+    return state;
+  }
+
+  /** Start a fresh room for this sender, closing the previous one. */
+  async rotate(key: K, build: EngineFactory = this.build): Promise<ChatState> {
+    const state = await this.opener.rotate(this.prefixFor(key), this.states.get(key), build);
+    this.states.set(key, state);
+    return state;
+  }
+
+  /** The cached session, without opening one. */
+  peek(key: K): ChatState | undefined {
+    return this.states.get(key);
+  }
+
+  /** Whether a session is already open — Slack uses it to tell a live thread
+   *  from one it should ignore. */
+  has(key: K): boolean {
+    return this.states.has(key);
+  }
+
+  keys(): Iterable<K> {
+    return this.states.keys();
+  }
+
+  closeAll(): void {
+    for (const state of this.states.values()) state.engine.close();
+    this.states.clear();
+  }
+}

package/src/channels/phone/consult.ts

@@ -6,6 +6,7 @@
  * Heavyweight (multi-second latency) by design — keep usage selective.
  */
 import Anthropic from "@anthropic-ai/sdk";
+import { errMsg } from "../../utils/errors";
 import { loadIdentity } from "../../chat/identity";
 import { log } from "../../utils/log";
 
@@ -38,6 +39,6 @@ export async function consultClaude(question: string, callerLabel: string): Prom
     return "(no answer)";
   } catch (err) {
     log.error({ err }, "phone: consult_claude failed");
-    return `error consulting Claude: ${err instanceof Error ? err.message : String(err)}`;
+    return `error consulting Claude: ${errMsg(err)}`;
   }
 }

package/src/channels/phone/index.ts

@@ -25,6 +25,7 @@ import type { ServerWebSocket } from "bun";
 import type { Channel, Outbound, PhoneConfig, TwilioConfig } from "../../types";
 import { getConfig } from "../../utils/config";
 import { log } from "../../utils/log";
+import { ignore } from "../../utils/errors";
 import { getChannel } from "../registry";
 import { Session, Message } from "../../db/models";
 import { runMigrations } from "../../db/migrate";
@@ -194,9 +195,10 @@ class PhoneChannel implements Channel {
 
     if (!allowed) {
       log.warn({ from, callSid }, "phone: rejecting unauthorized caller");
-      getChannel("telegram")
-        ?.deliver({ text: `Phone: rejected call from ${from} (CallSid ${callSid})` })
-        .catch(() => {});
+      const notice = getChannel("telegram")?.deliver({
+        text: `Phone: rejected call from ${from} (CallSid ${callSid})`,
+      });
+      if (notice) void ignore(notice, "notify rejected caller");
       return twimlResponse(sayAndHangupTwiML("Sorry, this line is not currently accepting calls. Goodbye."));
     }
 

package/src/channels/phone/relay.ts

@@ -12,6 +12,7 @@
  *   const result = await relay.completion;
  */
 import { log } from "../../utils/log";
+import { errMsg } from "../../utils/errors";
 
 export interface PhoneToolDefinition {
   name: string;
@@ -57,6 +58,17 @@ export interface RelayOpts {
   model: string;
   voice: string;
   context: CallContext;
+  /** Injectable so the bridge is testable without dialing OpenAI. */
+  openAiWsFactory?: (url: string, key: string) => OpenAiSocket;
+}
+
+/** The slice of the realtime socket the relay drives. */
+export interface OpenAiSocket extends WebSocketLike {
+  addEventListener(type: string, listener: (ev: any) => void): void;
+}
+
+function connectOpenAi(url: string, key: string): OpenAiSocket {
+  return new WebSocket(url, { headers: { Authorization: `Bearer ${key}` } } as any) as unknown as OpenAiSocket;
 }
 
 export interface WebSocketLike {
@@ -76,7 +88,7 @@ export interface RelayHandle {
 }
 
 export function createRelay(opts: RelayOpts): RelayHandle {
-  const { twilioWs, openAiKey, model, voice, context } = opts;
+  const { twilioWs, openAiKey, model, voice, context, openAiWsFactory = connectOpenAi } = opts;
   const transcript: TranscriptTurn[] = [];
   let endedReason: RelayEndReason = "twilio_stop";
   let errorMsg: string | undefined;
@@ -84,9 +96,7 @@ export function createRelay(opts: RelayOpts): RelayHandle {
   let pendingAssistantText = "";
 
   const openAiUrl = `wss://api.openai.com/v1/realtime?model=${encodeURIComponent(model)}`;
-  const openAiWs = new WebSocket(openAiUrl, {
-    headers: { Authorization: `Bearer ${openAiKey}` },
-  } as any);
+  const openAiWs = openAiWsFactory(openAiUrl, openAiKey);
 
   /** Whether a response is currently in flight on the OpenAI side. */
   let responseActive = false;
@@ -268,7 +278,7 @@ export function createRelay(opts: RelayOpts): RelayHandle {
           try {
             output = await tool.handler(args);
           } catch (err) {
-            output = `error: ${err instanceof Error ? err.message : String(err)}`;
+            output = `error: ${errMsg(err)}`;
             log.error({ err, callSid: context.callSid, toolName }, "phone tool handler failed");
           }
         }

package/src/channels/slack.ts

@@ -5,11 +5,14 @@ import { relativeTime } from "../utils/format";
 import { runMigrations } from "../db/migrate";
 import { Session, Message } from "../db/models";
 import { log } from "../utils/log";
+import { errMsg, ignore } from "../utils/errors";
 import { getMcpServers } from "../mcp";
-import { chainLock, openChatEngine, rotateRoom } from "./common/chat-session";
+import { ChatSessions, chainLock } from "./common/chat-session";
 import { SlackAttachmentCache } from "./slack/attachments";
 import { SlackWatchReloader } from "./slack/watch";
 
+const logActivity = (status: string) => log.debug({ status }, "slack engine activity");
+
 /** Strip markdown backticks so sentinel tokens like [NO_REPLY] match even when the LLM wraps them. */
 function cleanSentinel(text: string): string {
   return text.replace(/`/g, "").trim();
@@ -75,7 +78,7 @@ class SlackChannel implements Channel {
 
     this.dmUserId = config.channels.slack.dm_user_id;
 
-    const chats = new Map<string, ChatState>();
+    const chats = new ChatSessions<string>(roomPrefix, buildEngineOpts());
     const channelNames = new Map<string, string>();
 
     async function resolveChannelName(app: App, channelId: string): Promise<string> {
@@ -111,30 +114,20 @@ class SlackChannel implements Channel {
       });
     }
 
-    async function getState(
+    const getState = (
       key: string,
       watchBehavior?: { channel: string; behavior: string },
       slackCtx?: SlackContext,
-    ): Promise<ChatState> {
-      let state = chats.get(key);
-      if (state) return state;
-      state = await openChatEngine(roomPrefix(key), buildEngineOpts(watchBehavior, slackCtx));
-      chats.set(key, state);
-      return state;
-    }
+    ): Promise<ChatState> => chats.get(key, buildEngineOpts(watchBehavior, slackCtx));
 
-    async function restartChat(
+    const restartChat = (
       key: string,
       watchBehavior?: { channel: string; behavior: string },
       slackCtx?: SlackContext,
-    ): Promise<ChatState> {
-      const state = await rotateRoom(roomPrefix(key), chats.get(key), buildEngineOpts(watchBehavior, slackCtx));
-      chats.set(key, state);
-      return state;
-    }
+    ): Promise<ChatState> => chats.rotate(key, buildEngineOpts(watchBehavior, slackCtx));
 
     function withLock(key: string, fn: () => Promise<void>): void {
-      const state = chats.get(key);
+      const state = chats.peek(key);
       if (!state) {
         fn().catch((err) => log.error({ err, key }, "unhandled error in locked handler"));
         return;
@@ -177,13 +170,11 @@ class SlackChannel implements Channel {
         withLock(key, async () => {
           try {
             const { result } = await state.engine.send(subcommand, {
-              onActivity(status) {
-                log.debug({ status }, "slack engine activity");
-              },
+              onActivity: logActivity,
             });
             await respond(result.trim() || "(no response)");
           } catch (err) {
-            const errText = err instanceof Error ? err.message : String(err);
+            const errText = errMsg(err);
             await respond(`[error] ${errText}`);
           }
         });
@@ -437,9 +428,7 @@ class SlackChannel implements Channel {
           const { result, messageId, signal } = await state.engine.send(
             text,
             {
-              onActivity(status) {
-                log.debug({ status }, "slack engine activity");
-              },
+              onActivity: logActivity,
             },
             attachments,
           );
@@ -448,7 +437,7 @@ class SlackChannel implements Channel {
             await reactToSlackMessage(client, msg.channel, msg.ts, "skull").catch((err) =>
               log.debug({ err, channel: msg.channel }, "slack: failed to add provider-down reaction"),
             );
-            if (messageId) await Message.updateDeliveryStatus(messageId, "sent").catch(() => {});
+            if (messageId) await ignore(Message.updateDeliveryStatus(messageId, "sent"), "record sent delivery status");
             log.info({ channel: msg.channel, key, reaction: "skull" }, "slack provider failure sent as reaction");
             return;
           }
@@ -468,7 +457,7 @@ class SlackChannel implements Channel {
                 "slack: [NO_REPLY] sentinel mixed with content; suppressing send",
               );
             }
-            if (messageId) await Message.updateDeliveryStatus(messageId, "sent").catch(() => {});
+            if (messageId) await ignore(Message.updateDeliveryStatus(messageId, "sent"), "record sent delivery status");
             return;
           }
 
@@ -482,26 +471,27 @@ class SlackChannel implements Channel {
             } else {
               await say(reply);
             }
-            if (messageId) await Message.updateDeliveryStatus(messageId, "sent").catch(() => {});
+            if (messageId) await ignore(Message.updateDeliveryStatus(messageId, "sent"), "record sent delivery status");
             log.info({ channel: msg.channel, key, chars: reply.length }, "slack reply sent");
           } catch (sendErr) {
-            if (messageId) await Message.updateDeliveryStatus(messageId, "failed").catch(() => {});
+            if (messageId) await ignore(Message.updateDeliveryStatus(messageId, "failed"), "record failed delivery status");
             throw sendErr;
           }
         } catch (err) {
-          const errText = err instanceof Error ? err.message : String(err);
+          const errText = errMsg(err);
           log.error({ err, channel: msg.channel }, "slack message processing failed");
 
           if (replyThreadTs) {
-            await client.chat
-              .postMessage({
+            await ignore(
+              client.chat.postMessage({
                 channel: msg.channel,
                 text: `[error] ${errText}`,
                 thread_ts: replyThreadTs,
-              })
-              .catch(() => {});
+              }),
+              "reply engine error in thread",
+            );
           } else {
-            await say(`[error] ${errText}`).catch(() => {});
+            await ignore(say(`[error] ${errText}`), "reply engine error");
           }
         } finally {
           await client.reactions

package/src/channels/sms.ts

@@ -16,25 +16,29 @@
  */
 import { getMcpServers } from "../mcp";
 import { runMigrations } from "../db/migrate";
-import type { Channel, ChatState, Outbound, TwilioConfig } from "../types";
+import type { Channel, Outbound, TwilioConfig } from "../types";
 import { getConfig } from "../utils/config";
 import { log } from "../utils/log";
+import { errMsg, ignore } from "../utils/errors";
 import { sendMessage as twilioSendMessage } from "./twilio/rest";
 import { getTwilioServer } from "./twilio/server";
-import { chainLock, openChatEngine } from "./common/chat-session";
-
-const EMPTY_TWIML = '<?xml version="1.0" encoding="UTF-8"?><Response></Response>';
+import { ChatSessions, chainLock } from "./common/chat-session";
+import { ackTwiml, deliveryStatusAck, isAllowedSender } from "./twilio/shared";
 
 class SmsChannel implements Channel {
   name = "sms" as const;
   private readonly twilio: TwilioConfig;
   /** Cached resolved "from" number: sms.from_number || phone.from_number */
   private readonly fromNumber: string;
-  private readonly chats = new Map<string, ChatState>();
+  private readonly chats: ChatSessions<string>;
 
   constructor(twilio: TwilioConfig, fromNumber: string) {
     this.twilio = twilio;
     this.fromNumber = fromNumber;
+    this.chats = new ChatSessions((remote) => `sms-${remote}`, () => ({
+      channel: "sms",
+      mcpServers: getMcpServers(),
+    }));
   }
 
   async start(): Promise<void> {
@@ -70,8 +74,7 @@ class SmsChannel implements Channel {
   }
 
   async stop(): Promise<void> {
-    for (const state of this.chats.values()) state.engine.close();
-    this.chats.clear();
+    this.chats.closeAll();
   }
 
   /** Outbound — used by send_message MCP tool. SMS is text-only; media is dropped with a warning. */
@@ -92,12 +95,12 @@ class SmsChannel implements Channel {
     const from = params.From || "";
     const body = params.Body || "";
 
-    if (!this.isAllowed(from)) {
+    if (!isAllowedSender(this.twilio, from)) {
       log.warn({ from }, "sms: rejecting non-allowlisted sender");
-      return new Response(EMPTY_TWIML, { status: 200, headers: { "Content-Type": "text/xml" } });
+      return ackTwiml();
     }
 
-    const state = await this.getState(from);
+    const state = await this.chats.get(from);
     // Ack the webhook immediately; reply via REST asynchronously to avoid
     // Twilio's ~15s webhook timeout when the engine takes longer.
     chainLock(state, async () => {
@@ -107,24 +110,15 @@ class SmsChannel implements Channel {
         await this.sendTo(from, reply);
       } catch (err) {
         log.error({ err, from }, "sms: engine error");
-        await this.sendTo(from, `[error] ${err instanceof Error ? err.message : String(err)}`).catch(() => {});
+        await ignore(this.sendTo(from, `[error] ${errMsg(err)}`), "reply engine error");
       }
     });
 
-    return new Response(EMPTY_TWIML, { status: 200, headers: { "Content-Type": "text/xml" } });
+    return ackTwiml();
   }
 
   private handleStatus(params: Record<string, string>): Response {
-    log.info(
-      {
-        messageSid: params.MessageSid,
-        status: params.MessageStatus,
-        errorCode: params.ErrorCode,
-        to: params.To,
-      },
-      "sms: delivery status",
-    );
-    return new Response("", { status: 204 });
+    return deliveryStatusAck("sms", params);
   }
 
   // --- Outbound ---
@@ -153,20 +147,6 @@ class SmsChannel implements Channel {
     }
   }
 
-  // --- Helpers ---
-
-  private isAllowed(remoteE164: string): boolean {
-    if (this.twilio.owner_number && remoteE164 === this.twilio.owner_number) return true;
-    return this.twilio.allowlist.includes(remoteE164);
-  }
-
-  private async getState(remoteE164: string): Promise<ChatState> {
-    let state = this.chats.get(remoteE164);
-    if (state) return state;
-    state = await openChatEngine(`sms-${remoteE164}`, () => ({ channel: "sms", mcpServers: getMcpServers() }));
-    this.chats.set(remoteE164, state);
-    return state;
-  }
 }
 
 export function createSmsChannel(): SmsChannel | null {