metergraph-cli 0.2.2 → 0.2.4

package/src/anchored-fs.js

@@ -0,0 +1,163 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+// A process-local directory capability service. The shipped helper owns all
+// descriptors; only its inherited anonymous pipes carry requests and contents.
+// An absent or unverified backend is an error, never a pathname-write fallback.
+const MAX = 2 * 1024 * 1024;
+const base = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../native");
+const errnoNames = new Map(Object.entries(os.constants.errno).map(([name, number]) => [number, name]));
+let service = null;
+let rollbackDepth = 0;
+const aliases = new Map(process.platform === "darwin" ? [["/var", "/private/var"], ["/tmp", "/private/tmp"]] : []);
+function failure(code) { const error = new Error(`Secure filesystem operation failed (${code}).`); error.code = code; return error; }
+function verifiedHelper() {
+  const name = `anchored-fs-${process.platform}-${process.arch}`;
+  let file;
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(base, "manifest.json"), "utf8"));
+    file = path.join(base, "bin", name);
+    const bytes = fs.readFileSync(file);
+    if (manifest.schema !== 1 || typeof manifest.artifacts[name] !== "string" ||
+        createHash("sha256").update(bytes).digest("hex") !== manifest.artifacts[name]) throw failure("ENOTSUP");
+  } catch { throw failure("ENOTSUP"); }
+  return file;
+}
+// Test and diagnostic capability discovery verifies the same packaged bytes as
+// start(). It never enables a platform merely because its name is recognised.
+export function hasVerifiedHelper() {
+  try { verifiedHelper(); return true; } catch { return false; }
+}
+function start() {
+  if (service !== null) return service;
+  const file = verifiedHelper();
+  const child = spawn(file, [], { stdio: ["pipe", "pipe", "ignore"], windowsHide: true, env: {} });
+  child.on("error", () => { /* synchronous pipe operations report backend loss */ });
+  const input = child.stdin?._handle;
+  const output = child.stdout?._handle;
+  if (!input || !output || typeof input.setBlocking !== "function" || typeof output.setBlocking !== "function") {
+    child.kill("SIGKILL"); throw failure("ENOTSUP");
+  }
+  input.setBlocking(true); output.setBlocking(true);
+  service = { child, input: input.fd, output: output.fd };
+  child.unref(); child.stdin.unref(); child.stdout.unref();
+  return service;
+}
+function writeAll(fd, bytes) { let offset = 0; while (offset < bytes.length) { const count = fs.writeSync(fd, bytes, offset, bytes.length - offset); if (count === 0) throw failure("EIO"); offset += count; } }
+function readAll(fd, bytes) { let offset = 0; while (offset < bytes.length) { const count = fs.readSync(fd, bytes, offset, bytes.length - offset, null); if (count === 0) throw failure("EIO"); offset += count; } }
+function request(operation, args = [], payload = Buffer.alloc(0)) {
+  const encoded = args.map(value => Buffer.from(String(value)));
+  if (encoded.some(value => value.includes(0))) throw failure("EINVAL");
+  const size = 2 + encoded.reduce((n, value) => n + 4 + value.length, 0) + payload.length;
+  if (size > MAX) throw failure("EFBIG");
+  const body = Buffer.alloc(4 + size); body.writeUInt32BE(size); body[4] = operation; body[5] = args.length;
+  let offset = 6;
+  for (const value of encoded) { body.writeUInt32BE(value.length, offset); offset += 4; value.copy(body, offset); offset += value.length; }
+  payload.copy(body, offset);
+  const pipe = start(); writeAll(pipe.input, body);
+  const header = Buffer.alloc(8); readAll(pipe.output, header);
+  const error = header.readUInt32BE(); const length = header.readUInt32BE(4);
+  if (length > MAX) throw failure("EIO");
+  const result = Buffer.alloc(length); readAll(pipe.output, result);
+  if (error) throw failure(errnoNames.get(error) ?? "EIO");
+  return result;
+}
+function canonical(value) {
+  if (typeof value !== "string" || value.includes("\0")) throw failure("EINVAL");
+  let absolute = path.resolve(value);
+  const choices = [...aliases].sort((a,b) => b[0].length - a[0].length);
+  for (const [alias, target] of choices) if (absolute === alias || absolute.startsWith(`${alias}/`)) { absolute = target + absolute.slice(alias.length); break; }
+  return absolute;
+}
+function descriptor(value) { if (!Number.isSafeInteger(value) || value > -1001) throw failure("EBADF"); return -value - 1001; }
+function statResult(bytes, options) {
+  if (bytes.length !== 88) throw failure("EIO");
+  const keys = ["dev", "ino", "mode", "nlink", "uid", "gid", "size"];
+  const result = {};
+  keys.forEach((key, index) => { const n = bytes.readBigUInt64BE(index*8); result[key] = options?.bigint ? n : Number(n); });
+  for (const [name, index] of [["mtime", 7], ["ctime", 9]]) {
+    const seconds = bytes.readBigInt64BE(index * 8);
+    const nanoseconds = bytes.readBigUInt64BE((index + 1) * 8);
+    if (nanoseconds >= 1000000000n) throw failure("EIO");
+    const ns = seconds * 1000000000n + nanoseconds;
+    result[`${name}Ms`] = options?.bigint ? ns / 1000000n : Number(seconds) * 1000 + Number(nanoseconds) / 1000000;
+    if (options?.bigint) result[`${name}Ns`] = ns;
+    result[name] = new Date(Number(ns / 1000000n));
+  }
+  const mode = Number(result.mode) & 0o170000;
+  return Object.assign(result, { isFile: () => mode === 0o100000, isDirectory: () => mode === 0o040000,
+    isSymbolicLink: () => mode === 0o120000, isFIFO: () => mode === 0o010000,
+    isSocket: () => mode === 0o140000, isBlockDevice: () => mode === 0o060000, isCharacterDevice: () => mode === 0o020000 });
+}
+export function validatePath(value) { request(13, [canonical(value)]); return true; }
+export function withRollback(callback) {
+  if (rollbackDepth++ === 0) request(14, [1]);
+  try { return callback(); } finally { if (--rollbackDepth === 0) request(14, [0]); }
+}
+export function closeAnchoredFs() {
+  if (service !== null) { service.child.stdin.destroy(); service.child.stdout.destroy(); service.child.kill("SIGKILL"); service = null; }
+}
+const anchored = {
+  constants: fs.constants,
+  lstatSync(value, options) { return statResult(request(1, [canonical(value)]), options); },
+  statSync(value, options) { const result = this.lstatSync(value, options); if (result.isSymbolicLink()) throw failure("ELOOP"); return result; },
+  realpathSync(value) {
+    // Root selection is read-only. Pin the resolved identity immediately; every
+    // subsequent operation uses the helper's retained directory descriptors.
+    const absolute = path.resolve(value); const real = fs.realpathSync(absolute);
+    const prior = aliases.get(absolute);
+    if (prior !== undefined && prior !== real) throw failure("ESTALE");
+    // Freeze both the selected spelling and the capability spelling. A later
+    // root resolution cannot rebind an existing capability to another tree.
+    const pinned = aliases.get(real);
+    if (pinned !== undefined && pinned !== real) throw failure("ESTALE");
+    validatePath(real); aliases.set(real, real); aliases.set(absolute, real); return real;
+  },
+  existsSync(value) { try { this.lstatSync(value); return true; } catch (error) { if (["ENOENT", "ENOTDIR"].includes(error.code)) return false; throw error; } },
+  openSync(value, flags, mode = 0o666) {
+    let kind;
+    const extras = (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0);
+    const stripped = typeof flags === "number" ? flags & ~extras : flags;
+    if (flags === "r" || stripped === fs.constants.O_RDONLY) kind = 0;
+    else if (flags === "r+" || stripped === fs.constants.O_RDWR) kind = 1;
+    else if (flags === "wx" || flags === "wx+" || stripped === (fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL)) kind = 2;
+    else throw failure("ENOTSUP");
+    return -1001 - request(2, [canonical(value), kind, mode]).readUInt32BE();
+  },
+  fstatSync(fd, options) { return statResult(request(3, [descriptor(fd)]), options); },
+  readFileSync(value, options) {
+    const own = typeof value !== "number"; const fd = own ? this.openSync(value, "r") : value;
+    try { const bytes = request(4, [descriptor(fd)]); const encoding = typeof options === "string" ? options : options?.encoding; return encoding ? bytes.toString(encoding) : bytes; }
+    finally { if (own) this.closeSync(fd); }
+  },
+  readSync(fd, buffer, offset, length, position) {
+    const bytes = request(16, [descriptor(fd), length, position ?? 0]); bytes.copy(buffer, offset); return bytes.length;
+  },
+  writeFileSync(fd, value, options) {
+    if (typeof fd !== "number") throw failure("ENOTSUP");
+    const encoding = typeof options === "string" ? options : options?.encoding;
+    request(5, [descriptor(fd)], Buffer.isBuffer(value) ? value : Buffer.from(value, encoding));
+  },
+  fchmodSync(fd, mode) { request(6, [descriptor(fd), mode]); },
+  chmodSync(value, mode) { const fd = this.openSync(value, "r"); try { this.fchmodSync(fd, mode); } finally { this.closeSync(fd); } },
+  fsyncSync(fd) { request(7, [descriptor(fd)]); },
+  closeSync(fd) { request(8, [descriptor(fd)]); },
+  mkdirSync(value, options = {}) {
+    const absolute = canonical(value); const mode = typeof options === "number" ? options : options.mode ?? 0o777;
+    try { request(9, [absolute, mode]); }
+    catch (error) {
+      if (!options.recursive) throw error;
+      if (error.code === "ENOENT") { this.mkdirSync(path.dirname(absolute), {recursive:true, mode}); request(9, [absolute, mode]); }
+      else if (error.code !== "EEXIST" || !this.statSync(absolute).isDirectory()) throw error;
+    }
+  },
+  renameSync(from, to) { request(10, [canonical(from), canonical(to)]); },
+  unlinkSync(value) { request(11, [canonical(value)]); },
+  rmdirSync(value) { request(12, [canonical(value)]); },
+  linkSync(from, to) { request(15, [canonical(from), canonical(to)]); },
+};
+export default anchored;

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,
@@ -30,13 +39,25 @@ import {
   USAGE_DIMENSIONS,
   USAGE_MAX_FILTER_VALUES,
   USAGE_SORTS,
+  WORKFLOW_PERMISSIONS,
 } from "./constants.js";
 import { parseOrigin } from "./origin.js";
 import { groupedRequest, hasUnsafeText, isCursor, isSafeFilter, readQuery } from "./read-contract.js";
+import { TOOL_ARGS_MAX_BYTES, TOOL_NAME } from "./tools.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", "tools", ...READ_COMMANDS]);
+const HELP_TOPICS = new Set(["agents", "exit-codes", "pricing", "doctor", "skill", "skills", "login", "logout", "setup", "verify", "experiments", "tools", ...READ_COMMANDS]);
+export const TOOLS_ACTIONS = Object.freeze(["list", "call"]);
+// The roles login asks for: Metadata, or Debug, to which --allow-* adds the
+// workflow permissions a workspace owner approves. Replay is never asked for.
+export const LOGIN_ROLES = Object.freeze(["metadata", "debug"]);
+// Each --allow-* switch and the scope it asks for, by the names bin/agent-key
+// and the Keys page use.
+const LOGIN_PERMISSIONS = Object.freeze(
+  WORKFLOW_PERMISSIONS.map(({ field, scope }) => [`--${field.replaceAll("_", "-")}`, scope]),
+);
+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,10 +66,11 @@ 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"]),
-  login: new Set(["--runtime", "--url", "--workspace", "--project", "--config-dir", "--timeout-ms"]),
+  login: new Set(["--runtime", "--url", "--workspace", "--role", "--project", "--config-dir", "--timeout-ms"]),
   setup: new Set(["--runtime", "--url", "--workspace", "--project", "--config-dir", "--env-file", "--client", "--timeout-ms", "--deployment", "--agent-token-file", "--repository"]),
   logout: new Set(["--project", "--config-dir"]),
   status: new Set([...READ_BASE, ...READ_KEY]),
@@ -63,6 +85,17 @@ 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",
+  ]),
+  tools: new Set([...READ_BASE, ...READ_KEY, "--name", "--args", "--args-file"]),
+};
+// 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 +129,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,10 +140,12 @@ const USAGE_GROUPED = [
 ];
 // Options that take no value.
 const FLAGS = {
-  login: new Set(["--signup", "--no-browser", "--reconnect"]),
+  pricing: new Set(["--batch"]),
+  login: new Set(["--signup", "--no-browser", "--reconnect", ...LOGIN_PERMISSIONS.map(([flag]) => flag)]),
   setup: new Set(["--no-browser", "--repair", "--signup", "--reconnect", "--skip-skill", "--confirm-prerequisites", "--no-repository"]),
   verify: new Set(["--open", "--no-browser"]),
   usage: new Set(["--today"]),
+  tools: new Set(["--yes"]),
 };
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
@@ -133,13 +169,24 @@ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export function parseArgs(argv) {
   const json = argv.includes("--json");
 
-  if (argv.includes("--help") || argv.includes("-h")) {
-    const topic = argv.find((arg) => HELP_TOPICS.has(arg)) ?? null;
-    return { ok: true, command: "help", topic, json };
+  const helpCommand = argv.find(arg => arg !== "--json") === "help";
+  if (argv.includes("--help") || argv.includes("-h") || helpCommand) {
+    const parts = argv.filter(arg => !["--json", "--help", "-h", "--advanced"].includes(arg));
+    if (parts[0] === "help") parts.shift();
+    const topic = HELP_TOPICS.has(parts[0]) ? parts[0] : null;
+    const actions = { pricing: PRICING_ACTIONS, experiments: EXPERIMENT_ACTIONS,
+      skill: [...SKILL_ACTIONS], skills: [...SKILLS_ACTIONS] };
+    const action = actions[topic]?.includes(parts[1]) ? parts[1] : null;
+    if (helpCommand && (parts.length > (action ? 2 : topic ? 1 : 0))) {
+      return { ok: false, command: "help", json, code: "unknown_help_topic", outcome: "invalid_input",
+        message: 'Unknown help topic. Run "metergraph --help" for commands.' };
+    }
+    return { ok: true, command: "help", topic, ...(action ? { action } : {}), ...(argv.includes("--advanced") ? { advanced: true } : {}), json };
   }
 
   let command = null;
   let action = null;
+  let toolName = null;
   let topic = null;
   let version = false;
   const values = {};
@@ -147,7 +194,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" || command === "tools") && action !== null
       ? `${command} ${action}`
       : command ?? (version ? "version" : null),
     json,
@@ -174,6 +221,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 +233,18 @@ export function parseArgs(argv) {
       action = arg;
       continue;
     }
+    if (command === "experiments" && action === null && EXPERIMENT_ACTIONS.includes(arg)) {
+      action = arg;
+      continue;
+    }
+    if (command === "tools" && action === null && TOOLS_ACTIONS.includes(arg)) {
+      action = arg;
+      continue;
+    }
+    if (command === "tools" && action === "call" && toolName === null && !arg.startsWith("-")) {
+      toolName = arg;
+      continue;
+    }
 
     if (READ_COMMANDS.includes(command)) {
       const equals = arg.indexOf("=");
@@ -212,7 +275,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 +306,15 @@ 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.`,
+      );
+    }
+    if (command === "tools" && action === null && !arg.startsWith("-")) {
+      return fail("unknown_subcommand", `Unknown tools subcommand at argument ${position}. Use list or call.`);
+    }
     return fail(
       "unknown_argument",
       `Unrecognized argument at position ${position}. Run "metergraph --help" for usage.`,
@@ -252,11 +325,14 @@ 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 (command === "tools") return parseTools(action, toolName, values, flags, json, fail);
   if (READ_COMMANDS.includes(command)) return parseRead(command, values, flags, json, fail);
   if (command === "logout") {
     const paths = parsePaths(values, fail);
@@ -280,6 +356,240 @@ 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.
+// --workspace names a workspace by its slug (on its Settings page, and in
+// "metergraph context"), by its name, or by its ID. Returns { workspace,
+// workspaceText }: workspace is an ID, workspaceText a slug or name, which is
+// matched against the workspace the service reports. null for a bad value.
+function workspaceOption(raw) {
+  if (raw === undefined) return { workspace: null, workspaceText: null };
+  if (UUID.test(raw)) return { workspace: raw.toLowerCase(), workspaceText: null };
+  const text = raw.trim();
+  if (text.length === 0 || text.length > MAX_WORKSPACE_TEXT || hasUnsafeText(text)) return null;
+  return { workspace: null, workspaceText: text };
+}
+const MAX_WORKSPACE_TEXT = 200;
+const INVALID_WORKSPACE =
+  "--workspace takes the workspace's slug, shown on its Settings page and by \"metergraph context\", or its name.";
+
+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 named = workspaceOption(values["--workspace"]);
+  if (named === null) return fail("invalid_workspace", INVALID_WORKSPACE);
+  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,
+    ...named,
+    agentTokenFile,
+  };
+}
+
+// tools list [--name TOOL] | call TOOL [--args JSON | --args-file PATH] [--yes].
+// The credential options are the read commands'. Arguments are checked for
+// shape only; the service validates them against the tool's schema.
+function parseTools(action, toolName, values, flags, json, fail) {
+  if (action === null) {
+    return fail("missing_subcommand", 'tools requires a subcommand: list or call. Run "metergraph help tools" for usage.');
+  }
+  const allowed = action === "list" ? ["--name"] : ["--args", "--args-file"];
+  for (const name of Object.keys(values)) {
+    if (!READ_BASE.includes(name) && !READ_KEY.includes(name) && !allowed.includes(name)) {
+      return fail("unknown_argument", `tools ${action} does not take ${name}. Run "metergraph help tools" for usage.`);
+    }
+  }
+  if (action === "list" && flags.has("--yes")) {
+    return fail("unknown_argument", 'tools list does not take --yes. Run "metergraph help tools" for usage.');
+  }
+  const name = action === "list" ? values["--name"] ?? null : toolName;
+  if (action === "call" && name === null) {
+    return fail("missing_tool", 'tools call needs a tool name, such as metergraph_list_classified_workloads. Run "metergraph tools list" to see them.');
+  }
+  if (name !== null && !TOOL_NAME.test(name)) {
+    return fail("invalid_tool", "A tool name is metergraph_ followed by lower case letters, digits and underscores.");
+  }
+  if (values["--args"] !== undefined && values["--args-file"] !== undefined) {
+    return fail("conflicting_options", "Give --args or --args-file, not both.");
+  }
+  if (values["--args"] !== undefined && Buffer.byteLength(values["--args"]) > TOOL_ARGS_MAX_BYTES) {
+    return fail("args_too_large", "--args is larger than 1 MiB. Use --args-file.");
+  }
+  if (values["--args-file"] !== undefined && (values["--args-file"] === "" || values["--args-file"].includes("\0"))) {
+    return fail("invalid_args_file", "--args-file must name a file.");
+  }
+  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;
+  return {
+    ok: true, command: "tools", action, ...target, project: paths.project, configDir: paths.configDir, timeoutMs, json,
+    tool: { name, args: values["--args"] ?? null, argsFile: values["--args-file"] ?? null, yes: flags.has("--yes") },
+  };
+}
+
+// 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;
@@ -385,9 +695,16 @@ function parseLogin(values, flags, json, fail) {
   }
   const origin = parseUrlOption(values);
   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 named = workspaceOption(values["--workspace"]);
+  if (named === null) return fail("invalid_workspace", INVALID_WORKSPACE);
+  const role = values["--role"] ?? "metadata";
+  if (!LOGIN_ROLES.includes(role)) return fail("invalid_role", "--role must be metadata or debug.");
+  const permissions = LOGIN_PERMISSIONS.filter(([flag]) => flags.has(flag)).map(([, scope]) => scope);
+  if (permissions.length > 0 && role !== "debug") {
+    return fail(
+      "permission_needs_debug",
+      "--allow-evaluation-writes, --allow-evaluation-previews and --allow-analysis-starts need --role debug.",
+    );
   }
   const paths = parsePaths(values, fail);
   if (!paths.ok) return paths;
@@ -407,7 +724,9 @@ function parseLogin(values, flags, json, fail) {
     command: "login",
     runtime,
     origin,
-    workspace: rawWorkspace === undefined ? null : rawWorkspace.toLowerCase(),
+    ...named,
+    role,
+    permissions,
     project: paths.project,
     configDir: paths.configDir,
     timeoutMs,
@@ -515,24 +834,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 });
   }