metergraph-cli 0.2.2 → 0.2.3

package/README.md

@@ -53,7 +53,7 @@ npx --yes metergraph-cli@latest traces --limit 20   # one page of trace metadata
 ```
 
 To install it globally instead, run `npm install -g metergraph-cli@latest`. The command is
-`metergraph`. Pin an exact version, such as `metergraph-cli@0.2.2`, when a
+`metergraph`. Pin an exact version, such as `metergraph-cli@0.2.3`, when a
 script must not change with the `latest` tag. Previews use the `next` tag.
 
 ## Requirements
@@ -109,7 +109,11 @@ The CLI is built to be run by Codex, Claude Code and Cursor as well as by people
   `schema_version`, `command`, `ok`, `outcome`, `exit_code`, `data` and `error`.
   Failures carry a fixed `error.reason` and, where useful, a `data.next_action` that
   tells the agent what to do next.
-- **No hidden prompts.** No command reads stdin or asks a question. `--no-browser`
+- **No hidden prompts.** Only `setup` asks questions, and only a person at a terminal:
+  with stdin and stdout both terminals, no `--json` and no `CI`, it asks for what its
+  flags leave out and prints the full command before running it. Otherwise no command
+  reads stdin or asks a question, so an agent or script gets the same flag errors as
+  before. `--no-browser`
   prints the sign in URL for a person to open instead of launching a browser. With
   `--json`, a step that needs approval exits within seconds with 18
   `action_required` and `data.next_action` set to
@@ -135,6 +139,8 @@ Suggested `AGENTS.md` or `CLAUDE.md` lines for a project that uses Metergraph:
 
 | Command | What it does | Network |
 | --- | --- | --- |
+| `pricing models`, `pricing lookup`, `pricing calculate` (`cost` alias) | Discover models, look up rates and calculate costs through the public API without sign in | Yes |
+| `pricing market`, `pricing history` | Current public market board; historical terminal/HTML charts require the local reference adapter ([guide](docs/pricing.md)) | Yes |
 | `setup` | Sign in, choose a workspace, write the ingest key to `.env`, record the repository, install the skill | Yes |
 | `verify` | Confirm that one exact trace, by trace ID or request ID, reached the workspace | Yes |
 | `usage` | Daily calls, errors, cost, tokens and latency per route, or cost grouped by provider, model, route or UTC day with exact filters, rankings and a prior-period comparison; filtered by exact metadata or grouped by one metadata key | Yes |
@@ -143,6 +149,7 @@ Suggested `AGENTS.md` or `CLAUDE.md` lines for a project that uses Metergraph:
 | `status` | Whether the project is signed in, and to which workspace | Yes |
 | `context` | Workspace details and retention | Yes |
 | `capabilities` | What the workspace makes available to this project | Yes |
+| `experiments list`, `estimate`, `start`, `get` | Replay a workload's recent production calls on 1 to 3 other models or settings: price it, start it, poll it and read cost, latency and output statistics per treatment next to production | Yes |
 | `login`, `logout` | Sign a project in or out without the rest of `setup` | Yes |
 | `doctor` | Check that a service is reachable, healthy and supported, without credentials | Yes |
 | `skill install`, `skill update` | Install or update the Metergraph skill for one agent | No |
@@ -152,10 +159,37 @@ Suggested `AGENTS.md` or `CLAUDE.md` lines for a project that uses Metergraph:
 [CLI reference](https://github.com/metergraph/cli/blob/main/docs/reference.md) covers every option, what each command reads and
 writes, and full JSON examples.
 
+## Public pricing preview
+
+```sh
+metergraph pricing models --limit 10
+metergraph pricing lookup --model gpt-5 --provider openai --region global --json
+metergraph pricing calculate --model claude-sonnet-5 --provider anthropic \
+  --input-tokens 1000 --cache-read-tokens 800 --output-tokens 200
+metergraph pricing market --channel openai-api --limit 5
+```
+
+These commands use the public Pricing API without an account or workspace.
+`cost` is an alias for `calculate`. Inspect status and missing dimensions: an HTTP
+success may still be partial or unpriced. The current market board uses discovery
+plus bounded lookups; it does not invent historical prices or returns.
+
+The stock-style history visualization is preserved in explicit local reference mode:
+
+```sh
+metergraph pricing history --model openai/gpt-5.6-terra --channel openai-api \
+  --api reference --url http://127.0.0.1:8765 --format html > history.html
+```
+
+See [the pricing guide](docs/pricing.md) for the API contract, input semantics and
+local adapter. The public service does not document a history endpoint. This is
+an exploratory preview; supplier pricing coverage and storage claims are not
+independently verified by these command tests.
+
 ## Exit codes
 
 Exit codes are stable. Changing one is a breaking change. Codes 10 to 18 are not in
-`0.1.0`.
+`0.1.0`, and codes 19 and 20 are not in `0.2.2` or earlier.
 
 | Code | Outcome | Meaning |
 | --- | --- | --- |
@@ -178,6 +212,8 @@ Exit codes are stable. Changing one is a breaking change. Codes 10 to 18 are not
 | 16 | `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. |
 | 17 | `cancelled` | A read command was interrupted before it finished. Read commands never change workspace configuration or telemetry. |
 | 18 | `action_required` | A person must act before the command can finish; `data.next_action` says what to do. `login` and `setup` with `--json --no-browser` exit with this as soon as an approval URL exists (`next_action.kind: "open_url"`), while a background process waits for the approval until `--timeout-ms`. After approval, run the same command again to continue. |
+| 19 | `refused` | The service refused an experiment for a stated reason, such as its budget, the daily cap, experiments already running or a model it cannot price; `data.refusal` says which. Nothing was started. |
+| 20 | `unconfirmed` | An `experiments start` request reached the service but its result was not confirmed (a timeout, a dropped connection, a server error or an answer that does not match the contract), so an experiment may exist and may run. List experiments before starting again; each start creates one. |
 
 ## Security and privacy
 
@@ -185,7 +221,11 @@ Exit codes are stable. Changing one is a breaking change. Codes 10 to 18 are not
   only to the Metergraph origin you point it at.
 - **Least access.** Sign in grants only the Metadata scope, `agent:metadata`. The CLI
   never requests Debug or Replay access, never falls back to broader access, and never
-  reads retained prompts, responses or other content. It calls no model provider.
+  reads retained prompts, responses or other content. It calls no model provider. The one
+  exception is `experiments start`: it uses a coding-agent key a workspace owner created
+  with exactly Debug access and Allow analysis starts, refuses a key with any other scope,
+  and sends it only with that one start request. The service then replays the sampled calls on the
+  chosen providers within its own budget. Every other command refuses such a key.
 - **Credentials.** The sign in grant is stored per user in `~/.config/metergraph`
   (`AppData\Roaming\Metergraph` on Windows), as owner-only files on Linux and macOS and
   encrypted with DPAPI on Windows. The ingest key goes only into the project's private
@@ -194,7 +234,11 @@ Exit codes are stable. Changing one is a breaking change. Codes 10 to 18 are not
 - **Files it writes in your project:** `.env` (from `setup`), the skill file, and
   secret-free state under `.metergraph/` that is safe to commit. The skill installer
   never replaces a file it did not write and has no force option.
-- **Network.** Only `GET` requests to fixed paths for reads, no redirects followed,
+- **Public pricing.** Pricing reads send no credentials and return public catalog data.
+  `--format html` emits a standalone document; it does not launch a browser.
+- **Network.** Workspace reads use `GET`; experiments estimate and start use `POST`.
+  Public pricing lookup/calculation use unauthenticated `POST` with metadata-only
+  inputs. Fixed paths, no redirects followed,
   bounded response sizes and fixed timeouts. Mistyped arguments are never echoed, since
   they may hold a secret. `--help`, `--version` and `skill` make no network requests.
 

package/bin/metergraph.js

@@ -7,5 +7,5 @@ import { main } from "../src/cli.js";
 process.stdout.on("error", () => {});
 
 const argv = process.argv.slice(2);
-const io = { stdout: process.stdout, stderr: process.stderr };
+const io = { stdout: process.stdout, stderr: process.stderr, stdin: process.stdin };
 process.exitCode = handsOff(argv) ? await handOff(argv, io) : await main(argv, io);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metergraph-cli",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Metergraph command line tool with a read-only connection probe, a project skill installer, Metadata-only sign in and bounded workspace Metadata reads",
   "type": "module",
   "bin": {

package/src/agent-key.js

@@ -84,7 +84,10 @@ export function keyTarget({ binding, options, env, originConfirmed = false }) {
 //   { ok: false, outcome, reason }
 // verifiedProfile is the profile the caller already read from GET
 // /v1/deployment under the same deadline, or null to read it here.
-export async function keySession({ target, source, env, signal, verifiedProfile = null }) {
+// access is "metadata" for the read commands, or "experiment_start" for
+// experiments start, which needs Debug access and the start grant instead
+// (verifyContext) and uses the key for that one request.
+export async function keySession({ target, source, env, signal, verifiedProfile = null, access = "metadata" }) {
   // A key already in the environment is checked for shape before any
   // request; a key file is opened only once the origin has proven itself.
   let key = source.kind === "env" ? readAgentKey(source, env) : null;
@@ -108,7 +111,7 @@ export async function keySession({ target, source, env, signal, verifiedProfile
   const verified = await verifyContext(
     target.origin,
     token,
-    { profile, workspaceId: target.workspaceId, anyWorkspace: target.workspaceId === null },
+    { profile, workspaceId: target.workspaceId, anyWorkspace: target.workspaceId === null, access },
     signal,
   );
   if (!verified.ok) {
@@ -125,7 +128,7 @@ export async function keySession({ target, source, env, signal, verifiedProfile
       origin: target.origin,
       workspaceId: verified.workspaceId,
       profile,
-      scopes: [METADATA_SCOPE],
+      scopes: access === "metadata" ? [METADATA_SCOPE] : verified.scopes,
       accessToken: token,
     },
     documents: verified.documents,

package/src/args.js

@@ -1,7 +1,16 @@
+import { parsePricing, PRICING_ACTIONS, PRICING_OPTIONS } from "./pricing-args.js";
 import { parseRepository } from "./repository-identity.js";
 import {
   DEFAULT_ORIGIN,
   DEFAULT_TIMEOUT_MS,
+  EXPERIMENT_LAST_N,
+  EXPERIMENT_LIST_DEFAULT_LIMIT,
+  EXPERIMENT_LIST_MAX_LIMIT,
+  EXPERIMENT_MAX_TOKENS,
+  EXPERIMENT_MAX_TRACKED_FIELDS,
+  EXPERIMENT_MAX_TREATMENTS,
+  EXPERIMENT_REASONING_EFFORTS,
+  EXPERIMENT_TEXT_LIMITS,
   HANDOFF_SKILL_CLIENTS,
   HANDOFF_SKILL_RUNTIMES,
   HANDOFF_LOGIN_RUNTIMES,
@@ -35,8 +44,9 @@ import { parseOrigin } from "./origin.js";
 import { groupedRequest, hasUnsafeText, isCursor, isSafeFilter, readQuery } from "./read-contract.js";
 
 export const READ_COMMANDS = Object.freeze(["status", "context", "capabilities", "usage", "routes", "traces"]);
-const COMMANDS = new Set(["doctor", "help", "skill", "skills", "login", "logout", "setup", "verify", ...READ_COMMANDS]);
-const HELP_TOPICS = new Set(["doctor", "skill", "skills", "login", "logout", "setup", "verify", ...READ_COMMANDS]);
+const COMMANDS = new Set(["pricing", "doctor", "help", "skill", "skills", "login", "logout", "setup", "verify", "experiments", ...READ_COMMANDS]);
+const HELP_TOPICS = new Set(["pricing", "doctor", "skill", "skills", "login", "logout", "setup", "verify", "experiments", ...READ_COMMANDS]);
+export const EXPERIMENT_ACTIONS = Object.freeze(["list", "estimate", "start", "get"]);
 const SKILL_ACTIONS = new Set(["install", "update"]);
 const SKILLS_ACTIONS = new Set(["install", "update", "list"]);
 const READ_BASE = ["--project", "--config-dir", "--timeout-ms"];
@@ -45,6 +55,7 @@ const READ_BASE = ["--project", "--config-dir", "--timeout-ms"];
 // never an argument.
 const READ_KEY = ["--url", "--workspace", "--agent-token-file"];
 const OPTIONS = {
+  pricing: new Set(PRICING_OPTIONS),
   doctor: new Set(["--url", "--timeout-ms"]),
   skill: new Set(["--client", "--runtime", "--project"]),
   skills: new Set(["--client", "--runtime", "--project"]),
@@ -63,6 +74,16 @@ const OPTIONS = {
     ...READ_BASE, ...READ_KEY, "--days", "--limit", "--route", "--status", "--cursor", "--metadata", "--metadata-json",
   ]),
   verify: new Set([...READ_BASE, "--trace-id", "--request-id", "--since", "--until", "--source", "--days", "--poll-ms", "--max-attempts"]),
+  experiments: new Set([
+    ...READ_BASE, ...READ_KEY, "--workload", "--limit", "--treatment", "--last-n", "--sample-model", "--track", "--id",
+  ]),
+};
+// Which experiments options each action takes, beyond READ_BASE and READ_KEY.
+const EXPERIMENT_OPTIONS = {
+  list: new Set(["--workload", "--limit"]),
+  estimate: new Set(["--workload", "--treatment", "--last-n", "--sample-model", "--track"]),
+  start: new Set(["--workload", "--treatment", "--last-n", "--sample-model", "--track"]),
+  get: new Set(["--id"]),
 };
 // Requests the read commands recognize and refuse, so a script gets an
 // explicit unsupported result instead of an unknown argument or, worse, a
@@ -96,6 +117,7 @@ const REFUSED_MESSAGES = {
 };
 // Options that may be given more than once; their values are kept in order.
 const REPEATABLE = new Set(["--metadata"]);
+const EXPERIMENT_REPEATABLE = new Set(["--treatment", "--track"]);
 // usage takes several values for each of its exact-match filters.
 const USAGE_REPEATABLE = new Set(["--route", "--provider", "--model", "--environment"]);
 // usage reads a time range and environments itself, through grouped usage.
@@ -106,6 +128,7 @@ const USAGE_GROUPED = [
 ];
 // Options that take no value.
 const FLAGS = {
+  pricing: new Set(["--batch"]),
   login: new Set(["--signup", "--no-browser", "--reconnect"]),
   setup: new Set(["--no-browser", "--repair", "--signup", "--reconnect", "--skip-skill", "--confirm-prerequisites", "--no-repository"]),
   verify: new Set(["--open", "--no-browser"]),
@@ -147,7 +170,7 @@ export function parseArgs(argv) {
 
   const fail = (code, message, outcome = "invalid_input") => ({
     ok: false,
-    command: (command === "skill" || command === "skills") && action !== null
+    command: (command === "skill" || command === "skills" || command === "experiments") && action !== null
       ? `${command} ${action}`
       : command ?? (version ? "version" : null),
     json,
@@ -174,6 +197,10 @@ export function parseArgs(argv) {
       topic = arg;
       continue;
     }
+    if (command === "pricing" && action === null && PRICING_ACTIONS.includes(arg)) {
+      action = arg;
+      continue;
+    }
     if (command === "skill" && action === null && SKILL_ACTIONS.has(arg)) {
       action = arg;
       continue;
@@ -182,6 +209,10 @@ export function parseArgs(argv) {
       action = arg;
       continue;
     }
+    if (command === "experiments" && action === null && EXPERIMENT_ACTIONS.includes(arg)) {
+      action = arg;
+      continue;
+    }
 
     if (READ_COMMANDS.includes(command)) {
       const equals = arg.indexOf("=");
@@ -212,7 +243,8 @@ export function parseArgs(argv) {
         if (value === undefined) {
           return fail("missing_value", `${name} requires a value.`);
         }
-        if (REPEATABLE.has(name) || (command === "usage" && USAGE_REPEATABLE.has(name))) {
+        if (REPEATABLE.has(name) || (command === "usage" && USAGE_REPEATABLE.has(name)) ||
+            (command === "experiments" && EXPERIMENT_REPEATABLE.has(name))) {
           values[name] = [...(values[name] ?? []), value];
           continue;
         }
@@ -242,6 +274,12 @@ export function parseArgs(argv) {
         `Unknown skills subcommand at argument ${position}. Use install, update or list.`,
       );
     }
+    if (command === "experiments" && action === null && !arg.startsWith("-")) {
+      return fail(
+        "unknown_subcommand",
+        `Unknown experiments subcommand at argument ${position}. Use list, estimate, start or get.`,
+      );
+    }
     return fail(
       "unknown_argument",
       `Unrecognized argument at position ${position}. Run "metergraph --help" for usage.`,
@@ -252,11 +290,13 @@ export function parseArgs(argv) {
   if (command === null || command === "help") {
     return { ok: true, command: "help", topic, json };
   }
+  if (command === "pricing") return parsePricing(action, values, flags, json, fail);
   if (command === "skill") return parseSkill(action, values, json, fail);
   if (command === "skills") return parseSkills(action, values, json, fail);
   if (command === "login") return parseLogin(values, flags, json, fail);
   if (command === "setup") return parseSetup(values, flags, json, fail);
   if (command === "verify") return parseVerify(values, flags, json, fail);
+  if (command === "experiments") return parseExperiments(action, values, json, fail);
   if (READ_COMMANDS.includes(command)) return parseRead(command, values, flags, json, fail);
   if (command === "logout") {
     const paths = parsePaths(values, fail);
@@ -280,6 +320,177 @@ export function parseArgs(argv) {
   return { ok: true, command: "doctor", origin, timeoutMs, json };
 }
 
+// --url, --workspace and --agent-token-file, shared by the read commands and
+// experiments: { ok: true, origin, workspace, agentTokenFile } or a failure.
+function parseKeyTarget(values, fail) {
+  let origin = null;
+  if (values["--url"] !== undefined) {
+    origin = parseOrigin(values["--url"]);
+    if (origin === null) return fail("invalid_url", INVALID_URL);
+  }
+  const rawWorkspace = values["--workspace"];
+  if (rawWorkspace !== undefined && !UUID.test(rawWorkspace)) {
+    return fail("invalid_workspace", "--workspace must be a workspace ID in UUID form.");
+  }
+  const agentTokenFile = values["--agent-token-file"] ?? null;
+  if (agentTokenFile !== null && (agentTokenFile === "" || agentTokenFile.includes("\0"))) {
+    return fail("invalid_agent_token_file", "--agent-token-file must name a private absolute file.");
+  }
+  return {
+    ok: true,
+    origin,
+    workspace: rawWorkspace === undefined ? null : rawWorkspace.toLowerCase(),
+    agentTokenFile,
+  };
+}
+
+// experiments list | estimate | start | get. estimate and start take the same
+// request, so an agent starts exactly what it priced: the workload, 1 to 3
+// --treatment PROVIDER/MODEL[,label=..][,temperature=..][,max_tokens=..]
+// [,reasoning_effort=..], and optionally --last-n, --sample-model and up to ten
+// --track JSON paths. The service validates every request in full; these
+// checks only refuse what it would refuse before anything is sent.
+function parseExperiments(action, values, json, fail) {
+  if (action === null) {
+    return fail(
+      "missing_subcommand",
+      'experiments requires a subcommand: list, estimate, start or get. Run "metergraph help experiments" for usage.',
+    );
+  }
+  for (const name of Object.keys(values)) {
+    if (!READ_BASE.includes(name) && !READ_KEY.includes(name) && !EXPERIMENT_OPTIONS[action].has(name)) {
+      return fail("unknown_argument", `experiments ${action} does not take ${name}. Run "metergraph help experiments" for usage.`);
+    }
+  }
+  const paths = parsePaths(values, fail);
+  if (!paths.ok) return paths;
+  const rawTimeout = values["--timeout-ms"];
+  const timeoutMs = rawTimeout === undefined
+    ? READ_DEFAULT_TIMEOUT_MS
+    : parseTimeout(rawTimeout, READ_MIN_TIMEOUT_MS, READ_MAX_TIMEOUT_MS);
+  if (timeoutMs === null) {
+    return fail("invalid_timeout", `--timeout-ms must be a whole number from ${READ_MIN_TIMEOUT_MS} to ${READ_MAX_TIMEOUT_MS}.`);
+  }
+  const target = parseKeyTarget(values, fail);
+  if (!target.ok) return target;
+  delete target.ok;
+  const parsed = {
+    ok: true, command: "experiments", action, ...target, project: paths.project, configDir: paths.configDir,
+    timeoutMs, json, experiment: { id: null, workloadId: null, limit: null, request: null },
+  };
+  const workload = values["--workload"];
+  if (workload !== undefined && !experimentText(workload, EXPERIMENT_TEXT_LIMITS.workload)) {
+    return fail("invalid_workload", `--workload must be 1 to ${EXPERIMENT_TEXT_LIMITS.workload} characters without control characters.`);
+  }
+  if (action === "get") {
+    const id = values["--id"];
+    if (id === undefined || !UUID.test(id)) return fail("invalid_experiment_id", "--id must be an experiment ID in UUID form.");
+    parsed.experiment.id = id.toLowerCase();
+    return parsed;
+  }
+  if (action === "list") {
+    const limit = values["--limit"] === undefined
+      ? EXPERIMENT_LIST_DEFAULT_LIMIT
+      : parseBounded(values["--limit"], 1, EXPERIMENT_LIST_MAX_LIMIT);
+    if (limit === null) return fail("invalid_limit", `--limit must be a whole number from 1 to ${EXPERIMENT_LIST_MAX_LIMIT}.`);
+    // The exact query list sends, so an over-long one fails here and not after sign in.
+    const query = new URLSearchParams({ ...(workload === undefined ? {} : { workload_id: workload }), limit: String(limit) });
+    if (query.toString().length > MAX_QUERY_LENGTH) {
+      return fail("query_too_long", "--workload is too long to send in one request once encoded.");
+    }
+    parsed.experiment.workloadId = workload ?? null;
+    parsed.experiment.limit = limit;
+    return parsed;
+  }
+  if (workload === undefined) return fail("missing_workload", "--workload is required: the workload (route) whose calls to replay.");
+  const specs = values["--treatment"] ?? [];
+  if (specs.length < 1 || specs.length > EXPERIMENT_MAX_TREATMENTS) {
+    return fail("invalid_treatments", `Give 1 to ${EXPERIMENT_MAX_TREATMENTS} --treatment values.`);
+  }
+  const treatments = [];
+  for (const spec of specs) {
+    const treatment = parseTreatment(spec);
+    if (treatment === null) {
+      return fail(
+        "invalid_treatment",
+        "--treatment must be PROVIDER/MODEL, optionally followed by ,label=NAME ,temperature=0..2 " +
+          `,max_tokens=1..${EXPERIMENT_MAX_TOKENS} or ,reasoning_effort=${EXPERIMENT_REASONING_EFFORTS.join("|")}.`,
+      );
+    }
+    treatments.push(treatment);
+  }
+  const labels = treatments.map((treatment) => treatment.label).filter((label) => label !== undefined);
+  if (new Set(labels.map((label) => label.toLowerCase())).size !== labels.length ||
+      labels.some((label) => label.toLowerCase() === "control")) {
+    return fail("invalid_treatments", 'Treatment labels must be unique and cannot be "control".');
+  }
+  const sample = { last_n: EXPERIMENT_LAST_N.default };
+  if (values["--last-n"] !== undefined) {
+    sample.last_n = parseBounded(values["--last-n"], EXPERIMENT_LAST_N.min, EXPERIMENT_LAST_N.max);
+    if (sample.last_n === null) {
+      return fail("invalid_last_n", `--last-n must be a whole number from ${EXPERIMENT_LAST_N.min} to ${EXPERIMENT_LAST_N.max}.`);
+    }
+  }
+  if (values["--sample-model"] !== undefined) {
+    if (!experimentText(values["--sample-model"], EXPERIMENT_TEXT_LIMITS.model)) {
+      return fail("invalid_sample_model", `--sample-model must be 1 to ${EXPERIMENT_TEXT_LIMITS.model} characters without control characters.`);
+    }
+    sample.model = values["--sample-model"];
+  }
+  const tracked = values["--track"] ?? [];
+  if (tracked.length > EXPERIMENT_MAX_TRACKED_FIELDS ||
+      tracked.some((field) => !experimentText(field, EXPERIMENT_TEXT_LIMITS.path) || !field.startsWith("$"))) {
+    return fail("invalid_tracked_fields", `Give at most ${EXPERIMENT_MAX_TRACKED_FIELDS} --track JSON paths, each starting with $.`);
+  }
+  parsed.experiment.request = { workload_id: workload, sample, treatments, tracked_fields: [...new Set(tracked)] };
+  return parsed;
+}
+
+function experimentText(value, max) {
+  return typeof value === "string" && value.trim() === value && value.length > 0 && value.length <= max && !hasUnsafeText(value);
+}
+
+const TREATMENT_KEYS = new Set(["label", "temperature", "max_tokens", "reasoning_effort"]);
+
+// PROVIDER/MODEL[,key=value...] as a treatment, or null. The model may itself
+// contain "/" (a gateway ID such as anthropic/claude-haiku-4.5).
+function parseTreatment(spec) {
+  const [head, ...options] = spec.split(",");
+  const slash = head.indexOf("/");
+  if (slash <= 0) return null;
+  const provider = head.slice(0, slash);
+  const model = head.slice(slash + 1);
+  if (!experimentText(provider, EXPERIMENT_TEXT_LIMITS.provider) || !experimentText(model, EXPERIMENT_TEXT_LIMITS.model)) {
+    return null;
+  }
+  const treatment = { provider, model };
+  const settings = {};
+  for (const option of options) {
+    const equals = option.indexOf("=");
+    const key = option.slice(0, equals);
+    const value = option.slice(equals + 1);
+    if (equals <= 0 || !TREATMENT_KEYS.has(key) || Object.hasOwn(settings, key) || (key === "label" && treatment.label !== undefined)) {
+      return null;
+    }
+    if (key === "label") {
+      if (!experimentText(value, EXPERIMENT_TEXT_LIMITS.label)) return null;
+      treatment.label = value;
+    } else if (key === "temperature") {
+      if (!/^(?:[0-1](?:\.[0-9]{1,3})?|2(?:\.0{1,3})?)$/.test(value)) return null;
+      settings.temperature = Number(value);
+    } else if (key === "max_tokens") {
+      const tokens = /^[0-9]{1,5}$/.test(value) ? Number(value) : 0;
+      if (tokens < 1 || tokens > EXPERIMENT_MAX_TOKENS) return null;
+      settings.max_tokens = tokens;
+    } else {
+      if (!EXPERIMENT_REASONING_EFFORTS.includes(value)) return null;
+      settings.reasoning_effort = value;
+    }
+  }
+  if (Object.keys(settings).length > 0) treatment.settings = settings;
+  return treatment;
+}
+
 function parseVerify(values, flags, json, fail) {
   const paths = parsePaths(values, fail);
   if (!paths.ok) return paths;
@@ -515,24 +726,9 @@ function parseRead(command, values, flags, json, fail) {
   }
   // Where to read and with which key: the same for every read, grouped usage
   // included.
-  let origin = null;
-  if (values["--url"] !== undefined) {
-    origin = parseOrigin(values["--url"]);
-    if (origin === null) return fail("invalid_url", INVALID_URL);
-  }
-  const rawWorkspace = values["--workspace"];
-  if (rawWorkspace !== undefined && !UUID.test(rawWorkspace)) {
-    return fail("invalid_workspace", "--workspace must be a workspace ID in UUID form.");
-  }
-  const agentTokenFile = values["--agent-token-file"] ?? null;
-  if (agentTokenFile !== null && (agentTokenFile === "" || agentTokenFile.includes("\0"))) {
-    return fail("invalid_agent_token_file", "--agent-token-file must name a private absolute file.");
-  }
-  const target = {
-    origin,
-    workspace: rawWorkspace === undefined ? null : rawWorkspace.toLowerCase(),
-    agentTokenFile,
-  };
+  const target = parseKeyTarget(values, fail);
+  if (!target.ok) return target;
+  delete target.ok;
   if (command === "usage" && (USAGE_GROUPED.some((name) => values[name] !== undefined) || flags.has("--today"))) {
     return parseGroupedUsage(values, flags, json, fail, { paths, timeoutMs, limit, target });
   }

package/src/auth-oauth.js

@@ -1,6 +1,12 @@
 import { createHash, randomBytes } from "node:crypto";
 
-import { AGENT_CONTRACT_VERSION, AUTH_PATHS, METADATA_SCOPE } from "./constants.js";
+import {
+  AGENT_CONTRACT_VERSION,
+  AUTH_PATHS,
+  EXPERIMENT_START_KEY_SCOPES,
+  EXPERIMENT_START_SCOPE,
+  METADATA_SCOPE,
+} from "./constants.js";
 import { parseJsonObject } from "./http.js";
 import { failureOf, send } from "./transport.js";
 
@@ -396,14 +402,19 @@ function decodeClaims(token) {
 // with nothing to pin it to passes anyWorkspace: true with workspaceId null,
 // and then the workspace the service reports is checked for consistency and
 // returned as the verified one.
-export async function verifyContext(origin, accessToken, { profile, workspaceId, anyWorkspace = false }, signal) {
+// access is "metadata" (every read command and sign in) or
+// "experiment_start" (experiments start only: a coding-agent key with Debug
+// access and the start grant, checked for exactly that and used for nothing else).
+export async function verifyContext(origin, accessToken, { profile, workspaceId, anyWorkspace = false, access = "metadata" }, signal) {
   const workspace = await bearerJson(origin, AUTH_PATHS.workspace, accessToken, WORKSPACE_BYTES, signal, "workspace");
   if (!workspace.ok) return workspace;
   if (workspaceId === null && anyWorkspace === true) {
     workspaceId = normalizeUuid(workspace.body.workspace?.id);
     if (workspaceId === null) return stop("verification_failed", "workspace_response_invalid");
   }
-  const checked = checkWorkspace(workspace.body, { profile, workspaceId });
+  const checked = access === "experiment_start"
+    ? checkStartWorkspace(workspace.body, { profile, workspaceId })
+    : checkWorkspace(workspace.body, { profile, workspaceId });
   if (!checked.ok) return checked;
 
   const capabilities = await bearerJson(
@@ -415,11 +426,18 @@ export async function verifyContext(origin, accessToken, { profile, workspaceId,
     "capabilities",
   );
   if (!capabilities.ok) return capabilities;
-  const allowed = checkCapabilities(capabilities.body, { profile, workspaceId });
+  const allowed = access === "experiment_start"
+    ? checkStartCapabilities(capabilities.body, { profile, workspaceId })
+    : checkCapabilities(capabilities.body, { profile, workspaceId });
   if (!allowed.ok) return allowed;
   // The verified documents stay in memory for read commands, which print
   // only fields they validate themselves.
-  return { ok: true, workspaceId, documents: { workspace: workspace.body, capabilities: capabilities.body } };
+  return {
+    ok: true,
+    workspaceId,
+    scopes: checked.scopes ?? [METADATA_SCOPE],
+    documents: { workspace: workspace.body, capabilities: capabilities.body },
+  };
 }
 
 // Both documents carry the service's contract version string in
@@ -444,6 +462,41 @@ export function checkWorkspace(body, { profile, workspaceId }) {
   return { ok: true };
 }
 
+// A start key's workspace document: the same identity checks as
+// checkWorkspace, and exactly the scopes Debug and the start grant.
+export function checkStartWorkspace(body, { profile, workspaceId }) {
+  const identity = checkWorkspace({ ...body, access: { scopes: [METADATA_SCOPE] } }, { profile, workspaceId });
+  if (!identity.ok) return identity;
+  const scopes = body.access?.scopes;
+  if (
+    !Array.isArray(scopes) ||
+    scopes.length !== EXPERIMENT_START_KEY_SCOPES.length ||
+    !EXPERIMENT_START_KEY_SCOPES.every((scope) => scopes.includes(scope))
+  ) {
+    return stop("permission_denied", "experiment_start_not_granted");
+  }
+  return { ok: true, scopes: [...scopes].sort() };
+}
+
+// A start key's capabilities document: the same identity checks as
+// checkCapabilities, and the start capability offered to this key.
+export function checkStartCapabilities(body, { profile, workspaceId }) {
+  if (body.schema_version !== AGENT_CONTRACT_VERSION || !isObject(body.provenance) || !isObject(body.agent)) {
+    return stop("verification_failed", "capabilities_response_invalid");
+  }
+  if (normalizeUuid(body.provenance.workspace_id) !== workspaceId) {
+    return stop("verification_failed", "workspace_context_mismatch");
+  }
+  if (body.provenance.deployment_profile !== profile || body.deployment_profile !== profile) {
+    return stop("verification_failed", "profile_mismatch");
+  }
+  const start = body.agent.experiment_start;
+  if (!isObject(start) || start.available !== true || start.required_scope !== EXPERIMENT_START_SCOPE || start.mutates !== true) {
+    return stop("capability_unavailable", "experiment_start_unavailable");
+  }
+  return { ok: true };
+}
+
 export function checkCapabilities(body, { profile, workspaceId }) {
   if (body.schema_version !== AGENT_CONTRACT_VERSION || !isObject(body.provenance) || !isObject(body.agent)) {
     return stop("verification_failed", "capabilities_response_invalid");