@north-light/api 0.3.580 → 0.3.587

package/dist/commands/sys/panels/terminal-panel.js

@@ -0,0 +1,67 @@
+import { truncateToWidth } from '@earendil-works/pi-tui';
+import { theme, wrapText } from '../../../core/tui/panel.js';
+import { describeEdit } from '../terminal-option.js';
+/** The macOS Option-as-Alt step: explains the setting for the detected terminal
+ *  and, only where crouter can write it safely, offers to apply it. The offer
+ *  starts UNCHECKED — nothing is written without the person ticking it, and the
+ *  exact lines are on screen while they decide. */
+export class TerminalPanel {
+    plan;
+    onChange;
+    apply = false;
+    constructor(plan, onChange) {
+        this.plan = plan;
+        this.onChange = onChange;
+    }
+    badge() {
+        return this.plan.status === 'configured' ? '\u2713' : this.apply ? 'will apply' : 'info';
+    }
+    /** Whether this step can toggle anything — drives the footer wording. */
+    get canApply() {
+        return this.plan.edit !== undefined;
+    }
+    /** The edit to perform at install time; undefined unless consented. */
+    get selectedEdit() {
+        return this.apply ? this.plan.edit : undefined;
+    }
+    handleInput(data, matches) {
+        if (!matches || this.plan.edit === undefined)
+            return false;
+        if (!matches('crtr.setup.toggle', data))
+            return false;
+        this.apply = !this.apply;
+        this.onChange();
+        return true;
+    }
+    render(width) {
+        const { plan } = this;
+        const out = [
+            truncateToWidth(`${theme.fg('accent', theme.bold('Option key'))}${theme.fg('dim', `  Alt shortcuts in ${plan.terminal.name}`)}`, width),
+            '',
+        ];
+        const intro = plan.status === 'configured'
+            ? plan.summary
+            : `${plan.summary} crouter’s menu is Alt+C and its inbox is Alt+I; on a Mac, Alt is the Option key. Until it is set, type /menu for the menu.`;
+        for (const line of wrapText(intro, width))
+            out.push(theme.fg(plan.status === 'configured' ? 'success' : 'muted', line));
+        if (plan.instructions.length > 0) {
+            out.push('');
+            for (const line of plan.instructions) {
+                if (/^\s/.test(line))
+                    out.push(truncateToWidth(theme.fg('accent', line), width));
+                else
+                    for (const wrapped of wrapText(line, width))
+                        out.push(wrapped);
+            }
+        }
+        if (plan.edit !== undefined) {
+            out.push('');
+            const checked = this.apply ? theme.fg('success', '[x]') : theme.fg('dim', '[ ]');
+            out.push(truncateToWidth(`${checked} Apply this for me ${theme.fg('dim', '— writes exactly:')}`, width));
+            for (const line of describeEdit(plan.edit))
+                out.push(truncateToWidth(theme.fg('muted', `    ${line}`), width));
+            out.push(theme.fg('dim', '    A terminal restart/reload may be needed afterwards.'));
+        }
+        return out;
+    }
+}

package/dist/commands/sys/provider-login.d.ts

@@ -0,0 +1,8 @@
+import { ModelRuntime } from '@earendil-works/pi-coding-agent';
+import type { ProviderAuthInteraction } from '@earendil-works/pi-ai';
+export declare function openProviderLoginRuntime(): Promise<ModelRuntime>;
+export declare function loginProvider(runtime: ModelRuntime, providerId: string, interaction: ProviderAuthInteraction, options?: {
+    label?: string;
+    beforeInstall?: () => boolean;
+}): Promise<boolean>;
+export declare function terminalAuthInteraction(): ProviderAuthInteraction;

package/dist/commands/sys/provider-login.js

@@ -0,0 +1,99 @@
+import { execFile } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+import { join } from 'node:path';
+import { ModelRuntime } from '@earendil-works/pi-coding-agent';
+import { cliClient } from '../api-client.js';
+import { InputError } from '../../core/io.js';
+import { ApiCredentialStore } from '../../core/model-auth/api-credential-store.js';
+import { isManagedProvider } from '../../core/managed-providers.js';
+import { daemonManagedLogin } from '../../core/model-auth/daemon-login.js';
+import { piAgentDir } from '../../core/runtime/package-health.js';
+export async function openProviderLoginRuntime() {
+    const agentDir = piAgentDir();
+    return ModelRuntime.create({
+        credentials: new ApiCredentialStore(() => cliClient()),
+        modelsPath: join(agentDir, 'models.json'),
+    });
+}
+export async function loginProvider(runtime, providerId, interaction, options = {}) {
+    // Managed subscriptions sign in through the daemon (RT-LLM-24/45): it runs the
+    // vendor flow and writes the account, so this process only shows the URL or
+    // code and relays Anthropic's pasted code.
+    if (isManagedProvider(providerId)) {
+        await daemonManagedLogin(cliClient(), providerId, interaction, options.label ? { label: options.label } : {});
+        return true;
+    }
+    const provider = runtime.getProvider(providerId);
+    const oauth = provider?.auth.oauth;
+    if (oauth === undefined)
+        throw new InputError({
+            error: 'provider_login_unavailable',
+            message: `provider ${providerId} has no OAuth login flow`,
+            next: 'Configure an API key through `crtr sys setup`, then run `crtr sys connect` again.',
+        });
+    const credential = await oauth.login(interaction);
+    if (options.beforeInstall?.() === false)
+        return false;
+    const { type: _type, access, refresh, expires, ...extra } = credential;
+    await cliClient().installCredential(providerId, {
+        kind: 'oauth',
+        access_token: access,
+        refresh_token: refresh,
+        expires_at: new Date(expires).toISOString(),
+        ...(Object.keys(extra).length > 0 ? { extra } : {}),
+    });
+    return true;
+}
+function openBrowser(url) {
+    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    execFile(command, args, { timeout: 5_000 }, () => { });
+}
+function notify(event) {
+    switch (event.type) {
+        case 'auth_url':
+            process.stderr.write(`${event.instructions}\n${event.url}\n`);
+            openBrowser(event.url);
+            break;
+        case 'device_code':
+            process.stderr.write(`${event.verificationUri}\nCode: ${event.userCode}\n`);
+            openBrowser(event.verificationUri);
+            break;
+        case 'info':
+        case 'progress':
+            process.stderr.write(`${event.message}\n`);
+            break;
+    }
+}
+async function promptTerminal(prompt) {
+    if (!process.stdin.isTTY || !process.stderr.isTTY)
+        throw new InputError({
+            error: 'interactive_login_required',
+            message: 'provider login requires an interactive terminal',
+            next: 'Run `crtr sys connect` from an interactive terminal, or configure the provider credential through `crtr sys setup` first.',
+        });
+    const question = prompt.type === 'select'
+        ? `${prompt.message}\n${prompt.options.map((option, index) => `${index + 1}. ${option.label}`).join('\n')}\nSelect: `
+        : `${prompt.message}${prompt.placeholder ? ` (${prompt.placeholder})` : ''}: `;
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await rl.question(question, { signal: prompt.signal });
+        if (prompt.type !== 'select')
+            return answer;
+        const selected = prompt.options[Number.parseInt(answer, 10) - 1]?.id;
+        if (selected === undefined)
+            throw new Error('Login cancelled');
+        return selected;
+    }
+    finally {
+        rl.close();
+    }
+}
+export function terminalAuthInteraction() {
+    const controller = new AbortController();
+    return {
+        signal: controller.signal,
+        notify,
+        prompt: promptTerminal,
+    };
+}

package/dist/commands/sys/retry-delivery.d.ts

@@ -0,0 +1 @@
+export declare const sysRetryDeliveryLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/sys/retry-delivery.js

@@ -0,0 +1,33 @@
+import { defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+export const sysRetryDeliveryLeaf = defineLeaf({
+    name: 'retry-delivery',
+    description: 're-queue a delivery that failed after its retry budget',
+    whenToUse: 'a `delivery.exhausted` or `daemon_action.exhausted` error event (see `crtr sys logs`) or a `permanent_failed` outcome-delivery names a delivery id, and its receiver is working again',
+    help: {
+        name: 'sys retry-delivery',
+        summary: 'put one permanently failed push delivery or daemon action back to pending with a fresh attempt budget',
+        params: [
+            { kind: 'positional', name: 'delivery-id', required: true, constraint: 'The 32-character delivery id (or daemon action id) from the exhausted error event.' },
+        ],
+        output: [
+            { name: 'delivery_id', type: 'string', required: true, constraint: 'The re-queued delivery id; unchanged.' },
+            { name: 'state', type: 'string', required: true, constraint: 'Always `pending`: the next daemon tick attempts it.' },
+        ],
+        outputKind: 'object',
+        effects: ['Sets the delivery back to pending, due now, with attempts reset to 0. The receiver gets the same delivery id and event id as before, so it must tolerate a repeat. Fails with 404 `delivery_not_failed` when the delivery is not permanently failed.'],
+    },
+    run: async (input) => {
+        const id = typeof input['deliveryId'] === 'string' ? input['deliveryId'].trim() : '';
+        if (id === '')
+            throw new InputError({ error: 'invalid_delivery_id', message: 'a delivery id is required', field: 'delivery-id', next: 'Pass the delivery id named by the exhausted error event.' });
+        try {
+            return { ...await cliClient().retryDelivery(id) };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+    render: (result) => `<delivery id="${result['delivery_id']}" state="${result['state']}"/>`,
+});

package/dist/commands/sys/settings-shell.d.ts

@@ -0,0 +1,54 @@
+import { ModelRegistry, ModelRuntime } from '@earendil-works/pi-coding-agent';
+import { TUI, type Component, type Focusable } from '@earendil-works/pi-tui';
+import { type BindingId, type BindingResolution } from '../../core/keybindings/index.js';
+export type DestinationId = "providers" | "models" | "provider-options" | "keybindings" | "display" | "profiles" | "panes" | "broker-limits" | "updates";
+export declare class SettingsShell implements Component, Focusable {
+    private readonly tui;
+    private readonly bindings;
+    private readonly terminalRows;
+    private readonly providers;
+    private readonly models;
+    private readonly keybindings;
+    private readonly brokerLimits;
+    private readonly profiles;
+    private readonly destinations;
+    private index;
+    /** The rail owns the arrow keys until you step into a panel. */
+    private railFocused;
+    private _focused;
+    private cachedWidth;
+    private cachedHeight;
+    private cachedLines;
+    onCancel?: () => void;
+    constructor(tui: TUI, agentDir: string, runtime: ModelRuntime, registry: ModelRegistry, bindings: BindingResolution<BindingId>, rawKeybindings: unknown, terminalRows: () => number, rawTmuxPassthrough?: unknown, initial?: DestinationId);
+    set focused(value: boolean);
+    get focused(): boolean;
+    private get current();
+    invalidate(): void;
+    private syncFocus;
+    private enterRail;
+    private enterPanel;
+    private go;
+    private matches;
+    private label;
+    /** Panels that have taken over the keyboard — a live text field, a modal, an
+     *  open picker — keep every key including Escape until they release it. */
+    private panelOwnsKeyboard;
+    /** `crtr.setup.tab-next`/`-previous` still carry the tab strip's horizontal
+     *  arrows. In the rail layout the horizontal arrows mean "into the panel" and
+     *  "back to the rail", so only the Tab gestures cycle destinations. */
+    private cyclesDestination;
+    handleInput(data: string): void;
+    /** Typing a letter on the rail jumps to the destination it starts. */
+    private jumpToInitial;
+    private routeToPanel;
+    private close;
+    dispose(): void;
+    private renderRail;
+    /** Left hint plus the always-there navigation keys, the hint shedding its
+     *  optional half on a narrow terminal rather than pushing "close" off. */
+    private footer;
+    private panelHint;
+    render(width: number): string[];
+}
+export declare function runSettings(initial?: DestinationId): Promise<void>;

package/dist/commands/sys/settings-shell.js

@@ -0,0 +1,400 @@
+// The `crtr sys settings` surface: a grouped left rail over the config panels.
+//
+// This is the persistent settings editor. The first-run installer lives in
+// setup-wizard.ts; both surfaces reuse only the panels they actually share.
+import { matchesKey, truncateToWidth, visibleWidth, } from '@earendil-works/pi-tui';
+import { configPath } from '../../core/config.js';
+import { formatGesture, formatMovePair, matchesPiTuiInput, } from '../../core/keybindings/index.js';
+import { reconcileInboxFrontDoor } from './setup-core.js';
+import { runSetupSettingsProcess } from './setup-settings-runner.js';
+import { BrokerLimitsPanel } from './panels/broker-limits-panel.js';
+import { KeybindingsPanel } from './panels/keybindings-panel.js';
+import { ModelsPanel } from './panels/models-panel.js';
+import { PAGE_CHROME_ROWS, columns, padAnsi, pageFrame, theme, } from '../../core/tui/panel.js';
+import { PrefsPanel } from './panels/prefs-panel.js';
+import { ProfilesPanel } from './panels/profiles-panel.js';
+import { ProviderPanel } from './panels/provider-panel.js';
+/** Rail column width, including its badge gutter. */
+const RAIL_WIDTH = 22;
+/** Below this the rail costs more than it explains; the page falls back to a
+ *  one-line position header and gives every column to the panel. */
+const RAIL_MIN_TOTAL_WIDTH = 84;
+export class SettingsShell {
+    tui;
+    bindings;
+    terminalRows;
+    providers;
+    models;
+    keybindings;
+    brokerLimits;
+    profiles;
+    destinations;
+    index = 0;
+    /** The rail owns the arrow keys until you step into a panel. */
+    railFocused = true;
+    _focused = false;
+    cachedWidth;
+    cachedHeight;
+    cachedLines;
+    onCancel;
+    constructor(tui, agentDir, runtime, registry, bindings, rawKeybindings, terminalRows, rawTmuxPassthrough = undefined, initial) {
+        this.tui = tui;
+        this.bindings = bindings;
+        this.terminalRows = terminalRows;
+        const invalidate = () => this.invalidate();
+        this.providers = new ProviderPanel(tui, agentDir, runtime, registry);
+        this.providers.onChange = invalidate;
+        this.models = new ModelsPanel(tui, runtime, registry, (id, data) => this.matches(id, data), (id) => this.label(id));
+        this.models.onChange = invalidate;
+        this.keybindings = new KeybindingsPanel(bindings, rawKeybindings, rawTmuxPassthrough, terminalRows, invalidate);
+        this.brokerLimits = new BrokerLimitsPanel(invalidate);
+        // Profile purview and pins read against the directory the page was opened
+        // in — the same directory the startup menu was deciding for when `v` brought
+        // the user here.
+        this.profiles = new ProfilesPanel(process.cwd(), invalidate);
+        const prefs = (group, title, subtitle) => new PrefsPanel(group, title, subtitle, invalidate);
+        this.destinations = [
+            {
+                id: "providers",
+                group: "Intelligence",
+                label: "Providers",
+                panel: this.providers,
+            },
+            {
+                id: "models",
+                group: "Intelligence",
+                label: "Models",
+                panel: this.models,
+            },
+            {
+                id: "provider-options",
+                group: "Intelligence",
+                label: "Provider options",
+                panel: prefs("providers", "Provider options", "How a provider serves your turns, once it is authenticated."),
+            },
+            {
+                id: "keybindings",
+                group: "Interface",
+                label: "Keybindings",
+                panel: this.keybindings,
+            },
+            {
+                id: "display",
+                group: "Interface",
+                label: "Display",
+                panel: prefs("display", "Display", "How an attached viewer renders a conversation."),
+            },
+            {
+                id: "profiles",
+                group: "Workspace",
+                label: "Profiles",
+                panel: this.profiles,
+            },
+            {
+                id: "panes",
+                group: "Workspace",
+                label: "Panes",
+                panel: prefs("panes", "Panes", "Where tmux places viewers for the nodes you spawn."),
+            },
+            {
+                id: "broker-limits",
+                group: "Workspace",
+                label: "Broker limits",
+                panel: this.brokerLimits,
+            },
+            {
+                id: "updates",
+                group: "Workspace",
+                label: "Updates",
+                panel: prefs("updates", "Updates", "How crouter checks for and applies new releases."),
+            },
+        ];
+        // A deep link lands ON its destination with the rail already stepped out of:
+        // the caller named where they wanted to be, not where to start navigating
+        // from.
+        if (initial !== undefined) {
+            const at = this.destinations.findIndex((destination) => destination.id === initial);
+            if (at >= 0) {
+                this.index = at;
+                this.railFocused = false;
+            }
+        }
+    }
+    // focus and navigation
+    set focused(value) {
+        this._focused = value;
+        this.syncFocus();
+    }
+    get focused() {
+        return this._focused;
+    }
+    get current() {
+        return this.destinations[this.index];
+    }
+    invalidate() {
+        this.cachedWidth = undefined;
+        this.cachedHeight = undefined;
+        this.cachedLines = undefined;
+    }
+    syncFocus() {
+        const live = this._focused && !this.railFocused;
+        this.keybindings.focused = live && this.current.id === "keybindings";
+        this.brokerLimits.focused = live && this.current.id === "broker-limits";
+    }
+    enterRail() {
+        this.railFocused = true;
+        this.syncFocus();
+        this.invalidate();
+    }
+    enterPanel() {
+        this.railFocused = false;
+        this.syncFocus();
+        this.invalidate();
+    }
+    go(index) {
+        const next = (index + this.destinations.length) % this.destinations.length;
+        if (next === this.index)
+            return;
+        this.index = next;
+        if (this.current.id === "models")
+            this.models.refresh();
+        this.syncFocus();
+        this.invalidate();
+    }
+    matches(id, data) {
+        return matchesPiTuiInput(this.bindings, id, data, (input, gesture) => matchesKey(input, gesture));
+    }
+    label(id) {
+        const gestures = this.bindings.gestures(id);
+        return gestures.length === 0
+            ? "disabled"
+            : formatGesture(gestures[0].split(" > ").pop());
+    }
+    // input
+    /** Panels that have taken over the keyboard — a live text field, a modal, an
+     *  open picker — keep every key including Escape until they release it. */
+    panelOwnsKeyboard(data) {
+        if (this.railFocused)
+            return false;
+        switch (this.current.id) {
+            case "providers":
+                return this.providers.isNestedFlowActive();
+            case "models":
+                return this.models.isPickerOpen();
+            case "keybindings":
+                return this.keybindings.takesPriorityInput;
+            case "profiles":
+                return this.profiles.ownsInput(data);
+            case "broker-limits":
+                // Threshold fields take digits; a remapped destination gesture must
+                // never swallow a number the user is typing into a limit.
+                return /^\d+$/.test(data);
+            default:
+                return false;
+        }
+    }
+    /** `crtr.setup.tab-next`/`-previous` still carry the tab strip's horizontal
+     *  arrows. In the rail layout the horizontal arrows mean "into the panel" and
+     *  "back to the rail", so only the Tab gestures cycle destinations. */
+    cyclesDestination(data) {
+        if (this.matches("crtr.setup.tab-next", data) && !matchesKey(data, "right"))
+            return 1;
+        if (this.matches("crtr.setup.tab-previous", data) &&
+            !matchesKey(data, "left"))
+            return -1;
+        return 0;
+    }
+    handleInput(data) {
+        if (this.panelOwnsKeyboard(data)) {
+            this.routeToPanel(data);
+            return;
+        }
+        // Destination cycling works from either focus, so Tab keeps meaning
+        // "somewhere else in settings" exactly as it did with the old tab strip.
+        const cycle = this.cyclesDestination(data);
+        if (cycle !== 0) {
+            this.go(this.index + cycle);
+            return;
+        }
+        if (this.railFocused) {
+            if (this.matches("crtr.setup.list-down", data))
+                this.go(this.index + 1);
+            else if (this.matches("crtr.setup.list-up", data))
+                this.go(this.index - 1);
+            else if (this.matches("crtr.setup.advance", data) ||
+                this.matches("crtr.setup.cell-next", data) ||
+                matchesKey(data, "right"))
+                this.enterPanel();
+            else if (this.matches("crtr.setup.cancel", data))
+                this.close();
+            else
+                this.jumpToInitial(data);
+            return;
+        }
+        // An unsaved keybinding draft turns every exit into a discard prompt, so
+        // leaving the destination can never silently drop edits.
+        if (this.current.id === "keybindings" &&
+            this.keybindings.dirty &&
+            (this.matches("crtr.setup.cancel", data) ||
+                matchesKey(data, "escape") ||
+                matchesKey(data, "left"))) {
+            this.keybindings.requestDiscard();
+            return;
+        }
+        if (matchesKey(data, "escape") || matchesKey(data, "left")) {
+            this.enterRail();
+            return;
+        }
+        if (this.matches("crtr.setup.cancel", data)) {
+            this.close();
+            return;
+        }
+        this.routeToPanel(data);
+    }
+    /** Typing a letter on the rail jumps to the destination it starts. */
+    jumpToInitial(data) {
+        if (data.length !== 1 || data.charCodeAt(0) < 32)
+            return;
+        const needle = data.toLowerCase();
+        const found = this.destinations.findIndex((destination, offset) => offset !== this.index
+            ? destination.label.toLowerCase().startsWith(needle)
+            : false);
+        if (found >= 0)
+            this.go(found);
+    }
+    routeToPanel(data) {
+        const match = (id, input) => this.matches(id, input);
+        if (this.current.panel.handleInput(data, match))
+            this.invalidate();
+    }
+    close() {
+        this.onCancel?.();
+    }
+    dispose() {
+        this.providers.dispose();
+        this.models.dispose();
+        this.keybindings.focused = false;
+        this.brokerLimits.focused = false;
+    }
+    // rendering
+    renderRail(height) {
+        const out = [];
+        let group;
+        for (const [offset, destination] of this.destinations.entries()) {
+            if (destination.group !== group) {
+                if (group !== undefined)
+                    out.push("");
+                group = destination.group;
+                out.push(theme.fg("dim", ` ${group.toUpperCase()}`));
+            }
+            const badge = destination.panel.badge?.() ?? "";
+            const room = RAIL_WIDTH - 2 - visibleWidth(badge) - 1;
+            const label = truncateToWidth(destination.label, Math.max(1, room));
+            const selected = offset === this.index;
+            const body = ` ${padAnsi(label, Math.max(1, room))} ${badge}`;
+            if (selected && this.railFocused)
+                out.push(theme.bg("selectedBg", padAnsi(body, RAIL_WIDTH)));
+            else if (selected)
+                out.push(`${theme.fg("accent", "\u258c")}${padAnsi(theme.fg("accent", body.slice(1)), RAIL_WIDTH - 1)}`);
+            else
+                out.push(padAnsi(` ${padAnsi(label, Math.max(1, room))} ${theme.fg("dim", badge)}`, RAIL_WIDTH));
+        }
+        // Pad rather than trim: the rail column sets the divider's length, and a
+        // divider that stops halfway makes the page look broken.
+        while (out.length < height)
+            out.push("");
+        return out.slice(0, height);
+    }
+    /** Left hint plus the always-there navigation keys, the hint shedding its
+     *  optional half on a narrow terminal rather than pushing "close" off. */
+    footer(width) {
+        const right = `${this.label("crtr.setup.tab-next")}/${this.label("crtr.setup.tab-previous")} destination \u00b7 ${this.label("crtr.setup.cancel")} close`;
+        const move = `${formatMovePair(this.bindings, "crtr.setup.list-down", "crtr.setup.list-up")} move \u00b7 ${this.label("crtr.setup.advance")} open`;
+        // A panel that has claimed Escape for its own "back" step must not also be
+        // advertised as the way out to the rail — one key, one meaning per screen.
+        const escapes = !this.panelOwnsKeyboard("\u001b");
+        const candidates = this.railFocused
+            ? [`${move} \u00b7 type a letter to jump`, move]
+            : escapes
+                ? [`${this.panelHint()} \u00b7 esc rail`, this.panelHint()]
+                : [this.panelHint()];
+        for (const left of candidates) {
+            const gap = width - visibleWidth(left) - visibleWidth(right);
+            if (gap >= 2)
+                return `${theme.fg("dim", left)}${" ".repeat(gap)}${theme.fg("dim", right)}`;
+        }
+        return theme.fg("dim", truncateToWidth(candidates.at(-1), width));
+    }
+    panelHint() {
+        const move = formatMovePair(this.bindings, "crtr.setup.list-down", "crtr.setup.list-up");
+        switch (this.current.id) {
+            case "providers":
+                return this.providers.isNestedFlowActive()
+                    ? "OAuth in progress \u00b7 esc cancel"
+                    : `${move} select \u00b7 a add \u00b7 p prefer \u00b7 r rename \u00b7 l re-login \u00b7 x remove`;
+            case "models":
+                return this.models.isPickerOpen()
+                    ? this.models.footerHint()
+                    : `${move} row \u00b7 ${this.label("crtr.setup.cell-previous")}/${this.label("crtr.setup.cell-next")} column \u00b7 ${this.label("crtr.setup.models.scope-next")} scope \u00b7 ${this.label("crtr.setup.models.open")} edit`;
+            case "keybindings":
+                return this.keybindings.footerHint();
+            case "broker-limits":
+                return `${move} field \u00b7 type a value \u00b7 ${this.label("crtr.setup.advance")} save`;
+            case "profiles":
+                return this.profiles.footerHint();
+            default:
+                return `${move} row \u00b7 ${this.label("crtr.setup.toggle")} or ${this.label("crtr.setup.cell-previous")}/${this.label("crtr.setup.cell-next")} change value`;
+        }
+    }
+    render(width) {
+        const bypass = (this.current.id === "models" && this.models.isPickerOpen()) ||
+            this.current.id === "providers";
+        const height = this.terminalRows();
+        if (!bypass &&
+            this.cachedLines &&
+            this.cachedWidth === width &&
+            this.cachedHeight === height)
+            return this.cachedLines;
+        const bodyHeight = Math.max(1, height - PAGE_CHROME_ROWS);
+        const useRail = width >= RAIL_MIN_TOTAL_WIDTH;
+        const panelWidth = useRail ? width - RAIL_WIDTH - 3 : width;
+        let body;
+        if (useRail) {
+            const panel = this.current.panel.render(panelWidth, bodyHeight);
+            body = columns(this.renderRail(bodyHeight), RAIL_WIDTH, panel, panelWidth);
+        }
+        else {
+            body = this.current.panel.render(width, bodyHeight);
+        }
+        const lines = pageFrame({
+            width,
+            height,
+            title: "crouter settings",
+            // Without the rail, the title row carries the position instead of the
+            // config path — the page must always say where in settings you are.
+            meta: useRail
+                ? `user \u00b7 ${configPath("user") ?? ""}`
+                : `${this.index + 1}/${this.destinations.length} ${this.current.label}`,
+            body,
+            footer: this.footer(width),
+        });
+        if (!bypass) {
+            this.cachedWidth = width;
+            this.cachedHeight = height;
+            this.cachedLines = lines;
+        }
+        return lines;
+    }
+}
+export async function runSettings(initial) {
+    await reconcileInboxFrontDoor();
+    if (!process.stdout.isTTY) {
+        process.stdout.write("crtr sys settings needs a TTY. Run it in a terminal, or use `crtr sys config get|set` for scriptable access.\n");
+        return;
+    }
+    await runSetupSettingsProcess(({ tui, terminal, agentDir, runtime, registry, bindings, rawUserConfig }, control) => {
+        const shell = new SettingsShell(tui, agentDir, runtime, registry, bindings, rawUserConfig?.keybindings, () => terminal.rows, rawUserConfig?.tmux_passthrough, initial);
+        shell.onCancel = control.cancel;
+        return shell;
+    });
+}

package/dist/commands/sys/settings.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const sysSettingsLeaf: LeafDef;