@hraness/dawg 0.2.0 → 0.4.0

package/src/auth/openrouter.ts

@@ -0,0 +1,206 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { isValidKey } from "./credentials.ts";
+
+/**
+ * OpenRouter's OAuth PKCE flow for apps
+ * (https://openrouter.ai/docs/use-cases/oauth-pkce): open
+ * `https://openrouter.ai/auth?callback_url=…&code_challenge=…&code_challenge_method=S256`,
+ * receive `?code=` on a localhost callback (any port is allowed), then
+ * exchange it with `POST /api/v1/auth/keys` for a user-controlled key.
+ */
+export const OPENROUTER_AUTH_URL = "https://openrouter.ai/auth";
+export const OPENROUTER_API_URL = "https://openrouter.ai/api/v1";
+export const OPENROUTER_KEYS_URL = "https://openrouter.ai/settings/keys";
+export const OAUTH_TIMEOUT_MS = 5 * 60_000;
+const MAX_EXCHANGE_BYTES = 16 * 1024;
+const CODE_PATTERN = /^[A-Za-z0-9._~-]{8,512}$/;
+
+type Fetcher = (
+  input: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export type Pkce = Readonly<{
+  verifier: string;
+  challenge: string;
+  state: string;
+}>;
+
+function base64url(bytes: Buffer): string {
+  return bytes
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+/** A 43-character verifier, its S256 challenge, and a CSRF state. */
+export function createPkce(
+  random: (size: number) => Buffer = randomBytes,
+): Pkce {
+  const verifier = base64url(random(32));
+  const challenge = base64url(createHash("sha256").update(verifier).digest());
+  return { verifier, challenge, state: base64url(random(16)) };
+}
+
+export function authorizeUrl(
+  callbackUrl: string,
+  pkce: Pkce,
+  base = OPENROUTER_AUTH_URL,
+): string {
+  const url = new URL(base);
+  url.searchParams.set("callback_url", callbackUrl);
+  url.searchParams.set("code_challenge", pkce.challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("key_label", "dawg");
+  url.searchParams.set("state", pkce.state);
+  return url.toString();
+}
+
+function sameSecret(a: string, b: string): boolean {
+  const left = Buffer.from(a);
+  const right = Buffer.from(b);
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+const PAGE = (title: string, body: string) =>
+  `<!doctype html><meta charset="utf-8"><title>${title}</title><body style="font:16px system-ui;margin:3rem;max-width:32rem"><h1 style="font-size:1.4rem">${title}</h1><p>${body}</p></body>`;
+
+export type CallbackServer = Readonly<{
+  /** `http://127.0.0.1:<port>/callback`. */
+  url: string;
+  /** Resolves with the code once a request carries the right state. */
+  code: Promise<string>;
+  stop(): void;
+}>;
+
+/**
+ * A one-shot callback listener on 127.0.0.1 and an ephemeral port. Requests
+ * with a missing or wrong `state` are refused and do not end the wait.
+ */
+export function startCallbackServer(
+  state: string,
+  options: { signal?: AbortSignal; timeoutMs?: number } = {},
+): CallbackServer {
+  let settle: { resolve(code: string): void; reject(error: Error): void };
+  const code = new Promise<string>((resolve, reject) => {
+    settle = { resolve, reject };
+  });
+  code.catch(() => undefined);
+  const server = Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0,
+    fetch(request) {
+      const url = new URL(request.url);
+      if (url.pathname !== "/callback")
+        return new Response("not found", { status: 404 });
+      const html = (status: number, title: string, body: string) =>
+        new Response(PAGE(title, body), {
+          status,
+          headers: {
+            "content-type": "text/html; charset=utf-8",
+            "cache-control": "no-store",
+            "referrer-policy": "no-referrer",
+          },
+        });
+      const got = url.searchParams.get("state") ?? "";
+      const value = url.searchParams.get("code") ?? "";
+      if (!sameSecret(got, state))
+        return html(
+          400,
+          "Sign-in not recognized",
+          "This link does not match the sign-in dawg started. Return to the terminal and try again.",
+        );
+      if (!CODE_PATTERN.test(value)) {
+        settle.reject(
+          new Error("OpenRouter did not return a code (access denied?)"),
+        );
+        return html(
+          400,
+          "Sign-in cancelled",
+          "No authorization code came back. You can close this tab.",
+        );
+      }
+      settle.resolve(value);
+      return html(
+        200,
+        "dawg is connected to OpenRouter",
+        "You can close this tab and return to the terminal.",
+      );
+    },
+  });
+  const timer = setTimeout(
+    () => settle.reject(new Error("timed out waiting for the browser")),
+    options.timeoutMs ?? OAUTH_TIMEOUT_MS,
+  );
+  const onAbort = () => settle.reject(new Error("sign-in cancelled"));
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  const stop = () => {
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", onAbort);
+    // Graceful first so the browser still gets the "connected" page, then
+    // force-close any idle keep-alive sockets.
+    void server.stop(false);
+    setTimeout(() => void server.stop(true), 1_000).unref?.();
+  };
+  void code.then(stop, stop);
+  return { url: `http://127.0.0.1:${server.port}/callback`, code, stop };
+}
+
+/** `POST /api/v1/auth/keys` → the user's new key. */
+export async function exchangeCode(
+  code: string,
+  pkce: Pick<Pkce, "verifier">,
+  options: { fetcher?: Fetcher; baseUrl?: string } = {},
+): Promise<string> {
+  const fetcher = options.fetcher ?? fetch;
+  const base = (options.baseUrl ?? OPENROUTER_API_URL).replace(/\/$/, "");
+  const response = await fetcher(`${base}/auth/keys`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      code,
+      code_verifier: pkce.verifier,
+      code_challenge_method: "S256",
+    }),
+    signal: AbortSignal.timeout(20_000),
+  });
+  const text = (await response.text()).slice(0, MAX_EXCHANGE_BYTES);
+  if (!response.ok)
+    throw new Error(
+      response.status === 403
+        ? "OpenRouter refused the code (expired or already used)"
+        : `OpenRouter key exchange failed (${response.status})`,
+    );
+  let key: unknown;
+  try {
+    key = (JSON.parse(text) as { key?: unknown }).key;
+  } catch {
+    key = undefined;
+  }
+  if (!isValidKey(key)) throw new Error("OpenRouter returned no usable key");
+  return key;
+}
+
+export type KeyCheck = "valid" | "rejected" | "unverified";
+
+/** `GET /api/v1/key`: cheap, authenticated, and spends nothing. */
+export async function checkOpenRouterKey(
+  key: string,
+  options: { fetcher?: Fetcher; baseUrl?: string } = {},
+): Promise<KeyCheck> {
+  const fetcher = options.fetcher ?? fetch;
+  const base = (options.baseUrl ?? OPENROUTER_API_URL).replace(/\/$/, "");
+  try {
+    const response = await fetcher(`${base}/key`, {
+      headers: { authorization: `Bearer ${key}` },
+      signal: AbortSignal.timeout(8_000),
+    });
+    await response.body?.cancel().catch(() => undefined);
+    if (response.ok) return "valid";
+    if (response.status === 401 || response.status === 403) return "rejected";
+    return "unverified";
+  } catch {
+    return "unverified";
+  }
+}

package/src/auth/picker.ts

@@ -0,0 +1,282 @@
+import { stdin, stdout } from "node:process";
+
+/**
+ * A small inline picker for the shell (`dawg login`, `dawg model`), in the
+ * style of the Codex CLI sign-in: ↑/↓ or j/k move, Enter chooses, 1-9 jump
+ * and choose, typing filters (when enabled), Esc or Ctrl-C cancels. It draws
+ * below the cursor and erases itself afterwards, so the scrollback keeps only
+ * the one-line result the caller prints.
+ */
+export type ChoiceItem = Readonly<{
+  label: string;
+  /** Right-hand muted text: a status, a price. */
+  detail?: string;
+  /** Section heading shown above the first row of each group. */
+  group?: string;
+  /** Rows that cannot be chosen still show (e.g. "not set up"). */
+  disabled?: boolean;
+  /** Marked with ● (the current model). */
+  current?: boolean;
+}>;
+
+export type ChooseOptions = Readonly<{
+  initial?: number;
+  /** Type-to-filter on label and detail. */
+  filter?: boolean;
+  /** Footer hint override. */
+  hint?: string;
+}>;
+
+export type PickerKey =
+  | { type: "up" }
+  | { type: "down" }
+  | { type: "enter" }
+  | { type: "cancel" }
+  | { type: "digit"; value: number }
+  | { type: "backspace" }
+  | { type: "text"; text: string };
+
+/** Split one raw stdin read into picker keys. */
+export function parsePickerKeys(data: string): PickerKey[] {
+  const keys: PickerKey[] = [];
+  let rest = data.replace(/\u001b\[20[01]~/g, "");
+  while (rest.length > 0) {
+    if (rest.startsWith("\u001b[A") || rest.startsWith("\u001bOA")) {
+      keys.push({ type: "up" });
+      rest = rest.slice(3);
+    } else if (rest.startsWith("\u001b[B") || rest.startsWith("\u001bOB")) {
+      keys.push({ type: "down" });
+      rest = rest.slice(3);
+    } else if (rest.startsWith("\u001b[")) {
+      // Other CSI sequences (left/right, home, …) are ignored.
+      const match = /^\u001b\[[0-9;]*[A-Za-z~]/.exec(rest);
+      rest = rest.slice(match ? match[0].length : 2);
+    } else {
+      const char = rest[0]!;
+      rest = rest.slice(1);
+      if (char === "\r" || char === "\n") keys.push({ type: "enter" });
+      else if (char === "\u001b" || char === "\u0003")
+        keys.push({ type: "cancel" });
+      else if (char === "\u007f" || char === "\b")
+        keys.push({ type: "backspace" });
+      else if (char === "\u0010") keys.push({ type: "up" });
+      else if (char === "\u000e") keys.push({ type: "down" });
+      else if (char >= " ") keys.push({ type: "text", text: char });
+    }
+  }
+  return keys;
+}
+
+/** The picker's pure state; `step` applies one key. */
+export class PickerModel {
+  index: number;
+  query = "";
+  constructor(
+    readonly items: readonly ChoiceItem[],
+    readonly options: ChooseOptions = {},
+  ) {
+    const visible = this.visible();
+    const initial = options.initial ?? 0;
+    const start = visible.indexOf(initial) >= 0 ? initial : (visible[0] ?? 0);
+    this.index = start;
+  }
+
+  /** Indices of rows matching the filter, in order. */
+  visible(): number[] {
+    const query = this.query.toLowerCase();
+    return this.items
+      .map((item, index) => ({ item, index }))
+      .filter(
+        ({ item }) =>
+          !query ||
+          item.label.toLowerCase().includes(query) ||
+          (item.detail ?? "").toLowerCase().includes(query) ||
+          (item.group ?? "").toLowerCase().includes(query),
+      )
+      .map(({ index }) => index);
+  }
+
+  /** `undefined` while picking, a row index when chosen, `null` on cancel. */
+  step(key: PickerKey): number | null | undefined {
+    const visible = this.visible();
+    const position = Math.max(0, visible.indexOf(this.index));
+    const move = (delta: number) => {
+      if (visible.length === 0) return;
+      for (let offset = 1; offset <= visible.length; offset += 1) {
+        const n = visible.length;
+        const next = visible[(((position + delta * offset) % n) + n) % n]!;
+        if (!this.items[next]?.disabled) {
+          this.index = next;
+          return;
+        }
+      }
+    };
+    switch (key.type) {
+      case "up":
+        move(-1);
+        return undefined;
+      case "down":
+        move(1);
+        return undefined;
+      case "enter":
+        return visible.includes(this.index) && !this.items[this.index]?.disabled
+          ? this.index
+          : undefined;
+      case "cancel":
+        if (this.query) {
+          this.query = "";
+          this.refocus();
+          return undefined;
+        }
+        return null;
+      case "backspace":
+        this.query = this.query.slice(0, -1);
+        this.refocus();
+        return undefined;
+      case "digit": {
+        const target = visible[key.value - 1];
+        if (target !== undefined && !this.items[target]?.disabled)
+          return target;
+        return undefined;
+      }
+      case "text":
+        if (/^[1-9]$/.test(key.text) && !this.query)
+          return this.step({ type: "digit", value: Number(key.text) });
+        if (!this.options.filter) {
+          if (key.text === "k") move(-1);
+          if (key.text === "j") move(1);
+          return undefined;
+        }
+        if (this.query.length < 40) this.query += key.text;
+        this.refocus();
+        return undefined;
+    }
+  }
+
+  private refocus(): void {
+    const visible = this.visible().filter(
+      (index) => !this.items[index]?.disabled,
+    );
+    if (!visible.includes(this.index) && visible.length > 0)
+      this.index = visible[0]!;
+  }
+
+  /** Plain lines (no colour); the renderer styles them. */
+  lines(
+    title: string,
+    maxRows = 14,
+  ): {
+    text: string;
+    kind: "title" | "group" | "row" | "selected" | "muted" | "hint";
+  }[] {
+    const out: {
+      text: string;
+      kind: "title" | "group" | "row" | "selected" | "muted" | "hint";
+    }[] = [
+      {
+        text: title + (this.query ? `  filter: ${this.query}` : ""),
+        kind: "title",
+      },
+    ];
+    const visible = this.visible();
+    if (visible.length === 0) out.push({ text: "  no matches", kind: "muted" });
+    const position = Math.max(0, visible.indexOf(this.index));
+    const first = Math.max(
+      0,
+      Math.min(visible.length - maxRows, position - Math.floor(maxRows / 2)),
+    );
+    let lastGroup: string | undefined;
+    visible.slice(first, first + maxRows).forEach((index, offset) => {
+      const item = this.items[index]!;
+      if (item.group && item.group !== lastGroup) {
+        out.push({ text: `  ${item.group}`, kind: "group" });
+      }
+      lastGroup = item.group;
+      const selected = index === this.index;
+      const number =
+        first + offset < 9 && !this.query ? `${first + offset + 1}.` : "  ";
+      const mark = item.current ? "●" : " ";
+      out.push({
+        text: `${selected ? "›" : " "} ${number} ${mark} ${item.label}${item.detail ? `  ${item.detail}` : ""}`,
+        kind: selected ? "selected" : item.disabled ? "muted" : "row",
+      });
+    });
+    out.push({
+      text:
+        this.options.hint ??
+        `  ↑/↓ move · enter choose · 1-9 pick${this.options.filter ? " · type to filter" : ""} · esc cancel`,
+      kind: "hint",
+    });
+    return out;
+  }
+}
+
+const ESC = "\u001b[";
+
+function style(kind: string, text: string, color: boolean): string {
+  if (!color) return text;
+  if (kind === "title") return `${ESC}1m${text}${ESC}0m`;
+  if (kind === "selected") return `${ESC}1;36m${text}${ESC}0m`;
+  if (kind === "group") return `${ESC}2;4m${text}${ESC}0m`;
+  if (kind === "muted" || kind === "hint") return `${ESC}2m${text}${ESC}0m`;
+  return text;
+}
+
+/**
+ * Run a picker on the real terminal. Resolves the chosen index, or
+ * `undefined` on Esc / Ctrl-C. Requires a TTY on stdin and stdout.
+ */
+export function chooseOnTerminal(
+  title: string,
+  items: readonly ChoiceItem[],
+  options: ChooseOptions = {},
+): Promise<number | undefined> {
+  const model = new PickerModel(items, options);
+  const color = !process.env.NO_COLOR && process.env.TERM !== "dumb";
+  const width = () => Math.max(20, (stdout.columns ?? 80) - 1);
+  let drawn = 0;
+  const draw = () => {
+    const lines = model.lines(
+      title,
+      Math.max(4, Math.min(14, (stdout.rows ?? 24) - 6)),
+    );
+    let out = drawn > 0 ? `\r${ESC}${drawn - 1}A` : "\r";
+    out += `${ESC}J`;
+    out += lines
+      .map((line) => style(line.kind, truncate(line.text, width()), color))
+      .join("\r\n");
+    drawn = lines.length;
+    stdout.write(`${ESC}?25l${out}`);
+  };
+  const erase = () => {
+    if (drawn > 0) stdout.write(`\r${ESC}${drawn - 1}A${ESC}J`);
+    stdout.write(`${ESC}?25h`);
+  };
+  return new Promise((resolve) => {
+    const wasRaw = stdin.isRaw;
+    stdin.setRawMode?.(true);
+    stdin.resume();
+    const finish = (result: number | undefined) => {
+      stdin.off("data", onData);
+      stdin.setRawMode?.(wasRaw);
+      stdin.pause();
+      erase();
+      resolve(result);
+    };
+    const onData = (chunk: Buffer) => {
+      for (const key of parsePickerKeys(chunk.toString("utf8"))) {
+        const result = model.step(key);
+        if (result === null) return finish(undefined);
+        if (result !== undefined) return finish(result);
+      }
+      draw();
+    };
+    stdin.on("data", onData);
+    draw();
+  });
+}
+
+function truncate(text: string, width: number): string {
+  const chars = [...text];
+  return chars.length > width ? `${chars.slice(0, width - 1).join("")}…` : text;
+}

package/src/auth/runner.ts

@@ -14,6 +14,11 @@ export type RunOptions = Readonly<{
   /** Bound on captured stdout/stderr; excess is dropped. */
   maxOutputBytes?: number;
   env?: Readonly<Record<string, string | undefined>>;
+  /**
+   * Called with each decoded chunk as it arrives (progress parsing). Chunks
+   * keep flowing past `maxOutputBytes`; only the captured text is bounded.
+   */
+  onOutput?: (stream: "stdout" | "stderr", chunk: string) => void;
 }>;
 
 export type RunResult = Readonly<{
@@ -73,9 +78,18 @@ export const systemRunner: CommandRunner = {
           // The child may exit before reading its input; its exit code reports why.
         }
       }
+      const tap = options.onOutput;
       const [stdout, stderr, code] = await Promise.all([
-        readBounded(child.stdout, maxBytes),
-        readBounded(child.stderr, maxBytes),
+        readBounded(
+          child.stdout,
+          maxBytes,
+          tap && ((chunk) => tap("stdout", chunk)),
+        ),
+        readBounded(
+          child.stderr,
+          maxBytes,
+          tap && ((chunk) => tap("stderr", chunk)),
+        ),
         child.exited,
       ]);
       return { code, stdout, stderr, killed: stop.killed() };
@@ -127,12 +141,21 @@ function watchKill(
 async function readBounded(
   stream: ReadableStream<Uint8Array> | undefined | null,
   maxBytes: number,
+  tap?: (chunk: string) => void,
 ): Promise<string> {
   if (!stream) return "";
   const decoder = new TextDecoder();
+  const tapDecoder = tap ? new TextDecoder() : undefined;
   let text = "";
   let bytes = 0;
   for await (const chunk of stream) {
+    if (tap && tapDecoder) {
+      try {
+        tap(tapDecoder.decode(chunk, { stream: true }));
+      } catch {
+        // A progress parser must never stop the drain.
+      }
+    }
     if (bytes >= maxBytes) continue; // Keep draining so the child never blocks.
     const room = maxBytes - bytes;
     const part = chunk.byteLength > room ? chunk.subarray(0, room) : chunk;

package/src/auth/tui.ts

@@ -2,23 +2,28 @@ import { hostname } from "node:os";
 import { defaultAuthEnv } from "./credentials.ts";
 import {
   authStatus,
-  listXcbChoices,
-  login,
+  isLogoutTarget,
   logout,
+  modelChoices,
+  saveModelChoice,
   type LoginIO,
 } from "./login.ts";
 import { systemRunner, type CommandRunner } from "./runner.ts";
-import type { GatewayModel } from "../agent/gateway.ts";
 import { audioStatusLine } from "../audio/engine.ts";
+import {
+  providerLabel,
+  selectProvider,
+  type ProviderSelection,
+} from "../agent/provider.ts";
+import { parseLoginArgs } from "./cli.ts";
 
 /**
- * `/login [--xcb]`, `/logout` and `/auth` inside the TUI. The terminal is in
- * raw mode, so there is no hidden input or `vercel login` handoff here: those
- * flows tell the user to run `dawg login` in a shell instead.
+ * `/logout [provider]` and `/auth [--check]` inside the TUI: they print only,
+ * so they run without leaving the screen and return their lines as cards.
+ * `/login` hands the terminal to the shell flow instead (see main.ts).
  */
 export async function tuiAuthCommand(
   command: string,
-  gatewayModel: GatewayModel,
   runner: CommandRunner = systemRunner,
 ): Promise<string[]> {
   const lines: string[] = [];
@@ -31,60 +36,72 @@ export async function tuiAuthCommand(
   const deps = { auth: defaultAuthEnv(runner), io, hostname: hostname() };
   const [name, ...rest] = command.trim().split(/\s+/);
   try {
-    if (/^\/logout$/i.test(name ?? "")) await logout(deps);
-    else if (/^\/auth$/i.test(name ?? ""))
+    if (/^\/logout$/i.test(name ?? "")) {
+      const target = rest[0];
+      if (target !== undefined && !isLogoutTarget(target))
+        lines.push("usage · /logout [gateway|openrouter|codex|claude|xcb]");
+      else await logout(deps, target);
+    } else if (/^\/auth$/i.test(name ?? ""))
       lines.push(
         ...(await authStatus(deps, {
           verify: rest.includes("--check"),
-          gatewayModel,
         })),
         audioStatusLine(),
       );
-    else if (rest.includes("--xcb")) {
-      const account = flagValue(rest, "--account");
-      const model = flagValue(rest, "--model");
-      await login(
-        "xcb",
-        deps,
-        account && model ? { xcb: { account, model } } : {},
-      );
-    } else if (rest.includes("--key"))
-      lines.push(
-        "Paste a key from a shell: `dawg login --key` (input is hidden there).",
-      );
-    else await login("gateway", deps);
+    else lines.push(`unknown auth command: ${(name ?? "").slice(0, 20)}`);
   } catch (error) {
     lines.push(
-      `auth failed: ${error instanceof Error ? error.message : String(error)}`,
+      `auth failed · ${error instanceof Error ? error.message : String(error)} · dawg login in a shell`,
     );
   }
   return lines.map((line) => line.slice(0, 240));
 }
 
-function flagValue(args: readonly string[], flag: string): string | undefined {
-  const index = args.indexOf(flag);
-  const value = index >= 0 ? args[index + 1] : undefined;
-  return value && !value.startsWith("--") ? value : undefined;
+/** Validate `/login …` arguments before suspending the screen. */
+export function tuiLoginArgs(command: string) {
+  return parseLoginArgs(command.trim().split(/\s+/).slice(1));
 }
 
-export type XcbPickerItem = Readonly<{ label: string; value: string }>;
+export type ModelPickerItem = Readonly<{
+  label: string;
+  value: string;
+  detail: string;
+  current: boolean;
+}>;
 
 /**
- * Picker rows for `/login --xcb`: one per usable account and model, valued as
- * the follow-up command that saves it. Undefined when xcb is missing or
- * unreadable (the plain login path then prints the guidance).
+ * `/model` picker rows for the active provider, valued as the follow-up
+ * `/model <id>` command that saves the choice.
  */
-export async function xcbPickerItems(
+export async function modelPickerItems(
+  selection: ProviderSelection,
   runner: CommandRunner = systemRunner,
-): Promise<XcbPickerItem[] | undefined> {
-  const choices = await listXcbChoices(defaultAuthEnv(runner));
-  return choices?.map(({ account, model }) => ({
-    label: [
-      account.label,
-      account.provider,
-      model.label === model.key ? model.key : `${model.label} (${model.key})`,
-      ...(account.admission === "pending" ? ["admits on first use"] : []),
-    ].join(" · "),
-    value: `/login --xcb --account ${account.id} --model ${model.key}`,
+): Promise<ModelPickerItem[]> {
+  const rows = await modelChoices({ auth: defaultAuthEnv(runner) }, selection);
+  return rows.map((row) => ({
+    label: row.label,
+    detail: `${row.group} · ${row.detail}`,
+    current: row.current,
+    value: `/model ${row.value}`,
   }));
 }
+
+/** `/model <value>`: save for the active provider; returns the receipt. */
+export async function tuiSetModel(
+  value: string,
+  runner: CommandRunner = systemRunner,
+): Promise<string> {
+  const auth = defaultAuthEnv(runner);
+  const selection = await selectProvider(auth);
+  if (selection.kind === "offline")
+    return `model · unavailable: ${selection.reason}`;
+  try {
+    return `model · ${await saveModelChoice(auth, selection, value)}`;
+  } catch (error) {
+    const rows = await modelPickerItems(selection, runner).catch(() => []);
+    return `model · ${error instanceof Error ? error.message : String(error)}; try ${rows
+      .slice(0, 8)
+      .map((row) => row.label)
+      .join(", ")} · current ${providerLabel(selection)}`;
+  }
+}