@100xprompt/brain 0.0.0-stage → 0.1.1

package/src/gateway/connectors/vscode-copilot.ts

@@ -0,0 +1,286 @@
+// Gateway connector for GitHub Copilot Chat in VS Code (checked 2026-11-10 against VS Code 1.144.0 and the Copilot Chat
+// extension 0.72.0 built into it: /Applications/Visual Studio Code.app/Contents/Resources/app/extensions/copilot).
+//
+// Bring-your-own-key models live in the VS Code user folder, in chatLanguageModels.json (out/vs/workbench/
+// workbench.desktop.main.js: profile `languageModelsResource` = <User>/chatLanguageModels.json, a JSON array of provider
+// groups `{ name, vendor, ...settings }` that VS Code watches and parses as JSON with comments). The Copilot extension's
+// "Custom Endpoint" provider (vendor `customendpoint`, package.json contributes.languageModelChatProviders; in Stable since
+// VS Code 1.122, https://code.visualstudio.com/updates/v1_122) takes per model an `id`, `name`, `url`, `apiType`
+// (chat-completions | responses | messages) and `requestHeaders`.
+//
+// The key. A group's `apiKey` is a secret: VS Code keeps only `${input:chat.lm.secret.<n>}` in the file and the value in
+// its secret storage (workbench: _resolveConfiguration / _resolveLanguageModelProviderGroup), which brain cannot write.
+// But the Custom Endpoint provider lets a model's `requestHeaders` carry the authorization itself: dist/extension.js class
+// for `CustomEndpoint` endpoints overrides _isReservedHeader so `authorization` and `api-key` are allowed
+// (_overridableReservedAuthHeaders), and skips its own `Authorization: Bearer <apiKey>` when the model sets one
+// (_userAuthHeaderSuppressionSet). So brain adds one group, "100xprompt gateway", with no apiKey and a model whose
+// requestHeaders hold `Authorization: Bearer <key>` (and `x-100x-context-edit: on`): the key is copied into the file, which
+// is made private (0600). chatLanguageModels.json is not part of Settings Sync (sync resources: settings, keybindings,
+// snippets, prompts, tasks, extensions, globalState, profiles, mcp), so the copy stays on this machine.
+//
+// What brain does not set: the model picked in Copilot Chat. VS Code remembers that in its own storage; the
+// `chat.defaultModel` setting matches models by their id alone (workbench: function resolving it compares metadata.id),
+// and the gateway's model id (gemini-3.8-flash) could equally name a model Copilot serves itself, so the person picks
+// "100xprompt Pro" in the model picker once (the notes say so). The model list is given in the file, so the gateway's
+// /v1/models (403) is never asked (CustomEndpoint.getAllModels reads `models` unless the group has a `url`).
+//
+// Only the default VS Code profile and VS Code Stable ("Code") are handled; Insiders, VSCodium and other profiles keep
+// their own User folders.
+import { join, resolve } from "node:path"
+import { type Codec, type Connector, EDIT_HEADER, type Env, type Json, modelName, readKey, routeUrl } from "../common.ts"
+
+const GROUP = "100xprompt gateway"
+const VENDOR = "customendpoint"
+/** Gemini 3.x Flash, which the gateway's models are: a 1M-token window, 64K out. */
+const MAX_OUTPUT = 65_536
+const MAX_INPUT = 1_048_576 - MAX_OUTPUT
+
+/** VS Code's user folder: ~/Library/Application Support/Code/User on macOS, $XDG_CONFIG_HOME/Code/User or ~/.config/Code/User elsewhere. */
+export function vscodeUserDir(home: string, env: Env, platform: string = process.platform): string {
+  if (platform === "darwin") return join(home, "Library", "Application Support", "Code", "User")
+  if (platform === "win32") return join(env.APPDATA ?? join(home, "AppData", "Roaming"), "Code", "User")
+  // XDG_CONFIG_HOME describes the real home: followed only when brain works in that home.
+  const xdg = env.XDG_CONFIG_HOME?.startsWith("/") && env.HOME && resolve(home) === resolve(env.HOME) ? env.XDG_CONFIG_HOME : join(home, ".config")
+  return join(xdg, "Code", "User")
+}
+
+// ---- JSON with comments, with the position of every value -------------------------------------------------------------
+
+type Node =
+  | { kind: "object"; start: number; end: number; members: Array<{ key: string; value: Node }> }
+  | { kind: "array"; start: number; end: number; items: Node[] }
+  | { kind: "scalar"; start: number; end: number; value: unknown }
+
+/** Parses JSON with // and /* comments and trailing commas (what VS Code accepts in its JSON files); throws otherwise. */
+export function parseJsonc(text: string): Node | undefined {
+  let i = 0
+  const fail = (what: string): never => {
+    throw new Error(`${what} at offset ${i}`)
+  }
+  const skip = () => {
+    for (;;) {
+      while (i < text.length && /\s/.test(text[i]!)) i++
+      if (text.startsWith("//", i)) {
+        const nl = text.indexOf("\n", i)
+        i = nl < 0 ? text.length : nl + 1
+      } else if (text.startsWith("/*", i)) {
+        const end = text.indexOf("*/", i + 2)
+        if (end < 0) fail("unclosed comment")
+        i = end + 2
+      } else return
+    }
+  }
+  const string = (): string => {
+    const start = i
+    i++
+    while (i < text.length && text[i] !== '"') i += text[i] === "\\" ? 2 : 1
+    if (i >= text.length) fail("unclosed string")
+    i++
+    return JSON.parse(text.slice(start, i)) as string
+  }
+  const value = (): Node => {
+    skip()
+    const start = i
+    const c = text[i]
+    if (c === "{") {
+      i++
+      const members: Array<{ key: string; value: Node }> = []
+      for (;;) {
+        skip()
+        if (text[i] === "}") break
+        if (text[i] !== '"') fail("expected a key")
+        const key = string()
+        skip()
+        if (text[i] !== ":") fail("expected :")
+        i++
+        members.push({ key, value: value() })
+        skip()
+        if (text[i] === ",") i++
+        else if (text[i] !== "}") fail("expected , or }")
+      }
+      i++
+      return { kind: "object", start, end: i, members }
+    }
+    if (c === "[") {
+      i++
+      const items: Node[] = []
+      for (;;) {
+        skip()
+        if (text[i] === "]") break
+        items.push(value())
+        skip()
+        if (text[i] === ",") i++
+        else if (text[i] !== "]") fail("expected , or ]")
+      }
+      i++
+      return { kind: "array", start, end: i, items }
+    }
+    if (c === '"') {
+      const v = string()
+      return { kind: "scalar", start, end: i, value: v }
+    }
+    const m = /^(?:true|false|null|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?)/.exec(text.slice(i, i + 400))
+    if (!m) fail("unexpected character")
+    i += m![0].length
+    return { kind: "scalar", start, end: i, value: JSON.parse(m![0]) }
+  }
+  skip()
+  if (i >= text.length) return undefined
+  const root = value()
+  skip()
+  if (i < text.length) fail("text after the end")
+  return root
+}
+
+export function plain(n: Node): unknown {
+  if (n.kind === "scalar") return n.value
+  if (n.kind === "array") return n.items.map(plain)
+  const o: Json = {}
+  for (const m of n.members) o[m.key] = plain(m.value)
+  return o
+}
+
+/** The first `,` between from and to that is not inside a comment, or -1. */
+function commaBetween(text: string, from: number, to: number): number {
+  for (let i = from; i < to; i++) {
+    if (text.startsWith("//", i)) {
+      const nl = text.indexOf("\n", i)
+      i = nl < 0 ? to : nl
+    } else if (text.startsWith("/*", i)) i = text.indexOf("*/", i + 2) + 1
+    else if (text[i] === ",") return i
+  }
+  return -1
+}
+
+/** The whitespace a value at `at` is indented by, when it starts its line; undefined when something precedes it there. */
+function lineIndent(text: string, at: number): string | undefined {
+  const lineStart = text.lastIndexOf("\n", at - 1) + 1
+  const before = text.slice(lineStart, at)
+  return /^[ \t]*$/.test(before) ? before : undefined
+}
+
+const indentUnit = (text: string) => text.match(/\n([ \t]+)[^\s]/)?.[1]?.replace(/^(\t| {2,4}).*$/, "$1") ?? "\t"
+const render = (v: unknown, indent: string, unit: string) => JSON.stringify(v, null, unit).replace(/\n/g, `\n${indent}`)
+
+/**
+ * chatLanguageModels.json: a JSON-with-comments array of model groups. A key names one Custom Endpoint group (its `name`);
+ * set adds, replaces or removes that one array element and leaves every other byte as it was, so removing a group this
+ * codec added gives the file back exactly. A file that does not parse as such an array is refused.
+ */
+export const languageModelGroups: Codec = {
+  check(text) {
+    try {
+      const root = parseJsonc(text)
+      if (root && root.kind !== "array") return "it is not a list of model groups; left as it is"
+    } catch {
+      return "it is not valid JSON (with comments); left as it is"
+    }
+    return undefined
+  },
+  get(text, key) {
+    const root = parseJsonc(text)
+    if (root?.kind !== "array") return undefined
+    const el = findGroup(root, key)
+    return el ? plain(el) : undefined
+  },
+  set(text, key, value) {
+    const root = parseJsonc(text)
+    const unit = indentUnit(text)
+    if (!root) return value === undefined ? text : `[\n${unit}${render(value, unit, unit)}\n]\n`
+    if (root.kind !== "array") throw new Error("not a list of model groups")
+    const el = findGroup(root, key)
+    if (el && value !== undefined) return text.slice(0, el.start) + render(value, lineIndent(text, el.start) ?? unit, unit) + text.slice(el.end)
+    if (!el && value === undefined) return text
+    if (!el) {
+      const last = root.items[root.items.length - 1]
+      if (!last) {
+        // An empty list: `[]` (VS Code's own empty file) becomes one element on its own lines, closing at the list's indent.
+        const close = lineIndent(text, root.end - 1) ?? ""
+        const inner = text.slice(root.start + 1, root.end - 1)
+        const body = inner.trim() ? `${inner.replace(/\s*$/, "")}\n${close}${unit}` : `\n${close}${unit}`
+        return `${text.slice(0, root.start + 1)}${body}${render(value, close + unit, unit)}\n${close}${text.slice(root.end - 1)}`
+      }
+      const indent = lineIndent(text, last.start) ?? unit
+      return `${text.slice(0, last.end)},\n${indent}${render(value, indent, unit)}${text.slice(last.end)}`
+    }
+    // Remove the element with the comma that joins it to its neighbour.
+    const at = root.items.indexOf(el)
+    const prev = root.items[at - 1]
+    const next = root.items[at + 1]
+    let out: string
+    if (prev) {
+      const gap = text.slice(prev.end, el.start)
+      if (/^\s*,\s*$/.test(gap)) out = text.slice(0, prev.end) + text.slice(el.end)
+      else {
+        // Comments between the two: keep them, drop the comma before this element and the element's own line.
+        const comma = commaBetween(text, prev.end, el.start)
+        const from = lineIndent(text, el.start) !== undefined ? text.lastIndexOf("\n", el.start - 1) : el.start
+        out = text.slice(0, comma) + text.slice(comma + 1, from) + text.slice(el.end)
+      }
+    } else if (next) {
+      const comma = commaBetween(text, el.end, next.start)
+      out = text.slice(0, el.start) + (/^\s*,\s*$/.test(text.slice(el.end, next.start)) ? text.slice(next.start) : text.slice(comma + 1).replace(/^[ \t]*\n?[ \t]*/, ""))
+    } else {
+      const inner = text.slice(root.start + 1, el.start) + text.slice(el.end, root.end - 1)
+      out = text.slice(0, root.start + 1) + (inner.trim() ? inner : "") + text.slice(root.end - 1)
+    }
+    // A file this codec created (one group, "[...]\n") ends empty, so disconnect removes it; VS Code's own "[]" stays.
+    return out === "[]\n" ? "" : out
+  },
+}
+
+function findGroup(root: Extract<Node, { kind: "array" }>, name: string) {
+  let found: Node | undefined
+  for (const it of root.items) {
+    if (it.kind !== "object") continue
+    const v = plain(it) as Json
+    if (v.name === name && v.vendor === VENDOR) found = it
+  }
+  return found
+}
+
+// ---- the connector ------------------------------------------------------------------------------------------------------
+
+export const connectors: Connector[] = [
+  {
+    id: "vscode-copilot",
+    label: "Copilot Chat (VS Code)",
+    file: (home, env) => join(vscodeUserDir(home, env), "chatLanguageModels.json"),
+    probe: [],
+    authHeader: "authorization",
+    edits: (home, s, env) => [
+      {
+        path: join(vscodeUserDir(home, env), "chatLanguageModels.json"),
+        format: "custom",
+        codec: languageModelGroups,
+        holdsKey: true,
+        secretKeys: [GROUP],
+        values: {
+          [GROUP]: {
+            name: GROUP,
+            vendor: VENDOR,
+            apiType: "chat-completions",
+            models: [
+              {
+                id: s.model,
+                name: modelName(s.model),
+                url: `${routeUrl(s)}/v1/chat/completions`,
+                apiType: "chat-completions",
+                toolCalling: true,
+                vision: true,
+                maxInputTokens: MAX_INPUT,
+                maxOutputTokens: MAX_OUTPUT,
+                requestHeaders: { Authorization: `Bearer ${readKey(home)}`, ...(s.contextEdit ? { [EDIT_HEADER]: "on" } : {}) },
+              },
+            ],
+          },
+        },
+      },
+    ],
+    notes: [
+      'In Copilot Chat, open the model picker and choose the model listed under "100xprompt gateway" once; VS Code remembers the choice (brain does not change your default model).',
+      "VS Code keeps a custom model's key in its secret storage, which brain cannot write, so the gateway key is in the model's request headers in chatLanguageModels.json instead; that file is now readable by you only (0600) and is not synced by Settings Sync.",
+      "Needs VS Code 1.122 or later (the Custom Endpoint provider). On Copilot Business or Enterprise, your organization must allow bring-your-own-key models.",
+    ],
+  },
+]

package/src/gateway/connectors/windsurf.ts

@@ -0,0 +1,6 @@
+// Gateway connector for Windsurf (now Devin Desktop): none. Its models are served by Cognition's backend only; the one
+// network setting is an HTTP proxy, and "You cannot point Devin Desktop at your own LLM" (checked 2026-11-10:
+// https://agentgateway.dev/docs/standalone/main/integrations/llm-clients/devin/; docs.windsurf.com now redirects to docs.devin.ai).
+import type { Connector } from "../common.ts"
+
+export const connectors: Connector[] = []

package/src/gateway/connectors/zed.ts

@@ -0,0 +1,29 @@
+// Gateway connector for Zed: NOT BUILT. Zed cannot be given the gateway key through a file brain can write and undo.
+//
+// Checked 2026-11-10 (Zed is not installed on this machine) against the Zed docs and the zed-industries/zed main source:
+//   - https://zed.dev/docs/ai/use-api-access ("OpenAI-Compatible Endpoints", "Anthropic-Compatible Endpoints"): providers
+//     go in settings.json (JSON with comments, ~/.config/zed/settings.json) under `language_models.openai_compatible.<id>`
+//     (`api_url`, `available_models: [{ name, display_name, max_tokens, max_output_tokens, capabilities }]`,
+//     `custom_headers`) or `language_models.anthropic_compatible.<name>`, and the agent's model under `agent.default_model`.
+//     All of that is writable. The key is not: "Enter the API key in the provider settings UI or set the generated
+//     environment variable" (<PROVIDER_ID>_API_KEY, upper snake case), keys saved in Zed "are stored in the system
+//     keychain, not in settings.json", and `custom_headers` cannot carry it ("Headers Zed manages, such as provider
+//     authentication headers, are ignored with a warning").
+//   - crates/language_model/src/api_key.rs (ApiKeyState::load_if_needed): the key comes from the environment variable if it
+//     is set and non-empty, otherwise from the credentials provider (the system keychain) keyed by the API URL
+//     (read_credentials(url)); there is no file or command source.
+//   - crates/language_models/src/provider/open_ai_compatible.rs: OpenAiCompatibleSettings { api_url, available_models,
+//     custom_headers }; requests fail with NoApiKey when neither source has a key.
+//
+// So the key could only reach Zed through (a) the keychain, which brain must not write (and could neither refresh on a new
+// sign-in nor remove on disconnect), or (b) an environment variable in Zed's own launch environment, which means the
+// person's shell profile, not Zed's config, and would expose the key to every process started from that shell.
+//
+// A semi-manual connector was considered and not built: brain could add the provider and default model to settings.json
+// and ask the person to paste the key into Zed's Agent settings. It is not automatic, `connect` would report Zed as
+// connected while it has no key, `disconnect` would leave the key in the keychain, and a new `brain gateway login` would
+// leave Zed on the old key without anyone noticing. Not worth it until the core can mark a connector as needing a manual
+// key step (and status can say whether that step was done).
+import type { Connector } from "../common.ts"
+
+export const connectors: Connector[] = []

package/src/gateway/signin.ts

@@ -0,0 +1,323 @@
+// `brain gateway login`: sign in to 100xprompt in the browser, the same way the 100xprompt CLI does (`100xprompt auth login`).
+//
+//   1. A one-use server listens on 127.0.0.1 on a free port, for /auth/callback only.
+//   2. The browser opens https://100xprompt.com/auth/cli?port=<port>&state=<random>&challenge=<PKCE S256>. The person signs in
+//      there; the site sends the browser back to http://127.0.0.1:<port>/auth/callback?token=...&state=...&email=...
+//   3. The state must be the one sent (so no other page can hand this machine a key); the token is the gateway key.
+//   4. No browser here (SSH), or the callback cannot get through: the person pastes the one-time code or API key the
+//      site shows instead (input hidden). It is checked the way the CLI checks it.
+//
+// HUNDREDXPROMPT_AUTH_URL points the sign-in at another site (the CLI reads the same variable). The key is never printed.
+//
+// The state is the only thing that tells the real sign-in apart from a key planted by someone else on this machine, so
+// it is kept out of other processes' view where the system allows: on macOS the address goes to the browser through
+// AppleScript's `open location` on stdin, not on a command line that `ps` shows every user. (Linux and Windows browsers
+// take the address on their command line; there, another user who watches `ps` during the sign-in could plant a key. The
+// 100xprompt CLI has the same limit everywhere.)
+import { timingSafeEqual } from "node:crypto"
+
+export const AUTH_URL = "https://100xprompt.com"
+export const TIMEOUT_MS = 5 * 60_000
+
+/** PKCE (RFC 7636): a 43-character verifier and its S256 challenge, as the CLI makes them. */
+export async function pkce(): Promise<{ verifier: string; challenge: string }> {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~"
+  const verifier = Array.from(crypto.getRandomValues(new Uint8Array(43)), (b) => chars[b % chars.length]).join("")
+  const challenge = Buffer.from(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))).toString("base64url")
+  return { verifier, challenge }
+}
+
+/**
+ * Whether a pasted credential looks like a 100xprompt one, as the CLI decides it (Auth.validate): a 100x_live_ / 100x_test_ /
+ * sk- key, a sign-in token (JWT, not expired), or a 100x_auth_ one-time code wrapping either. Returns the key to store.
+ */
+export function checkCredential(raw: string, now = Date.now()): { ok: true; key: string; email?: string } | { ok: false; why: string } {
+  const t = raw.trim()
+  if (!t || t.length < 16) return { ok: false, why: "that is too short to be a key or code" }
+  if (/\s/.test(t)) return { ok: false, why: "a key or code has no spaces in it" }
+  // The sign-in page shows the key shortened ("100x_live_AbCdEfGhIjKl...12345678"); only its Copy key button gives all of it.
+  if (/\.\.\.|…/.test(t)) return { ok: false, why: "that is the shortened key the page shows: use its Copy key button, then paste again" }
+  if (/^(?:100x_live_|100x_test_|sk-)/.test(t)) {
+    if (!/^(?:100x_live_|100x_test_|sk-)[A-Za-z0-9_-]+$/.test(t)) return { ok: false, why: "that key has characters a 100xprompt key never has" }
+    return t.length >= 24 ? { ok: true, key: t } : { ok: false, why: "that key is too short" }
+  }
+  const parts = t.split(".")
+  if (parts.length === 3) {
+    try {
+      const head = JSON.parse(Buffer.from(parts[0]!, "base64url").toString("utf8"))
+      const body = JSON.parse(Buffer.from(parts[1]!, "base64url").toString("utf8"))
+      if (!head?.alg || !body?.sub) return { ok: false, why: "that sign-in token is malformed" }
+      if (typeof body.exp === "number" && body.exp < Math.floor(now / 1000)) return { ok: false, why: "that sign-in token has expired: sign in again" }
+      return { ok: true, key: t, ...(typeof body.email === "string" ? { email: body.email } : {}) }
+    } catch {
+      return { ok: false, why: "that sign-in token is malformed" }
+    }
+  }
+  if (t.startsWith("100x_auth_")) {
+    try {
+      const inner = JSON.parse(Buffer.from(t.slice("100x_auth_".length), "base64url").toString("utf8"))
+      if (typeof inner?.t === "string" && !inner.t.startsWith("100x_auth_")) {
+        const r = checkCredential(inner.t, now)
+        return r.ok && typeof inner.e === "string" && !r.email ? { ...r, email: inner.e } : r
+      }
+    } catch {}
+    return { ok: false, why: "that one-time code is malformed" }
+  }
+  return { ok: false, why: `that is not a 100xprompt key or one-time code (copy the code from ${AUTH_URL}/auth/cli, or a 100x_live_ key)` }
+}
+
+const esc = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`)
+const page = (title: string, body: string, status = 200) =>
+  new Response(
+    `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(title)}</title>` +
+      `<style>body{font-family:system-ui,-apple-system,sans-serif;display:flex;justify-content:center;align-items:center;height:100vh;margin:0;background:#050505;color:#f1ecec}` +
+      `main{text-align:center;max-width:32rem;padding:1rem}h1{font-size:1.4rem}p{color:#a8a3a3}</style></head>` +
+      `<body><main><h1>${esc(title)}</h1><p>${esc(body)}</p></main></body></html>`,
+    // The callback URL carries the key: nothing on this page may cache it or pass it on.
+    { status, headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", "referrer-policy": "no-referrer", "x-frame-options": "DENY" } },
+  )
+
+/** Constant-time state check. Byte lengths are compared (a non-ASCII state of the right length in characters must not throw). */
+const sameState = (got: string, want: string) => {
+  const a = Buffer.from(got)
+  const b = Buffer.from(want)
+  return a.length === b.length && timingSafeEqual(a, b)
+}
+
+/** The key in a callback's token: the CLI takes it as it is; brain also unwraps a one-time code and refuses junk. */
+const callbackKey = (token: string): { ok: true; key: string; email?: string } | { ok: false; why: string } =>
+  token.startsWith("100x_auth_") ? checkCredential(token) : token.length >= 16 && !/\s/.test(token) ? { ok: true, key: token } : { ok: false, why: "no key came back from the sign-in page" }
+
+/** The sign-in site from --auth-url / $HUNDREDXPROMPT_AUTH_URL (empty means unset, as for the CLI); undefined if not http(s). */
+export function signInBase(given?: string): string | undefined {
+  const raw = given?.trim() || process.env.HUNDREDXPROMPT_AUTH_URL?.trim() || AUTH_URL
+  try {
+    const u = new URL(raw)
+    if (u.protocol !== "https:" && u.protocol !== "http:") return undefined
+    return `${u.origin}${u.pathname.replace(/\/+$/, "")}`
+  } catch {
+    return undefined
+  }
+}
+
+export interface SignInDeps {
+  /** Opens the sign-in page; default: the system browser. */
+  open?: (url: string) => void
+  /** false: print the address only (a machine with no browser, or one the person opens elsewhere). */
+  browser?: boolean
+  /** The sign-in site; default $HUNDREDXPROMPT_AUTH_URL or https://100xprompt.com. */
+  authUrl?: string
+  timeoutMs?: number
+  /**
+   * Asks for a pasted code, input hidden; resolves undefined when the person gives up or `signal` aborts. Absent when
+   * there is no terminal to ask in (then the browser is the only way).
+   */
+  ask?: (message: string, signal: AbortSignal) => Promise<string | undefined>
+  say: (line: string) => void
+}
+
+export type SignIn = { ok: true; key: string; email?: string; via: "browser" | "code" } | { ok: false; why: string }
+
+/** Signs in through the browser (or a pasted code). Does not store anything: the caller does. */
+export async function browserSignIn(d: SignInDeps): Promise<SignIn> {
+  const base = signInBase(d.authUrl)
+  if (!base) return { ok: false, why: "HUNDREDXPROMPT_AUTH_URL must be an http:// or https:// address" }
+  const { challenge } = await pkce()
+  const state = Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString("hex")
+  let finish!: (r: SignIn) => void
+  const done = new Promise<SignIn>((r) => (finish = r))
+  let settled = false
+  const settle = (r: SignIn) => {
+    if (settled) return
+    settled = true
+    finish(r)
+  }
+  const server = Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0,
+    development: false,
+    // Anything the handler did not expect: a plain refusal, never a stack trace on the page or in the terminal.
+    error: () => new Response("Bad request", { status: 400 }),
+    fetch(req) {
+      const url = new URL(req.url)
+      if (url.pathname !== "/auth/callback" || req.method !== "GET") return new Response("Not found", { status: 404 })
+      if (settled) return page("Already signed in", "This sign-in has finished. You can close this tab.", 410)
+      const got = url.searchParams.get("state") ?? ""
+      const error = url.searchParams.get("error")
+      // Only the page this command opened knows the state: anything else is refused and the wait goes on.
+      if (!/^[0-9a-f]{64}$/.test(got) || !sameState(got, state)) return page("Sign-in refused", "This link was not started by this brain gateway login. Start again from your terminal.", 400)
+      if (error) {
+        settle({ ok: false, why: `the sign-in page said: ${error.slice(0, 200)}` })
+        return page("Sign-in failed", `${error.slice(0, 200)}. Go back to your terminal.`, 400)
+      }
+      const c = callbackKey(url.searchParams.get("token") ?? "")
+      if (!c.ok) {
+        settle({ ok: false, why: c.why })
+        return page("Sign-in failed", "No usable key came back. Go back to your terminal.", 400)
+      }
+      const email = url.searchParams.get("email") || c.email || undefined
+      settle({ ok: true, key: c.key, ...(email ? { email } : {}), via: "browser" })
+      return page("Signed in", `brain is now signed in to the 100xprompt gateway${email ? ` as ${email}` : ""}. You can close this tab and go back to your terminal.`)
+    },
+  })
+  const url = `${base}/auth/cli?port=${server.port}&state=${state}&challenge=${challenge}`
+  const stopAsking = new AbortController()
+  const timer = setTimeout(() => settle({ ok: false, why: `no sign-in came back within ${Math.round((d.timeoutMs ?? TIMEOUT_MS) / 60_000) || 1} minutes` }), d.timeoutMs ?? TIMEOUT_MS)
+  try {
+    if (d.browser === false) d.say(`Open this address in a browser to sign in to 100xprompt:\n  ${url}`)
+    else {
+      d.say(`Opening your browser to sign in to 100xprompt:\n  ${url}`)
+      try {
+        ;(d.open ?? openInBrowser)(url)
+      } catch {}
+    }
+    if (d.ask) {
+      d.say(
+        "Waiting for the browser. Signing in on another machine (SSH)? Paste the key from the page's Copy key button, or the address the browser could not open, then press Enter (Escape cancels).",
+      )
+      // The paste runs alongside the browser: whichever comes first wins. A bad paste asks again; Escape ends the sign-in
+      // (an abandoned hidden prompt would leave the terminal echoing whatever is pasted next, and the shell reading it).
+      void (async () => {
+        for (;;) {
+          const pasted = await d.ask!("key or address: ", stopAsking.signal)
+          if (settled) return
+          if (pasted === undefined) return settle({ ok: false, why: "sign-in cancelled" })
+          if (!pasted.trim()) continue
+          const c = fromPaste(pasted.trim(), state)
+          if (c.ok) return settle({ ok: true, key: c.key, ...(c.email ? { email: c.email } : {}), via: "code" })
+          if ("fatal" in c) return settle({ ok: false, why: c.why })
+          d.say(`  ${c.why}`)
+        }
+      })()
+    } else d.say("Waiting for the browser…")
+    return await done
+  } finally {
+    clearTimeout(timer)
+    stopAsking.abort()
+    // The page that just answered must reach the browser before this returns: `brain` exits right after, and an exit
+    // with the answer still unsent leaves the person looking at a browser error after a sign-in that worked. A graceful
+    // stop waits for that answer; a browser holding the connection open gets cut off after 1.5 s.
+    await Promise.race([server.stop(), Bun.sleep(1_500)])
+    void server.stop(true)
+  }
+}
+
+/**
+ * A pasted key, one-time code or sign-in token; or the callback address itself (on SSH the browser is sent to
+ * 127.0.0.1 on the wrong machine, and the address it could not open holds the key). An address must carry this sign-in's
+ * state, so one from another sign-in, or one made up, is refused.
+ */
+export function fromPaste(pasted: string, state: string): { ok: true; key: string; email?: string } | { ok: false; why: string } | { ok: false; why: string; fatal: true } {
+  if (/^https?:\/\//i.test(pasted)) {
+    let u: URL
+    try {
+      u = new URL(pasted)
+    } catch {
+      return { ok: false, why: "that address could not be read" }
+    }
+    if (!u.pathname.endsWith("/auth/callback")) return { ok: false, why: "that is not the sign-in's return address (it ends in /auth/callback?token=...)" }
+    const got = u.searchParams.get("state") ?? ""
+    if (!/^[0-9a-f]{64}$/.test(got) || !sameState(got, state)) return { ok: false, why: "that address is from another sign-in: paste the one from this sign-in" }
+    const error = u.searchParams.get("error")
+    if (error) return { ok: false, why: `the sign-in page said: ${error.slice(0, 200)}`, fatal: true }
+    const c = callbackKey(u.searchParams.get("token") ?? "")
+    if (!c.ok) return c
+    const email = u.searchParams.get("email") || c.email
+    return { ok: true, key: c.key, ...(email ? { email } : {}) }
+  }
+  return checkCredential(pasted)
+}
+
+/**
+ * How to open the sign-in page on this platform: the command, and what to write to its stdin. On macOS the address goes
+ * to AppleScript's `open location` on stdin, so it (and its state) is on no command line.
+ */
+export function browserCommand(url: string, platform: string = process.platform): { argv: string[]; stdin?: string } {
+  if (platform === "darwin") return { argv: ["osascript", "-"], stdin: `open location "${url.replace(/[\\"]/g, (c) => `\\${c}`)}"\n` }
+  if (platform === "win32") return { argv: ["cmd", "/c", "start", "", url.replace(/&/g, "^&")] }
+  return { argv: ["xdg-open", url] }
+}
+
+/** Opens the sign-in page in the default browser (browserCommand). */
+export function openInBrowser(url: string): void {
+  const c = browserCommand(url)
+  try {
+    const p = Bun.spawn(c.argv, { stdin: c.stdin === undefined ? "ignore" : "pipe", stdout: "ignore", stderr: "ignore" })
+    if (c.stdin !== undefined && p.stdin && typeof p.stdin !== "number") {
+      p.stdin.write(c.stdin)
+      void p.stdin.end()
+    }
+    p.unref()
+  } catch {}
+}
+
+/**
+ * Applies typed or pasted terminal input to `buf`. Enter ends the line; Escape on its own, or Ctrl-D on an empty line,
+ * cancels; Ctrl-C interrupts. Arrow, Delete and Home keys, Alt+key and bracketed-paste markers arrive as escape sequences
+ * and are skipped, so they neither end the prompt nor land in the key.
+ */
+export function applyKeys(buf: string, chunk: string): { buf: string; end?: "enter" | "cancel" | "interrupt" } {
+  for (let i = 0; i < chunk.length; i++) {
+    const ch = chunk[i]!
+    if (ch === "\r" || ch === "\n") return { buf, end: "enter" }
+    if (ch === "\u0003") return { buf, end: "interrupt" }
+    if (ch === "\u0004") {
+      if (!buf) return { buf, end: "cancel" }
+      continue
+    }
+    if (ch === "\u001b") {
+      const next = chunk[i + 1]
+      if (next === undefined) return { buf, end: "cancel" }
+      if (next === "[") {
+        // CSI: parameter bytes, then one final byte in 0x40-0x7E.
+        let j = i + 2
+        while (j < chunk.length && !(chunk.charCodeAt(j) >= 0x40 && chunk.charCodeAt(j) <= 0x7e)) j++
+        i = j
+      } else i += next === "O" ? 2 : 1 // SS3 (ESC O x) or Alt+key (ESC x)
+      continue
+    }
+    if (ch === "\u007f" || ch === "\b") buf = buf.slice(0, -1)
+    else if (ch >= " ") buf += ch
+  }
+  return { buf }
+}
+
+/**
+ * Reads one line from the terminal without showing it (the key must not land in the scrollback). undefined: no terminal,
+ * cancelled (Escape, Ctrl-D), or `signal` aborted. Ctrl-C ends the command, as it would anywhere else.
+ */
+export function askHidden(message: string, signal: AbortSignal): Promise<string | undefined> {
+  const stdin = process.stdin
+  if (!stdin.isTTY || signal.aborted) return Promise.resolve(undefined)
+  return new Promise((resolve) => {
+    let buf = ""
+    let over = false
+    process.stderr.write(message)
+    stdin.setRawMode(true)
+    stdin.setEncoding("utf8")
+    stdin.resume()
+    const end = (v: string | undefined) => {
+      if (over) return
+      over = true
+      stdin.off("data", onData)
+      signal.removeEventListener("abort", onAbort)
+      stdin.setRawMode(false)
+      stdin.pause()
+      process.stderr.write("\n")
+      resolve(v)
+    }
+    const onAbort = () => end(undefined)
+    const onData = (chunk: string) => {
+      const r = applyKeys(buf, chunk)
+      buf = r.buf
+      if (r.end === "enter") end(buf)
+      else if (r.end === "cancel") end(undefined)
+      else if (r.end === "interrupt") {
+        end(undefined)
+        process.exit(130)
+      }
+    }
+    stdin.on("data", onData)
+    signal.addEventListener("abort", onAbort)
+  })
+}