clauderipple 0.8.9 → 0.9.0

package/dist/mod/hooks/judge.ts

@@ -0,0 +1,226 @@
+import type { Domain, Effort, JudgeInput, Kind, Level, Pick, Settings, Verdict, WorkerVerdict } from '../types'
+import { DOMAINS, LEVELS } from './settings.ts'
+import { t } from './i18n.ts'
+import type { Lang } from './i18n.ts'
+
+const EFFORTS: readonly Effort[] = ['low', 'medium', 'high', 'xhigh', 'max']
+
+export const EFFORT_JUDGE_SYSTEM = `Choose the cheapest reasoning effort that can do this work well. This is a coding agent able to inspect files, run commands, and edit code, not merely answer a chat question.
+Assess work volume, uncertainty, and the cost of mistakes, not message length. A short choice approving a build inherits the size of that build. Corrections and steering retain at least the running effort; closing remarks need little effort. "Think hard" or thorough reasoning requires at least high; an explicit quick answer calls for low.
+Low and medium are only for turns that need no judgment: low for chit-chat, thanks, or a direct answer needing no inspection; medium for one fully specified, low-risk step the user spelled out (run this command, rename this). Anything that asks the agent to decide, explain why, review, verify, debug, plan, delegate, or change more than one thing needs at least high; most coding-agent turns are high. xhigh is for unusually difficult investigation, and max only for the hardest open-ended problems. Consider the current model's strength.
+Return only JSON {"effort":"low|medium|high|xhigh|max","sure":0.0,"why":"short reason"}. Confidence is between zero and one. The reason uses the user's language and at most six words.`
+
+/** A terse continuation usually carries no new scope; answers to questions are handled separately. */
+export function isShortFollowUp(text: string): boolean {
+  const trimmed = text.trim()
+  return trimmed.length > 0 && trimmed.length <= 12 && trimmed.split(/\s+/).length <= 2
+}
+
+export function looksLikeQuestion(assistantTail: string): boolean {
+  return assistantTail.slice(-400).includes('?')
+}
+
+/** The caller resolves slash commands so skills can be judged while host commands stay untouched. */
+export function shouldJudge(input: {
+  text: string; origin: string; auto: boolean; hostCommand?: boolean; modelId?: string
+  attachments?: readonly { type: string }[]; current?: Pick | null; assistantTail?: string
+}): boolean {
+  if (!input.auto || !['composer', 'bridge', 'sdk'].includes(input.origin) || (!input.text.trim() && !input.attachments?.length) || input.hostCommand) return false
+  if (input.modelId !== undefined && !isCacheSafeModel(input.modelId)) return false
+  const followup = input.current && input.current.by !== 'manual' && !input.text.trim().startsWith('/') &&
+    !input.attachments?.length && isShortFollowUp(input.text) && !looksLikeQuestion(input.assistantTail ?? '')
+  return !followup
+}
+
+function recent(input: JudgeInput): string {
+  const user = input.messages.findLast(message => message.role === 'user' && message.text.trim())
+  const assistant = input.messages.findLast(message => message.role === 'assistant' && message.text.trim())
+  return [user && `user: ${user.text.slice(0, 400)}`, assistant && `assistant: ${assistant.text.slice(-2000)}`].filter(Boolean).join('\n')
+}
+
+function nextText(input: JudgeInput, limit: number): string {
+  const counts: Record<string, number> = {}
+  for (const attachment of input.attachments ?? []) counts[attachment.type] = (counts[attachment.type] ?? 0) + 1
+  const attachments = Object.entries(counts).map(([type, count]) => `${type}: ${count}`).join(', ')
+  return [input.next.slice(0, limit), attachments && `Attachments (${attachments}).`,
+    input.midTurn && 'Steering a running turn: keep its effort for corrections and additions.'].filter(Boolean).join('\n')
+}
+
+/** Keep options in the assistant tail, since a one-letter answer may approve substantial work. */
+export function judgeContext(input: JudgeInput): string {
+  return [
+    `Current: ${input.current?.model ?? 'unknown'} / ${input.current?.effort ?? 'medium'}`,
+    recent(input) && `Recent conversation:\n${recent(input)}`,
+    input.contextPercent !== undefined && Number.isFinite(input.contextPercent) && `Context: ${Math.round(input.contextPercent)}%`,
+    `Next message:\n${nextText(input, 2000)}`,
+  ].filter(Boolean).join('\n\n')
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : undefined
+}
+
+function confidence(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1 ? value : undefined
+}
+
+function effort(value: unknown): Effort | undefined {
+  return EFFORTS.includes(value as Effort) ? value as Effort : undefined
+}
+
+/** JSON is a boundary: prose and fences are harmless, malformed objects are not verdicts. */
+export function parseEffortVerdict(text: string): Verdict | undefined {
+  const value = verdictObject(text)
+  const level = effort(value?.effort)
+  if (!level) return undefined
+  const sure = confidence(value?.sure)
+  return { effort: level, ...(sure !== undefined ? { sure } : {}), why: typeof value?.why === 'string' ? value.why.slice(0, 60) : '' }
+}
+
+/** Shared boundary decoder keeps effort and worker fields on the same object. */
+export function verdictObject(text: string): Record<string, unknown> | undefined {
+  for (let start = text.indexOf('{'); start !== -1; start = text.indexOf('{', start + 1)) {
+    for (let end = text.lastIndexOf('}'); end > start; end = text.lastIndexOf('}', end - 1)) {
+      try {
+        const value: unknown = JSON.parse(text.slice(start, end + 1))
+        const parsed = record(value)
+        if (parsed) return parsed
+      } catch {
+        // Try a smaller span: a judge can put braces in its surrounding prose.
+      }
+    }
+  }
+  return undefined
+}
+
+const effortCriteria = {
+  low: 'Small direct work with little uncertainty or planning.',
+  medium: 'Ordinary bounded coding with a few inspections or edits.',
+  high: 'Substantial multi-step coding or debugging where mistakes matter.',
+  xhigh: 'Difficult extended investigation with interacting constraints.',
+  max: 'Exceptional open-ended research or the hardest reasoning problems.',
+}
+const levelCriteria = {
+  light: 'Mechanical chores, repeated changes, or simple lookups.',
+  standard: 'Implement a designed change, research, summarize documentation, or review.',
+  deep: 'Careful high-stakes reasoning, subtle debugging, architecture, or security.',
+}
+const domainCriteria: Record<Domain, string> = {
+  design: 'Visual composition, branding, taste, look and voice of copy.',
+  frontend: 'Frontend UI implementation, components, styles and interactions.',
+  backend: 'Server application logic, APIs and authentication.', infra: 'Infrastructure, deployment, networks and operations.',
+  data: 'Data processing, schemas, queries and analysis.', test: 'Tests, quality assurance and verification.',
+  docs: 'Documentation, technical writing and summaries.', research: 'Investigation and research.', general: 'Other or cross-domain work.',
+}
+/** Plan decides what to build; do carries it out. The ladder sends plans at standard or deep to its Plan rung. */
+export const kindCriteria: Record<Kind, string> = {
+  plan: 'Decide what to build: architecture, design decisions, specifications, or a review whose verdict decides.',
+  do: 'Carry out what is decided: implement, fix, run, look up, rename, write, or check.',
+}
+export function kindOf(value: unknown): Kind | undefined {
+  return value === 'plan' || value === 'do' ? value : undefined
+}
+
+function jevBody(input: JudgeInput, task: string) {
+  return {
+    model: 'jev-latest' as const,
+    state: { task, current_model: input.current?.model ?? null, current_effort: input.current?.effort ?? null,
+      recent_conversation: recent(input), next_message: nextText(input, 4000) },
+    questions: { effort: { type: 'choice' as const, instructions: 'Select the effort needed for this work.', criteria: { ...effortCriteria } } },
+  }
+}
+
+export function jevEffortRequest(input: JudgeInput) {
+  return jevBody(input, EFFORT_JUDGE_SYSTEM)
+}
+
+/** Capability and kind of work are independent; the judge never chooses a provider. */
+export function jevWorkerRequest(input: { description: string; prompt: string }) {
+  const body = jevBody({ messages: [], next: `${input.description}\n${input.prompt.slice(0, 3000)}` }, 'Choose the domain, capability level, kind of work and reasoning effort for a delegated coding task. Judge scope and risk independently of the domain.')
+  return { ...body, questions: { ...body.questions,
+    domain: { type: 'choice' as const, instructions: 'Select the domain of this task.', criteria: { ...domainCriteria } },
+    level: { type: 'choice' as const, instructions: 'Select the capability level needed.', criteria: { ...levelCriteria } },
+    kind: { type: 'choice' as const, instructions: 'Select whether this task decides what to build or carries it out.', criteria: { ...kindCriteria } },
+  } }
+}
+
+function answers(json: unknown): Record<string, unknown> | undefined {
+  const root = record(json)
+  return record(root?.answers) ?? record(record(root?.result)?.answers)
+}
+
+function answerSure(answer: Record<string, unknown>): number | undefined {
+  return confidence(answer.confidence ?? record(answer.probabilities)?.[String(answer.choice)])
+}
+
+/** Torn between levels, Jev leaves a session at the effort it runs when that effort is still a plausible answer. */
+export function parseJevEffort(json: unknown, current?: { effort: Effort } | null, lang: Lang = 'en'): Verdict | undefined {
+  const answer = record(answers(json)?.effort)
+  const level = effort(answer?.choice)
+  if (!answer || !level) return undefined
+  const sure = answerSure(answer)
+  const odds = record(answer.probabilities)
+  const plausible = current && (!odds || (confidence(odds[current.effort]) ?? 0) >= 0.25)
+  if (sure !== undefined && sure < 0.5 && current && current.effort !== level && plausible) return { effort: current.effort, sure, why: t(lang, 'judge.keptUnsure') }
+  return { effort: level, ...(sure !== undefined ? { sure } : {}), why: '' }
+}
+
+export function parseJevWorker(json: unknown): WorkerVerdict | undefined {
+  const reply = answers(json)
+  const domainAnswer = record(reply?.domain)
+  const levelAnswer = record(reply?.level)
+  const effortAnswer = record(reply?.effort)
+  const selectedEffort = effort(effortAnswer?.choice)
+  if (!domainAnswer || !DOMAINS.includes(domainAnswer.choice as Domain) || !levelAnswer || !LEVELS.includes(levelAnswer.choice as Level) || !effortAnswer || !selectedEffort) return undefined
+  // Confidence moves a task up the ladder, so it is the level's question that counts, not the kind's.
+  const scores = [answerSure(domainAnswer), answerSure(levelAnswer), answerSure(effortAnswer)].filter((score): score is number => score !== undefined)
+  const kind = kindOf(record(reply?.kind)?.choice) ?? 'do'
+  return { domain: domainAnswer.choice as Domain, level: levelAnswer.choice as Level, kind, effort: selectedEffort, ...(scores.length ? { sure: Math.min(...scores) } : {}), why: '' }
+}
+
+export function jevUsage(json: unknown): number {
+  const usage = record(record(json)?.usage)
+  return [usage?.input_tokens, usage?.output_tokens].reduce<number>((sum, count) => sum + (typeof count === 'number' && Number.isFinite(count) && count >= 0 ? count : 0), 0)
+}
+
+export function jevFailure(status: number | 'timeout' | 'network', lang: Lang = 'en'): string {
+  if (status === 401 || status === 403) return t(lang, 'toasts.jevRejected')
+  if (status === 402) return t(lang, 'toasts.jevCredits')
+  if (status === 429) return t(lang, 'toasts.jevRateLimited')
+  if (status === 'timeout') return t(lang, 'toasts.jevTimeout')
+  if (status === 'network') return t(lang, 'toasts.jevNetwork')
+  return t(lang, 'toasts.jevHttp', { status })
+}
+
+export function parseJevKey(fileText: string): string | undefined {
+  const value = /^[ \t]*TYPESAFE_API_KEY[ \t]*=[ \t]*([^\r\n]*)/m.exec(fileText)?.[1]?.trim()
+  if (!value) return undefined
+  const unquoted = ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) ? value.slice(1, -1).trim() : value
+  return unquoted || undefined
+}
+
+export function tipped(level: Effort, sure: number | undefined, bias: Settings['bias']): Effort {
+  if (!bias || sure === undefined || !Number.isFinite(sure) || sure < 0 || sure >= (Math.abs(bias) === 2 ? 0.85 : 0.65)) return level
+  return EFFORTS[Math.max(0, Math.min(4, EFFORTS.indexOf(level) + Math.sign(bias)))]!
+}
+
+export function bounded(level: Effort, floor: Effort, ceiling: Effort): Effort {
+  const min = EFFORTS.indexOf(floor)
+  const max = Math.max(min, EFFORTS.indexOf(ceiling))
+  return EFFORTS[Math.max(min, Math.min(max, EFFORTS.indexOf(level)))]!
+}
+
+export function capped(level: Effort, saving: boolean): Effort {
+  return saving && EFFORTS.indexOf(level) > 1 ? 'medium' : level
+}
+
+/** Save is last, so even a high floor cannot defeat the subscription-saving cap. */
+export function finalEffort(verdict: Verdict, settings: Settings, saving: boolean, lang: Lang = 'en'): { effort: Effort; why: string } {
+  const adjusted = bounded(tipped(verdict.effort, verdict.sure, settings.bias), settings.floor, settings.ceiling)
+  const result = capped(adjusted, saving)
+  return { effort: result, why: result !== adjusted ? t(lang, 'toasts.saveMode') : adjusted !== verdict.effort ? t(lang, 'toasts.yourSettings') : verdict.why }
+}
+
+export function isCacheSafeModel(modelId: string): boolean {
+  return /(?:opus|sonnet|haiku)-5-5(?:$|[^\d])/.test(modelId)
+}

package/dist/mod/hooks/ladder.js

@@ -0,0 +1,179 @@
+// The four workers (docs/specs/2026-10-12-worker-tiers.md): which rung a verdict lands on, and the
+// fill that gives every rung a model from the ticked, connected ones. Pure, with type-only imports,
+// so the router fills settings with the same rule the mod uses.
+import { CLAUDE_WORKERS, EFFORTS, LEVEL_RUNG, RUNGS, candidateKey, isAllowed } from "./settings.js";
+/** Below this the judge is unsure enough that a task takes the next rung. */
+export const SURE_ENOUGH = 0.5;
+/**
+ * Doing work lands on Low, Medium and High by level. Planning — a deliverable that is a decision,
+ * design, strategy or verdict — is the Max worker's job from standard up (a business strategy
+ * judged "standard plan" went to the Medium worker before, 2026-10-12 pick log); a light plan
+ * (rename a section of a spec) is still light work.
+ * An unsure verdict moves up one rung (Low → Medium → High); High and Plan stay, so only a
+ * planning verdict ever reaches Plan.
+ */
+export function rungOf(verdict) {
+    const rung = verdict.kind === 'plan' && verdict.level !== 'light' ? 'plan' : LEVEL_RUNG[verdict.level];
+    if (verdict.sure === undefined || !(verdict.sure < SURE_ENOUGH))
+        return rung;
+    return rung === 'light' ? 'standard' : rung === 'standard' ? 'hard' : rung;
+}
+/** The rung above, none above Plan. */
+export function rungAbove(rung) {
+    return RUNGS[RUNGS.indexOf(rung) + 1];
+}
+/**
+ * The nearest effort a model takes, as the router clamps one (compat.ts clampEffort): ties go up,
+ * an unknown ladder keeps the effort.
+ */
+export function nearestEffort(effort, ladder) {
+    const known = ladder.filter((value) => EFFORTS.includes(value));
+    if (!known.length || known.includes(effort))
+        return effort;
+    const at = EFFORTS.indexOf(effort);
+    return known.reduce((best, next) => {
+        const d = Math.abs(EFFORTS.indexOf(next) - at);
+        const bd = Math.abs(EFFORTS.indexOf(best) - at);
+        return d < bd || (d === bd && EFFORTS.indexOf(next) > EFFORTS.indexOf(best)) ? next : best;
+    });
+}
+/** How a provider is paid for, from its configuration (type, auth, preset, address). */
+export function billingOf(provider, model) {
+    if (model && /(?::|-)free$/i.test(model))
+        return 'free';
+    if (provider.type === 'chatgpt')
+        return 'subscription';
+    if (provider.type === 'anthropic')
+        return provider.auth === 'api-key' ? 'payg' : 'subscription';
+    if (provider.type === 'google')
+        return provider.auth === 'antigravity' ? 'subscription' : 'payg';
+    if (provider.preset === 'opencode-go')
+        return 'subscription';
+    if (provider.preset === 'ollama' || provider.preset === 'lmstudio')
+        return 'free';
+    // A named hosted service is paid for wherever it is reached through; only a hand-entered local server is free.
+    if (provider.preset)
+        return 'payg';
+    if (provider.url) {
+        try {
+            const host = new URL(provider.url).hostname;
+            if (host === 'localhost' || host === '127.0.0.1' || host === '[::1]' || host.endsWith('.localhost'))
+                return 'free';
+        }
+        catch { /* not an address: paid like any other API */ }
+    }
+    return 'payg';
+}
+/** A family's newest model: gpt-6.1-sol over gpt-6-sol. */
+function newest(choices, family) {
+    const version = (model) => (/(\d+(?:[.-]\d+)*)/.exec(model)?.[1] ?? '0').split(/[.-]/).map(Number);
+    const later = (a, b) => { for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const d = (b[i] ?? 0) - (a[i] ?? 0);
+        if (d)
+            return d;
+    } return 0; };
+    return choices.filter(c => family.test(c.model) && !c.target.model).sort((a, b) => later(version(a.model), version(b.model)) || a.model.localeCompare(b.model))[0];
+}
+/** The cheapest model paid by the token or free: free first, then by measured cost; unmeasured last. */
+export function cheapest(choices) {
+    const cost = (c) => c.billing === 'free' ? 0 : c.cost ?? Number.POSITIVE_INFINITY;
+    return choices.filter(c => (c.billing === 'payg' || c.billing === 'free') && !c.target.model)
+        .sort((a, b) => cost(a) - cost(b) || a.model.localeCompare(b.model))[0];
+}
+const claudeModel = (alias) => (choices) => choices.find(c => c.target.agent === 'general-purpose' && c.target.model === alias);
+const family = (pattern) => (choices) => newest(choices, pattern);
+const LUNA = family(/\bluna\b/i);
+const SOL = family(/\bsol\b/i);
+const ASTRA = family(/\bastra\b/i);
+const HAIKU = claudeModel('haiku');
+const SONNET = claudeModel('sonnet');
+const OPUS = claudeModel('opus');
+/**
+ * The fill rule's wishes (a preset's, by name; only `claudeGpt` is used): each rung's in order: the first is what the preset names, the rest what stands in
+ * when it is not connected (the nearest choice, a GPT model's Claude counterpart).
+ */
+const PRESETS = {
+    claude: {
+        light: [{ pick: HAIKU, effort: 'low' }], standard: [{ pick: SONNET, effort: 'medium' }],
+        hard: [{ pick: OPUS, effort: 'high' }], plan: [{ pick: OPUS, effort: 'high' }],
+    },
+    claudeGpt: {
+        light: [{ pick: cheapest, effort: 'max' }, { pick: LUNA, effort: 'low' }, { pick: HAIKU, effort: 'low' }],
+        standard: [{ pick: SOL, effort: 'medium' }, { pick: SONNET, effort: 'medium' }],
+        hard: [{ pick: ASTRA, effort: 'high' }, { pick: OPUS, effort: 'high' }],
+        plan: [{ pick: OPUS, effort: 'high' }],
+    },
+    gpt: {
+        light: [{ pick: LUNA, effort: 'low' }, { pick: HAIKU, effort: 'low' }],
+        standard: [{ pick: SOL, effort: 'medium' }, { pick: SONNET, effort: 'medium' }],
+        hard: [{ pick: ASTRA, effort: 'high' }, { pick: OPUS, effort: 'high' }],
+        plan: [{ pick: ASTRA, effort: 'xhigh' }, { pick: OPUS, effort: 'high' }],
+    },
+    cheap: {
+        light: [{ pick: cheapest, effort: 'high' }, { pick: LUNA, effort: 'low' }, { pick: HAIKU, effort: 'low' }],
+        standard: [{ pick: cheapest, effort: 'max' }, { pick: LUNA, effort: 'medium' }, { pick: HAIKU, effort: 'medium' }],
+        hard: [{ pick: cheapest, effort: 'max' }, { pick: LUNA, effort: 'high' }, { pick: SONNET, effort: 'medium' }],
+        plan: [{ pick: SONNET, effort: 'high' }],
+    },
+};
+/** Claude's own models as rung choices: always there, since the session itself runs on Claude. */
+export function claudeChoices(efforts) {
+    const ladder = efforts.filter((e) => EFFORTS.includes(e));
+    return CLAUDE_WORKERS.map(w => ({ target: { ...w.target }, model: w.model, provider: w.provider, billing: 'subscription', efforts: ladder }));
+}
+/**
+ * A preset's rule applied to the connected, ticked models: each rung takes its first wish that is
+ * there, at that wish's effort moved to the nearest the model takes. A rung that had to take a
+ * later wish is listed in `substituted`.
+ */
+export function preset(id, choices) {
+    const rungs = {};
+    const substituted = [];
+    for (const rung of RUNGS) {
+        const wants = PRESETS[id][rung];
+        let filled = false;
+        for (const [at, want] of wants.entries()) {
+            const choice = want.pick(choices);
+            if (!choice)
+                continue;
+            rungs[rung] = { target: { ...choice.target }, effort: nearestEffort(want.effort, choice.efforts) };
+            if (at > 0)
+                substituted.push(rung);
+            filled = true;
+            break;
+        }
+        // Claude is always there, so only a choice list without it lands here: the session model.
+        if (!filled) {
+            rungs[rung] = { target: { agent: 'general-purpose' }, effort: wants[0].effort };
+            substituted.push(rung);
+        }
+    }
+    return { rungs, substituted };
+}
+/** The choices a person ticked; an empty list ticks every one. */
+export function tickedChoices(choices, allow) {
+    return choices.filter(choice => isAllowed(candidateKey(choice.target), choice.provider, allow));
+}
+/** Only empty lists need filling; unticked entries stay in order and are skipped at dispatch. */
+export function ladderNeedsFill(rungs, _allow = []) {
+    return RUNGS.some(rung => !rungs[rung]?.length);
+}
+/**
+ * Fill empty lists from the ticked, connected choices. Existing ordered lists are never rewritten
+ * for temporary availability or shared allow-list changes; dispatch explains each skipped entry.
+ */
+export function fillLadder(rungs, allow, choices) {
+    const pick = preset('claudeGpt', tickedChoices(choices, allow));
+    const out = {};
+    const filled = [];
+    for (const rung of RUNGS) {
+        const own = rungs[rung];
+        if (own?.length) {
+            out[rung] = own;
+            continue;
+        }
+        out[rung] = [pick.rungs[rung]];
+        filled.push(rung);
+    }
+    return { rungs: out, filled };
+}

package/dist/mod/hooks/ladder.ts

@@ -0,0 +1,174 @@
+// The four workers (docs/specs/2026-10-12-worker-tiers.md): which rung a verdict lands on, and the
+// fill that gives every rung a model from the ticked, connected ones. Pure, with type-only imports,
+// so the router fills settings with the same rule the mod uses.
+
+import type { Billing, Effort, LadderChoice, Preset, PresetId, Rung, Rungs, Step, WorkerVerdict } from '../types/index.d.ts'
+import { CLAUDE_WORKERS, EFFORTS, LEVEL_RUNG, RUNGS, candidateKey, isAllowed } from './settings.ts'
+
+/** Below this the judge is unsure enough that a task takes the next rung. */
+export const SURE_ENOUGH = 0.5
+
+/**
+ * Doing work lands on Low, Medium and High by level. Planning — a deliverable that is a decision,
+ * design, strategy or verdict — is the Max worker's job from standard up (a business strategy
+ * judged "standard plan" went to the Medium worker before, 2026-10-12 pick log); a light plan
+ * (rename a section of a spec) is still light work.
+ * An unsure verdict moves up one rung (Low → Medium → High); High and Plan stay, so only a
+ * planning verdict ever reaches Plan.
+ */
+export function rungOf(verdict: Pick<WorkerVerdict, 'level' | 'kind' | 'sure'>): Rung {
+  const rung = verdict.kind === 'plan' && verdict.level !== 'light' ? 'plan' : LEVEL_RUNG[verdict.level]
+  if (verdict.sure === undefined || !(verdict.sure < SURE_ENOUGH)) return rung
+  return rung === 'light' ? 'standard' : rung === 'standard' ? 'hard' : rung
+}
+
+/** The rung above, none above Plan. */
+export function rungAbove(rung: Rung): Rung | undefined {
+  return RUNGS[RUNGS.indexOf(rung) + 1]
+}
+
+/**
+ * The nearest effort a model takes, as the router clamps one (compat.ts clampEffort): ties go up,
+ * an unknown ladder keeps the effort.
+ */
+export function nearestEffort(effort: Effort, ladder: readonly string[]): Effort {
+  const known = ladder.filter((value): value is Effort => EFFORTS.includes(value as Effort))
+  if (!known.length || known.includes(effort)) return effort
+  const at = EFFORTS.indexOf(effort)
+  return known.reduce((best, next) => {
+    const d = Math.abs(EFFORTS.indexOf(next) - at)
+    const bd = Math.abs(EFFORTS.indexOf(best) - at)
+    return d < bd || (d === bd && EFFORTS.indexOf(next) > EFFORTS.indexOf(best)) ? next : best
+  })
+}
+
+/** How a provider is paid for, from its configuration (type, auth, preset, address). */
+export function billingOf(provider: { type?: string; auth?: string; preset?: string; url?: string }, model?: string): Billing {
+  if (model && /(?::|-)free$/i.test(model)) return 'free'
+  if (provider.type === 'chatgpt') return 'subscription'
+  if (provider.type === 'anthropic') return provider.auth === 'api-key' ? 'payg' : 'subscription'
+  if (provider.type === 'google') return provider.auth === 'antigravity' ? 'subscription' : 'payg'
+  if (provider.preset === 'opencode-go') return 'subscription'
+  if (provider.preset === 'ollama' || provider.preset === 'lmstudio') return 'free'
+  // A named hosted service is paid for wherever it is reached through; only a hand-entered local server is free.
+  if (provider.preset) return 'payg'
+  if (provider.url) {
+    try {
+      const host = new URL(provider.url).hostname
+      if (host === 'localhost' || host === '127.0.0.1' || host === '[::1]' || host.endsWith('.localhost')) return 'free'
+    } catch { /* not an address: paid like any other API */ }
+  }
+  return 'payg'
+}
+
+/** A family's newest model: gpt-6.1-sol over gpt-6-sol. */
+function newest(choices: readonly LadderChoice[], family: RegExp): LadderChoice | undefined {
+  const version = (model: string): number[] => (/(\d+(?:[.-]\d+)*)/.exec(model)?.[1] ?? '0').split(/[.-]/).map(Number)
+  const later = (a: number[], b: number[]): number => { for (let i = 0; i < Math.max(a.length, b.length); i++) { const d = (b[i] ?? 0) - (a[i] ?? 0); if (d) return d } return 0 }
+  return choices.filter(c => family.test(c.model) && !c.target.model).sort((a, b) => later(version(a.model), version(b.model)) || a.model.localeCompare(b.model))[0]
+}
+
+/** The cheapest model paid by the token or free: free first, then by measured cost; unmeasured last. */
+export function cheapest(choices: readonly LadderChoice[]): LadderChoice | undefined {
+  const cost = (c: LadderChoice): number => c.billing === 'free' ? 0 : c.cost ?? Number.POSITIVE_INFINITY
+  return choices.filter(c => (c.billing === 'payg' || c.billing === 'free') && !c.target.model)
+    .sort((a, b) => cost(a) - cost(b) || a.model.localeCompare(b.model))[0]
+}
+
+type Want = { pick: (choices: readonly LadderChoice[]) => LadderChoice | undefined; effort: Effort }
+
+const claudeModel = (alias: string) => (choices: readonly LadderChoice[]) => choices.find(c => c.target.agent === 'general-purpose' && c.target.model === alias)
+const family = (pattern: RegExp) => (choices: readonly LadderChoice[]) => newest(choices, pattern)
+const LUNA = family(/\bluna\b/i)
+const SOL = family(/\bsol\b/i)
+const ASTRA = family(/\bastra\b/i)
+const HAIKU = claudeModel('haiku')
+const SONNET = claudeModel('sonnet')
+const OPUS = claudeModel('opus')
+
+/**
+ * The fill rule's wishes (a preset's, by name; only `claudeGpt` is used): each rung's in order: the first is what the preset names, the rest what stands in
+ * when it is not connected (the nearest choice, a GPT model's Claude counterpart).
+ */
+const PRESETS: Readonly<Record<PresetId, Readonly<Record<Rung, readonly Want[]>>>> = {
+  claude: {
+    light: [{ pick: HAIKU, effort: 'low' }], standard: [{ pick: SONNET, effort: 'medium' }],
+    hard: [{ pick: OPUS, effort: 'high' }], plan: [{ pick: OPUS, effort: 'high' }],
+  },
+  claudeGpt: {
+    light: [{ pick: cheapest, effort: 'max' }, { pick: LUNA, effort: 'low' }, { pick: HAIKU, effort: 'low' }],
+    standard: [{ pick: SOL, effort: 'medium' }, { pick: SONNET, effort: 'medium' }],
+    hard: [{ pick: ASTRA, effort: 'high' }, { pick: OPUS, effort: 'high' }],
+    plan: [{ pick: OPUS, effort: 'high' }],
+  },
+  gpt: {
+    light: [{ pick: LUNA, effort: 'low' }, { pick: HAIKU, effort: 'low' }],
+    standard: [{ pick: SOL, effort: 'medium' }, { pick: SONNET, effort: 'medium' }],
+    hard: [{ pick: ASTRA, effort: 'high' }, { pick: OPUS, effort: 'high' }],
+    plan: [{ pick: ASTRA, effort: 'xhigh' }, { pick: OPUS, effort: 'high' }],
+  },
+  cheap: {
+    light: [{ pick: cheapest, effort: 'high' }, { pick: LUNA, effort: 'low' }, { pick: HAIKU, effort: 'low' }],
+    standard: [{ pick: cheapest, effort: 'max' }, { pick: LUNA, effort: 'medium' }, { pick: HAIKU, effort: 'medium' }],
+    hard: [{ pick: cheapest, effort: 'max' }, { pick: LUNA, effort: 'high' }, { pick: SONNET, effort: 'medium' }],
+    plan: [{ pick: SONNET, effort: 'high' }],
+  },
+}
+
+/** Claude's own models as rung choices: always there, since the session itself runs on Claude. */
+export function claudeChoices(efforts: readonly string[]): LadderChoice[] {
+  const ladder = efforts.filter((e): e is Effort => EFFORTS.includes(e as Effort))
+  return CLAUDE_WORKERS.map(w => ({ target: { ...w.target }, model: w.model, provider: w.provider, billing: 'subscription' as const, efforts: ladder }))
+}
+
+/**
+ * A preset's rule applied to the connected, ticked models: each rung takes its first wish that is
+ * there, at that wish's effort moved to the nearest the model takes. A rung that had to take a
+ * later wish is listed in `substituted`.
+ */
+export function preset(id: PresetId, choices: readonly LadderChoice[]): Preset {
+  const rungs = {} as Record<Rung, Step>
+  const substituted: Rung[] = []
+  for (const rung of RUNGS) {
+    const wants = PRESETS[id][rung]
+    let filled = false
+    for (const [at, want] of wants.entries()) {
+      const choice = want.pick(choices)
+      if (!choice) continue
+      rungs[rung] = { target: { ...choice.target }, effort: nearestEffort(want.effort, choice.efforts) }
+      if (at > 0) substituted.push(rung)
+      filled = true
+      break
+    }
+    // Claude is always there, so only a choice list without it lands here: the session model.
+    if (!filled) { rungs[rung] = { target: { agent: 'general-purpose' }, effort: wants[0]!.effort }; substituted.push(rung) }
+  }
+  return { rungs, substituted }
+}
+
+/** The choices a person ticked; an empty list ticks every one. */
+export function tickedChoices(choices: readonly LadderChoice[], allow: readonly string[]): LadderChoice[] {
+  return choices.filter(choice => isAllowed(candidateKey(choice.target), choice.provider, allow))
+}
+
+/** Only empty lists need filling; unticked entries stay in order and are skipped at dispatch. */
+export function ladderNeedsFill(rungs: Rungs, _allow: readonly string[] = []): boolean {
+  return RUNGS.some(rung => !rungs[rung]?.length)
+}
+
+/**
+ * Fill empty lists from the ticked, connected choices. Existing ordered lists are never rewritten
+ * for temporary availability or shared allow-list changes; dispatch explains each skipped entry.
+ */
+export function fillLadder(rungs: Rungs, allow: readonly string[], choices: readonly LadderChoice[]): { rungs: Record<Rung, Step[]>; filled: Rung[] } {
+  const pick = preset('claudeGpt', tickedChoices(choices, allow))
+  const out = {} as Record<Rung, Step[]>
+  const filled: Rung[] = []
+  for (const rung of RUNGS) {
+    const own = rungs[rung]
+    if (own?.length) { out[rung] = own; continue }
+    out[rung] = [pick.rungs[rung]]
+    filled.push(rung)
+  }
+  return { rungs: out, filled }
+}