@aisa-one/cli 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.2] — 2026-08-03
+
+### Added
+
+- **`aisa balance` now queries the live account wallet through the API-key
+  balance endpoint.** It reports both the account balance and the amount
+  available to the current API key, with `--json` support for automation.
+
 ### Fixed
 
 - **Skills registry now points at the canonical `agent-skills` repo.** The
@@ -58,5 +66,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Config commands (`aisa config get|set|list|reset`) and auth
   (`aisa login|logout|whoami`).
 
-[Unreleased]: https://github.com/AIsa-team/cli/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/AIsa-team/cli/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/AIsa-team/cli/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/AIsa-team/cli/releases/tag/v0.2.1
 [0.2.0]: https://github.com/AIsa-team/cli/releases/tag/v0.2.0

package/README.md

@@ -115,7 +115,8 @@ aisa video status <task-id>                      # check status
 ### Account
 
 ```bash
-aisa balance                # 🚧 WIP — check https://aisa.one/dashboard
+aisa balance                # Show wallet and API key credit balance
+aisa balance --json         # Output the balance response as JSON
 aisa usage --limit 20       # 🚧 WIP
 ```
 

package/dist/commands/account.d.ts

@@ -1,4 +1,7 @@
-export declare function balanceAction(): Promise<void>;
+export declare function formatMicrosUSD(micros: number | string | bigint): string;
+export declare function balanceAction(options?: {
+    json?: boolean;
+}): Promise<void>;
 export declare function usageAction(_options: {
     limit?: string;
     days?: string;

package/dist/commands/account.js

@@ -1,10 +1,38 @@
 import chalk from "chalk";
 import { requireApiKey } from "../config.js";
-import { hint } from "../utils/display.js";
-export async function balanceAction() {
-    requireApiKey();
-    console.log(chalk.yellow("  Balance API is not yet available."));
-    hint("Check your balance at https://aisa.one/dashboard");
+import { apiRequest } from "../api.js";
+import { formatJson, hint } from "../utils/display.js";
+export function formatMicrosUSD(micros) {
+    const value = typeof micros === "bigint" ? micros : BigInt(micros);
+    const negative = value < 0n;
+    let absolute = negative ? -value : value;
+    let cents = (absolute % 1000000n + 5000n) / 10000n;
+    let dollars = absolute / 1000000n;
+    if (cents === 100n) {
+        dollars += 1n;
+        cents = 0n;
+    }
+    return `${negative ? "-" : ""}$${dollars.toString()}.${cents.toString().padStart(2, "0")}`;
+}
+export async function balanceAction(options = {}) {
+    const key = requireApiKey();
+    const res = await apiRequest(key, "credits/balance");
+    if (!res.success || !res.data) {
+        throw new Error(res.error || "Failed to fetch balance");
+    }
+    if (options.json) {
+        console.log(formatJson(res.data));
+        return;
+    }
+    const balance = res.data;
+    console.log(`  Balance:             ${formatMicrosUSD(balance.account_balance_micros_usd)} ${balance.currency}`);
+    console.log(`  Available with key:  ${formatMicrosUSD(balance.available_balance_micros_usd)} ${balance.currency}`);
+    if (balance.api_key.unlimited) {
+        console.log("  API key limit:       Unlimited");
+    }
+    else {
+        console.log(`  API key limit:       ${formatMicrosUSD(balance.api_key.remaining_micros_usd)} remaining`);
+    }
 }
 export async function usageAction(_options) {
     requireApiKey();

package/dist/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.2.2";
 export declare const BASE_URL = "https://api.aisa.one";
 export declare const CLI_BASE_URL = "https://api.aisa.one/v1";
 export declare const APIS_BASE_URL = "https://api.aisa.one/apis/v1";

package/dist/constants.js

@@ -1,4 +1,4 @@
-export const VERSION = "0.2.0";
+export const VERSION = "0.2.2";
 export const BASE_URL = "https://api.aisa.one";
 export const CLI_BASE_URL = `${BASE_URL}/v1`;
 export const APIS_BASE_URL = `${BASE_URL}/apis/v1`;

package/dist/index.js

@@ -58,7 +58,8 @@ program
 // ── Account ──
 program
     .command("balance")
-    .description("Show credit balance (WIP)")
+    .description("Show credit balance")
+    .option("--json", "Output raw JSON")
     .action(wrap(balanceAction));
 program
     .command("usage")

package/dist/types.d.ts

@@ -26,8 +26,15 @@ export interface Model {
     supported_endpoint_types?: string[] | null;
 }
 export interface BalanceResponse {
-    balance: number;
     currency: string;
+    account_balance_micros_usd: number;
+    available_balance_micros_usd: number;
+    api_key: {
+        unlimited: boolean;
+        remaining_micros_usd: number;
+        used_micros_usd: number;
+    };
+    as_of: string;
 }
 export interface UsageRecord {
     timestamp: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aisa-one/cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "CLI for the AISA unified AI infrastructure platform - access 70+ LLMs, web search, finance, Twitter, and video generation APIs",
   "type": "module",
   "main": "dist/index.js",

package/tests/account.test.ts

@@ -0,0 +1,89 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { balanceAction, formatMicrosUSD } from "../src/commands/account.js";
+
+const balance = {
+  currency: "USD",
+  account_balance_micros_usd: 2_500_000,
+  available_balance_micros_usd: 1_000_000,
+  api_key: {
+    unlimited: false,
+    remaining_micros_usd: 1_000_000,
+    used_micros_usd: 300_000,
+  },
+  as_of: "2026-08-03T12:00:00Z",
+};
+
+describe("balanceAction", () => {
+  beforeEach(() => {
+    process.env.AISA_API_KEY = "test-balance-key";
+  });
+
+  afterEach(() => {
+    delete process.env.AISA_API_KEY;
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("formats microdollars without floating-point drift", () => {
+    expect(formatMicrosUSD(2_500_000)).toBe("$2.50");
+    expect(formatMicrosUSD(2_505_001)).toBe("$2.51");
+    expect(formatMicrosUSD(1_999_999)).toBe("$2.00");
+    expect(formatMicrosUSD(-1_500_000)).toBe("-$1.50");
+  });
+
+  it("requests the balance endpoint with the API key and renders the summary", async () => {
+    const fetchMock = vi.fn(async () => new Response(JSON.stringify(balance), { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await balanceAction();
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe("https://api.aisa.one/v1/credits/balance");
+    expect((init?.headers as Record<string, string>).Authorization).toBe("Bearer test-balance-key");
+    expect(log.mock.calls.map(([line]) => line).join("\n")).toContain("Balance:");
+    expect(log.mock.calls.map(([line]) => line).join("\n")).toContain("$2.50 USD");
+    expect(log.mock.calls.map(([line]) => line).join("\n")).toContain("$1.00 USD");
+    expect(log.mock.calls.map(([line]) => line).join("\n")).not.toContain("test-balance-key");
+  });
+
+  it("renders unlimited keys", async () => {
+    const fetchMock = vi.fn(async () => new Response(JSON.stringify({
+      ...balance,
+      api_key: { ...balance.api_key, unlimited: true },
+    }), { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await balanceAction();
+
+    expect(log.mock.calls.map(([line]) => line).join("\n")).toContain("API key limit:       Unlimited");
+  });
+
+  it("supports raw JSON output", async () => {
+    const fetchMock = vi.fn(async () => new Response(JSON.stringify(balance), { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await balanceAction({ json: true });
+
+    expect(JSON.parse(log.mock.calls[0][0] as string)).toEqual(balance);
+  });
+
+  it.each([401, 403, 404, 500])("raises API errors for HTTP %s", async (status) => {
+    const fetchMock = vi.fn(async () => new Response(JSON.stringify({ error: "balance unavailable" }), { status }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    await expect(balanceAction()).rejects.toThrow(`${status}: balance unavailable`);
+  });
+
+  it("raises network errors", async () => {
+    const fetchMock = vi.fn(async () => {
+      throw new Error("connection refused");
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    await expect(balanceAction()).rejects.toThrow("connection refused");
+  });
+});

package/dist/agent/env-setup.d.ts

@@ -1,5 +0,0 @@
-import type { AgentManifest } from "@aisa-one/agent-spec";
-export type Prompt = (question: string) => Promise<string>;
-export declare function collectEnv(manifest: AgentManifest, existingEnvText: string | null, deps?: {
-    prompt?: Prompt;
-}): Promise<string>;

package/dist/agent/env-setup.js

@@ -1,49 +0,0 @@
-import { getApiKey } from "../config.js";
-function parseEnvText(text) {
-    const map = new Map();
-    for (const line of (text ?? "").split("\n")) {
-        const m = line.match(/^([A-Z][A-Z0-9_]*)=(.*)$/);
-        if (m && m[2] !== "")
-            map.set(m[1], m[2]);
-    }
-    return map;
-}
-export async function collectEnv(manifest, existingEnvText, deps = {}) {
-    const prompt = deps.prompt ?? (async () => "");
-    const existing = parseEnvText(existingEnvText);
-    const values = new Map(existing);
-    // .env is user keys only. System defaults travel in the artifact's
-    // agent.json (render reads them; the installer passes them as process
-    // env for old artifacts). Legacy installs seeded system vars into .env
-    // — strip them, or updates would freeze them forever (HERMES_HOME even
-    // overrides hermes' --profile switch).
-    for (const legacy of ["HERMES_HOME", "PROFILE_ID", "MODEL_DEFAULT", "MODEL_PROVIDER"])
-        values.delete(legacy);
-    for (const v of manifest.env.required) {
-        if (values.has(v.name))
-            continue;
-        let val = process.env[v.name] || "";
-        if (!val && v.name === "AISA_API_KEY")
-            val = getApiKey() ?? "";
-        if (!val)
-            val = await prompt(`${v.name} (${v.description}): `);
-        if (!val)
-            throw new Error(`missing required ${v.name} — set it in your environment` +
-                (v.name === "AISA_API_KEY" ? ` or run "aisa login --key <key>"` : ""));
-        values.set(v.name, val);
-    }
-    const lines = [
-        `# ${manifest.name} — profile environment (managed by aisa agent install)`,
-    ];
-    for (const [k, v] of values)
-        lines.push(`${k}=${v}`);
-    for (const v of manifest.env.optional) {
-        if (values.has(v.name))
-            continue;
-        if (process.env[v.name])
-            lines.push(`${v.name}=${process.env[v.name]}`);
-        else
-            lines.push(`# ${v.name}=  (${v.description}${v.degrade ? `; degrade: ${v.degrade}` : ""})`);
-    }
-    return lines.join("\n") + "\n";
-}

package/dist/agent/index-client.d.ts

@@ -1,7 +0,0 @@
-import { type AgentIndex } from "@aisa-one/agent-spec";
-export declare const DEFAULT_INDEX_URL = "https://raw.githubusercontent.com/AIsa-team/agent-index/main/index.json";
-export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
-export declare function indexUrl(): string;
-export declare function fetchIndex(fetchImpl?: FetchLike): Promise<AgentIndex>;
-export declare function requireAgent(index: AgentIndex, id: string): AgentIndex["agents"][string];
-export declare function siblingAssetUrl(artifactUrl: string, filename: string): string;

package/dist/agent/index-client.js

@@ -1,22 +0,0 @@
-import { parseIndex } from "@aisa-one/agent-spec";
-export const DEFAULT_INDEX_URL = "https://raw.githubusercontent.com/AIsa-team/agent-index/main/index.json";
-export function indexUrl() {
-    return process.env.AISA_AGENT_INDEX_URL || DEFAULT_INDEX_URL;
-}
-export async function fetchIndex(fetchImpl = fetch) {
-    const res = await fetchImpl(indexUrl());
-    if (!res.ok)
-        throw new Error(`failed to fetch agent index (${res.status}): ${indexUrl()}`);
-    return parseIndex(await res.text());
-}
-export function requireAgent(index, id) {
-    const entry = index.agents[id];
-    if (!entry) {
-        const available = Object.keys(index.agents).sort().join(", ") || "(none)";
-        throw new Error(`unknown agent "${id}"\navailable agents: ${available}`);
-    }
-    return entry;
-}
-export function siblingAssetUrl(artifactUrl, filename) {
-    return artifactUrl.replace(/[^/]+$/, filename);
-}

package/dist/agent/installer.d.ts

@@ -1,19 +0,0 @@
-import { type AgentManifest } from "@aisa-one/agent-spec";
-import type { FetchLike } from "./index-client.js";
-export interface InstalledMarker {
-    id: string;
-    version: string;
-    target: "hermes";
-    pinned: boolean;
-}
-export declare function hermesRoot(): string;
-export declare function profileDir(id: string): string;
-export declare function downloadArtifact(url: string, sha256: string, fetchImpl?: FetchLike): Promise<Buffer>;
-export declare function extractBundle(buf: Buffer, destDir: string): Promise<void>;
-export declare function readBundleManifest(destDir: string): Promise<AgentManifest>;
-export declare function writeMarker(destDir: string, m: InstalledMarker): Promise<void>;
-export declare function readMarker(dir: string): Promise<InstalledMarker | null>;
-export declare function listInstalled(): Promise<{
-    dir: string;
-    marker: InstalledMarker;
-}[]>;

package/dist/agent/installer.js

@@ -1,70 +0,0 @@
-import { mkdir, readFile, writeFile, readdir, rename, rm, mkdtemp } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { createHash } from "node:crypto";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-import * as tar from "tar";
-import { parseManifest } from "@aisa-one/agent-spec";
-import { stringify as yamlStringify } from "yaml";
-import { expandHome } from "../utils/file.js";
-const MARKER = ".agentspec.json";
-export function hermesRoot() {
-    return expandHome(process.env.HERMES_HOME || "~/.hermes");
-}
-export function profileDir(id) {
-    return join(hermesRoot(), "profiles", id);
-}
-export async function downloadArtifact(url, sha256, fetchImpl = fetch) {
-    const res = await fetchImpl(url);
-    if (!res.ok)
-        throw new Error(`download failed (${res.status}): ${url}`);
-    const buf = Buffer.from(await res.arrayBuffer());
-    const actual = createHash("sha256").update(buf).digest("hex");
-    if (actual !== sha256)
-        throw new Error(`sha256 mismatch for ${url}\n  expected ${sha256}\n  actual   ${actual}`);
-    return buf;
-}
-export async function extractBundle(buf, destDir) {
-    const tmp = await mkdtemp(join(tmpdir(), "aisa-agent-"));
-    const tarPath = join(tmp, "bundle.tar.gz");
-    await writeFile(tarPath, buf);
-    await mkdir(destDir, { recursive: true });
-    await tar.x({ file: tarPath, cwd: destDir });
-    // promote profile/ contents to the root (hermes profile layout)
-    const profileSub = join(destDir, "profile");
-    if (existsSync(profileSub)) {
-        for (const name of await readdir(profileSub)) {
-            await rm(join(destDir, name), { recursive: true, force: true });
-            await rename(join(profileSub, name), join(destDir, name));
-        }
-        await rm(profileSub, { recursive: true, force: true });
-    }
-}
-export async function readBundleManifest(destDir) {
-    const raw = JSON.parse(await readFile(join(destDir, "agent.json"), "utf8"));
-    return parseManifest(yamlStringify(raw)); // 复用 schema 校验(YAML 是 JSON 超集)
-}
-export async function writeMarker(destDir, m) {
-    await writeFile(join(destDir, MARKER), JSON.stringify(m, null, 2) + "\n");
-}
-export async function readMarker(dir) {
-    try {
-        return JSON.parse(await readFile(join(dir, MARKER), "utf8"));
-    }
-    catch {
-        return null;
-    }
-}
-export async function listInstalled() {
-    const root = join(hermesRoot(), "profiles");
-    if (!existsSync(root))
-        return [];
-    const out = [];
-    for (const name of await readdir(root)) {
-        const dir = join(root, name);
-        const marker = await readMarker(dir);
-        if (marker)
-            out.push({ dir, marker });
-    }
-    return out.sort((a, b) => a.marker.id.localeCompare(b.marker.id));
-}

package/dist/agent/setup-python.d.ts

@@ -1,15 +0,0 @@
-import type { AgentManifest } from "@aisa-one/agent-spec";
-export type Exec = (cmd: string, args: string[]) => Promise<{
-    code: number;
-    stdout: string;
-    stderr: string;
-}>;
-export declare const SKIP_OPTIONAL_ENV = "AGENT_SKIP_OPTIONAL_SETUP";
-export declare const SETUP_PYTHON_ENV = "AGENT_SETUP_PYTHON";
-export interface SetupResult {
-    name: string;
-    status: "ok" | "skipped" | "failed";
-}
-/** Build the venvs declared in manifest.setup.python and point their env vars
- *  at the venv interpreters (written into <profileDir>/.env). */
-export declare function runPythonSetup(manifest: AgentManifest, profileDir: string, exec: Exec): Promise<SetupResult[]>;

package/dist/agent/setup-python.js

@@ -1,51 +0,0 @@
-import { readFile, writeFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-export const SKIP_OPTIONAL_ENV = "AGENT_SKIP_OPTIONAL_SETUP";
-// venv 基础解释器覆盖(如系统 python3 过旧时指向 python3.12)
-export const SETUP_PYTHON_ENV = "AGENT_SETUP_PYTHON";
-async function upsertEnvLine(dir, key, value) {
-    const envPath = join(dir, ".env");
-    const text = existsSync(envPath) ? await readFile(envPath, "utf8") : "";
-    const lines = text.split("\n").filter((l) => !l.startsWith(`${key}=`));
-    while (lines.length && lines[lines.length - 1] === "")
-        lines.pop();
-    lines.push(`${key}=${value}`);
-    await writeFile(envPath, lines.join("\n") + "\n");
-}
-/** Build the venvs declared in manifest.setup.python and point their env vars
- *  at the venv interpreters (written into <profileDir>/.env). */
-export async function runPythonSetup(manifest, profileDir, exec) {
-    const skipOptional = process.env[SKIP_OPTIONAL_ENV] === "1";
-    const results = [];
-    for (const s of manifest.setup.python) {
-        if (s.optional && skipOptional) {
-            console.log(`setup ${s.name}: optional, skipped (${SKIP_OPTIONAL_ENV}=1)`);
-            results.push({ name: s.name, status: "skipped" });
-            continue;
-        }
-        const venvDir = join(profileDir, ".venvs", s.name);
-        const venvPython = join(venvDir, "bin", "python");
-        const reqPath = join(profileDir, s.requirements);
-        const basePython = process.env[SETUP_PYTHON_ENV] || "python3";
-        console.log(`setup ${s.name}: building venv (${s.requirements})…`);
-        const created = await exec(basePython, ["-m", "venv", venvDir]);
-        const installed = created.code === 0
-            ? await exec(venvPython, ["-m", "pip", "install", "-r", reqPath])
-            : created;
-        if (installed.code !== 0) {
-            const detail = installed.stderr.slice(-500);
-            if (!s.optional)
-                throw new Error(`setup ${s.name} failed (required):\n${detail}`);
-            console.log(`setup ${s.name}: failed, degrading (optional). ${s.description ?? ""}`);
-            if (detail.trim())
-                console.log(`  reason: ${detail.trim().split("\n").slice(-3).join(" | ")}`);
-            results.push({ name: s.name, status: "failed" });
-            continue;
-        }
-        await upsertEnvLine(profileDir, s.env, venvPython);
-        console.log(`setup ${s.name}: ok -> ${s.env}=${venvPython}`);
-        results.push({ name: s.name, status: "ok" });
-    }
-    return results;
-}

package/dist/commands/agent.d.ts

@@ -1,37 +0,0 @@
-import { type FetchLike } from "../agent/index-client.js";
-import { type Prompt } from "../agent/env-setup.js";
-import type { AgentIndex } from "@aisa-one/agent-spec";
-export type Exec = (cmd: string, args: string[]) => Promise<{
-    code: number;
-    stdout: string;
-    stderr: string;
-}>;
-export declare function agentListAction(_opts: Record<string, never>, deps?: {
-    fetchImpl?: FetchLike;
-}): Promise<AgentIndex>;
-export declare function agentInfoAction(id: string, deps?: {
-    fetchImpl?: FetchLike;
-}): Promise<AgentIndex["agents"][string]>;
-export declare function agentInstallAction(id: string, opts: {
-    version?: string;
-    runtime?: string;
-}, deps?: {
-    fetchImpl?: FetchLike;
-    prompt?: Prompt;
-    exec?: Exec;
-}): Promise<void>;
-export declare function agentUpdateAction(id: string | undefined, _opts: Record<string, never>, deps?: {
-    fetchImpl?: FetchLike;
-    prompt?: Prompt;
-    exec?: Exec;
-}): Promise<{
-    id: string;
-    from: string;
-    to: string;
-    status: "updated" | "up-to-date" | "pinned";
-}[]>;
-export declare function agentGuideAction(id: string, opts: {
-    md?: boolean;
-}, deps?: {
-    fetchImpl?: FetchLike;
-}): Promise<string>;

package/dist/commands/agent.js

@@ -1,129 +0,0 @@
-import chalk from "chalk";
-import { readFile, writeFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import { execFile } from "node:child_process";
-import { table, success, hint, truncate } from "../utils/display.js";
-import { fetchIndex, requireAgent, siblingAssetUrl } from "../agent/index-client.js";
-import { hermesRoot, profileDir, downloadArtifact, extractBundle, readBundleManifest, writeMarker, listInstalled, } from "../agent/installer.js";
-import { collectEnv } from "../agent/env-setup.js";
-import { runPythonSetup } from "../agent/setup-python.js";
-const realExec = (cmd, args) => new Promise((resolve) => {
-    execFile(cmd, args, (err, stdout, stderr) => resolve({ code: err ? 1 : 0, stdout: String(stdout), stderr: String(stderr) }));
-});
-export async function agentListAction(_opts, deps = {}) {
-    const index = await fetchIndex(deps.fetchImpl);
-    const rows = Object.entries(index.agents).sort(([a], [b]) => a.localeCompare(b))
-        .map(([id, e]) => [id, e.name, e.latest, truncate(e.description, 60)]);
-    console.log(table(["ID", "NAME", "LATEST", "DESCRIPTION"], rows));
-    hint(`install one with: aisa agent install <id>`);
-    return index;
-}
-export async function agentInfoAction(id, deps = {}) {
-    const index = await fetchIndex(deps.fetchImpl);
-    const e = requireAgent(index, id);
-    console.log(`${chalk.bold(e.name)} (${id})`);
-    console.log(`  ${e.description}`);
-    console.log(`  repo:   https://github.com/${e.repo}`);
-    console.log(`  latest: ${e.latest}`);
-    for (const [v, spec] of Object.entries(e.versions))
-        console.log(`  ${v}: targets ${Object.keys(spec.targets).join(", ")}`);
-    hint(`install with: aisa agent install ${id}`);
-    return e;
-}
-export async function agentInstallAction(id, opts, deps = {}) {
-    const runtime = opts.runtime ?? "hermes";
-    if (runtime !== "hermes")
-        throw new Error(`runtime "${runtime}" not supported yet — v1 supports: hermes`);
-    if (!existsSync(hermesRoot()))
-        throw new Error(`hermes not found at ${hermesRoot()} — install it first:\n` +
-            `  curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash`);
-    const index = await fetchIndex(deps.fetchImpl);
-    const entry = requireAgent(index, id);
-    const version = opts.version ?? entry.latest;
-    const versionSpec = entry.versions[version];
-    if (!versionSpec)
-        throw new Error(`version ${version} not found for ${id} — available: ${Object.keys(entry.versions).join(", ")}`);
-    const artifact = versionSpec.targets[runtime];
-    if (!artifact)
-        throw new Error(`no ${runtime} artifact for ${id}@${version}`);
-    const dir = profileDir(id);
-    const existingEnv = existsSync(join(dir, ".env"))
-        ? await readFile(join(dir, ".env"), "utf8") : null;
-    const buf = await downloadArtifact(artifact.url, artifact.sha256, deps.fetchImpl);
-    await extractBundle(buf, dir);
-    const manifest = await readBundleManifest(dir);
-    const envText = await collectEnv(manifest, existingEnv, { prompt: deps.prompt });
-    await writeFile(join(dir, ".env"), envText);
-    const exec = deps.exec ?? realExec;
-    // system vars go to render as process env, never into .env — new render.sh
-    // reads them from the bundled agent.json itself, old artifacts (≤1.0.4)
-    // still require them in the environment
-    const r = await exec("env", [
-        `PROFILE_ID=${manifest.id}`,
-        `MODEL_DEFAULT=${manifest.models.default}`,
-        `MODEL_PROVIDER=${manifest.models.provider}`,
-        "bash", join(dir, "scripts", "render.sh"), dir,
-    ]);
-    if (r.code !== 0)
-        throw new Error(`render failed: ${r.stderr}`);
-    await runPythonSetup(manifest, dir, exec);
-    await writeMarker(dir, {
-        id, version, target: "hermes",
-        pinned: !!opts.version || manifest.update.channel === "pinned",
-    });
-    success(`installed ${entry.name} ${version} -> ${dir}`);
-    hint(`start it with: hermes --profile ${id}`);
-}
-export async function agentUpdateAction(id, _opts, deps = {}) {
-    const installed = await listInstalled();
-    const targets = id ? installed.filter((i) => i.marker.id === id) : installed;
-    if (id && targets.length === 0)
-        throw new Error(`agent "${id}" is not installed (no .agentspec.json marker found)`);
-    if (targets.length === 0) {
-        hint("no installed agents found");
-        return [];
-    }
-    const index = await fetchIndex(deps.fetchImpl);
-    const results = [];
-    for (const { marker } of targets) {
-        if (marker.pinned) {
-            console.log(`${marker.id}: pinned at ${marker.version} — skipping`);
-            results.push({ id: marker.id, from: marker.version, to: marker.version, status: "pinned" });
-            continue;
-        }
-        const entry = index.agents[marker.id];
-        if (!entry || entry.latest === marker.version) {
-            results.push({ id: marker.id, from: marker.version, to: marker.version, status: "up-to-date" });
-            continue;
-        }
-        await agentInstallAction(marker.id, {}, deps); // install 已保留 .env、更新 marker
-        results.push({ id: marker.id, from: marker.version, to: entry.latest, status: "updated" });
-    }
-    for (const r of results)
-        if (r.status === "updated")
-            success(`${r.id}: ${r.from} -> ${r.to}`);
-    return results;
-}
-export async function agentGuideAction(id, opts, deps = {}) {
-    const fetchImpl = deps.fetchImpl ?? fetch;
-    const index = await fetchIndex(deps.fetchImpl);
-    const entry = requireAgent(index, id);
-    const artifact = entry.versions[entry.latest]?.targets["hermes"];
-    if (!artifact)
-        throw new Error(`no hermes artifact for ${id}@${entry.latest}`);
-    // 优先读索引携带的资产 URL(2026-07-15 起 publish 写入);老条目回落到
-    // legacy 裸文件名拼接,保证旧版本 Release 仍可用
-    const url = opts.md
-        ? (artifact.installMd ?? siblingAssetUrl(artifact.url, "INSTALL.md"))
-        : (artifact.guidePrompt ?? siblingAssetUrl(artifact.url, "guide-prompt.txt"));
-    const filename = url.split("/").pop();
-    const res = await fetchImpl(url);
-    if (!res.ok)
-        throw new Error(`failed to fetch ${filename} (${res.status}): ${url}`);
-    const text = await res.text();
-    console.log(text);
-    if (!opts.md)
-        hint("paste the text above into your local AI agent (Claude Code, hermes, …)");
-    return text;
-}