@crouton-kit/crouter 0.3.70 → 0.3.79

package/dist/core/runtime/tmux.js

@@ -8,8 +8,7 @@
 // root) or switch-client + select-window (across roots). done/dead nodes close
 // their window; reviving opens a fresh one.
 import { spawnSync } from 'node:child_process';
-import { readConfig } from '../config.js';
-import { defaultCanvasNavConfig } from '../../types.js';
+import { resolveUserKeybindings, } from '../keybindings/index.js';
 import { bundledPiCommandForShell } from './pi-cli.js';
 import { surfaceTmuxStyleArgs } from './surface-bg.js';
 // ---------------------------------------------------------------------------
@@ -72,13 +71,22 @@ function ensureBracketedPaste() {
     // broken `Enbp=E[?2004h` (no ESC) and silently disables bracketed paste.
     tmux(['set-option', '-sga', 'terminal-overrides', '*:Enbp=\\E[?2004h:Dsbp=\\E[?2004l']);
 }
+/** Server-level tmux prerequisites for crtr's viewer surfaces, applied once a
+ *  server exists (callers invoke via ensureSession). Currently: bracketed paste
+ *  capability (above) and `focus-events on`, which forwards terminal focus
+ *  in/out (DECSET 1004) to the program in each pane — the attach viewer uses it
+ *  to hollow out the editor cursor in blurred panes. */
+function ensureServerOptions() {
+    ensureBracketedPaste();
+    tmux(['set-option', '-s', 'focus-events', 'on']);
+}
 /** Create a detached session rooted at `cwd` if it doesn't exist. The session
  *  name is a root's tmux home; every node under that root is a window in it. */
 export function ensureSession(name, cwd) {
     if (!sessionExists(name)) {
         tmux(['new-session', '-d', '-s', name, '-c', cwd]);
     }
-    ensureBracketedPaste();
+    ensureServerOptions();
 }
 function envFlags(env) {
     const out = [];
@@ -400,135 +408,234 @@ export function sendKeysEnter(pane, text) {
     return tmux(['send-keys', '-t', pane, text, 'Enter']).ok;
 }
 // ---------------------------------------------------------------------------
-// Prefix menu — Alt+C opens a which-key-style tmux display-menu of crouter
-// actions. Installed on the running server at root boot; idempotent (a re-bind
-// overwrites the previous one). Menu entries are data-driven: tmux renders the
-// action tree, and every `crtr` / `popup` action routes through `crtr canvas
-// chord` so node-relative vars resolve in one safe place.
+// Crouter-owned tmux bindings
 // ---------------------------------------------------------------------------
+const TMUX_BINDING_MANIFEST = '@crtr_keybindings_manifest';
+const ROOT_TABLE = 'root';
+const MENU_ACTIONS = {
+    'crtr.tmux.menu.promote': { description: 'promote to orchestrator', action: { kind: 'keys', keys: '/promote' } },
+    'crtr.tmux.menu.resume': { description: 'resume node', action: { kind: 'keys', keys: '/resume-node' } },
+    'crtr.tmux.menu.demote': { description: 'demote to terminal', action: { kind: 'command', run: 'node lifecycle demote --pane {pane}' } },
+    'crtr.tmux.menu.detach': { description: 'detach to background', action: { kind: 'command', run: 'node lifecycle demote --pane {pane} --detach' } },
+    'crtr.tmux.menu.close-subtree': { description: 'close agent + subtree', action: { kind: 'command', run: 'node lifecycle close --pane {pane}' } },
+    'crtr.tmux.menu.context': { description: 'browse context dirs', action: { kind: 'keys', keys: '/context' } },
+    'crtr.tmux.menu.providers': { description: 'manage providers', action: { kind: 'popup', run: 'sys setup' } },
+    'crtr.tmux.menu.graph': { description: 'graph view', action: { kind: 'keys', keys: '/graph' } },
+    'crtr.tmux.menu.focus-manager': { description: 'focus manager', action: { kind: 'command', run: 'node focus {manager}' } },
+    'crtr.tmux.menu.open': undefined,
+    'crtr.tmux.menu.issues': undefined,
+    'crtr.tmux.menu.issue.idea': undefined,
+    'crtr.tmux.menu.issue.bug': undefined,
+    'crtr.tmux.node.next': undefined,
+    'crtr.tmux.node.previous': undefined,
+    'crtr.tmux.view.next': undefined,
+    'crtr.tmux.view.previous': undefined,
+};
 function escapeTmuxFormats(value) {
     return value.replace(/#/g, '##');
 }
-function runShellCmd(shellCmd) {
-    return `run-shell ${shellQuote(shellCmd)}`;
-}
-function tmuxCmd(args) {
+function tmuxCommand(args) {
     return args.map(shellQuote).join(' ');
 }
-function chordShellCmd(run) {
-    return runShellCmd(`crtr canvas chord --pane '#{pane_id}' --run ${shellQuote(escapeTmuxFormats(run))} >/dev/null 2>&1`);
-}
-function popupCmd(run) {
-    return `display-popup -E -w 60% -h 50% -d "#{pane_current_path}" ${shellQuote(`crtr canvas chord --pane '#{pane_id}' --run ${shellQuote(escapeTmuxFormats(run))} --interactive`)}`;
-}
-function keysCmd(keys) {
-    return `send-keys -t '#{pane_id}' ${shellQuote(escapeTmuxFormats(keys))} Enter`;
+function chordCommand(run, interactive = false) {
+    const command = `crtr canvas chord --pane '#{pane_id}' --run ${shellQuote(escapeTmuxFormats(run))}${interactive ? ' --interactive' : ''}`;
+    return interactive
+        ? `display-popup -E -w 60% -h 50% -d "#{pane_current_path}" ${shellQuote(command)}`
+        : `run-shell ${shellQuote(`${command} >/dev/null 2>&1`)}`;
+}
+function renderMenuAction(action) {
+    switch (action.kind) {
+        case 'keys': return `send-keys -t '#{pane_id}' ${shellQuote(escapeTmuxFormats(action.keys))} Enter`;
+        case 'command': return chordCommand(action.run);
+        case 'popup': return chordCommand(action.run, true);
+        case 'submenu': return tmuxCommand(buildMenuArgs(action.title, action.items));
+    }
 }
 function buildMenuArgs(title, items) {
     const safeTitle = escapeTmuxFormats(title);
+    const widestItem = items.reduce((width, item) => Math.max(width, escapeTmuxFormats(item.description).length), 0);
     const args = ['display-menu', '-T', `#[align=centre]${safeTitle}`, ...surfaceTmuxStyleArgs()];
-    const boxW = Math.max(safeTitle.length, ...items.map((i) => escapeTmuxFormats(i.desc).length)) + 6;
-    const nudgeX = 1;
-    const nudgeY = 3;
-    args.push('-x', `#{e|-:#{pane_right},${boxW + nudgeX}}`, '-y', `#{e|+:#{pane_top},${nudgeY}}`);
+    args.push('-x', `#{e|-:#{pane_right},${Math.max(safeTitle.length, widestItem) + 7}}`, '-y', '#{e|+:#{pane_top},3}');
     for (const item of items) {
-        args.push(escapeTmuxFormats(item.desc), escapeTmuxFormats(item.key), renderAction(item.action, item.desc));
+        args.push(escapeTmuxFormats(item.description), item.selector, renderMenuAction(item.action));
     }
     args.push('-esc / q to close', '', '');
     return args;
 }
-function renderAction(action, label) {
-    const kind = action.kind ?? 'crtr';
-    switch (kind) {
-        case 'keys':
-            return keysCmd(action.keys);
-        case 'popup':
-            return popupCmd(action.run);
-        case 'menu':
-            return tmuxCmd(buildMenuArgs(label, action.items));
-        case 'crtr':
-            return chordShellCmd(action.run);
-        default:
-            throw new Error(`unknown canvas action kind: ${kind}`);
+const TMUX_NAMED_KEYS = {
+    enter: 'Enter', escape: 'Escape', tab: 'Tab', backspace: 'BSpace', delete: 'DC',
+    space: 'Space', up: 'Up', down: 'Down', left: 'Left', right: 'Right',
+    pageup: 'PPage', pagedown: 'NPage', home: 'Home', end: 'End',
+};
+function tmuxKey(stroke) {
+    const parts = stroke.split('+');
+    let key = parts.pop();
+    const modifiers = new Set(parts);
+    if (modifiers.has('shift') && key.length === 1 && /[a-z]/.test(key)) {
+        key = key.toUpperCase();
+        modifiers.delete('shift');
+    }
+    key = TMUX_NAMED_KEYS[key] ?? key;
+    const prefix = [
+        modifiers.has('ctrl') ? 'C-' : '',
+        modifiers.has('alt') ? 'M-' : '',
+        modifiers.has('shift') ? 'S-' : '',
+    ].join('');
+    return `${prefix}${key}`;
+}
+function menuSelector(stroke) {
+    const parts = stroke.split('+');
+    const key = parts.at(-1);
+    return parts.includes('shift') && /[a-z]/.test(key) ? key.toUpperCase() : key === 'space' ? ' ' : key;
+}
+function menuItems(bindings) {
+    const issueItems = [];
+    for (const [id, description, type] of [
+        ['crtr.tmux.menu.issue.idea', 'idea', 'idea'],
+        ['crtr.tmux.menu.issue.bug', 'bug', 'bug'],
+    ]) {
+        for (const gesture of bindings.gestures(id)) {
+            issueItems.push({ description, selector: menuSelector(gesture), action: { kind: 'popup', run: `canvas issue new --type ${type}` } });
+        }
     }
+    const items = [];
+    for (const id of [
+        'crtr.tmux.menu.promote', 'crtr.tmux.menu.resume', 'crtr.tmux.menu.demote',
+        'crtr.tmux.menu.detach', 'crtr.tmux.menu.close-subtree', 'crtr.tmux.menu.context',
+        'crtr.tmux.menu.providers', 'crtr.tmux.menu.graph', 'crtr.tmux.menu.focus-manager', 'crtr.tmux.menu.issues',
+    ]) {
+        const entry = id === 'crtr.tmux.menu.issues'
+            ? { description: 'new issue / todo', action: { kind: 'submenu', title: 'new issue / todo', items: issueItems } }
+            : MENU_ACTIONS[id];
+        if (id === 'crtr.tmux.menu.issues' && issueItems.length === 0)
+            continue;
+        for (const gesture of bindings.gestures(id)) {
+            items.push({ description: entry.description, selector: menuSelector(gesture), action: entry.action });
+        }
+    }
+    return items;
+}
+function bindingAt(table, key) {
+    const result = tmux(['list-keys', '-T', table]);
+    if (!result.ok)
+        return null;
+    return result.stdout.split('\n').find((line) => {
+        const match = line.match(/^bind-key\s+(?:-r\s+)?-T\s+\S+\s+(\S+)\s+/);
+        return match?.[1] === key;
+    }) ?? null;
 }
-/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails. */
-export function installMenuBinding() {
-    let prefixBinds;
+function sequenceTable(prefix) {
+    return `crtr-${Buffer.from(prefix).toString('hex')}`;
+}
+function readManifest() {
+    const option = tmux(['show-options', '-s', '-q', TMUX_BINDING_MANIFEST]);
+    if (!option.ok)
+        return null;
+    if (option.stdout === '')
+        return { pairs: [], existed: false };
+    const result = tmux(['show-options', '-s', '-qv', TMUX_BINDING_MANIFEST]);
+    if (!result.ok)
+        return null;
     try {
-        prefixBinds = readConfig('user').canvasNav.prefixBinds;
+        const value = JSON.parse(result.stdout);
+        if (!Array.isArray(value) || value.some((pair) => typeof pair !== 'object' || pair === null || typeof pair.table !== 'string' || typeof pair.key !== 'string'))
+            return null;
+        return { pairs: value, existed: true };
     }
     catch {
-        prefixBinds = defaultCanvasNavConfig().prefixBinds;
+        return null;
     }
-    const items = [];
-    for (const [key, bind] of Object.entries(prefixBinds)) {
-        if (key.length !== 1)
-            continue;
-        const desc = bind.desc ?? `chord ${key}`;
-        items.push({ key, desc, action: bind });
+}
+const LEGACY_ROOT_BINDINGS = [
+    { key: 'M-c', markers: ['display-menu', 'promote to orchestrator', 'crtr canvas chord', 'new issue / todo'] },
+    { key: 'M-]', markers: ['run-shell', 'crtr node cycle --dir next', "--pane '#{pane_id}'"] },
+    { key: 'M-[', markers: ['run-shell', 'crtr node cycle --dir prev', "--pane '#{pane_id}'"] },
+    { key: 'M-v', markers: ['switch-client', '-T crtr-view'] },
+];
+function adoptLegacyBindings() {
+    for (const legacy of LEGACY_ROOT_BINDINGS) {
+        const existing = bindingAt(ROOT_TABLE, legacy.key);
+        if (existing !== null && legacy.markers.every((marker) => existing.includes(marker))) {
+            tmux(['unbind-key', '-T', ROOT_TABLE, legacy.key]);
+        }
     }
-    return tmux(['bind-key', '-n', 'M-c', ...buildMenuArgs(' crtr ', items)]).ok;
 }
-// ---------------------------------------------------------------------------
-// Nav bindings — Alt+] / Alt+[ DFS-walk the canvas one window at a time. Each
-// key shells out to `crtr node cycle`, passing the active pane so the walk is
-// relative to the agent in front of you; cycle then swaps the next/prev node
-// into that pane (like `node focus`). Output is discarded so the keypress never
-// pops a results view. Installed at root boot alongside the Alt+C menu.
-// ---------------------------------------------------------------------------
-/** Bind Alt+] (forward) and Alt+[ (back) to the DFS canvas walk. Best-effort;
- *  false if either bind fails. NOTE: Alt+[ is only delivered cleanly when the
- *  terminal/tmux disambiguate it from a raw CSI introducer (`extended-keys on`).
- */
-export function installNavBindings() {
-    const next = tmux([
-        'bind-key', '-n', 'M-]', 'run-shell',
-        `crtr node cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`,
-    ]).ok;
-    const prev = tmux([
-        'bind-key', '-n', 'M-[', 'run-shell',
-        `crtr node cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`,
-    ]).ok;
-    return next && prev;
+function actionCommand(id) {
+    switch (id) {
+        case 'crtr.tmux.node.next': return ['run-shell', `crtr node cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`];
+        case 'crtr.tmux.node.previous': return ['run-shell', `crtr node cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`];
+        case 'crtr.tmux.view.next': return ['run-shell', `crtr surface view cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`];
+        case 'crtr.tmux.view.previous': return ['run-shell', `crtr surface view cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`];
+        default: throw new Error(`no tmux command for ${id}`);
+    }
 }
-// ---------------------------------------------------------------------------
-// View-nav bindings — Alt+V then ] / [ cycle the view hosted in a MONITOR pane
-// to the next/prev available view, in place. A VIEW-PREFIXED CHORD, not a bare
-// Alt pair: Alt+V switches into a private one-shot `crtr-view` key table, then
-// ] (next) / [ (prev) fire the cycle — mirroring node cycle's bracket DIRECTION
-// grammar (Alt+] next / Alt+[ prev) while NAMESPACING the brackets so they can
-// never shadow root bindings. This is collision-proof: only ONE root key (M-v)
-// is claimed, and bare Alt pairs are a minefield in real configs (e.g. Alt+,/. 
-// and Alt+]/.[ commonly bound to window/pane nav). The bracket lives in the
-// private table, so it also sidesteps the M-[ vs CSI-introducer ambiguity that
-// dogs installNavBindings' Alt+[. Each key shells surface-view cycle, passing the
-// active pane; cycle reads the pane's @crtr_view tag and respawns it on the
-// next/prev view. Output discarded so the keypress never pops a results view.
-// Installed at root boot alongside the node nav + Alt+C menu.
-//
-// NOTE: `M-v` is a GLOBAL root binding — it intercepts Alt+V in every pane/app
-// (e.g. swallowed from the pi editor), the same tradeoff crtr already takes for
-// M-c / M-] / M-[. Intended: crtr owns a small set of Alt chords server-wide.
-// ---------------------------------------------------------------------------
-/** Bind Alt+V → (], [) to the view-monitor cycle. `M-v` enters the private
- *  `crtr-view` key table (switch-client -T), then ] cycles next / [ cycles prev.
- *  Best-effort; false if any of the three binds fail. Deliberately distinct from
- *  installNavBindings' bare Alt+]/Alt+[ (node cycle): the two cycles coexist on
- *  the same server — brackets alone walk the node graph, Alt+V-then-bracket flips
- *  view monitors. The bracket keys are bound in the private table, so they NEVER
- *  shadow the user's root ]/[ and carry no CSI-introducer ambiguity. */
-export function installViewNavBindings() {
-    const enter = tmux([
-        'bind-key', '-n', 'M-v', 'switch-client', '-T', 'crtr-view',
-    ]).ok;
-    const next = tmux([
-        'bind-key', '-T', 'crtr-view', ']', 'run-shell',
-        `crtr surface view cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`,
-    ]).ok;
-    const prev = tmux([
-        'bind-key', '-T', 'crtr-view', '[', 'run-shell',
-        `crtr surface view cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`,
-    ]).ok;
-    return enter && next && prev;
+/** Reconcile the tmux server with one immutable crouter binding snapshot. */
+export function installTmuxBindings(bindings = resolveUserKeybindings()) {
+    const diagnostics = [];
+    const installed = [];
+    const manifest = readManifest();
+    if (manifest === null) {
+        diagnostics.push({ code: 'tmux-error', message: `tmux is unavailable or ${TMUX_BINDING_MANIFEST} is malformed` });
+        return { ok: false, installed, diagnostics };
+    }
+    if (!manifest.existed)
+        adoptLegacyBindings();
+    for (const pair of manifest.pairs) {
+        const result = tmux(['unbind-key', '-T', pair.table, pair.key]);
+        if (!result.ok && bindingAt(pair.table, pair.key) !== null) {
+            diagnostics.push({ code: 'tmux-error', message: `could not remove crouter binding ${pair.table}:${pair.key}: ${result.stderr}` });
+        }
+    }
+    if (diagnostics.some((diagnostic) => diagnostic.code === 'tmux-error')) {
+        return { ok: false, installed, diagnostics };
+    }
+    const install = (table, key, command, id, gesture) => {
+        if (bindingAt(table, key) !== null) {
+            diagnostics.push({ code: 'occupied', bindingId: id, gesture, message: `${table}:${key} is already bound by tmux; ${id} was not installed` });
+            return false;
+        }
+        const result = tmux(['bind-key', '-T', table, key, ...command]);
+        if (!result.ok) {
+            diagnostics.push({ code: 'tmux-error', bindingId: id, gesture, message: `could not install ${id}: ${result.stderr}` });
+            return false;
+        }
+        installed.push({ table, key });
+        return true;
+    };
+    const menuCommand = buildMenuArgs(' crtr ', menuItems(bindings));
+    for (const gesture of bindings.gestures('crtr.tmux.menu.open')) {
+        install(ROOT_TABLE, tmuxKey(gesture), menuCommand, 'crtr.tmux.menu.open', gesture);
+    }
+    for (const id of ['crtr.tmux.node.next', 'crtr.tmux.node.previous']) {
+        for (const gesture of bindings.gestures(id))
+            install(ROOT_TABLE, tmuxKey(gesture), actionCommand(id), id, gesture);
+    }
+    const sequences = new Map();
+    for (const id of ['crtr.tmux.view.next', 'crtr.tmux.view.previous']) {
+        for (const gesture of bindings.gestures(id)) {
+            const [first, second] = gesture.split(' > ');
+            const prefix = tmuxKey(first);
+            const entries = sequences.get(prefix) ?? [];
+            entries.push({ id, gesture, second: tmuxKey(second) });
+            sequences.set(prefix, entries);
+        }
+    }
+    for (const [prefix, entries] of sequences) {
+        if (bindingAt(ROOT_TABLE, prefix) !== null) {
+            for (const entry of entries)
+                diagnostics.push({ code: 'occupied', bindingId: entry.id, gesture: entry.gesture, message: `${ROOT_TABLE}:${prefix} is already bound by tmux; ${entry.id} was not installed` });
+            continue;
+        }
+        const table = sequenceTable(prefix);
+        let children = 0;
+        for (const entry of entries)
+            if (install(table, entry.second, actionCommand(entry.id), entry.id, entry.gesture))
+                children++;
+        if (children > 0)
+            install(ROOT_TABLE, prefix, ['switch-client', '-T', table], entries[0].id, entries[0].gesture);
+    }
+    const save = tmux(['set-option', '-s', TMUX_BINDING_MANIFEST, JSON.stringify(installed)]);
+    if (!save.ok)
+        diagnostics.push({ code: 'tmux-error', message: `could not save crouter tmux ownership manifest: ${save.stderr}` });
+    return { ok: diagnostics.every((diagnostic) => diagnostic.code !== 'tmux-error'), installed, diagnostics };
 }

package/dist/core/scope.js

@@ -1,5 +1,5 @@
 import { homedir } from 'node:os';
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, statSync, realpathSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CRTR_DIR_NAME } from '../types.js';
@@ -48,6 +48,14 @@ export function builtinPiPackageDir(name) {
 export function userScopeRoot() {
     return join(homedir(), CRTR_DIR_NAME);
 }
+function realpathOrSelf(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
 function isProjectScopeDir(candidate, userRoot) {
     if (candidate === userRoot || !existsSync(candidate))
         return false;
@@ -61,16 +69,31 @@ function isProjectScopeDir(candidate, userRoot) {
 export function findProjectScopeRoot(startDir = process.cwd()) {
     return findProjectScopeRoots(startDir)[0] ?? null;
 }
-/** Walk `startDir` upward to the filesystem root, collecting every ancestor
- *  `.crouter/` dir (nearest first). The user-global `~/.crouter/` is excluded
- *  because it is the separate user scope, not a project ancestor. */
+/** Walk `startDir` upward collecting every ancestor `.crouter/` dir (nearest
+ *  first). The user-global `~/.crouter/` is excluded because it is the separate
+ *  user scope, not a project ancestor.
+ *
+ *  The walk is FENCED at `homedir()`: it must never climb at or above HOME.
+ *  Home's own `.crouter/` is the user scope (already excluded), and nothing at
+ *  or above HOME is a project ancestor. Without this fence, a relocated HOME
+ *  nested under a directory tree that itself contains a `.crouter/` (e.g. a
+ *  mock-VM home under the real host home) would sweep the host's `~/.crouter`
+ *  (and any other above-HOME `.crouter`) in as a bogus project ancestor,
+ *  leaking one machine's user-global memory into a nested-HOME node. Mirrors
+ *  the on-read positional-walk fence (src/core/substrate/on-read.ts). A read
+ *  whose start dir is outside HOME (e.g. a production VM with HOME=/root and no
+ *  ancestor `.crouter`) never reaches home and walks to the filesystem root, as
+ *  before. */
 function collectAncestorScopeRoots(startDir, userRoot) {
     const roots = [];
+    const home = realpathOrSelf(homedir());
     let dir = resolve(startDir);
     while (true) {
         const candidate = join(dir, CRTR_DIR_NAME);
         if (isProjectScopeDir(candidate, userRoot))
             roots.push(candidate);
+        if (realpathOrSelf(dir) === home)
+            return roots;
         const parent = dirname(dir);
         if (parent === dir)
             return roots;

package/dist/core/subscription-state.d.ts

@@ -0,0 +1,90 @@
+import type { ThinkingLevel } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+export declare const ANTHROPIC_PROVIDER_ID = "anthropic";
+export declare const OPENAI_CODEX_PROVIDER_ID = "openai-codex";
+export type ManagedProviderId = typeof ANTHROPIC_PROVIDER_ID | typeof OPENAI_CODEX_PROVIDER_ID;
+export type LadderProviderId = "anthropic" | "openai";
+export type ModelStrength = "ultra" | "strong" | "medium" | "light";
+export type SubscriptionCredential = {
+    label: string;
+    refresh?: string;
+    access?: string;
+    expires?: number;
+    rateLimitedUntil: number;
+    lastAttemptAt: number;
+    lastRateLimitedAt: number;
+    accountId?: string;
+};
+export type ModelRef = {
+    providerId: ManagedProviderId;
+    modelId: string;
+};
+export type RotationConfig = {
+    defaultFallbackStrength?: ModelStrength;
+    revertWhenAvailable?: boolean;
+    preferredModel?: ModelRef;
+};
+type RotationConfigUpdate = {
+    defaultFallbackStrength?: ModelStrength;
+    revertWhenAvailable?: boolean;
+    preferredModel?: ModelRef | null;
+};
+export type FallbackTarget = {
+    providerId: ManagedProviderId;
+    modelId: string;
+    label: string;
+    strength: ModelStrength;
+    thinkingLevel?: ThinkingLevel;
+};
+export declare function isManagedProvider(providerId: string | undefined): providerId is ManagedProviderId;
+/** The `modelLadders` CONFIG key for a runtime provider id -- `openai-codex`
+ *  (the runtime/auth id) maps to the `openai` ladder key used in
+ *  ~/.crouter/config.json. Callers building a repair command that a user can
+ *  paste into `crtr sys config set modelLadders.<key>...` must use THIS key,
+ *  not the runtime provider id. */
+export declare function getLadderProviderId(providerId: ManagedProviderId): LadderProviderId;
+export declare function getProviderLabel(providerId: ManagedProviderId): string;
+export declare function mutateSubscriptionPool(providerId: ManagedProviderId, fn: (pool: SubscriptionCredential[]) => SubscriptionCredential[] | undefined): SubscriptionCredential[];
+export declare function readSubscriptionPool(providerId: ManagedProviderId): SubscriptionCredential[];
+export declare function writeSubscriptionPool(providerId: ManagedProviderId, next: SubscriptionCredential[]): SubscriptionCredential[];
+export declare function upsertSubscription(providerId: ManagedProviderId, next: SubscriptionCredential): SubscriptionCredential[];
+export declare class DuplicateSubscriptionError extends Error {
+    constructor(message: string);
+}
+export declare function addSubscription(providerId: ManagedProviderId, entry: SubscriptionCredential): SubscriptionCredential[];
+export declare function upsertSubscriptionWithUniqueAccount(providerId: ManagedProviderId, next: SubscriptionCredential): SubscriptionCredential[];
+export type DefaultSlotLogin = {
+    refresh: string;
+    access: string;
+    expires: number;
+    accountId?: string;
+    lastRateLimitedAt: number;
+};
+export declare function commitDefaultIdentity(providerId: ManagedProviderId, login: DefaultSlotLogin): SubscriptionCredential[];
+export declare function renameSubscription(providerId: ManagedProviderId, ref: string, nextLabel: string): SubscriptionCredential[];
+export declare function removeManagedAccount(providerId: ManagedProviderId, ref: string): SubscriptionCredential[];
+export declare function commitManagedLogin(providerId: ManagedProviderId, label: string, credential: {
+    refresh: string;
+    access: string;
+    expires: number;
+    accountId?: string;
+    defaultLastRateLimitedAt: number;
+}): SubscriptionCredential[];
+export declare function removeManagedProvider(providerId: ManagedProviderId, label?: string): SubscriptionCredential[];
+export declare function removeSubscription(providerId: ManagedProviderId, ref: string): SubscriptionCredential[];
+export declare function promoteSubscription(providerId: ManagedProviderId, ref: string): SubscriptionCredential[];
+export declare function markSubscriptionAttempt(providerId: ManagedProviderId, ref: string, attemptAt?: number): SubscriptionCredential[];
+export declare function markSubscriptionRateLimited(providerId: ManagedProviderId, ref: string, retryAfterMs: number, attemptAt?: number, rateLimitedAt?: number): SubscriptionCredential[];
+export declare function markSubscriptionSuccess(providerId: ManagedProviderId, ref: string, attemptAt?: number): SubscriptionCredential[];
+export declare function findAvailableSubscription(providerId: ManagedProviderId, now?: number): SubscriptionCredential | undefined;
+export declare function parseRetryAfterHeader(value: string | undefined, now?: number): number | undefined;
+export declare function readRotationConfig(): RotationConfig;
+export declare function writeRotationConfig(next: RotationConfigUpdate): RotationConfig;
+export declare function clearPreferredModel(): RotationConfig;
+export declare function rememberPreferredModel(model: ModelRef): RotationConfig;
+export declare function resolveFallbackTarget(currentProviderId: ManagedProviderId, currentModelId?: string, config?: RotationConfig, currentThinkingLevel?: string): FallbackTarget | undefined;
+export declare function shouldRestorePreferredModel(config?: RotationConfig, now?: number): boolean;
+export declare function restorePreferredModelIfPossible(piApi: ExtensionAPI, ctx: Pick<ExtensionContext, "model" | "modelRegistry">): Promise<boolean>;
+export declare function switchToFallbackIfPossible(piApi: ExtensionAPI, ctx: Pick<ExtensionContext, "model" | "modelRegistry">, preferredModel?: ModelRef | undefined): Promise<FallbackTarget | undefined>;
+export declare function formatStatusLine(providerId: ManagedProviderId, now?: number): string;
+export {};