@qadanm/opencode-smart-router 0.0.0-stage → 0.4.0

package/dist/tui.js

@@ -0,0 +1,587 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/gui/viewmodel.ts
+var viewmodel_exports = {};
+__export(viewmodel_exports, {
+  formatPercent: () => formatPercent,
+  formatReset: () => formatReset,
+  formatUsd: () => formatUsd,
+  formatWindowUsed: () => formatWindowUsed,
+  keyOf: () => keyOf,
+  orderCandidateRows: () => orderCandidateRows,
+  providerGroups: () => providerGroups,
+  rankingAdjustments: () => rankingAdjustments,
+  statusLine: () => statusLine,
+  summariseDecision: () => summariseDecision,
+  toCandidateRow: () => toCandidateRow,
+  toProviderRow: () => toProviderRow
+});
+var sourceLabelOf, windowLabels, formatReset, toWindow, toProviderRow, formatUsd, formatPercent, formatWindowUsed, rankingAdjustments, keyOf, toCandidateRow, verdictRank, orderCandidateRows, summariseDecision, statusLine, contextLabel, providerGroups;
+var init_viewmodel = __esm({
+  "src/gui/viewmodel.ts"() {
+    "use strict";
+    sourceLabelOf = (source) => {
+      switch (source) {
+        case "provider":
+          return "verified by provider";
+        case "estimate":
+          return "estimated \u2014 lower bound";
+        default:
+          return "not reported";
+      }
+    };
+    windowLabels = {
+      fiveHour: "5h",
+      weekly: "7d",
+      monthly: "Monthly"
+    };
+    formatReset = (at, now = Date.now()) => {
+      if (at === void 0) return void 0;
+      const delta = at - now;
+      if (delta <= 0) return "resetting";
+      const minutes = Math.round(delta / 6e4);
+      if (minutes < 60) return `in ${minutes}m`;
+      const hours = Math.round(minutes / 60);
+      if (hours < 36) return `in ${hours}h`;
+      const days = Math.round(hours / 24);
+      return `in ${days}d`;
+    };
+    toWindow = (id, window, now) => {
+      const source = window?.source ?? "unknown";
+      const usedPct = window?.usedPct ?? 0;
+      const reported = source !== "unknown" && (window?.capUsd !== void 0 || usedPct > 0);
+      return {
+        id,
+        label: windowLabels[id],
+        usedPct,
+        remainingPct: window?.remainingPct ?? Math.max(0, 100 - usedPct),
+        ...window?.usedUsd !== void 0 ? { usedUsd: window.usedUsd } : {},
+        ...window?.capUsd !== void 0 ? { capUsd: window.capUsd } : {},
+        ...window?.resetsAt !== void 0 ? { resetsAt: window.resetsAt } : {},
+        ...formatReset(window?.resetsAt, now) ? { resetLabel: formatReset(window?.resetsAt, now) } : {},
+        source,
+        sourceLabel: sourceLabelOf(source),
+        exceeded: Boolean(window?.exceeded),
+        reported,
+        lowerBound: source === "estimate"
+      };
+    };
+    toProviderRow = (snapshot, now = Date.now()) => {
+      const source = snapshot.monthly?.source === "provider" ? "provider" : snapshot.monthly?.source === "estimate" ? "estimate" : "unknown";
+      const windows = [
+        toWindow("fiveHour", snapshot.rolling, now),
+        toWindow("weekly", snapshot.weekly, now),
+        toWindow("monthly", snapshot.monthly, now)
+      ];
+      const exhaustedWindow = windows.find((window) => window.exceeded);
+      const pools = (snapshot.pools ?? []).map((pool) => ({
+        id: pool.id,
+        label: pool.label,
+        source: pool.source,
+        sourceLabel: sourceLabelOf(pool.source),
+        monthlyUsd: pool.monthlyUsd,
+        usedUsd: pool.usedUsd,
+        remainingUsd: pool.remainingUsd,
+        usedPct: pool.usedPct,
+        ...pool.weeklyUsedPct !== void 0 ? { weeklyPct: pool.weeklyUsedPct } : {},
+        ...pool.fiveHourUsedPct !== void 0 ? { fiveHourPct: pool.fiveHourUsedPct } : {},
+        ...formatReset(pool.resetsAt, now) ? { resetLabel: formatReset(pool.resetsAt, now) } : {},
+        note: pool.note
+      }));
+      return {
+        providerID: snapshot.providerID,
+        label: snapshot.label ?? snapshot.providerID,
+        plan: snapshot.plan ?? "",
+        source,
+        sourceLabel: sourceLabelOf(source),
+        ...snapshot.quotaState ? { quotaState: snapshot.quotaState } : {},
+        stale: Boolean(snapshot.stale),
+        fetchedAt: snapshot.fetchedAt ?? now,
+        exhausted: Boolean(exhaustedWindow),
+        ...exhaustedWindow ? { exhaustedWindow: exhaustedWindow.label } : {},
+        windows,
+        pools,
+        ...snapshot.monthlyRemainingUsd !== void 0 ? { monthlyRemainingUsd: snapshot.monthlyRemainingUsd } : {},
+        ...snapshot.extraCredits ? { extraCreditsUsd: snapshot.extraCredits.totalUsd } : {},
+        ...snapshot.error ? { error: snapshot.error } : {},
+        notes: snapshot.notes ?? [],
+        ...source === "estimate" ? { caveat: (snapshot.notes ?? [])[0] } : {}
+      };
+    };
+    formatUsd = (value) => {
+      if (!Number.isFinite(value)) return "\u2014";
+      if (value === 0) return "$0";
+      if (value < 0.01) return `$${value.toFixed(4)}`;
+      if (value < 1) return `$${value.toFixed(3)}`;
+      return `$${value.toFixed(2)}`;
+    };
+    formatPercent = (value) => Number.isFinite(value) ? `${Math.round(value)}%` : "\u2014";
+    formatWindowUsed = (window) => {
+      if (!window.reported) return "\u2014";
+      const value = formatPercent(window.usedPct);
+      return window.lowerBound ? `\u2265${value}` : value;
+    };
+    rankingAdjustments = (candidate) => {
+      const notes = [];
+      const credit = candidate.creditMultiplier;
+      if (credit !== void 0 && credit !== 1) notes.push(`${credit}x plan credits`);
+      const speed = candidate.speedFactor;
+      if (speed !== void 0 && speed !== 1) notes.push(`${speed}x measured speed`);
+      const marginal = candidate.marginalPriceFactor;
+      if (marginal !== void 0 && marginal !== 1) notes.push(`${marginal}x expiring allowance`);
+      if (candidate.switchPenaltyUsd > 0) notes.push(`${formatUsd(candidate.switchPenaltyUsd)} switch cost`);
+      return notes;
+    };
+    keyOf = (model) => `${model.providerID}/${model.modelID}`;
+    toCandidateRow = (candidate, chosen) => {
+      const key = keyOf(candidate.model);
+      return {
+        key,
+        name: candidate.name,
+        tier: candidate.tier,
+        verdict: key === chosen && candidate.eligible ? "chosen" : candidate.eligible ? "eligible" : "blocked",
+        reason: candidate.reason,
+        estimatedUsd: candidate.estimatedUsd,
+        effectiveCost: candidate.effectiveCost,
+        successProbability: candidate.successProbability,
+        adjustments: rankingAdjustments(candidate)
+      };
+    };
+    verdictRank = { chosen: 0, eligible: 1, blocked: 2 };
+    orderCandidateRows = (rows) => [...rows].sort((left, right) => {
+      const byVerdict = verdictRank[left.verdict] - verdictRank[right.verdict];
+      if (byVerdict !== 0) return byVerdict;
+      if (left.verdict === "blocked") return left.key.localeCompare(right.key);
+      return left.effectiveCost - right.effectiveCost || left.key.localeCompare(right.key);
+    });
+    summariseDecision = (decision) => {
+      if (!decision) return void 0;
+      const chosenKey = decision.chosen ? `${decision.chosen.providerID}/${decision.chosen.id}` : void 0;
+      const rows = orderCandidateRows(decision.candidates.map((candidate) => toCandidateRow(candidate, chosenKey)));
+      return {
+        id: decision.id,
+        chosen: chosenKey,
+        switched: decision.switched,
+        switchReason: decision.switchReason,
+        taskKind: decision.task?.kind ?? "unknown",
+        taskTier: decision.task?.tier ?? 0,
+        contextTokens: decision.contextTokens,
+        estimatedUsd: decision.estimatedUsd,
+        reasons: decision.reasons ?? [],
+        warnings: decision.warnings ?? [],
+        selfheal: decision.selfheal?.rejected ? `rejected ${decision.selfheal.rejected} \xB7 ${decision.selfheal.action === "noted" ? "noted for the next prompt" : decision.selfheal.action}` : void 0,
+        eligibleCount: rows.filter((row) => row.verdict !== "blocked").length,
+        blockedCount: rows.filter((row) => row.verdict === "blocked").length,
+        rows
+      };
+    };
+    statusLine = (input) => {
+      const parts = [input.runtime ?? "unknown", input.mode ?? "unknown"];
+      parts.push(input.current ? `${input.current.providerID}/${input.current.id}` : "no model yet");
+      return parts.join(" \xB7 ");
+    };
+    contextLabel = (tokens) => {
+      if (!Number.isFinite(tokens) || tokens <= 0) return "unknown";
+      return tokens >= 1e6 ? `${Number((tokens / 1e6).toFixed(1))}M` : `${Math.round(tokens / 1e3)}k`;
+    };
+    providerGroups = (input) => {
+      const byProvider = /* @__PURE__ */ new Map();
+      for (const model of input.models) {
+        const state = model.excluded ? "excluded" : model.approved ? "approved" : "not approved";
+        const row = {
+          key: model.key,
+          providerID: model.providerID,
+          name: model.name,
+          tier: model.tier,
+          intelligence: model.intelligence,
+          design: model.design,
+          contextLabel: contextLabel(model.context),
+          costLabel: `${formatUsd(model.costInput)} / ${formatUsd(model.costOutput)} per 1M`,
+          vision: model.vision,
+          state
+        };
+        const list = byProvider.get(model.providerID) ?? [];
+        list.push(row);
+        byProvider.set(model.providerID, list);
+      }
+      const quotaLabel = new Map(input.quota.map((entry) => [entry.providerID, entry.label ?? entry.providerID]));
+      return [...byProvider.entries()].map(([providerID, models]) => {
+        const active = input.activeProviders.includes(providerID);
+        const approvedCount = models.filter((model) => model.state === "approved").length;
+        return {
+          providerID,
+          label: quotaLabel.get(providerID) ?? providerID,
+          state: active ? "active" : "not configured",
+          // Approved first, then by tier and cost: the order a routing decision
+          // would consider them.
+          models: [...models].sort((left, right) => {
+            const rank = (row) => row.state === "approved" ? 0 : row.state === "excluded" ? 2 : 1;
+            return rank(left) - rank(right) || left.tier - right.tier || left.key.localeCompare(right.key);
+          }),
+          approvedCount,
+          totalCount: models.length,
+          ...active ? {} : { note: "Not routing here: no credential found for this provider on this machine." }
+        };
+      }).sort((left, right) => {
+        if (left.state !== right.state) return left.state === "active" ? -1 : 1;
+        return left.label.localeCompare(right.label);
+      });
+    };
+  }
+});
+
+// src/tui/index.tsx
+import { Plugin } from "@opencode/plugin/tui";
+
+// src/rpc.ts
+import { Rpc } from "@opencode/plugin/rpc";
+var objectOutput = { type: "object", additionalProperties: true };
+var emptyInput = { type: "object", properties: {}, additionalProperties: false };
+var sessionInput = {
+  type: "object",
+  properties: { sessionID: { type: "string" } },
+  required: ["sessionID"],
+  additionalProperties: false
+};
+var method = (input) => ({ input, output: objectOutput });
+var SmartRouterRpc = Rpc.define({
+  id: "smart-router",
+  methods: {
+    status: method({
+      type: "object",
+      properties: { sessionID: { type: "string" } },
+      additionalProperties: false
+    }),
+    preview: method({
+      type: "object",
+      properties: {
+        sessionID: { type: "string" },
+        text: { type: "string" },
+        files: { type: "array", items: { type: "object", additionalProperties: true } }
+      },
+      required: ["sessionID", "text"],
+      additionalProperties: false
+    }),
+    setMode: method({
+      type: "object",
+      properties: { mode: { type: "string", enum: ["efficiency", "balanced", "premium"] } },
+      required: ["mode"],
+      additionalProperties: false
+    }),
+    setPaused: method({
+      type: "object",
+      properties: { paused: { type: "boolean" } },
+      required: ["paused"],
+      additionalProperties: false
+    }),
+    /**
+     * Turn automatic routing on or off for one session.
+     *
+     * Not the same as disabling the plugin or pausing every session: the router
+     * stays loaded, keeps reporting quota and decisions, and simply stops
+     * changing the model. The user keeps whatever model they have.
+     */
+    setSessionAuto: method({
+      type: "object",
+      properties: { sessionID: { type: "string" }, auto: { type: "boolean" } },
+      required: ["sessionID", "auto"],
+      additionalProperties: false
+    }),
+    setDryRun: method({
+      type: "object",
+      properties: { dryRun: { type: "boolean" } },
+      required: ["dryRun"],
+      additionalProperties: false
+    }),
+    resumeAuto: method(sessionInput),
+    pin: method({
+      type: "object",
+      properties: {
+        sessionID: { type: "string" },
+        providerID: { type: "string" },
+        modelID: { type: "string" },
+        variant: { type: "string" }
+      },
+      required: ["sessionID", "providerID", "modelID"],
+      additionalProperties: false
+    }),
+    approvePremium: method(sessionInput),
+    denyPremium: method(sessionInput),
+    excludeModel: method({
+      type: "object",
+      properties: {
+        providerID: { type: "string" },
+        modelID: { type: "string" },
+        excluded: { type: "boolean" }
+      },
+      required: ["providerID", "modelID", "excluded"],
+      additionalProperties: false
+    }),
+    setPremiumBudget: method({
+      type: "object",
+      properties: { usd: { type: "number", minimum: 0, maximum: 1e5 } },
+      required: ["usd"],
+      additionalProperties: false
+    }),
+    setReserve: method({
+      type: "object",
+      properties: {
+        providerID: { type: "string" },
+        monthlyPct: { type: "number", minimum: 0, maximum: 90 },
+        weeklyPct: { type: "number", minimum: 0, maximum: 90 },
+        fiveHourPct: { type: "number", minimum: 0, maximum: 90 }
+      },
+      required: ["providerID"],
+      additionalProperties: false
+    }),
+    /**
+     * The intelligence floor in force, and why.
+     *
+     * Calibration can only be trusted if its result is visible: a number with
+     * no explanation is indistinguishable from the hand-picked one it replaced.
+     * This previews without enabling anything.
+     */
+    floor: method(emptyInput),
+    setCalibrateFloor: method({
+      type: "object",
+      properties: { enabled: { type: "boolean" } },
+      required: ["enabled"],
+      additionalProperties: false
+    }),
+    refreshQuota: method(emptyInput),
+    /**
+     * What this machine has, for the first-run screen.
+     *
+     * Onboarding must show evidence, not a questionnaire. The router already
+     * detects credentials and imports history at startup; this reports what it
+     * found so the first thing a new user sees is the truth about their own
+     * machine rather than a form asking them to type it in.
+     */
+    onboarding: method(emptyInput),
+    /** Mark the first run as seen, so it does not reappear. */
+    completeOnboarding: method(emptyInput),
+    /**
+     * Record what the user's account page showed, so the estimate reflects the
+     * whole account rather than only the traffic this router routed.
+     *
+     * Takes the percentage the page displays, not a dollar figure: asking a user
+     * to divide by a cap they may not know is where the arithmetic mistakes come
+     * from. The server converts it against the window the page was describing.
+     */
+    /**
+     * Record the account's balance page, pasted whole.
+     *
+     * One field, because that is the actual task: select the page, copy, paste.
+     * The server reads the plan, the percentage, which window it belongs to, the
+     * reset time, the billing period and the wallet out of the text. A form with
+     * four boxes asks the user to do that parsing by hand and get it right.
+     */
+    recordPlanPage: method({
+      type: "object",
+      properties: {
+        /** The pasted page text. */
+        page: { type: "string" },
+        /** Apply it without previewing. Defaults to false: the user confirms first. */
+        confirm: { type: "boolean" }
+      },
+      required: ["page"],
+      additionalProperties: false
+    }),
+    report: method(emptyInput),
+    usage: method(emptyInput),
+    getConfig: method(emptyInput),
+    resetOverrides: method(emptyInput),
+    resetMetrics: method(emptyInput),
+    refreshIndicator: method(sessionInput),
+    diagnostics: method(emptyInput),
+    setTitleIndicator: method({
+      type: "object",
+      properties: { enabled: { type: "boolean" } },
+      required: ["enabled"],
+      additionalProperties: false
+    })
+  },
+  events: {
+    decision: {
+      schema: {
+        type: "object",
+        properties: {
+          decision: { type: "object", additionalProperties: true }
+        },
+        required: ["decision"],
+        additionalProperties: false
+      }
+    },
+    status: {
+      schema: {
+        type: "object",
+        properties: {
+          sessionID: { type: "string" },
+          summary: { type: "object", additionalProperties: true }
+        },
+        required: ["summary"],
+        additionalProperties: false
+      }
+    },
+    quota: {
+      schema: {
+        type: "object",
+        properties: {
+          providers: { type: "array", items: { type: "object", additionalProperties: true } }
+        },
+        required: ["providers"],
+        additionalProperties: false
+      }
+    }
+  }
+});
+
+// src/tui/index.tsx
+var tick = (ok) => ok ? "\u2713" : "\xB7";
+var formatDecision = (status, view) => {
+  if (!status) return "Smart Router: no response from the router.";
+  const head = `${status.runtime ?? "unknown"} \xB7 ${status.mode ?? "unknown"} \xB7 ${status.current ? `${status.current.providerID}/${status.current.id}` : "no model yet"}`;
+  if (!view) return `${head}
+
+No decision yet in this session.`;
+  const lines = [head, "", `Chosen  ${view.chosen ?? "nothing eligible"}`];
+  lines.push(
+    `        ${view.taskKind} \xB7 tier ${view.taskTier} \xB7 ${Math.round(view.contextTokens / 1e3)}k context`
+  );
+  if (view.reasons.length > 0) {
+    lines.push("", "Why");
+    for (const reason of view.reasons.slice(0, 5)) lines.push(`  \u2022 ${reason}`);
+  }
+  if (view.rows.length > 0) {
+    lines.push("", `Candidates (${view.eligibleCount} eligible, ${view.blockedCount} blocked)`);
+    for (const row of view.rows.slice(0, 10)) {
+      lines.push(`  ${tick(row.verdict !== "blocked")} ${row.key}`);
+      lines.push(`      ${row.reason}`);
+    }
+  }
+  if (view.warnings.length > 0) {
+    lines.push("", "Warnings");
+    for (const warning of view.warnings.slice(0, 3)) lines.push(`  ! ${warning}`);
+  }
+  return lines.join("\n");
+};
+var formatProviders = (providers) => {
+  if (providers.length === 0) return "No providers reported.";
+  const lines = [];
+  for (const provider of providers) {
+    const windows = provider.windows.filter((window) => window.reported).map((window) => `${window.label} ${window.lowerBound ? "\u2265" : ""}${window.usedPct}%`);
+    lines.push(`${provider.label}${provider.exhausted ? " (exhausted)" : ""}`);
+    lines.push(`  ${windows.length > 0 ? windows.join(" \xB7 ") : "no windows reported"} \xB7 ${provider.sourceLabel}`);
+    if (provider.caveat) lines.push(`  ! ${provider.caveat}`);
+  }
+  return lines.join("\n");
+};
+var index_default = Plugin.define({
+  /**
+   * Deliberately NOT nested under the server part's id.
+   *
+   * The GUI docs are explicit: if a plugin's id has another id nested under it,
+   * or nests under one, its GUI does not load. The TUI previously used
+   * "opencode-smart-router.tui", which nests under the server part's
+   * "opencode-smart-router" — so adding a TUI silently disabled the desktop
+   * panel, with no error beyond a generic request failure.
+   *
+   * A sibling id avoids the namespace collision entirely.
+   */
+  id: "opencode-smart-router-tui",
+  setup(context) {
+    const stop = context.data.on("session.execution.succeeded", () => {
+      void refresh();
+    });
+    const refresh = async () => {
+      try {
+        const result = await context.client.rpc(SmartRouterRpc).status({});
+        setFooter(`${result?.runtime ?? "?"} \xB7 ${result?.mode ?? "?"}`);
+      } catch {
+        setFooter("router unreachable");
+      }
+    };
+    let setFooter = (_text) => {
+    };
+    context.ui.slot({
+      append: "prompt.footer.status",
+      render: () => {
+        const [text, set] = createTerminalSignal("router");
+        setFooter = set;
+        void refresh();
+        return /* @__PURE__ */ React.createElement("text", null, text());
+      }
+    });
+    context.keymap.layer(() => ({
+      mode: "global",
+      commands: [
+        {
+          id: "router.decision",
+          title: "Router: why this model",
+          slash: { name: "router-why" },
+          palette: true,
+          run: async () => {
+            try {
+              const result = await context.client.rpc(SmartRouterRpc).status({});
+              const { summariseDecision: summariseDecision2, toProviderRow: toProviderRow2 } = await Promise.resolve().then(() => (init_viewmodel(), viewmodel_exports));
+              const body = formatDecision(result, summariseDecision2(result?.lastDecision));
+              await context.ui.dialog.alert({ title: "Smart Router", message: body });
+            } catch (cause) {
+              await context.ui.dialog.alert({
+                title: "Smart Router",
+                message: `Could not read router status: ${cause instanceof Error ? cause.message : String(cause)}`
+              });
+            }
+          }
+        },
+        {
+          id: "router.providers",
+          title: "Router: providers and allowances",
+          slash: { name: "router-quota" },
+          palette: true,
+          run: async () => {
+            try {
+              const result = await context.client.rpc(SmartRouterRpc).status({});
+              const { toProviderRow: toProviderRow2 } = await Promise.resolve().then(() => (init_viewmodel(), viewmodel_exports));
+              const rows = (result?.quota ?? []).map((snapshot) => toProviderRow2(snapshot));
+              await context.ui.dialog.alert({ title: "Providers", message: formatProviders(rows) });
+            } catch (cause) {
+              await context.ui.dialog.alert({
+                title: "Providers",
+                message: `Could not read provider status: ${cause instanceof Error ? cause.message : String(cause)}`
+              });
+            }
+          }
+        }
+      ],
+      bindings: ["router.decision", "router.providers"]
+    }));
+    return () => stop();
+  }
+});
+function createTerminalSignal(initial) {
+  let value = initial;
+  const listeners = /* @__PURE__ */ new Set();
+  return [() => value, (next) => {
+    value = next;
+    for (const listener of listeners) listener(next);
+  }];
+}
+export {
+  index_default as default,
+  formatDecision,
+  formatProviders
+};

package/docs/ARCHITECTURE.md

@@ -0,0 +1,104 @@
+# Architecture
+
+## Runtime path
+
+```text
+OpenCode prompt admission
+  → session.hook("prompt")
+    → load session model and context tokens
+    → local classifier
+    → hard-requirement eligibility
+    → provider and per-model quota snapshots
+    → expected-cost ranking with cache-loss and hysteresis
+    → session.switchModel(...) when a switch is justified
+  → admission completes
+  → request dispatch
+```
+
+The plugin does not modify the prompt text, attachments, tools, or agent. It never injects a classification prompt and never calls a model to decide routing.
+
+## Modules
+
+| Module | Responsibility |
+|---|---|
+| `src/core/models/seed.ts` | Curated model intelligence, design, tier, privacy, and allowance metadata |
+| `src/core/models/registry.ts` | Merges live OpenCode metadata, approval state, exclusions, and tier overrides |
+| `src/core/classify/classifier.ts` | Deterministic task tier, kind, vision, design, scope, and constraints |
+| `src/core/policy/eligibility.ts` | Hard requirements, privacy, premium policy, context fit, quota blocks |
+| `src/core/quota/ledger.ts` | Bounded local usage ledger, rolling windows, per-model estimates, premium spend |
+| `src/core/quota/commandcode.ts` | Read-only Command Code alpha billing adapter |
+| `src/core/quota/opencode-go.ts` | Read-only Go usage adapter |
+| `src/core/quota/credentials.ts` | Owner-only credential discovery; never logs or persists keys |
+| `src/core/quota/service.ts` | Caching, polling, stale detection, per-provider backoff |
+| `src/core/routing/engine.ts` | Cost estimation, success probability, quota pressure, affinity, decision record |
+| `src/core/failures.ts` | Failure classification and bounded escalation |
+| `src/core/config.ts` | Defaults, validation, global/project precedence, project guardrails |
+| `src/server/shared-core.ts` | One process-wide core: ledger, quota service, persistence, event stream, session ownership, catalog cache |
+| `src/server/controller.ts` | Per-location bridge: hooks, RPC, commands, title queue, session-local state |
+| `src/index.ts` | Plugin definition; creates one bridge per loaded location |
+
+## Prompt timing
+
+The V2 prompt hook runs once during admission, before attachment and skill resolution and before the durable inbox admission. The plugin awaits `ctx.session.switchModel` inside that hook. Integration tests and live desktop tests confirmed that the request-context hook observes the new model for the same prompt.
+
+The router skips switching when:
+
+- routing is paused or disabled;
+- the session is manually overridden or pinned;
+- another routing decision is already in flight for the same session;
+- the session is busy in an active model loop;
+- no eligible route exists.
+
+It never switches in the middle of a response.
+
+## Session state and affinity
+
+Each session tracks the last model, last routed model, context size, cache-read share, step count, failures, retry count, manual override, premium one-shot, and pause state.
+
+The engine prices a model switch as a cache loss. It keeps the current model when the expected savings are below the configured hysteresis. Above 300K context tokens the hysteresis is wider. The router never truncates or rewrites the conversation to make a route cheaper.
+
+## Quota model
+
+Two layers are kept separate:
+
+1. **Provider-reported plan state**: Go percentages, Command Code remaining credits, windows, resets, plan, and billing period.
+2. **Local per-model ledger**: observed step costs and tokens, used where the provider has no per-model breakdown.
+
+Provider values override the ledger for plan-level pressure. Local values supply per-model estimates. Every displayed value carries its source (`provider`, `estimate`, or `unknown`). Polling is read-only and spends no inference allowance.
+
+The ledger keeps 2,000 *raw* usage events for per-request detail, but nothing is discarded when that cap is exceeded. Events older than a 48-hour horizon, or pushed out by the cap, are folded into hourly `UsageBucket` aggregates keyed by provider, model and billing period, retained for 400 days. Aggregation reads both sources, so a heavy week stays fully accounted at a few hundred rows instead of losing its own beginning.
+
+History is also preserved across an upgrade: hydrating a ledger written before aggregates existed folds the overflow into buckets rather than applying the old truncation.
+
+Decisions (120) and sessions (250) remain bounded, and writes are debounced and JSON-sanitized.
+
+Plan definitions live in `src/core/plans/catalog.ts` as data, not as branches in routing or quota code. A plan is a set of credit pools plus the window rule for each pool, so supporting a different user's tier requires no source change, and a provider's plan strings never appear in the routing or policy layers.
+
+## Concurrency
+
+- One shared core is active per server process; each loaded location registers a lightweight bridge.
+- A reload disposes only that location’s bridge. The core persists across reloads, stops its timers after a grace period, and revives on the next setup.
+- Prompt routing is serialized per session. Concurrent submissions for the same session do not double-switch.
+- Different sessions can route concurrently.
+- The ledger is updated in one event loop; persistence is debounced. There is no cross-process writer.
+- Provider probes are single-flight per provider and back off independently.
+
+## Failure handling
+
+- Context overflow → no escalation; recommend compaction or a handoff session.
+- Network, rate limit, provider outage → retry/failover, never premium escalation.
+- Auth → terminal retry decision, cooldown, no model escalation.
+- Tool or command failure → no model escalation.
+- Invalid image → no text-only fallback; require a verified vision route.
+- Capability failure → one bounded escalation opportunity, then stop.
+- Partial generation or side effects → never automatically replayed; the next prompt is routed with the failure history.
+
+## Security
+
+- No API keys or tokens are logged, persisted in router state, or included in RPC output.
+- Command Code keys are read only from owner-only files or the connected integration and sent only to `https://api.commandcode.ai`.
+- Go OAuth tokens are used only for `https://opencode.ai/zen/go/v1/usage`.
+- Training-enabled and free promotional models are blocked by default.
+- Project config files cannot loosen global privacy, extra-credit, or premium policy.
+- The router does not read repository files to classify a prompt; it uses prompt structure and attachments only.
+- Prompt text is not stored by default. Decision records contain signals and reasons, not the prompt.