@qadanm/opencode-smart-router 0.4.0 → 0.6.1

package/src/core/routing/engine.ts

@@ -209,6 +209,35 @@ export const estimateTaskCost = (input: {
   }
 }
 
+/**
+ * Which capability axis each task kind reads, and the benchmark-neutral point
+ * on that axis. Kinds with no axis get no nudge. Neutral points sit at the
+ * middle of the observed benchmark band, so a score above the band's middle
+ * helps and one below it hurts - by at most CAPABILITY_MAX_NUDGE.
+ */
+const CAPABILITY_AXIS: Partial<Record<TaskClass["kind"], keyof NonNullable<ModelRecord["capabilities"]>>> = {
+  feature: "coding",
+  debug: "debugging",
+  refactor: "coding",
+  design: "architecture",
+  architecture: "architecture",
+  security: "architecture",
+  test: "coding",
+  docs: undefined,
+  deterministic: undefined,
+  mechanical: undefined,
+  unknown: undefined,
+}
+
+const CAPABILITY_NEUTRAL: Record<"coding" | "debugging" | "agentic" | "architecture", number> = {
+  coding: 60,
+  debugging: 68,
+  agentic: 55,
+  architecture: 80,
+}
+
+const CAPABILITY_MAX_NUDGE = 0.04
+
 const observedSuccess = (model: ModelRecord, session: EngineInput["session"], _key: string): number => {
   // Only capability failures should reduce a model's expected success rate.
   // Provider, network, auth, tool, and context-overflow errors are handled by
@@ -249,6 +278,21 @@ export const estimateSuccess = (input: {
     const threshold = task.sophisticatedDesign ? 75 : 60
     if (model.design < threshold) probability *= 0.72
   }
+  // Per-kind capability evidence. A model with no measured capability for the
+  // task's kind stays neutral: an unscored model is not a zero-capability
+  // model, and inventing a score would poison every ranking it entered. With
+  // evidence, the benchmark gap moves the probability by at most a few points
+  // either way - enough to break a close ranking in favor of the model that
+  // measurably does this kind of work better, never enough to overrule a
+  // context, quota, or floor gate.
+  if (model.capabilities && CAPABILITY_AXIS[task.kind]) {
+    const axis = CAPABILITY_AXIS[task.kind]!
+    const score = model.capabilities[axis]
+    if (typeof score === "number") {
+      const edge = score - CAPABILITY_NEUTRAL[axis]
+      probability += Math.max(-CAPABILITY_MAX_NUDGE, Math.min(CAPABILITY_MAX_NUDGE, edge / 500))
+    }
+  }
   const floor = input.intelligenceFloor ?? 39.5
   if (task.tier >= 2 && model.intelligence < floor) probability *= 0.7
   if (model.context > 0 && input.contextTokens > model.context * 0.8) probability *= 0.9
@@ -619,7 +663,16 @@ export const routeTask = (input: EngineInput): EngineResult => {
     // Only protect the escalation pool when an ordinary-allowance route can
     // actually serve the task. A task that needs escalation must still be
     // able to escalate.
-    const ordinaryAvailable = unprotected.some((entry) => !entry.model.escalationOnly && !entry.model.premium)
+    // A tier-3 task served by a standard model runs at ~0.7 expected
+    // success by construction (estimateSuccess). That is below the bar a
+    // tier-3 model meets, so for tier-3 work no ordinary route "serves" the
+    // task and the pool stays available for it. Tier 1/2 work meets the bar
+    // at 0.93+, so the pool stays protected for ordinary tasks and can never
+    // be drained by routine work.
+    if (input.task.tier >= 3) return unprotected
+    const ordinaryAvailable = unprotected.some(
+      (entry) => !entry.model.escalationOnly && !entry.model.premium && entry.probability >= 0.85,
+    )
     if (!ordinaryAvailable) return unprotected
     return run(true)
   }
@@ -873,8 +926,14 @@ export const routeTask = (input: EngineInput): EngineResult => {
     )
   reasons.push(...quotaNotes)
 
+  // The trace keeps the twelve cheapest eligible routes plus, always, the
+  // chosen model: on an escalation the flagship is the most expensive row, so
+  // a bare cost-ordered slice would truncate exactly the entry an escalation
+  // exists to show.
+  const chosenEntry = chosen
   const candidates = evaluated
-    .slice(0, 12)
+    .sort((a, b) => a.candidate.effectiveCost - b.candidate.effectiveCost)
+    .filter((entry, index) => index < 12 || entry === chosenEntry)
     .map((entry) => ({
       ...entry.candidate,
       retained: keptForAffinity ? entry.model === currentEval?.model : entry.model === chosen.model,

package/src/core/types.ts

@@ -99,6 +99,21 @@ export interface ModelRecord {
   readonly intelligence: number
   /** Curated front-end and UX quality score. */
   readonly design: number
+  /**
+   * Per-kind capability evidence, when measured benchmarks exist. Absent
+   * axes are unknown, never zero: an unscored model stays neutral in
+   * ranking rather than being treated as incapable.
+   */
+  readonly capabilities?: {
+    /** Agentic coding benchmark, percent. */
+    readonly coding?: number
+    /** Complex-debugging / automation benchmark, percent. */
+    readonly debugging?: number
+    /** Long-horizon autonomous-execution benchmark, percent. */
+    readonly agentic?: number
+    /** Curated architectural-reasoning score, same 0-100 scale. */
+    readonly architecture?: number
+  }
   readonly designEvidence: "benchmark" | "curated" | "observed" | "unverified"
   /**
    * Credit multiplier applied to this model's usage value. One for every
@@ -283,10 +298,16 @@ export interface ProviderQuotaSnapshot {
 }
 
 export interface PremiumState {
-  readonly mode: "off" | "ask" | "allowed"
+  readonly mode: "off" | "ask" | "allowed" | "auto"
   readonly monthlyBudgetUsd: number
   readonly spentUsd: number
   readonly remainingUsd: number
+  /**
+   * Remaining plan-model pool allowance for the month. In auto mode this, not
+   * `remainingUsd`, is what escalation draws against; undefined when the
+   * caller has no pool identity for the model in play.
+   */
+  readonly planPoolRemainingUsd?: number
   readonly oneShotGranted: boolean
   readonly oneShotGrantedAt?: number
 }
@@ -402,6 +423,8 @@ export interface Metrics {
   dryRunDecisions: number
   premiumRequests: number
   premiumUsd: number
+  /** Lifetime spend against the plan-model pool (escalation allowance). */
+  planPoolUsd: number
   latencyMsTotal: number
   latencySamples: number
   lastLatencyMs?: number
@@ -454,6 +477,13 @@ export interface Ledger {
   /** Hourly aggregates for anything older than the raw-event horizon. */
   usageRollup?: UsageRollup
   premiumSpend: Array<{ month: string; usd: number }>
+  /**
+   * Monthly spend against the plan-model pool (the escalation allowance),
+   * separate from `premiumSpend` so the pool gate reads exactly what the
+   * pool funded. The hydrator always materializes this array, so ledgers
+   * written before the field existed read as zero spend.
+   */
+  planPoolSpend: Array<{ month: string; usd: number }>
   sessions: Record<string, SessionState>
   decisions: RoutingDecision[]
   metrics: Metrics
@@ -597,7 +627,7 @@ export interface PrivacySettings {
 }
 
 export interface PremiumSettings {
-  readonly mode: "off" | "ask" | "allowed"
+  readonly mode: "off" | "ask" | "allowed" | "auto"
   readonly monthlyBudgetUsd: number
   readonly oneShotApproval: boolean
 }
@@ -611,7 +641,20 @@ export interface RoutingSettings {
   readonly largeContextHysteresisPct: number
   readonly maxEscalationsPerTask: number
   readonly preferSameProvider: boolean
-  /** Reject a prompt when the current model is unqualified and no eligible route exists. */
+  /**
+   * Block a prompt when this plugin cannot produce a routing decision.
+   *
+   * Default false, and that default is the point: routing is an optimization,
+   * and a defect inside the router must degrade to "do not route", never to
+   * "do not work". An internal error leaves the current model in place and lets
+   * the prompt through.
+   *
+   * This does NOT govern quota safety. A provider that is configured to be
+   * probed but has no reading is always refused, because that is a spending
+   * decision about a provider the router cannot see, not a response to its own
+   * failure. Set this true only if you would rather be stopped than pay for an
+   * unrouted request.
+   */
   readonly failClosed: boolean
   /**
    * Refuse to route a task to a model funded from a pool reserved for
@@ -686,8 +729,6 @@ export interface SpeedSettings {
 }
 
 export interface UiSettings {
-  /** Prefix the session title with AUTO / MANUAL / PAUSED / DRY RUN and the current model. */
-  readonly titleIndicator: boolean
   /** Send a native macOS notification when the provider or model changes. */
   readonly notifications: boolean
   /** Use a shorter, denser indicator title and UI chrome (compact mode). */

package/src/gui/index.tsx

@@ -1443,6 +1443,8 @@ function SmartRouterPanel(props: { sessionID: string | undefined }) {
      * happens within a frame or two; everywhere else the answer is "no" and
      * nothing changes.
      */
+
+
     void (async () => {
       try {
         const state: any = await Promise.race([
@@ -1456,9 +1458,11 @@ function SmartRouterPanel(props: { sessionID: string | undefined }) {
       }
     })()
     const timer = setInterval(() => void load(), 3_000)
+    // The panel only reflects the window-scoped controller's state.
     onCleanup(() => clearInterval(timer))
   })
 
+
   const view = (): DecisionView | undefined => summariseDecision(status()?.lastDecision as never)
   const providers = (): ProviderRow[] =>
     ((status()?.quota ?? []) as never[]).map((snapshot) => toProviderRow(snapshot))
@@ -1651,6 +1655,7 @@ export default Plugin.define({
      */
     const autoOpenTimer = setInterval(tryAutoOpen, 800)
 
+
     ctx.add(Slot, {
       at: "window.bottom",
       render: () => (

package/src/index.ts

@@ -1,6 +1,5 @@
 import { Plugin } from "@opencode/plugin"
-import { RouterBlockedError, RouterController } from "./server/controller.js"
-import { stripTitlePrefix } from "./core/ui.js"
+import { RouterController } from "./server/controller.js"
 import { sharedCore } from "./server/shared-core.js"
 
 const describe = (error: unknown) => (error instanceof Error ? error.message : String(error))
@@ -12,36 +11,22 @@ export default Plugin.define({
     try {
       return await controller.initialize()
     } catch (error) {
-      // A broken location must not take down the host or the other bridges.
+      // A broken location must not take down the host or the other bridges, and
+      // it must not take the owner's ability to send a prompt with it.
+      //
+      // This branch used to install a "minimal fail-closed hook" that rejected
+      // every prompt until the next reload. That turned a failed setup into a
+      // disabled editor, which is the worst possible response to a plugin that
+      // is already not working. Verified in scripts/isolated-e2e.sh: a plugin
+      // hook that throws fails the request outright, so a hook here is not a
+      // safety net.
+      //
+      // The correct outcome is that this location has no router. OpenCode then
+      // behaves exactly as it would with the plugin uninstalled, which is the
+      // guarantee the plugin owes its host. The failure stays visible in
+      // diagnostics and in the status RPC of any bridge that did start.
       sharedCore.recordError(`setup ${ctx.location?.directory ?? ""}: ${describe(error)}`)
       await controller.dispose().catch(() => undefined)
-      // A broken location must not silently execute prompts with no routing.
-      // Keep a minimal fail-closed hook until the next reload.
-      try {
-        await ctx.session.hook("prompt", async (event: any) => {
-          const sessionID = event?.sessionID
-          if (!sessionID) throw new RouterBlockedError("Smart Router setup failed")
-          let info: any
-          try {
-            info = await ctx.session.get({ sessionID })
-          } catch {
-            info = undefined
-          }
-          const localID = ctx.location?.project?.id
-          if (info?.projectID && localID && info.projectID !== localID) return
-          if (info) {
-            try {
-              const base = stripTitlePrefix(typeof info.title === "string" ? info.title : "") || "Session"
-              await ctx.session.update({ sessionID, title: `BLOCKED · router setup failed — ${base}` })
-            } catch {
-              // The rejection below still stops admission.
-            }
-          }
-          throw new RouterBlockedError("Smart Router setup failed; routing is unavailable")
-        })
-      } catch (hookError) {
-        sharedCore.recordError(`setup fallback hook ${ctx.location?.directory ?? ""}: ${describe(hookError)}`)
-      }
       return () => undefined
     }
   },

package/src/server/containment.ts

@@ -0,0 +1,131 @@
+/**
+ * Containment for the host boundary.
+ *
+ * WHAT THIS IS FOR. OpenCode does not protect itself from a plugin: a hook that
+ * throws fails the request, and a hook that never settles leaves the editor
+ * waiting forever. Verified against a real OpenCode process on 2026-11-06, in
+ * `scripts/isolated-e2e.sh` -- see the `hook-throws` and `hook-hangs`
+ * scenarios.
+ *
+ * That makes "the host is robust" an assumption this plugin cannot rely on.
+ * The only place the guarantee can come from is here: whatever the router does
+ * internally, the function OpenCode calls must return, and must not throw.
+ *
+ * TWO RULES.
+ *
+ * 1. A hook never propagates an exception. The prompt is served unrouted, which
+ *    is exactly what would have happened if the plugin were not installed.
+ *
+ * 2. A hook never waits forever. Routing runs against a deadline; if the router
+ *    is still working when it expires, the prompt proceeds without it. The
+ *    router is an optimization, and an optimization that cannot finish is
+ *    worth nothing -- but only if it gets out of the way.
+ *
+ * This module has no dependencies and no state, so it cannot be part of the
+ * thing that fails.
+ */
+
+/** The narrow shape a contained hook needs from the plugin's own error type. */
+interface BlockedLike {
+  readonly name?: string
+}
+
+const isBlocked = (error: unknown): boolean =>
+  typeof error === "object" &&
+  error !== null &&
+  ((error as BlockedLike).name === "RouterBlockedError" || (error as any).routerBlocked === true)
+
+export interface ContainOptions {
+  /** What to call this hook in a diagnostic. Never user-facing. */
+  readonly label: string
+  /** Called with the reason a hook was contained. Must not throw. */
+  readonly onContained?: (message: string) => void
+  /**
+   * Whether an exception is a deliberate refusal that must reach the host.
+   * Deliberate refusals are the one thing that may still stop a prompt,
+   * because they are a decision rather than a defect.
+   */
+  readonly allowBlocked?: boolean
+}
+
+const describe = (error: unknown): string => (error instanceof Error ? error.message : String(error))
+
+/**
+ * Wrap a hook so it can never throw and never hang.
+ *
+ * The returned function always resolves. A `RouterBlockedError` is re-thrown
+ * when `allowBlocked` is set, because that is the router saying "I refuse",
+ * which is a supported outcome. Everything else is a defect, and a defect
+ * leaves the prompt alone.
+ */
+export const containHook = <TEvent>(
+  handler: (event: TEvent) => Promise<unknown> | unknown,
+  options: ContainOptions,
+): ((event: TEvent) => Promise<void>) => {
+  const report = (message: string) => {
+    try {
+      options.onContained?.(message)
+    } catch {
+      // A diagnostic sink that throws must not resurrect the failure.
+    }
+  }
+
+  return async (event: TEvent): Promise<void> => {
+    try {
+      await handler(event)
+    } catch (error) {
+      if (options.allowBlocked && isBlocked(error)) throw error
+      report(`${options.label}: ${describe(error)}`)
+    }
+  }
+}
+
+/**
+ * Run work against a deadline, resolving to `undefined` when it is exceeded.
+ *
+ * `Promise.race` would leave the slow work running and unobserved, which can
+ * produce an unhandled rejection later and, worse, keep doing work whose result
+ * nobody will read. This variant attaches handlers to the original promise so a
+ * late rejection is swallowed deliberately, and reports the timeout so the
+ * owner can see that routing was skipped.
+ *
+ * The timer is cleared on the normal path: a deadline that has already been met
+ * must not keep the process alive or fire against a later request.
+ */
+export const withDeadline = async <T>(input: {
+  readonly work: () => Promise<T> | T
+  readonly ms: number
+  readonly onTimeout: () => void
+}): Promise<T | undefined> => {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let settled = false
+
+  const deadline = new Promise<undefined>((resolve) => {
+    timer = setTimeout(() => {
+      settled = true
+      try {
+        input.onTimeout()
+      } catch {
+        // Reporting the timeout must not replace it with another failure.
+      }
+      resolve(undefined)
+    }, input.ms)
+    // Never hold the event loop open on a deadline alone.
+    ;(timer as any)?.unref?.()
+  })
+
+  const work = Promise.resolve()
+    .then(input.work)
+    .catch((error) => {
+      // The caller's handler is responsible for the failure; this only stops a
+      // rejection from escaping after the deadline has already won the race.
+      if (settled) return undefined
+      throw error
+    })
+
+  try {
+    return (await Promise.race([work, deadline])) as T | undefined
+  } finally {
+    if (timer) clearTimeout(timer)
+  }
+}