talon-agent 1.12.0 → 1.34.0

package/src/backend/claude-sdk/index.ts

@@ -7,8 +7,12 @@
 
 export { initAgent, updateSystemPrompt } from "./state.js";
 export { warmSession } from "./warm.js";
-export { handleMessage, getActiveQuery } from "./handler.js";
-export { buildMcpServers, getActiveFrontends } from "./options.js";
+export { getActiveQuery } from "./handler.js";
+export {
+  buildMcpServers,
+  buildPluginMcpServers,
+  getActiveFrontends,
+} from "./options.js";
 export { getBridgePort } from "./state.js";
 export {
   runOneShotAgent,

package/src/backend/claude-sdk/mcp-ready.ts

@@ -0,0 +1,54 @@
+/**
+ * Helper to bridge the gap between MCP server *registration* and *connection*.
+ *
+ * `Query.setMcpServers` resolves as soon as servers are registered — MCP
+ * startup is non-blocking by design. A stdio server that dials a slow remote
+ * endpoint (e.g. the playwright plugin connecting to the Camoufox websocket)
+ * finishes its `initialize` handshake seconds later. During that window the
+ * server is reported as `pending` and its tools are absent from the live
+ * registry, so a turn that proceeds immediately after `refreshTools` sees
+ * `mcp__playwright-tools__*` stuck "connecting" until the next refresh.
+ *
+ * `waitForMcpServersReady` polls `mcpServerStatus()` until the named servers
+ * leave the transient `pending` state (or a bounded timeout elapses), so the
+ * caller can return only once the freshly-added tools are actually usable.
+ */
+
+import type { Query } from "@anthropic-ai/claude-agent-sdk";
+
+/**
+ * Resolve once every server in `names` has left the `pending` state, or after
+ * `timeoutMs`. Best-effort and non-throwing: any error from `mcpServerStatus()`
+ * ends the wait so the turn is never blocked. Servers that settle into a
+ * terminal state (`connected`/`failed`/`needs-auth`/`disabled`) also resolve
+ * the wait — only the transient `pending` window is blocked on.
+ */
+export async function waitForMcpServersReady(
+  qi: Pick<Query, "mcpServerStatus">,
+  names: string[],
+  timeoutMs = 60_000,
+  pollMs = 250,
+): Promise<void> {
+  if (names.length === 0) return;
+  const pending = new Set(names);
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    let statuses;
+    try {
+      statuses = await qi.mcpServerStatus();
+    } catch {
+      return; // status query unsupported/failed — don't block the turn
+    }
+    // Best-effort: a backend (or stub) may report status in an unexpected
+    // shape (undefined / non-array). Treat anything non-iterable as
+    // "unsupported" and return rather than throwing into the turn.
+    if (!Array.isArray(statuses)) return;
+    for (const s of statuses) {
+      if (pending.has(s.name) && s.status !== "pending") {
+        pending.delete(s.name);
+      }
+    }
+    if (pending.size === 0) return;
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+}

package/src/backend/claude-sdk/model-drift.ts

@@ -0,0 +1,65 @@
+/**
+ * Turn-time model-drift detection.
+ *
+ * The SDK result's `modelUsage` is keyed by the model that ACTUALLY
+ * served the turn. Nothing compared it to the model we asked for — so
+ * when the API substitutes (requested model withdrawn from the
+ * catalog, rate-limit downshift, silent server-side fallback), the
+ * only evidence was an INFO accounting line nobody reads. This module
+ * turns that into a WARN with the fix in it, once per
+ * (requested → actual) pair per process.
+ */
+
+import { logWarn } from "../../util/log.js";
+
+/**
+ * Alias-tolerant model identity: "opus" is the same model as
+ * "claude-opus-4-8", "sonnet[1m]" the same as "sonnet". Substring
+ * containment after normalisation is deliberately loose — a false
+ * "same" (missed warning) is better than crying wolf on every alias
+ * expansion.
+ */
+export function isSameModel(requested: string, actual: string): boolean {
+  const norm = (s: string) =>
+    s
+      .toLowerCase()
+      .replace(/\[1m\]/g, "")
+      .trim();
+  const r = norm(requested);
+  const a = norm(actual);
+  if (!r || !a) return true; // nothing to compare — don't warn
+  return a === r || a.includes(r) || r.includes(a);
+}
+
+/** (requested→actual) pairs already warned about this process. */
+const warned = new Set<string>();
+
+/** Test seam. */
+export function resetModelDriftWarnings(): void {
+  warned.clear();
+}
+
+/**
+ * Compare the requested model against the models that actually served
+ * the turn (the `modelUsage` keys). Warns once per distinct pair.
+ * "default" requests are skipped — no pin, nothing to drift from.
+ */
+export function checkModelDrift(
+  requested: string,
+  actualModels: readonly string[],
+): void {
+  if (!requested || requested === "default") return;
+  if (actualModels.length === 0) return;
+  if (actualModels.some((actual) => isSameModel(requested, actual))) return;
+
+  const actual = actualModels.join(", ");
+  const key = `${requested}→${actual}`;
+  if (warned.has(key)) return;
+  warned.add(key);
+  logWarn(
+    "agent",
+    `[MODEL DRIFT] requested "${requested}" but the API served "${actual}" — ` +
+      `the pinned model may no longer exist or was substituted upstream. ` +
+      `Check "model" in config.json (or this chat's /model override).`,
+  );
+}

package/src/backend/claude-sdk/model-provider.ts

@@ -1,7 +1,7 @@
 /**
  * Model provider methods for the Claude SDK backend.
  *
- * Implements the optional model methods from QueryBackend by delegating
+ * Implements the optional model methods from Backend by delegating
  * to the core model registry. The Claude SDK exposes a single provider
  * ("anthropic") with models discovered from the SDK at startup.
  */
@@ -11,8 +11,8 @@ import {
   getModels,
   resolveModel as coreResolveModel,
   resolveModelId,
-} from "../../core/models.js";
-import type { ModelInfo } from "../../core/models.js";
+} from "../../core/models/catalog.js";
+import type { ModelInfo } from "../../core/models/catalog.js";
 import type {
   UnifiedModelInfo,
   UnifiedModelResolution,
@@ -34,10 +34,16 @@ function toUnified(model: ModelInfo): UnifiedModelInfo {
     provider: PROVIDER_ID,
     providerName: PROVIDER_NAME,
     selectable: true,
+    supportedReasoningLevels: model.supportedReasoningLevels,
+    defaultReasoningLevel: model.defaultReasoningLevel,
   };
 }
 
-/** De-duplicate models by displayName (1M variants share a label with their base). */
+/**
+ * De-duplicate models by displayName. Base and 1M variants carry distinct
+ * labels ("Sonnet 4.6" vs "Sonnet 4.6 (1M context)"), so both survive here;
+ * this only guards against accidental collisions.
+ */
 function getUniqueModels(): ModelInfo[] {
   const options: ModelInfo[] = [];
   const seenKeys = new Set<string>();
@@ -156,7 +162,7 @@ export async function getProviders(): Promise<UnifiedProviderInfo[]> {
 
 export async function getProviderModels(
   providerId: string,
-  page = 0,
+  page = 1,
   pageSize = 20,
 ): Promise<{ models: UnifiedModelInfo[]; total: number }> {
   if (providerId !== PROVIDER_ID) {
@@ -164,7 +170,7 @@ export async function getProviderModels(
   }
 
   const all = getModels(PROVIDER_ID).map(toUnified);
-  const start = page * pageSize;
+  const start = (page - 1) * pageSize;
   return {
     models: all.slice(start, start + pageSize),
     total: all.length,

package/src/backend/claude-sdk/models/convert.ts

@@ -0,0 +1,169 @@
+/**
+ * SDK → registry conversion. Groups SDK models into variant buckets, picks a
+ * canonical per bucket, derives display names + aliases + the fallback chain,
+ * and emits the registry `ModelInfo[]`.
+ */
+
+import type { ModelInfo } from "../../../core/models/catalog.js";
+import { normalizeReasoningLevels } from "../../../core/models/reasoning-levels.js";
+import {
+  buildSdkModelRecords,
+  buildGeneratedAliases,
+  deriveDisplayName,
+  getPreferredModelPriority,
+  mergeAliases,
+  type AliasFormOptions,
+  type SdkModelInfo,
+  type SdkModelRecord,
+} from "./parsing.js";
+
+function extractSdkReasoningLevels(model: SdkModelInfo) {
+  if (model.supportsEffort === false) return [];
+
+  const sdkLevels = normalizeReasoningLevels(model.supportedEffortLevels);
+  if (sdkLevels.length > 0) return sdkLevels;
+
+  const effort = model.capabilities?.effort;
+  if (!effort?.supported) return [];
+
+  return normalizeReasoningLevels(
+    (["low", "medium", "high", "max", "xhigh"] as const).filter(
+      (level) => effort[level]?.supported === true,
+    ),
+  );
+}
+
+/**
+ * Group records into variant buckets and pick the canonical record for each.
+ * Records without a parseable identity become their own singleton bucket so
+ * they still surface (keyed by value to stay unique).
+ */
+function groupVariants(
+  records: readonly SdkModelRecord[],
+): Map<string, SdkModelRecord[]> {
+  const groups = new Map<string, SdkModelRecord[]>();
+  for (const record of records) {
+    const key = record.variantKey ?? `raw:${record.value}`;
+    const bucket = groups.get(key) ?? [];
+    bucket.push(record);
+    groups.set(key, bucket);
+  }
+  return groups;
+}
+
+function pickCanonical(bucket: readonly SdkModelRecord[]): SdkModelRecord {
+  return [...bucket].sort((left, right) => {
+    const priorityDelta =
+      getPreferredModelPriority(left) - getPreferredModelPriority(right);
+    if (priorityDelta !== 0) return priorityDelta;
+    return left.index - right.index;
+  })[0]!;
+}
+
+/**
+ * Assign a best-effort fallback (used on overload/timeout) to every model
+ * except the last:
+ *  - A 1M variant prefers its base sibling of the same family+version.
+ *  - Otherwise a model falls back to the next model in SDK order.
+ */
+function assignFallbacks(
+  models: ModelInfo[],
+  recordByValue: ReadonlyMap<string, SdkModelRecord>,
+): void {
+  const baseByFamily = new Map<string, string>();
+  for (const model of models) {
+    const rec = recordByValue.get(model.id);
+    if (rec && !rec.identity.isOneMillion && rec.familyKey) {
+      baseByFamily.set(rec.familyKey, model.id);
+    }
+  }
+
+  models.forEach((model, index) => {
+    const rec = recordByValue.get(model.id);
+    if (rec?.identity.isOneMillion && rec.familyKey) {
+      const baseSibling = baseByFamily.get(rec.familyKey);
+      if (baseSibling && baseSibling !== model.id) {
+        model.fallback = baseSibling;
+        return;
+      }
+    }
+    if (index < models.length - 1) {
+      model.fallback = models[index + 1]!.id;
+    }
+  });
+}
+
+/**
+ * Convert SDK ModelInfo to our registry format.
+ *
+ * Base and 1M variants of the same family+version each surface as their own
+ * selectable entry (so the picker shows both), while true duplicates — the
+ * same model exposed under multiple ids — collapse into one canonical entry
+ * that absorbs the others' aliases. Display names, aliases, and the fallback
+ * chain are all derived from SDK metadata, never hardcoded versions.
+ */
+export function convertSdkModels(sdkModels: SdkModelInfo[]): ModelInfo[] {
+  const records = buildSdkModelRecords(sdkModels);
+  const groups = groupVariants(records);
+
+  // One canonical per variant bucket, ordered by SDK position so the registry
+  // preserves the SDK's ordering.
+  const canonicals = [...groups.values()]
+    .map(pickCanonical)
+    .sort((a, b) => a.index - b.index);
+
+  // Which family+version pairs have a base (non-1M) canonical? A 1M entry only
+  // claims the bare family aliases when there is no base sibling to own them.
+  const baseFamilyVersions = new Set<string>();
+  for (const canonical of canonicals) {
+    if (!canonical.identity.isOneMillion && canonical.familyKey) {
+      baseFamilyVersions.add(canonical.familyKey);
+    }
+  }
+
+  const usedKeys = new Set<string>();
+  const recordByValue = new Map<string, SdkModelRecord>();
+  const models: ModelInfo[] = [];
+
+  for (const canonical of canonicals) {
+    const groupKey = canonical.variantKey ?? `raw:${canonical.value}`;
+    const bucket = groups.get(groupKey)!;
+    const { identity } = canonical;
+
+    const hasBaseSibling = identity.isOneMillion
+      ? !!canonical.familyKey && baseFamilyVersions.has(canonical.familyKey)
+      : true;
+    const aliasForms: AliasFormOptions = {
+      includeBare: !identity.isOneMillion || !hasBaseSibling,
+      include1m: identity.isOneMillion,
+    };
+
+    // Aliases come from every record the canonical absorbs (its own value plus
+    // each duplicate's value and generated forms), so legacy ids keep resolving.
+    const canonicalKey = canonical.value.toLowerCase();
+    const aliases = mergeAliases(
+      ...bucket.map((record) => [
+        record.value,
+        ...buildGeneratedAliases(record.identity, aliasForms),
+      ]),
+    )
+      .filter((alias) => alias.toLowerCase() !== canonicalKey)
+      .filter((alias) => !usedKeys.has(alias.toLowerCase()));
+
+    usedKeys.add(canonicalKey);
+    for (const alias of aliases) usedKeys.add(alias.toLowerCase());
+
+    recordByValue.set(canonical.value, canonical);
+    models.push({
+      id: canonical.value,
+      displayName: deriveDisplayName(identity, canonical.displayName),
+      description: canonical.description,
+      aliases,
+      provider: "anthropic",
+      supportedReasoningLevels: extractSdkReasoningLevels(canonical),
+    });
+  }
+
+  assignFallbacks(models, recordByValue);
+  return models;
+}

package/src/backend/claude-sdk/models/discovery.ts

@@ -0,0 +1,203 @@
+/**
+ * Claude model discovery — spawns throwaway SDK subprocesses, calls
+ * `supportedModels()`, unions the results, and registers them in the global
+ * model registry. Also the static-registration path for tests / CLI setup.
+ */
+
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import {
+  registerModels,
+  clearModelsByProvider,
+  registerProviderPrefix,
+} from "../../../core/models/catalog.js";
+import type { ModelInfo } from "../../../core/models/catalog.js";
+import { log, logError } from "../../../util/log.js";
+import { describeSdkModel, type SdkModelInfo } from "./parsing.js";
+import { convertSdkModels } from "./convert.js";
+
+type ProbeOptions = {
+  cwd?: string;
+  permissionMode?: string;
+  allowDangerouslySkipPermissions?: boolean;
+  pathToClaudeCodeExecutable?: string;
+};
+
+const DISCOVERY_TIMEOUT_MS = 15_000;
+const MAX_DISCOVERY_SEEDS = 8;
+
+/**
+ * The `claude` binary returns "Custom model" for a `model` it doesn't
+ * recognise — it echoes the requested id straight back as a passthrough entry
+ * with no real metadata. We drop those (except the user's own configured
+ * model) so seed probing doesn't pollute the registry with junk families.
+ */
+const CUSTOM_MODEL_DESCRIPTION = "custom model";
+
+/**
+ * Spawn a throwaway SDK subprocess seeded with `seedModel` and return its
+ * `supportedModels()` list. The binary always echoes the requested model into
+ * the list, so the seed controls which models surface beyond the base set.
+ */
+async function probeSupportedModels(
+  seedModel: string,
+  probeOptions: ProbeOptions,
+): Promise<SdkModelInfo[]> {
+  const abort = new AbortController();
+  let drainPromise: Promise<void> | undefined;
+
+  try {
+    const neverYield = async function* (): AsyncGenerator<never> {
+      await new Promise<never>((_, reject) => {
+        abort.signal.addEventListener("abort", () =>
+          reject(new Error("aborted")),
+        );
+      });
+    };
+
+    const q = query({
+      prompt: neverYield(),
+      options: {
+        ...probeOptions,
+        model: seedModel,
+        abortController: abort,
+      } as Parameters<typeof query>[0]["options"],
+    });
+
+    drainPromise = (async () => {
+      try {
+        for await (const _ of q) {
+          /* discard */
+        }
+      } catch {
+        /* expected on abort */
+      }
+    })();
+
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<never>((_, reject) => {
+      timeoutId = setTimeout(
+        () =>
+          reject(
+            new Error(
+              `model discovery timed out after 15s (seed "${seedModel}")`,
+            ),
+          ),
+        DISCOVERY_TIMEOUT_MS,
+      );
+    });
+
+    try {
+      return await Promise.race([q.supportedModels(), timeout]);
+    } finally {
+      if (timeoutId !== undefined) clearTimeout(timeoutId);
+      abort.abort();
+      await drainPromise.catch(() => {});
+    }
+  } catch (err) {
+    abort.abort();
+    if (drainPromise) await drainPromise.catch(() => {});
+    throw err;
+  }
+}
+
+/**
+ * Merge probe results into one list, first-occurrence-wins by value, dropping
+ * unrecognised "Custom model" passthrough echoes (but always keeping the user's
+ * configured model even if the binary treats it as custom).
+ */
+function unionSdkModels(
+  lists: readonly SdkModelInfo[][],
+  configuredModel: string,
+): SdkModelInfo[] {
+  const byValue = new Map<string, SdkModelInfo>();
+  for (const list of lists) {
+    for (const model of list) {
+      if (byValue.has(model.value)) continue;
+      const isPassthroughJunk =
+        (model.description ?? "").trim().toLowerCase() ===
+          CUSTOM_MODEL_DESCRIPTION && model.value !== configuredModel;
+      if (isPassthroughJunk) continue;
+      byValue.set(model.value, model);
+    }
+  }
+  return [...byValue.values()];
+}
+
+/**
+ * Discover available models from the Claude Agent SDK and register them.
+ *
+ * Discovery is a union of probes. The binary only echoes the *requested* model
+ * (and a small base set) from `supportedModels()`, so a single probe misses
+ * the base-vs-1M counterpart of most families. We therefore probe the
+ * configured model first (mandatory), then best-effort re-probe each real
+ * family alias it revealed, and union the results. Throws only if the
+ * mandatory first probe fails — if the SDK can't provide models, Talon cannot
+ * function.
+ */
+export async function registerClaudeModels(sdkOptions: {
+  model: string;
+  cwd?: string;
+  permissionMode?: string;
+  allowDangerouslySkipPermissions?: boolean;
+  pathToClaudeCodeExecutable?: string;
+}): Promise<void> {
+  const { model: configuredModel, ...probeOptions } = sdkOptions;
+
+  try {
+    // Pass 1 (mandatory): the configured model is always echoed back.
+    const primary = await probeSupportedModels(configuredModel, probeOptions);
+    if (primary.length === 0) {
+      throw new Error("SDK returned empty model list");
+    }
+
+    // Pass 2 (best-effort): re-probe each real family alias from pass 1 to coax
+    // out the context variants the first probe didn't echo. Bare family aliases
+    // (e.g. "opus") return real metadata; unrecognised ones come back as
+    // "Custom model" and are filtered by unionSdkModels.
+    const seeds = new Set<string>();
+    for (const model of primary) {
+      const { family } = describeSdkModel(model);
+      if (family && family !== "default") seeds.add(family);
+    }
+    seeds.delete(configuredModel);
+
+    const seedList = [...seeds].slice(0, MAX_DISCOVERY_SEEDS);
+    const secondary = await Promise.allSettled(
+      seedList.map((seed) => probeSupportedModels(seed, probeOptions)),
+    );
+    const extraLists = secondary
+      .filter(
+        (result): result is PromiseFulfilledResult<SdkModelInfo[]> =>
+          result.status === "fulfilled",
+      )
+      .map((result) => result.value);
+
+    const union = unionSdkModels([primary, ...extraLists], configuredModel);
+    const models = convertSdkModels(union);
+    clearModelsByProvider("anthropic");
+    registerProviderPrefix("claude-");
+    registerModels(models);
+    log(
+      "agent",
+      `Discovered ${models.length} models from SDK ` +
+        `(${1 + extraLists.length}/${1 + seedList.length} probes): ` +
+        models.map((m) => m.id).join(", "),
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logError("agent", `Fatal: model discovery failed — ${msg}`);
+    throw new Error(
+      `Claude SDK model discovery failed: ${msg}. ` +
+        `Check that Claude Code is installed and your API key is valid.`,
+    );
+  }
+}
+
+/**
+ * Register models from a static list. For use in tests and the CLI setup
+ * wizard where the SDK subprocess is not available.
+ */
+export function registerClaudeModelsStatic(models: ModelInfo[]): void {
+  registerProviderPrefix("claude-");
+  registerModels(models);
+}

package/src/backend/claude-sdk/models/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Claude model discovery — queries the SDK for available models.
+ *
+ * Split by responsibility:
+ *   - `parsing`   — model-identity parsing, display names, alias generation
+ *   - `convert`   — SDK ModelInfo → registry ModelInfo[] (variants, fallbacks)
+ *   - `discovery` — SDK subprocess probing + registration (registerClaudeModels,
+ *                   registerClaudeModelsStatic)
+ *   - `static`    — CLAUDE_MODELS_STATIC fallback list
+ *
+ * Re-exports the same public surface the old single-file module exposed.
+ */
+
+export {
+  registerClaudeModels,
+  registerClaudeModelsStatic,
+} from "./discovery.js";
+export { CLAUDE_MODELS_STATIC } from "./static.js";