metergraph-cli 0.2.1 → 0.2.3

package/src/cli.js

@@ -1,3 +1,5 @@
+import { runPricing } from "./pricing.js";
+import { pricingText, pricingHtml } from "./pricing-output.js";
 import { READ_COMMANDS, parseArgs } from "./args.js";
 import { runLogin, runLogout } from "./auth-login.js";
 import { runDoctor } from "./doctor.js";
@@ -15,22 +17,35 @@ import {
   versionData,
 } from "./output.js";
 import { runRead } from "./read.js";
+import { runExperimentStart } from "./experiments.js";
+import { experimentsMessage, experimentsText } from "./experiments-output.js";
 import { readMessage, readText } from "./read-output.js";
 import { listSkillPack, runSkill, runSkillPack } from "./skill.js";
 import { runSetup } from "./setup.js";
 import { containsKnownCredential, preflightNonHostedSetup, prerequisiteGuide, resumeNonHostedRoute } from "./setup-deployment.js";
+import {
+  ASKABLE,
+  agentAccessOffer,
+  canAsk,
+  commandLine,
+  fillSetupArgv,
+  offerAgentAccess,
+  terminalPrompter,
+} from "./setup-interactive.js";
 import { VERSION } from "./constants.js";
+import { createStyle, fields, headline, paragraph, render, steps, toneFor } from "./style.js";
 import { runVerify } from "./verify.js";
 import { verifyMessage, verifyText } from "./verify-output.js";
 
 // Runs one command and resolves with the exit code. With --json, stdout gets
 // exactly one JSON line and stderr stays empty. Without it, results go to
-// stdout and usage or internal errors go to stderr. Never reads stdin.
-export async function main(argv, { stdout, stderr }) {
+// stdout and usage or internal errors go to stderr. Only setup reads stdin,
+// and only to ask a person at a terminal (see setup-interactive.js).
+export async function main(argv, { stdout, stderr, stdin = null }) {
   const json = argv.includes("--json");
   let result;
   try {
-    result = await run(argv, { stdout, stderr });
+    result = await run(argv, { stdout, stderr, stdin });
   } catch {
     result = envelope({
       command: null,
@@ -44,8 +59,33 @@ export async function main(argv, { stdout, stderr }) {
   return result.exit_code;
 }
 
-async function run(argv, { stdout, stderr }) {
-  const parsed = parseArgs(argv);
+async function run(argv, { stdout, stderr, stdin }) {
+  let parsed = parseArgs(argv);
+  const style = createStyle(stdout);
+  const say = (...lines) => stdout.write(lines.map((line) => `${line}\n`).join(""));
+  const asking = canAsk(argv, { stdin, stdout });
+
+  // A person at a terminal is asked for what setup is missing; the answers
+  // become flags and go through the same parsing as a script's.
+  if (parsed.command === "setup" && !parsed.ok && ASKABLE.has(parsed.code) && asking) {
+    const prompter = terminalPrompter(stdin, stdout);
+    let filled;
+    try {
+      filled = await fillSetupArgv(argv, { ask: prompter.ask, say });
+    } finally {
+      prompter.close();
+    }
+    if (filled === null) {
+      stderr.write("Setup was cancelled. Nothing was changed.\n");
+      return envelope({ command: "setup", outcome: "cancelled", reason: "questions_cancelled",
+        message: "Setup was cancelled. Nothing was changed." });
+    }
+    argv = filled;
+    parsed = parseArgs(argv);
+    // Only a command that parses is shown: a value the parser refuses may be
+    // a mistyped credential, and its error never echoes input.
+    if (parsed.ok) say("", `Running: ${commandLine(filled)}`, "");
+  }
 
   if (!parsed.ok) {
     const result = envelope({
@@ -55,13 +95,13 @@ async function run(argv, { stdout, stderr }) {
       message: parsed.message,
     });
     if (parsed.json) stdout.write(toJsonLine(result));
-    else stderr.write(`Error: ${parsed.message}\n`);
+    else stderr.write(`${createStyle(stderr).red("Error:")} ${parsed.message}\n`);
     return result;
   }
 
   if (parsed.command === "help") {
     const result = envelope({ command: "help", outcome: "ok", data: helpData(parsed.topic) });
-    stdout.write(parsed.json ? toJsonLine(result) : helpText(parsed.topic));
+    stdout.write(parsed.json ? toJsonLine(result) : helpText(parsed.topic, style));
     return result;
   }
 
@@ -71,6 +111,14 @@ async function run(argv, { stdout, stderr }) {
     return result;
   }
 
+  if (parsed.command === "pricing") {
+    const response = await runPricing(parsed);
+    const result = envelope({ command: `pricing ${parsed.action}`, ...response });
+    stdout.write(parsed.json ? toJsonLine(result) :
+      parsed.format === "html" && result.ok ? pricingHtml(result.data) : pricingText(result, parsed.format, style));
+    return result;
+  }
+
   if (parsed.command === "login" || parsed.command === "logout") {
     // Human progress goes to stderr, never with --json, so stdout carries
     // only the final result.
@@ -87,7 +135,7 @@ async function run(argv, { stdout, stderr }) {
       data,
       message: outcome === "ok" ? null : message,
     });
-    stdout.write(parsed.json ? toJsonLine(result) : authText(result, message));
+    stdout.write(parsed.json ? toJsonLine(result) : authText(result, message, style));
     return result;
   }
 
@@ -104,22 +152,30 @@ async function run(argv, { stdout, stderr }) {
       ? await runSetup({ ...options, expectedProfile: routed.profile ?? null, announce: pending.announce }, progress)
       : routed;
     if (pending.result) return pending.result;
-    const { outcome, reason, data } = response;
+    const { outcome, reason } = response;
+    // The customer-local bundle can give the agent more than Metadata
+    // without a sign in; say how.
+    const offer = outcome === "ok" && routed.profile === "local";
+    const data = offer ? { ...response.data, agent_access: agentAccessOffer(options.origin) } : response.data;
     let result = envelope({ command: "setup", outcome, reason, data,
       message: outcome === "ok" ? null : "Setup did not complete. Review the reason and retry safely." });
     if (containsKnownCredential(result, routed)) {
       result = envelope({ command: "setup", outcome: "unsupported", reason: "credential_echo" });
     }
-    const receipt = result.data?.receipt;
-    const summary = receipt ? `Workspace: ${receipt.workspace_id}\nDeployment: ${receipt.deployment_profile} at ${receipt.origin}\nCompleted: ${receipt.completed_steps.join(", ")}\nPending: ${receipt.pending_steps.join(", ")}\n` : "";
-    const identity = repositoryLine(result.data?.repository);
-    const guide = handoffLines(result.data);
-    const human = `Metergraph setup: ${result.data?.status ?? "not_ready"}\n${summary}${identity}${guide}Application traffic verified: no\n${result.ok ? "Next: instrument your application and verify an exact trace.\n" : `Result: ${result.outcome} (${result.error.reason})\n`}`;
+    const human = setupText(result, style, { asking });
     if (containsKnownCredential(human, routed)) {
       result = envelope({ command: "setup", outcome: "unsupported", reason: "credential_echo" });
       stdout.write(parsed.json ? toJsonLine(result) : "Setup stopped.\n");
-    } else {
-      stdout.write(parsed.json ? toJsonLine(result) : human);
+      return result;
+    }
+    stdout.write(parsed.json ? toJsonLine(result) : human);
+    if (offer && asking && result.ok) {
+      const prompter = terminalPrompter(stdin, stdout);
+      try {
+        await offerAgentAccess({ client: options.client, origin: options.origin, prompter, say });
+      } finally {
+        prompter.close();
+      }
     }
     return result;
   }
@@ -134,7 +190,23 @@ async function run(argv, { stdout, stderr }) {
       data,
       message: outcome === "ok" ? null : message,
     });
-    stdout.write(parsed.json ? toJsonLine(result) : readText(result, message));
+    stdout.write(parsed.json ? toJsonLine(result) : readText(result, message, style));
+    return result;
+  }
+
+  if (parsed.command === "experiments") {
+    // start is the one write: its own key session (experiments.js). The other
+    // actions are Metadata reads through runRead's shared session.
+    const { outcome, reason, data } = parsed.action === "start" ? await runExperimentStart(parsed) : await runRead(parsed);
+    const message = experimentsMessage(outcome, reason);
+    const result = envelope({
+      command: `experiments ${parsed.action}`,
+      outcome,
+      reason,
+      data,
+      message: outcome === "ok" ? null : message,
+    });
+    stdout.write(parsed.json ? toJsonLine(result) : experimentsText(result, message, style, parsed.action));
     return result;
   }
 
@@ -142,7 +214,7 @@ async function run(argv, { stdout, stderr }) {
     const { outcome, reason, data } = await runVerify(parsed);
     const message = verifyMessage(outcome, reason);
     const result = envelope({ command: "verify", outcome, reason, data, message: outcome === "ok" ? null : message });
-    stdout.write(parsed.json ? toJsonLine(result) : verifyText(result));
+    stdout.write(parsed.json ? toJsonLine(result) : verifyText(result, style));
     return result;
   }
 
@@ -155,7 +227,7 @@ async function run(argv, { stdout, stderr }) {
       data,
       message: outcome === "ok" ? null : message,
     });
-    stdout.write(parsed.json ? toJsonLine(result) : skillText(result, message));
+    stdout.write(parsed.json ? toJsonLine(result) : skillText(result, message, style));
     return result;
   }
 
@@ -169,7 +241,7 @@ async function run(argv, { stdout, stderr }) {
       data,
       message: outcome === "ok" ? null : message,
     });
-    stdout.write(parsed.json ? toJsonLine(result) : skillsText(result, message));
+    stdout.write(parsed.json ? toJsonLine(result) : skillsText(result, message, style));
     return result;
   }
 
@@ -184,7 +256,7 @@ async function run(argv, { stdout, stderr }) {
     data: report,
     message: doctorMessage(outcome, reason),
   });
-  stdout.write(parsed.json ? toJsonLine(result) : doctorText(result));
+  stdout.write(parsed.json ? toJsonLine(result) : doctorText(result, style));
   return result;
 }
 
@@ -209,39 +281,112 @@ function announcer(parsed, stdout, screen) {
   return pending;
 }
 
-// What an operator handoff is waiting for, in fixed text: the route, each
-// unconfirmed prerequisite with its guidance, and the next action.
-function handoffLines(data) {
-  if (data?.status !== "operator_handoff") return "";
-  let text = data.origin ? `Deployment: ${data.deployment_profile} at ${data.origin}\n` : "";
-  if (data.workspace_id) text += `Workspace: ${data.workspace_id}\n`;
+const SETUP_TITLES = {
+  ready_for_instrumentation: "Setup complete, ready to instrument",
+  operator_handoff: "Setup is waiting on the operator",
+};
+
+function setupText(result, style, { asking = false } = {}) {
+  const data = result.data;
+  const status = data?.status ?? "not_ready";
+  const title = SETUP_TITLES[status] ?? (result.ok ? `Setup: ${status}` : "Setup did not complete");
+  const tone = status === "operator_handoff" ? "warn" : toneFor(result.outcome);
+  const lines = [headline(style, tone, title, result.outcome), ""];
+  const receipt = data?.receipt;
+  const rows = [];
+  if (receipt) {
+    rows.push(
+      ["Workspace", receipt.workspace_id],
+      ["Deployment", `${receipt.deployment_profile} at ${receipt.origin}`],
+      ["Completed", receipt.completed_steps.join(", ") || "none"],
+      ["Pending", receipt.pending_steps.join(", ") || "none"],
+    );
+  }
+  const repository = repositoryValue(data?.repository);
+  if (repository !== null) rows.push(["Repository", repository]);
+  if (status === "operator_handoff") {
+    if (data.origin) rows.push(["Deployment", `${data.deployment_profile} at ${data.origin}`]);
+    if (data.workspace_id) rows.push(["Workspace", data.workspace_id]);
+  }
+  rows.push(["Application traffic verified", "no"]);
+  lines.push(...fields(style, rows), "");
+  if (!result.ok) lines.push(...paragraph(style, result.error.message), `  ${style.dim(`Reason: ${result.error.reason}`)}`, "");
+  lines.push(...handoffLines(data, style));
+  lines.push(...remoteLines(data, style));
+  lines.push(...budgetLines(data, style));
+  if (result.ok) lines.push(...steps(style, [["", "Instrument your application and verify an exact trace."]]));
+  // At a terminal the offer is a question asked next instead.
+  if (data?.agent_access && !asking) lines.push(...agentAccessLines(data.agent_access, style));
+  return render(lines);
+}
+
+// How to give the agent more than Metadata on the customer-local bundle.
+function agentAccessLines(access, style) {
+  const offer = access.offer;
+  return ["", ...steps(style, [
+    ["", "Your coding agent has Metadata access. To let it write evaluations and start analyses, " +
+      "run this in the bundle directory. It shows what it grants and asks you to confirm, then writes " +
+      "the key to that file without printing it."],
+    ["In the bundle directory", style.bold(offer.command)],
+    ["Bundle without bin/agent-key", offer.keys_page_url],
+  ]), ""];
+}
+
+// What an operator handoff is waiting for, in fixed text: each unconfirmed
+// prerequisite with its guidance, and the next action.
+function handoffLines(data, style) {
+  if (data?.status !== "operator_handoff" || data.next_action?.kind === "run_on_local_machine") return [];
+  const lines = [];
   if (data.pending_prerequisites.length > 0) {
-    text += "Confirm each prerequisite, then rerun with --confirm-prerequisites:\n";
+    lines.push("Confirm each prerequisite, then rerun with --confirm-prerequisites:");
     for (const name of data.pending_prerequisites) {
-      text += `  - ${name}: ${prerequisiteGuide(name, data.deployment_profile) ?? "see the guide"}\n`;
+      lines.push(`  ${style.yellow("•")} ${style.bold(name)}`,
+        ...paragraph(style, prerequisiteGuide(name, data.deployment_profile) ?? "See the guide.", "    "));
     }
+    lines.push("");
   }
   const next = data.next_action;
-  if (next?.message && !(next.kind === "complete_prerequisite" && data.pending_prerequisites.includes(next.prerequisite))) {
-    text += `Next: ${next.message}\n`;
-  }
-  if (next?.url) text += `Guide: ${next.url}\n`;
-  return text;
+  const message = next?.message && !(next.kind === "complete_prerequisite" && data.pending_prerequisites.includes(next.prerequisite))
+    ? next.message : null;
+  lines.push(...steps(style, [["", message], ["Guide", next?.url ?? null]]), "");
+  return lines;
+}
+
+// A refused key issuance: wait for the next window, or revoke unused keys.
+function budgetLines(data, style) {
+  const next = data?.next_action;
+  if (next?.kind !== "retry_later" && next?.kind !== "revoke_keys") return [];
+  return [...steps(style, [["", next.message], ["Keys page", next.url ?? null]]), ""];
+}
+
+// A remote session's handoff: where setup runs instead, and how this
+// environment can still make Metadata reads with a separate agent key.
+function remoteLines(data, style) {
+  const next = data?.next_action;
+  if (next?.kind !== "run_on_local_machine") return [];
+  const keys = next.metadata_reads?.person_steps.find((step) => step.action === "create_metadata_key")?.url ?? null;
+  return [...steps(style, [
+    ["", next.message],
+    ["On the person's own machine", style.bold(next.command)],
+    ["Metadata key for reads here", keys],
+    ["Then run here", next.metadata_reads ? style.bold(next.metadata_reads.then_run.join(", then ")) : null],
+    ["Guide", next.url],
+  ]), ""];
 }
 
-// One line on the repository identity setup found or recorded. The value is
-// owner/name only; a remote URL is never shown.
-function repositoryLine(repository) {
-  if (!repository) return "";
+// The repository identity setup found or recorded. The value is owner/name
+// only; a remote URL is never shown.
+function repositoryValue(repository) {
+  if (!repository) return null;
   const where = repository.path ? ` in ${repository.path}` : repository.source === "env_file" ? " in the env file" : "";
   switch (repository.status) {
-    case "written": return `Repository: ${repository.repository} (recorded${where}; commit it)\n`;
+    case "written": return `${repository.repository} (recorded${where}; commit it)`;
     case "existing": return repository.repository === null
-      ? `Repository: already set${where}\n` : `Repository: ${repository.repository} (already set${where})\n`;
-    case "mismatch": return `Repository: ${repository.repository} (already set${where}; differs from ${repository.expected}, left unchanged)\n`;
-    case "invalid_config": return `Repository: not recorded (${repository.path} is not a usable config; left unchanged)\n`;
-    case "skipped": return "Repository: not recorded (--no-repository)\n";
-    case "write_failed": return `Repository: not recorded (could not write ${repository.path})\n`;
-    default: return "Repository: not recorded (no owner/name git remote; pass --repository OWNER/NAME)\n";
+      ? `already set${where}` : `${repository.repository} (already set${where})`;
+    case "mismatch": return `${repository.repository} (already set${where}; differs from ${repository.expected}, left unchanged)`;
+    case "invalid_config": return `not recorded (${repository.path} is not a usable config; left unchanged)`;
+    case "skipped": return "not recorded (--no-repository)";
+    case "write_failed": return `not recorded (could not write ${repository.path})`;
+    default: return "not recorded (no owner/name git remote; pass --repository OWNER/NAME)";
   }
 }

package/src/constants.js

@@ -95,15 +95,68 @@ export const AUTH_PATHS = Object.freeze({
 // --limit locally.
 export const READ_PATHS = Object.freeze({
   usage: "/v1/agent/usage",
+  usageAggregates: "/v1/agent/usage/aggregates",
   routes: "/v1/agent/routes",
   traces: "/v1/agent/traces",
 });
+const PRICING_QUERY_KEYS = Object.freeze(["model", "provider", "channel", "region", "at", "limit",
+  "input_tokens", "output_tokens", "cache_read_tokens", "cache_write_tokens", "cache_write_5m_tokens", "cache_write_1h_tokens", "batch"]);
 export const READ_QUERY_KEYS = Object.freeze({
-  "/v1/agent/usage": Object.freeze(["days", "limit"]),
-  "/v1/agent/traces": Object.freeze(["days", "limit", "route", "status", "cursor"]),
+  "/v1/pricing/lookup": PRICING_QUERY_KEYS,
+  "/v1/pricing/cost": PRICING_QUERY_KEYS,
+  "/v1/pricing/history": PRICING_QUERY_KEYS,
+  "/v1/pricing/market": PRICING_QUERY_KEYS,
+  "/v1/agent/usage": Object.freeze(["days", "limit", "metadata"]),
+  "/v1/agent/experiments": Object.freeze(["workload_id", "limit"]),
+  "/v1/agent/usage/aggregates": Object.freeze([
+    "group_by", "days", "since", "until", "limit", "route", "provider", "model", "environment", "metadata",
+  ]),
+  "/v1/agent/traces": Object.freeze(["days", "limit", "route", "status", "cursor", "metadata"]),
   "/v1/cli/setup/credential": Object.freeze(["family_id"]),
 });
 
+// Query keys that may repeat on a path, one value each, as the service reads
+// list parameters. Every other key may appear at most once.
+export const READ_QUERY_REPEATABLE = Object.freeze({
+  // One group_by per dimension, so a metadata key is never split on a comma.
+  "/v1/agent/usage/aggregates": Object.freeze(["group_by", "route", "provider", "model", "environment"]),
+});
+
+// Grouped usage (GET /v1/agent/usage/aggregates). Dimensions the service can
+// group by (plus at most one "metadata.<key>"), the most values one filter may name, and how far apart the two
+// ends of an explicit window may be.
+export const USAGE_DIMENSIONS = Object.freeze(["provider", "model", "route", "day"]);
+export const USAGE_DEFAULT_GROUP_BY = Object.freeze(["provider", "model"]);
+export const USAGE_MAX_FILTER_VALUES = 20;
+export const USAGE_SORTS = Object.freeze(["cost", "cost-per-call", "calls", "errors", "avg-latency", "p95-latency", "day"]);
+export const USAGE_COMPARISONS = Object.freeze(["previous", "previous-same-time"]);
+
+// Experiments: replay a workload's recent production calls on 1 to 3
+// treatments and compare them with production. The list, estimate and
+// summary are Metadata reads at these fixed paths (one experiment is
+// EXPERIMENT_PATHS.list plus "/" and its UUID). Starting one is the only
+// write this CLI makes to a workspace: it needs a separate coding-agent key
+// with Debug access and the EXPERIMENT_START_SCOPE grant, used for that one
+// request and nothing else. The limits match the service's own.
+export const EXPERIMENT_PATHS = Object.freeze({
+  list: "/v1/agent/experiments",
+  estimate: "/v1/agent/experiments/estimate",
+  start: "/v1/agent/experiments",
+});
+export const EXPERIMENT_START_SCOPE = "agent:analysis-run";
+// Exactly the scopes a start key carries: Debug and the start grant. A key
+// with any other scope (Replay, other workflow grants, Metadata, ingest) is
+// refused, so the key in an agent's environment can do no more than this.
+export const EXPERIMENT_START_KEY_SCOPES = Object.freeze(["agent:read", EXPERIMENT_START_SCOPE]);
+export const EXPERIMENT_LAST_N = Object.freeze({ min: 10, max: 40, default: 20 });
+export const EXPERIMENT_MAX_TREATMENTS = 3;
+export const EXPERIMENT_MAX_TRACKED_FIELDS = 10;
+export const EXPERIMENT_LIST_DEFAULT_LIMIT = 20;
+export const EXPERIMENT_LIST_MAX_LIMIT = 50;
+export const EXPERIMENT_TEXT_LIMITS = Object.freeze({ workload: 500, provider: 60, model: 200, label: 40, path: 200 });
+export const EXPERIMENT_MAX_TOKENS = 32000;
+export const EXPERIMENT_REASONING_EFFORTS = Object.freeze(["none", "minimal", "low", "medium", "high", "xhigh", "max"]);
+
 // Read commands share one total deadline for every request they make,
 // including a token refresh. It is never reset per request or page.
 export const READ_DEFAULT_TIMEOUT_MS = 15000;
@@ -119,6 +172,15 @@ export const READ_DEFAULT_LIMIT = 50;
 export const TRACES_DEFAULT_LIMIT = 20;
 export const MAX_CURSOR_LENGTH = 512;
 export const MAX_FILTER_LENGTH = 256;
+// Exact customer-metadata filters, matching the service's bounds. The service
+// also refuses credential-like keys; the CLI checks the same rule first.
+export const MAX_METADATA_FILTERS = 5;
+export const MAX_METADATA_KEY_LENGTH = 200;
+export const MAX_METADATA_VALUE_LENGTH = 1000;
+// The longest query string the transport sends. Read arguments are checked
+// against the exact query they produce, so a long one is an input error
+// before any request rather than a failure after sign in.
+export const MAX_QUERY_LENGTH = 2048;
 
 // One exit code per outcome. Documented in README.md; changing a value is a
 // breaking change for scripts. New outcomes are appended.
@@ -142,6 +204,8 @@ export const EXIT_CODES = Object.freeze({
   rate_limited: 16,
   cancelled: 17,
   action_required: 18,
+  refused: 19,
+  unconfirmed: 20,
 });
 
 export const EXIT_CODE_MEANINGS = Object.freeze({
@@ -175,11 +239,17 @@ export const EXIT_CODE_MEANINGS = Object.freeze({
     "The service does not make this read available to the project's Metadata grant. No data was read.",
   permission_denied:
     "The service refused this read for the signed in grant, for example for a missing scope or permission.",
-  rate_limited: "The service asked the CLI to slow down. Nothing was retried. Try again later.",
+  rate_limited: "The service asked the CLI to slow down. Try again later. Only setup retries, after a short Retry-After, to keep its approval.",
   cancelled:
     "A read command was interrupted before it finished. Read commands never change workspace configuration or telemetry.",
   action_required:
     "A person must act before this command can finish; data.next_action says what to do. " +
     "With --json --no-browser the command exits as soon as the approval URL exists, and a background " +
     "process waits for approval until --timeout-ms. After approval, run the same command again to continue.",
+  refused:
+    "The service refused the experiment for a stated reason, such as its budget, the daily cap, experiments " +
+    "already running or a request it cannot price; data.refusal says which. Nothing was started.",
+  unconfirmed:
+    "An experiment start reached the service but its result was not confirmed, so an experiment may have " +
+    "been recorded and may run. List the workload's experiments before starting again: each start creates one.",
 });

package/src/environment.js

@@ -0,0 +1,169 @@
+import fs from "node:fs";
+
+import { CONNECTION_GUIDE_URL, DEFAULT_ORIGIN } from "./constants.js";
+
+// Where this CLI runs, for the sign in and setup path matrix. Only the
+// presence of a variable or file is checked; no value is ever read into
+// output.
+//
+//   local_shell      A terminal on the person's own machine. Browser sign in
+//                    and setup work here.
+//   local_container  A container on the person's machine (Docker, Podman, a
+//                    local dev container) with no remote marker. It is not
+//                    treated as remote: browser sign in works when the
+//                    container's loopback port is forwarded, and --no-browser
+//                    prints the URL to open.
+//   ssh_session      A shell reached over SSH. The person's browser is on
+//                    another machine.
+//   cloud_workspace  A hosted development environment (Codespaces, Gitpod,
+//                    Cloud Shell, or a remote dev container). The person's
+//                    browser is on another machine.
+//   ci               A CI job. No person is present.
+//
+// Remote markers win over container markers: a cloud workspace usually runs
+// in a container, and it is still remote.
+
+const REMOTE_MARKERS = [
+  ["ssh_session", ["SSH_CONNECTION", "SSH_CLIENT", "SSH_TTY"]],
+  ["cloud_workspace", ["CODESPACES", "GITPOD_WORKSPACE_ID", "CLOUD_SHELL"]],
+  ["ci", ["CI"]],
+];
+const CONTAINER_VARIABLES = ["REMOTE_CONTAINERS", "DEVCONTAINER", "container"];
+const CONTAINER_FILES = ["/.dockerenv", "/run/.containerenv"];
+
+// The fixed reason each remote kind reports. These are the reasons login and
+// setup have always used, so scripts that match them keep working.
+const REMOTE_REASONS = Object.freeze({
+  ssh_session: "ssh_session",
+  cloud_workspace: "cloud_workspace",
+  ci: "ci_environment",
+});
+
+// The secret name an agent reads its Metadata key from. It matches the name
+// the hosted Keys page and the Agent Access MCP setup already use.
+export const AGENT_TOKEN_ENV = "METERGRAPH_AGENT_TOKEN";
+// The origin an agent key is sent to, when no project binding and no --url
+// names one. It matches the MCP setup's variable.
+export const AGENT_URL_ENV = "METERGRAPH_URL";
+
+function present(value) {
+  return typeof value === "string" && value !== "" && value !== "0" && value.toLowerCase() !== "false";
+}
+
+function defaultFileExists(file) {
+  try {
+    return fs.existsSync(file);
+  } catch {
+    return false;
+  }
+}
+
+// Returns { kind, remote, reason } where reason is null for a local kind.
+export function classifyEnvironment(env = process.env, { fileExists = defaultFileExists } = {}) {
+  for (const [kind, names] of REMOTE_MARKERS) {
+    if (names.some((name) => present(env[name]))) return { kind, remote: true, reason: REMOTE_REASONS[kind] };
+  }
+  const container =
+    CONTAINER_VARIABLES.some((name) => present(env[name])) || CONTAINER_FILES.some((file) => fileExists(file));
+  return { kind: container ? "local_container" : "local_shell", remote: false, reason: null };
+}
+
+// Hosted pages a person opens on their own device. The Keys page creates a
+// coding-agent key in the workspace the person is signed in to, which is how
+// the person chooses the workspace. Sign up exists only on the hosted service.
+export function handoffPages(origin) {
+  const hosted = origin === DEFAULT_ORIGIN;
+  return {
+    sign_up_url: hosted ? `${origin}/v1/auth/signup?return_to=${encodeURIComponent("/#api-keys")}` : null,
+    keys_url: `${origin}/#api-keys`,
+  };
+}
+
+// The structured next action for an agent that cannot finish browser sign in
+// where it runs, or has no credential yet. It names what a person does on
+// their own device, where the key goes, and the exact commands the agent runs
+// afterwards. The key itself never passes through the agent's chat, a command
+// line or a file in the project.
+export function agentKeyAction(environment, origin) {
+  const pages = handoffPages(origin);
+  const where = environment.kind === "ci"
+    ? `a CI secret exposed to this job as ${AGENT_TOKEN_ENV}`
+    : `this environment's secret settings as ${AGENT_TOKEN_ENV}`;
+  const steps = [];
+  if (pages.sign_up_url !== null) {
+    steps.push({ action: "sign_up_or_sign_in", url: pages.sign_up_url });
+  } else {
+    steps.push({ action: "request_invitation", url: null });
+  }
+  steps.push({ action: "create_metadata_key", url: pages.keys_url });
+  steps.push({ action: "store_secret", name: AGENT_TOKEN_ENV });
+  // A key for a deployment other than the hosted service must only ever be
+  // sent there, so the commands name its origin; without it they would use
+  // the hosted default.
+  const hosted = origin === DEFAULT_ORIGIN;
+  const url = hosted ? "" : ` --url ${shellArg(origin)}`;
+  return {
+    kind: "use_agent_key",
+    environment: environment.kind,
+    credential_env: AGENT_TOKEN_ENV,
+    origin,
+    person_steps: steps,
+    then_run: [`metergraph status${url} --json`, `metergraph usage${url} --json`],
+    message:
+      (environment.remote === false
+        ? "If browser sign in cannot finish here, use a Metadata key instead. "
+        : "Browser sign in cannot finish here. ") +
+      "Ask the person to sign in on their own device, open the Keys page " +
+      "in the workspace this agent should read, create a coding-agent key with Metadata access, and save it in " +
+      `${where}. Do not ask them to paste the key into chat or a command. Then run the listed commands; ` +
+      "they verify the origin, workspace, scope and capabilities before reading." +
+      (hosted
+        ? ""
+        : " On the open-source self-hosted server there is no Keys page: the operator provides one of its " +
+          "MG_AGENT_TOKENS values instead."),
+    alternative: { kind: "run_on_local_machine", command: "metergraph login --runtime local" },
+    url: CONNECTION_GUIDE_URL,
+  };
+}
+
+// The next action for setup in a remote session. Ingest setup writes the
+// application's own key and needs a local browser approval, so it runs on the
+// person's machine. Metadata reads can still use an agent key here; that key
+// is separate from the ingest key and never replaces it.
+// options are the parsed setup options; the command repeats the caller's
+// deployment, origin, workspace and skill choice so it runs as given.
+export function remoteSetupAction(environment, origin, options = {}) {
+  return {
+    kind: "run_on_local_machine",
+    environment: environment.kind,
+    command: setupCommand(origin, options),
+    message:
+      "Setup approves an ingest key in a browser on the same machine as the CLI, so it cannot finish here. " +
+      "Run it on the person's own machine, or follow the connection guide. For Metadata reads from this " +
+      "environment, follow metadata_reads.",
+    metadata_reads: agentKeyAction(environment, origin),
+    url: CONNECTION_GUIDE_URL,
+  };
+}
+
+// Agents run these commands in a shell, and an origin may come from a
+// committed project file, so every interpolated value is quoted even though
+// the parsers already restrict it. Without a client choice the command skips
+// the skill rather than show a placeholder a shell would misread.
+function setupCommand(origin, options) {
+  const parts = ["metergraph setup --runtime local"];
+  if (options.deployment && options.deployment !== "managed") parts.push(`--deployment ${shellArg(options.deployment)}`);
+  if (origin !== DEFAULT_ORIGIN) parts.push(`--url ${shellArg(origin)}`);
+  if (options.workspace) parts.push(`--workspace ${shellArg(options.workspace)}`);
+  if (options.skipSkill || !options.client) parts.push("--skip-skill");
+  else parts.push(`--client ${shellArg(options.client)}`);
+  return parts.join(" ");
+}
+
+// A value as one POSIX shell word: as is when it holds only characters no
+// shell treats specially, otherwise single-quoted.
+export function shellArg(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9._:/=-]+$/.test(text)) return text;
+  return `'${text.replace(/'/g, "'\\''")}'`;
+}