talon-agent 1.12.0 → 1.34.0

package/src/core/engine/backend-controller/pool.ts

@@ -0,0 +1,296 @@
+/**
+ * Pool lifecycle + role bindings + observability: init/teardown, role
+ * accessors, availability queries, the `/model` snapshot, and change
+ * listeners.
+ */
+
+import type { Backend } from "../../agent-runtime/capabilities.js";
+import type { TalonConfig } from "../../../util/config.js";
+import {
+  listBackends,
+  type BackendInitContext,
+} from "../../agent-runtime/backend-registry.js";
+import { log, logWarn } from "../../../util/log.js";
+import { roleHolder } from "./holders.js";
+import {
+  pool,
+  bindings,
+  listeners,
+  ctx,
+  ensurePoolEntry,
+  releaseHolderFromEntry,
+  resolveRoleBackendId,
+  hasBackendPool,
+} from "./state.js";
+import {
+  ALL_ROLES,
+  type BackendChangeListener,
+  type BackendHolder,
+  type BackendRole,
+  type PoolSnapshot,
+} from "./types.js";
+
+export { hasBackendPool };
+
+/**
+ * Initialise the backend pool with bindings for every role.
+ *
+ * Reads `config.backend` (chat), `config.heartbeatBackend` (heartbeat,
+ * falls back to chat), `config.dreamBackend` (dream, falls back to
+ * chat). Identical ids share a pool instance — Talon does NOT spin up
+ * two Claude SDK runtimes just because chat and heartbeat both want
+ * Claude.
+ *
+ * If any role's init fails, previously-initialised roles are torn
+ * down before the throw bubbles up — so a partial-init state never
+ * leaks past bootstrap.
+ */
+export async function initBackendPool(
+  config: TalonConfig,
+  initContext: BackendInitContext,
+): Promise<void> {
+  ctx.initCtx = initContext;
+  ctx.poolConfig = config;
+  const initialisedHolders: BackendHolder[] = [];
+  try {
+    for (const role of ALL_ROLES) {
+      const holder = roleHolder(role);
+      const id = resolveRoleBackendId(role, config);
+      const entry = await ensurePoolEntry(id, config);
+      entry.holders.add(holder);
+      bindings.set(holder, id);
+      initialisedHolders.push(holder);
+    }
+  } catch (err) {
+    // Roll back partial init — release every holder that succeeded so
+    // the pool isn't left holding orphaned instances.
+    for (const holder of initialisedHolders) {
+      const id = bindings.get(holder);
+      bindings.delete(holder);
+      if (id) {
+        const entry = pool.get(id);
+        if (entry) await releaseHolderFromEntry(entry, holder);
+      }
+    }
+    ctx.initCtx = null;
+    throw err;
+  }
+  const summary = ALL_ROLES.map(
+    (r) => `${r}=${bindings.get(roleHolder(r))}`,
+  ).join(" ");
+  log("backend-controller", `Pool initialised — ${summary}`);
+}
+
+/** Backend instance for a role. Throws if the role isn't bound. */
+export function getBackendForRole(role: BackendRole): Backend {
+  const holder = roleHolder(role);
+  const id = bindings.get(holder);
+  if (!id) {
+    throw new Error(
+      `Backend role "${role}" not bound — initialise the pool or rebind first`,
+    );
+  }
+  const entry = pool.get(id);
+  if (!entry) {
+    throw new Error(
+      `Backend role "${role}" bound to "${id}" but pool entry missing`,
+    );
+  }
+  return entry.backend;
+}
+
+/** Backend id bound to a role. Throws if the role isn't bound. */
+export function getBackendIdForRole(role: BackendRole): string {
+  const id = bindings.get(roleHolder(role));
+  if (!id) {
+    throw new Error(`Backend role "${role}" not bound`);
+  }
+  return id;
+}
+
+/** Display label for the role's bound backend. */
+export function getBackendLabelForRole(role: BackendRole): string {
+  const id = getBackendIdForRole(role);
+  const entry = pool.get(id);
+  if (!entry) {
+    throw new Error(`Pool entry for "${id}" missing`);
+  }
+  return entry.label;
+}
+
+/**
+ * All registered backends, optionally filtered by `config.enabledBackends`.
+ *
+ * When `config.enabledBackends` is set, only ids on the whitelist are
+ * returned (in the whitelist's order). When unset, every registered
+ * backend is returned, sorted by id for deterministic output.
+ */
+export function listAvailableBackends(
+  config?: TalonConfig,
+): { id: string; label: string }[] {
+  const all = listBackends().map((b) => ({ id: b.id, label: b.label }));
+  const enabled = config?.enabledBackends;
+  if (!enabled || enabled.length === 0) return all;
+  const byId = new Map(all.map((b) => [b.id, b]));
+  return enabled
+    .map((id) => byId.get(id))
+    .filter((b): b is { id: string; label: string } => Boolean(b));
+}
+
+/** Whether a backend id is registered and currently exposed by config. */
+export function isBackendAvailable(id: string, config?: TalonConfig): boolean {
+  return listAvailableBackends(config).some((b) => b.id === id);
+}
+
+/**
+ * Available backends using the config captured at init — convenience for
+ * runtime readers (e.g. the `list_backends` tool) that don't have config
+ * plumbed through. Falls back to all registered backends pre-init.
+ */
+export function getAvailableBackends(): { id: string; label: string }[] {
+  return listAvailableBackends(ctx.poolConfig ?? undefined);
+}
+
+/**
+ * The live pooled `Backend` instance for an id, or `null` if it isn't currently
+ * pooled. Unlike `getBackendForRole`/`getBackendForChat` this never initialises
+ * on demand — it only returns backends already spun up (role backends + chat
+ * overrides).
+ */
+export function getPooledBackend(id: string): Backend | null {
+  return pool.get(id)?.backend ?? null;
+}
+
+/** Monotonic counter for synthetic transient holders. */
+let transientHolderSeq = 0;
+
+/**
+ * Acquire a backend instance transiently — boots it on demand if it isn't
+ * already pooled, pinned by a synthetic `read:N` holder so a concurrent rebind
+ * can't tear it down mid-use. The caller MUST call the returned `release()`,
+ * which drops the holder and cleans the instance up iff nothing else holds it
+ * (so an already-active backend is left running).
+ *
+ * Used by read-only callers that need a non-current backend's catalog (e.g.
+ * `list_models backend=<other>`) without permanently switching the chat to it.
+ */
+export async function acquireBackendInstance(
+  id: string,
+): Promise<{ backend: Backend; release: () => Promise<void> }> {
+  if (!ctx.poolConfig) {
+    throw new Error(
+      "Backend pool not initialised — call initBackendPool first",
+    );
+  }
+  const entry = await ensurePoolEntry(id, ctx.poolConfig);
+  const holder = `read:${++transientHolderSeq}` as BackendHolder;
+  entry.holders.add(holder);
+  let released = false;
+  return {
+    backend: entry.backend,
+    release: async () => {
+      if (released) return;
+      released = true;
+      const e = pool.get(id);
+      if (e) await releaseHolderFromEntry(e, holder);
+    },
+  };
+}
+
+/**
+ * Validate a persisted model id against the backend that will serve
+ * it. Resolves through the catalog's `resolveModelInfo` — exact
+ * matches with `selectable !== false` are kept; everything else
+ * falls back. Backends without a catalog return `true` (we can't
+ * prove the value is stale, so we trust the chat-settings store).
+ */
+export async function isModelValidForBackend(
+  backend: Backend,
+  model: string,
+): Promise<boolean> {
+  const catalog = backend.models;
+  if (!catalog) return true;
+  const resolution = await catalog.resolveModelInfo(model);
+  return resolution.kind === "exact" && resolution.model.selectable !== false;
+}
+
+/** Snapshot of the live pool + bindings for `/model` rendering. */
+export function getPoolSnapshot(): PoolSnapshot {
+  const instances = [...pool.values()]
+    .sort((a, b) => a.id.localeCompare(b.id))
+    .map((entry) => {
+      const holdersList = [...entry.holders].sort();
+      const roles = holdersList
+        .filter((h) => h.startsWith("role:"))
+        .map((h) => h.slice(5) as BackendRole)
+        .sort();
+      const chats = holdersList
+        .filter((h) => h.startsWith("chat:"))
+        .map((h) => h.slice(5))
+        .sort();
+      return {
+        id: entry.id,
+        label: entry.label,
+        holders: holdersList,
+        roles,
+        chats,
+      };
+    });
+  const bindingsObj: Partial<Record<BackendRole, string>> = {};
+  for (const role of ALL_ROLES) {
+    const id = bindings.get(roleHolder(role));
+    if (id) bindingsObj[role] = id;
+  }
+  return {
+    instances,
+    bindings: bindingsObj as Record<BackendRole, string>,
+  };
+}
+
+/**
+ * Register a backend-change listener.
+ *
+ * Listener receives the holder that changed (`role:chat`, `chat:1234`,
+ * etc.), the new backend, and id/label. Fires AFTER the rebind is
+ * committed and the new entry is in the pool, but BEFORE the previous
+ * entry's cleanup runs (when applicable).
+ */
+export function onBackendChange(listener: BackendChangeListener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** Tear down the entire pool. Idempotent. */
+export async function cleanupBackendPool(): Promise<void> {
+  const entries = [...pool.values()];
+  pool.clear();
+  bindings.clear();
+  for (const entry of entries) {
+    if (entry.cleanup) {
+      try {
+        await entry.cleanup();
+      } catch (err) {
+        logWarn(
+          "backend-controller",
+          `Pool shutdown cleanup of ${entry.label} failed: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+      }
+    }
+  }
+  ctx.initCtx = null;
+}
+
+/** Test-only state reset. */
+export function resetBackendPoolForTest(): void {
+  pool.clear();
+  bindings.clear();
+  ctx.initCtx = null;
+  ctx.poolConfig = null;
+}
+
+/** Test-only: drop all listeners. */
+export function clearBackendChangeListenersForTest(): void {
+  listeners.clear();
+}

package/src/core/engine/backend-controller/rebind.ts

@@ -0,0 +1,205 @@
+/**
+ * Rebind / release holders, plus the per-chat accessors that resolve a chat
+ * to its override (or the chat-role default).
+ */
+
+import type { Backend } from "../../agent-runtime/capabilities.js";
+import type { TalonConfig } from "../../../util/config.js";
+import {
+  getBackend,
+  listBackends,
+} from "../../agent-runtime/backend-registry.js";
+import { log, logWarn } from "../../../util/log.js";
+import { chatHolder, roleHolder } from "./holders.js";
+import {
+  pool,
+  bindings,
+  ctx,
+  ensurePoolEntry,
+  releaseHolderFromEntry,
+  notifyListeners,
+  hasBackendPool,
+  type PoolEntry,
+} from "./state.js";
+import { getBackendForRole, getBackendIdForRole } from "./pool.js";
+import type { BackendHolder, BackendRole, RebindResult } from "./types.js";
+
+/**
+ * Rebind any holder to a different backend id.
+ *
+ * Pool semantics:
+ *   - If the target id is already pooled (another holder uses it),
+ *     the existing instance is reused — no double init.
+ *   - The previous binding's instance loses a refcount; cleanup fires
+ *     only if no other holder still references it.
+ *   - Failed init leaves the previous binding in place.
+ *
+ * Use `rebindRole` / `rebindChat` for typed wrappers.
+ */
+export async function rebindHolder(
+  holder: BackendHolder,
+  newId: string,
+  config: TalonConfig,
+): Promise<RebindResult> {
+  if (!ctx.initCtx) {
+    return { ok: false, error: "Backend pool not initialised" };
+  }
+  const currentId = bindings.get(holder);
+  if (currentId === newId) {
+    return {
+      ok: false,
+      error: `Holder "${holder}" already bound to "${newId}"`,
+    };
+  }
+
+  const factory = getBackend(newId);
+  if (!factory) {
+    const known = listBackends()
+      .map((b) => `"${b.id}"`)
+      .join(", ");
+    return {
+      ok: false,
+      error: `Unknown backend "${newId}" — known: ${known}`,
+    };
+  }
+
+  const newReused = pool.has(newId);
+  let newEntry: PoolEntry;
+  try {
+    newEntry = await ensurePoolEntry(newId, config);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logWarn(
+      "backend-controller",
+      `rebindHolder(${holder}, ${newId}) init failed: ${msg} — binding unchanged`,
+    );
+    return { ok: false, error: `Failed to init ${factory.label}: ${msg}` };
+  }
+  newEntry.holders.add(holder);
+  bindings.set(holder, newId);
+
+  let previousReused = false;
+  if (currentId) {
+    const oldEntry = pool.get(currentId);
+    if (oldEntry) {
+      previousReused = oldEntry.holders.size > 1;
+      await releaseHolderFromEntry(oldEntry, holder);
+    }
+  }
+
+  log(
+    "backend-controller",
+    `Rebound ${holder}: ${currentId ?? "(unbound)"} → ${newId}` +
+      (newReused ? " (reused pool instance)" : ""),
+  );
+  notifyListeners(holder, newEntry.backend, {
+    id: newId,
+    label: newEntry.label,
+  });
+
+  return {
+    ok: true,
+    from: currentId,
+    to: newId,
+    previousReused,
+    newReused,
+  };
+}
+
+/**
+ * Release a holder. If the entry it was holding has no other holders,
+ * the entry is cleaned up.
+ *
+ * No-op when the holder isn't bound — useful for "clear my override"
+ * flows that don't want to care whether the override was ever set.
+ */
+export async function releaseHolder(holder: BackendHolder): Promise<void> {
+  const id = bindings.get(holder);
+  if (!id) return;
+  bindings.delete(holder);
+  const entry = pool.get(id);
+  if (entry) await releaseHolderFromEntry(entry, holder);
+}
+
+/** Rebind a role. Convenience wrapper over `rebindHolder`. */
+export function rebindRole(
+  role: BackendRole,
+  newId: string,
+  config: TalonConfig,
+): Promise<RebindResult> {
+  return rebindHolder(roleHolder(role), newId, config);
+}
+
+/**
+ * Rebind a per-chat override.
+ *
+ * Pool refcounts the new backend in addition to whatever the role
+ * holders already pin. Releasing the chat (`releaseChat`) reverts the
+ * chat to whichever backend the chat-role is bound to.
+ */
+export function rebindChat(
+  chatId: string,
+  newId: string,
+  config: TalonConfig,
+): Promise<RebindResult> {
+  return rebindHolder(chatHolder(chatId), newId, config);
+}
+
+/** Release a per-chat override — the chat reverts to the global default. */
+export function releaseChat(chatId: string): Promise<void> {
+  return releaseHolder(chatHolder(chatId));
+}
+
+/**
+ * Resolve the backend a chat should use right now.
+ *
+ * If the chat has an override pooled, return that backend; otherwise
+ * fall back to the global chat-role backend.
+ */
+export function getBackendForChat(chatId: string): Backend {
+  const overrideId = bindings.get(chatHolder(chatId));
+  if (overrideId) {
+    const entry = pool.get(overrideId);
+    if (entry) return entry.backend;
+  }
+  return getBackendForRole("chat");
+}
+
+/** Backend id the chat would resolve to (override → role default). */
+export function getBackendIdForChat(chatId: string): string {
+  return bindings.get(chatHolder(chatId)) ?? getBackendIdForRole("chat");
+}
+
+/** Whether this chat has an override pinning a non-default backend. */
+export function hasChatBackendOverride(chatId: string): boolean {
+  return bindings.has(chatHolder(chatId));
+}
+
+/**
+ * Safe variant of `getBackendForChat` that never throws — returns
+ * the per-chat / role:chat backend when the pool is initialised, or
+ * `fallback` (typically `gateway?.backend`) when it isn't.
+ *
+ * The pool is always initialised in production at bootstrap; this
+ * helper exists so unit tests and legacy code paths that wire the
+ * frontend before the pool can degrade gracefully instead of
+ * throwing on every `/model` command. Frontends should call this
+ * everywhere they previously read `gateway?.backend` for /model,
+ * /status, and warmSession — otherwise per-chat backend overrides
+ * silently lose effect.
+ */
+export function resolveChatBackend(
+  chatId: string,
+  fallback?: Backend | null,
+): Backend | null {
+  if (hasBackendPool()) {
+    try {
+      return getBackendForChat(chatId);
+    } catch {
+      // Pool initialised but the chat-role binding is somehow missing —
+      // shouldn't happen in practice, but degrade to fallback rather
+      // than crash a /model render.
+    }
+  }
+  return fallback ?? null;
+}

package/src/core/engine/backend-controller/state.ts

@@ -0,0 +1,150 @@
+/**
+ * Backend-pool shared state + internal helpers.
+ *
+ * All pool modules import the SAME Map/Set instances and the SAME `ctx`
+ * holder from here, so refcounting and rebinds stay coherent across files.
+ * `initCtx`/`poolConfig` are reassignable, so they live on the mutable `ctx`
+ * object rather than as module-level `let`s (which can't be reassigned from
+ * another module).
+ */
+
+import type { Backend } from "../../agent-runtime/capabilities.js";
+import type { TalonConfig } from "../../../util/config.js";
+import {
+  getBackend,
+  listBackends,
+  type BackendInitContext,
+} from "../../agent-runtime/backend-registry.js";
+import { log, logWarn } from "../../../util/log.js";
+import { roleHolder } from "./holders.js";
+import type { BackendChangeListener, BackendHolder } from "./types.js";
+
+export interface PoolEntry {
+  id: string;
+  label: string;
+  backend: Backend;
+  cleanup?: () => Promise<void> | void;
+  holders: Set<BackendHolder>;
+}
+
+/** id → entry. */
+export const pool = new Map<string, PoolEntry>();
+/** holder → backend id (only present for holders currently bound). */
+export const bindings = new Map<BackendHolder, string>();
+
+export const listeners = new Set<BackendChangeListener>();
+
+/**
+ * Reassignable init context, captured at first init so subsequent calls don't
+ * need ctx/config plumbed through. On a holder object so other modules can
+ * reassign it.
+ */
+export const ctx: {
+  initCtx: BackendInitContext | null;
+  poolConfig: TalonConfig | null;
+} = {
+  initCtx: null,
+  poolConfig: null,
+};
+
+// ── Internal helpers ────────────────────────────────────────────────────────
+
+/** Look up or initialise a pool entry for a backend id. */
+export async function ensurePoolEntry(
+  id: string,
+  config: TalonConfig,
+): Promise<PoolEntry> {
+  const existing = pool.get(id);
+  if (existing) return existing;
+
+  const factory = getBackend(id);
+  if (!factory) {
+    const known = listBackends()
+      .map((b) => `"${b.id}"`)
+      .join(", ");
+    throw new Error(`Unknown backend "${id}" — known: ${known}`);
+  }
+  if (!ctx.initCtx) {
+    throw new Error(
+      "Backend pool not initialised — call initBackendPool first",
+    );
+  }
+  const instance = await factory.init(config, ctx.initCtx);
+  const entry: PoolEntry = {
+    id: factory.id,
+    label: factory.label,
+    backend: instance.backend,
+    cleanup: instance.cleanup,
+    holders: new Set(),
+  };
+  pool.set(factory.id, entry);
+  log("backend-controller", `Pool init: ${factory.label} (${factory.id})`);
+  return entry;
+}
+
+/** Drop a holder from an entry; clean up the entry if its refcount hits zero. */
+export async function releaseHolderFromEntry(
+  entry: PoolEntry,
+  holder: BackendHolder,
+): Promise<void> {
+  entry.holders.delete(holder);
+  if (entry.holders.size > 0) {
+    log(
+      "backend-controller",
+      `Released ${holder} from ${entry.label} (still held by: ${[...entry.holders].join(", ")})`,
+    );
+    return;
+  }
+  pool.delete(entry.id);
+  if (entry.cleanup) {
+    try {
+      await entry.cleanup();
+      log("backend-controller", `Pool cleanup: ${entry.label} (${entry.id})`);
+    } catch (err) {
+      logWarn(
+        "backend-controller",
+        `Cleanup of ${entry.label} failed: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
+  } else {
+    log("backend-controller", `Pool cleanup: ${entry.label} (no cleanup hook)`);
+  }
+}
+
+export function notifyListeners(
+  holder: BackendHolder,
+  backend: Backend,
+  ctxInfo: { id: string; label: string },
+): void {
+  for (const listener of listeners) {
+    try {
+      listener(holder, backend, ctxInfo);
+    } catch (err) {
+      logWarn(
+        "backend-controller",
+        `Backend-change listener threw: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+}
+
+export function resolveRoleBackendId(
+  role: "chat" | "heartbeat" | "dream",
+  config: TalonConfig,
+): string {
+  switch (role) {
+    case "chat":
+      return config.backend;
+    case "heartbeat":
+      return config.heartbeatBackend ?? config.backend;
+    case "dream":
+      return config.dreamBackend ?? config.backend;
+  }
+}
+
+/** Has the pool been initialised? */
+export function hasBackendPool(): boolean {
+  return bindings.has(roleHolder("chat"));
+}

package/src/core/engine/backend-controller/types.ts

@@ -0,0 +1,51 @@
+/**
+ * Public types for the backend controller / pool.
+ */
+
+import type { Backend } from "../../agent-runtime/capabilities.js";
+
+/** Roles that map to global holders. */
+export type BackendRole = "chat" | "heartbeat" | "dream";
+
+export const ALL_ROLES: readonly BackendRole[] = ["chat", "heartbeat", "dream"];
+
+/** Holder identifier — opaque string. Use `roleHolder()` / `chatHolder()`. */
+export type BackendHolder = string;
+
+export interface RebindResult {
+  ok: boolean;
+  /** Backend id the holder was bound to before the rebind (omitted when none). */
+  from?: string;
+  /** Backend id the holder is now bound to. */
+  to?: string;
+  /** Whether the previous instance stays alive (still bound elsewhere). */
+  previousReused?: boolean;
+  /** Whether the new binding reuses an existing pool instance. */
+  newReused?: boolean;
+  /** Human-readable error on failure. */
+  error?: string;
+}
+
+/** Snapshot of the pool for observability / `/model` rendering. */
+export interface PoolSnapshot {
+  /** Active pool entries, sorted by id, with the holders pinning them. */
+  instances: Array<{
+    id: string;
+    label: string;
+    /** Free-form holder strings — useful for diagnostics. */
+    holders: BackendHolder[];
+    /** Role-only subset, kept sorted, for the common case. */
+    roles: BackendRole[];
+    /** Per-chat overrides (chat ids only). */
+    chats: string[];
+  }>;
+  /** Current role bindings (always all three roles once initialised). */
+  bindings: Record<BackendRole, string>;
+}
+
+/** Notified after a successful rebind. */
+export type BackendChangeListener = (
+  holder: BackendHolder,
+  backend: Backend,
+  ctx: { id: string; label: string },
+) => void;