metergraph-cli 0.2.3 → 0.2.5

package/src/action-help.js

@@ -0,0 +1,130 @@
+// Human action help; command execution and JSON envelopes remain independent.
+const option = (name, value, summary) => ({ name, value, summary });
+const selectors = [
+  option("--model", "ID", "Model ID."),
+  option("--provider", "ID", "Provider; use instead of --channel."),
+  option("--channel", "ID", "Billing channel; use instead of --provider."),
+  option("--region", "ID", "Billing region."),
+];
+const pricingCommon = [
+  option("--url", "ORIGIN", "Service origin. Default: https://app.metergraph.dev."),
+  option("--timeout-ms", "N", "Request deadline, 100–30000 ms. Default: 10000."),
+  option("--api", "API", "public (default) or reference. Reference requires a loopback origin."),
+  option("--json", null, "Print JSON."),
+];
+const tokens = ["input", "output", "cache-read", "cache-write", "cache-write-5m", "cache-write-1h"].map(
+  name => option(`--${name}-tokens`, "N", name.startsWith("cache-write")
+    ? "Anthropic cache-write tokens."
+    : "Token count. Omitted counts stay unknown."));
+const pricing = {
+  models: ["Discover available models", "[--provider ID | --channel ID] [--limit N]", "metergraph pricing models --limit 10",
+    [...selectors, option("--limit", "N", "Models to show. Default: 20; max: 100.")],
+    "Current catalog. No account required."],
+  lookup: ["Look up a model's prices", "--model ID [--provider ID | --channel ID]", "metergraph pricing lookup --model gpt-5 --provider openai",
+    [...selectors, option("--at", "YYYY-MM-DD", "Price date (UTC). Default: now.")],
+    "Public catalog prices. No account required."],
+  calculate: ["Estimate cost from token counts", "--model ID [--input-tokens N] [--output-tokens N]", "metergraph pricing calculate --model gpt-5 --provider openai --input-tokens 1000 --output-tokens 200",
+    [...selectors, ...tokens, option("--batch", null, "Use batch rates."),
+      option("--at", "YYYY-MM-DD", "Price date (UTC). Default: now."),
+      option("--trace-format", "FORMAT", "Token format: anthropic.messages, openai.responses, openai.chat_completions or otel.gen_ai.")],
+    "Only supplied counts are sent. Partial costs are known subtotals. OpenAI cache reads cannot exceed total input. No model calls are made."],
+  market: ["Compare current rates on one billing channel", "--channel ID [--region ID] [--limit N]", "metergraph pricing market --channel openai-api --limit 10",
+    selectors.filter(o => ["--channel", "--region"].includes(o.name)).concat(option("--limit", "N", "Models to show. Default: 20; max: 100.")),
+    "Current prices, without historical or quality rankings. No account required."],
+  history: ["Inspect historical catalog prices", "--model ID --channel ID --api reference --url ORIGIN", "metergraph pricing history --model openai/gpt-5.6-terra --channel openai-api --api reference --url http://127.0.0.1:8765 --format chart",
+    selectors.filter(o => o.name !== "--provider").concat([
+      option("--api", "reference", "Required. History currently uses the local reference adapter."),
+      option("--at", "YYYY-MM-DD", "Reference lookup date at UTC midnight."),
+      option("--format", "FORMAT", "chart (default), table or html. Cannot combine with --json."),
+    ]), "Requires a loopback reference service. Historical data is not available from the public API."],
+};
+
+export function actionHelpData(topic, action, commands) {
+  if (topic === "pricing") {
+    const canonical = action === "cost" ? "calculate" : action;
+    const entry = pricing[canonical];
+    if (!entry) return null;
+    const [summary, usage, example, options, note] = entry;
+    const focused = options.map(o => {
+      if (o.name === "--model") return { ...o, summary: canonical === "models" ? "Filter by model ID." : "Required. Model ID." };
+      if (o.name === "--channel" && ["market", "history"].includes(canonical)) return { ...o, summary: "Required. Billing channel." };
+      if (o.name === "--region" && ["market", "history"].includes(canonical)) return { ...o, summary: "Billing region. Default: global." };
+      return o;
+    });
+    return { summary, usage: `metergraph pricing ${action} ${usage} [options]`,
+      options: [...focused, ...pricingCommon.filter(o => !options.some(specific => specific.name === o.name)
+        && !(o.name === "--api" && ["models", "calculate"].includes(action)))], examples: [example.replace("pricing calculate", `pricing ${action}`)], note };
+  }
+  if (topic === "experiments") {
+    const entry = commands.find(c => c.name === topic);
+    const names = { list: ["--workload", "--limit"], get: ["--id"],
+      estimate: ["--workload", "--treatment", "--last-n", "--sample-model", "--track"],
+      start: ["--workload", "--treatment", "--last-n", "--sample-model", "--track"] }[action];
+    if (!names) return null;
+    const specific = ["--workload", "--limit", "--id", "--treatment", "--last-n", "--sample-model", "--track"];
+    const options = entry.options.filter(o => !specific.includes(o.name) || names.includes(o.name)).map(o => {
+      if (o.name === "--agent-token-file") return { ...o, summary: action === "start"
+        ? "Private (0600) Debug key file with Allow analysis starts. Or set METERGRAPH_AGENT_TOKEN."
+        : "Private (0600) Metadata key file. Or use saved sign in or METERGRAPH_AGENT_TOKEN." };
+      const summaries = {
+        "--workload": action === "list" ? "Filter by workload ID." : "Required. Workload ID.",
+        "--id": "Required. Experiment ID.", "--limit": "Experiments to show. Default: 20; max: 50.",
+        "--treatment": "Required. PROVIDER/MODEL; repeat for up to 3 treatments.",
+        "--last-n": "Calls to replay. Default: 20; range: 10–40.",
+        "--sample-model": "Filter production calls by model.", "--track": "JSON path to compare; repeat up to 10 times.",
+      };
+      return { ...o, summary: summaries[o.name] ?? o.summary };
+    });
+    const invocation = { list: "[--workload ID] [--limit N]", get: "--id UUID",
+      estimate: "--workload ID --treatment PROVIDER/MODEL", start: "--workload ID --treatment PROVIDER/MODEL" }[action];
+    return { summary: { list: "List recent experiments", get: "Read an experiment's results",
+      estimate: "Estimate a model comparison before starting it", start: "Start a budgeted model comparison" }[action],
+      usage: `metergraph experiments ${action} ${invocation} [options]`, options,
+      examples: [`metergraph experiments ${action} ${{ list: "--limit 10", get: "--id UUID", estimate: "--workload ROUTE --treatment PROVIDER/MODEL", start: "--workload ROUTE --treatment PROVIDER/MODEL --agent-token-file /path/to/private-key" }[action]}`],
+      note: action === "start"
+        ? "Replays captured production prompts on the selected providers and incurs provider costs. Requires a Debug key with Allow analysis starts. Estimate first. Each start creates a new experiment; never retry a successful start."
+        : { list: "Uses Metadata access. Returns experiment summaries.",
+          get: "Uses Metadata access. Returns results without prompts or responses.",
+          estimate: "Uses Metadata access. Estimates provider cost without starting a replay." }[action] };
+  }
+  const entry = commands.find(c => c.name === `${topic} ${action}`);
+  if (!entry) return null;
+  const label = topic === "skill" ? "setup skill" : "workflow skills";
+  return { summary: action === "list" ? "List installed workflow skills"
+      : `${action === "install" ? "Install" : "Update"} the Metergraph ${label}`,
+    usage: `metergraph ${topic} ${action}${action === "list" ? "" : " --client codex|claude|cursor"} [options]`,
+    options: entry.options, examples: [`metergraph ${topic} ${action}${action === "list" ? "" : " --client codex"}`],
+    note: action === "list" ? "Lists installed workflow skills for all clients. Makes no changes."
+      : (action === "install" ? "Existing skills are left alone. No network requests." : "Replaces only unchanged skills owned by this CLI. No network requests.") };
+}
+
+// Connection details remain available offline without dominating everyday help.
+const ADVANCED_CONNECTION = new Set(["--url", "--config-dir", "--workspace", "--agent-token-file", "--timeout-ms", "--api"]);
+const SHORT_OPTIONS = {
+  "--project": "Project directory. Default: current directory.",
+  "--config-dir": "Credential directory. Default: per-user config directory.",
+  "--url": "Service origin. Default: project binding or hosted service.",
+  "--workspace": "Require this workspace ID.",
+  "--json": "Print JSON.",
+  "--client": "Agent: codex, claude or cursor.",
+  "--runtime": "local, cloud or cloud-no-shell. Inferred in a local terminal.",
+  "--skip-skill": "Skip agent skill installation.",
+  "--env-file": "Private env file. Default: .env.",
+  "--no-browser": "Print the approval link instead of opening it.",
+  "--signup": "Open sign up during browser approval.",
+  "--reconnect": "Allow switching the connected workspace.",
+  "--repair": "Approve replacement of a key that no longer verifies.",
+  "--deployment": "managed (default), customer-local, byoc or oss.",
+  "--confirm-prerequisites": "Confirm operator prerequisites are met.",
+  "--repository": "Repository identity as OWNER/NAME.",
+  "--no-repository": "Leave repository identity unset.",
+};
+export function displayOptions(options, topic, action, advanced = false) {
+  return options.filter(o => advanced || !ADVANCED_CONNECTION.has(o.name)
+    // History cannot run without these explicit connection selectors.
+    || (topic === "pricing" && action === "history" && ["--api", "--url"].includes(o.name)))
+    .map(o => ({ ...o, summary: advanced ? o.summary
+      : o.name === "--runtime" && ["skill", "skills"].includes(topic) ? "local (default) or cloud."
+      : o.name === "--url" && topic === "pricing" ? o.summary
+      : SHORT_OPTIONS[o.name] ?? o.summary }));
+}

package/src/agent-key.js

@@ -1,15 +1,17 @@
 import { verifyContext } from "./auth-oauth.js";
-import { DEFAULT_ORIGIN, MAX_BODY_BYTES, METADATA_SCOPE } from "./constants.js";
+import { DEFAULT_ORIGIN, MAX_BODY_BYTES } from "./constants.js";
 import { CREDENTIAL_MIN_LENGTH, readCredentialFile } from "./deployment-credential.js";
 import { checkDeployment } from "./doctor.js";
 import { AGENT_TOKEN_ENV, AGENT_URL_ENV } from "./environment.js";
 import { parseOrigin } from "./origin.js";
 import { send } from "./transport.js";
 
-// The read commands' second credential: a coding-agent key with Metadata
-// access that a person created on the Keys page and handed to the agent's
-// environment as a secret. It is for agents where browser sign in cannot
-// finish (SSH, cloud workspaces, CI, some containers).
+// The read commands' second credential: a coding-agent key that a person
+// created on the Keys page (or with a bundle's bin/agent-key) and handed to
+// the agent's environment as a secret. It has the Metadata role, or the
+// Debug role with workflow permissions. It is how agents read where browser
+// sign in cannot finish (SSH, cloud workspaces, CI, some containers), and how
+// they get the Debug role and permissions.
 //
 // The key comes only from the METERGRAPH_AGENT_TOKEN environment variable or
 // from a private file named by --agent-token-file (checked as setup checks
@@ -17,10 +19,11 @@ import { send } from "./transport.js";
 // written anywhere, never printed, and sent only as a bearer header to the
 // chosen origin, and only after that origin has answered the unauthenticated
 // deployment probe as a supported Metergraph service. Before any read, the
-// service's own workspace and capabilities documents must show exactly the
-// Metadata scope, no content access, the expected deployment profile and,
-// when one is pinned, the expected workspace. A broader key fails closed:
-// there is no fallback to Debug or Replay access.
+// service's own workspace and capabilities documents must show Metadata, or
+// Debug with workflow permissions, the expected deployment profile and, when
+// one is pinned, the expected workspace. A Replay key, or one with any other
+// scope, fails closed. The read commands send only Metadata requests,
+// whichever key they use.
 
 const TOKEN = new RegExp(`^[\\x21-\\x7e]{${CREDENTIAL_MIN_LENGTH},8192}$`);
 
@@ -66,6 +69,8 @@ export function keyTarget({ binding, options, env, originConfirmed = false }) {
       ok: true,
       origin: binding.origin,
       workspaceId: binding.workspace_id,
+      // A slug or name to match against the verified workspace.
+      workspaceText: options.workspaceText ?? null,
       profile: binding.deployment_profile,
       originSource: "binding",
     };
@@ -74,6 +79,7 @@ export function keyTarget({ binding, options, env, originConfirmed = false }) {
     ok: true,
     origin: requested ?? DEFAULT_ORIGIN,
     workspaceId: pinned,
+    workspaceText: options.workspaceText ?? null,
     profile: null,
     originSource: source ?? "default",
   };
@@ -84,10 +90,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.
-// 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" }) {
+// access is "read" for the read commands, or "experiment_start" for
+// experiments start, which needs Debug access and the start grant
+// (verifyContext).
+export async function keySession({ target, source, env, signal, verifiedProfile = null, access = "read" }) {
   // 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;
@@ -128,7 +134,8 @@ export async function keySession({ target, source, env, signal, verifiedProfile
       origin: target.origin,
       workspaceId: verified.workspaceId,
       profile,
-      scopes: access === "metadata" ? [METADATA_SCOPE] : verified.scopes,
+      access: verified.access,
+      scopes: verified.scopes,
       accessToken: token,
     },
     documents: verified.documents,

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

@@ -39,13 +39,24 @@ 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(["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]);
+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"]);
@@ -59,7 +70,7 @@ const 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]),
@@ -77,6 +88,7 @@ const OPTIONS = {
   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 = {
@@ -129,10 +141,11 @@ const USAGE_GROUPED = [
 // Options that take no value.
 const FLAGS = {
   pricing: new Set(["--batch"]),
-  login: new Set(["--signup", "--no-browser", "--reconnect"]),
+  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;
 
@@ -156,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 = {};
@@ -170,7 +194,7 @@ export function parseArgs(argv) {
 
   const fail = (code, message, outcome = "invalid_input") => ({
     ok: false,
-    command: (command === "skill" || command === "skills" || command === "experiments") && action !== null
+    command: (command === "skill" || command === "skills" || command === "experiments" || command === "tools") && action !== null
       ? `${command} ${action}`
       : command ?? (version ? "version" : null),
     json,
@@ -213,6 +237,14 @@ export function parseArgs(argv) {
       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("=");
@@ -280,6 +312,9 @@ export function parseArgs(argv) {
         `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.`,
@@ -297,6 +332,7 @@ export function parseArgs(argv) {
   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);
@@ -322,16 +358,29 @@ export function parseArgs(argv) {
 
 // --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 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 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.");
@@ -339,11 +388,61 @@ function parseKeyTarget(values, fail) {
   return {
     ok: true,
     origin,
-    workspace: rawWorkspace === undefined ? null : rawWorkspace.toLowerCase(),
+    ...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=..]
@@ -596,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;
@@ -618,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,