metergraph-cli 0.2.1 → 0.2.3

package/src/setup.js

@@ -1,4 +1,7 @@
-import { detectRemoteSession, openBrowser } from "./auth-browser.js";
+import { randomUUID } from "node:crypto";
+
+import { openBrowser } from "./auth-browser.js";
+import { classifyEnvironment, remoteSetupAction } from "./environment.js";
 import { readBinding, resolveProject } from "./auth-binding.js";
 import { startCallbackListener } from "./auth-callback.js";
 import { openUrl, runLogin } from "./auth-login.js";
@@ -9,6 +12,9 @@ import { AUTH_HTTP_TIMEOUT_MS } from "./constants.js";
 import { preflightEnv, currentEnvValues, commitEnv, isAppToken } from "./setup-env.js";
 import { newSetupState, readSetupState, setupReceipt, withSetupState, writeSetupState } from "./setup-state.js";
 import { runSkill } from "./skill.js";
+import { handoffPages } from "./environment.js";
+import { REFUSAL_REASONS, clearSetupRefusal, pendingRefusal, waiterRecord } from "./setup-refusal.js";
+import { isApprovalWaiter } from "./approval-handoff.js";
 import { ensureRepositoryIdentity, envRepository } from "./repository-identity.js";
 import { parseJsonObject } from "./http.js";
 import { deadline, failureOf, send, trapSignals } from "./transport.js";
@@ -37,8 +43,20 @@ const fail = (outcome, reason, status = "not_ready", receipt = null, next = null
 // keeps waiting; stdout has room for one line, so a second approval in the
 // same run is not started. The person approves, the run saves what it
 // finished, and the agent reruns setup, which resumes from the saved state.
+//
+// A first setup that has to sign in asks the sign-in consent to approve the
+// first ingest key as well, when the service advertises it, so the person
+// approves once. The sign-in grant and the ingest key stay separate
+// credentials: the receipt is redeemed here with its own PKCE verifier,
+// exactly as one from the ingest-only approval is. A service without that
+// support, a repair, a replacement or a project already signed in keeps the
+// separate ingest-only approval.
 export async function runSetup(options, progress = () => {}) {
-  if (options.runtime !== "local" || detectRemoteSession() !== null) return fail("unsupported", "run_on_local_machine");
+  const environment = options.environment ?? classifyEnvironment();
+  if (options.runtime !== "local" || environment.remote) {
+    const where = options.runtime !== "local" ? { kind: "declared_cloud" } : environment;
+    return fail("unsupported", "run_on_local_machine", "not_ready", null, remoteSetupAction(where, options.origin, options));
+  }
   const trap = trapSignals();
   let receipt = null;
   let loginVerified = false;
@@ -54,8 +72,14 @@ export async function runSetup(options, progress = () => {}) {
     }
     return current;
   };
-  const stop = (outcome, reason, status = "not_ready") => fail(outcome, reason, status, currentReceipt());
+  const stop = (outcome, reason, status = "not_ready", next = null) =>
+    fail(outcome, reason, status, currentReceipt(), next);
   let announced = false;
+  // Only the --json --no-browser background waiter records what it does with
+  // an approval; a foreground run reports directly.
+  const waiter = Boolean(options.announce) && isApprovalWaiter();
+  let record = null;
+  let refusalRecorded = false;
   const announce = options.announce ? (status, next) => {
     announced = true;
     options.announce(fail("action_required", "browser_approval_required", status, currentReceipt(), next).data);
@@ -73,6 +97,18 @@ export async function runSetup(options, progress = () => {}) {
         (bound !== null && (bound.origin !== saved.value.origin || bound.workspace_id !== saved.value.workspace_id)))) {
       return stop("conflict", "setup_binding_changed");
     }
+    // What an earlier --json --no-browser waiter is doing with an approval it
+    // received: still redeeming it, or refused by the service's budget. The
+    // rerun reports that instead of asking the person for another approval.
+    // It runs after the binding guard, so a rerun aimed at another deployment
+    // or workspace is refused as such and leaves the record for a correct
+    // rerun; the next action names the saved family's own deployment.
+    const pending = pendingRefusal(root, { familyId: saved?.value.family_id ?? null,
+      delivered: saved?.value.phase === "delivered" });
+    if (pending !== null) {
+      return stop(pending.reason === "setup_rate_limited" ? "rate_limited" : "conflict", pending.reason,
+        "delivery_pending", redeemNext(pending, saved?.value.origin ?? intendedOrigin));
+    }
     // An env key this setup does not own stops before any sign in, so the
     // refusal costs no approval and leaves the binding untouched. The check
     // after sign in stays, against a fresh read.
@@ -85,11 +121,27 @@ export async function runSetup(options, progress = () => {}) {
     if (bindingDiffers && !options.reconnect) return stop("conflict", "bound_to_other_workspace");
     let signedIn = bindingDiffers || options.reconnect ? { ok: false, outcome: "login_required" } :
       await verifiedSession({ project: root, configDir: options.configDir, cancel: trap.signal });
+    // An approved, unredeemed receipt for a new family, from a combined sign in.
+    let combined = null;
     if (!signedIn.ok && signedIn.outcome === "login_required") {
+      const familyId = randomUUID();
+      const ingestSetup = saved || options.repair ? null : { familyId,
+        // In the waiter, record the approval before anything else happens,
+        // so an immediate rerun waits instead of asking for another one.
+        onApproved: () => { if (waiter) record = waiterRecord(root, familyId); record?.redeeming(); },
+        supported: async (origin, profile, cancel) => {
+          const discovered = await discoverSetup(origin, profile, cancel);
+          return discovered.ok && discovered.loginSetup;
+        } };
       const login = await runLogin({ ...options, origin: intendedOrigin, workspace: intendedWorkspace,
-        project: root, reconnect: options.reconnect, expectedProfile: options.expectedProfile ?? null,
+        project: root, reconnect: options.reconnect, expectedProfile: options.expectedProfile ?? null, ingestSetup,
         announce: announce && ((data) => announce("login_pending", data.next_action)) }, progress);
-      if (login.outcome !== "ok") return stop(login.outcome, login.reason, "login_pending");
+      // Login's own next action (for example no_browser with a Metadata key
+      // alternative in a local container) is passed through.
+      if (login.outcome !== "ok") return stop(login.outcome, login.reason, "login_pending", login.data?.next_action ?? null);
+      if (login.ingestSetup && login.ingestSetup.familyId === familyId && RECEIPT.test(login.ingestSetup.code)) {
+        combined = login.ingestSetup;
+      }
       signedIn = await verifiedSession({ project: root, configDir: options.configDir, cancel: trap.signal });
     }
     if (!signedIn.ok) return stop(signedIn.outcome, signedIn.reason, "login_pending");
@@ -159,15 +211,21 @@ export async function runSetup(options, progress = () => {}) {
       return stop("conflict", "repair_requires_saved_key");
     }
 
+    // A combined sign in already approved a key for a new family. Anything
+    // that makes this anything but a first create drops the receipt unused;
+    // it expires without issuing a key.
+    if (previous !== null || options.repair) combined = null;
     // A verified rerun returned above without approval. From here a person
-    // must open an approval URL. A run that already announced its sign in URL
-    // has used its one JSON line, so it stops here and the rerun continues.
-    if (announced) return stop("action_required", "browser_approval_required", "approval_pending");
+    // must open an approval URL, unless the sign in approved the key too. A
+    // run that already announced its sign in URL has used its one JSON line,
+    // so it stops here and the rerun continues.
+    if (announced && combined === null) return stop("action_required", "browser_approval_required", "approval_pending");
     const setup = await discoverSetup(origin, profile, trap.signal);
     if (!setup.ok) return stop(setup.outcome, setup.reason);
 
     if (previous === null) {
-      writeSetupState(root, newSetupState(origin, workspaceId, profile, options.client), null);
+      writeSetupState(root, combined === null ? newSetupState(origin, workspaceId, profile, options.client)
+        : newSetupState(origin, workspaceId, profile, options.client, combined.familyId), null);
       previous = readSetupState(root);
       receipt = setupReceipt(previous.value);
     }
@@ -177,40 +235,19 @@ export async function runSetup(options, progress = () => {}) {
     // An acknowledged family is never implicitly replaced. Repair requires
     // the explicit flag and the key ID saved from its original issuance.
     if (intent === "replace_pending" && state.phase === "delivered") return stop("conflict", "repair_required");
-    const listener = await startCallbackListener();
-    let callback;
-    let clientId;
-    let pkce;
-    try {
-      const client = await clientFor(endpointsFor(origin), setup.offeredClientId, listener.redirectUri,
-        deadline(AUTH_HTTP_TIMEOUT_MS, trap.signal).signal);
-      if (!client.ok) return stop(client.outcome, client.reason);
-      clientId = client.clientId;
-      pkce = newPkce();
-      const pending = listener.wait({ state: pkce.state, issuer: `${origin}/v1/oauth`, requireIss: false,
-        timeoutMs: options.timeoutMs, cancel: trap.signal });
-      const url = new URL(`${origin}${SETUP_PATHS.authorize}`);
-      const params = {
-        client_id: clientId, redirect_uri: listener.redirectUri, state: pkce.state,
-        code_challenge: pkce.challenge, code_challenge_method: "S256",
-        workspace_id: workspaceId, family_id: state.family_id, intent,
-      };
-      if (intent === "repair") params.expected_key_id = state.key_id;
-      url.search = new URLSearchParams(params).toString();
-      if (trap.signal.aborted) return stop("authorization_failed", "cancelled");
-      if (options.noBrowser && announce) {
-        announce("approval_pending", openUrl(url.href, Math.round(options.timeoutMs / 1000), "approve ingest-only setup"));
-      } else if (options.noBrowser) progress(`Open this URL on this machine to approve ingest-only setup:\n${url.href}`);
-      else if (!(await openBrowser(url.href))) return stop("authorization_failed", "browser_unavailable");
-      else progress("Opened your browser for ingest-only setup approval.");
-      callback = await pending;
-    } finally {
-      await listener.close();
+    let approval;
+    if (combined !== null && intent === "create" && state.family_id === combined.familyId) {
+      approval = combined;
+      progress("Your sign-in approval also approved this project's ingest key.");
+    } else {
+      approval = await approveInBrowser({ origin, setup, workspaceId, state, intent, options, announce, progress,
+        cancel: trap.signal });
+      if (!approval.ok) return stop(approval.outcome, approval.reason);
+      if (waiter) {
+        record = waiterRecord(root, state.family_id);
+        record.redeeming();
+      }
     }
-    if (callback.kind === "denied") return stop("authorization_failed", "access_denied");
-    if (callback.kind === "timeout") return stop("authorization_failed", "timeout");
-    if (callback.kind === "cancelled") return stop("authorization_failed", "cancelled");
-    if (callback.kind !== "code" || !RECEIPT.test(callback.code)) return stop("authorization_failed", "callback_invalid");
 
     // Persist the ambiguity boundary before a single-use receipt is sent.
     // If the response is lost, a later run asks the browser to replace only
@@ -220,11 +257,22 @@ export async function runSetup(options, progress = () => {}) {
       return stop("conflict", "setup_state_changed");
     }
     writeSetupState(root, withSetupState(previous.value, { phase: "redeem_attempted" }), previous);
+    // This waiter won the state for its redemption: the record is now its own,
+    // even if another waiter's approval arrived first and wrote it.
+    if (waiter) {
+      record ??= waiterRecord(root, state.family_id);
+      record.redeeming({ force: true });
+    }
     previous = readSetupState(root);
-    const redeemed = await redeem(origin, { code: callback.code, client_id: clientId,
-      redirect_uri: listener.redirectUri, code_verifier: pkce.verifier,
-      family_id: state.family_id, workspace_id: workspaceId }, profile, trap.signal);
-    if (!redeemed.ok) return stop(redeemed.outcome, redeemed.reason, "delivery_pending");
+    const redeemed = await redeem(origin, { code: approval.code, client_id: approval.clientId,
+      redirect_uri: approval.redirectUri, code_verifier: approval.verifier,
+      family_id: state.family_id, workspace_id: workspaceId }, profile, trap.signal, progress);
+    if (!redeemed.ok) {
+      if (record !== null && REFUSAL_REASONS.includes(redeemed.reason)) {
+        refusalRecorded = record.refused(redeemed.reason, redeemed.retryAfter ?? null);
+      }
+      return stop(redeemed.outcome, redeemed.reason, "delivery_pending", redeemNext(redeemed, origin));
+    }
     const written = await commitEnv(plan, { token: redeemed.token, ingestUrl: origin, signal: trap.signal });
     const checked = await checkCredential(origin, redeemed.token, state, profile, trap.signal);
     if (!checked.ok || checked.keyId !== redeemed.keyId) return stop("verification_failed", "issued_key_unverified", "delivery_pending");
@@ -236,10 +284,59 @@ export async function runSetup(options, progress = () => {}) {
   } catch (error) {
     if (error instanceof Stop) return stop(error.outcome, error.reason);
     throw error;
-  } finally { trap.release(); }
+  } finally {
+    if (record !== null && !refusalRecorded) record.settle();
+    trap.release();
+  }
+}
+
+// The ingest-only approval at the setup authorization endpoint: the only
+// browser step for a repair or replacement, and the second one for a service
+// without the combined sign-in approval. Returns the receipt with the client,
+// redirect and verifier it must be redeemed with, or a stop reason.
+async function approveInBrowser({ origin, setup, workspaceId, state, intent, options, announce, progress, cancel }) {
+  const failed = (reason, outcome = "authorization_failed") => ({ ok: false, outcome, reason });
+  const listener = await startCallbackListener();
+  let callback;
+  let clientId;
+  let pkce;
+  try {
+    const client = await clientFor(endpointsFor(origin), setup.offeredClientId, listener.redirectUri,
+      deadline(AUTH_HTTP_TIMEOUT_MS, cancel).signal);
+    if (!client.ok) return failed(client.reason, client.outcome);
+    clientId = client.clientId;
+    pkce = newPkce();
+    const pending = listener.wait({ state: pkce.state, issuer: `${origin}/v1/oauth`, requireIss: false,
+      timeoutMs: options.timeoutMs, cancel });
+    const url = new URL(`${origin}${SETUP_PATHS.authorize}`);
+    const params = {
+      client_id: clientId, redirect_uri: listener.redirectUri, state: pkce.state,
+      code_challenge: pkce.challenge, code_challenge_method: "S256",
+      workspace_id: workspaceId, family_id: state.family_id, intent,
+    };
+    if (intent === "repair") params.expected_key_id = state.key_id;
+    url.search = new URLSearchParams(params).toString();
+    if (cancel.aborted) return failed("cancelled");
+    if (options.noBrowser && announce) {
+      announce("approval_pending", openUrl(url.href, Math.round(options.timeoutMs / 1000), "approve ingest-only setup"));
+    } else if (options.noBrowser) progress(`Open this URL on this machine to approve ingest-only setup:\n${url.href}`);
+    else if (!(await openBrowser(url.href))) return failed("browser_unavailable");
+    else progress("Opened your browser for ingest-only setup approval.");
+    callback = await pending;
+  } finally {
+    await listener.close();
+  }
+  if (callback.kind === "denied") return failed("access_denied");
+  if (callback.kind === "timeout") return failed("timeout");
+  if (callback.kind === "cancelled") return failed("cancelled");
+  if (callback.kind !== "code" || !RECEIPT.test(callback.code)) return failed("callback_invalid");
+  return { ok: true, code: callback.code, clientId, redirectUri: listener.redirectUri, verifier: pkce.verifier };
 }
 
 function finishSkill(root, options, envStatus) {
+  // Reached only with a verified, delivered credential, whether just issued
+  // or reused: no earlier refusal or redemption still applies.
+  clearSetupRefusal(root);
   let previous = readSetupState(root);
   if (previous === null || previous.value.phase !== "delivered") return fail("conflict", "setup_state_changed");
   if (previous.value.selected_client !== options.client) {
@@ -313,14 +410,91 @@ async function discoverSetup(origin, profile, cancel) {
   }
   const offered = offeredClientId(doc);
   if (offered === undefined) return { ok: false, outcome: "unsupported", reason: "setup_contract_mismatch" };
-  return { ok: true, offeredClientId: offered };
+  // Optional: a service that names it lets the sign-in consent approve the
+  // first ingest key too. Anything but true means the separate approval.
+  return { ok: true, offeredClientId: offered, loginSetup: doc.login_ingest_setup_supported === true };
 }
 
-async function redeem(origin, form, profile, cancel) {
-  const response = await send(origin, SETUP_PATHS.redeem, { method: "POST", form,
-    signal: deadline(AUTH_HTTP_TIMEOUT_MS, cancel).signal, maxBytes: 32768 });
-  const failed = failureOf(response);
-  if (failed) return { ok: false, ...failed };
+// The service budgets how many ingest keys setup may issue per person and per
+// workspace each minute. A refusal leaves the receipt unredeemed, and only
+// this process holds its PKCE verifier, so setup waits out a short
+// Retry-After and redeems the same receipt rather than asking for another
+// approval. It gives up after REDEEM_RETRIES waits.
+const REDEEM_RETRIES = 2;
+const MAX_RETRY_AFTER_SECONDS = 60;
+
+async function redeem(origin, form, profile, cancel, progress = () => {}) {
+  for (let attempt = 0; ; attempt += 1) {
+    const response = await send(origin, SETUP_PATHS.redeem, { method: "POST", form,
+      signal: deadline(AUTH_HTTP_TIMEOUT_MS, cancel).signal, maxBytes: 32768 });
+    const failed = failureOf(response);
+    if (failed) return { ok: false, ...failed };
+    if (response.status === 429) {
+      const wait = retryAfterSeconds(response);
+      if (wait === null || attempt >= REDEEM_RETRIES) {
+        return { ok: false, outcome: "rate_limited", reason: "setup_rate_limited", retryAfter: wait };
+      }
+      progress(`The service is pacing new ingest keys. Retrying in ${wait} seconds.`);
+      if (!(await pause(wait * 1000, cancel))) return { ok: false, outcome: "authorization_failed", reason: "cancelled" };
+      continue;
+    }
+    if (response.status === 409 && parseJsonObject(response)?.error === "setup_key_limit") {
+      return { ok: false, outcome: "conflict", reason: "setup_key_limit" };
+    }
+    return redeemResult(response, origin, form, profile);
+  }
+}
+
+// Seconds from Retry-After (or the body's retry_after_seconds), 1 to 60, or
+// null when the service gave no usable delay. The header must be whole
+// digits: "60junk" or "1.5" is unusable, as on the read path.
+const RETRY_AFTER = /^[0-9]{1,6}$/;
+
+function retryAfterSeconds(response) {
+  const raw = response.headers?.["retry-after"];
+  const header = typeof raw === "string" && RETRY_AFTER.test(raw.trim()) ? Number(raw.trim()) : null;
+  if (raw !== undefined && header === null) return null;
+  const body = parseJsonObject(response)?.retry_after_seconds;
+  const value = header !== null ? header : Number.isInteger(body) ? body : null;
+  return value !== null && value >= 1 && value <= MAX_RETRY_AFTER_SECONDS ? value : null;
+}
+
+function pause(ms, cancel) {
+  return new Promise((resolve) => {
+    if (cancel.aborted) return resolve(false);
+    const done = (value) => {
+      clearTimeout(timer);
+      cancel.removeEventListener("abort", onAbort);
+      resolve(value);
+    };
+    const onAbort = () => done(false);
+    const timer = setTimeout(() => done(true), ms);
+    cancel.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// The next action for a budget refusal. Nothing was issued, and a rerun asks
+// for a new approval.
+function redeemNext(result, origin) {
+  if (result.reason === "setup_in_progress") {
+    return { kind: "retry_later", retry_after_seconds: result.retryAfter ?? null,
+      message: "An earlier setup run for this project is still finishing an approval it received. Wait a " +
+        "few seconds, then run setup again; do not ask for another approval." };
+  }
+  if (result.reason === "setup_rate_limited") {
+    return { kind: "retry_later", retry_after_seconds: result.retryAfter ?? null,
+      message: "The service limits how many ingest keys setup can issue each minute for one person and one " +
+        "workspace. Nothing was issued. Wait a minute, then run setup again; it asks for a new approval." };
+  }
+  if (result.reason === "setup_key_limit") {
+    return { kind: "revoke_keys", url: handoffPages(origin).keys_url,
+      message: "This workspace has reached its limit of active CLI setup keys. Nothing was issued. Revoke " +
+        "unused CLI setup keys on the Keys page, then run setup again." };
+  }
+  return null;
+}
+
+function redeemResult(response, origin, form, profile) {
   if (response.status !== 200) return { ok: false, outcome: "authorization_failed", reason: "setup_redeem_rejected" };
   const body = parseJsonObject(response);
   if (body?.schema_version !== SCHEMA || body.token_type !== "ingest" || body.scope !== "ingest" ||

package/src/skill-bundle.js

@@ -5,7 +5,7 @@ import { readFileSync } from "node:fs";
 // public skill at the manifest's source_url. The source has no version of its
 // own, so the revision is derived from the content hash. The hash is pinned
 // here as well as in the manifest, so editing either file alone is detected.
-const PINNED_SHA256 = "d527a67efc42a55245b9c2c8fd2687c1f31f553e154a6242d0f31466993e314e";
+const PINNED_SHA256 = "ebf784673eff0280d85974504f93c683a1dabfb54156c9d27e091131462e9d5f";
 
 const ASSET_DIR = new URL("../assets/skill/", import.meta.url);
 const MANIFEST_KEYS = ["file", "manifest_version", "name", "revision", "sha256", "size", "source_url"];
@@ -55,7 +55,7 @@ export function loadBundledSkill() {
 // The workflow skills that "skills install" writes, vendored from the public
 // skills repository at one commit. The manifest's own hash is pinned here, and
 // the manifest pins each skill's hash, so changing any file alone is detected.
-const PINNED_PACK_SHA256 = "c47c8920b633ddd9b52d0855f91361e4e193746a89d6a58f43902af6a38e9617";
+const PINNED_PACK_SHA256 = "11ab983875911c4c2ad03d2a3b7b9e9213c410e77f4ff2d27b4059354b00fe0c";
 
 const PACK_DIR = new URL("../assets/skills/", import.meta.url);
 const PACK_KEYS = ["commit", "manifest_version", "repository", "skills"];

package/src/style.js

@@ -0,0 +1,101 @@
+import { EXIT_CODES } from "./constants.js";
+
+// Presentation for human (non --json) output: a status headline, aligned
+// fields and next steps. Color is used only when the stream is a terminal
+// and NO_COLOR is unset (https://no-color.org); FORCE_COLOR turns it on.
+// Symbols are plain Unicode and are printed with or without color.
+
+const CODES = { bold: [1, 22], dim: [2, 22], red: [31, 39], green: [32, 39], yellow: [33, 39], cyan: [36, 39] };
+
+function makeStyle(color, width = Infinity) {
+  const style = { color, width };
+  for (const [name, [open, close]] of Object.entries(CODES)) {
+    style[name] = color ? (text) => `\u001b[${open}m${text}\u001b[${close}m` : (text) => String(text);
+  }
+  return style;
+}
+
+export const PLAIN = makeStyle(false);
+
+// Prose wraps to the terminal width only on a terminal, so piped output keeps
+// one line per message.
+export function createStyle(stream, env = process.env) {
+  const tty = Boolean(stream?.isTTY);
+  const width = tty ? Math.min(Math.max(stream.columns || 80, 40), 100) - 2 : Infinity;
+  if (env.NO_COLOR) return makeStyle(false, width);
+  if (env.FORCE_COLOR && env.FORCE_COLOR !== "0") return makeStyle(true, width);
+  return makeStyle(tty && env.TERM !== "dumb", width);
+}
+
+const TONES = {
+  ok: ["✓", "green"],
+  warn: ["!", "yellow"],
+  fail: ["✗", "red"],
+  info: ["•", "cyan"],
+};
+
+// ok for success; warn when the command stopped for a person to act;
+// fail for everything else.
+export function toneFor(outcome) {
+  if (outcome === "ok") return "ok";
+  if (outcome === "action_required" || outcome === "authentication_required") return "warn";
+  return "fail";
+}
+
+export function headline(style, tone, title, outcome = null) {
+  const [icon, color] = TONES[tone];
+  let line = `${style[color](icon)} ${style.bold(title)}`;
+  if (outcome !== null && outcome !== "ok") line += `  ${style.dim(`(${outcome}, exit ${EXIT_CODES[outcome]})`)}`;
+  return line;
+}
+
+// Aligned "label  value" rows. Rows whose value is null or undefined are left out.
+export function fields(style, rows, indent = "  ") {
+  const shown = rows.filter(([, value]) => value !== null && value !== undefined);
+  const width = Math.max(0, ...shown.map(([label]) => label.length));
+  return shown.map(([label, value]) => `${indent}${style.dim(label.padEnd(width))}  ${value}`);
+}
+
+// Indents prose and wraps it to style.width.
+export function paragraph(style, text, indent = "  ") {
+  const width = style.width;
+  const lines = [];
+  let line = "";
+  for (const word of String(text).split(/\s+/).filter(Boolean)) {
+    if (line && indent.length + line.length + 1 + word.length > width) {
+      lines.push(indent + line);
+      line = word;
+    } else {
+      line = line ? `${line} ${word}` : word;
+    }
+  }
+  if (line) lines.push(indent + line);
+  return lines;
+}
+
+// "→ label  value" rows for what to do next, aligned like fields.
+export function steps(style, rows) {
+  const shown = rows.filter(([, value]) => value !== null && value !== undefined);
+  const width = Math.max(0, ...shown.map(([label]) => label.length));
+  return shown.flatMap(([label, value]) => {
+    if (label) return [`${style.cyan("→")} ${label.padEnd(width)}  ${value}`];
+    // Unlabeled steps are prose: wrap them with a hanging indent.
+    const [first, ...rest] = paragraph(style, value, "  ");
+    return [`${style.cyan("→")} ${first.trimStart()}`, ...rest];
+  });
+}
+
+export function section(style, title) {
+  return style.bold(title);
+}
+
+export function render(lines) {
+  // Collapse runs of blank lines and trim blank edges.
+  const out = [];
+  for (const line of lines) {
+    if (line === "" && (out.length === 0 || out[out.length - 1] === "")) continue;
+    out.push(line);
+  }
+  while (out.length > 0 && out[out.length - 1] === "") out.pop();
+  return `${out.join("\n")}\n`;
+}

package/src/transport.js

@@ -1,16 +1,17 @@
 import http from "node:http";
 import https from "node:https";
 
-import { PACKAGE_NAME, READ_QUERY_KEYS, VERSION } from "./constants.js";
+import { MAX_QUERY_LENGTH, PACKAGE_NAME, READ_QUERY_KEYS, READ_QUERY_REPEATABLE, VERSION } from "./constants.js";
 import { classifyError } from "./http.js";
 
 const USER_AGENT = `${PACKAGE_NAME}/${VERSION}`;
-const MAX_QUERY_LENGTH = 2048;
+// MAX_QUERY_LENGTH is shared with argument validation (constants.js).
 
 // Builds the request URL. Without a query the path must be a fixed path on
 // the origin with no search part. A query is accepted only as a
 // URLSearchParams the caller built, only on a path in READ_QUERY_KEYS, only
-// with that path's keys, each at most once. Anything else is a programming
+// with that path's keys, each at most once unless READ_QUERY_REPEATABLE lists
+// it for that path. Anything else is a programming
 // error, so no input can choose another path, origin or header.
 function requestUrl(origin, pathname, query) {
   const url = new URL(pathname, origin);
@@ -23,9 +24,12 @@ function requestUrl(origin, pathname, query) {
   if (!(query instanceof URLSearchParams) || allowed === null) {
     throw new Error("a query is not allowed on this path");
   }
+  const repeatable = READ_QUERY_REPEATABLE[pathname] ?? [];
   const seen = new Set();
   for (const key of query.keys()) {
-    if (!allowed.includes(key) || seen.has(key)) throw new Error("query key is not allowed");
+    if (!allowed.includes(key) || (seen.has(key) && !repeatable.includes(key))) {
+      throw new Error("query key is not allowed");
+    }
     seen.add(key);
   }
   const search = query.toString();
@@ -48,11 +52,13 @@ function requestUrl(origin, pathname, query) {
 // other status are read up to maxBytes; a larger body sets tooLarge and is
 // discarded. The only credential ever sent is the bearer argument, and only
 // to this origin. Nothing is taken from the environment, and no cookies are
-// sent or kept. query is null or a URLSearchParams accepted by requestUrl.
+// sent or kept. useGlobalAgent is opt-in for public pricing so Node can use its
+// configured environment proxy (Node 24+ with --use-env-proxy). Other callers
+// retain their existing isolated-agent behavior. query is null or a URLSearchParams accepted by requestUrl.
 export function send(
   origin,
   pathname,
-  { method = "GET", signal, maxBytes, bearer = null, form = null, json = null, query = null },
+  { method = "GET", signal, maxBytes, bearer = null, form = null, json = null, query = null, useGlobalAgent = false },
 ) {
   const url = requestUrl(origin, pathname, query);
 
@@ -87,7 +93,7 @@ export function send(
     const transport = url.protocol === "https:" ? https : http;
     let request;
     try {
-      request = transport.request(url, { method, agent: false, signal, headers });
+      request = transport.request(url, { method, agent: useGlobalAgent ? undefined : false, signal, headers });
     } catch (error) {
       fail(error);
       return;