@north-light/api 0.3.580 → 0.3.587

package/dist/core/model-auth/daemon-login.js

@@ -0,0 +1,156 @@
+// Client side of daemon-run vendor sign-in (runtime spec §7, RT-LLM-24/41/45).
+// The attach viewer's /login, `crtr sys setup`'s Providers panel, the front door,
+// and `crtr sys connect` drive a managed provider's sign-in through
+// `model_auth.start`/`complete` and never run vendor OAuth in their own process.
+// The caller's `ProviderAuthInteraction` (a LoginDialogComponent adapter or the
+// terminal one) only shows the URL/code and collects Anthropic's pasted code.
+import { ApiError } from '../../api/errors.js';
+import { OPENAI_CHATGPT_PROVIDER_ID } from '../managed-providers.js';
+/** A self-host box with a browser on this machine: the vendor's redirect can
+ *  reach the daemon's loopback listener (RT-LLM-41). Over SSH or on a headless
+ *  host the code page / device flow is the only one that works. */
+export function localBrowserAvailable(env = process.env) {
+    if (env['SSH_CONNECTION'] || env['SSH_TTY'])
+        return false;
+    if (process.platform === 'darwin' || process.platform === 'win32')
+        return true;
+    return Boolean(env['DISPLAY'] || env['WAYLAND_DISPLAY']);
+}
+function cancelled(signal) { return signal.aborted; }
+/** Stop waiting on a long-poll the moment the person cancels. */
+function raceAbort(promise, signal) {
+    if (signal.aborted)
+        return Promise.reject(new Error('Login cancelled'));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(new Error('Login cancelled'));
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+    });
+}
+/** A daemon started before `model_auth.start` existed has no such route. */
+function olderDaemon(error) {
+    if (!(error instanceof ApiError) || error.status !== 404 || !/no route for/.test(error.message))
+        return undefined;
+    return new Error('The running crtr daemon predates daemon-run sign-in. Run `crtr sys daemon restart`, then sign in again.');
+}
+async function startFlow(client, request) {
+    try {
+        return await client.startModelAuth(request);
+    }
+    catch (error) {
+        throw olderDaemon(error) ?? error;
+    }
+}
+async function start(client, provider, label, loopback) {
+    // The API name `openai` means Codex (Northlight's vendor page relies on it);
+    // the runtime `openai` provider (ChatGPT) is addressed as `openai-chatgpt`.
+    const request = { provider: provider === OPENAI_CHATGPT_PROVIDER_ID ? 'openai-chatgpt' : provider, ...(label ? { label } : {}) };
+    if (!loopback)
+        return { flow: await startFlow(client, request), loopback: false };
+    try {
+        return { flow: await startFlow(client, { ...request, redirect: 'loopback' }), loopback: true };
+    }
+    catch (error) {
+        // The vendor's loopback port is taken: fall back to the flow that needs none.
+        if (error instanceof ApiError && error.status === 409 && error.param === 'redirect')
+            return { flow: await startFlow(client, request), loopback: false };
+        throw error;
+    }
+}
+/** Wait on the daemon until the flow leaves `pending`; throws unless it connected. */
+async function awaitFlow(client, flowId, signal) {
+    while (!cancelled(signal)) {
+        const flow = await raceAbort(client.getModelAuthFlow(flowId, 25), signal);
+        if (flow.status === 'connected')
+            return;
+        if (flow.status !== 'pending')
+            throw new Error(flow.message ?? `sign-in ${flow.status}`);
+    }
+    throw new Error('Login cancelled');
+}
+/** Sign in to a managed provider through the daemon. Resolves once the daemon
+ *  has written the credential; rejects with `Login cancelled` on abort. */
+export async function daemonManagedLogin(client, provider, interaction, options = {}) {
+    const { flow, loopback } = await start(client, provider, options.label, options.loopback ?? localBrowserAvailable());
+    // Tell the daemon when the person gives up, so its poll or loopback listener
+    // stops and a later browser approval writes nothing.
+    const cancel = () => { void client.cancelModelAuth(flow.flow_id).catch(() => undefined); };
+    if (cancelled(interaction.signal)) {
+        cancel();
+        throw new Error('Login cancelled');
+    }
+    interaction.signal.addEventListener('abort', cancel, { once: true });
+    try {
+        await drive(client, flow, loopback, interaction);
+    }
+    finally {
+        interaction.signal.removeEventListener('abort', cancel);
+    }
+}
+async function drive(client, flow, loopback, interaction) {
+    if (flow.user_code !== undefined) {
+        interaction.notify({ type: 'device_code', userCode: flow.user_code, verificationUri: flow.url, expiresInSeconds: 15 * 60 });
+        await awaitFlow(client, flow.flow_id, interaction.signal);
+        return;
+    }
+    interaction.notify({ type: 'auth_url', url: flow.url, instructions: flow.instructions });
+    const chatgpt = flow.provider === OPENAI_CHATGPT_PROVIDER_ID;
+    if (loopback && !chatgpt) {
+        // Loopback: the vendor redirect lands on the daemon, which finishes by itself.
+        await awaitFlow(client, flow.flow_id, interaction.signal);
+        return;
+    }
+    if (loopback) {
+        // ChatGPT loopback also accepts the pasted redirect URL when the browser's
+        // redirect never reaches this machine; whichever lands first wins.
+        const pasteAbort = new AbortController();
+        const signal = AbortSignal.any([interaction.signal, pasteAbort.signal]);
+        const pasted = pasteRedirect(client, flow, interaction, signal);
+        pasted.catch(() => undefined);
+        try {
+            await Promise.race([awaitFlow(client, flow.flow_id, interaction.signal), pasted]);
+        }
+        finally {
+            pasteAbort.abort();
+        }
+        return;
+    }
+    if (chatgpt) {
+        await pasteRedirect(client, flow, interaction, interaction.signal);
+        return;
+    }
+    // Code page: collect the `code#state` Claude shows; a malformed or mismatched
+    // paste leaves the flow open, so ask again.
+    for (;;) {
+        const input = await interaction.prompt({ type: 'manual_code', message: 'Paste the code Claude shows' });
+        try {
+            await client.completeModelAuth(flow.flow_id, { input });
+            return;
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.status === 400 && (error.param === 'input' || error.param === 'state')) {
+                interaction.notify({ type: 'info', message: `${error.message} — paste it again.` });
+                continue;
+            }
+            throw error;
+        }
+    }
+}
+/** ChatGPT: collect the final redirect URL (http://127.0.0.1:1455/auth/callback?…);
+ *  a malformed or mismatched paste leaves the flow open, so ask again. */
+async function pasteRedirect(client, flow, interaction, signal) {
+    for (;;) {
+        const input = await interaction.prompt({ type: 'manual_code', message: 'Paste the final redirect URL from your browser', placeholder: 'http://127.0.0.1:1455/auth/callback?...', signal });
+        try {
+            await client.completeModelAuth(flow.flow_id, { input });
+            return;
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.status === 400 && (error.param === 'input' || error.param === 'state')) {
+                interaction.notify({ type: 'info', message: `${error.message} — paste it again.` });
+                continue;
+            }
+            throw error;
+        }
+    }
+}

package/dist/core/model-auth/readiness.d.ts

@@ -0,0 +1,12 @@
+import { type ModeDTO, type ModelAuthReadinessDTO } from '../../api/index.js';
+/** A prospective launch: each field absent or null takes the default a root launch would. */
+export interface ProspectiveLaunch {
+    profile?: string | null;
+    cwd?: string | null;
+    pin_cwd?: string | null;
+    kind?: string | null;
+    model?: string | null;
+    mode?: ModeDTO | null;
+}
+/** Resolve `launch` (a root launch when it names no parent) and report its provider's credential state. */
+export declare function modelAuthReadiness(launch: ProspectiveLaunch): Promise<ModelAuthReadinessDTO>;

package/dist/core/model-auth/readiness.js

@@ -0,0 +1,48 @@
+// readiness.ts — whether the provider a prospective node launch would use has a credential the daemon can use.
+// One answer for `GET /v1/model-auth/readiness` and for the model sign-in check at a node birth from an exec.
+import { ApiError } from '../../api/index.js';
+import { storedApiKey } from '../auth-file.js';
+import { PoolCredentialStore } from '../pool-credential-store.js';
+import { resolveLaunchTarget } from '../runtime/launch-target.js';
+import { coolingUntilFor, isManagedProvider, readSubscriptionPool } from '../subscription-state.js';
+function providerFromModel(model) {
+    const slash = model.indexOf('/');
+    const provider = slash > 0 ? model.slice(0, slash) : '';
+    if (provider === '')
+        throw new ApiError(422, 'unresolved_model', 'the selected launch has no concrete model provider');
+    return provider;
+}
+/** Resolve `launch` (a root launch when it names no parent) and report its provider's credential state. */
+export async function modelAuthReadiness(launch) {
+    const target = await resolveLaunchTarget({
+        root: true,
+        ...(launch.profile != null ? { profile: launch.profile } : {}),
+        ...(launch.cwd != null ? { cwd: launch.cwd } : {}),
+        ...(launch.pin_cwd != null ? { pin_cwd: launch.pin_cwd } : {}),
+        ...(launch.mode != null ? { mode: launch.mode } : {}),
+        ...(launch.kind != null ? { kind: launch.kind } : {}),
+        ...(launch.model != null ? { model: launch.model } : {}),
+    }, { readOnlyProfileSelection: true });
+    const model = target.launch.model;
+    if (model === undefined)
+        throw new ApiError(422, 'unresolved_model', 'the selected launch has no concrete model');
+    const provider = providerFromModel(model);
+    if (isManagedProvider(provider)) {
+        const pool = await readSubscriptionPool(provider);
+        if (pool.length > 0) {
+            const usable = pool.filter((account) => account.authFailure === undefined);
+            // A pool with no usable account (all failing auth, or all cooling) does not block a launch with a stored api_key: the model call falls back to it.
+            if (usable.length === 0)
+                return (await storedApiKey(provider)) !== undefined ? { provider, model, credential: 'ready' } : { provider, model, credential: 'unusable', reason: 'invalid_grant' };
+            const now = Date.now();
+            // A model-family cooldown only blocks this launch when the launch model is in that family.
+            const ready = usable.some((account) => coolingUntilFor(account, model) <= now);
+            const nextAvailable = Math.min(...usable.map((account) => coolingUntilFor(account, model)));
+            const cooling = !ready && nextAvailable > now && (await storedApiKey(provider)) === undefined;
+            return { provider, model, credential: 'ready', ...(cooling ? { rate_limited_until: new Date(nextAvailable).toISOString() } : {}) };
+        }
+    }
+    const credential = await new PoolCredentialStore().read(provider);
+    const ready = credential?.type === 'oauth' || (credential?.type === 'api_key' && Boolean(credential.key));
+    return { provider, model, credential: ready ? 'ready' : 'missing' };
+}

package/dist/core/model-routes-pool.d.ts

@@ -0,0 +1,14 @@
+import { type InitialModelRegistryLike, type InitialModelRouteSelection, type ModelRegistryLike, type ModelRequest, type RouteAvailability, type RoutedCandidate } from './model-routes.js';
+/** Probe the common availability facts consumed unchanged by resolveProviderCandidates. Reads the person's credential rows: daemon-side callers only. */
+export declare function probeRouteAvailability(candidate: RoutedCandidate, registry: ModelRegistryLike, now?: number): Promise<RouteAvailability>;
+/** Select the first viable route for a new SDK session. Route declarations own
+ * preference order; logical requests append registered models not declared by a
+ * route. The caller owns broker faults/events and the no-viable outcome. */
+export declare function selectInitialModelRoute<Model extends {
+    provider: string;
+    id: string;
+}>(request: ModelRequest, registry: InitialModelRegistryLike<Model>, options?: {
+    cwd?: string;
+    profileId?: string | null;
+    now?: number;
+}): Promise<InitialModelRouteSelection<Model>>;

package/dist/core/model-routes-pool.js

@@ -0,0 +1,50 @@
+// Route availability that reads the person's credential rows: daemon-side callers only.
+import { isManagedProvider, resolveProviderCandidates } from './managed-providers.js';
+import { readSubscriptionPool } from './subscription-state.js';
+import { expandModelCandidates, routeAvailability } from './model-routes.js';
+/** Probe the common availability facts consumed unchanged by resolveProviderCandidates. Reads the person's credential rows: daemon-side callers only. */
+export async function probeRouteAvailability(candidate, registry, now = Date.now()) {
+    return routeAvailability(candidate, registry, isManagedProvider(candidate.providerId) ? await readSubscriptionPool(candidate.providerId) : undefined, now);
+}
+/** Select the first viable route for a new SDK session. Route declarations own
+ * preference order; logical requests append registered models not declared by a
+ * route. The caller owns broker faults/events and the no-viable outcome. */
+export async function selectInitialModelRoute(request, registry, options = {}) {
+    const routes = await expandModelCandidates(request, options.cwd, options.profileId);
+    const routeKeys = new Set(routes.map((candidate) => `${candidate.providerId}/${candidate.modelId}`));
+    const tail = request.kind === 'logical'
+        ? registry.getAll()
+            .filter((model) => !routeKeys.has(`${model.provider}/${model.id}`))
+            .map((model, index) => ({
+            routeId: `registry:${model.provider}/${model.id}`,
+            credentialSource: 'registry',
+            family: model.provider,
+            strength: 'strong',
+            providerId: model.provider,
+            modelId: model.id,
+            rank: routes.length + index,
+        }))
+        : [];
+    const candidates = [...routes, ...tail];
+    const now = options.now ?? Date.now();
+    const availabilities = new Map();
+    for (const candidate of candidates)
+        availabilities.set(candidate, await probeRouteAvailability(candidate, registry, now));
+    const hasManagedAuthenticated = candidates.some((candidate) => {
+        const availability = availabilities.get(candidate);
+        return isManagedProvider(candidate.providerId) && availability.registered && availability.authenticated;
+    });
+    const selection = resolveProviderCandidates(candidates.map((candidate) => ({
+        ...candidate,
+        ...availabilities.get(candidate),
+        automaticFallback: candidate.routeId.startsWith('registry:')
+            ? (isManagedProvider(candidate.providerId) || !hasManagedAuthenticated)
+            : true,
+    })), now, { pinnedToFirst: request.kind === 'exact' });
+    const candidate = selection.candidates[0];
+    const model = candidate === undefined ? undefined : registry.find(candidate.providerId, candidate.modelId);
+    return {
+        ...(candidate !== undefined && model !== undefined ? { selected: { model, candidate } } : {}),
+        rejected: selection.rejected,
+    };
+}

package/dist/core/model-routes.d.ts

@@ -0,0 +1,98 @@
+import type { ModelStrength } from '../types.js';
+import { type ProviderCandidate, type ProviderCandidateRejection, type SubscriptionCredential } from './managed-providers.js';
+export type ModelRequest = {
+    kind: 'logical';
+    family: string;
+    strength: ModelStrength;
+    spec: string;
+} | {
+    kind: 'concrete';
+    spec: string;
+} | {
+    kind: 'exact';
+    spec: string;
+};
+export type RoutedCandidate = {
+    routeId: string;
+    credentialSource: string;
+    family: string;
+    strength: ModelStrength;
+    providerId: string;
+    modelId: string;
+    thinkingLevel?: string;
+    rank: number;
+    /** Set on a candidate no configured route offers: an exact request, or a concrete request's fallback to its own model. */
+    unrouted?: true;
+};
+export type RouteAvailability = {
+    authenticated: boolean;
+    coolingUntil?: number;
+    registered: boolean;
+};
+export interface ModelRegistryLike {
+    find(providerId: string, modelId: string): unknown;
+    hasConfiguredAuth(model: unknown): boolean;
+}
+export interface InitialModelRegistryLike<Model extends {
+    provider: string;
+    id: string;
+}> {
+    find(providerId: string, modelId: string): Model | undefined;
+    getAll(): Model[];
+    hasConfiguredAuth(model: Model): boolean;
+}
+export interface InitialModelRouteSelection<Model extends {
+    provider: string;
+    id: string;
+}> {
+    selected?: {
+        model: Model;
+        candidate: ProviderCandidate;
+    };
+    rejected: Array<{
+        candidate: ProviderCandidate;
+        reason: ProviderCandidateRejection;
+    }>;
+}
+export interface UnregisteredConcreteModel {
+    request: Extract<ModelRequest, {
+        kind: 'concrete' | 'exact';
+    }>;
+    candidate: RoutedCandidate;
+    reason: 'unregistered';
+}
+/** The route family of an app-paid node's recipe: the intent is `app/<strength>`. */
+export declare const APP_FAMILY = "app";
+export declare function parseModelSpec(spec: string): {
+    providerId: string;
+    modelId: string;
+    thinkingLevel?: string;
+} | undefined;
+type RotationReader = () => Promise<{
+    defaultFallbackStrength?: ModelStrength;
+}>;
+/** The process that owns the person's rows (daemon, API) registers how to read their rotation settings; a broker reads its launch snapshot, and a CLI process has neither and gets the default. */
+export declare function registerRotationReader(reader: RotationReader): void;
+/** Expand config-derived route order only. Availability never affects rank. */
+export declare function expandModelCandidates(request: ModelRequest, cwd?: string, profileId?: string | null): Promise<RoutedCandidate[]>;
+/** Identify the one permanently invalid recipe shape: a concrete/exact request
+ * whose requested provider/model is absent from the serving registry. Auth and
+ * cooldown are deliberately outside this discriminator so callers retain their
+ * existing policy for those transient states. */
+export declare function unregisteredConcreteModel(request: ModelRequest | undefined, registry: ModelRegistryLike, options?: {
+    cwd?: string;
+    profileId?: string | null;
+}): Promise<UnregisteredConcreteModel | undefined>;
+/** A concrete request whose model is registered but offered by no configured route. The daemon serves a turn only
+ * from configured routes, so such a recipe is accepted and then faults every turn with "no eligible model route".
+ * An exact request is served without any route, so it is never unroutable. */
+export declare function unroutableConcreteModel(request: ModelRequest | undefined, options?: {
+    cwd?: string;
+    profileId?: string | null;
+}): Promise<Extract<ModelRequest, {
+    kind: 'concrete';
+}> | undefined>;
+/** The availability facts of one route given the managed pool already read for its provider (undefined for a provider that has no pool). */
+export declare function routeAvailability(candidate: RoutedCandidate, registry: ModelRegistryLike, pool: readonly SubscriptionCredential[] | undefined, now?: number): RouteAvailability;
+export declare function modelRequestFromConfig(model: string | undefined, modelIntent: string | undefined, exact: boolean): ModelRequest | undefined;
+export {};

package/dist/core/model-routes.js

@@ -0,0 +1,190 @@
+import { readMergedLaunchConfig } from './config.js';
+import { brokerConfigSnapshot } from './config.js';
+import { coolingUntilFor, } from './managed-providers.js';
+/** The route family of an app-paid node's recipe: the intent is `app/<strength>`. */
+export const APP_FAMILY = 'app';
+const STRENGTHS = ['ultra', 'strong', 'medium', 'light'];
+const THINKING_SUFFIXES = new Set(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
+export function parseModelSpec(spec) {
+    const slash = spec.indexOf('/');
+    if (slash <= 0 || slash === spec.length - 1)
+        return undefined;
+    const providerId = spec.slice(0, slash);
+    const rawId = spec.slice(slash + 1);
+    const colon = rawId.lastIndexOf(':');
+    const suffix = colon > 0 ? rawId.slice(colon + 1).toLowerCase() : undefined;
+    return {
+        providerId,
+        modelId: suffix !== undefined && THINKING_SUFFIXES.has(suffix) ? rawId.slice(0, colon) : rawId,
+        ...(suffix !== undefined && THINKING_SUFFIXES.has(suffix) && suffix !== 'off' ? { thinkingLevel: suffix } : {}),
+    };
+}
+function synthesizeRoutes(ladders) {
+    const route = (family) => {
+        const providerId = ladders[family].strong.slice(0, ladders[family].strong.indexOf('/'));
+        // `credentialSource` orders routes. Auth and subscription-pool lookup are
+        // provider-wide, keyed by providerId, so this does not select credentials.
+        return { family, credentialSource: 'default', providerId, models: ladders[family] };
+    };
+    return { anthropic: route('anthropic'), openai: route('openai') };
+}
+function ordered(first, rest) {
+    return [first, ...rest.filter((item) => item !== first)];
+}
+function strengths(requested, configured) {
+    return ordered(requested, configured).filter((value, index, all) => all.indexOf(value) === index);
+}
+let rotationReader;
+/** The process that owns the person's rows (daemon, API) registers how to read their rotation settings; a broker reads its launch snapshot, and a CLI process has neither and gets the default. */
+export function registerRotationReader(reader) { rotationReader = reader; }
+async function rotationConfig() {
+    const snapshot = brokerConfigSnapshot();
+    if (snapshot)
+        return snapshot.rotation;
+    // A CLI process owns no rows and has no snapshot: the stored default strength applies there.
+    return rotationReader ? rotationReader() : {};
+}
+/** Expand config-derived route order only. Availability never affects rank. */
+export async function expandModelCandidates(request, cwd, profileId) {
+    if (request.kind === 'exact') {
+        const parsed = parseModelSpec(request.spec);
+        return parsed ? [{ routeId: 'exact', credentialSource: 'exact', family: parsed.providerId, strength: 'strong', ...parsed, rank: 0, unrouted: true }] : [];
+    }
+    // An app-paid node's recipe names the rung's catalog model under the intent `app/<strength>` (RT-RTE-24). That model
+    // is the only candidate: the owner's ladders and routes are never consulted for it, and the daemon's `llm` picks the rung.
+    if (request.kind === 'logical' && request.family === APP_FAMILY) {
+        const parsed = parseModelSpec(request.spec);
+        return parsed ? [{ routeId: APP_FAMILY, credentialSource: APP_FAMILY, family: APP_FAMILY, strength: request.strength, ...parsed, rank: 0 }] : [];
+    }
+    const cfg = readMergedLaunchConfig(cwd, profileId ?? null);
+    // Complete routes are the effective contract. Sparse entries written by an
+    // older crouter release remain readable for one cutover release only.
+    const declaredRoutes = { ...(cfg.modelRoutes ?? {}), ...(cfg.legacyModelRoutes ?? {}) };
+    const routes = Object.keys(declaredRoutes).length > 0 ? declaredRoutes : synthesizeRoutes(cfg.modelLadders);
+    const routeEntries = Object.entries(routes);
+    const fallback = cfg.modelRouting?.strengthFallback ?? [(await rotationConfig()).defaultFallbackStrength ?? 'strong'];
+    const declarationFamilies = routeEntries.map(([, route]) => route.family).filter((value, index, all) => all.indexOf(value) === index);
+    const declarationSources = routeEntries.map(([, route]) => route.credentialSource).filter((value, index, all) => all.indexOf(value) === index);
+    const concrete = request.kind === 'concrete' ? parseModelSpec(request.spec) : undefined;
+    const logical = request.kind === 'logical' ? request : undefined;
+    const matchesConcrete = (spec, exactThinking) => {
+        const parsed = parseModelSpec(spec);
+        return parsed !== undefined
+            && concrete !== undefined
+            && parsed.providerId === concrete.providerId
+            && parsed.modelId === concrete.modelId
+            && (!exactThinking || parsed.thinkingLevel === concrete.thinkingLevel);
+    };
+    const concreteRoute = concrete === undefined ? undefined : routeEntries.find(([, route]) => Object.values(route.models).some((spec) => matchesConcrete(spec, false)));
+    const requestedStrength = logical?.strength ?? (() => {
+        if (!concrete)
+            return 'strong';
+        // Preserve a precise thinking-level match, then map a drifting or omitted
+        // suffix to the weakest same-model cell.
+        for (const exactThinking of [true, false]) {
+            for (const strength of exactThinking ? STRENGTHS : [...STRENGTHS].reverse()) {
+                if (routeEntries.some(([, route]) => {
+                    const spec = route.models[strength];
+                    return spec !== undefined && matchesConcrete(spec, exactThinking);
+                }))
+                    return strength;
+            }
+        }
+        return 'strong';
+    })();
+    const requestedFamily = logical?.family ?? concreteRoute?.[1].family ?? concrete?.providerId ?? 'anthropic';
+    const sourceOrder = concrete ? declarationSources : (cfg.modelRouting?.credentialSourceOrder ?? declarationSources);
+    const familyOrder = concrete ? [requestedFamily] : (cfg.modelRouting?.familyOrder ?? declarationFamilies);
+    const emitted = [];
+    const seen = new Set();
+    const append = (routeId, route, strength, spec, isUnrouted = false) => {
+        const parsed = parseModelSpec(spec);
+        if (!parsed)
+            return;
+        if (concrete && parsed.modelId !== concrete.modelId)
+            return;
+        // Route identity is meaningful: two panel-managed routes can intentionally
+        // share a provider/model while carrying distinct credential-source order.
+        const key = JSON.stringify([routeId, parsed.providerId, parsed.modelId, parsed.thinkingLevel]);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        emitted.push({ routeId, credentialSource: route.credentialSource, family: route.family, strength, ...parsed, rank: emitted.length, ...(isUnrouted ? { unrouted: true } : {}) });
+    };
+    // Concrete requests retain their exact model/provider first even if a route has
+    // not been authored for it; declared routes then offer that identical model in
+    // other credential sources only.
+    if (concrete) {
+        const [routeId, route] = concreteRoute ?? [
+            'concrete',
+            { family: requestedFamily, credentialSource: 'default' },
+        ];
+        append(routeId, route, requestedStrength, request.spec, concreteRoute === undefined);
+    }
+    for (const credentialSource of sourceOrder) {
+        for (const strength of concrete ? [requestedStrength] : strengths(requestedStrength, fallback)) {
+            for (const family of ordered(requestedFamily, familyOrder)) {
+                for (const [routeId, route] of routeEntries) {
+                    if (route.credentialSource !== credentialSource || route.family !== family)
+                        continue;
+                    const spec = route.models[strength];
+                    if (spec)
+                        append(routeId, route, strength, spec);
+                }
+            }
+        }
+    }
+    return emitted.map((candidate, rank) => ({ ...candidate, rank }));
+}
+/** Identify the one permanently invalid recipe shape: a concrete/exact request
+ * whose requested provider/model is absent from the serving registry. Auth and
+ * cooldown are deliberately outside this discriminator so callers retain their
+ * existing policy for those transient states. */
+export async function unregisteredConcreteModel(request, registry, options = {}) {
+    if (request === undefined || request.kind === 'logical')
+        return undefined;
+    const candidate = (await expandModelCandidates(request, options.cwd, options.profileId))[0];
+    if (candidate === undefined || registry.find(candidate.providerId, candidate.modelId) !== undefined)
+        return undefined;
+    return { request, candidate, reason: 'unregistered' };
+}
+/** A concrete request whose model is registered but offered by no configured route. The daemon serves a turn only
+ * from configured routes, so such a recipe is accepted and then faults every turn with "no eligible model route".
+ * An exact request is served without any route, so it is never unroutable. */
+export async function unroutableConcreteModel(request, options = {}) {
+    if (request?.kind !== 'concrete')
+        return undefined;
+    const candidate = (await expandModelCandidates(request, options.cwd, options.profileId))[0];
+    return candidate === undefined || candidate.unrouted ? request : undefined;
+}
+/** The availability facts of one route given the managed pool already read for its provider (undefined for a provider that has no pool). */
+export function routeAvailability(candidate, registry, pool, now = Date.now()) {
+    const model = registry.find(candidate.providerId, candidate.modelId);
+    if (model === undefined)
+        return { registered: false, authenticated: false };
+    if (pool === undefined)
+        return { registered: true, authenticated: registry.hasConfiguredAuth(model) };
+    const usable = pool.filter((entry) => entry.authFailure === undefined);
+    // A model-family cooldown (e.g. an Opus weekly window) only cools this route when it is that family.
+    const cooling = usable.length > 0 && usable.every((entry) => coolingUntilFor(entry, candidate.modelId) > now);
+    return {
+        registered: true,
+        // A populated pool always short-circuits (unaffected by the credential check below).
+        // With an empty pool, a non-pool credential (an api_key row) still authenticates the managed provider.
+        authenticated: usable.length > 0 || registry.hasConfiguredAuth(model),
+        ...(cooling ? { coolingUntil: Math.min(...usable.map((entry) => coolingUntilFor(entry, candidate.modelId))) } : {}),
+    };
+}
+export function modelRequestFromConfig(model, modelIntent, exact) {
+    if (!model)
+        return undefined;
+    if (exact)
+        return { kind: 'exact', spec: model };
+    if (modelIntent) {
+        const slash = modelIntent.lastIndexOf('/');
+        const strength = slash > 0 ? modelIntent.slice(slash + 1) : '';
+        if (STRENGTHS.includes(strength))
+            return { kind: 'logical', family: modelIntent.slice(0, slash), strength: strength, spec: model };
+    }
+    return { kind: 'concrete', spec: model };
+}

package/dist/core/northlight/previews.d.ts

@@ -0,0 +1,22 @@
+import type { BranchDef, BranchRefusal } from '../command.js';
+export interface NorthlightPreview {
+    /** The command name, and the root name the account's real command replaces it under. */
+    name: string;
+    concept: string;
+    /** One line, in the root listing and the help page's description. */
+    description: string;
+    useWhen: string;
+    /** What it does once signed in, 2–3 sentences, filling "Once signed in, …". */
+    doesOnceSignedIn: string;
+    /** `process.platform` values it is listed on; absent means every platform. */
+    platforms?: readonly NodeJS.Platform[];
+}
+export declare const NORTHLIGHT_PREVIEWS: readonly NorthlightPreview[];
+/** The one rendering of a preview's text: its help page (`crtr <name> -h`) and its refusal (any other invocation). */
+export declare function renderPreview(row: NorthlightPreview): {
+    summary: string;
+    model: string;
+    refusal: BranchRefusal;
+};
+/** One refusing branch per row listed on `platform`, skipping any name in `taken` (an installed bundle already provides it). */
+export declare function previewBranches(platform: NodeJS.Platform, taken: ReadonlySet<string>): BranchDef[];