amness 0.1.0 → 0.1.3

package/README.md

@@ -5,7 +5,7 @@
 [![CI](https://github.com/amirsdream/Amness/actions/workflows/ci.yml/badge.svg)](https://github.com/amirsdream/Amness/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![Node](https://img.shields.io/badge/node-%E2%89%A5%2022.18-339933)
-![Runtime dependencies](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen)
+![Runtime dependencies](https://img.shields.io/badge/required%20dependencies-0-brightgreen)
 
 <p align="center"><img src="docs/images/chat.png" alt="Amness full-screen interface: cards, diff, sidebar, input panel" width="900"></p>
 
@@ -16,12 +16,26 @@
 You need **Node 22.18+**, git, and an API key (OpenAI or Anthropic) or a local model server.
 
 ```bash
-git clone https://github.com/amirsdream/Amness.git && cd Amness && npm install
-export OPENAI_API_KEY=sk-...          # or ANTHROPIC_API_KEY=sk-ant-...
-npm link                              # gives you the `amness` command
-cd ~/your-project && amness           # start a conversation in your project
+npm install -g amness                 # gives you the `amness` command
+cd ~/your-project && amness           # first start: pick a provider and paste your key (see below)
 ```
 
+Or try it without installing: `npx amness`. To run the latest `main` from source (or to work on Amness), see [Run from source](#run-from-source).
+
+### Your API key
+
+Give Amness the key once, in whichever way suits you:
+
+| How | Command or step | Saved? |
+|---|---|---|
+| **Paste it on first start** | run `amness`, choose a provider, paste the key (hidden). Add more providers any time with `/connect`, and switch with `/provider`. | Yes, in your system's secure store: the macOS Keychain, the Linux keyring, or Windows DPAPI. The prompt tells you which. |
+| **Environment variable** | `export ANTHROPIC_API_KEY=sk-ant-...` or `export OPENAI_API_KEY=sk-...` (PowerShell: `$env:OPENAI_API_KEY="sk-..."`) | No. Used for that shell only, and never written to disk. It wins over a saved key. |
+| **Secret file** (Docker, Kubernetes) | `ANTHROPIC_API_KEY_FILE=/run/secrets/anthropic` (also `OPENAI_API_KEY_FILE`, `TAVILY_API_KEY_FILE`) | No. Read from the file each run. |
+| **Docker** | `docker run -it --rm -v "$PWD":/work -e ANTHROPIC_API_KEY amness` | No. Inside a container nothing is saved. |
+| **Library or CI** | pass `apiKey` in code, or set the variable as a CI secret | No. |
+
+Each provider keeps its own saved key, so you can connect several and switch with `/provider`; `/connect` shows which are connected. `OPENAI_API_KEY` is used for every provider except Anthropic (OpenRouter prefers `OPENROUTER_API_KEY`). To remove a saved key, clear "API key" in the settings. A Linux server with no keyring falls back to `~/.amness/config.json` (mode 600, **not encrypted**), so use an environment variable or your platform's secret manager there. Details: [Safety](docs/safety.md).
+
 More ways to start:
 
 ```bash
@@ -33,6 +47,17 @@ amness demo                                                    # a scripted tour
 
 New to it? Follow the [step-by-step guide](docs/getting-started.md). Inside the chat: `/help` lists everything · `Shift+Tab` changes how much it may do without asking · `Ctrl+P` opens the command palette · `@file` attaches a file or image · `!cmd` runs a shell command · `#note` saves a memory.
 
+## Run from source
+
+Use this for the latest `main` (changes not yet released to npm) or to work on Amness itself.
+
+```bash
+git clone https://github.com/amirsdream/Amness.git && cd Amness && npm install
+npm link                              # `amness` now runs your clone; `git pull` updates it
+```
+
+Update the npm version with `npm install -g amness@latest`. Contributors: see [Development](docs/development.md).
+
 ## What it looks like
 
 <p align="center"><img src="docs/images/approval.png" alt="An edit waiting for your approval, with the diff" width="780"></p>
@@ -172,7 +197,7 @@ More plugin ideas (finish gates, policies, loop strategies, custom metrics) are
 | **Evaluate and improve** | `amness eval` (ablations, SWE-bench-format suites, injection suite, leak audit), trace replay, failure mining, `amness tune` (changes kept only if they hold on unseen tasks). |
 | **Works where you work** | Full-screen and inline terminal UI, headless mode, git worktree sessions with `/review` and `/pr`, scheduled runs, a GitHub Action, an editor server (`amness acp`), image input, session branching. |
 
-Models: OpenAI (Responses and Chat), Claude, and any OpenAI-compatible local server. No runtime dependencies.
+Models: OpenAI (Responses and Chat), Claude, and any OpenAI-compatible local server. No required dependencies (the Claude SDK is an optional one that npm installs for you).
 
 ## Choose Amness if, choose something else if
 
@@ -184,7 +209,7 @@ Models: OpenAI (Responses and Chat), Claude, and any OpenAI-compatible local ser
 
 - **Tested:** about 375 automated tests (scripted models, mock servers, real git repositories, a pseudo-terminal), CI on Linux and Windows, and a Docker and npm-package smoke test.
 - **Measured on real models (small):** the guards and the reviewer showed no detectable pass-rate effect on [these tasks and models](docs/evaluation.md#measured-results-so-far); the guards and reviewer cost extra tokens, most visibly on strong models. Every newer feature (routing, `tune`, best-of-n, parallel parts, language-server diagnostics, the approval reviewer) is implemented and unit-tested but **not yet shown to help on real work**. The [roadmap](ROADMAP.md) lists the measurements still to run.
-- **Platforms:** developed on macOS and Linux. Windows runs the test suite but has no OS sandbox. Not on npm yet.
+- **Platforms:** developed on macOS and Linux. Windows runs the test suite but has no OS sandbox. Installed from npm; the Claude SDK comes with it.
 - Cost figures are estimates. Small local models vary widely in tool-calling quality.
 
 ## Documentation

package/dist/cli/amness.js

@@ -15,7 +15,8 @@ import { runPlugin } from "./plugincli.js";
 import { runSchedule } from "./schedulecli.js";
 import { ACP_HELP, runAcp } from "./acpcli.js";
 import { runEval, runTune } from "./evalcli.js";
-import { CLAUDE_MODELS, OPENAI_MODELS, PROVIDERS, home, loadConfig, mask, ready, saveConfig } from "./config.js";
+import { CLAUDE_MODELS, OPENAI_MODELS, PROVIDERS, home, keyFor, loadConfig, mask, ready, saveConfig } from "./config.js";
+import { where } from "./keystore.js";
 import { DEMO_TASK, explain, runDemo } from "./demo.js";
 import { formatEvent } from "./format.js";
 import { Cancel, ask, bold, box, clearScreen, confirm, cyan, dim, gray, green, log, pause, red, select, spin, yellow } from "./ui.js";
@@ -90,7 +91,7 @@ async function ensureReady() {
         cfg.model = (await ask("Model", cfg.model)) || cfg.model;
     }
     if (PROVIDERS[id].needsKey)
-        cfg.apiKey = (await ask("API key (hidden; saved to ~/.amness/config.json, mode 600)", "", { secret: true })) || undefined;
+        cfg.apiKey = keyFor(id).key ?? ((await ask(`API key (hidden; ${where()})`, "", { secret: true })) || undefined);
     saveConfig(cfg);
     if (!ready(cfg))
         return false;
@@ -431,7 +432,7 @@ async function settings() {
             if (what === "provider") {
                 const id = await select("Provider", Object.keys(PROVIDERS).map((k) => ({ label: PROVIDERS[k].label, value: k, hint: PROVIDERS[k].baseUrl })));
                 if (id)
-                    Object.assign(cfg, { provider: id, baseUrl: PROVIDERS[id].baseUrl, model: PROVIDERS[id].model });
+                    Object.assign(cfg, { provider: id, baseUrl: PROVIDERS[id].baseUrl, model: PROVIDERS[id].model, apiKey: keyFor(id).key });
             }
             else if (what === "model") {
                 if (cfg.provider === "anthropic" || cfg.provider === "openai") {
@@ -452,7 +453,7 @@ async function settings() {
             else if (what === "url")
                 cfg.baseUrl = (await ask("Base URL", cfg.baseUrl)) || cfg.baseUrl;
             else if (what === "key")
-                cfg.apiKey = (await ask("API key (hidden; stored in ~/.amness/config.json, mode 600)", cfg.apiKey ?? "", { secret: true })) || undefined;
+                cfg.apiKey = (await ask(`API key (hidden; ${where()})`, cfg.apiKey ?? "", { secret: true })) || undefined;
             else if (what === "tavily")
                 cfg.tavilyKey = (await ask("Tavily API key (blank to clear)", "", { secret: true })) || undefined;
             else if (what === "budget")

package/dist/cli/config.d.ts

@@ -35,7 +35,8 @@ export type Config = {
     provider: ProviderId;
     baseUrl: string;
     model: string;
-    apiKey?: string;
+    apiKey?: string; /** saved keys for the other providers, only where there is no OS store */
+    apiKeys?: Partial<Record<ProviderId, string>>;
     tavilyKey?: string;
     maxTokens: number;
     effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"; /** OpenAI wire API: auto (default) picks Responses for reasoning models and self-corrects */
@@ -65,6 +66,26 @@ export type Config = {
 };
 export declare const home: () => string;
 export declare const defaults: () => Config;
+/** The variable that holds a provider's key. Anthropic has its own; OpenRouter may have its own; every other provider uses OPENAI_API_KEY. */
+export declare const envNameFor: (p: ProviderId) => "ANTHROPIC_API_KEY" | "OPENROUTER_API_KEY" | "OPENAI_API_KEY";
+export declare const envKeyFor: (p: ProviderId) => string | undefined;
+export type KeyState = {
+    key?: string;
+    source: "env" | "saved" | "none";
+};
+/** The key to use for a provider: an environment variable wins over a saved key. */
+export declare function keyFor(p: ProviderId): KeyState;
+/** Save (or, with no key, remove) a provider's key. Uses the OS store; else config.json (mode 600); in a container, memory only. */
+export declare function storeKey(p: ProviderId, key?: string): void;
+export type Connection = {
+    id: ProviderId;
+    label: string;
+    needsKey: boolean;
+    source: KeyState["source"];
+    env: string;
+};
+/** Every provider and whether it is ready to use. */
+export declare function connections(): Connection[];
 export declare function loadConfig(): Config;
 export declare function saveConfig(c: Config): void;
 export declare const ready: (c: Config) => boolean;

package/dist/cli/config.js

@@ -1,6 +1,7 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { deleteSecret, getSecret, noStore, setSecret } from "./keystore.js";
 export const PROVIDERS = {
     anthropic: { label: "Anthropic (Claude)", baseUrl: "https://api.anthropic.com", model: "claude-opus-5-5", needsKey: true },
     openai: { label: "OpenAI", baseUrl: "https://api.openai.com/v1", model: "gpt-6.1-sol", needsKey: true },
@@ -11,30 +12,148 @@ export const PROVIDERS = {
 export const home = () => process.env.AMNESS_HOME ?? join(homedir(), ".amness");
 const file = () => join(home(), "config.json");
 export const defaults = () => ({ provider: "openai", baseUrl: PROVIDERS.openai.baseUrl, model: PROVIDERS.openai.model, maxTokens: 300_000 });
+// ---- keys. One saved key per provider (account "apiKey-<provider>" in the OS store), so you can be connected to several at once. `cfg.apiKey` is always the active provider's key.
+const acct = (p) => `apiKey-${p}`;
+let fileKeys = {}, fileKeysLoaded = false; // only where there is no OS store (a Linux server): kept in config.json, mode 600
+const sessionKeys = {}; // in a container: this run only
+const persisted = {}; // what is stored now, so a save does not rewrite an unchanged key
+/** An environment variable, or the file NAME_FILE points to (Docker and Kubernetes secrets are mounted as files, for example /run/secrets/openai). */
+const envSecret = (name) => {
+    const v = process.env[name];
+    if (v)
+        return v;
+    const f = process.env[`${name}_FILE`];
+    if (!f)
+        return undefined;
+    try {
+        return readFileSync(f, "utf8").trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** The variable that holds a provider's key. Anthropic has its own; OpenRouter may have its own; every other provider uses OPENAI_API_KEY. */
+export const envNameFor = (p) => (p === "anthropic" ? "ANTHROPIC_API_KEY" : p === "openrouter" && envSecret("OPENROUTER_API_KEY") ? "OPENROUTER_API_KEY" : "OPENAI_API_KEY");
+export const envKeyFor = (p) => envSecret(envNameFor(p));
+const loadFileKeys = () => { if (!fileKeysLoaded) {
+    fileKeysLoaded = true;
+    fileKeys = { ...readFileCfg().apiKeys };
+} };
+const savedKey = (p) => { loadFileKeys(); return getSecret(acct(p)) ?? fileKeys[p] ?? sessionKeys[p]; };
+/** The key to use for a provider: an environment variable wins over a saved key. */
+export function keyFor(p) {
+    const e = envKeyFor(p);
+    if (e)
+        return { key: e, source: "env" };
+    const s = savedKey(p);
+    if (s) {
+        persisted[p] = s;
+        return { key: s, source: "saved" };
+    }
+    return { source: "none" };
+}
+/** Save (or, with no key, remove) a provider's key. Uses the OS store; else config.json (mode 600); in a container, memory only. */
+export function storeKey(p, key) {
+    loadFileKeys();
+    persisted[p] = key;
+    if (!key) {
+        deleteSecret(acct(p));
+        delete fileKeys[p];
+        delete sessionKeys[p];
+        writeConfigFile(readFileCfg());
+        return;
+    }
+    if (setSecret(acct(p), key)) {
+        delete fileKeys[p];
+        delete sessionKeys[p];
+    }
+    else if (noStore())
+        sessionKeys[p] = key;
+    else
+        fileKeys[p] = key;
+    writeConfigFile(readFileCfg());
+}
+/** Every provider and whether it is ready to use. */
+export function connections() {
+    return Object.keys(PROVIDERS).map((id) => ({ id, label: PROVIDERS[id].label, needsKey: PROVIDERS[id].needsKey, source: PROVIDERS[id].needsKey ? keyFor(id).source : "saved", env: envNameFor(id) }));
+}
+const readFileCfg = () => { try {
+    return { ...defaults(), ...JSON.parse(readFileSync(file(), "utf8")) };
+}
+catch {
+    return defaults();
+} };
+let tavilyEnv;
 export function loadConfig() {
-    let c = defaults();
+    let c = defaults(), onDisk = {};
     try {
         if (existsSync(file()))
-            c = { ...c, ...JSON.parse(readFileSync(file(), "utf8")) };
+            onDisk = JSON.parse(readFileSync(file(), "utf8"));
+        c = { ...c, ...onDisk };
     }
     catch { /* corrupt config: start fresh */ }
-    // environment wins, so CI and one-off runs work without touching the saved file
+    fileKeys = { ...onDisk.apiKeys };
+    fileKeysLoaded = true;
+    delete c.apiKeys;
+    let dirty = false;
+    // older versions kept ONE key (account "apiKey", or a field in the file) for whichever provider was active: give it to that provider
+    const legacy = [getSecret("apiKey"), onDisk.apiKey].find(Boolean);
+    if (legacy && !savedKey(c.provider)) {
+        fileKeys[c.provider] = legacy;
+        dirty = true;
+    }
+    if (getSecret("apiKey"))
+        deleteSecret("apiKey");
+    if (onDisk.apiKey) {
+        delete onDisk.apiKey;
+        dirty = true;
+    }
+    // keys still in the file move to the OS store, and leave the file only after they read back
+    for (const p of Object.keys(fileKeys))
+        if (fileKeys[p] && setSecret(acct(p), fileKeys[p])) {
+            delete fileKeys[p];
+            dirty = true;
+        }
+    const tv = getSecret("tavilyKey") ?? onDisk.tavilyKey;
+    if (onDisk.tavilyKey && setSecret("tavilyKey", onDisk.tavilyKey)) {
+        delete onDisk.tavilyKey;
+        dirty = true;
+    }
+    if (dirty)
+        writeConfigFile({ ...defaults(), ...onDisk, apiKey: undefined, tavilyKey: onDisk.tavilyKey });
     const claude = c.provider === "anthropic";
-    const key = claude ? process.env.ANTHROPIC_API_KEY : process.env.OPENAI_API_KEY;
-    if (key)
-        c.apiKey = key;
-    if (process.env.TAVILY_API_KEY)
-        c.tavilyKey = process.env.TAVILY_API_KEY;
+    c.apiKey = keyFor(c.provider).key;
+    // environment wins, so CI and one-off runs work without touching the saved key. It is never written back (see saveConfig).
+    tavilyEnv = envSecret("TAVILY_API_KEY");
+    c.tavilyKey = tavilyEnv ?? tv;
     if (process.env.OPENAI_BASE_URL && !claude)
         c.baseUrl = process.env.OPENAI_BASE_URL;
     if (process.env.AMNESS_MODEL)
         c.model = process.env.AMNESS_MODEL;
     return c;
 }
-export function saveConfig(c) {
+function writeConfigFile(c) {
     mkdirSync(home(), { recursive: true });
-    writeFileSync(file(), JSON.stringify(c, null, 2));
-    chmodSync(file(), 0o600); // may hold API keys
+    const out = { ...c, apiKeys: Object.keys(fileKeys).length ? fileKeys : undefined };
+    writeFileSync(file(), JSON.stringify(out, null, 2), { mode: 0o600 }); // owner-only from the first byte
+    chmodSync(file(), 0o600); // and for a file that already existed
+}
+export function saveConfig(c) {
+    const out = { ...c };
+    delete out.apiKey;
+    delete out.apiKeys;
+    if (c.apiKey !== persisted[c.provider] && !(c.apiKey && c.apiKey === envKeyFor(c.provider)))
+        storeKey(c.provider, c.apiKey); // a key from an environment variable is never stored
+    const tv = c.tavilyKey;
+    if (tv && tv === tavilyEnv)
+        delete out.tavilyKey;
+    else if (!tv) {
+        deleteSecret("tavilyKey");
+        delete out.tavilyKey;
+    }
+    else if (setSecret("tavilyKey", tv) || noStore())
+        delete out.tavilyKey;
+    writeConfigFile(out);
 }
 export const ready = (c) => !PROVIDERS[c.provider].needsKey || !!c.apiKey;
 export const mask = (k) => (k ? k.slice(0, 3) + "…" + k.slice(-4) : "not set");

package/dist/cli/keystore.d.ts

@@ -0,0 +1,9 @@
+export type Backend = "keychain" | "secret-service" | "dpapi" | "file" | "none";
+export declare function backend(): Backend;
+export declare const where: () => string;
+/** True when keys must never be written to disk (containers). */
+export declare const noStore: () => boolean;
+/** Save a secret. Returns false when the OS store is not available or refused, so the caller can fall back to the file. */
+export declare function setSecret(name: string, value: string): boolean;
+export declare function getSecret(name: string): string | undefined;
+export declare function deleteSecret(name: string): void;

package/dist/cli/keystore.js

@@ -0,0 +1,108 @@
+// Where API keys live. macOS: the login Keychain. Linux: the desktop secret service (`secret-tool`). Windows: DPAPI, which encrypts the key so only your Windows user on this machine can decrypt it.
+// If the OS store is missing or refuses (a Linux server or Docker image with no keyring), the key stays in the config file with mode 600, and `where()` says so.
+// The key goes to the OS tool on stdin, never on the command line (a command line is visible to other users in `ps`), and is hex-encoded so no quoting can go wrong.
+// Tests and any run with a custom AMNESS_HOME use the file, so they never touch your real store. AMNESS_KEYSTORE=file|keychain|secret-service|dpapi|none forces one.
+// In a container (Docker, Kubernetes) nothing is saved at all ("none"): pass the key as an environment variable or a secret file (see config.ts), so it is never written into an image or a volume.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const SERVICE = process.env.AMNESS_KEYSTORE_SERVICE || "amness"; // the override is for tests
+const run = (cmd, args, input, timeout = 10_000, env) => {
+    try {
+        const r = spawnSync(cmd, args, { input, encoding: "utf8", timeout, env });
+        return r.error ? undefined : r;
+    }
+    catch {
+        return undefined;
+    }
+};
+export function backend() {
+    const want = process.env.AMNESS_KEYSTORE;
+    if (want === "file" || (!want && process.env.AMNESS_HOME))
+        return "file";
+    if (want === "keychain" || want === "secret-service" || want === "dpapi" || want === "none")
+        return want;
+    if (process.platform === "linux" && (existsSync("/.dockerenv") || process.env.KUBERNETES_SERVICE_HOST))
+        return "none";
+    if (process.platform === "darwin")
+        return "keychain";
+    if (process.platform === "win32")
+        return "dpapi";
+    if (process.platform === "linux" && run("secret-tool", ["--version"])?.status !== undefined)
+        return "secret-service";
+    return "file";
+}
+export const where = () => ({ keychain: "saved in the macOS Keychain", "secret-service": "saved in the system keyring (secret-tool)", dpapi: "saved with Windows encryption (DPAPI, this user only)", file: "saved in ~/.amness/config.json, mode 600, not encrypted", none: "not saved: this is a container, so pass the key as an environment variable or a secret file (OPENAI_API_KEY_FILE / ANTHROPIC_API_KEY_FILE)" })[backend()];
+/** True when keys must never be written to disk (containers). */
+export const noStore = () => backend() === "none";
+// Windows: PowerShell turns the key into an encrypted string that only this Windows user on this machine can decrypt (DPAPI). The string is kept in ~/.amness/secrets/<name>.dpapi.
+const dir = () => join(process.env.AMNESS_HOME ?? join(homedir(), ".amness"), "secrets");
+const blob = (name) => join(dir(), `${name}.dpapi`);
+// A parent PowerShell 7 (pwsh) leaves a PSModulePath that Windows PowerShell 5.1 cannot load its Security module from; dropping it lets 5.1 use its own default.
+const psEnv = () => { const e = { ...process.env }; for (const k of Object.keys(e))
+    if (k.toLowerCase() === "psmodulepath")
+        delete e[k]; return e; };
+const ps = (script, input) => run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], input, 60_000, psEnv()); // Windows PowerShell can take several seconds to start
+const PS_ENCRYPT = "$p = [Console]::In.ReadToEnd().Trim(); ConvertTo-SecureString $p -AsPlainText -Force | ConvertFrom-SecureString";
+const PS_DECRYPT = "$e = [Console]::In.ReadToEnd().Trim(); $s = ConvertTo-SecureString $e; [Runtime.InteropServices.Marshal]::PtrToStringBSTR([Runtime.InteropServices.Marshal]::SecureStringToBSTR($s))";
+const hex = (s) => Buffer.from(s, "utf8").toString("hex");
+const unhex = (s) => Buffer.from(s.trim(), "hex").toString("utf8");
+/** Save a secret. Returns false when the OS store is not available or refused, so the caller can fall back to the file. */
+export function setSecret(name, value) {
+    const b = backend();
+    if (b === "file" || b === "none")
+        return false;
+    if (b === "dpapi") {
+        const r = ps(PS_ENCRYPT, hex(value));
+        if (r?.status !== 0 || !r.stdout.trim())
+            return false;
+        try {
+            mkdirSync(dir(), { recursive: true });
+            writeFileSync(blob(name), r.stdout.trim(), { mode: 0o600 });
+        }
+        catch {
+            return false;
+        }
+        return getSecret(name) === value;
+    }
+    if (b === "keychain") {
+        const r = run("security", ["-i"], `add-generic-password -U -s ${SERVICE} -a ${name} -w ${hex(value)}\n`);
+        return r?.status === 0 && !/error|fail/i.test(r.stderr ?? "") && getSecret(name) === value;
+    }
+    const r = run("secret-tool", ["store", `--label=amness ${name}`, "service", SERVICE, "account", name], hex(value));
+    return r?.status === 0 && getSecret(name) === value;
+}
+export function getSecret(name) {
+    const b = backend();
+    if (b === "file" || b === "none")
+        return undefined;
+    if (b === "dpapi") {
+        if (!existsSync(blob(name)))
+            return undefined;
+        const r = ps(PS_DECRYPT, readFileSync(blob(name), "utf8"));
+        const v = r?.status === 0 ? unhex(r.stdout) : "";
+        return v || undefined;
+    }
+    const r = b === "keychain" ? run("security", ["find-generic-password", "-s", SERVICE, "-a", name, "-w"]) : run("secret-tool", ["lookup", "service", SERVICE, "account", name]);
+    if (r?.status !== 0 || !r.stdout.trim())
+        return undefined;
+    const v = unhex(r.stdout);
+    return v || undefined;
+}
+export function deleteSecret(name) {
+    const b = backend();
+    if (b === "file" || b === "none")
+        return;
+    if (b === "dpapi") {
+        try {
+            rmSync(blob(name), { force: true });
+        }
+        catch { /* already gone */ }
+        return;
+    }
+    if (b === "keychain")
+        run("security", ["delete-generic-password", "-s", SERVICE, "-a", name]);
+    else
+        run("secret-tool", ["clear", "service", SERVICE, "account", name]);
+}

package/dist/cli/models.d.ts

@@ -0,0 +1,8 @@
+export type ModelProbe = {
+    provider: string;
+    baseUrl: string;
+    apiKey?: string;
+};
+export declare function fetchModels(p: ModelProbe, fetchImpl?: typeof fetch): Promise<string[]>;
+/** For tests. */
+export declare const clearModelCache: () => void;

package/dist/cli/models.js

@@ -0,0 +1,31 @@
+const cache = new Map();
+const TTL = 10 * 60_000;
+const NOT_CHAT = /embed|whisper|tts|dall-e|moderation|davinci|babbage|transcribe|realtime|audio|image|rerank/i;
+export async function fetchModels(p, fetchImpl = fetch) {
+    if (!p.apiKey && p.provider !== "ollama" && p.provider !== "custom")
+        return []; // a hosted provider refuses a request with no key: do not even try
+    const key = `${p.provider}|${p.baseUrl}|${(p.apiKey ?? "").slice(-6)}`, hit = cache.get(key);
+    if (hit && Date.now() - hit.at < TTL)
+        return hit.ids;
+    const base = p.baseUrl.replace(/\/+$/, "");
+    const anthropic = p.provider === "anthropic";
+    try {
+        const res = await fetchImpl(anthropic ? `${base}/v1/models?limit=100` : `${base}/models`, {
+            headers: anthropic ? { "x-api-key": p.apiKey ?? "", "anthropic-version": "2023-06-01" } : p.apiKey ? { authorization: `Bearer ${p.apiKey}` } : {},
+            signal: AbortSignal.timeout(6000),
+        });
+        if (!res.ok)
+            return [];
+        const body = (await res.json());
+        const ids = [...(body.data ?? []).map((m) => m.id), ...(body.models ?? []).map((m) => m.model ?? m.name)] // Ollama's native shape uses `models`
+            .filter((x) => typeof x === "string" && !!x && !NOT_CHAT.test(x));
+        const uniq = [...new Set(ids)].sort();
+        cache.set(key, { at: Date.now(), ids: uniq });
+        return uniq;
+    }
+    catch {
+        return [];
+    }
+}
+/** For tests. */
+export const clearModelCache = () => cache.clear();

package/dist/cli/tui/app.d.ts

@@ -131,9 +131,11 @@ export declare class App {
         items: Suggestion[];
         sel: number;
         token: Token;
-        kind: Token["kind"];
+        kind: Token["kind"]; /** the user moved into the list with the arrow keys */
+        nav?: boolean;
     } | null;
     suggOff: string;
+    private argPending;
     private builtin;
     private customAt;
     private customCmds;

package/dist/cli/tui/app.js

@@ -15,7 +15,8 @@ import { BlockStore } from "./blocks.js";
 import { buildCommands } from "./commands.js";
 import { FullView } from "./full.js";
 import { loadCustomCommands } from "./custom.js";
-import { FileIndex, applySuggestion, rankCommands, rankFiles, tokenAtCursor } from "./complete.js";
+import { argOptions } from "./argcomplete.js";
+import { FileIndex, fuzzyScore, applySuggestion, menuRows, rankCommands, rankFiles, tokenAtCursor } from "./complete.js";
 import { Editor } from "./editor.js";
 import { KeyParser, PASTE_OFF, PASTE_ON } from "./keys.js";
 import { renderMarkdown, takeCompleteBlocks } from "./markdown.js";
@@ -80,6 +81,7 @@ export class App {
     pager = null;
     sugg = null;
     suggOff = "";
+    argPending = new Set();
     builtin;
     customAt = 0;
     customCmds = [];
@@ -370,11 +372,16 @@ export class App {
     setTitle(t) { if (this.io.output.isTTY !== false)
         this.io.output.write(`\x1b]0;${t}\x07`); }
     suggLines(w) {
-        const s = this.sugg, win = 8, top = Math.max(0, Math.min(s.sel - 3, s.items.length - win));
-        return s.items.slice(top, top + win).map((it, i) => {
-            const on = top + i === s.sel, label = s.kind === "file" ? it.label : it.label.padEnd(12);
+        const s = this.sugg, { rows, above, below } = menuRows(s.items, s.sel, Math.min(12, Math.max(4, this.screen.rows - 8)));
+        const lines = rows.map((r) => {
+            if ("head" in r)
+                return dim(`  ── ${r.head} ${"─".repeat(Math.max(2, 20 - r.head.length))}`);
+            const it = s.items[r.item], on = r.item === s.sel, label = s.kind === "file" ? it.label : it.label.padEnd(16);
             return (on ? cyan("❯ ") + bold(cyan(label)) : "  " + label) + (it.detail ? "  " + (on ? gray(it.detail) : dim(it.detail)) : "");
         }).map((l) => (cellWidth(l) > w ? l.slice(0, w + 12) : l));
+        if (above || below)
+            lines.push(dim(`  ${s.sel + 1}/${s.items.length}  ${above ? "↑" : " "}${below ? "↓" : " "}  ↑↓ move · PgUp/PgDn page`));
+        return lines;
     }
     tick = () => { this.frame++; this.render(); };
     ensureTimer() { if (!this.timer)
@@ -451,7 +458,7 @@ export class App {
         if (k.name === "enter" && !k.alt && !k.shift) {
             if (this.sugg && this.sugg.items.length) {
                 const it = this.sugg.items[this.sugg.sel];
-                if (!(this.sugg.kind === "slash" && ed.text.trim() === it.label))
+                if (!(this.sugg.kind === "slash" && ed.text.trim() === it.label) && !(this.sugg.kind === "arg" && (this.sugg.items.some((x) => x.label === this.sugg.token.query) || (it.open && !this.sugg.nav))))
                     return this.acceptSugg(true);
             }
             if (ed.text.slice(0, ed.cursorIndex).endsWith("\\")) {
@@ -461,10 +468,16 @@ export class App {
             }
             return void this.submit();
         }
+        if (this.sugg && (k.name === "pageup" || k.name === "pagedown")) {
+            const n = this.sugg.items.length;
+            this.sugg.sel = Math.max(0, Math.min(n - 1, this.sugg.sel + (k.name === "pageup" ? -8 : 8)));
+            return this.render();
+        }
         if (k.name === "up" || k.name === "down") {
             if (this.sugg) {
                 const n = this.sugg.items.length;
                 this.sugg.sel = (this.sugg.sel + (k.name === "up" ? n - 1 : 1)) % n;
+                this.sugg.nav = true;
                 return this.render();
             }
             if (!ed.vertical(k.name === "up" ? -1 : 1))
@@ -492,13 +505,25 @@ export class App {
         let items = [];
         if (tok.kind === "slash")
             items = rankCommands(tok.query, this.cmds);
+        else if (tok.kind === "arg") {
+            const cmd = this.cmds.find((c) => c.name === tok.cmd || c.alias === tok.cmd);
+            if (cmd) {
+                const r = argOptions(this, cmd.name, tok.words ?? []), pk = `${cmd.name}|${(tok.words ?? []).join(" ")}`;
+                if (r.pending && !this.argPending.has(pk)) {
+                    this.argPending.add(pk);
+                    void r.pending.catch(() => { }).then(() => { this.argPending.delete(pk); this.updateSugg(); this.render(); });
+                }
+                items = r.options.map((o) => ({ o, s: fuzzyScore(tok.query, o.value) })).filter((x) => x.s !== null)
+                    .sort((x, y) => (tok.query ? y.s - x.s : 0)).map(({ o }) => ({ label: o.value, insert: o.value + (o.more ? " " : ""), detail: o.detail, more: o.more, open: r.open }));
+            }
+        }
         else {
             if (!this.files.fresh())
                 void this.files.ensure().then(() => this.updateSugg(), () => { }); // list still loading: fill the popup in once it arrives
             items = rankFiles(tok.query, this.files.files);
         }
-        const keep = this.sugg && this.sugg.kind === tok.kind && this.sugg.token.query === tok.query ? this.sugg.sel : 0;
-        this.sugg = items.length ? { items, sel: Math.min(keep, items.length - 1), token: tok, kind: tok.kind } : null;
+        const same = this.sugg && this.sugg.kind === tok.kind && this.sugg.token.query === tok.query, keep = same ? this.sugg.sel : 0;
+        this.sugg = items.length ? { items, sel: Math.min(keep, items.length - 1), token: tok, kind: tok.kind, nav: same ? this.sugg.nav : false } : null;
         if (!this.sugg)
             return;
         this.schedule();
@@ -512,6 +537,8 @@ export class App {
         this.suggOff = "";
         if (fromEnter && s.kind === "slash" && !this.cmds.find((c) => "/" + c.name === s.items[s.sel].label)?.args)
             return void this.submit();
+        if (fromEnter && s.kind === "arg" && !s.items[s.sel].more)
+            return void this.submit(); // a finished value: run the command
         this.updateSugg();
         this.render();
     }

package/dist/cli/tui/argcomplete.d.ts

@@ -0,0 +1,12 @@
+import type { App } from "./app.ts";
+export type ArgOption = {
+    value: string;
+    detail?: string; /** more words are expected after this one: insert a space and do not submit */
+    more?: boolean;
+};
+export type ArgResult = {
+    options: ArgOption[];
+    pending?: Promise<unknown>; /** any value is allowed (a number, a model id, a command): Enter runs what you typed unless you moved into the list; Tab still completes */
+    open?: boolean;
+};
+export declare function argOptions(a: App, cmd: string, words: string[]): ArgResult;