metergraph-cli 0.2.1 → 0.2.3

package/src/read.js

@@ -1,23 +1,34 @@
+import { agentKeySource, keySession, keyTarget, readAgentKey } from "./agent-key.js";
 import { readBinding, resolveProject } from "./auth-binding.js";
 import { checkDeployment } from "./doctor.js";
 import { sessionFor } from "./auth-session.js";
-import { Stop, openStore, resolveConfigDir } from "./auth-store.js";
-import { MAX_BODY_BYTES, METADATA_SCOPE, READ_MAX_BYTES, READ_PATHS } from "./constants.js";
+import { Stop, openStore, readCredential, resolveConfigDir } from "./auth-store.js";
+import { DEFAULT_ORIGIN, MAX_BODY_BYTES, METADATA_SCOPE, READ_MAX_BYTES, READ_MAX_LIMIT, READ_PATHS } from "./constants.js";
 import { parseJsonObject } from "./http.js";
 import {
+  readQuery,
+  groupedRequest,
+  READ_ENVIRONMENTS,
   CAPABILITY_NAMES,
   capabilitySummary,
   routesReport,
   tracesReport,
+  usageAggregatesReport,
   usageReport,
   workspaceContext,
 } from "./read-contract.js";
+import { compareReports, priorWindow, rankReport } from "./usage-aggregates.js";
 import { deadline, failureOf, send, trapSignals } from "./transport.js";
+import { experimentNextAction, experimentRead } from "./experiments.js";
+import { agentKeyAction, classifyEnvironment, handoffPages } from "./environment.js";
 
 // The read commands: status, context, capabilities, usage, routes and traces.
-// Each one uses the project's existing verified session (never a browser,
-// never a new grant), shares one total deadline across every request,
-// including a token refresh, and sends GET requests only, to fixed paths on
+// Each one uses either the project's existing verified session or a
+// coding-agent key with Metadata access (agent-key.js); never a browser,
+// never a new grant. A saved project grant is used when one exists, unless
+// --agent-token-file names a key explicitly; otherwise a key in
+// METERGRAPH_AGENT_TOKEN is used. Each one shares one total deadline across
+// every request, including a token refresh, and sends GET requests only, to fixed paths on
 // the bound origin. Nothing is written except what the session helper writes
 // when it refreshes the grant. Each returns { outcome, reason, data } where
 // data holds only validated fields and fixed tokens, and never a credential
@@ -29,12 +40,21 @@ const READS = Object.freeze({
   routes: { capability: "routes", path: READ_PATHS.routes, validate: routesReport },
   traces: { capability: "trace_metadata", path: READ_PATHS.traces, validate: tracesReport },
 });
+const GROUPED_USAGE = Object.freeze({
+  capability: "usage_aggregates",
+  path: READ_PATHS.usageAggregates,
+  validate: usageAggregatesReport,
+});
 
 export async function runRead(options) {
+  const env = options.env ?? process.env;
   const ctx = {
     command: options.command,
+    environment: options.environment ?? classifyEnvironment(env),
+    credential: null,
     origin: null,
     workspaceId: null,
+    intendedWorkspace: null,
     profile: null,
     configured: false,
     reachable: null,
@@ -49,14 +69,19 @@ export async function runRead(options) {
   const limit = deadline(options.timeoutMs, trap.signal);
   // Token values this run holds. Filled after the session is verified.
   let known = [];
+  const grouped = options.command === "usage" && options.grouped !== undefined && options.grouped !== null;
   const build = (outcome, report) =>
-    options.command === "status" ? statusData(ctx, notices, outcome) : readData(ctx, report, notices, outcome);
+    options.command === "status"
+      ? statusData(ctx, notices, outcome, options)
+      : readData(ctx, report, notices, outcome, options, { grouped, report });
   const end = (outcome, reason, report = null) => {
+    ctx.reason = reason;
     const data = build(outcome, report);
     // Validated metadata can still be any string the service chose. If any
     // printed string holds a credential this run knows, nothing is printed.
     if (holdsKnown(data, known)) {
       notices.clear();
+      ctx.reason = "credential_in_metadata_response";
       return {
         outcome: "verification_failed",
         reason: "credential_in_metadata_response",
@@ -80,18 +105,57 @@ export async function runRead(options) {
     const root = resolveProject(options.project);
     const configDir = resolveConfigDir(options.configDir);
     const found = readBinding(root);
-    if (found === null) return end("login_required", "not_signed_in");
-    const binding = found.binding;
+    const binding = found?.binding ?? null;
+    const source = agentKeySource(options, env);
+    // The private store matters only for a bound project. With a key at
+    // hand, a store that cannot be read means no grant here; without one,
+    // its error is the answer, as before.
+    let store = null;
+    let grantSaved = false;
+    let originConfirmed = false;
+    if (binding !== null) {
+      try {
+        store = openStore(configDir, { create: false });
+        const record = store === null ? null : readCredential(store, binding.credential_slot);
+        grantSaved = record !== null;
+        originConfirmed = record !== null && record.origin === binding.origin;
+      } catch (error) {
+        if (!(error instanceof Stop) || source === null) throw error;
+        store = null;
+      }
+    }
+    // An explicit key file wins. Otherwise a saved grant wins over the
+    // environment variable, so a project signed in on this machine behaves as
+    // it always has; a binding without a grant here (for example one
+    // committed to the repository and cloned into a remote workspace) uses
+    // the key, pinned to the binding.
+    const useKey = source !== null && (source.kind === "file" || !grantSaved);
+    if (!useKey && binding === null) return end("login_required", "not_signed_in");
+    if (!useKey && source !== null) notices.add("agent_key_not_used");
+
+    ctx.credential = useKey ? "agent_key" : "oauth_grant";
+    // A key in the environment is checked for shape before any request,
+    // including status's unauthenticated probes.
+    if (useKey && source.kind === "env") {
+      const shape = readAgentKey(source, env);
+      if (!shape.ok) return end(shape.outcome, shape.reason);
+    }
+    // --url, METERGRAPH_URL (for a key only) and --workspace may repeat the
+    // binding but never contradict it.
+    const target = keyTarget({ binding, options, env: useKey ? env : {}, originConfirmed: originConfirmed || !useKey });
+    if (!target.ok) return end(target.outcome, target.reason);
     Object.assign(ctx, {
-      origin: binding.origin,
-      workspaceId: binding.workspace_id,
-      profile: binding.deployment_profile,
-      configured: true,
+      origin: target.origin,
+      workspaceId: target.workspaceId,
+      intendedWorkspace: target.workspaceId,
+      profile: target.profile,
+      // configured means this project is bound; a key alone binds nothing.
+      configured: binding !== null,
     });
-    const store = openStore(configDir, { create: false });
 
+    let verifiedProfile = null;
     if (options.command === "status") {
-      const health = await checkHealth(binding.origin, limit.signal);
+      const health = await checkHealth(ctx.origin, limit.signal);
       ctx.reachable = health.reachable;
       ctx.healthy = health.healthy;
       if (!health.ok) {
@@ -101,22 +165,31 @@ export async function runRead(options) {
       // The service's own unauthenticated profile report must be the bound
       // profile before the grant is even tried.
       const deployment = checkDeployment(
-        await send(binding.origin, "/v1/deployment", { signal: limit.signal, maxBytes: MAX_BODY_BYTES }),
+        await send(ctx.origin, "/v1/deployment", { signal: limit.signal, maxBytes: MAX_BODY_BYTES }),
       );
       if (deployment.outcome !== null) {
         if (deployment.outcome === "unhealthy") ctx.healthy = false;
         const settled = settle(deployment);
         return end(settled.outcome, settled.reason);
       }
-      ctx.profileVerified = deployment.profile === binding.deployment_profile;
+      verifiedProfile = deployment.profile;
+      ctx.profileVerified = ctx.profile === null || deployment.profile === ctx.profile;
       if (!ctx.profileVerified) return end("verification_failed", "profile_mismatch");
+      ctx.profile = deployment.profile;
     }
 
-    const session = await sessionFor(binding, store, limit.signal);
+    const session = useKey
+      ? await keySession({ target, source, env, signal: limit.signal, verifiedProfile })
+      : await sessionFor(binding, store, limit.signal);
     if (!session.ok) {
       const settled = settle(session);
       return end(settled.outcome, settled.reason);
     }
+    ctx.profile = session.session.profile;
+    if (ctx.workspaceId === null) {
+      ctx.workspaceId = session.session.workspaceId;
+      notices.add("workspace_not_pinned");
+    }
     known = session.knownCredentials;
     ctx.authenticated = true;
     const { documents } = session;
@@ -139,25 +212,84 @@ export async function runRead(options) {
       return end("ok", null, context.value);
     }
     if (options.command === "capabilities") return end("ok", null, capabilities.value);
+    if (options.command === "experiments") {
+      const read = await experimentRead(session.session, options, ctx, documents, limit.signal, notices);
+      if (!read.ok) {
+        const settled = read.outcome === "refused" ? read : settle(read);
+        const report = read.refusal ? { refusal: read.refusal }
+          : read.retryAfter !== undefined ? { retry_after_seconds: read.retryAfter } : null;
+        return end(settled.outcome, settled.reason, report);
+      }
+      return end("ok", null, read.value);
+    }
 
-    const read = READS[options.command];
+    const read = grouped ? GROUPED_USAGE : READS[options.command];
     const entry = capabilities.value.agent[read.capability];
-    if (entry === null || entry.available !== true) return end("capability_unavailable", "capability_unavailable");
+    if (entry === null || entry.available !== true) {
+      return end("capability_unavailable", grouped ? "usage_aggregates_unavailable" : "capability_unavailable");
+    }
     // The service's own bounds; a request beyond them is refused, never
     // clamped into a different question.
     const { bounds } = capabilities.value;
-    if ((options.days !== null && options.days > bounds.max_days) || options.limit > bounds.max_rows) {
+    // An explicit grouped window is held to the same day bound as --days.
+    const explicitDays = grouped && options.grouped.since !== null
+      ? ((options.grouped.until === null ? Date.now() : Date.parse(options.grouped.until)) -
+          Date.parse(options.grouped.since)) / (24 * 60 * 60 * 1000)
+      : null;
+    if (
+      (options.days !== null && options.days > bounds.max_days) ||
+      (explicitDays !== null && explicitDays > bounds.max_days) ||
+      options.limit > bounds.max_rows
+    ) {
       return end("unsupported", "exceeds_service_bounds");
     }
 
-    const response = await fetchRead(session.session, read.path, queryFor(options), limit.signal);
-    if (!response.ok) {
-      const settled = settle(response);
-      return end(settled.outcome, settled.reason, response.retryAfter === undefined ? null : { retry_after_seconds: response.retryAfter });
+    const fetchOne = async (query, request, into) => {
+      // When this read was asked for, to check a window that ends "now".
+      request = { ...request, requestedAt: Date.now() };
+      const response = await fetchRead(session.session, read.path, query, limit.signal);
+      if (!response.ok) {
+        // A key refused moments after it was verified was revoked meanwhile.
+        if (ctx.credential === "agent_key" && response.reason === "access_revoked") response.reason = "agent_key_rejected";
+        const settled = settle(response);
+        return {
+          ok: false,
+          ...settled,
+          detail: response.retryAfter === undefined ? null : { retry_after_seconds: response.retryAfter },
+        };
+      }
+      return read.validate(response.body, ctx, request, into);
+    };
+    if (!grouped) {
+      const report = await fetchOne(readQuery(options), requestOf(options), notices);
+      if (!report.ok) return end(report.outcome, report.reason, report.detail ?? null);
+      return end("ok", null, report.value);
     }
-    const report = read.validate(response.body, ctx, requestOf(options), notices);
-    if (!report.ok) return end(report.outcome, report.reason);
-    return end("ok", null, report.value);
+
+    // Grouped usage: the current window, then for --compare the prior
+    // window computed from the window the service actually read.
+    const request = groupedRequest(options);
+    const current = await fetchOne(readQuery(options, request), request, notices);
+    if (!current.ok) return end(current.outcome, current.reason, current.detail ?? null);
+    let report = rankReport(current.value, options.grouped.sort, notices);
+    if (options.grouped.compare !== null) {
+      const window = priorWindow(current.value.window, options.grouped.compare);
+      const priorRequest = { ...request, days: null, since: window.since, until: window.until, limit: options.limit };
+      // The prior read's own coverage notices describe the prior window; they
+      // are kept apart and summarised by the comparison.
+      const priorNotices = new Set();
+      const prior = await fetchOne(readQuery(options, priorRequest), priorRequest, priorNotices);
+      if (!prior.ok) return end(prior.outcome, prior.reason, prior.detail ?? null);
+      // Both windows must cover the same environments, or the change compares
+      // different populations.
+      if (JSON.stringify(prior.value[READ_ENVIRONMENTS]) !== JSON.stringify(current.value[READ_ENVIRONMENTS])) {
+        return end("verification_failed", "filter_mismatch");
+      }
+      for (const token of priorNotices) if (token !== "current_day_partial") notices.add(`prior_${token}`);
+      // The ranked report, so comparison rows follow the requested --sort.
+      report = { ...report, comparison: compareReports(report, prior.value, options.grouped.compare, notices) };
+    }
+    return end("ok", null, report);
   } catch (error) {
     if (error instanceof Stop) {
       const settled = settle(error);
@@ -176,23 +308,11 @@ function requestOf(options) {
     route: options.route ?? null,
     status: options.status ?? null,
     cursor: options.cursor ?? null,
+    metadata: options.metadata ?? null,
+    groupByMetadata: options.groupByMetadata ?? null,
   };
 }
 
-// The query string is built here from validated options only. The routes
-// endpoint takes none.
-function queryFor(options) {
-  if (options.command === "routes") return null;
-  const query = new URLSearchParams();
-  query.set("days", String(options.days));
-  query.set("limit", String(options.limit));
-  if (options.command === "traces") {
-    if (options.route !== null) query.set("route", options.route);
-    if (options.status !== null) query.set("status", options.status);
-    if (options.cursor !== null) query.set("cursor", options.cursor);
-  }
-  return query;
-}
 
 // Unauthenticated GET /healthz on the bound origin, so status can tell an
 // unreachable service from a refused grant. status then checks GET
@@ -219,7 +339,7 @@ const INSUFFICIENT_SCOPE = /(?:^|[\s,])error\s*=\s*"?insufficient_scope"?(?:$|[\
 // True when any string in value (keys included) contains one of the known
 // credential values. An exact containment check against values this run
 // holds, not a guess at what looks secret.
-function holdsKnown(value, known) {
+export function holdsKnown(value, known) {
   if (known.length === 0) return false;
   if (typeof value === "string") return known.some((secret) => value.includes(secret));
   if (value === null || typeof value !== "object") return false;
@@ -229,6 +349,14 @@ function holdsKnown(value, known) {
   return false;
 }
 
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+function retryAfterOf(response) {
+  const header = response.headers["retry-after"];
+  const seconds = typeof header === "string" && RETRY_AFTER.test(header.trim()) ? Number(header.trim()) : null;
+  return seconds !== null && seconds <= 86400 ? seconds : null;
+}
+
 // One GET with the session's access token. A refused token is never
 // refreshed and retried here: the grant was valid moments ago, so a refusal
 // means it was revoked or access was lost.
@@ -251,16 +379,18 @@ async function fetchRead(session, path, query, signal) {
       return { ok: false, outcome: "permission_denied", reason: scope ? "insufficient_scope" : "forbidden" };
     }
     if (status === 429) {
-      const header = response.headers["retry-after"];
-      const seconds = typeof header === "string" && RETRY_AFTER.test(header.trim()) ? Number(header.trim()) : null;
-      return {
-        ok: false,
-        outcome: "rate_limited",
-        reason: "rate_limited",
-        retryAfter: seconds !== null && seconds <= 86400 ? seconds : null,
-      };
+      return { ok: false, outcome: "rate_limited", reason: "rate_limited", retryAfter: retryAfterOf(response) };
     }
     if (status === 404) return { ok: false, outcome: "unsupported", reason: "endpoint_unavailable" };
+    if (status === 413) return { ok: false, outcome: "unsupported", reason: "response_too_large" };
+    if (status === 503) {
+      // The service's read budget (time or pool) was exceeded. Nothing is
+      // retried here; the result says when to retry and how to narrow it.
+      const body = parseJsonObject(response);
+      if (isObject(body?.error) && body.error.code === "temporarily_unavailable") {
+        return { ok: false, outcome: "unhealthy", reason: "temporarily_unavailable", retryAfter: retryAfterOf(response) };
+      }
+    }
     if (status === 400 || status === 422) return { ok: false, outcome: "unsupported", reason: "request_rejected" };
   }
   const failure = failureOf(response);
@@ -272,27 +402,33 @@ async function fetchRead(session, path, query, signal) {
 }
 
 // The shape shared by context, capabilities, usage, routes and traces.
-function readData(ctx, report, notices, outcome) {
+function readData(ctx, report, notices, outcome, options, extra = {}) {
   return {
     origin: ctx.origin,
     workspace: ctx.workspaceId === null ? null : { id: ctx.workspaceId },
     deployment_profile: ctx.profile,
+    environment: ctx.environment.kind,
+    credential: ctx.credential,
     authenticated: ctx.authenticated,
     scopes: ctx.authenticated ? [METADATA_SCOPE] : [],
     result: outcome === "ok" ? report : null,
-    retry_after_seconds: outcome === "rate_limited" ? report?.retry_after_seconds ?? null : null,
+    retry_after_seconds: outcome === "rate_limited" || report?.retry_after_seconds !== undefined
+      ? report?.retry_after_seconds ?? null : null,
+    ...(options.command === "experiments" ? { refusal: outcome === "refused" ? report?.refusal ?? null : null } : {}),
     notices: [...notices].sort(),
-    next_action: nextAction(outcome),
+    next_action: nextAction(outcome, ctx, options, extra),
   };
 }
 
 // status keeps configured, reachable, authenticated, the bound and verified
 // workspace and the capability flags apart. Application traffic is never
 // claimed: existing data or a configured SDK does not prove it.
-function statusData(ctx, notices, outcome) {
+function statusData(ctx, notices, outcome, options) {
   const agent = ctx.capabilities?.agent ?? null;
   return {
     origin: ctx.origin,
+    environment: ctx.environment.kind,
+    credential: ctx.credential,
     configured: ctx.configured,
     reachable: ctx.reachable,
     healthy: ctx.healthy,
@@ -301,10 +437,15 @@ function statusData(ctx, notices, outcome) {
     // true when GET /v1/deployment reported exactly the bound profile, false
     // when it reported another one, null when it was not checked.
     deployment_profile_verified: ctx.profileVerified,
+    // intended is null for an agent key with no binding and no --workspace;
+    // match is then null too, and the notices say workspace_not_pinned.
     workspace: {
-      intended: ctx.workspaceId,
+      intended: ctx.intendedWorkspace,
       actual: ctx.verifiedWorkspace,
-      match: ctx.verifiedWorkspace === null ? null : ctx.verifiedWorkspace === ctx.workspaceId,
+      match:
+        ctx.verifiedWorkspace === null || ctx.intendedWorkspace === null
+          ? null
+          : ctx.verifiedWorkspace === ctx.intendedWorkspace,
     },
     scopes: ctx.authenticated ? [METADATA_SCOPE] : [],
     capabilities:
@@ -312,14 +453,125 @@ function statusData(ctx, notices, outcome) {
     content_access: false,
     application_traffic_verified: false,
     notices: [...notices].sort(),
-    next_action: nextAction(outcome),
+    next_action: nextAction(outcome, ctx, options),
   };
 }
 
-function nextAction(outcome) {
+const NARROW =
+  "Narrow the read: a shorter --days or --since/--until window, exact --route, --provider or --model filters, " +
+  "fewer --group-by dimensions or a lower --limit.";
+
+// The next action for a read, by credential and environment. Where browser
+// sign in cannot finish (SSH, a cloud workspace, CI), the answer is always
+// the agent key handoff, never "run login". Grouped usage adds its own steps
+// (a supported read, retry, narrow, raise the limit, compare like for like);
+// their text is fixed except a window and limit computed from validated values.
+function nextAction(outcome, ctx, options, { grouped = false, report = null } = {}) {
+  const origin = ctx.origin ?? options.origin ?? DEFAULT_ORIGIN;
+  const keyed = ctx.credential === "agent_key";
+  const reason = ctx.reason;
+  const capabilities = ctx.capabilities;
+  if (outcome === "rate_limited") return { kind: "retry_later", message: "Wait, then run the same command again." };
+  const experiment = experimentNextAction(outcome, ctx, options, report);
+  if (experiment !== undefined) return experiment;
+  if (reason === "usage_aggregates_unavailable" || (grouped && reason === "endpoint_unavailable")) {
+    // Offer the route-by-day read only when this grant actually has it.
+    if (capabilities?.agent?.usage?.available !== true) return null;
+    return {
+      kind: "use_supported_read",
+      message:
+        "This deployment does not offer grouped usage to this grant. \"metergraph usage --days N\" still lists " +
+        "cost per route and day over the last N x 24 hours. Grouping by provider, model, UTC day or a metadata key " +
+        "needs a service that offers grouped usage; nothing was read.",
+      command: "metergraph usage --days 7 --json",
+    };
+  }
+  if (grouped && reason === "temporarily_unavailable") {
+    return { kind: "retry_later", message: `The service stopped the read at its time budget. Wait, then retry. ${NARROW}` };
+  }
+  if (grouped && reason === "response_too_large") return { kind: "narrow_read", message: NARROW };
+  if (outcome === "ok" && report?.sort && !report.sort.complete && report.matched_groups !== null) {
+    const needed = report.matched_groups;
+    // The largest --limit this deployment accepts, not only the CLI's own.
+    const maxLimit = Math.min(READ_MAX_LIMIT, capabilities?.bounds?.max_rows ?? READ_MAX_LIMIT);
+    return needed <= maxLimit
+      ? {
+          kind: "raise_limit",
+          message: `The ranking covers the ${report.rows} highest-cost groups of ${needed}. ` +
+            `Run the same command with --limit ${needed} to rank every group.`,
+        }
+      : { kind: "narrow_read", message: `The ranking covers the ${report.rows} highest-cost groups of ${needed}. ${NARROW}` };
+  }
+  if (outcome === "ok" && report?.comparison?.partial_day_compared_with_full) {
+    const window = report.comparison.like_for_like_window;
+    return {
+      kind: "compare_like_for_like",
+      message:
+        "The current window ends part way through today (UTC) and the prior period is whole days. " +
+        "For equal lengths, run the same command with --compare previous-same-time " +
+        `(prior window ${window.since} to ${window.until}).`,
+    };
+  }
+  if (keyed && (reason === "agent_key_rejected" || reason === "agent_key_insufficient_scope")) {
+    return {
+      kind: "replace_agent_key",
+      url: handoffPages(origin).keys_url,
+      message:
+        "The service refused this key: it is unknown, expired or revoked, or it lacks Metadata access. Ask the " +
+        "person to create a new coding-agent key with Metadata access on the Keys page and replace the secret. " +
+        "Do not ask for the key in chat.",
+    };
+  }
+  if (keyed && (reason === "scope_mismatch" || reason === "content_access_granted")) {
+    return {
+      kind: "use_metadata_only_key",
+      url: handoffPages(origin).keys_url,
+      message:
+        "This key grants more than Metadata access, so the CLI does not use it. Ask the person for a " +
+        "coding-agent key limited to Metadata access.",
+    };
+  }
+  if (keyed && reason === "workspace_context_mismatch") {
+    return {
+      kind: "use_workspace_key",
+      url: handoffPages(origin).keys_url,
+      workspace: ctx.intendedWorkspace === null ? null : { id: ctx.intendedWorkspace },
+      message:
+        "This key belongs to a different workspace than this project or --workspace names. Ask the person to " +
+        "create the key in the intended workspace, or pass the intended workspace with --workspace.",
+    };
+  }
+  if (keyed && reason === "agent_key_origin_unconfirmed") {
+    return {
+      kind: "confirm_origin",
+      message:
+        "This project's binding names a deployment other than the hosted service. A Metadata key is sent there " +
+        "only when you confirm the same address: set METERGRAPH_URL or pass --url with it.",
+    };
+  }
+  if (keyed && (reason === "bound_to_other_origin" || reason === "bound_to_other_workspace")) {
+    return {
+      kind: "match_project_binding",
+      message:
+        "This project's .metergraph/project.json names a different origin or workspace. Remove --url, " +
+        "--workspace or METERGRAPH_URL, or use a key for the bound workspace.",
+    };
+  }
+  if (keyed && reason?.startsWith("agent_token")) {
+    return {
+      kind: "fix_agent_key",
+      message:
+        "The key could not be used as given. METERGRAPH_AGENT_TOKEN must hold exactly one key with no label " +
+        "or spaces; --agent-token-file must name a private (0600) file owned by this user.",
+    };
+  }
   if (outcome === "login_required") {
-    return { kind: "login", message: 'Run "metergraph login --runtime local" in this project to sign in again.' };
+    if (ctx.environment.remote) return agentKeyAction(ctx.environment, origin);
+    return {
+      kind: "login",
+      message: 'Run "metergraph login --runtime local" in this project to sign in again.',
+      alternative: agentKeyAction(ctx.environment, origin),
+    };
   }
-  if (outcome === "rate_limited") return { kind: "retry_later", message: "Wait, then run the same command again." };
   return null;
 }

package/src/setup-deployment.js

@@ -1,4 +1,4 @@
-import { detectRemoteSession } from "./auth-browser.js";
+import { classifyEnvironment, remoteSetupAction } from "./environment.js";
 import { runDoctor } from "./doctor.js";
 import { action, planDeploymentRoute, verifyDeploymentRoute } from "./deployment-route.js";
 import { AUTH_HTTP_TIMEOUT_MS } from "./constants.js";
@@ -64,6 +64,13 @@ const ACTION_GUIDE = Object.freeze({
   retry: "Rerun the same command.",
 });
 
+// Each prerequisite a non-hosted route asserts, with its guidance, for a
+// person confirming them at a terminal.
+export function prerequisitesFor(deployment) {
+  const profile = EXPECTED_PROFILE[deployment];
+  return (PREREQUISITES[deployment] ?? []).map((name) => ({ name, guide: prerequisiteGuide(name, profile) }));
+}
+
 export function prerequisiteGuide(name, profile) {
   if (name === "metadata_agent_credential") return METADATA_CREDENTIAL_GUIDE[profile] ?? null;
   return PREREQUISITE_GUIDE[name] ?? null;
@@ -164,8 +171,9 @@ export async function preflightNonHostedSetup(options, { env = process.env } = {
   // Setup itself refuses a remote session, but only after this preflight.
   // Refuse here first, so a remote shell sends no request and never reads the
   // separate agent token file.
-  if (detectRemoteSession(env) !== null) {
-    return handoff("unsupported", "run_on_local_machine", action("run_on_customer_machine"), {
+  const environment = classifyEnvironment(env);
+  if (environment.remote) {
+    return handoff("unsupported", "run_on_local_machine", remoteSetupAction(environment, plan.origin, options), {
       profile: plan.deployment_profile, origin: plan.origin, workspaceId: plan.workspace_id,
     });
   }