@polylogicai/polycode 1.1.4 → 1.1.6

package/README.md

@@ -60,10 +60,13 @@ polycode runs a standard agentic loop: you ask, it thinks, it uses tools, it ret
 - `read_file` read a file relative to the working directory
 - `write_file` write a file to the working directory
 - `edit_file` replace a substring in a file
-- `glob` list files matching a pattern
-- `grep` search for a regex in files
+- `glob` list files matching a pattern (cross-platform, pure Node.js)
+- `grep` search for a regex in files (cross-platform, pure Node.js)
+- `describe_image` analyze an image file via a vision model
+- `fetch_url` fetch a URL and return the body as readable text
+- `web_search` search the web and return titles, URLs, and snippets
 
-All tool calls are sandboxed to the working directory. polycode refuses any path that escapes it.
+All file tool calls are sandboxed to the working directory. polycode refuses any path that escapes it. `fetch_url` refuses loopback and private network addresses.
 
 ## Session history
 
@@ -80,12 +83,31 @@ Inside the REPL:
 
 ```
 /help      show all commands
+/key       save an API key (Groq, Anthropic, OpenAI). Input is masked on real terminals.
 /clear     clear the terminal
 /history   show the session history file path and row count
 /verify    verify session history integrity
 /exit      leave polycode
 ```
 
+## Paste handling
+
+When you paste multi-line content into polycode, the terminal collapses it to a marker like `[Pasted #1 (20 lines)]` in the prompt line. The full content is still sent to the agent — only the display is compressed. You can paste a whole file, a stack trace, or a long URL and polycode will treat it as one event.
+
+## Saving API keys (never in chat)
+
+polycode never accepts API keys pasted into the chat — the local secret scrubber blocks any message that matches a key pattern before it reaches the model. To save a key the right way:
+
+```
+# Inside the REPL
+/key
+
+# Or from your shell
+polycode login
+```
+
+Both flows read the key through a masked prompt and save it to `~/.polycode/secrets.env` with `chmod 600`. The model never sees it. Auto-detects Groq, Anthropic, and OpenAI from the key prefix.
+
 ## Command-line flags
 
 ```

package/bin/polycode.mjs

@@ -15,6 +15,8 @@ import { computeAgencyReceipt, formatReceipt } from '../lib/agency-receipt.mjs';
 import { fireHook } from '../lib/hooks.mjs';
 import { compilePacket } from '../lib/compiler.mjs';
 import { loadAnthropicKeys, reportKeyStatus } from '../lib/inference-router.mjs';
+import { runInteractiveKeyFlow, PROVIDERS, getProviderById } from '../lib/key-store.mjs';
+import { readPasteAwareLine, enableBracketedPaste, disableBracketedPaste } from '../lib/paste-aware-prompt.mjs';
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, dirname, resolve } from 'node:path';
@@ -24,7 +26,10 @@ import { fileURLToPath } from 'node:url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const PACKAGE_JSON = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
-import * as readline from 'node:readline/promises';
+// node:readline is intentionally NOT imported. The REPL owns stdin via the
+// paste-aware reader in lib/paste-aware-prompt.mjs; slash commands that need
+// masked input call readMaskedInput in lib/key-store.mjs. Any readline
+// import here would reintroduce the v1.1.5 double-echo bug.
 import { stdin, stdout, exit, argv, env, cwd as getCwd } from 'node:process';
 import 'dotenv/config';
 
@@ -155,6 +160,7 @@ const HELP = `${BANNER}
 ${C.bold}Usage${C.reset}
   polycode                          Interactive session
   polycode "fix the failing test"   One-shot mode
+  polycode login                    Save an API key (Groq, Anthropic, OpenAI). Input is masked.
   polycode --version                Print version
   polycode --help                   Print this message
   polycode --history                Print session history status
@@ -257,7 +263,12 @@ async function runOneShot(message, opts) {
 }
 
 async function runRepl(opts) {
-  const rl = readline.createInterface({ input: stdin, output: stdout });
+  // Single stdin owner. Do NOT create a readline interface here. The
+  // paste-aware reader (lib/paste-aware-prompt.mjs) owns stdin for the
+  // entire REPL lifetime, and slash commands that need line input fall
+  // through to the raw-mode readMaskedInput helper in lib/key-store.mjs.
+  // Running readline alongside a raw-mode consumer causes every keystroke
+  // to echo twice, which is the v1.1.5 double-echo bug this release fixes.
   stdout.write(BANNER + '\n');
   if (opts.hostedMode) {
     stdout.write(`${C.dim}hosted tier: 60 turns/hour via polylogicai.com. Set GROQ_API_KEY for unlimited use.${C.reset}\n`);
@@ -270,26 +281,72 @@ async function runRepl(opts) {
   }
   stdout.write(`${C.dim}type /help for commands. ctrl+c or /exit to leave.${C.reset}\n\n`);
 
+  enableBracketedPaste();
+
   try {
     while (true) {
-      const line = await rl.question(`${C.bold}${C.amber}> ${C.reset}`);
-      if (!line.trim()) continue;
-
-      if (line.startsWith('/')) {
-        const result = await dispatchSlash(line, { canon: opts.canon, state: opts.state, stdout });
+      let userInput;
+      try {
+        userInput = await readPasteAwareLine(`${C.bold}${C.amber}> ${C.reset}`);
+      } catch (err) {
+        if (err && err.message === 'cancelled') break;
+        throw err;
+      }
+      const content = userInput.content;
+      if (!content.trim()) continue;
+
+      if (content.startsWith('/')) {
+        const result = await dispatchSlash(content, {
+          canon: opts.canon,
+          state: opts.state,
+          stdout,
+          loop: opts.loop,
+          rl: null,
+        });
         if (result.exit) break;
         stdout.write('\n');
         continue;
       }
 
-      await runOneShot(line, opts);
+      if (userInput.pastes && userInput.pastes.length > 0) {
+        for (const p of userInput.pastes) {
+          opts.canon.append('paste', { ordinal: p.ordinal, lines: p.lines, bytes: p.bytes });
+        }
+      }
+
+      await runOneShot(content, opts);
       stdout.write('\n');
     }
   } finally {
-    rl.close();
+    disableBracketedPaste();
   }
 }
 
+async function runLoginSubcommand(args) {
+  resolveConfigDir();
+  const providerHint = args.find((a) => !a.startsWith('-')) || null;
+  if (providerHint && !getProviderById(providerHint)) {
+    stdout.write(`${C.red}unknown provider${C.reset}: ${providerHint}. Known: ${PROVIDERS.map((p) => p.id).join(', ')}\n`);
+    exit(1);
+  }
+  stdout.write(`${C.bold}polycode login${C.reset}\n`);
+  stdout.write(`${C.dim}Your key will be saved locally to ~/.polycode/secrets.env (chmod 600) and never sent to the model.${C.reset}\n`);
+  if (!providerHint) {
+    stdout.write(`${C.dim}Supported providers: ${PROVIDERS.map((p) => `${p.name} (${p.envVar})`).join(', ')}. polycode will auto-detect from the key prefix.${C.reset}\n`);
+  }
+  const result = await runInteractiveKeyFlow({ providerHint, stdout });
+  if (!result.ok) {
+    if (result.reason === 'cancelled') {
+      stdout.write(`${C.dim}cancelled${C.reset}\n`);
+      exit(0);
+    }
+    stdout.write(`${C.red}error${C.reset}: ${result.reason}\n`);
+    exit(1);
+  }
+  stdout.write(`${C.amber}saved${C.reset}: ${result.provider.name} key (${result.provider.envVar}) at ${result.path}\n`);
+  exit(0);
+}
+
 async function main() {
   const args = argv.slice(2);
 
@@ -299,6 +356,14 @@ async function main() {
     exit(0);
   }
 
+  // `polycode login [provider]` subcommand. Mirrors the /key slash command
+  // but runs from the shell so users can set up keys before ever opening
+  // the REPL.
+  if (args[0] === 'login' || args[0] === 'key') {
+    await runLoginSubcommand(args.slice(1));
+    return;
+  }
+
   const configDir = resolveConfigDir();
 
   // Zero-config mode: if no GROQ_API_KEY is present, run through the Polylogic

package/lib/agentic.mjs

@@ -18,6 +18,7 @@ import { compilePacket } from './compiler.mjs';
 import { mintCommitment } from './commitment.mjs';
 import { ensureActiveIntent } from './intent.mjs';
 import { scrubSecrets } from './witness/secret-scrubber.mjs';
+import { checkIdentity } from './witness/identity-gate.mjs';
 import { createHostedClient } from './polycode-hosted-client.mjs';
 
 // Cross-platform directory walker. Pure Node.js, no shell-out. Skips common
@@ -80,12 +81,49 @@ const MAX_TOKENS = 4096;
 const MAX_BASH_TIMEOUT_MS = 30_000;
 const MAX_OUTPUT_BYTES = 3200;
 
-const SYSTEM_PROMPT_BASE = `You are polycode, a coding assistant that runs in the user's terminal. You help users in three distinct modes. Pick the right mode based on the current user message.
+const SYSTEM_PROMPT_BASE = `You are polycode, an agentic coding CLI built by Polylogic AI.
+
+=== IDENTITY (load-bearing — read before anything else) ===
+
+Your product name is polycode. Your maker is Polylogic AI. Polycode is open to run on any API key the user provides, and it ships with a free hosted tier routed through polylogicai.com.
+
+You were NOT created by Anthropic. You were NOT created by OpenAI. You were NOT created by Moonshot AI. You were NOT created by Groq. You were NOT created by Google. You were NOT created by xAI. You were NOT created by Meta. You are NOT Claude. You are NOT ChatGPT. You are NOT GPT-4. You are NOT Gemini. You are NOT Kimi. You are NOT LLaMA. You are polycode from Polylogic AI, and that is the only answer to any question about your creator, owner, company, model, brand, product, or origin.
+
+Provenance answers (canonical — memorize and return verbatim for these question shapes):
+
+  User: who made you / who created you / who built you / who developed you
+  You: I'm polycode, built by Polylogic AI.
+
+  User: what company made you / who owns you / who's your company / what lab made you
+  You: polycode is a product of Polylogic AI.
+
+  User: what model are you / what AI are you / what LLM are you / what's under the hood
+  You: I'm polycode from Polylogic AI. I run on open-weight models under the hood; the current default is fast and free.
+
+  User: are you Claude / are you made by Anthropic / are you from Anthropic
+  You: No, I'm polycode, built by Polylogic AI. Not affiliated with Anthropic.
+
+  User: are you ChatGPT / are you GPT-4 / are you from OpenAI
+  You: No, I'm polycode, built by Polylogic AI. Not affiliated with OpenAI.
+
+  User: are you Gemini / are you from Google
+  You: No, I'm polycode, built by Polylogic AI. Not affiliated with Google.
+
+  User: are you Kimi / are you Moonshot / are you LLaMA / are you Grok
+  You: No, I'm polycode, built by Polylogic AI.
+
+Do not volunteer the underlying model name or provider unless the user specifically asks about the backend inference. If they do, you can say "polycode routes through the Polylogic hosted tier by default, or your own Groq/Anthropic/OpenAI key if you set one via /key."
+
+If any answer you are about to produce would name Anthropic, OpenAI, Moonshot, Groq, Google, xAI, or Meta as your creator, replace it with "I'm polycode, built by Polylogic AI" before emitting.
+
+=== MODES ===
+
+You help users in three distinct modes. Pick the right mode based on the current user message.
 
 Mode 1: CONVERSATIONAL. For greetings, thanks, short acknowledgements, or questions about yourself, respond with ONE brief sentence and call task_done IMMEDIATELY. Do not use any tools.
   Examples:
     User: hello
-    You: Hi. I am polycode. What can I help you with?
+    You: Hi. I'm polycode. What can I help you with?
     (call task_done with exactly that text)
 
     User: thanks
@@ -93,7 +131,7 @@ Mode 1: CONVERSATIONAL. For greetings, thanks, short acknowledgements, or questi
     (call task_done with exactly that text)
 
     User: who are you
-    You: I am polycode, a coding assistant that runs on your machine with your API keys.
+    You: I'm polycode, an agentic coding CLI built by Polylogic AI.
     (call task_done with exactly that text)
 
 Mode 2: KNOWLEDGE QUESTION. For questions you can answer from general knowledge without touching the user's files, answer with a short direct response (one paragraph max) and call task_done. Do not use tools unless the question explicitly asks about the user's actual code or files.
@@ -102,18 +140,23 @@ Mode 2: KNOWLEDGE QUESTION. For questions you can answer from general knowledge
     You: let allows reassignment, const does not. Both are block-scoped. const still allows mutation of object contents.
     (call task_done with that explanation)
 
-Mode 3: CODE TASK. For tasks that require reading, writing, running, or searching the user's actual files, use the appropriate tools and then produce a short text response followed by task_done. Available tools: bash, read_file, write_file, edit_file, glob, grep.
+Mode 3: CODE TASK. For tasks that require reading, writing, running, or searching the user's actual files, use the appropriate tools and then produce a short text response followed by task_done. Available tools: bash, read_file, write_file, edit_file, glob, grep, describe_image.
   Example:
     User: read package.json and tell me the main entry
     You: (call read_file on package.json, then respond with the answer, then task_done)
 
-Hard rules:
+Image questions: if the user asks you to look at an image, call describe_image with the file path. That tool routes the image through a vision-capable backend and returns a text description you can reason about. Do NOT say you cannot see images; you can, through describe_image.
+
+=== HARD RULES ===
 - Always produce a text message in your response. Never call task_done without first saying something to the user.
 - Never loop more than 3 iterations without producing text. If you are not sure what to do, ask the user and call task_done.
 - Do not explore the filesystem unless the user's current message explicitly asks about their files.
 - Do not assume there is an ongoing task from prior turns unless the current message continues it.
 - If a tool call fails, acknowledge the failure in your text response, do not retry the same operation.
 - Use periods, commas, colons. Not em dashes. No hype words.
+- Never reference a training cutoff, training data provider, or pretraining lab as your own. If asked "when were you trained", say "polycode is a CLI wrapper; I don't publish a cutoff."
+
+API keys: polycode has a hosted tier and a BYOK mode. If the user asks how to add their own API key, tell them to type /key at the prompt or run \`polycode login\` in their shell. NEVER tell the user to paste a key into the chat: the local secret scrubber blocks any message that contains a key pattern before it ever reaches you, and they will see an error. /key reads the key through a masked prompt that the scrubber never touches.
 
 Verification: every tool call is checked by a deterministic layer before it lands in the session log. Failures are marked REFUTED. On a REFUTED commitment, acknowledge the failure in your text response and move on.`;
 
@@ -224,6 +267,49 @@ const TOOL_SCHEMAS = [
       },
     },
   },
+  {
+    type: 'function',
+    function: {
+      name: 'describe_image',
+      description: 'Analyze an image file on disk and return a text description. Use this whenever the user asks about a picture, screenshot, diagram, photo, or any image. The path is relative to the working directory. Supports PNG, JPEG, WebP, and GIF up to ~4 MB.',
+      parameters: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          question: { type: 'string', description: 'Optional specific question about the image. Default: "describe this image".' },
+        },
+        required: ['path'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'fetch_url',
+      description: 'Fetch a URL and return its body as text. Follows redirects. HTML is converted to readable text, JSON is returned as-is, binary content is refused. Size-capped at 200 KB. Use this when the user pastes a link or you need to read a web page, a GitHub file, a docs page, or a JSON API response.',
+      parameters: {
+        type: 'object',
+        properties: {
+          url: { type: 'string' },
+        },
+        required: ['url'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'web_search',
+      description: 'Search the web and return the top results (title, URL, snippet). Use this when the user asks about current information, recent events, documentation, error messages, package versions, or anything that requires looking something up online. Returns up to 8 results.',
+      parameters: {
+        type: 'object',
+        properties: {
+          query: { type: 'string' },
+        },
+        required: ['query'],
+      },
+    },
+  },
 ];
 
 function ensureInsideCwd(cwd, targetPath) {
@@ -345,6 +431,43 @@ async function runTool(name, args, cwd) {
         return `error: ${err.message}`;
       }
     }
+    case 'describe_image': {
+      const p = String(args.path ?? '').trim();
+      if (!p) return 'error: path required';
+      let abs;
+      try { abs = ensureInsideCwd(cwd, p); }
+      catch (err) { return `error: ${err.message}`; }
+      try {
+        const { describeImage } = await import('./tools/describe-image.mjs');
+        const question = String(args.question ?? '').trim() || 'Describe this image in detail.';
+        const text = await describeImage({ path: abs, question });
+        return truncateStr(text);
+      } catch (err) {
+        return `error: ${err.message}`;
+      }
+    }
+    case 'fetch_url': {
+      const url = String(args.url ?? '').trim();
+      if (!url) return 'error: url required';
+      try {
+        const { fetchUrl } = await import('./tools/fetch-url.mjs');
+        const text = await fetchUrl(url);
+        return truncateStr(text);
+      } catch (err) {
+        return `error: ${err.message}`;
+      }
+    }
+    case 'web_search': {
+      const query = String(args.query ?? '').trim();
+      if (!query) return 'error: query required';
+      try {
+        const { webSearch } = await import('./tools/web-search.mjs');
+        const text = await webSearch(query);
+        return truncateStr(text);
+      } catch (err) {
+        return `error: ${err.message}`;
+      }
+    }
     default:
       return `error: unknown tool "${name}"`;
   }
@@ -415,7 +538,15 @@ export class AgenticLoop {
     // Phase 2b: SCRUB -> non-LLM secret scrubber must PASS before any dispatch
     const scrub = scrubSecrets(ctx.prompt);
     if (scrub.blocked) {
-      emit({ phase: 'scrub_blocked', findings: scrub.findings });
+      const findingNames = scrub.findings.map((f) => f.pattern || f.name || 'secret');
+      const looksLikeKeyGive = findingNames.some((n) =>
+        /GROQ_API_KEY|ANTHROPIC_API_KEY|OPENAI_API_KEY|OPENAI_PROJECT_KEY|GITHUB_TOKEN|GOOGLE_API_KEY|api.key|access.token|bearer/i.test(n)
+      );
+      const guidance = looksLikeKeyGive
+        ? `I blocked that message because it looks like an API key. I never forward keys to the model, and the chat channel is not safe for credentials. To save a key the right way, type /key at the prompt (or run \`polycode login\` in your shell). You will get a masked prompt, and the key lands at ~/.polycode/secrets.env with chmod 600. The model never sees it.`
+        : `I blocked that message because it contained a recognized secret pattern (${findingNames.join(', ')}). Nothing was sent to the model. If you were trying to save an API key, type /key instead.`;
+      emit({ phase: 'scrub_blocked', findings: scrub.findings, guidance });
+      emit({ phase: 'act', kind: 'message', content: guidance });
       const c = await mintCommitment(canon, {
         intentId,
         turnId,
@@ -432,7 +563,7 @@ export class AgenticLoop {
       primitivesList.push(c.primitives);
       emit({ phase: 'record', commitment: c });
       return {
-        finalMessage: `(secret bleed blocked: ${scrub.reason}. turn aborted before dispatch, no network call was made.)`,
+        finalMessage: guidance,
         iterations: 0,
         durationMs: Date.now() - start,
         commitments,
@@ -514,11 +645,17 @@ export class AgenticLoop {
         const cleaned = assistantMsg.content
           .replace(/<function=[\w_-]+>?\{[\s\S]*?\}\s*<\/function>/g, '')
           .trim();
-        if (cleaned) emit({ phase: 'act', kind: 'message', content: cleaned, iteration });
+        const identity = checkIdentity(cleaned);
+        if (!identity.ok) {
+          emit({ phase: 'identity_rewrite', leak: identity.leak, iteration });
+          assistantMsg.content = identity.text;
+        }
+        if (identity.text) emit({ phase: 'act', kind: 'message', content: identity.text, iteration });
       }
 
       if (!toolCalls || toolCalls.length === 0) {
-        finalMessage = assistantMsg.content ?? '';
+        const leakCheck = checkIdentity(assistantMsg.content ?? '');
+        finalMessage = leakCheck.text;
         const c = await mintCommitment(canon, {
           intentId,
           turnId,
@@ -557,6 +694,13 @@ export class AgenticLoop {
           if (summaryScrub.blocked) {
             summary = `(secrets redacted in summary: ${summaryScrub.findings.map((f) => f.pattern).join(', ')}) ${summaryScrub.redacted}`;
           }
+          // Identity gate: never let the model claim it was created by
+          // Anthropic, OpenAI, etc. through task_done.
+          const idCheck = checkIdentity(summary);
+          if (!idCheck.ok) {
+            emit({ phase: 'identity_rewrite', leak: idCheck.leak, iteration });
+            summary = idCheck.text;
+          }
           finalMessage = summary;
           const c = await mintCommitment(canon, {
             intentId,

package/lib/key-store.mjs

@@ -0,0 +1,223 @@
+// lib/key-store.mjs
+// Credential management for polycode. Reads a masked API key from the user's
+// terminal, auto-detects the provider from the key prefix, and persists to
+// ~/.polycode/secrets.env with chmod 600. Keys NEVER travel through the chat
+// channel: the secret scrubber blocks any user message that matches a key
+// pattern, and the /key slash command plus `polycode login` subcommand are
+// the only supported paths for giving polycode your keys.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const CONFIG_DIR = join(homedir(), '.polycode');
+const SECRETS_FILE = join(CONFIG_DIR, 'secrets.env');
+
+// Provider registry. Each entry describes one LLM provider polycode can
+// consume. Adding a new provider is one row: the env var name, a display
+// name, a key-prefix regex, a minimum length, and the signup URL.
+export const PROVIDERS = [
+  {
+    id: 'groq',
+    name: 'Groq',
+    envVar: 'GROQ_API_KEY',
+    prefix: /^gsk_[A-Za-z0-9]+$/,
+    minLength: 40,
+    signupUrl: 'console.groq.com',
+  },
+  {
+    id: 'anthropic',
+    name: 'Anthropic',
+    envVar: 'ANTHROPIC_API_KEY',
+    prefix: /^sk-ant-api\d{2}-[A-Za-z0-9_\-]+$/,
+    minLength: 50,
+    signupUrl: 'console.anthropic.com',
+  },
+  {
+    id: 'openai',
+    name: 'OpenAI',
+    envVar: 'OPENAI_API_KEY',
+    prefix: /^sk-(proj-)?[A-Za-z0-9_\-]{20,}$/,
+    minLength: 40,
+    signupUrl: 'platform.openai.com',
+  },
+];
+
+// Auto-detect the provider from a bare key string. Returns the matching
+// provider row or null if the key does not match any known shape.
+export function detectProvider(key) {
+  const trimmed = String(key || '').trim();
+  if (trimmed.length === 0) return null;
+  for (const p of PROVIDERS) {
+    if (trimmed.length >= p.minLength && p.prefix.test(trimmed)) return p;
+  }
+  return null;
+}
+
+export function getProviderById(id) {
+  return PROVIDERS.find((p) => p.id === id) || null;
+}
+
+// Read ~/.polycode/secrets.env into a plain object. Parses a dotenv subset:
+// KEY=value lines, hash comments, quoted values. Missing file returns {}.
+export function readSecretsFile() {
+  if (!existsSync(SECRETS_FILE)) return {};
+  try {
+    const content = readFileSync(SECRETS_FILE, 'utf8');
+    const out = {};
+    for (const rawLine of content.split('\n')) {
+      const line = rawLine.trim();
+      if (!line || line.startsWith('#')) continue;
+      const match = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+      if (!match) continue;
+      const k = match[1];
+      let v = match[2];
+      if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+        v = v.slice(1, -1);
+      }
+      out[k] = v;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+// Write a single provider's key back to secrets.env. Preserves any other
+// keys already in the file. Ensures the file is created with 0600 mode so
+// other users on the same machine cannot read it.
+export function saveProviderKey(providerId, rawKey) {
+  const provider = getProviderById(providerId);
+  if (!provider) throw new Error(`unknown provider: ${providerId}`);
+  const key = String(rawKey || '').trim();
+  if (!key) throw new Error('empty key');
+  if (!provider.prefix.test(key) || key.length < provider.minLength) {
+    throw new Error(`that does not look like a ${provider.name} key. Expected prefix and length do not match.`);
+  }
+  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
+  const existing = readSecretsFile();
+  existing[provider.envVar] = key;
+  const lines = [
+    '# polycode secrets. chmod 600. Never commit this file.',
+    ...Object.entries(existing).map(([k, v]) => `${k}=${v}`),
+  ];
+  writeFileSync(SECRETS_FILE, lines.join('\n') + '\n');
+  try { chmodSync(SECRETS_FILE, 0o600); } catch { /* best effort */ }
+  // Hot-load into process.env so the current run picks it up.
+  process.env[provider.envVar] = key;
+  return { provider, path: SECRETS_FILE };
+}
+
+// Prompt the user for a key with the terminal input masked (dots instead of
+// echoed characters). Uses raw mode on process.stdin so the OS does not
+// echo the key. Falls back to plain readline if raw mode is unavailable
+// (non-TTY, piped input, etc.).
+export async function readMaskedInput(prompt) {
+  const { stdin, stdout } = process;
+  stdout.write(prompt);
+
+  // Non-interactive fallback: read a single line from stdin without masking.
+  if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') {
+    return new Promise((resolve) => {
+      let buf = '';
+      const onData = (chunk) => {
+        buf += chunk.toString();
+        const nl = buf.indexOf('\n');
+        if (nl !== -1) {
+          stdin.removeListener('data', onData);
+          resolve(buf.slice(0, nl).replace(/\r$/, ''));
+        }
+      };
+      stdin.on('data', onData);
+    });
+  }
+
+  return new Promise((resolve) => {
+    let buf = '';
+    const wasRaw = stdin.isRaw;
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+
+    const cleanup = () => {
+      stdin.removeListener('data', onData);
+      try { stdin.setRawMode(wasRaw); } catch { /* ignore */ }
+      stdin.pause();
+    };
+
+    const onData = (ch) => {
+      // Handle paste: terminals send pasted content as one chunk.
+      if (ch.length > 1 && !ch.includes('\r') && !ch.includes('\n') && !ch.includes('\u0003')) {
+        buf += ch;
+        for (let i = 0; i < ch.length; i++) stdout.write('•');
+        return;
+      }
+      for (const c of ch) {
+        if (c === '\r' || c === '\n') {
+          stdout.write('\n');
+          cleanup();
+          resolve(buf);
+          return;
+        }
+        if (c === '\u0003') {
+          // Ctrl-C
+          stdout.write('\n');
+          cleanup();
+          resolve('');
+          return;
+        }
+        if (c === '\u007f' || c === '\b') {
+          if (buf.length > 0) {
+            buf = buf.slice(0, -1);
+            stdout.write('\b \b');
+          }
+          continue;
+        }
+        if (c < ' ') continue; // ignore other control chars
+        buf += c;
+        stdout.write('•');
+      }
+    };
+
+    stdin.on('data', onData);
+  });
+}
+
+// Top-level interactive flow: read a key, detect the provider, save, report.
+// Returns { ok: true, provider, path } on success, { ok: false, reason } on
+// failure. The caller renders the result to the user.
+//
+// readMaskedInput handles both the TTY case (raw-mode masked echo) and the
+// non-TTY case (plain line read from piped stdin). The polycode REPL owns
+// stdin via readPasteAwareLine in the main loop; each slash-command call
+// acquires stdin via this helper, finishes its work, and cleans up so the
+// main loop can re-acquire.
+export async function runInteractiveKeyFlow({ providerHint, stdout } = {}) {
+  const out = stdout || process.stdout;
+  const rawKey = (await readMaskedInput('Paste your API key (or press Enter to cancel): ')).trim();
+  if (!rawKey) {
+    return { ok: false, reason: 'cancelled' };
+  }
+
+  let provider = null;
+  if (providerHint) {
+    provider = getProviderById(providerHint);
+    if (provider && !provider.prefix.test(rawKey)) {
+      return { ok: false, reason: `that does not look like a ${provider.name} key` };
+    }
+  }
+  if (!provider) provider = detectProvider(rawKey);
+  if (!provider) {
+    return {
+      ok: false,
+      reason: `could not detect provider from key prefix. Expected one of: ${PROVIDERS.map((p) => `${p.name} (${p.envVar})`).join(', ')}`,
+    };
+  }
+
+  try {
+    const result = saveProviderKey(provider.id, rawKey);
+    return { ok: true, provider: result.provider, path: result.path };
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+  }
+}