amness 0.1.0 → 0.1.3

package/dist/cli/tui/argcomplete.js

@@ -0,0 +1,55 @@
+// Completion for the words after a slash command: `/mode ` lists the modes, `/model ` the models your provider offers, `/theme ` the themes, and so on.
+// A completer returns its options now and, when it needs the network, a promise that settles when the list has been filled in (the menu refreshes then).
+import { effortsFor, loadPrompts, SANDBOX_MODES, SHELL_CHOICES, STRATEGIES } from "../../src/index.js";
+import { CLAUDE_MODELS, OPENAI_MODELS } from "../config.js";
+import { fetchModels } from "../models.js";
+import { themeNames, THEMES } from "./themes.js";
+const onOff = [{ value: "on" }, { value: "off" }];
+const opts = (...xs) => xs.map(([value, detail]) => ({ value, detail }));
+/** Known models with their hints first, then any other model the provider reports. The provider is asked once per ten minutes; until it answers, only the known models show. */
+const fetched = new Map();
+function modelOptions(a, extra = []) {
+    const known = a.cfg.provider === "anthropic" ? CLAUDE_MODELS : a.cfg.provider === "openai" ? OPENAI_MODELS : [];
+    const key = `${a.cfg.provider}|${a.cfg.baseUrl}`, have = fetched.get(key), fresh = have && Date.now() - have.at < 10 * 60_000;
+    const seen = new Set(known.map((m) => m.id));
+    const options = [...extra, ...known.map((m) => ({ value: m.id, detail: m.hint })), ...(have?.ids ?? []).filter((id) => !seen.has(id)).map((id) => ({ value: id, detail: "from your provider" }))];
+    if (fresh)
+        return { options, open: true };
+    return { options, open: true, pending: fetchModels({ provider: a.cfg.provider, baseUrl: a.cfg.baseUrl, apiKey: a.cfg.apiKey }).then((ids) => { fetched.set(key, { at: Date.now(), ids }); }) };
+}
+export function argOptions(a, cmd, words) {
+    const first = words.length === 0;
+    const ok = (options) => ({ options });
+    switch (cmd) {
+        case "mode": return first ? ok(opts(["default", "ask before edits and non-trivial commands"], ["acceptEdits", "edits are automatic, commands still ask"], ["plan", "read-only: investigate and propose a plan"], ["yolo", "never ask (dangerous)"])) : ok([]);
+        case "api": return first ? ok(opts(["auto", "pick Responses for reasoning models, self-correct"], ["responses", "OpenAI Responses API"], ["chat", "Chat Completions API"])) : ok([]);
+        case "effort": return first ? ok([{ value: "default", detail: "let the model decide" }, ...(a.cfg.provider === "anthropic" ? ["low", "medium", "high", "xhigh", "max"] : effortsFor(a.cfg.model)).map((e) => ({ value: e }))]) : ok([]);
+        case "model": return first ? modelOptions(a) : ok([]);
+        case "models": return first ? ok([...["explore", "compact", "review", "cheap"].map((r) => ({ value: r, detail: `model for ${r} steps`, more: true })), { value: "fallback", detail: "answer from this model when the main one is down", more: true }])
+            : words.length === 1 ? modelOptions(a, [{ value: "off", detail: "use the main model" }]) : ok([]);
+        case "theme": return first ? ok(themeNames().map((n) => ({ value: n, detail: THEMES[n].label }))) : ok([]);
+        case "shell": return first ? ok(SHELL_CHOICES.map((n) => ({ value: n, detail: n === "auto" ? "detect from your system" : undefined }))) : ok([]);
+        case "strategy": return first ? ok([...Object.keys(STRATEGIES).map((n) => ({ value: n })), { value: "off", detail: "the default loop" }]) : ok([]);
+        case "prompt": return first ? ok([...loadPrompts(a.cwd).map((p) => ({ value: p.id, detail: "from .amness/prompts" })), { value: "list" }, { value: "off", detail: "the built-in prompt" }]) : ok([]);
+        case "sandbox": return first ? ok(SANDBOX_MODES.map((m) => ({ value: m, detail: m === "off" ? "no isolation" : m === "workspace" ? "writes only in the project" : "no network, caches read-only" }))) : ok([]);
+        case "diffmode": return first ? ok(opts(["auto"], ["stacked"], ["split"])) : ok([]);
+        case "ui": return first ? ok(opts(["full", "full-screen"], ["inline", "scrolls with the terminal"])) : ok([]);
+        case "mouse":
+        case "keepwarm":
+        case "lsp":
+        case "approver":
+        case "reviewer":
+        case "router": return first ? ok(onOff) : ok([]);
+        case "copy": return first ? ok(opts(["code", "the last code block"], ["all", "the whole conversation"])) : ok([]);
+        case "memory": return first ? ok([...["forget", "add"].map((v) => ({ value: v, more: true })), ...["stale", "prune", "consolidate", "graph", "embeddings"].map((v) => ({ value: v }))]) : ok([]);
+        case "permissions": return first ? ok([{ value: "list" }, ...["allow", "ask", "deny"].map((v) => ({ value: v, detail: `e.g. /permissions ${v} sh(npm test*)`, more: true }))]) : ok([]);
+        case "branch": return first ? ok(a.session.turns.map((t, i) => ({ value: String(i + 1), detail: t.text.replace(/\s+/g, " ").slice(0, 60) }))) : ok([]);
+        case "pr": return first ? ok(opts(["draft", "create it as a draft"])) : ok([]);
+        case "report": return first ? ok([{ value: "case", detail: "turn the last request into an eval task", more: true }]) : ok([]);
+        case "mcp": return first ? ok([{ value: "list" }, { value: "off" }]) : ok([]);
+        case "budget": return first ? { options: opts(["100k"], ["300k", "the default"], ["500k"], ["1m"], ["2m"]), open: true } : ok([]);
+        case "check":
+        case "verify": return first ? { options: [{ value: "off", detail: "switch it off" }], open: true } : ok([]);
+        default: return ok([]);
+    }
+}

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

@@ -16,6 +16,8 @@ export type RenderCtx = {
     diffMode: "auto" | "stacked" | "split";
     /** The block above is also a tool call: draw no blank line between them, so a run of tool calls reads as one unit. */
     tight?: boolean;
+    /** this is the most recent tool call of the lead agent: its output stays open (a short preview) until the next one starts */
+    last?: boolean;
 };
 export type Hit = {
     row: number;

package/dist/cli/tui/cards.js

@@ -123,7 +123,8 @@ export function renderBlock(b, c) {
     // ---------------------------------------------------------------- tool card
     const sub = !!b.agent && b.agent !== "lead", failed = b.status === "fail", edit = b.edit;
     const hue = failed ? t.err : ({ read_file: t.tool.read, list_files: t.tool.read, grep: t.tool.read, write_file: t.tool.edit, edit_file: t.tool.edit, apply_patch: t.tool.edit, sh: t.tool.shell, web_search: t.tool.web, fetch_url: t.tool.web, memory_save: t.tool.memory, memory_forget: t.tool.memory, memory_search: t.tool.read, todo_write: t.tool.plan, exit_plan_mode: t.tool.plan, task: t.tool.explore })[b.name] ?? (b.name.includes("__") ? t.tool.web : t.tool.generic);
-    const expanded = c.expandAll ? true : b.expanded ?? (!!edit || failed);
+    const expanded = c.expandAll ? true : b.expanded ?? (!!edit || failed || (!!c.last && !sub && b.name !== "read_file" && b.name !== "task"));
+    const preview = !c.expandAll && b.expanded === undefined && !edit && !failed && !!c.last && b.name !== "read_file" && b.name !== "task"; // opened automatically, not by the user: show a short preview only
     const bg = failed ? mix(t.surface, t.err, 0.14) : t.surface, spinner = SPIN[c.frame % SPIN.length];
     const label = BOLD(F(failed ? t.err : t.text, toolLabel(b.name))), args = F(t.dim, argSummary(b.name, b.args));
     const status = b.status === "running"
@@ -163,7 +164,7 @@ export function renderBlock(b, c) {
         }
         else {
             const res = b.result ?? "", hl = (k, s) => F(k === "plain" ? t.syn.plain : t.syn[k], s);
-            let lines = res.split("\n"), cap = c.expandAll ? 200 : 60;
+            let lines = res.split("\n"), cap = c.expandAll ? 200 : preview ? 20 : 60;
             if (b.name === "sh") {
                 let cmd = "";
                 try {
@@ -191,7 +192,7 @@ export function renderBlock(b, c) {
                         body(w); // only the lines that look like errors are red
             }
             if (lines.length > cap)
-                body(F(t.faint, `… ${lines.length - cap} more lines (ctrl+o expands everything)`));
+                body(F(t.faint, `… ${lines.length - cap} more line${lines.length - cap === 1 ? "" : "s"} · /output shows all of it${preview ? "" : " · ctrl+o expands everything"}`));
         }
     }
     return done();

package/dist/cli/tui/commands.js

@@ -3,7 +3,9 @@ import { relatives } from "./session.js";
 import { SHELL_CHOICES, STRATEGIES, chooseShell, currentShell, loadPrompts, setShell, shellFallbackNote } from "../../src/index.js";
 import { join, resolve } from "node:path";
 import { collectFiles, effortsFor, loadMcp, readBundle, writeBundle } from "../../src/index.js";
-import { CLAUDE_MODELS, OPENAI_MODELS, PROVIDERS } from "../config.js";
+import { CLAUDE_MODELS, OPENAI_MODELS, PROVIDERS, connections, keyFor, storeKey } from "../config.js";
+import { noStore, where } from "../keystore.js";
+import { fetchModels } from "../models.js";
 import { bold, cyan, dim, green, red, yellow } from "../ui.js";
 import { estimateCost, fmtCost, fmtDuration, fmtTokens } from "./pricing.js";
 import { codeBlocks } from "./clipboard.js";
@@ -15,6 +17,29 @@ import { THEMES, getTheme, themeNames } from "./themes.js";
 import { helpLines, renderDiff, toolCall, todoList } from "./view.js";
 const INIT_PROMPT = "Explore this repository and write an AGENTS.md at the repo root for future coding sessions: what the project is, how to build/test/run it (exact commands), the code layout, conventions you can verify from the code, and gotchas. Keep it under 80 lines and do not invent anything you cannot confirm from the files.";
 const EFFORTS = ["low", "medium", "high", "xhigh", "max"];
+const keyStatus = (c) => !c.needsKey ? "local, no key needed" : c.source === "env" ? `connected · from ${c.env}` : c.source === "saved" ? `connected · ${noStore() ? "this session only" : where()}` : "not connected";
+/** Make `id` the active provider, using its saved key (or asking for one). Returns false if the user gave up. */
+async function switchProvider(a, id) {
+    let apiKey = keyFor(id).key;
+    if (PROVIDERS[id].needsKey && !apiKey) {
+        apiKey = await a.askText(`${PROVIDERS[id].label} API key (hidden; ${where()})`, { secret: true });
+        if (!apiKey)
+            return false;
+    }
+    Object.assign(a.cfg, { provider: id, baseUrl: PROVIDERS[id].baseUrl, model: PROVIDERS[id].model, apiKey });
+    if (id === "custom" || id === "ollama") {
+        const m = await a.askText("Model id", { initial: a.cfg.model });
+        if (m)
+            a.cfg.model = m;
+        const u = await a.askText("Base URL", { initial: a.cfg.baseUrl });
+        if (u)
+            a.cfg.baseUrl = u;
+    }
+    a.saveConfig();
+    a.buildAgent();
+    a.say(`provider → ${cyan(PROVIDERS[id].label)}, model ${cyan(a.cfg.model)}`, dim);
+    return true;
+}
 export function buildCommands() {
     return [
         { name: "help", alias: "?", help: "keys and commands", live: true, run: (a) => a.openPager(helpLines(a.cmds, (a.io.output.columns || 80) - 1), "help") },
@@ -22,7 +47,10 @@ export function buildCommands() {
                 let id = arg;
                 if (!id) {
                     const list = a.cfg.provider === "anthropic" ? CLAUDE_MODELS : a.cfg.provider === "openai" ? OPENAI_MODELS : [{ id: a.cfg.model, hint: "current" }];
-                    const known = list.map((m) => ({ label: m.id, value: m.id, hint: m.hint }));
+                    const have = new Set(list.map((m) => m.id));
+                    a.note("asking your provider for its models…", 7000);
+                    const extra = (await fetchModels({ provider: a.cfg.provider, baseUrl: a.cfg.baseUrl, apiKey: a.cfg.apiKey })).filter((m) => !have.has(m)).map((m) => ({ id: m, hint: "from your provider" }));
+                    const known = [...list, ...extra].map((m) => ({ label: m.id, value: m.id, hint: m.hint }));
                     id = await a.pick("Model", [...known, { label: "Other…", value: "" }], Math.max(0, known.findIndex((m) => m.value === a.cfg.model)));
                     if (id === undefined)
                         return;
@@ -41,29 +69,54 @@ export function buildCommands() {
                 a.buildAgent();
                 a.say(`model → ${cyan(id)}`, dim);
             } },
-        { name: "provider", help: "switch provider (OpenAI, Claude, Ollama…)", run: async (a) => {
-                const id = await a.pick("Provider", Object.keys(PROVIDERS).map((k) => ({ label: PROVIDERS[k].label, value: k, hint: PROVIDERS[k].baseUrl })));
-                if (!id)
-                    return;
-                const key = id === "anthropic" ? process.env.ANTHROPIC_API_KEY : process.env.OPENAI_API_KEY;
-                let apiKey = key;
-                if (PROVIDERS[id].needsKey && !apiKey) {
-                    apiKey = await a.askText(`${PROVIDERS[id].label} API key (hidden; stored in ~/.amness/config.json, mode 600)`, { secret: true });
-                    if (!apiKey)
+        { name: "provider", help: "switch provider (OpenAI, Claude, Ollama…); each provider keeps its own saved key", run: async (a) => {
+                const list = connections();
+                const id = await a.pick("Provider", list.map((c) => ({ label: `${!c.needsKey || c.source !== "none" ? "●" : "○"} ${c.label}${c.id === a.cfg.provider ? "  (in use)" : ""}`, value: c.id, hint: keyStatus(c) })));
+                if (id)
+                    await switchProvider(a, id);
+            } },
+        { name: "connect", alias: "keys", help: "add, replace or remove API keys for several providers and see which are connected", run: async (a) => {
+                for (;;) {
+                    const list = connections();
+                    const id = await a.pick("Providers   ● connected   ○ not connected", list.map((c) => ({ label: `${!c.needsKey || c.source !== "none" ? "●" : "○"} ${c.label}${c.id === a.cfg.provider ? "  (in use)" : ""}`, value: c.id, hint: keyStatus(c) })));
+                    if (!id)
                         return;
+                    const c = list.find((x) => x.id === id);
+                    if (!c.needsKey) {
+                        a.say(`${c.label} needs no key. Use /provider to switch to it.`, dim);
+                        continue;
+                    }
+                    const act = c.source === "none" ? "add" : await a.pick("What do you want to do?", [
+                        ...(id === a.cfg.provider ? [] : [{ label: "Use this provider now", value: "use" }]),
+                        { label: c.source === "env" ? `Also save a key (${c.env} still wins while it is set)` : "Replace the key", value: "add" },
+                        ...(c.source === "saved" ? [{ label: "Remove the saved key", value: "remove" }] : []),
+                    ]);
+                    if (!act)
+                        continue;
+                    if (act === "use") {
+                        await switchProvider(a, id);
+                        continue;
+                    }
+                    if (act === "add") {
+                        const key = await a.askText(`${c.label} API key (hidden; ${where()})`, { secret: true });
+                        if (!key)
+                            continue;
+                        storeKey(id, key);
+                        if (id === a.cfg.provider) {
+                            a.cfg.apiKey = keyFor(id).key;
+                            a.buildAgent();
+                        }
+                        a.say(`${green("✓")} ${c.label} connected (${noStore() ? "this session only" : where()})`, dim);
+                    }
+                    else {
+                        storeKey(id, undefined);
+                        if (id === a.cfg.provider) {
+                            a.cfg.apiKey = keyFor(id).key;
+                            a.buildAgent();
+                        }
+                        a.say(`${c.label}: saved key removed`, dim);
+                    }
                 }
-                Object.assign(a.cfg, { provider: id, baseUrl: PROVIDERS[id].baseUrl, model: PROVIDERS[id].model, apiKey });
-                if (id === "custom" || id === "ollama") {
-                    const m = await a.askText("Model id", { initial: a.cfg.model });
-                    if (m)
-                        a.cfg.model = m;
-                    const u = await a.askText("Base URL", { initial: a.cfg.baseUrl });
-                    if (u)
-                        a.cfg.baseUrl = u;
-                }
-                a.saveConfig();
-                a.buildAgent();
-                a.say(`provider → ${cyan(PROVIDERS[id].label)}, model ${cyan(a.cfg.model)}`, dim);
             } },
         { name: "effort", help: "reasoning effort for the current model", args: "[level]", run: async (a, arg) => {
                 const levels = a.cfg.provider === "anthropic" ? [...EFFORTS] : effortsFor(a.cfg.model);
@@ -105,6 +158,23 @@ export function buildCommands() {
                     return void a.say(`unknown mode "${m}"`, red);
                 a.setMode(m);
             } },
+        { name: "output", alias: "last", help: "the full output of the last tool call in a pager (/output 2 for the one before)", args: "[n]", live: true, run: (a, arg) => {
+                const calls = a.blocks.blocks.filter((b) => b.kind === "tool" && (!b.agent || b.agent === "lead") && !!b.result && b.name !== "todo_write");
+                if (!calls.length)
+                    return void a.say("no tool output yet", dim);
+                const n = Math.max(1, Math.floor(Number(arg) || 1)), b = calls[calls.length - n];
+                if (!b)
+                    return void a.say(`only ${calls.length} tool call${calls.length === 1 ? "" : "s"} so far`, dim);
+                const body = b.result.split("\n");
+                let head = toolCall(b.name, b.args);
+                if (b.name === "sh") {
+                    try {
+                        head = `$ ${JSON.parse(b.args).cmd}`;
+                    }
+                    catch { /* keep the generic header */ }
+                }
+                a.openPager([head, "", ...body], "output");
+            } },
         { name: "plan", help: "enter plan mode (read-only)", run: (a) => a.setMode("plan") },
         { name: "clear", help: "start a fresh conversation", alias: "new", run: (a) => {
                 a.newConversation();

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

@@ -1,16 +1,25 @@
 export type Suggestion = {
     label: string;
     insert: string;
-    detail?: string;
+    detail?: string; /** arg suggestions: more words are expected, so do not submit on Enter */
+    more?: boolean; /** arg suggestions: any value is allowed, so Enter runs what was typed unless the user moved into the list */
+    open?: boolean; /** category header shown above the first item of each group (only when the list is not filtered) */
+    group?: string;
 };
 export type Token = {
-    kind: "slash" | "file";
+    kind: "slash" | "file" | "arg";
     query: string;
     start: number;
-    end: number;
+    end: number; /** arg tokens: the command, and the words already typed after it */
+    cmd?: string;
+    words?: string[];
 };
 /** What is the user completing right now? A slash command (first word of the input) or an @file mention. */
 export declare function tokenAtCursor(text: string, cursor: number): Token | null;
+/** Categories of the built-in commands, in the order the menu shows them. A command that is not listed (yours, or a plugin's) goes under "Custom". */
+export declare const GROUP_ORDER: readonly ["Conversation", "Model & keys", "Safety", "Quality", "Project", "Extend", "Interface", "Custom"];
+export declare const groupOf: (name: string) => string;
+/** All matching commands. With no query they come grouped by category (in GROUP_ORDER, A to Z inside a group); with a query, best match first. */
 export declare function rankCommands(query: string, cmds: {
     name: string;
     help: string;
@@ -37,3 +46,14 @@ export declare class FileIndex {
     private load;
     private walk;
 }
+export type MenuRow = {
+    head: string;
+} | {
+    item: number;
+};
+/** The rows to draw for a suggestion list: a window of `win` rows that keeps the selected item in view, with a header row above each new group (headers cannot be selected). */
+export declare function menuRows(items: Suggestion[], sel: number, win: number): {
+    rows: MenuRow[];
+    above: number;
+    below: number;
+};

package/dist/cli/tui/complete.js

@@ -8,17 +8,37 @@ export function tokenAtCursor(text, cursor) {
     const slash = before.match(/^\/(\S*)$/);
     if (slash)
         return { kind: "slash", query: slash[1], start: 0, end: cursor };
+    const arg = before.match(/^\/(\S+)((?:\s+\S+)*)\s+(\S*)$/); // "/model gp": the command, the words before the last one, the word being typed
+    if (arg)
+        return { kind: "arg", cmd: arg[1], words: arg[2].trim() ? arg[2].trim().split(/\s+/) : [], query: arg[3], start: cursor - arg[3].length, end: cursor };
     const file = before.match(/(?:^|\s)@([^\s@]*)$/);
     if (file)
         return { kind: "file", query: file[1], start: cursor - file[1].length - 1, end: cursor };
     return null;
 }
-export function rankCommands(query, cmds, limit = 8) {
+/** Categories of the built-in commands, in the order the menu shows them. A command that is not listed (yours, or a plugin's) goes under "Custom". */
+export const GROUP_ORDER = ["Conversation", "Model & keys", "Safety", "Quality", "Project", "Extend", "Interface", "Custom"];
+const GROUP_MEMBERS = {};
+for (const [g, names] of Object.entries({
+    Conversation: "output clear compact resume branch branches export import undo rewind copy todos exit",
+    "Model & keys": "model provider connect effort api models router keepwarm budget tokens",
+    Safety: "mode plan permissions policy sandbox approver hooks",
+    Quality: "verify check review reviewer lsp report loop diff",
+    Project: "init pr tools procs shell status live",
+    Extend: "memory mcp skills agents plugins reload-plugins prompt strategy profile",
+    Interface: "help theme sidebar details diffmode mouse ui",
+}))
+    for (const n of names.split(" "))
+        GROUP_MEMBERS[n] = g;
+export const groupOf = (name) => GROUP_MEMBERS[name] ?? "Custom";
+/** All matching commands. With no query they come grouped by category (in GROUP_ORDER, A to Z inside a group); with a query, best match first. */
+export function rankCommands(query, cmds, limit = 500) {
     const q = query.toLowerCase();
     const score = (c) => (c.name.startsWith(q) ? 3 : c.alias?.startsWith(q) ? 2 : c.name.includes(q) || c.alias?.includes(q) ? 1 : 0);
+    const gi = (n) => GROUP_ORDER.indexOf(groupOf(n));
     return cmds.map((c) => ({ c, score: score(c) }))
-        .filter((x) => x.score > 0 || !q).sort((a, b) => b.score - a.score || a.c.name.localeCompare(b.c.name)).slice(0, limit)
-        .map(({ c }) => ({ label: "/" + c.name, insert: "/" + c.name + " ", detail: c.help + (c.alias && !c.name.includes(query.toLowerCase()) && c.alias.includes(query.toLowerCase()) ? ` (also /${c.alias})` : "") }));
+        .filter((x) => x.score > 0 || !q).sort((a, b) => (q ? b.score - a.score : gi(a.c.name) - gi(b.c.name)) || a.c.name.localeCompare(b.c.name)).slice(0, limit)
+        .map(({ c }) => ({ group: q ? undefined : groupOf(c.name), label: "/" + c.name, insert: "/" + c.name + " ", detail: c.help + (c.alias && !c.name.includes(query.toLowerCase()) && c.alias.includes(query.toLowerCase()) ? ` (also /${c.alias})` : "") }));
 }
 /** Subsequence fuzzy match. Tries the greedy alignment and the exact-substring alignments and keeps the best. null = no match. */
 export function fuzzyScore(query, path) {
@@ -111,3 +131,18 @@ export class FileIndex {
         return out;
     }
 }
+/** The rows to draw for a suggestion list: a window of `win` rows that keeps the selected item in view, with a header row above each new group (headers cannot be selected). */
+export function menuRows(items, sel, win) {
+    const all = [];
+    let selRow = 0, last;
+    items.forEach((it, i) => { if (it.group && it.group !== last)
+        all.push({ head: it.group }); last = it.group; if (i === sel)
+        selRow = all.length; all.push({ item: i }); });
+    win = Math.max(1, win);
+    let top = Math.max(0, Math.min(selRow - Math.floor(win / 2), all.length - win));
+    if (selRow - 1 >= 0 && "head" in all[selRow - 1] && top > selRow - 1)
+        top = selRow - 1; // keep the group title with its first command
+    const rows = all.slice(top, top + win);
+    const count = (r) => r.filter((x) => "item" in x).length;
+    return { rows, above: count(all.slice(0, top)), below: count(all.slice(top + win)) };
+}

package/dist/cli/tui/full.js

@@ -1,5 +1,6 @@
 // The full-screen UI: header, scrollable transcript, sidebar, input panel, modals, toasts and mouse handling, drawn on a cell canvas.
 import { copyToClipboard } from "./clipboard.js";
+import { menuRows } from "./complete.js";
 import { basename } from "node:path";
 import { A, mix } from "./ansi.js";
 import { brandOfModel } from "./brand.js";
@@ -162,6 +163,7 @@ export class FullView {
         const live = new Set();
         const blocks = app.blocks.blocks.filter((b) => !(b.kind === "tool" && (b.name === "todo_write" || (b.parent && b.agent && b.agent !== "lead")))); // todos live in the sidebar; a subagent's steps are drawn inside its card
         let prevTool = false;
+        const lastTool = [...blocks].reverse().find((b) => b.kind === "tool" && (!b.agent || b.agent === "lead"))?.id; // its output stays open
         for (let i = 0; i < blocks.length; i++) {
             const b = blocks[i];
             live.add(b.id);
@@ -169,7 +171,7 @@ export class FullView {
             if (isQuiet(b))
                 while (i + run < blocks.length && isQuiet(blocks[i + run]))
                     run++;
-            const tctx = { ...ctx, tight: prevTool };
+            const tctx = { ...ctx, tight: prevTool, last: b.id === lastTool };
             if (run >= 2) {
                 const members = blocks.slice(i, i + run), open = this.expandAll || this.groupOpen.has(b.id);
                 const key = `g|${tctx.tight}|${open}|${ctx.theme.name}|${ctx.width}|` + members.map((m) => `${m.id}:${m.status}:${m.ms ?? 0}`).join(",") + (members.some((m) => m.status === "running") ? `|${ctx.frame}` : ""), hit = this.cache.get(b.id);
@@ -182,7 +184,7 @@ export class FullView {
                 prevTool = r.rows.length <= 2;
                 continue;
             }
-            const key = this.sig(b, tctx) + (tctx.tight ? "|t" : ""), hit = this.cache.get(b.id);
+            const key = this.sig(b, tctx) + (tctx.tight ? "|t" : "") + (tctx.last ? "|last" : ""), hit = this.cache.get(b.id);
             const r = hit && hit.key === key ? hit.r : (() => { const rr = renderBlock(b, tctx); this.cache.set(b.id, { key, r: rr }); return rr; })();
             this.items.push({ b, r, start: total });
             total += r.rows.length;
@@ -406,13 +408,19 @@ export class FullView {
         const s = this.app.sugg;
         if (!s || !s.items.length || this.app.overlay)
             return;
-        const rows = Math.min(8, s.items.length), w = Math.min(70, mainW), top = Math.max(0, Math.min(s.sel - 3, s.items.length - rows)), y = inputY - rows - 2;
-        if (y < 1)
+        const w = Math.min(86, mainW), room = inputY - 4; // rows between the top of the screen and the box
+        if (room < 3)
             return;
-        c.box(x + 1, y, w, rows + 2, { border: t.border, bg: t.surface, style: "round", title: s.kind === "slash" ? "commands" : "files", titleFg: t.dim });
-        s.items.slice(top, top + rows).forEach((it, i) => {
-            const idx = top + i, on = idx === s.sel, bg = on ? t.selection : t.surface;
-            const label = s.kind === "file" ? (() => { const n = it.label.split("/").pop(), d = it.label.slice(0, it.label.length - n.length); return F(t.faint, d) + BOLD(F(t.text, n)); })() : BOLD(F(t.accent2, it.label));
+        const { rows, above, below } = menuRows(s.items, s.sel, Math.min(14, room)), y = inputY - rows.length - 2;
+        const pos = s.items.length > rows.filter((r) => "item" in r).length ? `  ${s.sel + 1}/${s.items.length}${above ? " ↑" : ""}${below ? " ↓" : ""}` : "";
+        c.box(x + 1, y, w, rows.length + 2, { border: t.border, bg: t.surface, style: "round", title: (s.kind === "slash" ? "commands" : s.kind === "arg" ? `/${s.token.cmd} options` : "files") + pos, titleFg: t.dim });
+        rows.forEach((r, i) => {
+            if ("head" in r) {
+                c.ansi(x + 2, y + 1 + i, fit(" " + F(t.faint, "── ") + BOLD(F(t.dim, r.head)) + " " + F(t.faint, "─".repeat(Math.max(2, 24 - r.head.length))), w - 2, t.surface), {}, w - 2);
+                return;
+            }
+            const idx = r.item, it = s.items[idx], on = idx === s.sel, bg = on ? t.selection : t.surface;
+            const label = s.kind === "file" ? (() => { const n = it.label.split("/").pop(), d = it.label.slice(0, it.label.length - n.length); return F(t.faint, d) + BOLD(F(t.text, n)); })() : BOLD(F(t.accent2, it.label.padEnd(16)));
             c.ansi(x + 2, y + 1 + i, fit((on ? F(t.accent, "▌") : " ") + " " + label + (it.detail ? "  " + F(t.faint, it.detail) : ""), w - 2, bg), {}, w - 2);
             this.regions.push({ x: x + 2, y: y + 1 + i, w: w - 2, h: 1, kind: "sugg", click: () => { s.sel = idx; this.app.acceptSuggPublic(true); } });
         });
@@ -588,6 +596,8 @@ export class FullView {
     } return false; }
     /** Scroll keys; returns whether the key was used. */
     key(name, ctrl) {
+        if (this.app.sugg && (name === "pageup" || name === "pagedown"))
+            return false; // the open menu pages through its list instead
         const page = Math.max(3, Math.floor(this.viewH / 2));
         if (name === "pageup") {
             this.scrollBy(page);

package/dist/src/anthropic.d.ts

@@ -1,6 +1,6 @@
 import type { Message, Model } from "./harness.ts";
 /**
- * Claude backend via the official Anthropic SDK (an optional peer dependency: `npm i @anthropic-ai/sdk`).
+ * Claude backend via the official Anthropic SDK (an optional dependency, installed with the package: `npm i @anthropic-ai/sdk` if it is missing).
  * Defaults follow Anthropic's guidance for agent loops: adaptive thinking, auto prompt caching, streaming,
  * server-side refusal fallbacks. Credentials: `apiKey`, ANTHROPIC_API_KEY, or an `ant auth login` profile.
  */

package/docs/architecture.md

@@ -87,7 +87,7 @@ flowchart TB
 
 **Limits.** The diagrams show the main paths only. Many small files in `src/` (for example `permissions.ts`, `hooks.ts`, `sandbox.ts`) are called by the agent layer and are not drawn.
 
-The runtime has no required packages. The Claude adapter needs the optional package `@anthropic-ai/sdk`.
+The runtime has no required packages. The Claude adapter uses the optional dependency `@anthropic-ai/sdk`, which npm installs with Amness.
 
 ## Find which file does what
 

package/docs/bench.md

@@ -44,16 +44,15 @@ Do these steps in PowerShell.
 
 2. Install [Git for Windows](https://git-scm.com/download/win). The bench needs `git` on your PATH. The hidden checks of the built-in tasks use bash tools such as `test`. Amness looks for the `bash.exe` that comes with Git (in `Program Files\Git\bin`) and for any `bash.exe` on PATH. It skips `C:\Windows\System32\bash.exe`, because that is the WSL launcher and it sees other files (see `src/shell.ts`).
 
-3. Download Amness and install its packages:
+3. Install Amness from npm:
 
    ```powershell
-   git clone https://github.com/amirsdream/Amness.git
-   cd Amness
-   npm install
-   npm link
+   npm install -g amness
    amness --version
    ```
 
+   To bench the latest `main` instead of the release, install from a clone: `git clone https://github.com/amirsdream/Amness.git`, then `cd Amness`, `npm install` and `npm link`.
+
 4. Install and log in to the other tools yourself. Follow their own documentation. This page does not repeat install commands, because they change.
    - Claude Code: <https://docs.claude.com/en/docs/claude-code>
    - Codex: <https://github.com/openai/codex>

package/docs/development.md

@@ -70,7 +70,7 @@ The file `.github/workflows/ci.yml` has these jobs:
 | `windows` | `npm run typecheck` and `npm test` on Windows. It is informational (`continue-on-error`) |
 | `action` | runs the GitHub Action (`action.yml`) with no API key and checks that it reports instead of crashing |
 
-A second workflow, `.github/workflows/publish.yml`, runs type check and tests, then `npm publish`, when you push a tag that starts with `v`. It needs an `NPM_TOKEN` secret. Whether the package is published on npm is not verified here.
+A second workflow, `.github/workflows/publish.yml`, runs type check and tests, then `npm stage publish --provenance`, when you push a tag that starts with `v`. It needs an `NPM_TOKEN` secret (a stage-only token is enough). It only stages the version; you release it with `npm stage approve <id>` and your 2FA code.
 
 ## Find your way around the project
 

package/docs/getting-started.md

@@ -13,21 +13,19 @@ You need Node.js 22.18 or newer, git, and a terminal. A *diff* is a view of the
 
 ## 1. Install Amness
 
-Amness is **not on npm yet**. You install it from the source code.
+Amness is a package on npm. You install it with one command.
 
-1. Download the code and install its packages.
+1. Install it. The `-g` flag makes the `amness` command available in every folder.
 
    ```bash
-   git clone https://github.com/amirsdream/Amness.git && cd Amness && npm install
+   npm install -g amness
    ```
 
-2. Create the `amness` command.
+   This also installs the Anthropic SDK, which the Claude models use. It is an optional dependency, so Amness still installs if the SDK cannot. If you see "Claude support needs the SDK", run `npm install -g @anthropic-ai/sdk`.
 
-   ```bash
-   npm link
-   ```
+   You can also run Amness once without installing it: `npx amness`.
 
-3. Check that the command works.
+2. Check that the command works.
 
    ```bash
    amness --version
@@ -35,6 +33,17 @@ Amness is **not on npm yet**. You install it from the source code.
 
    You see a version number, for example `0.1.0`.
 
+To update later, run `npm install -g amness@latest`.
+
+**Run the latest `main` from source.** Use this if you want a change that is not released yet, or if you want to work on Amness itself:
+
+```bash
+git clone https://github.com/amirsdream/Amness.git && cd Amness && npm install
+npm link
+```
+
+`npm link` makes the `amness` command point at your clone, so `git pull` updates it.
+
 Amness is developed on macOS and Linux. The tests also run on Windows, but Windows has **no OS sandbox** for shell commands.
 
 ## 2. Set an API key or choose a local model
@@ -57,7 +66,7 @@ ollama pull qwen2.5-coder:7b
 
 Start Amness, run `/provider`, and choose "Ollama (local)". You need no key. Small local models can be weak at tool calling. See [Providers and models](providers.md).
 
-You can also do nothing now. On the first start, Amness asks you to pick a provider and paste a key. It saves the key in `~/.amness/config.json`, where only you can read it.
+You can also do nothing now. On the first start, Amness asks you to pick a provider and paste a key. It saves the key in your system's secure store (the macOS Keychain, the Linux keyring, or Windows DPAPI) and tells you which one. See [Safety](safety.md) for the details and for servers that have no keyring.
 
 ## 3. Start in a project
 

package/docs/headless.md

@@ -166,7 +166,12 @@ You see one line on stderr for each attempt, for example `attempt 1: failed veri
 
 ## Docker and GitHub Actions
 
-- A `Dockerfile` is included: `docker build -t amness .`, then `docker run -it --rm -v "$PWD":/work -e ANTHROPIC_API_KEY amness`. The old version of this page said it has not been built or tested. The README lists a Docker smoke test. **Not verified:** which of the two is right.
+- A `Dockerfile` is included: `docker build -t amness .`, then `docker run -it --rm -v "$PWD":/work -e ANTHROPIC_API_KEY amness`. CI builds the image and runs `--version` and a self-test in it (see [Development](development.md)).
+- **Keys in Docker.** Inside a container Amness never saves a key to disk. Pass it in one of two ways:
+  - an environment variable: `-e ANTHROPIC_API_KEY` (with no value, Docker copies it from your shell, so it is not typed on the command line);
+  - a Docker secret, which is mounted as a file: `-e ANTHROPIC_API_KEY_FILE=/run/secrets/anthropic`. `OPENAI_API_KEY_FILE` and `TAVILY_API_KEY_FILE` work the same way.
+
+  The image sets `AMNESS_KEYSTORE=none`. Amness also detects `/.dockerenv` and Kubernetes on its own. If you type a key into the chat in a container, it is used for that session only.
 - The repository has a GitHub Action in `action.yml`. Its inputs are `task`, `verify`, `provider`, `model`, `max-tokens` and `comment`. See [Features: Scheduled runs and the GitHub Action](features.md#scheduled-runs-and-the-github-action).
 
 ## Related pages

package/docs/library.md

@@ -17,34 +17,25 @@ Everything is exported from `src/index.ts`. The code samples on this page were t
 
 **Why you would use it.** You get the same guards as the chat (argument checks, verify gate, loop guard, budgets) inside a script, a server or a test.
 
-**How to use it.** The README says Amness is not on npm yet, and this page could not confirm a release. Use a clone.
-
-1. Clone and build:
-
-```bash
-git clone https://github.com/amirsdream/Amness.git
-cd Amness
-npm install
-npm run build
-npm pack
-```
+**How to use it.**
 
-2. Install the tarball in your own project:
+1. Install the package in your own project:
 
 ```bash
-cd ../my-project
-npm install ../Amness/amness-0.1.0.tgz
+npm install amness
 ```
 
-3. Or skip the build and import the source from the clone. Node.js can run `.ts` files:
+2. Import what you need:
 
 ```ts
-import { createCodeAgent, openai } from "../Amness/src/index.ts";
+import { createCodeAgent, openai } from "amness";
 ```
 
-The CI job `package` does steps 1 and 2 and checks that `import("amness")` works.
+To use the latest `main` before it is released, clone the repository, run `npm install && npm run build && npm pack`, and install the tarball it makes with `npm install ../Amness/amness-<version>.tgz`. You can also import the source directly, because Node.js can run `.ts` files: `import { createCodeAgent, openai } from "../Amness/src/index.ts";`.
+
+The CI job `package` packs the tarball, installs it in a new folder, and checks that `import("amness")` works.
 
-**Limits.** The Claude adapter needs the optional package `@anthropic-ai/sdk` (`npm install @anthropic-ai/sdk`). The OpenAI adapter uses plain `fetch` and has no dependency.
+**Limits.** The Claude adapter uses the optional dependency `@anthropic-ai/sdk`, which `npm install amness` adds for you (if it is missing, run `npm install @anthropic-ai/sdk`). The OpenAI adapter uses plain `fetch` and has no dependency.
 
 ## Run a coding agent