@north-light/api 0.3.580 → 0.3.587

package/dist/commands/sys/update.js

@@ -0,0 +1,157 @@
+import { defineLeaf } from '../../core/command.js';
+import { updateState } from '../../core/config.js';
+import { projectScopeRoot } from '../../core/scope.js';
+import { selfCheck, selfUpdate, contentCheck } from '../../core/self-update.js';
+import { marketUpdate } from '../pkg/market-manage.js';
+import { pluginUpdate } from '../pkg/plugin-manage.js';
+import { nowIso } from '../../core/fs-utils.js';
+import { processLocatedGeneration, readPackageVersion, runtimeManifest, selectedGeneration } from './shared.js';
+export const sysUpdateLeaf = defineLeaf({
+    name: 'update',
+    description: 'update binary and content',
+    whenToUse: 'upgrading crtr or its installed plugins and marketplaces — pull the latest binary, refresh installed content, or both, or just check what is out of date without applying anything.',
+    help: {
+        name: 'sys update',
+        summary: 'update the crtr binary and/or installed plugins and marketplaces',
+        params: [
+            { kind: 'flag', name: 'target', type: 'enum', choices: ['self', 'content', 'all'], required: false, constraint: "What to update. Default: all." },
+            { kind: 'flag', name: 'check', type: 'bool', required: false, constraint: 'Check for updates without applying them (bounded, blocking).' },
+        ],
+        output: [
+            { name: 'target', type: 'string', required: false, constraint: 'Present when applying updates: self | content | all.' },
+            { name: 'status', type: 'string', required: false, constraint: 'done | failed when applying updates.' },
+            { name: 'error', type: 'string', required: false, constraint: 'Failure message when status is failed.' },
+            { name: 'warning', type: 'string', required: false, constraint: 'Present when the update was applied but recording the self-check time failed; status stays done.' },
+            { name: 'updates', type: 'object[]', required: false, constraint: 'Present when --check. Each: {name, current, latest, up_to_date, unreachable, kind}.' },
+            { name: 'up_to_date', type: 'boolean', required: false, constraint: 'Present when --check. True when all items are up to date.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            '--check — read-only, bounded network calls.',
+            'Default (no --check) — launches a background job; returns job handle immediately.',
+            'Content update replaces each marketplace and source-installed plugin checkout with a freshly staged revision, discarding local modifications in those directories.',
+        ],
+    },
+    run: async (input) => {
+        const target = input['target'];
+        const check = input['check'];
+        const resolvedTarget = target !== undefined ? target : 'all';
+        if (check) {
+            // Bounded blocking path: collect check results and return
+            const updates = [];
+            if (resolvedTarget === 'self' || resolvedTarget === 'all') {
+                const r = selfCheck();
+                if (r !== null) {
+                    updates.push({
+                        name: r.package,
+                        kind: 'self',
+                        current: r.current,
+                        latest: r.latest,
+                        // A package switch is always an update, whatever the version numbers say.
+                        up_to_date: !r.migrating && r.current === r.latest,
+                        unreachable: false,
+                    });
+                }
+                else {
+                    updates.push({
+                        name: '@north-light/cli',
+                        kind: 'self',
+                        current: null,
+                        latest: null,
+                        up_to_date: true,
+                        unreachable: true,
+                    });
+                }
+            }
+            if (resolvedTarget === 'content' || resolvedTarget === 'all') {
+                const entries = contentCheck();
+                for (const e of entries) {
+                    updates.push({
+                        name: e.name,
+                        kind: e.kind,
+                        current: e.current,
+                        latest: e.latest,
+                        up_to_date: e.up_to_date,
+                        unreachable: e.unreachable,
+                    });
+                }
+            }
+            const up_to_date = updates.every((u) => u.up_to_date || u.unreachable);
+            return { updates: updates, up_to_date };
+        }
+        // Apply path. Content update owns no refresh logic of its own: it runs the
+        // same replace-in-place leaves as `pkg market update` and `pkg plugin
+        // update`, so every surface refreshes content one way. Marketplaces go
+        // first — one registered with no installed plugin is invisible to the
+        // plugin sweep.
+        const warnings = [];
+        try {
+            if (resolvedTarget === 'self' || resolvedTarget === 'all') {
+                selfUpdate();
+                // The install has landed; the self-check timestamp is bookkeeping. A
+                // store that cannot record it must not turn a finished install into a failure.
+                const scopes = ['user'];
+                if (projectScopeRoot())
+                    scopes.unshift('project');
+                for (const scope of scopes) {
+                    try {
+                        await updateState(scope, (s) => {
+                            s.last_self_check = nowIso();
+                        });
+                    }
+                    catch (e) {
+                        warnings.push(`recording the ${scope}-scope self-check failed: ${e instanceof Error ? e.message : String(e)}`);
+                    }
+                }
+            }
+            if (resolvedTarget === 'content' || resolvedTarget === 'all') {
+                await marketUpdate.run({});
+                await pluginUpdate.run({});
+            }
+            return warnings.length === 0 ? { target: resolvedTarget, status: 'done' } : { target: resolvedTarget, status: 'done', warning: `update installed, but ${warnings.join('; ')}` };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return { target: resolvedTarget, status: 'failed', error: msg };
+        }
+    },
+});
+export const sysVersionLeaf = defineLeaf({
+    name: 'version',
+    description: 'print installed version',
+    whenToUse: 'you need the installed crtr version — to report it in a bug or confirm an upgrade landed.',
+    help: {
+        name: 'sys version',
+        summary: 'report selected and process runtime generations',
+        params: [],
+        output: [
+            { name: 'version', type: 'string', required: true, constraint: 'Version from this process generation manifest; package.json version in a development checkout.' },
+            { name: 'selected_generation', type: 'object', required: true, constraint: 'Selected runtime generation: {id, version, status}; id/version are null when no selection exists.' },
+            { name: 'process_generation', type: 'object', required: true, constraint: 'Generation containing this loaded module: {id, version, status}; id/version are null in a development checkout.' },
+            { name: 'drift', type: 'boolean', required: true, constraint: 'True when selected and process generation ids differ.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (_input) => {
+        const describe = (lookup) => {
+            if (lookup.generation === null)
+                return { id: null, version: null, status: lookup.error ?? 'no runtime generation' };
+            const { id, manifest } = lookup.generation;
+            const shape = runtimeManifest.validateManifestShape(manifest, { id, entryName: 'cli' });
+            return {
+                id,
+                version: typeof manifest.packageVersion === 'string' ? manifest.packageVersion : null,
+                status: shape.ok ? 'valid' : shape.error,
+            };
+        };
+        const selected = describe(selectedGeneration());
+        const process = describe(processLocatedGeneration());
+        return {
+            version: process.version ?? readPackageVersion(),
+            selected_generation: selected,
+            process_generation: process,
+            drift: selected.id !== null && process.id !== null && selected.id !== process.id,
+        };
+    },
+});

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

@@ -0,0 +1,2 @@
+export declare function formatSize(bytes: number | null): string;
+export declare const sysWorktreesLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/sys/worktrees.js

@@ -0,0 +1,53 @@
+import { defineLeaf } from '../../core/command.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+export function formatSize(bytes) {
+    if (bytes === null || !Number.isFinite(bytes) || bytes < 0)
+        return 'unmeasurable';
+    const units = ['B', 'KiB', 'MiB', 'GiB', 'TiB'];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return `${value >= 10 || unit === 0 ? value.toFixed(0) : value.toFixed(1)} ${units[unit]}`;
+}
+export const sysWorktreesLeaf = defineLeaf({
+    name: 'worktrees',
+    description: 'list managed worktrees quarantined by daemon cleanup',
+    whenToUse: 'daemon cleanup has stopped retrying managed worktrees it could not reconcile and you need the recorded refusal, remaining checkout, and disk cost for human intervention',
+    help: {
+        name: 'sys worktrees',
+        summary: 'list managed worktrees the daemon cleanup sweep quarantined',
+        params: [],
+        output: [
+            { name: 'worktrees', type: 'QuarantinedWorktreeDTO[]', required: true, constraint: 'Oldest refusal first. Each record: {node_id, path, branch, repo_root, reason, detail?, attempts, last_attempt, size_bytes}; size_bytes is null when the checkout path is gone or cannot be measured.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async () => {
+        try {
+            return { worktrees: await cliClient().listQuarantinedWorktrees() };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+    render: (result) => {
+        const worktrees = result['worktrees'];
+        if (worktrees.length === 0)
+            return '0 quarantined managed worktrees.';
+        return `${worktrees.length} quarantined managed worktree${worktrees.length === 1 ? '' : 's'}:\n\n${worktrees.map((worktree) => {
+            const details = [
+                `- \`${worktree.node_id}\` — ${worktree.reason} · ${formatSize(worktree.size_bytes)} · ${worktree.attempts} attempt${worktree.attempts === 1 ? '' : 's'} · ${worktree.last_attempt}`,
+                `  - path: \`${worktree.path}\``,
+                `  - branch: \`${worktree.branch}\``,
+                `  - repo root: \`${worktree.repo_root}\``,
+            ];
+            if (worktree.detail !== undefined)
+                details.push(`  - detail: ${worktree.detail}`);
+            return details.join('\n');
+        }).join('\n')}`;
+    },
+});

package/dist/commands/sys.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerSys(): BranchDef;

package/dist/commands/sys.js

@@ -0,0 +1,31 @@
+// `crtr sys` subtree: configuration, diagnostics, and self-management.
+import { defineSysBranch } from './sys/branch.js';
+import { configBranch } from './sys/config.js';
+import { sysEnvBranch } from './sys/env.js';
+import { daemonBranch } from './sys/daemon.js';
+import { sysDoctorLeaf } from './sys/doctor.js';
+import { sysFeedbackLeaf } from './sys/feedback.js';
+import { sysLogsLeaf } from './sys/logs.js';
+import { sysRetryDeliveryLeaf } from './sys/retry-delivery.js';
+import { sysWorktreesLeaf } from './sys/worktrees.js';
+import { sysSpacesLeaf } from './sys/spaces.js';
+import { sysLimitsBranch } from './sys/limits.js';
+import { sysSpendBranch } from './sys/spend.js';
+import { sysSettingsLeaf } from './sys/settings.js';
+import { sysConnectLeaf } from './sys/connect.js';
+import { sysSetupLeaf } from './sys/setup.js';
+import { tutorialBranch } from './sys/tutorial/branch.js';
+import { supportBranch } from './sys/support.js';
+import { contextBranch } from './sys/context.js';
+import { sysSyncBranch } from './sys/sync.js';
+import { sysMigrateLeaf } from './sys/migrate.js';
+import { sysJoinLeaf } from './sys/join.js';
+import { sysDbBranch } from './sys/db.js';
+import { sysImportBranch } from './sys/import/start.js';
+import { sysMachineBranch } from './sys/machine/rotate.js';
+import { sysDesktopBranch } from './sys/desktop.js';
+import { sysSigninLeaf, sysSignoutLeaf } from './sys/signin.js';
+import { sysUpdateLeaf, sysVersionLeaf } from './sys/update.js';
+export function registerSys() {
+    return defineSysBranch([sysSettingsLeaf, configBranch, sysEnvBranch, sysConnectLeaf, sysSetupLeaf, tutorialBranch, sysDoctorLeaf, contextBranch, sysFeedbackLeaf, sysLogsLeaf, sysWorktreesLeaf, sysRetryDeliveryLeaf, sysSpacesLeaf, sysLimitsBranch, sysSpendBranch, supportBranch, sysUpdateLeaf, sysVersionLeaf, sysMigrateLeaf, sysJoinLeaf, sysSyncBranch, sysDbBranch, sysImportBranch, sysMachineBranch, sysSigninLeaf, sysSignoutLeaf, sysDesktopBranch, daemonBranch]);
+}

package/dist/core/activity-signal.d.ts

@@ -0,0 +1,7 @@
+/** One durable-mutation signal file under `crtrHome()/signals/<name>`, shared by
+ *  every subsystem that needs to tell every open viewer "something changed"
+ *  without watching each individual record's directory. */
+export declare function activityPath(name: string): string;
+/** Signal one durable mutation to every open watcher of `name`. */
+export declare function signalActivity(name: string): void;
+export declare function watchActivity(name: string, onChange: () => void): () => void;

package/dist/core/activity-signal.js

@@ -0,0 +1,38 @@
+import { basename, dirname, join } from 'node:path';
+import { mkdirSync, watch, writeFileSync } from 'node:fs';
+import { crtrHome } from './canvas/paths.js';
+/** One durable-mutation signal file under `crtrHome()/signals/<name>`, shared by
+ *  every subsystem that needs to tell every open viewer "something changed"
+ *  without watching each individual record's directory. */
+export function activityPath(name) {
+    return join(crtrHome(), 'signals', name);
+}
+/** Signal one durable mutation to every open watcher of `name`. */
+export function signalActivity(name) {
+    const path = activityPath(name);
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeFileSync(path, `${Date.now()}\n`, { mode: 0o600 });
+    }
+    catch {
+        // A later read of the underlying record is still authoritative.
+    }
+}
+export function watchActivity(name, onChange) {
+    const path = activityPath(name);
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        const watcher = watch(dirname(path), (_event, filename) => {
+            if (String(filename) === basename(path))
+                onChange();
+        });
+        return () => watcher.close();
+    }
+    catch (error) {
+        // The caller keeps a working no-op unwatch — a watch failure must not crash
+        // whatever set it up to be best-effort — but it stays surfaced once, since a
+        // silently-never-refreshing viewer is a real symptom, not a background detail.
+        console.error(`activity-signal: failed to watch "${name}": ${error instanceof Error ? error.message : String(error)}`);
+        return () => { };
+    }
+}

package/dist/core/async-array.d.ts

@@ -0,0 +1,7 @@
+export declare function mapAsync<T, U>(items: readonly T[], fn: (item: T, index: number, items: readonly T[]) => Promise<U>): Promise<U[]>;
+export declare function flatMapAsync<T, U>(items: readonly T[], fn: (item: T, index: number, items: readonly T[]) => Promise<U | readonly U[]>): Promise<U[]>;
+export declare function filterAsync<T>(items: readonly T[], fn: (item: T, index: number, items: readonly T[]) => Promise<unknown>): Promise<T[]>;
+export declare function someAsync<T>(items: readonly T[], fn: (item: T, index: number, items: readonly T[]) => Promise<unknown>): Promise<boolean>;
+export declare function everyAsync<T>(items: readonly T[], fn: (item: T, index: number, items: readonly T[]) => Promise<unknown>): Promise<boolean>;
+export declare function findAsync<T>(items: readonly T[], fn: (item: T, index: number, items: readonly T[]) => Promise<unknown>): Promise<T | undefined>;
+export declare function forEachAsync<T>(items: readonly T[], fn: (item: T, index: number, items: readonly T[]) => Promise<unknown>): Promise<void>;

package/dist/core/async-array.js

@@ -0,0 +1,48 @@
+// Sequential async stand-ins for the Array callbacks whose body now awaits a canvas-db call.
+// Each callback runs to completion before the next starts, as the synchronous loop did.
+export async function mapAsync(items, fn) {
+    const out = [];
+    for (let i = 0; i < items.length; i++)
+        out.push(await fn(items[i], i, items));
+    return out;
+}
+export async function flatMapAsync(items, fn) {
+    const out = [];
+    for (let i = 0; i < items.length; i++) {
+        const r = await fn(items[i], i, items);
+        if (Array.isArray(r))
+            out.push(...r);
+        else
+            out.push(r);
+    }
+    return out;
+}
+export async function filterAsync(items, fn) {
+    const out = [];
+    for (let i = 0; i < items.length; i++)
+        if (await fn(items[i], i, items))
+            out.push(items[i]);
+    return out;
+}
+export async function someAsync(items, fn) {
+    for (let i = 0; i < items.length; i++)
+        if (await fn(items[i], i, items))
+            return true;
+    return false;
+}
+export async function everyAsync(items, fn) {
+    for (let i = 0; i < items.length; i++)
+        if (!(await fn(items[i], i, items)))
+            return false;
+    return true;
+}
+export async function findAsync(items, fn) {
+    for (let i = 0; i < items.length; i++)
+        if (await fn(items[i], i, items))
+            return items[i];
+    return undefined;
+}
+export async function forEachAsync(items, fn) {
+    for (let i = 0; i < items.length; i++)
+        await fn(items[i], i, items);
+}

package/dist/core/auth-file.d.ts

@@ -0,0 +1,35 @@
+import type { Credential, CredentialInfo, CredentialStore } from '@earendil-works/pi-ai';
+type AuthFileData = Record<string, Credential>;
+/**
+ * Resolve a stored api-key value the way pi does before handing it to a provider: a leading
+ * `!` runs the rest as a shell command (cached for the process), and `$VAR` / `${VAR}`
+ * interpolate from the credential's own env then `process.env` (`$$` and `$!` escape a
+ * literal `$`/`!`); an unset reference resolves the whole value to undefined. pi's resolver
+ * is internal to the coding agent and its credential store — which crouter replaces — is the
+ * only place it runs, so an auth.json holding `"key": "$ANTHROPIC_API_KEY"` would otherwise
+ * be sent to the provider verbatim.
+ */
+export declare function resolveCredentialValue(config: string, env?: Record<string, string>): string | undefined;
+/** The api_key a model call can send for `providerId`: the stored row with its `$VAR` / `!cmd` reference resolved. Undefined when no api_key is stored or its reference does not resolve. */
+export declare function storedApiKey(providerId: string): Promise<string | undefined>;
+/** Read all stored credentials. */
+export declare function readAuthCredentials(): Promise<AuthFileData>;
+/** Read one provider's stored credential. */
+export declare function readAuthCredential(providerId: string): Promise<Credential | undefined>;
+/** Persist one provider's credential, leaving every other entry intact. */
+export declare function setAuthCredential(providerId: string, credential: Credential): Promise<void>;
+/** Remove one provider's credential (logout). Returns whether a row was removed. */
+export declare function deleteAuthCredential(providerId: string): Promise<boolean>;
+/**
+ * The `CredentialStore` crouter hands to `ModelRuntime`. Backed directly by the rows rather than
+ * by an in-memory cache, so `modify` is a real cross-process read-modify-write: pi's
+ * OAuth refresh inside `Models.getAuth()` and crouter's own credential writes serialize
+ * against each other on the row lock.
+ */
+export declare class CrouterCredentialStore implements CredentialStore {
+    read(providerId: string): Promise<Credential | undefined>;
+    list(): Promise<readonly CredentialInfo[]>;
+    modify(providerId: string, fn: (current: Credential | undefined) => Promise<Credential | undefined>): Promise<Credential | undefined>;
+    delete(providerId: string): Promise<void>;
+}
+export {};

package/dist/core/auth-file.js

@@ -0,0 +1,161 @@
+// auth-file.ts — crouter's non-managed model credentials: sealed `model_api_keys` rows keyed by person and provider (these were pi's `auth.json`).
+//
+// pi 0.82 removed `AuthStorage` from its public surface: credentials are now an app-owned
+// `CredentialStore` that `ModelRuntime` consumes. crouter needs both halves of that:
+//
+//  - `CrouterCredentialStore` — the auth.json half of the store handed to
+//    `ModelRuntime.create()`. It reads the file fresh under the lock on every call, so a
+//    runtime never serves a cached view that a concurrent broker or viewer has moved past.
+//    Runtimes are actually handed `PoolCredentialStore`, which wraps this one and serves the
+//    managed providers (anthropic, openai-codex, openai) from the subscription pool instead; auth.json
+//    holds a managed record only as a hand-written api_key.
+//  - the `read/set/delete` helpers below — the credential half of transactions
+//    crouter runs itself (the daemon's already-obtained OAuth credential, the Providers panel's
+//    non-managed removal).
+//
+// Writers serialize on the row (`SELECT … FOR UPDATE`), so crouter and every process on the database exclude each other.
+import { execSync } from 'node:child_process';
+import { openDb, withCanvasWrite } from './canvas/db.js';
+import { personIdAsync } from './canvas/person.js';
+import { loadSecretsKey, open, seal } from './secrets/index.js';
+const aadOf = (person, providerId) => `model_api_keys|${person}|${providerId}`;
+function openRow(person, row) { return JSON.parse(open(row.credential_sealed, row.key_id, loadSecretsKey(), aadOf(person, row.provider_id))); }
+async function put(db, person, providerId, credential) {
+    const { sealed, keyId } = seal(JSON.stringify(credential), loadSecretsKey(), aadOf(person, providerId));
+    await db.prepare('INSERT INTO model_api_keys(person,provider_id,credential_sealed,key_id,updated_at) VALUES(?,?,?,?,?) ON CONFLICT(person,provider_id) DO UPDATE SET credential_sealed=EXCLUDED.credential_sealed,key_id=EXCLUDED.key_id,updated_at=EXCLUDED.updated_at').run(person, providerId, sealed, keyId, new Date().toISOString());
+}
+const ENV_NAME_PREFIX = /^[A-Za-z_][A-Za-z0-9_]*/;
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const commandValues = new Map();
+function runValueCommand(command) {
+    if (commandValues.has(command))
+        return commandValues.get(command);
+    let value;
+    try {
+        value = execSync(command, { encoding: 'utf-8', timeout: 10_000, stdio: ['ignore', 'pipe', 'ignore'] }).trim() || undefined;
+    }
+    catch {
+        value = undefined;
+    }
+    commandValues.set(command, value);
+    return value;
+}
+/**
+ * Resolve a stored api-key value the way pi does before handing it to a provider: a leading
+ * `!` runs the rest as a shell command (cached for the process), and `$VAR` / `${VAR}`
+ * interpolate from the credential's own env then `process.env` (`$$` and `$!` escape a
+ * literal `$`/`!`); an unset reference resolves the whole value to undefined. pi's resolver
+ * is internal to the coding agent and its credential store — which crouter replaces — is the
+ * only place it runs, so an auth.json holding `"key": "$ANTHROPIC_API_KEY"` would otherwise
+ * be sent to the provider verbatim.
+ */
+export function resolveCredentialValue(config, env) {
+    if (config.startsWith('!'))
+        return runValueCommand(config.slice(1));
+    let resolved = '';
+    let index = 0;
+    while (index < config.length) {
+        const dollar = config.indexOf('$', index);
+        if (dollar < 0) {
+            resolved += config.slice(index);
+            break;
+        }
+        resolved += config.slice(index, dollar);
+        const next = config[dollar + 1];
+        if (next === '$' || next === '!') {
+            resolved += next;
+            index = dollar + 2;
+            continue;
+        }
+        let name;
+        let end = dollar + 1;
+        if (next === '{') {
+            const close = config.indexOf('}', dollar + 2);
+            const inner = close < 0 ? undefined : config.slice(dollar + 2, close);
+            if (inner !== undefined && ENV_NAME.test(inner)) {
+                name = inner;
+                end = close + 1;
+            }
+        }
+        else {
+            const match = ENV_NAME_PREFIX.exec(config.slice(dollar + 1));
+            if (match !== null) {
+                name = match[0];
+                end = dollar + 1 + name.length;
+            }
+        }
+        if (name === undefined) {
+            // Not an env reference — a literal `$`.
+            resolved += '$';
+            index = dollar + 1;
+            continue;
+        }
+        const value = env?.[name] || process.env[name];
+        if (value === undefined || value === '')
+            return undefined;
+        resolved += value;
+        index = end;
+    }
+    return resolved;
+}
+/** The api_key a model call can send for `providerId`: the stored row with its `$VAR` / `!cmd` reference resolved. Undefined when no api_key is stored or its reference does not resolve. */
+export async function storedApiKey(providerId) {
+    const credential = await new CrouterCredentialStore().read(providerId);
+    return credential?.type === 'api_key' && credential.key ? credential.key : undefined;
+}
+/** Read all stored credentials. */
+export async function readAuthCredentials() {
+    const person = await personIdAsync();
+    const rows = await (await openDb()).prepare('SELECT provider_id,credential_sealed,key_id FROM model_api_keys WHERE person=? ORDER BY provider_id').all(person);
+    return Object.fromEntries(rows.map((row) => [row.provider_id, openRow(person, row)]));
+}
+/** Read one provider's stored credential. */
+export async function readAuthCredential(providerId) {
+    const person = await personIdAsync();
+    const row = await (await openDb()).prepare('SELECT provider_id,credential_sealed,key_id FROM model_api_keys WHERE person=? AND provider_id=?').get(person, providerId);
+    return row ? openRow(person, row) : undefined;
+}
+/** Persist one provider's credential, leaving every other entry intact. */
+export async function setAuthCredential(providerId, credential) {
+    const person = await personIdAsync();
+    await withCanvasWrite((db) => put(db, person, providerId, credential));
+}
+/** Remove one provider's credential (logout). Returns whether a row was removed. */
+export async function deleteAuthCredential(providerId) {
+    const person = await personIdAsync();
+    return (await (await openDb()).prepare('DELETE FROM model_api_keys WHERE person=? AND provider_id=?').run(person, providerId)).changes > 0;
+}
+/**
+ * The `CredentialStore` crouter hands to `ModelRuntime`. Backed directly by the rows rather than
+ * by an in-memory cache, so `modify` is a real cross-process read-modify-write: pi's
+ * OAuth refresh inside `Models.getAuth()` and crouter's own credential writes serialize
+ * against each other on the row lock.
+ */
+export class CrouterCredentialStore {
+    async read(providerId) {
+        const credential = await readAuthCredential(providerId);
+        if (credential?.type !== 'api_key' || credential.key === undefined)
+            return credential;
+        return { ...credential, key: resolveCredentialValue(credential.key, credential.env) };
+    }
+    async list() {
+        return Object.entries(await readAuthCredentials()).map(([providerId, credential]) => ({ providerId, type: credential.type }));
+    }
+    async modify(providerId, fn) {
+        const person = await personIdAsync();
+        return withCanvasWrite(async (db) => {
+            await db.exec(`SET LOCAL lock_timeout = '15s'`);
+            const row = await db.prepare('SELECT provider_id,credential_sealed,key_id FROM model_api_keys WHERE person=? AND provider_id=? FOR UPDATE').get(person, providerId);
+            const current = row ? openRow(person, row) : undefined;
+            const next = await fn(current);
+            // Per the CredentialStore contract, `undefined` leaves the entry unchanged.
+            if (next === undefined)
+                return current;
+            await put(db, person, providerId, next);
+            return next;
+        });
+    }
+    async delete(providerId) {
+        await deleteAuthCredential(providerId);
+    }
+}

package/dist/core/auth-interaction.d.ts

@@ -0,0 +1,19 @@
+import type { ProviderAuthInteraction } from '@earendil-works/pi-ai';
+import type { LoginDialogComponent } from '@earendil-works/pi-coding-agent';
+export type DialogInteractionOptions = {
+    /** Open the verification URL for `auth_url` / `device_code` events. */
+    openBrowser?: (url: string) => void;
+    /** Repaint hook — the login dialog transitions between keystrokes, so a host that
+     *  proxies its render (the setup wizard) must be told to drop its cached lines. */
+    onChange?: () => void;
+    /** False once the flow is dead (superseded, cancelled); events are then dropped. */
+    isActive?: () => boolean;
+};
+/**
+ * Build the `AuthInteraction` for one login flow on `dialog`.
+ *
+ * `select` prompts render as a numbered list through the dialog's normal text input:
+ * the dialog occupies crouter's single inline slot in both surfaces, so swapping in pi's
+ * separate selector component (what pi's own interactive mode does) has nowhere to go.
+ */
+export declare function dialogAuthInteraction(dialog: LoginDialogComponent, options?: DialogInteractionOptions): ProviderAuthInteraction;