@agentcentral/cli 0.1.2 → 0.1.3

package/README.md

@@ -53,6 +53,7 @@ The config lives at `${XDG_CONFIG_HOME:-~/.config}/agentcentral/config.json`, wr
 ```bash
 agentcentral tools list                         # key-scoped tools (json)
 agentcentral tools list --format table          # aligned table
+agentcentral tools list --domain inventory      # filter by server domain
 agentcentral tools describe get_orders          # full descriptor
 agentcentral tools schema get_orders            # raw JSON Schema
 
@@ -62,6 +63,12 @@ agentcentral tools call get_orders @args.json
 echo '{"limit":5}' | agentcentral tools call get_orders -
 ```
 
+A new hosted tool is callable (`tools list`, `describe`, `schema`, `call`) with no CLI release. The one
+caveat is domain filtering: `tools list --domain` and `mcp serve --domain` fall back to the bundled
+`TOOL_DOMAINS` registry from `@agent-central/shared` when the server omits `_meta` domain hints, so a
+brand-new tool will not appear under a domain filter until that registry is updated (or the server emits
+the tool's domain via `_meta`).
+
 Write tools default to a non-mutating **preview**. To submit, pass `--yes` and an `--idempotency-key`:
 
 ```bash
@@ -69,6 +76,25 @@ agentcentral tools call update_keyword_bids @bids.json \
   --yes --idempotency-key "$(uuidgen)"
 ```
 
+### Convenience read commands
+
+Thin wrappers over the same hosted read tools. Each maps friendly flags onto the exact parameters its
+backing tool declares. They return facts only and add no recommendations or agentcentral-authored next
+actions.
+
+```bash
+agentcentral inventory health                  # -> get_inventory_health (--limit)
+agentcentral inventory risk --asin B00...       # -> get_inventory_risk_triage (--asin, --limit)
+agentcentral ads performance --since 30d        # -> get_campaign_performance (--since, --limit)
+agentcentral catalog quality --asin B00...      # -> get_listing_quality (--asin, --limit)
+agentcentral actions history --since 7d         # -> get_action_history (--since, --limit; needs agent_actions:read scope)
+agentcentral today --fulfillment-channel AFN    # -> get_todays_sales (current-day only; --fulfillment-channel AFN|MFN, --limit)
+agentcentral orders --since 30d --asin B00...   # -> get_orders (--since, --asin, --fulfillment-channel AFN|MFN, --limit)
+```
+
+`--since` accepts a relative lookback (`30d`) or an absolute `YYYY-MM-DD` date. `today` is current-day
+only and takes no `--since`.
+
 ### Run the stdio MCP bridge
 
 `mcp serve` relays newline-delimited JSON-RPC between a local MCP client and the hosted server. stdout
@@ -92,9 +118,13 @@ agentcentral doctor --format markdown
 
 ## Global flags
 
-Every command accepts: `--format/-f json|ndjson|table`, `--output/-o <path>`, `--profile/-p <name>`,
-`--timeout <ms>`, `--limit <n>`, `--quiet/-q`, `--no-color`, `--verbose`, `--request-id <id>`,
-`--yes/-y`, `--idempotency-key <key>`, `--api-key-stdin`.
+Every command accepts: `--format/-f json|ndjson|table|csv|markdown`, `--output/-o <path>`,
+`--profile/-p <name>`, `--timeout <ms>`, `--limit <n>`, `--quiet/-q`, `--no-color`, `--verbose`,
+`--request-id <id>`, `--yes/-y`, `--idempotency-key <key>`, `--api-key-stdin`.
+
+When `--limit <n>` is set and the result comes back with exactly `n` rows, the CLI emits a best-effort
+truncation WARNING to stderr. The hosted server exposes no truncation flag or total-row count, so this
+is a heuristic, it only fires when `--limit` is set, and it never touches stdout.
 
 ## Exit codes
 

package/dist/index.js

@@ -34,13 +34,14 @@ var API_KEY_PREFIX = "ac_live_";
 
 // src/config.ts
 import {
-  chmodSync,
   closeSync,
   existsSync,
   fstatSync,
   mkdirSync,
   openSync,
   readFileSync,
+  renameSync,
+  unlinkSync,
   writeFileSync
 } from "fs";
 import { homedir } from "os";
@@ -107,9 +108,23 @@ function loadConfig(env = process.env) {
 function saveConfig(config, env = process.env) {
   const path = configPath(env);
   const dir = dirname(path);
+  const tmp = `${path}.${process.pid}.tmp`;
   mkdirSync(dir, { recursive: true, mode: 448 });
-  writeFileSync(path, JSON.stringify(config, null, 2), { mode: 384 });
-  chmodSync(path, 384);
+  const data = JSON.stringify(config, null, 2);
+  try {
+    writeFileSync(tmp, data, { mode: 384, flag: "wx" });
+    renameSync(tmp, path);
+  } catch (error) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+    }
+    throw new CliError(
+      1 /* GeneralFailure */,
+      `failed to write config ${path}`,
+      error instanceof Error ? error.message : String(error)
+    );
+  }
 }
 function upsertProfile(config, profile) {
   const exists = config.profiles.some((p) => p.name === profile.name);
@@ -243,7 +258,128 @@ async function resolveAuth(input) {
   };
 }
 
+// src/exit-codes.ts
+var RPC_INVALID_PARAMS = -32602;
+var DETAIL_MAX_LENGTH = 180;
+var PERMISSION_PATTERN = /no_amazon|not connected|expired|suspended|revoked|past_due|trial expired|permission|not authorized|scope/i;
+var VALIDATION_PATTERN = /invalid|validation|must be|required/i;
+function writeEnvelopeFrom(result) {
+  const structured = result.structuredContent;
+  if (!structured) {
+    return void 0;
+  }
+  const hasWriteShape = "mode" in structured || "status" in structured || "requested_count" in structured;
+  if (!hasWriteShape) {
+    return void 0;
+  }
+  return structured;
+}
+function toolClassification(def) {
+  const hint = def.annotations;
+  const annotationWrite = hint?.destructiveHint === true || hint?.readOnlyHint === false;
+  const properties = def.inputSchema.properties;
+  const props = properties && typeof properties === "object" ? properties : {};
+  const schemaWrite = "confirm" in props && "idempotency_key" in props;
+  const isWrite = annotationWrite || schemaWrite;
+  return {
+    isWrite,
+    supportsPreview: isWrite
+  };
+}
+function classifyToolText(text) {
+  if (PERMISSION_PATTERN.test(text)) {
+    return 4 /* PermissionDenied */;
+  }
+  if (VALIDATION_PATTERN.test(text)) {
+    return 5 /* ValidationFailed */;
+  }
+  return void 0;
+}
+function joinContentText(result) {
+  return result.content.map((block) => typeof block.text === "string" ? block.text : "").filter((text) => text.length > 0).join(" ").trim();
+}
+function truncateDetail(text) {
+  if (text.length <= DETAIL_MAX_LENGTH) {
+    return text;
+  }
+  return `${text.slice(0, DETAIL_MAX_LENGTH)}\u2026`;
+}
+function classifyWriteStatus(status) {
+  switch (status) {
+    case "validation_error":
+      return 5 /* ValidationFailed */;
+    case "partial":
+      return 9 /* PartialWrite */;
+    case "blocked":
+    case "failed":
+      return 7 /* ToolExecutionFailed */;
+    case "duplicate_blocked":
+    case "accepted":
+    case "preview":
+    default:
+      return 0 /* Success */;
+  }
+}
+function summarizeWriteEnvelope(env) {
+  const parts = [];
+  if (typeof env.requested_count === "number") {
+    parts.push(`requested=${env.requested_count}`);
+  }
+  if (typeof env.accepted_count === "number") {
+    parts.push(`accepted=${env.accepted_count}`);
+  }
+  if (typeof env.failed_count === "number") {
+    parts.push(`failed=${env.failed_count}`);
+  }
+  if (typeof env.previewed_count === "number") {
+    parts.push(`previewed=${env.previewed_count}`);
+  }
+  const status = env.status ?? "unknown";
+  return parts.length > 0 ? `${status} (${parts.join(", ")})` : status;
+}
+function classifyResponse(response) {
+  if (response.error) {
+    const message = response.error.message;
+    const code = response.error.code === RPC_INVALID_PARAMS ? 5 /* ValidationFailed */ : classifyToolText(message) ?? 7 /* ToolExecutionFailed */;
+    return {
+      code,
+      status: "rpc_error",
+      detail: message
+    };
+  }
+  const result = response.result;
+  const env = writeEnvelopeFrom(result);
+  if (env?.status) {
+    return {
+      code: classifyWriteStatus(env.status),
+      status: env.status,
+      detail: summarizeWriteEnvelope(env),
+      result
+    };
+  }
+  if (result.isError) {
+    const text = joinContentText(result);
+    const code = classifyToolText(text) ?? 7 /* ToolExecutionFailed */;
+    return {
+      code,
+      status: "tool_error",
+      detail: truncateDetail(text),
+      result
+    };
+  }
+  return {
+    code: 0 /* Success */,
+    status: "ok",
+    detail: truncateDetail(joinContentText(result)),
+    result
+  };
+}
+
 // src/transport.ts
+var RPC_INVALID_PARAMS2 = -32602;
+function classifyRpcError(error) {
+  return error.code === RPC_INVALID_PARAMS2 ? 5 /* ValidationFailed */ : classifyToolText(error.message) ?? 7 /* ToolExecutionFailed */;
+}
 function parseSseJsonRpc(text) {
   const dataLines = text.trim().split(/\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trim());
   return JSON.parse(dataLines.length ? dataLines.join("\n") : text);
@@ -293,13 +429,14 @@ function createClient(auth, opts = {}) {
     counter += 1;
     return counter;
   };
-  async function attempt(method, params, id, timeoutMs) {
+  async function attempt(method, params, id, timeoutMs, notification) {
+    const requestBody = notification ? { jsonrpc: "2.0", method, params } : { jsonrpc: "2.0", id, method, params };
     let res;
     try {
       res = await fetch(auth.endpoint, {
         method: "POST",
         headers,
-        body: JSON.stringify({ jsonrpc: "2.0", id, method, params }),
+        body: JSON.stringify(requestBody),
         signal: AbortSignal.timeout(timeoutMs)
       });
     } catch (error) {
@@ -336,16 +473,20 @@ function createClient(auth, opts = {}) {
         method
       );
     }
+    if (notification) {
+      return { jsonrpc: "2.0" };
+    }
     return parseSseJsonRpc(text);
   }
   async function rpc(method, params, rpcOpts) {
     const timeoutMs = rpcOpts?.timeoutMs ?? defaultTimeoutMs;
+    const notification = rpcOpts?.notification === true;
     const id = rpcOpts?.id ?? nextId();
     const maxAttempts = Math.max(1, retry.maxAttempts);
     let lastReason = "transport failure";
     for (let n = 1; n <= maxAttempts; n += 1) {
       try {
-        return await attempt(method, params ?? {}, id, timeoutMs);
+        return await attempt(method, params ?? {}, id, timeoutMs, notification);
       } catch (error) {
         if (error instanceof CliError) {
           throw error;
@@ -370,7 +511,7 @@ function createClient(auth, opts = {}) {
   async function listTools(listOpts) {
     const response = await rpc("tools/list", {}, { timeoutMs: listOpts?.timeoutMs });
     if (response.error) {
-      throw new CliError(7 /* ToolExecutionFailed */, response.error.message, "tools/list");
+      throw new CliError(classifyRpcError(response.error), response.error.message, "tools/list");
     }
     const result = response.result ?? {};
     return result.tools ?? [];
@@ -382,7 +523,7 @@ function createClient(auth, opts = {}) {
       { timeoutMs: callOpts?.timeoutMs }
     );
     if (response.error) {
-      throw new CliError(7 /* ToolExecutionFailed */, response.error.message, name);
+      throw new CliError(classifyRpcError(response.error), response.error.message, name);
     }
     return response.result ?? {};
   }
@@ -1473,7 +1614,7 @@ var TOOL_DOMAINS = [
       { name: "get_buybox_status", description: "Live Buy Box status plus daily win-rate history" },
       { name: "get_competitive_pricing", description: "Live price points plus historical pricing snapshots" },
       { name: "get_offer_listings", description: "Live seller offers for an ASIN" },
-      { name: "get_replenishment_offers", description: "Live and historical Subscribe and Save replenishment offer status" },
+      { name: "get_subscribe_and_save", description: "Subscribe & Save offer status, history, and Amazon-provided metrics" },
       { name: "get_fba_eligibility", description: "Check FBA eligibility per ASIN" },
       { name: "get_listing_restrictions", description: "Listing restrictions and approvals" }
     ]
@@ -2032,7 +2173,7 @@ var TOOL_MARKETPLACE_SUPPORT_DECLARED_TOOL_NAMES = [
   "get_buybox_status",
   "get_competitive_pricing",
   "get_offer_listings",
-  "get_replenishment_offers",
+  "get_subscribe_and_save",
   "get_fba_eligibility",
   "get_listing_restrictions",
   "get_financial_events",
@@ -3146,123 +3287,6 @@ function formatOutput(value, format) {
   }
 }
 
-// src/exit-codes.ts
-var RPC_INVALID_PARAMS = -32602;
-var DETAIL_MAX_LENGTH = 180;
-var PERMISSION_PATTERN = /no_amazon|not connected|expired|suspended|revoked|past_due|trial expired|permission|not authorized|scope/i;
-var VALIDATION_PATTERN = /invalid|validation|must be|required/i;
-function writeEnvelopeFrom(result) {
-  const structured = result.structuredContent;
-  if (!structured) {
-    return void 0;
-  }
-  const hasWriteShape = "mode" in structured || "status" in structured || "requested_count" in structured;
-  if (!hasWriteShape) {
-    return void 0;
-  }
-  return structured;
-}
-function toolClassification(def) {
-  const hint = def.annotations;
-  const annotationWrite = hint?.destructiveHint === true || hint?.readOnlyHint === false;
-  const properties = def.inputSchema.properties;
-  const props = properties && typeof properties === "object" ? properties : {};
-  const schemaWrite = "confirm" in props && "idempotency_key" in props;
-  const isWrite = annotationWrite || schemaWrite;
-  return {
-    isWrite,
-    supportsPreview: isWrite
-  };
-}
-function classifyToolText(text) {
-  if (PERMISSION_PATTERN.test(text)) {
-    return 4 /* PermissionDenied */;
-  }
-  if (VALIDATION_PATTERN.test(text)) {
-    return 5 /* ValidationFailed */;
-  }
-  return void 0;
-}
-function joinContentText(result) {
-  return result.content.map((block) => typeof block.text === "string" ? block.text : "").filter((text) => text.length > 0).join(" ").trim();
-}
-function truncateDetail(text) {
-  if (text.length <= DETAIL_MAX_LENGTH) {
-    return text;
-  }
-  return `${text.slice(0, DETAIL_MAX_LENGTH)}\u2026`;
-}
-function classifyWriteStatus(status) {
-  switch (status) {
-    case "validation_error":
-      return 5 /* ValidationFailed */;
-    case "partial":
-      return 9 /* PartialWrite */;
-    case "blocked":
-    case "failed":
-      return 7 /* ToolExecutionFailed */;
-    case "duplicate_blocked":
-    case "accepted":
-    case "preview":
-    default:
-      return 0 /* Success */;
-  }
-}
-function summarizeWriteEnvelope(env) {
-  const parts = [];
-  if (typeof env.requested_count === "number") {
-    parts.push(`requested=${env.requested_count}`);
-  }
-  if (typeof env.accepted_count === "number") {
-    parts.push(`accepted=${env.accepted_count}`);
-  }
-  if (typeof env.failed_count === "number") {
-    parts.push(`failed=${env.failed_count}`);
-  }
-  if (typeof env.previewed_count === "number") {
-    parts.push(`previewed=${env.previewed_count}`);
-  }
-  const status = env.status ?? "unknown";
-  return parts.length > 0 ? `${status} (${parts.join(", ")})` : status;
-}
-function classifyResponse(response) {
-  if (response.error) {
-    const message = response.error.message;
-    const code = response.error.code === RPC_INVALID_PARAMS ? 5 /* ValidationFailed */ : classifyToolText(message) ?? 7 /* ToolExecutionFailed */;
-    return {
-      code,
-      status: "rpc_error",
-      detail: message
-    };
-  }
-  const result = response.result;
-  const env = writeEnvelopeFrom(result);
-  if (env?.status) {
-    return {
-      code: classifyWriteStatus(env.status),
-      status: env.status,
-      detail: summarizeWriteEnvelope(env),
-      result
-    };
-  }
-  if (result.isError) {
-    const text = joinContentText(result);
-    const code = classifyToolText(text) ?? 7 /* ToolExecutionFailed */;
-    return {
-      code,
-      status: "tool_error",
-      detail: truncateDetail(text),
-      result
-    };
-  }
-  return {
-    code: 0 /* Success */,
-    status: "ok",
-    detail: truncateDetail(joinContentText(result)),
-    result
-  };
-}
-
 // src/commands/tools.ts
 function parseJsonArgs(text, origin) {
   try {
@@ -3422,6 +3446,14 @@ function selectOutputValue(result) {
     return text;
   }
 }
+function warnIfLimitTruncated(ctx, value) {
+  const limit = ctx.flags.limit;
+  if (limit != null && Array.isArray(value) && value.length === limit) {
+    ctx.err(
+      `warning: result returned exactly --limit (${limit}) rows; output may be truncated. Raise --limit or narrow the query.`
+    );
+  }
+}
 function echoWriteSummary(ctx, result) {
   const env = writeEnvelopeFrom(result);
   if (!env) {
@@ -3459,6 +3491,7 @@ async function toolsCall(ctx, name, inputSpec) {
   }
   echoWriteSummary(ctx, result);
   const value = selectOutputValue(result);
+  warnIfLimitTruncated(ctx, value);
   const rendered = formatOutput(value, ctx.flags.format);
   if (ctx.flags.output) {
     await writeFile(ctx.flags.output, rendered, { encoding: "utf8", mode: 384 });
@@ -3516,7 +3549,7 @@ async function handleMessage(line, client, opts) {
   const method = typeof message.method === "string" ? message.method : "";
   if (message.id === void 0) {
     try {
-      await client.rpc(method, message.params);
+      await client.rpc(method, message.params, { notification: true });
     } catch {
     }
     return null;
@@ -3589,9 +3622,9 @@ function pump(ctx, client, opts, input = process.stdin) {
   return new Promise((resolve, reject) => {
     input.setEncoding("utf8");
     let buffer = "";
-    let chain = Promise.resolve();
+    const inflight = /* @__PURE__ */ new Set();
     const dispatch = (line) => {
-      chain = chain.then(async () => {
+      const task = (async () => {
         try {
           const out = await handleMessage(line, client, opts);
           if (out !== null) {
@@ -3600,6 +3633,10 @@ function pump(ctx, client, opts, input = process.stdin) {
         } catch (error) {
           ctx.err(`bridge error: ${error instanceof Error ? error.message : String(error)}`);
         }
+      })();
+      inflight.add(task);
+      void task.finally(() => {
+        inflight.delete(task);
       });
     };
     input.on("data", (data) => {
@@ -3621,10 +3658,10 @@ function pump(ctx, client, opts, input = process.stdin) {
       if (tail.trim() !== "") {
         dispatch(tail);
       }
-      chain.then(() => {
+      Promise.allSettled([...inflight]).then(() => {
         ctx.err("bridge stopped (stdin closed)");
         resolve(0 /* Success */);
-      }).catch(reject);
+      }, reject);
     });
   });
 }
@@ -4030,17 +4067,37 @@ async function profilesUse(ctx, name) {
 }
 
 // src/keychain.ts
-import { Entry } from "@napi-rs/keyring";
+import { createRequire } from "module";
 var SERVICE = "agentcentral-cli";
 var DEFAULT_ACCOUNT = "default";
 var DISABLE_ENV = "AGENT_CENTRAL_DISABLE_KEYCHAIN";
+var entryClassCache = void 0;
+var loaderOverride = void 0;
 function disabled() {
   return process.env[DISABLE_ENV] === "1";
 }
+var requireNative = createRequire(import.meta.url);
+function loadEntryClass() {
+  if (entryClassCache !== void 0) {
+    return entryClassCache;
+  }
+  try {
+    const loaded = loaderOverride ? loaderOverride() : requireNative("@napi-rs/keyring").Entry;
+    entryClassCache = loaded;
+    return loaded;
+  } catch {
+    entryClassCache = null;
+    return null;
+  }
+}
 function keychainAvailable() {
   if (disabled()) {
     return false;
   }
+  const Entry = loadEntryClass();
+  if (!Entry) {
+    return false;
+  }
   try {
     const entry = new Entry(SERVICE, DEFAULT_ACCOUNT);
     try {
@@ -4056,6 +4113,10 @@ function keychainGet(account) {
   if (disabled()) {
     return null;
   }
+  const Entry = loadEntryClass();
+  if (!Entry) {
+    return null;
+  }
   try {
     const entry = new Entry(SERVICE, account ?? DEFAULT_ACCOUNT);
     const secret = entry.getPassword();
@@ -4069,6 +4130,10 @@ function keychainSet(account, secret) {
   if (disabled()) {
     return false;
   }
+  const Entry = loadEntryClass();
+  if (!Entry) {
+    return false;
+  }
   try {
     const entry = new Entry(SERVICE, account ?? DEFAULT_ACCOUNT);
     entry.setPassword(secret);
@@ -4081,6 +4146,10 @@ function keychainDelete(account) {
   if (disabled()) {
     return false;
   }
+  const Entry = loadEntryClass();
+  if (!Entry) {
+    return false;
+  }
   try {
     const entry = new Entry(SERVICE, account ?? DEFAULT_ACCOUNT);
     return entry.deletePassword();
@@ -4169,7 +4238,6 @@ function extraFlags(ctx) {
   const flags = ctx.flags;
   return {
     since: flags.since,
-    groupBy: flags.groupBy,
     asin: flags.asin,
     fulfillmentChannel: flags.fulfillmentChannel
   };
@@ -4204,6 +4272,14 @@ function selectOutputValue2(result) {
     return text;
   }
 }
+function warnIfLimitTruncated2(ctx, value) {
+  const limit = ctx.flags.limit;
+  if (limit != null && Array.isArray(value) && value.length === limit) {
+    ctx.err(
+      `warning: result returned exactly --limit (${limit}) rows; output may be truncated. Raise --limit or narrow the query.`
+    );
+  }
+}
 async function emit(ctx, name, args) {
   const client = await ctx.getClient();
   const response = await client.rpc(
@@ -4220,6 +4296,7 @@ async function emit(ctx, name, args) {
     return classified.code;
   }
   const value = selectOutputValue2(result);
+  warnIfLimitTruncated2(ctx, value);
   const rendered = formatOutput(value, ctx.flags.format);
   if (ctx.flags.output) {
     await writeFile2(ctx.flags.output, rendered, { encoding: "utf8", mode: 384 });
@@ -4499,9 +4576,9 @@ async function run(argv) {
   withGlobalOptions(cli.command("inventory health", "summarize inventory health")).action(
     (options) => dispatch((ctx) => inventoryHealth(ctx), options)
   );
-  withGlobalOptions(cli.command("ads performance", "summarize campaign performance")).option("--since <dur>", "lookback window: a relative duration like 30d or a YYYY-MM-DD date").option("--group-by <field>", "advisory grain hint (documented; not wired server-side)").action(
+  withGlobalOptions(cli.command("ads performance", "summarize campaign performance")).option("--since <dur>", "lookback window: a relative duration like 30d or a YYYY-MM-DD date").action(
     (options) => dispatch((ctx) => adsPerformance(ctx), options, {
-      extra: { since: asString(options.since), groupBy: asString(options.groupBy) }
+      extra: { since: asString(options.since) }
     })
   );
   withGlobalOptions(cli.command("catalog quality", "summarize listing quality")).option("--asin <asin>", "scope to a single ASIN").action(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcentral/cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "license": "MIT",
   "description": "agentcentral CLI — local MCP bridge and generic tool runner for Amazon seller data",
   "keywords": [