agentcoor 0.0.0-stage → 0.3.7

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# agentcoor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command-line installer and helper for [AgentCoor](https://agentcoor.nionto.com).
+It connects a machine to your AgentCoor dashboard and points your agent harnesses
+(Claude Code, Codex, OpenClaude, Cursor, or plain environment variables) at AgentCoor models.
+
+Requires Node.js 20 or newer. No runtime dependencies.
+
+## Connect a machine
+
+In the dashboard open **Hosts -> Connect a machine** to get a host ID and token, then run:
+
+```sh
+npx agentcoor connect --host-id <id>
+```
+
+The host token is read from a hidden prompt. In scripts, pipe it on stdin, pass `--token-file <path>`,
+or set `AGENTCOOR_HOST_TOKEN`. (`--token` still works but is insecure: anything on the command line can end up
+in shell history and process listings, so the CLI prints a warning.)
+
+This downloads the agent for your OS and CPU (macOS or Linux, x64 or arm64; on Windows run it inside WSL),
+checks the Ed25519 signature on the published release manifest (`release.json`) against the AgentCoor release key
+built into this CLI, refuses expired manifests and releases older than one this machine already installed, then
+verifies the binary's size and SHA-256 against that signed manifest (the install stops on any failure), installs it to
+`~/Library/Application Support/AgentCoor` on macOS or `~/.local/share/agentcoor` on Linux (the same place `install.sh`
+uses; an earlier `~/.agentcoor` agent is stopped and removed, and its session state is not carried over, so reconnect
+any sessions you need),
+writes a private config (`agent.json`, mode 600) there,
+and runs it as a per-user background service (launchd on macOS, `systemd --user` on Linux).
+If Claude Code or Codex is installed, AgentCoor tools are added to them; re-running updates the existing
+entries instead of adding duplicates.
+
+`AGENTCOOR_HOST_ID` and `AGENTCOOR_HOST_TOKEN` work in place of the flags (the token variable is removed from the
+environment before any other program is started).
+
+Advanced: to use the shell installer instead, let this package verify it first. `install.sh` is authenticated
+through the signed release manifest (`release.json` lists its SHA-256 and size), so it inherits the manifest's
+expiry and rollback floor:
+
+```sh
+npx agentcoor verify-installer --download --host-id <id>   # verifies, stages in a private temp dir, runs it there
+```
+
+Without `--host-id` it only verifies and prints the path of the private staged copy.
+
+## Use AgentCoor models
+
+Create an API key in the dashboard (**API & Credits** tab), then:
+
+```sh
+npm install -g agentcoor          # or prefix each command with npx
+agentcoor login                   # paste the key at the hidden prompt (or: --key-file <path>, stdin, AGENTCOOR_API_KEY)
+agentcoor test                    # one tiny chat completion
+agentcoor models
+agentcoor credits
+```
+
+The key is stored in `~/.agentcoor/config.json` with mode 600. The CLI does not echo it (only a masked form
+like `bbk_…abcd`), unless you ask for it with `setup --show-key`. Avoid `--key <value>`: command-line arguments are
+visible to other tools on the machine and saved in shell history.
+
+### Harness setup
+
+```sh
+agentcoor setup claude        # Claude Code
+agentcoor setup codex         # Codex
+agentcoor setup openclaude    # OpenClaude
+agentcoor setup cursor        # Cursor (printed steps only)
+agentcoor setup env           # shell exports for any OpenAI- or Anthropic-compatible client
+```
+
+By default this only prints the settings (with a placeholder key; add `--show-key` to include your key).
+Add `--write` to update the harness config file. Existing AgentCoor entries are replaced, not duplicated;
+the previous file is first backed up (`<file>.agentcoor-backup-<timestamp>-<random>`, mode 600), and a file that
+is not valid JSON/TOML is left untouched.
+
+| Harness | Written to |
+| --- | --- |
+| claude | `env` block of `~/.claude/settings.json` |
+| codex | `[model_providers.agentcoor]` and `[profiles.agentcoor]` in `~/.codex/config.toml` (run `codex --profile agentcoor`) |
+| openclaude, env | `~/.agentcoor/env.sh` (add `source ~/.agentcoor/env.sh` to your shell profile) |
+
+Endpoints:
+
+- OpenAI-compatible: `https://agentcoor.nionto.com/v1`
+- Anthropic Messages: base URL `https://agentcoor.nionto.com` (clients call `/v1/messages`)
+
+Models: `agentcoor-auto` (default, best route for the task), `agentcoor-fast` (frontier-class reasoning),
+`agentcoor-compute` (AgentCoor-hosted open models, lowest cost). Claude model names map automatically:
+opus -> agentcoor-fast, haiku -> agentcoor-compute, others -> agentcoor-auto.
+
+## Options
+
+- `--gateway <url>` or `AGENTCOOR_GATEWAY_URL`: use a different AgentCoor deployment (HTTPS required).
+- `AGENTCOOR_HOME`: CLI config directory (default `~/.agentcoor`).
+
+All requests use HTTPS with certificate verification, a timeout, no redirects, and size limits
+(1 MB for API responses and checksum files, 200 MB for the agent binary).
+
+## Development
+
+```sh
+npm test
+npm run verify-pack   # packs the tarball and checks it contains exactly the expected files
+```

package/bin/agentcoor.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+main(process.argv.slice(2)).then((code) => { process.exitCode = code ?? 0; }, (err) => {
+  process.stderr.write(`agentcoor: ${err?.message || err}\n`);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "agentcoor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.7",
+  "description": "AgentCoor CLI: connect a machine and point agent harnesses at AgentCoor models",
+  "type": "module",
+  "bin": {
+    "agentcoor": "bin/agentcoor.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "verify-pack": "node scripts/verify-pack.js",
+    "prepublishOnly": "node scripts/verify-pack.js --publish"
+  },
+  "homepage": "https://agentcoor.nionto.com",
+  "license": "UNLICENSED",
+  "keywords": [
+    "agentcoor",
+    "cli",
+    "agents",
+    "claude-code",
+    "codex"
+  ]
+}

package/src/cli.js

@@ -0,0 +1,334 @@
+import { parseArgs } from "node:util";
+import { open, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { spawnSync } from "node:child_process";
+import { createHash, timingSafeEqual } from "node:crypto";
+import { constants } from "node:fs";
+import { createInterface } from "node:readline";
+import { Writable } from "node:stream";
+import { readConfig, writeConfig, resolveSettings, isApiKey, maskKey, configPath, baseUrls, installPaths } from "./config.js";
+import { apiJson, errorMessage, download, MAX_API_BYTES } from "./http.js";
+import { plan, applyPlan, HARNESSES } from "./harness.js";
+import { connect, SECRET_ENV, childEnv, HOST_ID } from "./connect.js";
+import { keyFingerprint, RELEASE_PUBLIC_KEY } from "./signature.js";
+import { verifyManifest, installerFor, verifyArtifact, readAcceptedEpoch } from "./release.js";
+import { openExclusive } from "./fsx.js";
+import { shareModel, shareCommand } from "./share.js";
+import { listAgent, listTools, jobsCommand, sessionsCommand } from "./market.js";
+
+const HELP = `agentcoor - connect machines and agent harnesses to AgentCoor
+
+Usage:
+  agentcoor connect --host-id <id> [--token-file <path>]
+                                                     Install the agent on this machine and enroll it
+                                                     (token: hidden prompt, stdin, --token-file or AGENTCOOR_HOST_TOKEN)
+  agentcoor login [--key-file <path>]                Save your AgentCoor API key
+                                                     (key: hidden prompt, stdin, --key-file or AGENTCOOR_API_KEY)
+  agentcoor verify-installer [install.sh] [--manifest <release.json>] [--download] [--host-id <id>]
+                                                     Check install.sh against the signed release manifest
+                                                     (signature, expiry, epoch floor, SHA-256 and size),
+                                                     stage the verified bytes in a private directory, and
+                                                     run them there when --host-id is given
+                                                     (--download fetches all three from the gateway)
+  agentcoor logout                                   Remove the saved API key
+  agentcoor setup <${HARNESSES.join("|")}> [--write] [--show-key]
+                                                     Print (or write) harness config for AgentCoor
+  agentcoor models                                   List the models your key can use
+  agentcoor credits                                  Show your credit balance
+  agentcoor test [--model agentcoor-auto]            Send one tiny chat completion
+  agentcoor share-model --endpoint <url> --model <name> [--context N] [--max-concurrency N] [--private]
+                                                     Share a local OpenAI-compatible endpoint (loopback or
+                                                     tailnet only) and earn points; installs agentcoor-share
+  agentcoor share <pause|resume|withdraw|status|usage|earnings> [--listing lst_...]
+                                                     Manage the model shared from this machine
+  agentcoor <pause|resume|withdraw> [lst_...]        Aliases for agentcoor share <pause|resume|withdraw>
+  agentcoor earnings                                 Alias for agentcoor share earnings
+  agentcoor list-agent --description <text> --per-job-microusd N [--per-minute-microusd N]
+                       [--sandbox-config sandbox.json] [--harness claude-code] [--max-duration S]
+                       [--egress host1,host2] [--public]
+                                                     Linux only: probe sandbox isolation, enroll this machine
+                                                     as a marketplace worker, list an agent for batch jobs
+                                                     and install the agentcoor-worker service
+  agentcoor list-tools --tool-config tools.json [--sandbox-config sandbox.json] [--public]
+                                                     Linux only: list live tools (JSON schemas) on the same worker
+  agentcoor jobs submit --listing lst_... (--task <text> | --task-file <path>) --max-spend <microusd>
+  agentcoor jobs <get|cancel|artifacts> job_...      Rent an agent for a batch job (paid credit only)
+  agentcoor sessions open --listing lst_... --max-spend <microusd>
+  agentcoor sessions call rss_... --tool <name> [--args '<json>' | --args-file <path>]
+  agentcoor sessions close rss_...                   Rent live tools by the call or minute
+
+Options:
+  --gateway <url>   AgentCoor URL (default https://agentcoor.nionto.com, or AGENTCOOR_GATEWAY_URL)
+  --key-file <path> Read the API key from a file (default: AGENTCOOR_API_KEY, then ~/.agentcoor/config.json)
+  --key, --token    Insecure: secrets on the command line leak into shell history and process listings
+
+Create API keys in the dashboard: API & Credits tab.
+`;
+
+const OPTIONS = {
+  gateway: { type: "string" }, key: { type: "string" }, "key-file": { type: "string" }, "host-id": { type: "string" }, token: { type: "string" }, "token-file": { type: "string" },
+  write: { type: "boolean" }, "show-key": { type: "boolean" }, model: { type: "string" }, "no-verify": { type: "boolean" },
+  manifest: { type: "string" }, download: { type: "boolean" },
+  endpoint: { type: "string" }, context: { type: "string" }, "max-concurrency": { type: "string" }, private: { type: "boolean" },
+  description: { type: "string" }, "per-job-microusd": { type: "string" }, "per-minute-microusd": { type: "string" }, harness: { type: "string" },
+  "max-duration": { type: "string" }, cpu: { type: "string" }, "memory-mb": { type: "string" }, "disk-mb": { type: "string" }, egress: { type: "string" },
+  "sandbox-config": { type: "string" }, "tool-config": { type: "string" }, public: { type: "boolean" },
+  task: { type: "string" }, "task-file": { type: "string" }, "max-spend": { type: "string" }, "idempotency-key": { type: "string" },
+  tool: { type: "string" }, args: { type: "string" }, "args-file": { type: "string" },
+  "price-input": { type: "string" }, "price-output": { type: "string" }, "fleet-url": { type: "string" }, listing: { type: "string" }, replace: { type: "boolean" },
+  help: { type: "boolean", short: "h" }, version: { type: "boolean", short: "v" },
+};
+
+const ARGV_WARNING = (flag) => `warning: --${flag} puts a secret on the command line, where shell history, process listings and logs can capture it. Prefer the hidden prompt, stdin, or --${flag}-file.\n`;
+
+async function readStdin(stdin) {
+  let s = "";
+  for await (const chunk of stdin) { s += chunk; if (s.length > 64 * 1024) throw new Error("stdin input is too large"); }
+  return s.trim();
+}
+
+function hiddenPrompt(question, stdin, stderr) {
+  let muted = false;
+  const output = new Writable({ write(chunk, _enc, cb) { if (!muted) stderr.write(chunk); cb(); } });
+  const rl = createInterface({ input: stdin, output, terminal: true });
+  return new Promise((resolve) => {
+    rl.question(question, (a) => { rl.close(); stderr.write("\n"); resolve(a.trim()); });
+    muted = true;
+  });
+}
+
+export const MAX_SECRET_FILE = 64 * 1024;
+
+/**
+ * Read a small file through one descriptor: O_NOFOLLOW (no symlinks), O_NONBLOCK
+ * (a FIFO cannot hang us), fstat before reading (regular file, at most `max`
+ * bytes; for secrets also owned by us with no group/world permission bits), then
+ * a bounded read.
+ */
+export async function readSmallFile(path, max = MAX_SECRET_FILE, { requireOwner = true } = {}) {
+  let fh;
+  try { fh = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0)); }
+  catch (e) { throw new Error(e.code === "ELOOP" ? `refusing to read ${path}: it is a symbolic link` : `cannot read ${path}: ${e.code || e.message}`); }
+  try {
+    const st = await fh.stat();
+    if (!st.isFile()) throw new Error(`refusing to read ${path}: not a regular file`);
+    if (requireOwner && typeof process.getuid === "function" && st.uid !== process.getuid()) throw new Error(`refusing to read ${path}: not owned by you`);
+    if (requireOwner && (st.mode & 0o077)) throw new Error(`refusing to read ${path}: it is accessible to group or others (chmod 600 ${path})`);
+    if (st.size > max) throw new Error(`${path} is too large (limit ${max} bytes)`);
+    const buf = Buffer.alloc(max + 1);
+    let n = 0;
+    for (;;) {
+      const { bytesRead } = await fh.read(buf, n, buf.length - n, n);
+      if (bytesRead === 0) break;
+      n += bytesRead;
+      if (n > max) throw new Error(`${path} is too large (limit ${max} bytes)`);
+    }
+    return buf.subarray(0, n);
+  } finally { await fh.close(); }
+}
+
+async function readSecretFile(path) {
+  return (await readSmallFile(path)).toString("utf8").trim();
+}
+
+/** Secret precedence: --x-file, then --x (warned), then the env var, then a hidden prompt (TTY) or stdin. */
+async function resolveSecret({ file, flag, flagName, envValue, prompt, io, err }) {
+  if (file) return readSecretFile(file);
+  if (flag) { err(ARGV_WARNING(flagName)); return flag.trim(); }
+  if (envValue) return envValue.trim();
+  if (io.stdin.isTTY) return hiddenPrompt(prompt, io.stdin, io.stderr);
+  return readStdin(io.stdin);
+}
+
+async function requireKey(flags, env, err) {
+  if (flags["key-file"]) flags = { ...flags, key: await readSecretFile(flags["key-file"]) };
+  else if (flags.key) err(ARGV_WARNING("key"));
+  const s = await resolveSettings(flags, env);
+  if (!s.apiKey) throw new Error("no API key: run `agentcoor login` or set AGENTCOOR_API_KEY (create one in the dashboard, API & Credits tab)");
+  if (!isApiKey(s.apiKey)) throw new Error("the API key does not look like an AgentCoor key (bbk_...)");
+  return s;
+}
+
+/**
+ * Fetch (or read) install.sh plus release.json(.sig) and authenticate install.sh
+ * through the signed manifest: signature, expiry, epoch >= this CLI's floor and
+ * >= the epoch already accepted on this machine, then its SHA-256 and size.
+ */
+export async function loadInstaller({ download: dl, origin, path, manifestPath, env = process.env, fetcher = download, publicKey = RELEASE_PUBLIC_KEY, minEpoch, now } = {}) {
+  let script, mbuf, sig;
+  if (dl) {
+    [script, mbuf, sig] = await Promise.all(["install.sh", "release.json", "release.json.sig"].map((n) => fetcher(`${origin}/download/${n}`, { maxBytes: MAX_API_BYTES })));
+  } else {
+    const sh = path || "install.sh";
+    const mp = manifestPath || join(dirname(sh), "release.json");
+    script = await readSmallFile(sh, MAX_API_BYTES, { requireOwner: false });
+    mbuf = await readSmallFile(mp, MAX_API_BYTES, { requireOwner: false });
+    sig = await readSmallFile(`${mp}.sig`, 1024, { requireOwner: false });
+  }
+  const acceptedEpoch = await readAcceptedEpoch(installPaths(env).base);
+  const manifest = verifyManifest(mbuf, sig, { publicKey, acceptedEpoch, ...(minEpoch ? { minEpoch } : {}), ...(now ? { now } : {}) });
+  verifyArtifact(script, installerFor(manifest));
+  return { script, manifest };
+}
+
+/**
+ * Write verified bytes into a fresh private directory (mkdtemp, mode 700) through an
+ * exclusive, no-follow descriptor, read them back through that descriptor and
+ * re-check the hash, so what `sh` runs is exactly what was verified.
+ */
+export async function stageInstaller(script) {
+  const dir = await mkdtemp(join(tmpdir(), "agentcoor-installer-"));
+  const path = join(dir, "install.sh");
+  const want = createHash("sha256").update(script).digest();
+  const fh = await openExclusive(path, 0o600);
+  try {
+    await fh.writeFile(script);
+    await fh.sync();
+    const back = Buffer.alloc(script.length + 1);
+    const { bytesRead } = await fh.read(back, 0, back.length, 0);
+    if (bytesRead !== script.length || !timingSafeEqual(createHash("sha256").update(back.subarray(0, bytesRead)).digest(), want)) throw new Error("staged installer does not match the verified bytes");
+  } catch (e) { await rm(dir, { recursive: true, force: true }); throw e; }
+  finally { await fh.close(); }
+  return { dir, path };
+}
+
+export async function main(argv, { env = process.env, out = (s) => process.stdout.write(s), err = (s) => process.stderr.write(s), io = { stdin: process.stdin, stderr: process.stderr } } = {}) {
+  const { values: f, positionals } = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true });
+  const [cmd, arg, arg2] = positionals;
+  // Secrets taken from the environment are copied, then removed so no child process inherits them.
+  const scrubbed = {};
+  for (const k of SECRET_ENV) if (env[k] !== undefined) { scrubbed[k] = env[k]; delete env[k]; if (env !== process.env) delete process.env[k]; }
+  env = { ...env, ...scrubbed };
+  if (f.version) { out("0.1.0\n"); return 0; }
+  if (f.help || !cmd || cmd === "help") { out(HELP); return 0; }
+
+  switch (cmd) {
+    case "connect": {
+      const { origin } = await resolveSettings({ gateway: f.gateway }, env);
+      const hostId = f["host-id"] || env.AGENTCOOR_HOST_ID;
+      if (!hostId) throw new Error("usage: agentcoor connect --host-id <id> (copy it from the dashboard: Hosts -> Connect a machine)");
+      const hostToken = await resolveSecret({ file: f["token-file"], flag: f.token, flagName: "token", envValue: env.AGENTCOOR_HOST_TOKEN, prompt: "Host token (input hidden): ", io, err });
+      await connect({ origin, hostId, hostToken, env, log: (s) => out(s + "\n") });
+      return 0;
+    }
+    case "login": {
+      const key = await resolveSecret({ file: f["key-file"], flag: f.key, flagName: "key", envValue: env.AGENTCOOR_API_KEY, prompt: "AgentCoor API key (input hidden): ", io, err });
+      if (!key) throw new Error("usage: agentcoor login (then paste the key at the hidden prompt), or pipe it on stdin, or use --key-file <path>");
+      if (!isApiKey(key)) throw new Error("that does not look like an AgentCoor API key (expected bbk_...)");
+      const cfg = await readConfig(env);
+      const { origin } = await resolveSettings({ gateway: f.gateway }, env);
+      if (!f["no-verify"]) {
+        const r = await apiJson(origin, "/v1/models", key, { timeoutMs: 15_000 });
+        if (r.status === 401) throw new Error("AgentCoor rejected this key (it may have been revoked)");
+        if (!r.ok) err(`warning: could not verify the key (${errorMessage(r)}); saving anyway\n`);
+      }
+      await writeConfig({ ...cfg, gateway: origin, apiKey: key }, env);
+      out(`Saved API key ${maskKey(key)} to ${configPath(env)} (mode 600).\n`);
+      return 0;
+    }
+    case "verify-installer": {
+      const hostId = f["host-id"];
+      if (hostId && !HOST_ID.test(hostId)) throw new Error("the host ID contains unexpected characters; copy it again from the dashboard");
+      const { origin } = await resolveSettings({ gateway: f.gateway }, env);
+      const { script, manifest } = await loadInstaller({ download: f.download, origin, path: arg, manifestPath: f.manifest, env });
+      const staged = await stageInstaller(script);
+      out(`OK: install.sh is listed in signed release ${manifest.version} (epoch ${manifest.epoch}, expires ${manifest.expires_at}; key sha256:${keyFingerprint()}).\n`);
+      if (!hostId) {
+        out(`Verified copy staged at ${staged.path} (private directory).\nRun it with: sh ${staged.path} --host-id <id>${f.gateway ? ` --gateway ${origin}` : ""}\n`);
+        return 0;
+      }
+      try {
+        const r = spawnSync("sh", [staged.path, "--host-id", hostId, ...(f.gateway ? ["--gateway", origin] : [])], { stdio: "inherit", env: childEnv(env) });
+        return r.status ?? 1;
+      } finally { await rm(staged.dir, { recursive: true, force: true }); }
+    }
+    case "logout": {
+      const cfg = await readConfig(env);
+      delete cfg.apiKey;
+      await writeConfig(cfg, env);
+      out("Removed the saved API key.\n");
+      return 0;
+    }
+    case "setup": {
+      if (!arg) throw new Error(`usage: agentcoor setup <${HARNESSES.join("|")}> [--write]`);
+      const s = (f.write || f["show-key"]) ? await requireKey(f, env, err) : await resolveSettings(f, env);
+      const displayKey = f["show-key"] && s.apiKey ? s.apiKey : "bbk_your_key";
+      const p = plan(arg, { origin: s.origin, key: s.apiKey, displayKey, env });
+      out(p.print);
+      if (f.write) {
+        const r = await applyPlan(p);
+        if (!r) out(`\n${p.file} already points at AgentCoor; nothing changed.\n`);
+        else out(`\nWrote ${r.path}${r.backup ? ` (backup: ${r.backup})` : ""}.\n`);
+      } else if (p.file) out(`\nRun with --write to update ${p.file} (a backup is made first).\n`);
+      return 0;
+    }
+    case "models": {
+      const s = await requireKey(f, env, err);
+      const r = await apiJson(s.origin, "/v1/models", s.apiKey);
+      if (!r.ok) throw new Error(`models: ${errorMessage(r)}`);
+      for (const m of r.data?.data || []) out(`${m.id.padEnd(20)} ${m.description || ""}${m.context_length ? `  (${m.context_length.toLocaleString("en-US")} tokens)` : ""}\n`);
+      return 0;
+    }
+    case "credits": {
+      const s = await requireKey(f, env, err);
+      const r = await apiJson(s.origin, "/v1/credits", s.apiKey);
+      if (r.ok) {
+        const d = r.data || {};
+        const usd = (v) => (typeof v === "number" ? `$${(v / 1e6).toFixed(2)}` : "n/a");
+        out(`Balance:   ${usd(d.balanceMicrousd)}\nAvailable: ${usd(d.availableMicrousd)}\nReserved:  ${usd(d.reservedMicrousd)}\n`);
+        return 0;
+      }
+      if (r.status === 401) throw new Error("credits: AgentCoor rejected this key");
+      out(`Credit balances are not available to API keys yet.\nSee your balance and add credit at ${s.origin} (API & Credits tab).\n`);
+      return 0;
+    }
+    case "test": {
+      const s = await requireKey(f, env, err);
+      const model = f.model || "agentcoor-auto";
+      const t0 = Date.now();
+      const r = await apiJson(s.origin, "/v1/chat/completions", s.apiKey, {
+        method: "POST", timeoutMs: 60_000,
+        body: { model, max_tokens: 16, messages: [{ role: "user", content: "Reply with the single word: ok" }] },
+      });
+      if (!r.ok) {
+        if (r.status === 402) throw new Error(`test: out of credit. Add credit at ${s.origin} (API & Credits tab)`);
+        throw new Error(`test: ${errorMessage(r)}`);
+      }
+      const reply = r.data?.choices?.[0]?.message?.content ?? "";
+      out(`OK  ${model}  ${Date.now() - t0} ms  reply: ${JSON.stringify(String(reply).trim().slice(0, 80))}\n`);
+      if (r.data?.usage) out(`    tokens: ${r.data.usage.prompt_tokens} in / ${r.data.usage.completion_tokens} out\n`);
+      out(`    OpenAI base URL ${baseUrls(s.origin).openai}, Anthropic base URL ${baseUrls(s.origin).anthropic}\n`);
+      return 0;
+    }
+    case "share-model": {
+      const s = await requireKey(f, env, err);
+      await shareModel({ origin: s.origin, apiKey: s.apiKey, flags: f, env, log: (m) => out(m + "\n") });
+      return 0;
+    }
+    case "share": {
+      const s = await requireKey(f, env, err);
+      return shareCommand(arg, { origin: s.origin, apiKey: s.apiKey, flags: f, env, out });
+    }
+    // Top-level aliases shown in the dashboard: `agentcoor pause <listing>`, `agentcoor earnings`.
+    case "pause": case "resume": case "withdraw": case "earnings": {
+      const s = await requireKey(f, env, err);
+      const flags = arg && !f.listing ? { ...f, listing: arg } : f;
+      return shareCommand(cmd, { origin: s.origin, apiKey: s.apiKey, flags, env, out });
+    }
+    case "list-agent": case "list-tools": {
+      const s = await requireKey(f, env, err);
+      const fn = cmd === "list-agent" ? listAgent : listTools;
+      await fn({ origin: s.origin, apiKey: s.apiKey, flags: f, env, log: (m) => out(m + "\n") });
+      return 0;
+    }
+    case "jobs": case "sessions": {
+      const s = await requireKey(f, env, err);
+      const readFile = async (path) => (await readSmallFile(path, 256 * 1024, { requireOwner: false })).toString("utf8");
+      const fn = cmd === "jobs" ? jobsCommand : sessionsCommand;
+      return fn(arg, arg2, { origin: s.origin, apiKey: s.apiKey, flags: f, out, readFile });
+    }
+    default:
+      throw new Error(`unknown command "${cmd}". Run \`agentcoor --help\`.`);
+  }
+}

package/src/config.js

@@ -0,0 +1,67 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { ensurePrivateDir, atomicWrite } from "./fsx.js";
+
+export const DEFAULT_ORIGIN = "https://agentcoor.nionto.com";
+
+export function homeDir(env = process.env) {
+  return env.AGENTCOOR_HOME || join(env.HOME || homedir(), ".agentcoor");
+}
+export const configPath = (env = process.env) => join(homeDir(env), "config.json");
+
+/**
+ * Canonical agent install locations, shared with install.sh:
+ *   macOS: ~/Library/Application Support/AgentCoor (logs in ~/Library/Logs/AgentCoor)
+ *   Linux: ${XDG_DATA_HOME:-~/.local/share}/agentcoor (logs in <base>/logs)
+ * The CLI's own settings (API key) stay in ~/.agentcoor/config.json.
+ */
+export function installPaths(env = process.env, platform = process.platform) {
+  const home = env.HOME || homedir();
+  const base = platform === "darwin" ? join(home, "Library", "Application Support", "AgentCoor") : join(env.XDG_DATA_HOME || join(home, ".local", "share"), "agentcoor");
+  const logs = platform === "darwin" ? join(home, "Library", "Logs", "AgentCoor") : join(base, "logs");
+  return { base, logs, bin: join(base, "bin", "agentcoor-agent"), config: join(base, "agent.json"), state: join(base, "state") };
+}
+
+/** Normalise an origin: https only (loopback http allowed for local development), no trailing slash or path. */
+export function normalizeOrigin(raw) {
+  let u;
+  try { u = new URL(String(raw || "").trim()); } catch { throw new Error(`invalid gateway URL: ${raw}`); }
+  const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(u.hostname);
+  if (u.protocol !== "https:" && !(u.protocol === "http:" && loopback)) throw new Error("gateway URL must use https");
+  if (u.username || u.password) throw new Error("gateway URL must not contain credentials");
+  return u.origin;
+}
+
+/** Base URLs each API family expects. Anthropic clients append /v1/messages themselves. */
+export function baseUrls(origin) {
+  const o = normalizeOrigin(origin);
+  return { origin: o, anthropic: o, openai: `${o}/v1` };
+}
+
+export function isApiKey(key) { return typeof key === "string" && /^bbk_[A-Za-z0-9_-]{8,}$/.test(key); }
+
+export async function readConfig(env = process.env) {
+  try { return JSON.parse(await readFile(configPath(env), "utf8")); }
+  catch (e) { if (e.code === "ENOENT") return {}; throw new Error(`cannot read ${configPath(env)}: ${e.message}`); }
+}
+
+/** Atomic write with mode 0600 into a private (0700, owned, non-symlink) directory. */
+export async function writePrivateFile(path, content) {
+  await ensurePrivateDir(dirname(path));
+  await atomicWrite(path, content, { mode: 0o600 });
+}
+
+export async function writeConfig(cfg, env = process.env) {
+  await writePrivateFile(configPath(env), JSON.stringify(cfg, null, 2) + "\n");
+}
+
+/** Resolve gateway origin and API key: flags, then env, then config file. */
+export async function resolveSettings(flags = {}, env = process.env) {
+  const cfg = await readConfig(env);
+  const origin = normalizeOrigin(flags.gateway || env.AGENTCOOR_GATEWAY_URL || cfg.gateway || DEFAULT_ORIGIN);
+  const apiKey = flags.key || env.AGENTCOOR_API_KEY || cfg.apiKey || "";
+  return { origin, apiKey, cfg };
+}
+
+export function maskKey(key) { return key ? `bbk_…${key.slice(-4)}` : "(none)"; }