@aisa-one/cli 0.3.0 → 0.5.1

package/dist/commands/llm-config.js

@@ -0,0 +1,452 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import * as TOML from "smol-toml";
+import { expandHome, ensureDir } from "../utils/file.js";
+import { LLM_BASE_URL, LLM_RESPONSES_BASE_URL, AISA_PROVIDER_ID } from "../constants.js";
+/**
+ * Pointing a coding agent's model traffic at AIsa.
+ *
+ * Both agents support this through their own documented settings — no wrapper,
+ * no proxy process, nothing injected at runtime. Claude Code reads an `env`
+ * block from settings.json; Codex takes a named provider in config.toml. We
+ * write one block each and can remove exactly what we wrote.
+ *
+ * Everything here is reversible by key, never by rewriting the file: a user's
+ * own settings live in the same documents and must survive both directions.
+ */
+/** Written into every managed block so removal never has to guess. */
+const MANAGED_KEYS_CLAUDE = [
+    "ANTHROPIC_AUTH_TOKEN",
+    "ANTHROPIC_BASE_URL",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL",
+];
+/**
+ * Defaults follow the agent, not our preference.
+ *
+ * Each coding agent is tuned around a model family: its system prompt, tool
+ * schemas and patch format were written and evaluated against one. Codex is
+ * OpenAI's, and `gpt-5.3-codex` is the model trained for it; Claude Code is
+ * Anthropic's. Sending either somewhere else works — the gateway speaks both
+ * protocols — but it is not the pairing the agent was built for, and it is
+ * not what a user installing that agent expects. Both remain switchable.
+ */
+export const DEFAULT_MODELS = {
+    model: "claude-sonnet-5",
+    smallModel: "claude-haiku-4-5-20251001",
+    contextWindow: 200_000,
+};
+export const CODEX_DEFAULT_MODELS = {
+    model: "gpt-5.3-codex",
+    smallModel: "gpt-5.4-mini",
+    contextWindow: 400_000,
+};
+/** The default pairing for one agent. */
+export function defaultModelsFor(client) {
+    return client === "codex" ? CODEX_DEFAULT_MODELS : DEFAULT_MODELS;
+}
+// ── Claude Code ─────────────────────────────────────────────────────────────
+const claudeSettingsPath = () => expandHome("~/.claude/settings.json");
+function readJson(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        // A file we cannot parse is a file we do not own: refuse rather than
+        // replace someone's hand-edited settings.
+        return null;
+    }
+}
+export function writeClaudeCodeLLM(apiKey, models = DEFAULT_MODELS) {
+    const path = claudeSettingsPath();
+    const settings = readJson(path);
+    if (settings === null)
+        return { ok: false, reason: `${path} exists but is not valid JSON` };
+    const env = { ...(settings.env ?? {}) };
+    env.ANTHROPIC_AUTH_TOKEN = apiKey;
+    env.ANTHROPIC_BASE_URL = LLM_BASE_URL;
+    // Claude Code asks for three tiers by name; map the two it will actually
+    // reach for and leave opus pointed at the same workhorse.
+    env.ANTHROPIC_DEFAULT_HAIKU_MODEL = models.smallModel;
+    env.ANTHROPIC_DEFAULT_SONNET_MODEL = models.model;
+    env.ANTHROPIC_DEFAULT_OPUS_MODEL = models.model;
+    settings.env = env;
+    ensureDir(join(path, ".."));
+    writeFileSync(path, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+    return { ok: true, path };
+}
+export function removeClaudeCodeLLM() {
+    const path = claudeSettingsPath();
+    if (!existsSync(path))
+        return { ok: true, path };
+    const settings = readJson(path);
+    if (settings === null)
+        return { ok: false, reason: `${path} is not valid JSON` };
+    const env = settings.env;
+    if (!env)
+        return { ok: true, path };
+    for (const key of MANAGED_KEYS_CLAUDE)
+        delete env[key];
+    // An env block that only ever held our keys should not linger as `{}`.
+    if (Object.keys(env).length === 0)
+        delete settings.env;
+    writeFileSync(path, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+    return { ok: true, path };
+}
+// ── Codex ───────────────────────────────────────────────────────────────────
+const codexConfigPath = () => expandHome("~/.codex/config.toml");
+/** Codex ≥0.149: `--profile <name>` layers this file on top of the base
+ *  config rather than reading a `[profiles.<name>]` table — see
+ *  writeCodexAisaProfile for the migration this replaced. */
+const codexAisaProfilePath = () => expandHome("~/.codex/aisa.config.toml");
+function readToml(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return TOML.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writeToml(path, config) {
+    ensureDir(join(path, ".."));
+    writeFileSync(path, TOML.stringify(config) + "\n", "utf-8");
+}
+/**
+ * Codex talks the Responses API, not Chat Completions, so its base URL is the
+ * `/v1` root our gateway serves `/v1/responses` from — hence the separate
+ * constant and `wire_api = "responses"`.
+ */
+export function writeCodexLLM(apiKey, models = CODEX_DEFAULT_MODELS) {
+    const path = codexConfigPath();
+    const config = readToml(path);
+    if (config === null)
+        return { ok: false, reason: `${path} exists but is not valid TOML` };
+    // Declare the model before selecting it. Codex looks its metadata up in
+    // models.json and, finding nothing, warns and falls back to defaults —
+    // observed live against a gateway model on 2026-08-20.
+    writeCodexModelCatalog(models);
+    const providers = { ...(config.model_providers ?? {}) };
+    providers[AISA_PROVIDER_ID] = {
+        name: "AIsa",
+        base_url: LLM_RESPONSES_BASE_URL,
+        // Codex's own field name for a bearer credential on a custom provider.
+        experimental_bearer_token: apiKey,
+        wire_api: "responses",
+    };
+    config.model_providers = providers;
+    config.model_provider = AISA_PROVIDER_ID;
+    config.model = models.model;
+    config.model_catalog_json = CODEX_MODELS_PATH;
+    writeToml(path, config);
+    return { ok: true, path };
+}
+/** `~/.codex/models.json`, as Codex spells it in config. */
+const CODEX_MODELS_PATH = "~/.codex/models.json";
+/**
+ * Declare one model in Codex's catalog, preserving any other entries.
+ * Best-effort: a catalog we cannot read is left alone and Codex falls back to
+ * its warning, which is noisy but not fatal — that must not cost the user the
+ * provider config that does work.
+ */
+function writeCodexModelCatalog(models) {
+    const path = expandHome(CODEX_MODELS_PATH);
+    let catalog = { models: [] };
+    if (existsSync(path)) {
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf-8"));
+            if (parsed && Array.isArray(parsed.models))
+                catalog = parsed;
+        }
+        catch {
+            return;
+        }
+    }
+    const others = catalog.models.filter((m) => m.slug !== models.model);
+    catalog.models = [
+        ...others,
+        {
+            slug: models.model,
+            display_name: models.model,
+            description: `${models.model} through the AIsa gateway`,
+            // Required by Codex, and each level is a struct rather than a string:
+            // it rejects the catalog outright otherwise (both shapes observed live).
+            default_reasoning_level: "medium",
+            supported_reasoning_levels: [
+                { effort: "low", description: "Light reasoning" },
+                { effort: "medium", description: "Balanced reasoning" },
+                { effort: "high", description: "Deep reasoning" },
+            ],
+            shell_type: "shell_command",
+            visibility: "list",
+            supported_in_api: true,
+            priority: 0,
+            base_instructions: "",
+            supports_reasoning_summaries: true,
+            default_reasoning_summary: "none",
+            support_verbosity: false,
+            apply_patch_tool_type: "freeform",
+            // Codex's own output-truncation ceiling in bytes; unrelated to context.
+            truncation_policy: { mode: "bytes", limit: 10_000 },
+            context_window: models.contextWindow,
+            max_context_window: models.contextWindow,
+            effective_context_window_percent: 95,
+            supports_parallel_tool_calls: true,
+            experimental_supported_tools: [],
+            input_modalities: ["text"],
+        },
+    ];
+    ensureDir(join(path, ".."));
+    writeFileSync(path, JSON.stringify(catalog, null, 2) + "\n", "utf-8");
+}
+export function removeCodexLLM() {
+    const path = codexConfigPath();
+    if (!existsSync(path))
+        return { ok: true, path };
+    const config = readToml(path);
+    if (config === null)
+        return { ok: false, reason: `${path} is not valid TOML` };
+    const providers = config.model_providers;
+    if (providers) {
+        delete providers[AISA_PROVIDER_ID];
+        if (Object.keys(providers).length === 0)
+            delete config.model_providers;
+    }
+    // Only surrender the top-level selection if it is still ours: a user who
+    // switched back to another provider keeps their choice.
+    if (config.model_provider === AISA_PROVIDER_ID) {
+        delete config.model_provider;
+        delete config.model;
+        delete config.model_catalog_json;
+    }
+    // models.json is declarative metadata: harmless if left, and removing an
+    // entry Codex may share with another provider would be the riskier move.
+    writeToml(path, config);
+    return { ok: true, path };
+}
+// ── Codex MCP ───────────────────────────────────────────────────────────────
+/**
+ * Codex keeps MCP servers in the same config.toml. Note `http_headers`, not
+ * `headers` — Codex's field name, and getting it wrong fails silently at the
+ * first authenticated call rather than at load.
+ */
+export function writeCodexMCP(servers, apiKey) {
+    const path = codexConfigPath();
+    const config = readToml(path);
+    if (config === null)
+        return { ok: false, reason: `${path} exists but is not valid TOML` };
+    const mcp = { ...(config.mcp_servers ?? {}) };
+    for (const s of servers) {
+        mcp[`aisa-${s.slug}`] = {
+            type: "http",
+            url: s.endpoint,
+            ...(apiKey ? { http_headers: { Authorization: `Bearer ${apiKey}` } } : {}),
+        };
+    }
+    config.mcp_servers = mcp;
+    writeToml(path, config);
+    return { ok: true, path };
+}
+/**
+ * Swap an entry's env-var token reference for the literal Authorization header.
+ *
+ * `codex mcp add --bearer-token-env-var` is the official way to add a keyed
+ * entry without triggering the OAuth flow, but it records only the variable
+ * NAME — at runtime Codex reads the token from its own process environment,
+ * and nothing guarantees the user's shell exports it. `http_headers` is the
+ * field Codex accepts for a literal header (`bearer_token` is explicitly
+ * rejected by its config loader), and it matches what the Claude Code path
+ * already stores via --header. The env-var reference is removed so the entry
+ * has exactly one source of credentials.
+ */
+export function patchCodexMCPAuth(name, apiKey) {
+    const path = codexConfigPath();
+    const config = readToml(path);
+    if (config === null)
+        return { ok: false, reason: `${path} exists but is not valid TOML` };
+    const servers = config.mcp_servers;
+    const entry = servers?.[name];
+    if (!entry)
+        return { ok: false, reason: `no MCP entry named ${name} in ${path}` };
+    delete entry.bearer_token_env_var;
+    entry.http_headers = { Authorization: `Bearer ${apiKey}` };
+    writeToml(path, config);
+    return { ok: true, path };
+}
+// ── opencode ────────────────────────────────────────────────────────────────
+//
+// opencode has no `mcp add` command at all — its whole surface is one JSON
+// document, ~/.config/opencode/opencode.json, validated against the schema
+// at opencode.ai/config.json. Both the model provider and the MCP servers
+// are keys in that document, so this section is two writers over the same
+// file, with the same removal-by-key discipline as the other clients.
+// `opencode mcp add` creates opencode.jsonc; the schema site says .json.
+// Both are read by opencode — write whichever already exists (jsonc wins,
+// since the official command creates it), so there is never a second file
+// fighting the first.
+function opencodeConfigPath() {
+    const jsonc = expandHome("~/.config/opencode/opencode.jsonc");
+    if (existsSync(jsonc))
+        return jsonc;
+    return expandHome("~/.config/opencode/opencode.json");
+}
+/**
+ * Register AIsa as a custom provider and point the default models at it.
+ *
+ * `@ai-sdk/anthropic` is the runtime (opencode loads providers as Vercel AI
+ * SDK packages): our gateway's /v1/messages face is live and verified with a
+ * real Claude Code session, and the anthropic SDK is the pairing that face
+ * was built for. Models are declared explicitly — a custom provider has no
+ * models.dev entry to inherit from.
+ */
+export function writeOpencodeLLM(apiKey, models = DEFAULT_MODELS) {
+    const path = opencodeConfigPath();
+    const config = readJson(path);
+    if (config === null)
+        return { ok: false, reason: `${path} exists but is not valid JSON` };
+    config.$schema ??= "https://opencode.ai/config.json";
+    const provider = { ...(config.provider ?? {}) };
+    provider[AISA_PROVIDER_ID] = {
+        npm: "@ai-sdk/anthropic",
+        name: "AIsa",
+        options: { baseURL: `${LLM_BASE_URL}/v1`, apiKey },
+        models: {
+            [models.model]: { name: models.model },
+            [models.smallModel]: { name: models.smallModel },
+        },
+    };
+    config.provider = provider;
+    config.model = `${AISA_PROVIDER_ID}/${models.model}`;
+    config.small_model = `${AISA_PROVIDER_ID}/${models.smallModel}`;
+    ensureDir(join(path, ".."));
+    writeFileSync(path, JSON.stringify(config, null, 2) + "\n", "utf-8");
+    return { ok: true, path };
+}
+export function removeOpencodeLLM() {
+    const path = opencodeConfigPath();
+    if (!existsSync(path))
+        return { ok: true, path };
+    const config = readJson(path);
+    if (config === null)
+        return { ok: false, reason: `${path} is not valid JSON` };
+    const provider = config.provider;
+    if (provider) {
+        delete provider[AISA_PROVIDER_ID];
+        if (Object.keys(provider).length === 0)
+            delete config.provider;
+    }
+    // Only unset the defaults if they still point at us — a user who switched
+    // to another provider keeps their choice.
+    if (typeof config.model === "string" && config.model.startsWith(`${AISA_PROVIDER_ID}/`))
+        delete config.model;
+    if (typeof config.small_model === "string" && config.small_model.startsWith(`${AISA_PROVIDER_ID}/`))
+        delete config.small_model;
+    writeFileSync(path, JSON.stringify(config, null, 2) + "\n", "utf-8");
+    return { ok: true, path };
+}
+/**
+ * Write the MCP entries. With a key the entry carries the literal
+ * Authorization header; without one, `oauth: {}` tells opencode to run its
+ * own MCP OAuth (dynamic client registration per its schema).
+ */
+export function writeOpencodeMCP(servers, apiKey) {
+    const path = opencodeConfigPath();
+    const config = readJson(path);
+    if (config === null)
+        return { ok: false, reason: `${path} exists but is not valid JSON` };
+    config.$schema ??= "https://opencode.ai/config.json";
+    const mcp = { ...(config.mcp ?? {}) };
+    for (const s of servers) {
+        mcp[`aisa-${s.slug}`] = {
+            type: "remote",
+            url: s.endpoint,
+            enabled: true,
+            ...(apiKey ? { headers: { Authorization: `Bearer ${apiKey}` } } : { oauth: {} }),
+        };
+    }
+    config.mcp = mcp;
+    ensureDir(join(path, ".."));
+    writeFileSync(path, JSON.stringify(config, null, 2) + "\n", "utf-8");
+    return { ok: true, path };
+}
+// ── backup mode ─────────────────────────────────────────────────────────────
+//
+// "Add AIsa as a backup" for a user who already has working models: nothing
+// they rely on changes. Codex gets the provider plus an aisa.config.toml
+// profile (its native mechanism — `codex --profile aisa` layers it in for
+// one session, the default stays theirs); opencode gets the provider only
+// (its TUI lists models across providers, switching is built in). Claude
+// Code has no coexistence mechanism in its config, so its backup lives
+// entirely outside: a settings file under ~/.aisa driven through --settings
+// (see wrappers.ts).
+/**
+ * Codex backup: provider + catalog in the base config, top-level defaults
+ * untouched, and a standalone aisa.config.toml that `codex --profile aisa`
+ * (or the codex-aisa wrapper) layers on top of it.
+ *
+ * That standalone file is Codex ≥0.149's replacement for the old
+ * `[profiles.aisa]` table — `--profile <name>` now means "layer
+ * `$CODEX_HOME/<name>.config.toml`", and Codex refuses to start at all if
+ * the legacy table for that name still exists in config.toml alongside it
+ * (hit live 2026-08-24, codex-cli 0.149.1: "cannot be used while
+ * config.toml contains legacy `profile = \"aisa\"` or `[profiles.aisa]`").
+ * A machine still carrying that table from an earlier version of this
+ * writer gets it removed here — a one-time, one-way migration; nothing a
+ * user typed into it themselves would collide with a section this narrow.
+ */
+export function writeCodexAisaProfile(apiKey, models = CODEX_DEFAULT_MODELS) {
+    const path = codexConfigPath();
+    const config = readToml(path);
+    if (config === null)
+        return { ok: false, reason: `${path} exists but is not valid TOML` };
+    writeCodexModelCatalog(models);
+    const providers = { ...(config.model_providers ?? {}) };
+    providers[AISA_PROVIDER_ID] = {
+        name: "AIsa",
+        base_url: LLM_RESPONSES_BASE_URL,
+        experimental_bearer_token: apiKey,
+        wire_api: "responses",
+    };
+    config.model_providers = providers;
+    config.model_catalog_json = CODEX_MODELS_PATH;
+    if (config.profiles && typeof config.profiles === "object") {
+        const profiles = { ...config.profiles };
+        delete profiles[AISA_PROVIDER_ID];
+        if (Object.keys(profiles).length > 0)
+            config.profiles = profiles;
+        else
+            delete config.profiles;
+    }
+    writeToml(path, config);
+    writeToml(codexAisaProfilePath(), { model_provider: AISA_PROVIDER_ID, model: models.model });
+    return { ok: true, path: codexAisaProfilePath() };
+}
+/**
+ * opencode backup: provider declared, `model`/`small_model` left alone — the
+ * user picks aisa/<model> in the TUI whenever they want it.
+ */
+export function writeOpencodeAisaBackup(apiKey, models = DEFAULT_MODELS) {
+    const path = opencodeConfigPath();
+    const config = readJson(path);
+    if (config === null)
+        return { ok: false, reason: `${path} exists but is not valid JSON` };
+    config.$schema ??= "https://opencode.ai/config.json";
+    const provider = { ...(config.provider ?? {}) };
+    provider[AISA_PROVIDER_ID] = {
+        npm: "@ai-sdk/anthropic",
+        name: "AIsa",
+        options: { baseURL: `${LLM_BASE_URL}/v1`, apiKey },
+        models: {
+            [models.model]: { name: models.model },
+            [models.smallModel]: { name: models.smallModel },
+        },
+    };
+    config.provider = provider;
+    ensureDir(join(path, ".."));
+    writeFileSync(path, JSON.stringify(config, null, 2) + "\n", "utf-8");
+    return { ok: true, path };
+}

package/dist/commands/manifest.d.ts

@@ -0,0 +1,68 @@
+import type { Command } from "commander";
+import { ROUTER_EXITS, type RouterCommandContract } from "./tool-help.js";
+/**
+ * The whole command tree as JSON, for the reader this CLI actually has most of:
+ * another agent.
+ *
+ * `--help` is written for a person who can drill down. An agent gets one shot
+ * at a top-level dump, and Commander's default renders every subcommand as a
+ * bare `[options]` — the flags exist in its own metadata but never reach the
+ * page. Tested on 2026-08-24 by handing an LLM nothing but `aisa --help` and
+ * `aisa twitter --help`: it invented `--json` (the real flag is `--raw`) and
+ * could not find `api show` at all, because the `api` subtree is invisible
+ * from the top. Both are discovery failures, not reasoning failures, and both
+ * disappear once the tree is dumped in full.
+ *
+ * Nothing here is written per command: Commander already holds the flags,
+ * defaults, arguments and descriptions used to render help, so this walks that
+ * same metadata. New commands appear in the manifest the day they are added,
+ * with no second place to update.
+ */
+interface ManifestOption {
+    flags: string;
+    description: string;
+    default?: unknown;
+    /** Must this flag be passed at all. Nearly always false. */
+    mandatory: boolean;
+    /** "none" for a boolean switch, "required" for --f <v>, "optional" for --f [v]. */
+    value: "none" | "required" | "optional";
+}
+interface ManifestArgument {
+    name: string;
+    description: string;
+    required: boolean;
+    variadic: boolean;
+}
+interface ManifestCommand {
+    path: string;
+    description: string;
+    usage: string;
+    arguments: ManifestArgument[];
+    options: ManifestOption[];
+    subcommands: ManifestCommand[];
+    /** MCP operation this CLI command posts to. Absent on non-Router commands. */
+    mcp?: {
+        identifier: string;
+        path: string;
+    };
+    auth?: RouterCommandContract["auth"];
+    flow?: string;
+    enforced?: string[];
+    safety?: string[];
+    exits?: typeof ROUTER_EXITS;
+    sameRequestShapeAs?: RouterCommandContract["sameRequestShapeAs"];
+    examples?: RouterCommandContract["examples"];
+}
+export declare function buildManifest(program: Command, prefix?: string): ManifestCommand;
+/** Walk down a command path: ["twitter", "search"] -> that one node. */
+export declare function descend(root: ManifestCommand, path: string[]): ManifestCommand | undefined;
+/**
+ * A path argument, because the whole tree is ~15k tokens.
+ *
+ * An agent that needs to post a tweet should not have to read the definition
+ * of 87 commands to find out how — `aisa manifest twitter search` is under
+ * half a kilobyte. The full dump stays the default so that asking for
+ * everything still works, but the help line advertises the narrow form.
+ */
+export declare function manifestAction(program: Command, path?: string[]): void;
+export {};

package/dist/commands/manifest.js

@@ -0,0 +1,90 @@
+import { mcpForCommand } from "../cli-guidance.js";
+import { ROUTER_EXITS, routerContractFor, } from "./tool-help.js";
+/**
+ * Commander's `Option.required` means "this flag's *value* is required", not
+ * "this flag is required" — `--limit <n>` sets it while being entirely
+ * optional. Reporting it as `required` told an agent that almost every flag
+ * had to be passed, which is worse than saying nothing: it turns a correct
+ * command into an over-specified one. `mandatory` is the field that means
+ * what it sounds like, and value-ness gets its own name.
+ */
+function describeOption(o) {
+    return {
+        flags: o.flags,
+        description: o.description,
+        ...(o.defaultValue === undefined ? {} : { default: o.defaultValue }),
+        mandatory: Boolean(o.mandatory),
+        value: o.required ? "required" : o.optional ? "optional" : "none",
+    };
+}
+function describeArgument(a) {
+    return {
+        name: a.name(),
+        description: a.description,
+        required: a.required,
+        variadic: a.variadic,
+    };
+}
+/** Hidden commands are excluded: `__complete` is shell plumbing, and listing
+ *  it invites an agent to call it as if it were a feature. */
+function visible(cmd) {
+    return cmd.commands.filter((c) => !c._hidden);
+}
+export function buildManifest(program, prefix = "") {
+    const path = prefix ? `${prefix} ${program.name()}` : program.name();
+    const args = program.registeredArguments ?? [];
+    const relative = path.replace(/^aisa\s+/, "");
+    const mcp = mcpForCommand(relative);
+    const contract = routerContractFor(relative);
+    return {
+        path,
+        description: program.description(),
+        usage: `${path} ${program.usage()}`.trim(),
+        arguments: args.map(describeArgument),
+        options: program.options.map(describeOption),
+        subcommands: visible(program).map((c) => buildManifest(c, path)),
+        ...(mcp ? { mcp: { identifier: mcp.identifier, path: mcp.path } } : {}),
+        ...(contract
+            ? {
+                auth: contract.auth,
+                flow: contract.flow,
+                enforced: contract.enforced,
+                safety: contract.safety,
+                exits: ROUTER_EXITS,
+                examples: contract.examples,
+                ...(contract.sameRequestShapeAs
+                    ? { sameRequestShapeAs: contract.sameRequestShapeAs }
+                    : {}),
+            }
+            : {}),
+    };
+}
+/** Walk down a command path: ["twitter", "search"] -> that one node. */
+export function descend(root, path) {
+    let node = root;
+    for (const step of path) {
+        node = node?.subcommands.find((c) => c.path.split(" ").pop() === step);
+        if (!node)
+            return undefined;
+    }
+    return node;
+}
+/**
+ * A path argument, because the whole tree is ~15k tokens.
+ *
+ * An agent that needs to post a tweet should not have to read the definition
+ * of 87 commands to find out how — `aisa manifest twitter search` is under
+ * half a kilobyte. The full dump stays the default so that asking for
+ * everything still works, but the help line advertises the narrow form.
+ */
+export function manifestAction(program, path = []) {
+    const root = buildManifest(program);
+    const node = path.length ? descend(root, path) : root;
+    if (!node) {
+        console.error(`Unknown command: aisa ${path.join(" ")}`);
+        console.error(`Run \`aisa manifest\` with no arguments to see every command.`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(JSON.stringify(node, null, 2));
+}

package/dist/commands/mcp.d.ts

@@ -1,8 +1,67 @@
+/**
+ * `aisa mcp setup` — write real, per-client MCP entries from the live manifest.
+ *
+ * Three rules, each one a lesson from the version this replaces:
+ *
+ * 1. The server list comes from the platform's discovery manifest at setup
+ *    time, never from this file. Servers ship without a CLI release.
+ * 2. Nothing is written unless the manifest was actually fetched. The old
+ *    command wrote first and verified never, which is how a dead hostname
+ *    sat in users' configs across releases.
+ * 3. Each client gets the shape it executes: `{url}` for clients that dial
+ *    HTTP themselves, an `npx mcp-remote` stdio bridge for the ones that only
+ *    spawn processes. One shape for all three was the old bug.
+ *
+ * Auth is a choice the user already made: with an API key configured, entries
+ * carry it as a Bearer header (zero-interaction, but the key lands in each
+ * client's config file); without one, entries carry no credentials and the
+ * server's 401 challenge drives the client through the Clerk OAuth flow.
+ */
+export interface LiveServer {
+    slug: string;
+    name: string;
+    endpoint: string;
+    toolCount: number;
+    /** One-paragraph capability description from the manifest — the single
+     *  source of truth for what a server does; rendered on the connect page. */
+    description: string;
+    category: string;
+}
+export declare const stripped: (name: string) => string;
+/**
+ * Which servers exist, asked of the host that runs them.
+ *
+ * The index is preferred and the manifest is the fallback, in that order for
+ * one reason: the manifest is a snapshot committed by hand, and on 2026-08-25
+ * it was three servers and 72 tools behind what the host was actually serving.
+ * Anything derived from a running process cannot drift that way.
+ *
+ * The fallback is not defensive padding — the index is newer than some
+ * deployments, and a self-hosted gateway configured through `baseUrl` may
+ * never grow one. A user in either case should still get a working setup from
+ * a slightly stale list rather than an error.
+ */
+export declare function fetchLiveServers(): Promise<LiveServer[]>;
 /** One config entry in the shape the client actually executes. */
 export declare function buildEntry(shape: "url" | "stdio", endpoint: string, key: string | undefined): Record<string, unknown>;
+export type WriteResult = {
+    ok: true;
+    written: number;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Write the chosen servers (plus the docs server) into one client's config
+ * file. Shared by `aisa mcp setup` and `aisa connect` so the two entry points
+ * cannot drift in how they treat existing files: unparseable JSON is refused,
+ * never replaced, and only the known-dead legacy entry is cleaned up.
+ */
+export declare function writeClientConfig(agent: string, chosen: LiveServer[], key: string | undefined): WriteResult;
 export declare function mcpSetupAction(options: {
     agent?: string;
     all?: boolean;
+    yes?: boolean;
 }): Promise<void>;
 /**
  * `aisa mcp status` — what is configured, and does it actually answer.