metergraph-cli 0.2.2 → 0.2.4

package/src/pricing.js

@@ -0,0 +1,307 @@
+import { send } from "./transport.js";
+import { parseJsonObject } from "./http.js";
+import { validDate } from "./pricing-args.js";
+import { runReferencePricing, RATE_KEYS } from "./pricing-reference.js";
+
+const fail = (
+  outcome,
+  reason,
+  message = "Pricing could not be read. Check the reason and retry with supported inputs.",
+) => ({ outcome, reason, message });
+const text = (v) =>
+  typeof v === "string" &&
+  v.length > 0 &&
+  v.length <= 500 &&
+  !/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/u.test(v);
+const currency = (v) => typeof v === "string" && /^[A-Z]{3}$/.test(v);
+const decimal = (v) => typeof v === "string" && /^(0|[1-9]\d{0,14})(\.\d{1,16})?$/.test(v);
+const instant = (v) =>
+  typeof v === "string" &&
+  /^\d{4}-\d{2}-\d{2}T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,6})?(?:Z|\+00:00)$/.test(v) &&
+  validDate(v.slice(0, 10)) &&
+  Number.isFinite(Date.parse(v));
+const date = (v) => validDate(v) || instant(v);
+const strings = (v) => Array.isArray(v) && v.length <= 10000 && v.every(text);
+const object = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const source = (v) => {
+  if (!text(v)) return false;
+  try {
+    const u = new URL(v);
+    return u.protocol === "https:" && !u.username && !u.password;
+  } catch {
+    return false;
+  }
+};
+const units = (v) => {
+  const [a, b = ""] = v.split(".");
+  return BigInt(a) * 10n ** 16n + BigInt(b.padEnd(16, "0"));
+};
+function price(p) {
+  return (
+    object(p) &&
+    ["id", "model_id", "channel", "region"].every((k) => text(p[k])) &&
+    currency(p.currency) &&
+    date(p.effective_from) &&
+    (p.effective_to === null || (date(p.effective_to) && Date.parse(p.effective_to) > Date.parse(p.effective_from))) &&
+    source(p.source_url) &&
+    object(p.rules) &&
+    RATE_KEYS.every((k) => p[k] === null || decimal(p[k]))
+  );
+}
+export function validateModels(d) {
+  return (
+    object(d) &&
+    instant(d.as_of) &&
+    object(d.catalog) &&
+    text(d.catalog.version) &&
+    currency(d.catalog.currency) &&
+    validDate(d.catalog.pricing_verified_at) &&
+    ["formats", "providers", "channels", "regions", "service_tiers"].every((k) => strings(d[k])) &&
+    Array.isArray(d.models) &&
+    d.models.length <= 10000 &&
+    new Set(d.models.map((m) => m?.model_id)).size === d.models.length &&
+    d.models.every(
+      (m) =>
+        object(m) &&
+        text(m.model_id) &&
+        text(m.publisher) &&
+        Array.isArray(m.aliases) &&
+        m.aliases.every((a) => object(a) && ["provider", "model", "channel"].every((k) => text(a[k]))) &&
+        Array.isArray(m.prices) &&
+        m.prices.every(
+          (p) =>
+            object(p) &&
+            text(p.channel) &&
+            text(p.region) &&
+            currency(p.currency) &&
+            date(p.effective_from) &&
+            strings(p.dimensions) &&
+            strings(p.service_tiers),
+        ),
+    )
+  );
+}
+export function validatePublicResult(d, action, q, now = Date.now()) {
+  if (!object(d) || !Array.isArray(d.results) || d.results.length !== 1) return false;
+  const r = d.results[0];
+  if (
+    !object(r) ||
+    !["priced", "partial", "unpriced"].includes(r.status) ||
+    !instant(r.effective_at) ||
+    !strings(r.missing_dimensions) ||
+    new Set(r.missing_dimensions).size !== r.missing_dimensions.length
+  )
+    return false;
+  if (
+    q.at ? Date.parse(r.effective_at) !== Date.parse(q.at) : Math.abs(Date.parse(r.effective_at) - now) > 15 * 60 * 1000
+  )
+    return false;
+  if (r.status === "priced" && r.missing_dimensions.length) return false;
+  if (r.status === "unpriced") {
+    if (r.model_id !== null || r.price !== null || r.currency !== null) return false;
+  } else if (
+    !price(r.price) ||
+    r.model_id !== r.price.model_id ||
+    r.currency !== r.price.currency ||
+    (q.channel && r.price.channel !== q.channel) ||
+    (q.region && ![q.region, "global", "*"].includes(r.price.region)) ||
+    Date.parse(r.price.effective_from) > Date.parse(r.effective_at) ||
+    (r.price.effective_to !== null && Date.parse(r.price.effective_to) <= Date.parse(r.effective_at))
+  )
+    return false;
+  if (action === "cost" || action === "calculate") {
+    if (r.status === "unpriced") return r.cost === null && r.components === null;
+    if (
+      !decimal(r.cost) ||
+      !object(r.components) ||
+      Object.keys(r.components).sort().join() !== "cache_read,cache_write,input,output,request" ||
+      !Object.values(r.components).every(decimal) ||
+      Object.values(r.components).reduce((n, v) => n + units(v), 0n) !== units(r.cost)
+    )
+      return false;
+    if (["input_tokens", "output_tokens"].some((k) => !Object.hasOwn(q, k) && !r.missing_dimensions.includes(k)))
+      return false;
+  }
+  return true;
+}
+export function pricingPayload(o) {
+  const q = o.query;
+  const context = Object.fromEntries(
+    ["provider", "channel", "region"].filter((k) => q[k] !== undefined).map((k) => [k, q[k]]),
+  );
+  if (q.at) context.at = `${q.at}T00:00:00Z`;
+  if (q.batch) context.service_tier = "batch";
+  if (o.action === "lookup") return { model: q.model, context };
+  const usage = {};
+  const put = (key, value) => {
+    if (value !== undefined) usage[key] = value;
+  };
+  let trace;
+  if (o.traceFormat === "anthropic.messages") {
+    put("input_tokens", q.input_tokens);
+    put("output_tokens", q.output_tokens);
+    put("cache_read_input_tokens", q.cache_read_tokens);
+    put("cache_creation_input_tokens", q.cache_write_tokens);
+    if (q.cache_write_5m_tokens !== undefined || q.cache_write_1h_tokens !== undefined)
+      usage.cache_creation = {
+        ...(q.cache_write_5m_tokens === undefined ? {} : { ephemeral_5m_input_tokens: q.cache_write_5m_tokens }),
+        ...(q.cache_write_1h_tokens === undefined ? {} : { ephemeral_1h_input_tokens: q.cache_write_1h_tokens }),
+      };
+    trace = { model: q.model, usage };
+  } else if (o.traceFormat.startsWith("openai.")) {
+    const chat = o.traceFormat === "openai.chat_completions";
+    put(chat ? "prompt_tokens" : "input_tokens", q.input_tokens);
+    put(chat ? "completion_tokens" : "output_tokens", q.output_tokens);
+    if (q.cache_read_tokens !== undefined)
+      usage[chat ? "prompt_tokens_details" : "input_tokens_details"] = { cached_tokens: q.cache_read_tokens };
+    trace = { model: q.model, usage };
+  } else {
+    usage["gen_ai.request.model"] = q.model;
+    put("gen_ai.usage.input_tokens", q.input_tokens);
+    put("gen_ai.usage.output_tokens", q.output_tokens);
+    put("gen_ai.usage.cache_read.input_tokens", q.cache_read_tokens);
+    trace = { attributes: usage };
+  }
+  return { format: o.traceFormat, trace, context };
+}
+export async function runPricing(o) {
+  if (o.api === "reference") return runReferencePricing(o);
+  if (o.action === "history")
+    return fail(
+      "unsupported",
+      "pricing_history_unavailable",
+      "The public API documents no history endpoint. Historical charts remain available with --api reference and a loopback --url; no public history request was made.",
+    );
+  if (o.action === "market") return runPublicMarket(o);
+  const path =
+    o.action === "models"
+      ? "/v1/pricing/models"
+      : o.action === "lookup"
+        ? "/v1/pricing/lookup"
+        : "/v1/pricing/calculate";
+  const res = await send(o.origin, path, {
+    method: o.action === "models" ? "GET" : "POST",
+    json: o.action === "models" ? null : pricingPayload(o),
+    maxBytes: 1024 * 1024,
+    signal: AbortSignal.timeout(o.timeoutMs),
+    useGlobalAgent: true,
+  });
+  const failure = responseFailure(res);
+  if (failure) return failure;
+  const d = parseJsonObject(res);
+  if (o.action === "models") {
+    if (!validateModels(d)) return fail("verification_failed", "pricing_contract_mismatch");
+    const q = o.query;
+    const matches = d.models.filter(
+      (m) =>
+        (!q.model || m.model_id === q.model || m.aliases.some((a) => a.model === q.model)) &&
+        (!q.provider || m.aliases.some((a) => a.provider === q.provider && (!q.channel || a.channel === q.channel))) &&
+        (!q.channel || m.prices.some((p) => p.channel === q.channel && (!q.region || p.region === q.region))) &&
+        (!q.region || m.prices.some((p) => p.region === q.region && (!q.channel || p.channel === q.channel))),
+    );
+    return {
+      outcome: "ok",
+      data: {
+        api: "public",
+        action: o.action,
+        request: q,
+        catalog: d.catalog,
+        as_of: d.as_of,
+        formats: d.formats,
+        providers: d.providers,
+        channels: d.channels,
+        regions: d.regions,
+        service_tiers: d.service_tiers,
+        result: {
+          models: matches.slice(0, q.limit),
+          matched: matches.length,
+          total_models: d.models.length,
+          truncated: matches.length > q.limit,
+        },
+      },
+    };
+  }
+  if (!validatePublicResult(d, o.action, o.query)) return fail("verification_failed", "pricing_contract_mismatch");
+  const r = d.results[0];
+  return {
+    outcome: "ok",
+    data: {
+      api: "public",
+      action: o.action,
+      request: o.query,
+      ...(o.action === "lookup" ? {} : { trace_format: o.traceFormat }),
+      catalog: null,
+      result: r,
+    },
+  };
+}
+
+function responseFailure(res) {
+  if (res.kind === "error") return fail("connection_failed", res.reason);
+  if (res.status >= 300 && res.status < 400) return fail("redirect_rejected", "pricing_redirect_rejected");
+  if (res.status === 429) return fail("rate_limited", "pricing_rate_limited");
+  if (res.status >= 500) return fail("unhealthy", "pricing_service_unhealthy");
+  if ([401, 403, 404, 405].includes(res.status)) return fail("unsupported", "public_pricing_unavailable");
+  if (res.tooLarge) return fail("unsupported", "pricing_response_too_large");
+  if ([400, 422].includes(res.status)) return fail("invalid_input", "pricing_request_rejected");
+  if (res.status !== 200) return fail("unsupported", "pricing_response_unsupported");
+  return null;
+}
+
+async function runPublicMarket(o) {
+  if (o.query.at)
+    return fail(
+      "unsupported",
+      "market_date_unsupported",
+      "The public market board uses current discovery and lookups. Use lookup --at for one historical price; historical board coverage is unavailable.",
+    );
+  const signal = AbortSignal.timeout(o.timeoutMs);
+  const options = { signal, maxBytes: 1024 * 1024, useGlobalAgent: true };
+  const discovery = await send(o.origin, "/v1/pricing/models", options);
+  const error = responseFailure(discovery);
+  if (error) return error;
+  const d = parseJsonObject(discovery);
+  if (!validateModels(d)) return fail("verification_failed", "pricing_contract_mismatch");
+  const q = o.query;
+  const matches = d.models.filter((m) => m.prices.some((p) => p.channel === q.channel && p.region === q.region));
+  const selected = matches.slice(0, q.limit),
+    items = new Array(selected.length);
+  let next = 0,
+    failure = null;
+  const worker = async () => {
+    while (!failure && next < selected.length) {
+      const index = next++,
+        model = selected[index].model_id;
+      const request = { model, channel: q.channel, region: q.region };
+      const res = await send(o.origin, "/v1/pricing/lookup", {
+        ...options,
+        method: "POST",
+        json: { model, context: { channel: q.channel, region: q.region } },
+      });
+      const error = responseFailure(res);
+      if (error) {
+        failure = error;
+        break;
+      }
+      const result = parseJsonObject(res);
+      if (!validatePublicResult(result, "lookup", request)) {
+        failure = fail("verification_failed", "pricing_contract_mismatch");
+        break;
+      }
+      items[index] = { requested_model: model, ...result.results[0] };
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(3, selected.length) }, worker));
+  if (failure) return failure;
+  return {
+    outcome: "ok",
+    data: {
+      api: "public",
+      action: "market",
+      request: q,
+      catalog: d.catalog,
+      as_of: d.as_of,
+      result: { items, matched: matches.length, truncated: matches.length > items.length, history_available: false },
+    },
+  };
+}

package/src/read-contract.js

@@ -1,4 +1,4 @@
-import { normalizeUuid } from "./auth-oauth.js";
+import { credentialAccess, normalizeUuid } from "./auth-oauth.js";
 import {
   AGENT_CONTRACT_VERSION,
   MAX_CURSOR_LENGTH,
@@ -16,8 +16,9 @@ import { traceLink } from "./trace-contract.js";
 //   { ok: true, value } or { ok: false, outcome, reason }
 // with fixed tokens. notices is a Set that collects fixed notice tokens.
 
-// Every capability name the contract defines, in its order. The last three
-// read content or replay and are never available to a Metadata grant.
+// Every capability name the contract defines. Content, replay and start
+// entries are never available to a Metadata grant; a Debug credential with
+// workflow permissions may be offered content and starts.
 export const CAPABILITY_NAMES = Object.freeze([
   "workspace_context",
   "capability_discovery",
@@ -30,11 +31,16 @@ export const CAPABILITY_NAMES = Object.freeze([
   "reports",
   "report_detail",
   "report_evidence",
+  "experiments",
+  "experiment_estimate",
+  "experiment",
+  "experiment_cases",
+  "experiment_start",
   "trace_content",
   "trace_replay",
 ]);
 const PRIVACY_CLASSES = Object.freeze(["metadata", "content", "replay"]);
-const SCOPES = Object.freeze(["agent:metadata", "agent:read", "agent:replay"]);
+const SCOPES = Object.freeze(["agent:metadata", "agent:read", "agent:replay", "agent:analysis-run"]);
 
 const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:/+-]{0,127}$/;
 const IDENT = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
@@ -1106,6 +1112,33 @@ export function combinePages(pages) {
   };
 }
 
+const SLUG = /^[a-z0-9][a-z0-9-]{1,62}$/;
+const MAX_WORKSPACE_NAME = 200;
+
+// A workspace document's slug and name, each kept only when it is safe to
+// print (a well-formed slug; a name with no control or bidirectional
+// characters), else null. This is how output names a workspace: never by ID.
+export function workspaceLabel(workspace) {
+  const slug = typeof workspace?.slug === "string" && SLUG.test(workspace.slug) ? workspace.slug : null;
+  const raw = workspace?.name;
+  const name = typeof raw === "string" && raw.trim() !== "" && raw.length <= MAX_WORKSPACE_NAME && !hasUnsafeText(raw)
+    ? raw : null;
+  return { slug, name };
+}
+
+// Whether a workspace document is the one a person named with --workspace.
+// Slugs are unique, names are not, and anyone who owns a workspace chooses
+// its name, including a workspace a person was invited to. So the match is
+// strict, for sign in and for every credential pin: text shaped like a slug
+// matches only the slug, and other text only the exact name, ignoring case.
+export function workspacePinned(workspace, text) {
+  const { slug, name } = workspaceLabel(workspace);
+  const wanted = text.trim().toLowerCase();
+  if (SLUG.test(wanted)) return slug === wanted;
+  return name !== null && name.trim().toLowerCase() === wanted;
+}
+
+
 // GET /v1/agent/workspace, already checked by checkWorkspace during the
 // session. Returns the approved workspace fields only.
 export function workspaceContext(body, ctx, notices) {
@@ -1123,7 +1156,8 @@ export function workspaceContext(body, ctx, notices) {
       throw new Invalid("verification_failed", "content_access_granted");
     }
     const scopes = body.access?.scopes;
-    if (!Array.isArray(scopes) || scopes.length !== 1 || scopes[0] !== METADATA_SCOPE) {
+    const access = credentialAccess(scopes);
+    if (access === null || access !== (ctx.access ?? "metadata")) {
       throw new Invalid("verification_failed", "scope_mismatch");
     }
     return {
@@ -1136,12 +1170,15 @@ export function workspaceContext(body, ctx, notices) {
       },
       retention: { metadata_days: body.retention.metadata_days },
       content: { captured: body.content.captured, included: false },
-      access: { scopes: [METADATA_SCOPE] },
+      access: { scopes: [...scopes].sort() },
     };
   });
 }
 
-function capabilityEntry(entry, reason) {
+// access is the credential's: a Metadata credential is never offered a
+// sensitive capability; a Debug credential may be, and read commands still
+// never use one.
+function capabilityEntry(entry, reason, access = "metadata") {
   if (
     !isObject(entry) ||
     typeof entry.available !== "boolean" ||
@@ -1161,8 +1198,10 @@ function capabilityEntry(entry, reason) {
     entry.privacy_class === "metadata" &&
     entry.required_scope === METADATA_SCOPE;
   // checkCapabilities already refuses this; it is checked again here so a
-  // summary can never show a sensitive capability as available.
-  if (!metadataOnly && entry.available) throw new Invalid("verification_failed", "content_access_granted");
+  // summary can never show a sensitive capability as available to Metadata.
+  if (!metadataOnly && entry.available && access === "metadata") {
+    throw new Invalid("verification_failed", "content_access_granted");
+  }
   return {
     available: entry.available,
     content: entry.content,
@@ -1189,7 +1228,7 @@ export function capabilitySummary(body, ctx, notices) {
     if (!isObject(body.agent)) throw new Invalid("verification_failed", reason);
     const agent = {};
     for (const name of CAPABILITY_NAMES) {
-      agent[name] = Object.hasOwn(body.agent, name) ? capabilityEntry(body.agent[name], reason) : null;
+      agent[name] = Object.hasOwn(body.agent, name) ? capabilityEntry(body.agent[name], reason, ctx.access) : null;
     }
     if (Object.keys(body.agent).some((name) => !CAPABILITY_NAMES.includes(name))) {
       notices.add("unrecognized_capabilities_ignored");
@@ -1547,3 +1586,18 @@ function checkFilters(body, rows, request) {
     }
   }
 }
+
+// Shared with the experiments validators (experiments-contract.js), which
+// hold their documents to the same rules.
+export {
+  Invalid,
+  displayText,
+  isAmount,
+  isCount,
+  isObject,
+  isTimestamp,
+  isToken,
+  provenance,
+  rowObject,
+  run,
+};

package/src/read-output.js

@@ -1,5 +1,6 @@
+import { WORKFLOW_PERMISSIONS } from "./constants.js";
 import { authMessage } from "./output.js";
-import { PLAIN, fields, headline, paragraph, render, steps, toneFor } from "./style.js";
+import { PLAIN, fields, headline, paragraph, render, steps, toneFor, workspaceShown } from "./style.js";
 
 // Fixed text for read command reasons and notices. Reasons shared with sign
 // in and doctor fall back to their wording. Nothing here contains a value from
@@ -7,18 +8,18 @@ import { PLAIN, fields, headline, paragraph, render, steps, toneFor } from "./st
 
 const READ_MESSAGES = {
   not_signed_in:
-    'This project is not signed in and no Metadata key was given. Run "metergraph login --runtime local" first, ' +
-    "or, where browser sign in cannot finish, give the CLI a coding-agent key with Metadata access in " +
-    "METERGRAPH_AGENT_TOKEN.",
+    'This project is not signed in and no coding-agent key was given. Run "metergraph login --runtime local" first, ' +
+    "or, where browser sign in cannot finish, give the CLI a coding-agent key with the Metadata or Debug role " +
+    "in METERGRAPH_AGENT_TOKEN.",
   agent_key_rejected:
-    "The service refused the Metadata key: it is unknown, expired or revoked. Nothing was read.",
+    "The service refused the coding-agent key: it is unknown, expired or revoked. Nothing was read.",
   agent_key_insufficient_scope:
     "The key is valid but lacks Metadata access to this workspace, for example because it is an ingest key. " +
     "No broader access was requested. Nothing was read.",
   agent_token_malformed:
     "METERGRAPH_AGENT_TOKEN does not hold exactly one key with no label, spaces or extra lines. Its value is not " +
     "shown. Nothing was sent.",
-  agent_token_missing: "No Metadata key was found. Nothing was sent.",
+  agent_token_missing: "No coding-agent key was found. Nothing was sent.",
   metergraph_url_invalid:
     "METERGRAPH_URL is not a bare https origin, or an http origin on localhost. Its value is not shown. Nothing was sent.",
   bound_to_other_origin:
@@ -28,13 +29,14 @@ const READ_MESSAGES = {
     "This project's binding names a non-hosted origin, and a key is never sent to an origin taken only from a " +
     "project file. Set METERGRAPH_URL or pass --url with the same origin to confirm it. Nothing was sent.",
   scope_mismatch:
-    "The credential is not limited to exactly the Metadata scope, so it was not used. The CLI never uses broader access.",
+    "The credential has Replay access or a scope this CLI does not use, so it was not used. Use a credential with " +
+    "the Metadata or Debug role.",
   content_access_granted:
-    "The credential would allow content, replay or provider access, so it was not used. The CLI never uses broader access.",
+    "The service offered content, replay or provider access to a Metadata credential, so it was not used.",
   platform_credential_handoff:
     "--agent-token-file cannot be checked for privacy on this platform. Use METERGRAPH_AGENT_TOKEN instead.",
   capability_unavailable:
-    "The service does not offer this read to the project's Metadata grant. No data was read and no broader access was requested.",
+    "The service does not offer this read to this credential. No data was read and no broader access was requested.",
   exceeds_service_bounds:
     "The requested --days or --limit is larger than the service allows. It was not reduced automatically. No data was read.",
   insufficient_scope: "The service refused this read because the grant lacks a required scope. No broader scope was requested.",
@@ -279,7 +281,7 @@ export function readText(result, message, style = PLAIN) {
     statusRows(data, rows);
     lines.push(...fields(style, rows));
   } else {
-    rows.push(["Workspace", data.workspace?.id ?? null]);
+    rows.push(["Workspace", workspaceShown(data.workspace)]);
     if (result.ok) {
       const body = [];
       resultLines(result.command, data.result, body);
@@ -325,16 +327,30 @@ export function readText(result, message, style = PLAIN) {
       ["Connection guide", handoff ? next.url : null],
     ]));
   }
+  const access = result.command === "status" && result.ok ? data.access : null;
+  const step = access && !allPermissions(access) && access.permissions_offered !== false
+    ? permissionsStep(data.deployment_profile)
+    : null;
+  if (step !== null) lines.push("", ...steps(style, [["", `${PERMISSIONS_NEEDED} ${step}`]]));
   return render(lines);
 }
 
+// The verified workspace by name and slug, and whether it is the bound one.
+function statusWorkspace(workspace) {
+  const shown = workspaceShown(workspace);
+  if (workspace.actual === null) return workspace.intended === null ? "none" : "bound, not verified";
+  const name = shown ?? "verified";
+  if (workspace.match === false) return `${name}, which is not the workspace this project is bound to`;
+  return workspace.match === true ? `${name}, the bound workspace` : name;
+}
+
 function statusRows(data, rows) {
   rows.push(
     ["Configured", data.configured ? "yes" : "no"],
-    ["Credential", { oauth_grant: "saved sign in", agent_key: "Metadata key" }[data.credential] ?? "none"],
+    ["Credential", { oauth_grant: "saved sign in", agent_key: "coding-agent key" }[data.credential] ?? "none"],
     ["Reachable", yesNo(data.reachable)],
     ["Authenticated", data.authenticated ? "yes, verified by the service" : "no"],
-    ["Workspace", `bound ${show(data.workspace.intended)}, verified ${show(data.workspace.actual)}`],
+    ["Workspace", statusWorkspace(data.workspace)],
     ["Deployment profile", `bound ${show(data.deployment_profile)}, reported by the service: ${
       data.deployment_profile_verified === true
         ? "same"
@@ -348,12 +364,49 @@ function statusRows(data, rows) {
     const flag = (name) => yesNo(data.capabilities[name]);
     rows.push(
       ["Metadata reads", `usage ${flag("usage")}, routes ${flag("routes")}, traces ${flag("trace_metadata")}`],
-      ["Content and replay", "not available to this grant"],
+      ["Content", data.content_access
+        ? "available to this credential; the read commands never request it"
+        : "not available to this credential"],
     );
   }
+  if (data.access) rows.push(["Role", ROLE_LABELS[data.access.role] ?? "none"], ["Permissions", permissionsText(data.access)]);
   rows.push(["Application traffic verified", "no"]);
 }
 
+// The role and permission labels the Keys and consent pages use.
+const ROLE_LABELS = { metadata: "Metadata", debug: "Debug" };
+
+const PERMISSIONS_NEEDED =
+  "Writing and testing evaluations and starting analyses need the Debug role with Allow evaluation writes, " +
+  "Allow evaluation previews and Allow analysis starts.";
+
+const allPermissions = (access) =>
+  access.role === "debug" && WORKFLOW_PERMISSIONS.every(({ field }) => access.permissions[field] === true);
+
+function permissionsText(access) {
+  if (access.permissions_offered === false) return "not offered by this deployment";
+  const granted = WORKFLOW_PERMISSIONS.filter(({ field }) => access.permissions[field] === true);
+  return granted.length > 0 ? granted.map(({ label }) => label).join(", ") : "none";
+}
+
+// How a person gives this agent Debug with all three permissions, by
+// deployment. Fixed text: no value from the service is printed.
+export function permissionsStep(profile) {
+  if (profile === "local") {
+    return "From the bundle directory, a workspace owner runs ./bin/agent-key create --role debug " +
+      "--allow-evaluation-writes --allow-evaluation-previews --allow-analysis-starts " +
+      "--write-to ~/.config/metergraph/agent.env, then loads that file in the shell that starts the agent.";
+  }
+  if (profile === "managed") {
+    return 'Run "metergraph login --runtime local --role debug --allow-evaluation-writes ' +
+      '--allow-evaluation-previews --allow-analysis-starts"; a workspace owner approves it in the browser. ' +
+      'Or a workspace owner creates a coding-agent key on the Keys page, choosing "Debug with all three ' +
+      'permissions" under Access, saved as METERGRAPH_AGENT_TOKEN in a private file outside the project. ' +
+      "Do not paste a key into chat.";
+  }
+  return null;
+}
+
 function resultLines(command, report, lines) {
   if (command === "context") {
     const { workspace } = report;