@agentcentral/cli 0.1.4 → 0.1.5

package/README.md

@@ -76,6 +76,28 @@ agentcentral tools call update_keyword_bids @bids.json \
   --yes --idempotency-key "$(uuidgen)"
 ```
 
+#### Auto-pagination (`--all` / `--paginate`)
+
+Some live-API read tools return their results across multiple pages. Pass `--all` (alias `--paginate`)
+to `tools call` and the CLI follows the server's continuation block, fetching every page and emitting
+the concatenated rows:
+
+```bash
+agentcentral tools call get_sponsored_ads_entities_live '{"ad_product":"SP"}' --all
+agentcentral tools call get_audience_segments '{}' --all --format ndjson
+```
+
+Notes:
+
+- `--all` is reads only. Combining it with a write tool or with `--yes` is a usage error (exit 2).
+- For `json`, `csv`, `table`, and `markdown`, the rows from every page are accumulated and rendered
+  once. For `ndjson`, each page's rows stream to stdout as they arrive (incremental); with `--output`,
+  ndjson buffers and writes the file once instead.
+- Auto-pagination stops at a 100-page cap and warns on stderr if the cap is hit, so narrow the query
+  to fetch the rest.
+- A tool whose response carries no pagination block is a single call plus a one-line stderr note, not
+  an error. This is also how `--all` degrades gracefully against an older server.
+
 ### Convenience read commands
 
 Thin wrappers over the same hosted read tools. Each maps friendly flags onto the exact parameters its
@@ -122,9 +144,13 @@ Every command accepts: `--format/-f json|ndjson|table|csv|markdown`, `--output/-
 `--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.
+`tools call` also accepts `--all` / `--paginate` (auto-pagination, reads only; see above).
+
+Truncation is reported authoritatively from the server, not guessed. When the result envelope says it
+hit the row limit (`more_rows_possible` / `limit_reached`), the CLI warns on stderr with the row count
+(and the exact `returned N of M matching rows` phrasing when the tool supplies a total). When more
+pages are available, it instead notes that you can pass `--all` to fetch them. These messages go to
+stderr only (honoring `--quiet`) and never touch stdout.
 
 ## Exit codes
 

package/dist/index.js

@@ -34,6 +34,7 @@ var DEFAULT_RETRY = {
   honorRetryAfter: true
 };
 var API_KEY_PREFIX = "ac_live_";
+var MAX_AUTO_PAGES = 100;
 
 // src/config.ts
 import {
@@ -3290,6 +3291,83 @@ function formatOutput(value, format) {
   }
 }
 
+// src/pagination.ts
+function readNumber(source, key) {
+  const value = source[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function readBoolean(source, key) {
+  const value = source[key];
+  return typeof value === "boolean" ? value : void 0;
+}
+function readPagination(structured) {
+  const raw = structured.pagination;
+  if (!raw || typeof raw !== "object") {
+    return void 0;
+  }
+  const block = raw;
+  const mode = block.mode;
+  const continueParam = block.continue_param;
+  if (mode !== "token" && mode !== "offset" || typeof continueParam !== "string") {
+    return void 0;
+  }
+  const nextToken = typeof block.next_token === "string" || block.next_token === null ? block.next_token : void 0;
+  const nextOffset = readNumber(block, "next_offset");
+  const derivedHasMore = mode === "token" ? nextToken != null : nextOffset != null;
+  const hasMore = readBoolean(block, "has_more") ?? derivedHasMore;
+  return {
+    mode,
+    ...nextToken !== void 0 ? { next_token: nextToken } : {},
+    ...nextOffset !== void 0 ? { next_offset: nextOffset } : {},
+    continue_param: continueParam,
+    has_more: hasMore
+  };
+}
+function readResultMeta(result) {
+  const structured = result.structuredContent;
+  if (!structured || typeof structured !== "object") {
+    return {};
+  }
+  return {
+    rowCount: readNumber(structured, "row_count"),
+    requestedLimit: readNumber(structured, "requested_limit"),
+    limitReached: readBoolean(structured, "limit_reached"),
+    moreRowsPossible: readBoolean(structured, "more_rows_possible"),
+    totalMatching: readNumber(structured, "total_matching"),
+    pagination: readPagination(structured)
+  };
+}
+function warnFromResultMeta(ctx, meta, allRequested) {
+  if (meta.pagination?.has_more && !allRequested) {
+    ctx.err("note: more pages available; pass --all to fetch them.");
+    return;
+  }
+  if (meta.moreRowsPossible || meta.limitReached) {
+    const rows = meta.rowCount;
+    if (typeof meta.totalMatching === "number" && typeof rows === "number") {
+      ctx.err(
+        `warning: returned ${rows} of ${meta.totalMatching} matching rows at the limit. Raise --limit or narrow the query (deep paging is not available for this tool).`
+      );
+      return;
+    }
+    const count = typeof rows === "number" ? `${rows} rows` : "rows";
+    ctx.err(
+      `warning: returned ${count} at the limit. Raise --limit or narrow the query (deep paging is not available for this tool).`
+    );
+  }
+}
+function readRows(result) {
+  const structured = result.structuredContent;
+  if (!structured || typeof structured !== "object") {
+    return [];
+  }
+  const rows = structured.rows;
+  return Array.isArray(rows) ? rows : [];
+}
+function nextContinueValue(pagination) {
+  return pagination.mode === "token" ? pagination.next_token : pagination.next_offset;
+}
+
 // src/commands/tools.ts
 function parseJsonArgs(text, origin) {
   try {
@@ -3449,14 +3527,6 @@ 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) {
@@ -3473,11 +3543,28 @@ function echoWriteSummary(ctx, result) {
     ctx.err("note: a prior submission with this idempotency key stands; no new write was made.");
   }
 }
+async function emitRendered(ctx, rendered) {
+  if (ctx.flags.output) {
+    await writeFile(ctx.flags.output, rendered, { encoding: "utf8", mode: 384 });
+    ctx.err(`wrote result to ${ctx.flags.output}`);
+  } else {
+    ctx.out(rendered);
+  }
+}
 async function toolsCall(ctx, name, inputSpec) {
+  if (ctx.flags.all && ctx.flags.yes) {
+    throw new CliError(
+      2 /* UsageError */,
+      "--all is for reads only; it cannot be combined with --yes."
+    );
+  }
   const input = await resolveInput(inputSpec, readStdinOnce);
   const client = await ctx.getClient();
   const tools = await client.listTools({ timeoutMs: ctx.flags.timeoutMs });
   const def = requireTool(tools, name);
+  if (ctx.flags.all) {
+    return toolsCallAll(ctx, client, def, name, input);
+  }
   const args = buildCallArgs(ctx, def, input);
   const response = await client.rpc(
     "tools/call",
@@ -3493,17 +3580,89 @@ async function toolsCall(ctx, name, inputSpec) {
     return classified.code;
   }
   echoWriteSummary(ctx, result);
+  const meta = readResultMeta(result);
+  warnFromResultMeta(ctx, meta, false);
   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 });
-    ctx.err(`wrote result to ${ctx.flags.output}`);
-  } else {
-    ctx.out(rendered);
-  }
+  await emitRendered(ctx, rendered);
   return classified.code;
 }
+async function toolsCallAll(ctx, client, def, name, input) {
+  if (toolClassification(def).isWrite || ctx.flags.yes) {
+    throw new CliError(
+      2 /* UsageError */,
+      "--all is for reads only; it cannot be combined with a write tool or --yes."
+    );
+  }
+  const streamNdjson = ctx.flags.format === "ndjson" && !ctx.flags.output;
+  const accumulated = [];
+  let args = buildCallArgs(ctx, def, input);
+  let pages = 0;
+  let exitCode = 0 /* Success */;
+  const collect = (rows) => {
+    if (streamNdjson) {
+      if (rows.length > 0) {
+        ctx.out(formatOutput(rows, "ndjson"));
+      }
+    } else {
+      accumulated.push(...rows);
+    }
+  };
+  for (; ; ) {
+    if (pages >= MAX_AUTO_PAGES) {
+      ctx.err(
+        `warning: pagination stopped at the ${MAX_AUTO_PAGES}-page cap; more pages may remain. Narrow the query to fetch the rest.`
+      );
+      break;
+    }
+    const response = await client.rpc(
+      "tools/call",
+      { name, arguments: args },
+      { timeoutMs: ctx.flags.timeoutMs }
+    );
+    pages += 1;
+    const classified = classifyResponse(response);
+    const result = classified.result;
+    if (!result) {
+      if (classified.detail) {
+        ctx.err(classified.detail);
+      }
+      exitCode = classified.code;
+      break;
+    }
+    if (classified.code !== 0 /* Success */) {
+      if (classified.detail) {
+        ctx.err(classified.detail);
+      }
+      collect(readRows(result));
+      ctx.err(`warning: pagination stopped after ${pages} page(s) on a page error.`);
+      exitCode = classified.code;
+      break;
+    }
+    collect(readRows(result));
+    const meta = readResultMeta(result);
+    if (!meta.pagination) {
+      if (pages === 1) {
+        ctx.err("note: this tool returned no pagination block; fetched a single page.");
+      }
+      warnFromResultMeta(ctx, meta, true);
+      break;
+    }
+    if (!meta.pagination.has_more) {
+      break;
+    }
+    const next = nextContinueValue(meta.pagination);
+    if (next == null) {
+      break;
+    }
+    args = { ...args, [meta.pagination.continue_param]: next };
+  }
+  if (!streamNdjson) {
+    const rendered = formatOutput(accumulated, ctx.flags.format);
+    await emitRendered(ctx, rendered);
+  }
+  return exitCode;
+}
 async function readStdinOnce() {
   const chunks = [];
   for await (const chunk of process.stdin) {
@@ -4275,14 +4434,6 @@ 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(
@@ -4298,8 +4449,9 @@ async function emit(ctx, name, args) {
     }
     return classified.code;
   }
+  const meta = readResultMeta(result);
+  warnFromResultMeta(ctx, meta, ctx.flags.all === true);
   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 });
@@ -4442,7 +4594,9 @@ function parseGlobalFlags(options) {
     verbose: options.verbose === true,
     requestId: asString(options.requestId),
     yes: options.yes === true,
-    idempotencyKey: asString(options.idempotencyKey)
+    idempotencyKey: asString(options.idempotencyKey),
+    // --all and its --paginate alias both land here.
+    all: options.all === true || options.paginate === true
   };
 }
 async function readKeyFromStdin() {
@@ -4537,7 +4691,7 @@ async function run(argv) {
   withGlobalOptions(cli.command("tools schema <tool>", "print a tool's JSON Schema")).action(
     (tool, options) => dispatch((ctx) => toolsSchema(ctx, tool), options)
   );
-  withGlobalOptions(cli.command("tools call <tool> [input]", "invoke a tool")).option("-i, --input <spec>", "tool input as JSON, @file, a file path, or - for stdin").action(
+  withGlobalOptions(cli.command("tools call <tool> [input]", "invoke a tool")).option("-i, --input <spec>", "tool input as JSON, @file, a file path, or - for stdin").option("--all, --paginate", "follow the server's pagination block and fetch every page (reads only)").action(
     (tool, input, options) => dispatch((ctx) => toolsCall(ctx, tool, asString(options.input) ?? input), options)
   );
   withGlobalOptions(cli.command("mcp serve", "run the transparent stdio MCP bridge")).option("--domain <domain>", "advisory domain scope (repeatable / comma-separated)").option("--read-only", "advisory: hide write tools from tools/list").action(

package/package.json

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