privateer-agent 0.6.7 → 0.6.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "description": "Privateer — a provider-agnostic, safe-by-default terminal coding agent with TEE/Tinfoil attestation, rebuilt on the Pi toolkit. Bring your own model across 20 providers.",
   "type": "module",
   "license": "MIT",

package/patches/@earendil-works+pi-coding-agent+0.80.3.patch

@@ -1,8 +1,23 @@
 diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/core/agent-session.js b/node_modules/@earendil-works/pi-coding-agent/dist/core/agent-session.js
-index e223ce1..2bdab10 100644
+index e223ce1..3615d74 100644
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/core/agent-session.js
 +++ b/node_modules/@earendil-works/pi-coding-agent/dist/core/agent-session.js
-@@ -711,6 +711,15 @@ export class AgentSession {
+@@ -163,6 +163,14 @@ export class AgentSession {
+         }
+         const isOAuth = this._modelRegistry.isUsingOAuth(model);
+         if (isOAuth) {
++            // Privateer patch: the account channel has no API key that could expire —
++            // the terminal is simply not signed in yet (a fresh install now boots on
++            // `privateer/*`, which is the model it will run once logged in). Stock Pi's
++            // wording describes a state that user was never in, and its "/login
++            // privateer" bypasses the branded sign-in. auth-guidance owns the words.
++            if (model.provider === "privateer") {
++                throw new Error(formatNoApiKeyFoundMessage(model.provider));
++            }
+             throw new Error(`Authentication failed for "${model.provider}". ` +
+                 `Credentials may have expired or network is unavailable. ` +
+                 `Run '/login ${model.provider}' to re-authenticate.`);
+@@ -711,6 +719,15 @@ export class AgentSession {
                  finalError: msg.errorMessage,
              });
              this._retryAttempt = 0;
@@ -18,11 +33,72 @@ index e223ce1..2bdab10 100644
          }
          if (await this._checkCompaction(msg)) {
              return true;
+diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/core/auth-guidance.js b/node_modules/@earendil-works/pi-coding-agent/dist/core/auth-guidance.js
+index 197bccc..27f6429 100644
+--- a/node_modules/@earendil-works/pi-coding-agent/dist/core/auth-guidance.js
++++ b/node_modules/@earendil-works/pi-coding-agent/dist/core/auth-guidance.js
+@@ -1,21 +1,33 @@
+ import { join } from "node:path";
+ import { getDocsPath } from "../config.js";
+ const UNKNOWN_PROVIDER = "unknown";
++// Privateer patch: speak Privateer, and stop printing absolute node_modules doc paths.
++//
++// Stock Pi answered every auth failure with four lines, two of them full paths into
++// node_modules/@earendil-works/pi-coding-agent/docs/. On a terminal that isn't signed
++// in, that wall repeats on every prompt and buries the one sentence that matters. It
++// also told a Privateer user to go find a provider API key when their subscription
++// already covers the model. Same information, one actionable line.
+ export function getProviderLoginHelp() {
+-    return [
+-        "Use /login to log into a provider via OAuth or API key. See:",
+-        `  ${join(getDocsPath(), "providers.md")}`,
+-        `  ${join(getDocsPath(), "models.md")}`,
+-    ].join("\n");
++    return "Run /login to connect your Privateer account, or /login keys to use your own provider API key.";
+ }
+ export function formatNoModelsAvailableMessage() {
+     return `No models available. ${getProviderLoginHelp()}`;
+ }
+ export function formatNoModelSelectedMessage() {
+-    return `No model selected.\n\n${getProviderLoginHelp()}\n\nThen use /model to select a model.`;
++    return `No model selected. ${getProviderLoginHelp()}\n\nThen use /models to select a model.`;
+ }
+ export function formatNoApiKeyFoundMessage(provider) {
++    // The account channel: there is no API key to find — you're just not signed in (or
++    // the session didn't arm). Naming the real problem is the whole fix here.
++    if (provider === "privateer") {
++        return "This terminal isn't signed in to Privateer, so it can't run your subscription models.\n\nRun /login — it takes one approval in the Privateer app, and no API key.";
++    }
+     const providerDisplay = provider === UNKNOWN_PROVIDER ? "the selected model" : provider;
+     return `No API key found for ${providerDisplay}.\n\n${getProviderLoginHelp()}`;
+ }
++// Kept so the module's imports stay meaningful for anything that still wants the docs.
++export function getProviderDocsPaths() {
++    return [join(getDocsPath(), "providers.md"), join(getDocsPath(), "models.md")];
++}
+ //# sourceMappingURL=auth-guidance.js.map
 diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js
-index 5d65200..a997ad7 100644
+index 5d65200..0a08971 100644
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js
 +++ b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js
-@@ -2042,7 +2042,17 @@ export class InteractiveMode {
+@@ -301,9 +301,15 @@ export class InteractiveMode {
+     }
+     getBuiltInCommandConflictDiagnostics(extensionRunner) {
+         const builtinNames = new Set(BUILTIN_SLASH_COMMANDS.map((command) => command.name));
++        // Privateer redirect: these built-ins are patched above to dispatch into the
++        // Privateer extension, so an extension command of the same name is deliberate,
++        // not a mistake — and it stays live in the modes that have no such redirect
++        // (rpc, print). Warning about it just tells the user their own shipped auth
++        // commands are broken when they aren't.
++        const redirectedBuiltins = new Set(["login", "logout"]);
+         return extensionRunner
+             .getRegisteredCommands()
+-            .filter((command) => builtinNames.has(command.name))
++            .filter((command) => builtinNames.has(command.name) && !redirectedBuiltins.has(command.name))
+             .map((command) => ({
+             type: "warning",
+             message: command.invocationName === command.name
+@@ -2042,7 +2048,17 @@ export class InteractiveMode {
              if (text === "/model" || text.startsWith("/model ")) {
                  const searchTerm = text.startsWith("/model ") ? text.slice(7).trim() : undefined;
                  this.editor.setText("");
@@ -41,3 +117,51 @@ index 5d65200..a997ad7 100644
                  return;
              }
              if (text === "/export" || text.startsWith("/export ")) {
+@@ -2105,14 +2121,44 @@ export class InteractiveMode {
+                 this.editor.setText("");
+                 return;
+             }
+-            if (text === "/login") {
+-                this.showOAuthSelector("login");
++            if (text === "/login" || text.startsWith("/login ")) {
+                 this.editor.setText("");
++                // Privateer redirect: a bare /login IS the account sign-in. Pi's built-in
++                // opens a two-step menu ("Use a subscription" → a list of 20+ providers)
++                // that buries the one option a Privateer user wants, and — because it
++                // only auto-selects a model when the current one is UNKNOWN — a
++                // successful login through it left the terminal on its launch model and
++                // the next prompt died on "No API key found". The extension's own flow
++                // signs in, arms the account channel, and selects the model.
++                // `/login <anything>` (documented as `/login keys`) still opens Pi's own
++                // selector, so BYO provider keys stay reachable; and if the extension
++                // isn't loaded we fall back to Pi's selector for both.
++                if (text === "/login" && this.isExtensionCommand("/privateer")) {
++                    await this.session.prompt("/privateer login");
++                }
++                else {
++                    this.showOAuthSelector("login");
++                }
+                 return;
+             }
+             if (text === "/logout") {
+-                this.showOAuthSelector("logout");
+                 this.editor.setText("");
++                // Privateer redirect: /logout must actually log you out. Pi's built-in
++                // only clears Pi's authStorage, which leaves the Privateer machine
++                // login in ~/.privateer/credentials.json untouched — so on a signed-in
++                // machine it reported "No stored credentials to remove" and changed
++                // nothing. Route to the account logout instead, which revokes this
++                // machine's whole token family (login + every terminal spawned from it)
++                // and wipes local state. Target is `/privateer logout` rather than the
++                // extension's own `/logout` so this can never re-enter the branch it
++                // was dispatched from. Falls back to Pi's selector when the extension
++                // isn't loaded.
++                if (this.isExtensionCommand("/privateer")) {
++                    await this.session.prompt("/privateer logout");
++                }
++                else {
++                    this.showOAuthSelector("logout");
++                }
+                 return;
+             }
+             if (text === "/new") {

package/src/auth/accountSessions.ts

@@ -144,7 +144,10 @@ export function dropOwnedSession(pid: number): void {
   writeRegistry(reg);
 }
 
-// Test seam: wipe the registry file.
+// Wipe the registry. Used by logout(), where the server has just revoked this
+// machine's whole token family: every entry now names a dead session, and leaving
+// them behind would offer the next login a list of orphans to "reclaim" that can
+// only fail. Also a test seam.
 export function clearOwnedSessions(): void {
   try {
     rmSync(accountSessionsPath(), { force: true });

package/src/auth/privateer.ts

@@ -21,6 +21,7 @@ import {
   forgetOwnedSession,
   orphanedSessions,
   dropOwnedSession,
+  clearOwnedSessions,
 } from "./accountSessions.ts";
 import { isAccountCapCode } from "../engine/errors.ts";
 import { terminalPublicKeyBase64 } from "../crypto/terminalKey.ts";
@@ -94,9 +95,37 @@ export function defaultDeviceLabel(): string {
   }
 }
 
-// ── Credential storage (0600, like saveGlobalConfig) ─────────────────────────
+// ── Cross-instance state ─────────────────────────────────────────────────────
+//
+// Pi loads every extension with a FRESH jiti instance (`moduleCache: false`, see
+// core/extensions/loader.js), so privateer-brand and privateer-account each get their
+// OWN copy of this module — separate credential cache, separate listener sets.
+//
+// That silently broke /login. The account provider's OAuth login() ran inside the
+// privateer-account copy and called notifySignedIn() there, while the UI's listener
+// (the one that switches the live session onto a model the account can actually
+// serve) was registered on the privateer-brand copy. The signal never crossed, so a
+// successful sign-in left the terminal pinned to its keyless launch model and the
+// very next prompt died with "No API key found for openrouter" — exactly the state
+// the login was supposed to fix. The same split let a /logout in one copy leave a
+// stale `user` memoized in another.
+//
+// So anything that must be observed ACROSS extensions lives on globalThis, keyed by
+// a registered Symbol — one bus, however many module instances jiti creates.
+const SHARED = Symbol.for("privateer.auth.shared");
+
+interface SharedAuthState {
+  cache: Credentials | null;
+  signedIn: Set<SignedInListener>;
+  expired: Set<SessionExpiredListener>;
+}
 
-let _cache: Credentials | null | undefined;
+function shared(): SharedAuthState {
+  const g = globalThis as { [SHARED]?: SharedAuthState };
+  return (g[SHARED] ??= { cache: null, signedIn: new Set(), expired: new Set() });
+}
+
+// ── Credential storage (0600, like saveGlobalConfig) ─────────────────────────
 
 // Per-terminal child session (see spawnChildSession). Held in memory ONLY — it
 // is never written to the shared credentials file, so each running terminal
@@ -144,15 +173,16 @@ export function loadCredentials(): Credentials | null {
   // memoized the pre-login "absent" as null, that instance would report "not signed
   // in" forever (e.g. /remote-access refusing after a successful sign-in). Re-reading
   // disk on each miss lets a later call see what a sign-in just wrote.
-  if (_cache) return _cache;
+  const state = shared();
+  if (state.cache) return state.cache;
   const path = credentialsPath();
   if (!existsSync(path)) return null;
   try {
-    _cache = JSON.parse(readFileSync(path, "utf8")) as Credentials;
+    state.cache = JSON.parse(readFileSync(path, "utf8")) as Credentials;
   } catch {
     return null;
   }
-  return _cache;
+  return state.cache;
 }
 
 export function saveCredentials(creds: Credentials): void {
@@ -162,7 +192,7 @@ export function saveCredentials(creds: Credentials): void {
   const path = credentialsPath();
   writeFileSync(path, JSON.stringify(creds, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
   tryChmod(path, 0o600);
-  _cache = creds;
+  shared().cache = creds;
 }
 
 export function clearCredentials(): void {
@@ -174,7 +204,7 @@ export function clearCredentials(): void {
   // Drop the pinned account signing key too — it belongs to the account that just
   // signed out; a different account must re-pin its own at link.
   clearAccountSignKey();
-  _cache = null;
+  shared().cache = null;
   _child = null;
   _account = null;
 }
@@ -204,15 +234,15 @@ function tryChmod(path: string, mode: number): void {
 // stops working; the UI subscribes to announce the sign-out prominently.
 
 type SessionExpiredListener = () => void;
-const _expiredListeners = new Set<SessionExpiredListener>();
 
 export function onSessionExpired(listener: SessionExpiredListener): () => void {
-  _expiredListeners.add(listener);
-  return () => _expiredListeners.delete(listener);
+  const listeners = shared().expired;
+  listeners.add(listener);
+  return () => listeners.delete(listener);
 }
 
 function notifySessionExpired(): void {
-  for (const listener of _expiredListeners) {
+  for (const listener of shared().expired) {
     try {
       listener();
     } catch {
@@ -248,17 +278,19 @@ export function handleServerRevoke(): void {
 // A listener here refreshes the UI regardless of which path the user took.
 
 type SignedInListener = () => void;
-const _signedInListeners = new Set<SignedInListener>();
 
 export function onSignedIn(listener: SignedInListener): () => void {
-  _signedInListeners.add(listener);
-  return () => _signedInListeners.delete(listener);
+  const listeners = shared().signedIn;
+  listeners.add(listener);
+  return () => listeners.delete(listener);
 }
 
 // Emit the sign-in signal. Exported so the account OAuth provider can announce a
 // completed subscription login on the already-linked path (see the note above).
+// Listeners MUST be idempotent: a device-code login fires this once the credentials
+// land and again once the account channel is armed (see privateerOAuthProvider.login).
 export function notifySignedIn(): void {
-  for (const listener of _signedInListeners) {
+  for (const listener of shared().signedIn) {
     try {
       listener();
     } catch {
@@ -602,15 +634,55 @@ export async function revokeLocalSessions(timeoutMs = 1500): Promise<void> {
 // ── Logout ───────────────────────────────────────────────────────────────────
 
 /**
- * Log out this terminal: revoke its session server-side (best effort) and wipe
- * local credentials. Other devices/sessions are untouched.
+ * Log out this MACHINE: revoke the machine login and every terminal session
+ * spawned from it, then wipe all local auth state. Other devices (the phone app,
+ * another laptop) keep their own logins — each has its own token family.
+ *
+ * Two things this deliberately does NOT do, both of which it used to:
+ *
+ * 1. It does not POST /auth/logout. That endpoint calls revokeAllUserSessions —
+ *    the entire ACCOUNT, every device including the app — while this function's
+ *    contract (and its old doc comment) promised the opposite. Signing out of one
+ *    terminal must not sign you out of your phone.
+ *
+ * 2. It does not go through apiRequest/authedFetch. Those authenticate with a CHILD
+ *    session and spawn one if absent — so at the per-machine child cap the spawn
+ *    throws 429 and the logout never reaches the server AT ALL. That was a deadlock:
+ *    the cap blocked the one call that clears the cap. We authenticate with the
+ *    PARENT instead, which is never subject to the cap.
+ *
+ * The parent's stored access token is usually expired (it is minted once at /login
+ * and never rotated — the refresh token is the liveness proof), so we rotate for a
+ * fresh one first. Rotation is free here precisely because we are destroying the
+ * credential either way: nothing downstream needs the token we burn. rotateSession
+ * is the no-ownership-side-effects variant, so this cannot clobber the registry
+ * entry of a session we are about to revoke wholesale anyway.
+ *
+ * DELETE /auth/session/current then revokes the parent's family, which the server
+ * cascades to every row with `parentFamilyId === familyId` — i.e. all this machine's
+ * terminals, including the orphans left by terminals that died without their
+ * shutdown hook. That cascade is what makes an accumulated cap self-clearing:
+ * logout, log back in, and the machine starts from zero live children.
+ *
+ * Local state is wiped unconditionally at the end, whatever the network did. A
+ * logout that can't reach the server must still leave you logged out locally —
+ * the rows it failed to revoke age out on their TTL.
  */
 export async function logout(): Promise<void> {
-  try {
-    await apiRequest("/auth/logout", { method: "POST" });
-  } catch {
-    /* best effort — clear locally regardless */
+  const parent = loadCredentials();
+  if (parent) {
+    try {
+      const fresh = await rotateSession(parent.refreshToken);
+      await deleteSession(fresh.access, 5000);
+    } catch {
+      /* offline, or the login was already dead server-side — wipe locally anyway */
+    }
   }
+  // In-memory sessions are gone with the family above; drop the handles so nothing
+  // tries to revoke them individually on the way out.
+  _child = null;
+  _account = null;
+  clearOwnedSessions(); // every entry named a session the cascade just killed
   clearCredentials();
 }
 
@@ -622,7 +694,7 @@ export async function logout(): Promise<void> {
 // = the JWT's exp (so Pi refreshes just before the server would reject it). These are
 // independent of authedFetch's in-memory _child (Pi owns this credential's lifecycle).
 
-interface AccountCredential {
+export interface AccountCredential {
   access: string;
   refresh: string;
   expires: number; // ms epoch

package/src/cli/chat.ts

@@ -478,8 +478,8 @@ async function main() {
       });
       console.log(`${GREEN}Signed in as ${user.email ?? user.id}.${RESET}`);
       // Move the live session onto a confidential model right away, so the next prompt
-      // doesn't dead-end on the keyless launch model ("No API key found for openrouter").
-      // resolveSignedInModel prefers Tinfoil GLM 5.2, else the account's NEAR channel;
+      // doesn't dead-end on the launch model's missing key. resolveSignedInModel picks
+      // Tinfoil GLM 5.2 — direct with a Tinfoil key, over the subscription otherwise;
       // PRIVATEER_MODEL (a deliberate override) is respected and left alone.
       if (!process.env.PRIVATEER_MODEL?.trim()) {
         const target = resolveSignedInModel();

package/src/daemon/index.ts

@@ -326,7 +326,7 @@ export class Daemon {
         // The account signed this daemon out server-side (revoked from the app's Linked
         // Devices). Beyond ending remote access (onTerminate), this wipes the machine
         // login: drop the relay and clear credentials, so routines/tasks stop cleanly
-        // instead of dead-ending on a 401 each run. Stays idle until you /signin on this
+        // instead of dead-ending on a 401 each run. Stays idle until you /login on this
         // machine and restart the daemon (the relayTerminated guard, as with onTerminate).
         onRevoked: () => {
           this.relayTerminated = true;
@@ -334,7 +334,7 @@ export class Daemon {
           this.relay?.stop();
           this.relay = undefined;
           handleServerRevoke();
-          log("account signed out from the app (session revoked) — cleared credentials; idle until you run /signin on this machine and restart the daemon");
+          log("account signed out from the app (session revoked) — cleared credentials; idle until you run /login on this machine and restart the daemon");
         },
         onStatus: (text) => log(`relay: ${text}`),
         onDisconnected: () => {

package/src/mcp/catalog.ts

@@ -0,0 +1,178 @@
+/**
+ * Curated MCP connector catalog for the `/connect` TUI picker — the terminal's
+ * counterpart to the app's quick-add grid (treeview/client/components/mcpCatalog.ts).
+ * Kept in sync with that list by hand: it is small, changes rarely, and duplicating
+ * eight entries is cheaper than making the agent depend on the client package.
+ *
+ * `needs` drives what the wizard asks for after you pick an entry:
+ *   token — one prompt per env key (masked); `credUrl` is shown as "get one at …"
+ *   path  — one prompt replacing the `fill` placeholder ARG (a folder, a DSN)
+ *   oauth — nothing to type here; you authorize in a browser on THIS machine
+ *   none  — runs locally with no credentials, save it as-is
+ *
+ * Keep this list conservative and correct: a broken command in the catalog is worse
+ * than an omission — the user has no way to tell "this server is misconfigured" from
+ * "MCP is broken". tests/mcpCatalog.test.ts enforces the structural invariants.
+ */
+import type { McpDraft, McpTransport } from "../remote/mcpControl.ts";
+
+export type CatalogNeeds = "token" | "path" | "oauth" | "none";
+
+export interface CatalogEntry {
+  // Stable key for the picker; also the default server name written to config.
+  id: string;
+  name: string;
+  label: string; // display name in the picker
+  blurb: string; // one line, lowercase-ish, says what it gives the agent
+  transport: McpTransport;
+  command?: string; // stdio
+  args?: string[]; // stdio
+  env?: Record<string, string>; // env KEYS the user must fill (values are "")
+  url?: string; // http
+  oauth?: boolean; // http servers that negotiate OAuth
+  needs: CatalogNeeds;
+  // needs:"token" → the PRIMARY env key (others are still prompted for).
+  // needs:"path"  → the placeholder ARG to replace with a real path/DSN.
+  fill?: string;
+  // Where to get the credential, shown as a hint in the form.
+  credUrl?: string;
+}
+
+export const MCP_CATALOG: CatalogEntry[] = [
+  {
+    id: "github",
+    name: "github",
+    label: "GitHub",
+    blurb: "Repos, issues, and pull requests.",
+    transport: "stdio",
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-github"],
+    env: { GITHUB_PERSONAL_ACCESS_TOKEN: "" },
+    needs: "token",
+    fill: "GITHUB_PERSONAL_ACCESS_TOKEN",
+    credUrl: "https://github.com/settings/tokens",
+  },
+  {
+    id: "filesystem",
+    name: "filesystem",
+    label: "Filesystem",
+    blurb: "Read and write files in a folder you pick.",
+    transport: "stdio",
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/folder"],
+    needs: "path",
+    fill: "/path/to/folder",
+  },
+  {
+    id: "notion",
+    name: "notion",
+    label: "Notion",
+    blurb: "Pages, databases, and blocks.",
+    transport: "stdio",
+    command: "npx",
+    args: ["-y", "@notionhq/notion-mcp-server"],
+    env: { NOTION_TOKEN: "" },
+    needs: "token",
+    fill: "NOTION_TOKEN",
+    credUrl: "https://www.notion.so/my-integrations",
+  },
+  {
+    id: "linear",
+    name: "linear",
+    label: "Linear",
+    blurb: "Issues and projects. Sign in via browser.",
+    transport: "http",
+    url: "https://mcp.linear.app/sse",
+    oauth: true,
+    needs: "oauth",
+  },
+  {
+    id: "slack",
+    name: "slack",
+    label: "Slack",
+    blurb: "Read and post to channels.",
+    transport: "stdio",
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-slack"],
+    env: { SLACK_BOT_TOKEN: "", SLACK_TEAM_ID: "" },
+    needs: "token",
+    fill: "SLACK_BOT_TOKEN",
+    credUrl: "https://api.slack.com/apps",
+  },
+  {
+    id: "postgres",
+    name: "postgres",
+    label: "PostgreSQL",
+    blurb: "Query a Postgres database (read-only).",
+    transport: "stdio",
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"],
+    needs: "path",
+    fill: "postgresql://localhost/mydb",
+  },
+  {
+    id: "playwright",
+    name: "playwright",
+    label: "Browser (Playwright)",
+    blurb: "Drive a real browser to fetch and click.",
+    transport: "stdio",
+    command: "npx",
+    args: ["-y", "@playwright/mcp@latest"],
+    needs: "none",
+  },
+  {
+    id: "memory",
+    name: "memory",
+    label: "Memory",
+    blurb: "A local knowledge-graph scratchpad.",
+    transport: "stdio",
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-memory"],
+    needs: "none",
+  },
+];
+
+export function catalogEntry(id: string): CatalogEntry | undefined {
+  return MCP_CATALOG.find((e) => e.id === id);
+}
+
+// The env keys the wizard prompts for, primary (`fill`) first so the token you
+// actually care about is asked for before the incidentals (Slack's TEAM_ID).
+export function promptOrder(e: CatalogEntry): string[] {
+  const keys = Object.keys(e.env ?? {});
+  if (!e.fill || !keys.includes(e.fill)) return keys;
+  return [e.fill, ...keys.filter((k) => k !== e.fill)];
+}
+
+// Build the draft mcpControl.save() persists, from a catalog entry plus whatever the
+// user typed. PURE — the whole reason this lives outside the TUI component.
+//
+//   input.env  — env VALUES by key. An empty/omitted value is passed through as ""
+//                and mcpControl treats that as "clear this key" — so a skipped
+//                optional credential is simply absent, never a bogus empty one.
+//   input.fill — the real path/DSN replacing the placeholder ARG (needs:"path").
+export function draftFromCatalog(
+  e: CatalogEntry,
+  input: { env?: Record<string, string>; fill?: string } = {},
+): McpDraft {
+  const draft: McpDraft = { name: e.name, transport: e.transport };
+
+  if (e.transport === "stdio") {
+    draft.command = e.command;
+    // Replace the placeholder ARG in place (not by index) so reordering the catalog's
+    // args can never silently overwrite the wrong one.
+    const filled = input.fill?.trim();
+    draft.args = (e.args ?? []).map((a) => (e.fill && a === e.fill && filled ? filled : a));
+  } else {
+    draft.url = e.url;
+    draft.oauth = e.oauth ?? true;
+  }
+
+  const keys = Object.keys(e.env ?? {});
+  if (keys.length > 0) {
+    const env: Record<string, string> = {};
+    for (const k of keys) env[k] = input.env?.[k] ?? "";
+    draft.env = env;
+  }
+  return draft;
+}