privateer-agent 0.1.1 → 0.3.0

package/src/permissions/classify.ts

@@ -0,0 +1,172 @@
+import { resolve, isAbsolute, relative } from "node:path";
+import { isProtectedPath } from "./protected.ts";
+import type { PermissionRequest } from "./gate.ts";
+
+// NEW glue for the Pi rewrite. In 0.2 each tool built its own PermissionRequest
+// before calling ctx.gate.request(). Pi's `tool_call` hook instead hands us
+// { toolName, input }, so the classification — which kind of action is this, does
+// it touch a protected/outside path — moves here. Field extraction is defensive
+// across Pi's builtin input shapes (command/cmd, path/file_path/file).
+//
+// Returns null when the call needs no gate (a read-only builtin acting inside
+// scope, or a known-safe meta tool): the hook then lets it run untouched, so
+// ordinary in-cwd work has zero friction.
+
+export interface ScopeOptions {
+  cwd: string;
+  confineToCwd?: boolean; // default true
+  allowedOutsideRoots?: string[];
+}
+
+function resolveInCwd(cwd: string, p: string): string {
+  return isAbsolute(p) ? p : resolve(cwd, p);
+}
+
+function isInsideDir(root: string, abs: string): boolean {
+  if (abs === root) return true;
+  const rel = relative(root, abs);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+// Outside the agent's working-directory scope? Only when confinement is on and the
+// path is neither inside cwd nor inside a session-approved outside root.
+export function isOutsideScope(scope: ScopeOptions, abs: string): boolean {
+  if (scope.confineToCwd === false) return false;
+  if (isInsideDir(scope.cwd, abs)) return false;
+  return !(scope.allowedOutsideRoots ?? []).some((root) => isInsideDir(root, abs));
+}
+
+function str(v: unknown): string {
+  return typeof v === "string" ? v : v == null ? "" : String(v);
+}
+
+function firstPath(input: Record<string, unknown>): string {
+  return str(input.path ?? input.file_path ?? input.file ?? input.filename ?? input.dir ?? input.directory);
+}
+
+// Known-safe read-only / meta builtins that never mutate and never leave the
+// machine: no gate regardless of arguments. Tunable — the conservative default for
+// anything NOT listed here is to ask (see below). TODO(verify) against Pi's full
+// builtin tool catalog as it's enumerated in Phase 5.
+const NON_GATED = new Set([
+  "todo", "todowrite", "todo_write", "todoread", "think", "plan_note",
+]);
+
+// Read-ish builtins: gated ONLY when the target resolves outside scope.
+const READ_TOOLS = new Set(["read", "cat", "grep", "find", "glob", "ls", "tree", "view"]);
+const EDIT_TOOLS = new Set(["edit", "edit_file", "str_replace", "str_replace_editor", "apply_patch", "patch"]);
+const WRITE_TOOLS = new Set(["write", "write_file", "create_file", "create", "save_attachment"]);
+const BASH_TOOLS = new Set(["bash", "shell", "run", "exec", "sh"]);
+
+export function classifyToolCall(
+  toolName: string,
+  input: unknown,
+  scope: ScopeOptions,
+): PermissionRequest | null {
+  const name = toolName.toLowerCase();
+  const obj: Record<string, unknown> =
+    input && typeof input === "object" ? (input as Record<string, unknown>) : {};
+
+  if (NON_GATED.has(name)) return null;
+
+  // Creating a routine is a persistent mutation; surface the trigger + delivery, and
+  // force a human decision (alwaysAsk) when it grants off-machine egress.
+  if (name === "create_routine" || name === "routine") {
+    const label = str(obj.name) || "routine";
+    const trigger = obj.cron ? `cron ${str(obj.cron)}` : obj.at ? `at ${str(obj.at)}` : "(no trigger)";
+    const delivery = Array.isArray(obj.delivery) ? (obj.delivery as unknown[]).map(String) : ["file"];
+    const egress: string[] = [];
+    if (delivery.includes("email")) egress.push("email leaves the machine");
+    if (delivery.some((d) => d.startsWith("webhook:"))) egress.push("posts to a webhook off-machine");
+    return {
+      tool: toolName,
+      kind: "write",
+      title: "Create routine",
+      detail: `${label}: ${trigger} → ${delivery.join(",")}${egress.length ? ` [${egress.join("] [")}]` : ""}`,
+      alwaysAsk: egress.length > 0,
+    };
+  }
+
+  // Shell — the whole command is the detail (danger scanning runs on it).
+  if (BASH_TOOLS.has(name)) {
+    const command = str(obj.command ?? obj.cmd ?? obj.script);
+    return { tool: toolName, kind: "bash", title: "Run command", detail: command };
+  }
+
+  // Write — create/overwrite a file.
+  if (WRITE_TOOLS.has(name)) {
+    const p = firstPath(obj);
+    const abs = resolveInCwd(scope.cwd, p);
+    const outside = isOutsideScope(scope, abs);
+    return {
+      tool: toolName,
+      kind: "write",
+      title: outside ? "Write outside working directory" : "Write file",
+      detail: outside ? abs : p,
+      protected: isProtectedPath(abs),
+      outside,
+      path: abs,
+    };
+  }
+
+  // Edit — modify an existing file.
+  if (EDIT_TOOLS.has(name)) {
+    const p = firstPath(obj);
+    const abs = resolveInCwd(scope.cwd, p);
+    const outside = isOutsideScope(scope, abs);
+    return {
+      tool: toolName,
+      kind: "edit",
+      title: outside ? "Edit outside working directory" : "Edit file",
+      detail: outside ? abs : p,
+      protected: isProtectedPath(abs),
+      outside,
+      path: abs,
+    };
+  }
+
+  // Read-ish — no gate in scope; when the target is outside scope, prompt.
+  if (READ_TOOLS.has(name)) {
+    const p = firstPath(obj);
+    if (!p) return null; // e.g. grep with no explicit path → in-cwd, no gate
+    const abs = resolveInCwd(scope.cwd, p);
+    if (!isOutsideScope(scope, abs)) return null;
+    return {
+      tool: toolName,
+      kind: "read",
+      title: "Read outside working directory",
+      detail: abs,
+      outside: true,
+      path: abs,
+    };
+  }
+
+  // Network reads (web fetch / search / http).
+  if (name.includes("fetch") || name.includes("web") || name.includes("http") || name.includes("url")) {
+    return {
+      tool: toolName,
+      kind: "fetch",
+      title: "Fetch from the network",
+      detail: str(obj.url ?? obj.query ?? obj.q),
+    };
+  }
+
+  // Unknown / custom / MCP tool: we can't prove it's side-effect-free, so
+  // safe-by-default is to prompt. Classified as a bash-kind action (asks in
+  // default/acceptEdits, denies in plan, allows only under bypass). Phase 5 refines
+  // this with MCP destructiveHint → alwaysAsk and a per-tool policy map.
+  return {
+    tool: toolName,
+    kind: "bash",
+    title: `Run ${toolName}`,
+    detail: safeJson(obj),
+  };
+}
+
+function safeJson(v: unknown): string {
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}

package/src/permissions/gate.ts

@@ -1,8 +1,10 @@
-// The permission gate is the seam between tools and the user's approval policy.
-// Tools call `gate.request(...)` before any mutation or shell execution; the gate
-// decides allow/deny based on the active permission mode (Phase 4) and may prompt
-// the user interactively. Phase 2 ships a pass-through gate so tools work
-// end-to-end; Phase 4 replaces it with the mode-aware interactive gate.
+// Permission-gate vocabulary — the request shape the policy reasons about, and
+// the decision it returns. Ported from tree-cli/src/permissions/gate.ts, trimmed
+// to types only: in the 0.2 codebase each tool built a PermissionRequest and
+// called ctx.gate.request(); in the Pi rewrite the gate is a `tool_call`
+// extension hook that receives { toolName, input } and derives the request via
+// classifyToolCall (see ./classify.ts). So the pass-through gate is gone; the
+// live policy lives in ./mode.ts + ./modeGate.ts.
 
 export type PermissionDecision = "allow" | "deny";
 
@@ -14,22 +16,22 @@ export interface PermissionRequest {
   title: string; // short action label, e.g. "Run command"
   detail: string; // the command, or file path + change preview
   protected?: boolean; // target is a guarded file: never auto-approve, always prompt
+  // Always require a human decision, ABOVE bypass mode and the allowlist (like a
+  // dangerous shell command). Set for tools that declare themselves destructive,
+  // so even a "take no prisoners" run can't fire an irreversible action silently.
+  // The decision is never remembered.
+  alwaysAsk?: boolean;
   // Target resolves outside the working directory: never auto-approve (unless bypass),
   // always prompt. `path` carries the absolute target so "always" can remember its dir.
   outside?: boolean;
   path?: string;
 }
 
+// Implemented by ModeGate (./modeGate.ts). The extension builds one per tool_call.
 export interface PermissionGate {
   request(req: PermissionRequest): Promise<PermissionDecision>;
 }
 
-export const autoApproveGate: PermissionGate = {
-  async request() {
-    return "allow";
-  },
-};
-
 export class PermissionDeniedError extends Error {
   constructor(tool: string) {
     super(`Permission denied for ${tool}`);

package/src/permissions/mode.ts

@@ -1,7 +1,11 @@
-import type { PermissionMode } from "../config/schema.ts";
+import type { PermissionMode } from "../config/permissionMode.ts";
 import type { PermissionRequest } from "./gate.ts";
 import { isDangerousCommand } from "./danger.ts";
 
+// Ported verbatim from tree-cli/src/permissions/mode.ts (only the PermissionMode
+// import path changed). This is the pure mode/allowlist policy the gate consults
+// before ever involving the user.
+
 export type AutoDecision = "allow" | "deny" | "ask";
 
 // Is a bash command covered by the allowlist? Entries are command prefixes:
@@ -27,6 +31,10 @@ export function decideAuto(
   // Dangerous shell (destructive / secret-exfil) always confirms — this sits
   // above bypass and the allowlist so an injected command can't run silently.
   if (req.kind === "bash" && isDangerousCommand(req.detail, denylist)) return "ask";
+  // Explicitly destructive actions (e.g. a tool that declares destructiveHint)
+  // always confirm too — also above bypass, so "skip permissions" can't fire them
+  // blind.
+  if (req.alwaysAsk) return "ask";
   if (mode === "bypass") return "allow";
   // Access outside the working directory always confirms (the user has to explicitly
   // allow leaving cwd), even under acceptEdits or the allowlist.

package/src/permissions/{uiGate.ts → modeGate.ts}

@@ -1,9 +1,14 @@
 import { dirname } from "node:path";
-import type { PermissionMode } from "../config/schema.ts";
+import type { PermissionMode } from "../config/permissionMode.ts";
 import type { PermissionGate, PermissionRequest, PermissionDecision } from "./gate.ts";
 import { decideAuto } from "./mode.ts";
 import { isDangerousCommand } from "./danger.ts";
 
+// Ported verbatim from tree-cli/src/permissions/uiGate.ts (renamed modeGate;
+// only import paths changed). The mode/allowlist/remote policy engine — the moat.
+// In the Pi rewrite the extension (../ext/permissionGate.ts) builds one of these
+// per tool_call, with `ask` bound to that call's ctx.ui (local) or the relay (remote).
+
 // What the interactive prompt can return. "always" means allow now and remember:
 // for bash, add the command to the session allowlist; for edits, switch to acceptEdits.
 export type AskOutcome = "allow" | "deny" | "always";
@@ -15,8 +20,7 @@ export interface ModeGateDeps {
   allowlist: string[]; // session-scoped, mutated in place on "always"
   denylist?: string[]; // dangerous-command patterns that always require a prompt
   // Out-of-cwd directories approved this session ("always" on an outside prompt),
-  // mutated in place. Shared with the tool context so approved locations stop
-  // re-prompting. The same array instance must be handed to the tools.
+  // mutated in place. Shared with the tool scope so approved locations stop re-prompting.
   allowedOutsideRoots?: string[];
   ask: Asker;
   // True while the active turn was injected by a remote controller (the app, via
@@ -25,6 +29,11 @@ export interface ModeGateDeps {
   // an unattended terminal can't silently run a remote party's bash or edits.
   // Hard denies (e.g. plan mode) are still honored without bothering the phone.
   getRemote?: () => boolean;
+  // True while the controller has toggled no-quarter (unattended) mode: remote
+  // turns auto-approve like bypass mode so the agent runs to completion without
+  // pinging the phone. Dangerous shell and alwaysAsk-destructive actions rank
+  // above bypass in decideAuto, so those still relay for an explicit Allow/Deny.
+  getNoQuarter?: () => boolean;
 }
 
 // The permission gate used by the live TUI. It first applies the mode/allowlist
@@ -43,14 +52,21 @@ export class ModeGate implements PermissionGate {
     // remembered — we don't let a remote operator mutate local allowlist/mode.
     if (this.deps.getRemote?.()) {
       if (auto === "deny") return "deny";
+      // No-quarter: re-evaluate as if in bypass mode. Dangerous/destructive
+      // actions still come back "ask" (they sit above bypass) and fall through
+      // to the relayed prompt; everything else runs unattended.
+      if (this.deps.getNoQuarter?.() && decideAuto(req, "bypass", this.deps.allowlist, denylist) === "allow") {
+        return "allow";
+      }
       return (await this.deps.ask(req)) === "deny" ? "deny" : "allow";
     }
 
     if (auto !== "ask") return auto;
 
-    // A dangerous command can be approved once, but is never remembered: adding
-    // it to the allowlist would let a later injected variant slip through.
-    const dangerous = req.kind === "bash" && isDangerousCommand(req.detail, denylist);
+    // A dangerous command (or an always-ask destructive action) can be approved
+    // once, but is never remembered: adding it to the allowlist or relaxing the
+    // mode would let a later variant slip through.
+    const dangerous = req.alwaysAsk === true || (req.kind === "bash" && isDangerousCommand(req.detail, denylist));
 
     const outcome = await this.deps.ask(req);
     if (outcome === "deny") return "deny";

package/src/providers/account.ts

@@ -0,0 +1,170 @@
+// The `privateer` account provider — run inference billed to the user's Privateer
+// subscription instead of a BYO key. This is the one provider the plan flags as a
+// genuine code-blocker (Appendix A): it can't be a static key — it uses a rotating,
+// 401-refreshing child session against the account channel (`${server}/api/agent/v1`).
+//
+// We register it via Pi's OAuth path (ProviderConfigInput.oauth). Pi drives the
+// credential lifecycle: it calls getApiKey(cred) per request and refreshToken(cred)
+// when Date.now() >= cred.expires. We map a per-terminal child session onto that
+// shape (see auth/privateer.ts spawn/refreshAccountCredentials). Because the machine
+// login already exists (~/.privateer/credentials.json), login() just spawns a child;
+// only a first-ever machine login runs the device-code flow.
+
+import {
+  serverBaseUrl,
+  hasCredentials,
+  runDeviceLogin,
+  authedFetch,
+  spawnAccountCredentials,
+  refreshAccountCredentials,
+} from "../auth/privateer.ts";
+import { interpretReport, teePosture, type PrivacyTier } from "pi-privacy";
+
+// Seed/fallback catalog: registered synchronously so the account provider has real
+// models the instant it loads (before the live /api/models fetch resolves) — in
+// particular the signed-in default, near/zai-org/GLM-5.1-FP8, resolves at startup
+// without a "model not found" warning. The first entry is that default: a NEAR
+// confidential-compute (TEE, attestable) model — the strongest privacy tier. Also the
+// fallback list if the live listing can't be reached.
+const DEFAULT_MODELS = [
+  "near/zai-org/GLM-5.1-FP8",
+  "anthropic/claude-sonnet-4.6",
+  "openai/gpt-5.5",
+  "deepseek/deepseek-v4-flash",
+];
+
+function seedModel(id: string) {
+  return {
+    id,
+    name: id,
+    reasoning: false,
+    input: ["text"] as ("text" | "image")[],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+  };
+}
+
+// Fetch the account channel's enabled model catalog. `GET /api/models` is the server's
+// public list of billable models (`{ models: [{ modelId }] }`) — the same set the app
+// shows. (The `/api/agent/v1` base only implements chat/completions, no /models route.)
+// Falls back to DEFAULT_MODELS on any failure.
+export async function fetchAccountModels(): Promise<string[]> {
+  try {
+    const res = await fetch(`${serverBaseUrl()}/api/models`);
+    if (!res.ok) return DEFAULT_MODELS;
+    const data = (await res.json()) as { models?: { modelId?: string }[] };
+    const ids = (data.models ?? []).map((m) => m.modelId).filter((x): x is string => !!x);
+    return ids.length ? ids : DEFAULT_MODELS;
+  } catch {
+    return DEFAULT_MODELS;
+  }
+}
+
+// The Pi OAuth provider (Omit<OAuthProviderInterface, "id"> — Pi supplies the id from
+// the provider name). login/refreshToken/getApiKey are the whole contract.
+export const privateerOAuthProvider = {
+  name: "Privateer account",
+  usesCallbackServer: false,
+  async login(cb: { onDeviceCode?: (info: unknown) => void }) {
+    if (!hasCredentials()) {
+      await runDeviceLogin({
+        onCode: (code) =>
+          cb.onDeviceCode?.({
+            userCode: code.user_code,
+            verificationUri: code.verification_uri_complete ?? code.verification_uri ?? "",
+            intervalSeconds: code.interval,
+            expiresInSeconds: code.expires_in,
+          }),
+      });
+    }
+    return spawnAccountCredentials();
+  },
+  async refreshToken(creds: { refresh: string }) {
+    try {
+      return await refreshAccountCredentials(creds.refresh);
+    } catch {
+      // child token expired/reused → spawn a fresh one from the parent login.
+      return spawnAccountCredentials();
+    }
+  },
+  getApiKey(creds: { access: string }): string {
+    return creds.access;
+  },
+};
+
+// Which privacy channel an account model routes through: NEAR confidential-compute
+// (TEE, attestable) for `near/`-prefixed ids, else a server-side ZDR channel.
+// Ported from tree-cli resolve.ts.
+export function privateerChannel(modelId: string): "tee" | "zdr" {
+  return modelId.startsWith("near/") ? "tee" : "zdr";
+}
+
+export interface AccountPosture {
+  tier: PrivacyTier;
+  teePosture?: "green" | "yellow" | "red";
+  error?: string;
+}
+
+// Posture for an account-channel model. For NEAR models the attestation is fetched
+// through the SERVER proxy (the account's NEAR key stays server-side): the server
+// mints the nonce AND returns the report, so the CLIENT contributes no freshness and
+// can't bind the report to the live TLS key. That is a trust-the-server posture, not
+// client-verified — materially weaker than the direct nearai path (which supplies its
+// own randomNonce). So we must NOT promote it to `tee-verified`: that tier reads as
+// cryptographically proven and, critically, disables pi-privacy's PII gate. We cap a
+// green server posture at `tee-unverified` (honest yellow — the PII gate stays on) and
+// still surface the raw teePosture for display. ZDR-channel models route to
+// zero-retention endpoints server-side, which we can't observe here — a policy claim.
+export async function accountPosture(modelId: string): Promise<AccountPosture> {
+  if (privateerChannel(modelId) === "zdr") {
+    return { tier: "zdr-policy" };
+  }
+  try {
+    const res = await authedFetch(
+      `${serverBaseUrl()}/api/models/near/attestation?model=${encodeURIComponent(modelId)}`,
+    );
+    if (!res.ok) return { tier: "tee-unverified", error: `HTTP ${res.status}` };
+    const data = (await res.json()) as { nonce?: string; report?: unknown };
+    const att = interpretReport(modelId, data.nonce ?? "", data.report ?? {});
+    const tp = teePosture(att);
+    // Cap at client-unverifiable: server-proxied green never earns `tee-verified`.
+    const tier: PrivacyTier = tp === "red" ? "standard" : "tee-unverified";
+    return { tier, teePosture: tp };
+  } catch (e) {
+    return { tier: "tee-unverified", error: (e as Error).message };
+  }
+}
+
+// Extension factory: registers the account provider when a machine login exists. No
+// login → nothing registered (BYO-key only).
+//
+// Registration is SYNCHRONOUS (seeded with the fallback), then refined once the live
+// catalog is fetched. This matters: Pi flushes provider registrations made during the
+// synchronous extension-init pass before it binds extensions, so the `privateer`
+// provider (and its OAuth login path) exist immediately — before the model picker can
+// open. If we instead awaited the network fetch first, the registration could land
+// after the picker built its list, and privateer models would be missing until reopen.
+// registerProvider replaces the provider's models on the second call, and the picker's
+// refresh() re-applies registered providers, so the full list appears once fetched.
+export function makeAccountProvider() {
+  return (pi: {
+    registerProvider?: (name: string, config: unknown) => void;
+  }): void => {
+    if (!hasCredentials() || typeof pi.registerProvider !== "function") return;
+    const register = (ids: string[]): void =>
+      pi.registerProvider!("privateer", {
+        name: "Privateer account",
+        baseUrl: `${serverBaseUrl()}/api/agent/v1`,
+        api: "openai-completions",
+        oauth: privateerOAuthProvider,
+        models: ids.map(seedModel),
+      });
+    register(DEFAULT_MODELS); // immediate: provider exists this tick
+    void fetchAccountModels()
+      .then((ids) => ids.length && register(ids)) // refine to the live catalog
+      .catch(() => {
+        /* keep the fallback model */
+      });
+  };
+}

package/src/providers/catalog.ts

@@ -1,66 +1,78 @@
-import { KNOWN_PROVIDERS, type ProviderName } from "../config/schema.ts";
-import { providerRequiresKey } from "./registry.ts";
+// The provider landscape — the single map of how each of privateer's 21 providers
+// becomes reachable under Pi. Written after verifying (2026-07-07) that:
+//   - pi-ai ships STATIC model catalogs for its 14 built-in providers, so they're
+//     selectable once a key is present — privateer emits NO models.json entry for them;
+//   - the `pi-privacy` extension registers the 5 privacy providers (tinfoil, nearai,
+//     venice, ollama, custom) at load — privateer emits NO entry for them either;
+//   - so the ONLY provider this generator must emit is `qwen` (config-only,
+//     non-privacy, no built-in catalog), and `privateer` (the account OAuth channel)
+//     is handled in code, not config (Phase 4).
+//
+// The plan (Appendix A) assumed we'd generate the whole models.json; Pi's built-in
+// catalogs + pi-privacy made most of that redundant. This map keeps the accounting
+// explicit so nothing silently falls through.
 
-// Human-facing metadata for each provider, used by the onboarding flow: a display
-// label, where to get an API key, and the model to default to when the provider is
-// chosen first. Keeps the registry (wiring) separate from presentation.
-export interface ProviderMeta {
-  name: ProviderName;
-  label: string;
-  requiresKey: boolean;
-  defaultModel: string; // "provider:model" picked when this provider is selected first
-  keyHint: string; // where to obtain a key, or a note for keyless providers
-  baseURLDefault?: string; // shown as the placeholder for keyless/local providers
+export type ProviderSource =
+  | "pi-builtin" // pi-ai ships the provider + its model catalog (needs only a key)
+  | "pi-privacy" // registered by the pi-privacy extension at load
+  | "generate" // privateer must emit a models.json entry (config-only, no built-in)
+  | "account"; // the privateer account channel — OAuth in code, not config
+
+export type ProviderApi = "openai-completions" | "openai-responses" | "anthropic-messages";
+
+export interface ProviderEntry {
+  id: string;
+  source: ProviderSource;
+  // For `generate` providers: the config a models.json entry needs.
+  baseUrl?: string;
+  api?: ProviderApi;
+  keyEnv?: string; // env template ${...}; Pi resolves it (or auth.json wins)
+  compat?: Record<string, unknown>;
+  seedModels?: string[]; // provisional ids until live listing refines them
+  // Optional nuance override for a built-in (api/compat differs from pi-ai default).
+  // Not emitted yet — overriding a built-in can drop its model catalog; revisit once
+  // Pi's override-merge semantics are confirmed. Documented here so it's not lost.
+  overrideNote?: string;
 }
 
-export const PROVIDER_META: Record<ProviderName, ProviderMeta> = {
-  anthropic: {
-    name: "anthropic",
-    label: "Anthropic",
-    requiresKey: providerRequiresKey("anthropic"),
-    defaultModel: "anthropic:claude-opus-4-8",
-    keyHint: "console.anthropic.com/settings/keys",
-  },
-  openai: {
-    name: "openai",
-    label: "OpenAI",
-    requiresKey: providerRequiresKey("openai"),
-    defaultModel: "openai:gpt-4o",
-    keyHint: "platform.openai.com/api-keys",
-  },
-  openrouter: {
-    name: "openrouter",
-    label: "OpenRouter",
-    requiresKey: providerRequiresKey("openrouter"),
-    defaultModel: "openrouter:anthropic/claude-opus-4.8",
-    keyHint: "openrouter.ai/keys",
-  },
-  ollama: {
-    name: "ollama",
-    label: "Ollama (local)",
-    requiresKey: providerRequiresKey("ollama"),
-    defaultModel: "ollama:llama3.1",
-    keyHint: "runs locally — no key needed",
-    baseURLDefault: "http://localhost:11434/api",
+// Ordered like KNOWN_PROVIDERS (tree-cli schema.ts) for a stable picker order.
+export const PROVIDERS: ProviderEntry[] = [
+  { id: "openrouter", source: "pi-builtin", overrideNote: "ZDR routing handled by pi-privacy" },
+  { id: "anthropic", source: "pi-builtin" },
+  { id: "openai", source: "pi-builtin", overrideNote: "0.2 used chat-completions, not responses" },
+  { id: "google", source: "pi-builtin" },
+  { id: "xai", source: "pi-builtin" },
+  { id: "groq", source: "pi-builtin" },
+  { id: "mistral", source: "pi-builtin" },
+  { id: "zai", source: "pi-builtin", overrideNote: "0.2 baseUrl …/api/paas/v4; compat.thinkingFormat zai" },
+  { id: "moonshot", source: "pi-builtin" },
+  { id: "cerebras", source: "pi-builtin" },
+  { id: "fireworks", source: "pi-builtin" },
+  { id: "together", source: "pi-builtin", overrideNote: "compat.thinkingFormat together" },
+  { id: "deepseek", source: "pi-builtin", overrideNote: "compat.thinkingFormat deepseek" },
+  { id: "minimax", source: "pi-builtin", overrideNote: "0.2 used …/v1 openai-compat, not anthropic-messages" },
+  {
+    id: "qwen",
+    source: "generate",
+    baseUrl: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
+    api: "openai-completions",
+    keyEnv: "${DASHSCOPE_API_KEY}",
+    compat: { thinkingFormat: "qwen" },
+    seedModels: ["qwen3-max", "qwen3-coder-plus", "qwen-max-latest"],
   },
-  nearai: {
-    name: "nearai",
-    label: "NEAR AI (private TEE inference)",
-    requiresKey: providerRequiresKey("nearai"),
-    defaultModel: "nearai:zai-org/GLM-5.1-FP8",
-    keyHint: "cloud.near.ai → API Keys",
-  },
-  privateer: {
-    name: "privateer",
-    // Default to a NEAR confidential-compute (TEE) model: it's the strongest
-    // privacy guarantee, runs through the same billed agent endpoint, and was
-    // verified to pass agent tool_calls. Switch to any listed model with /model.
-    label: "Privateer account (billed to your subscription)",
-    requiresKey: providerRequiresKey("privateer"),
-    defaultModel: "privateer:near/deepseek-ai/DeepSeek-V4-Flash",
-    keyHint: "sign in with /login — no API key needed",
-  },
-};
+  { id: "ollama", source: "pi-privacy" },
+  { id: "nearai", source: "pi-privacy" },
+  { id: "tinfoil", source: "pi-privacy" },
+  { id: "venice", source: "pi-privacy" },
+  { id: "custom", source: "pi-privacy" },
+  { id: "privateer", source: "account" },
+];
 
-// Provider metadata in display order.
-export const PROVIDER_LIST: ProviderMeta[] = KNOWN_PROVIDERS.map((n) => PROVIDER_META[n]);
+export const PROVIDER_BY_ID: Record<string, ProviderEntry> = Object.fromEntries(
+  PROVIDERS.map((p) => [p.id, p]),
+);
+
+// Providers this generator is responsible for emitting into models.json.
+export function providersToGenerate(): ProviderEntry[] {
+  return PROVIDERS.filter((p) => p.source === "generate");
+}