mycomesh-consumer 0.1.0

package/README.md

@@ -0,0 +1,150 @@
+# mycomesh-consumer
+
+Node.js CLI for consumers calling a MycoMesh OpenAI-compatible Consumer edge.
+The commands remain stateless: wallet funding and V5 Session activation happen
+in the browser, while this package sends API requests to the local loopback
+edge or an explicitly configured HTTPS Gateway.
+
+The package is published as `mycomesh-consumer`. `mycomesh-consumer` and the
+short `mycomesh` command are equivalent.
+
+## Requirements
+
+- Node.js 20 or newer
+- A MycoMesh Consumer base URL (the default is the local loopback edge)
+- A consumer API key for authenticated endpoints
+- For paid V5 inference, an active Session ID opened by the same wallet in the
+  local Web dApp
+
+For local development, install it directly from the repository:
+
+```sh
+npm install --global ./packages/mycomesh-cli
+```
+
+For an npm install from the public registry:
+
+```sh
+npm install --global mycomesh-consumer
+mycomesh-consumer health
+```
+
+This installs only the stateless Consumer CLI. It does not install or start
+Bridge, Relay, Proxy, or Codex services. Provider operators should install the
+separate `mycomesh-provider` package.
+
+For a one-shot command without a global install:
+
+```sh
+npx --yes --package=mycomesh-consumer mycomesh-consumer health
+```
+
+## Configuration
+
+```sh
+export MYCOMESH_BASE_URL=http://127.0.0.1:8110/v1
+export MYCOMESH_API_KEY=your-consumer-key
+```
+
+`--base-url` and `--api-key` override their corresponding environment
+variables. A base URL may be the service root or end in `/v1`.
+Remote base URLs must use HTTPS. Loopback HTTP remains available for local
+development; `--allow-insecure-http` is an explicit test-only escape hatch.
+Requests default to a 300-second deadline. Set `MYCOMESH_TIMEOUT_SECONDS` or
+`--timeout`; successful JSON bodies are capped at 32 MiB while SSE remains
+streamed with backpressure.
+
+Prefer `MYCOMESH_API_KEY` over `--api-key`: command-line arguments may be stored
+in shell history or visible to other local processes. The CLI never writes the
+key to disk and redacts it from HTTP error output.
+
+For the local network, start `make consumer-up`, open the local Playground,
+connect a browser wallet, fund V5 escrow and approve the one-time `openSession`
+transaction. Copy the active Session ID from the local status/Playground, then
+set:
+
+```sh
+export MYCOMESH_BASE_URL=http://127.0.0.1:8110/v1
+export MYCOMESH_API_KEY='replace-with-local-consumer-key'
+export MYCOMESH_SESSION_ID='0x...replace-with-active-v5-session-id'
+```
+
+The Session ID is not a replacement for the API key. Both values must belong to
+the same local Consumer wallet. The CLI does not connect a wallet, move funds,
+or open a V5 Session; the browser wallet flow does that once. A public Gateway
+can still be used explicitly with `--base-url`, but it is never the default.
+
+## Commands
+
+```sh
+mycomesh health
+mycomesh models
+
+mycomesh responses \
+  --input "Summarize this text" \
+  --model mycomesh-codex-standard-v1 \
+  --max-output-tokens 500
+
+mycomesh chat \
+  --message "Explain this function" \
+  --system "Be concise." \
+  --model mycomesh-codex-standard-v1 \
+  --max-completion-tokens 500
+```
+
+The CLI validates `MYCOMESH_SESSION_ID` and adds the required
+`mycomesh_session` object automatically. Use `--session-id 0x...` to override it
+for one command. A bare OpenAI-shaped request without either value is useful
+only with a Gateway whose operator has explicitly configured another billing
+path.
+
+Use `--stream` to request SSE. SSE bytes are forwarded to stdout as they arrive,
+without rewriting event boundaries:
+
+```sh
+mycomesh responses \
+  --input "Write a short status update" \
+  --max-output-tokens 500 \
+  --stream
+```
+
+## JSON Input
+
+Pass an inline object, read a file, or read stdin explicitly:
+
+```sh
+mycomesh responses --json '{"model":"my-model","input":"hello"}'
+mycomesh chat --json @request.json
+generate-request | mycomesh responses --json -
+```
+
+When `MYCOMESH_SESSION_ID` or `--session-id` is set, the CLI overwrites any JSON
+session field with that validated value. A client constructing the complete raw
+request body instead may include the extension directly:
+
+```json
+{
+  "mycomesh_session": {
+    "session_id": "0x..."
+  }
+}
+```
+
+Piped stdin is treated as JSON even without `--json`:
+
+```sh
+printf '%s' '{"model":"my-model","messages":[{"role":"user","content":"hello"}]}' \
+  | mycomesh chat
+```
+
+Explicit flags such as `--model`, `--input`, `--message`, `--system`, and
+`--stream` override the corresponding JSON fields. Successful JSON responses
+are pretty-printed. SSE and other response types are copied to stdout. HTTP and
+input errors are written to stderr and return a nonzero exit status.
+
+## Development
+
+```sh
+cd packages/mycomesh-cli
+npm test
+```

package/bin/mycomesh-consumer.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli.mjs";
+
+process.exitCode = await main(process.argv.slice(2));

package/bin/mycomesh.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli.mjs";
+
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "mycomesh-consumer",
+  "version": "0.1.0",
+  "description": "Stateless MycoMesh Consumer CLI for the local loopback edge or an explicit HTTPS Gateway.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "mycomesh": "./bin/mycomesh.mjs",
+    "mycomesh-consumer": "./bin/mycomesh-consumer.mjs"
+  },
+  "files": [
+    "bin/mycomesh.mjs",
+    "bin/mycomesh-consumer.mjs",
+    "src/cli.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "license": "UNLICENSED"
+}

package/src/cli.mjs

@@ -0,0 +1,654 @@
+import { once } from "node:events";
+import { readFile } from "node:fs/promises";
+
+const CLI_VERSION = "0.1.0";
+// The npm client is local-first. A public Gateway is an explicit override;
+// the default remains the loopback Consumer edge so a blocked domain cannot
+// strand the Codex client.
+const DEFAULT_BASE_URL = "http://127.0.0.1:8110/v1";
+const DEFAULT_TIMEOUT_SECONDS = 300;
+const MAX_TIMEOUT_SECONDS = 3600;
+const MAX_INPUT_BYTES = 16 * 1024 * 1024;
+const MAX_ERROR_BYTES = 64 * 1024;
+const MAX_JSON_RESPONSE_BYTES = 32 * 1024 * 1024;
+const COMMANDS = new Set(["health", "models", "responses", "chat"]);
+
+const HELP = `Usage: mycomesh <command> [options] [input]
+
+Consumer commands:
+  health                 Check gateway health
+  models                 List available models
+  responses [input]      Create a Responses API request
+  chat [message]         Create a Chat Completions API request
+
+Connection options:
+  --base-url <url>        Consumer root or /v1 URL (default: local loopback)
+                         (env: MYCOMESH_BASE_URL)
+  --api-key <key>         Bearer API key (env: MYCOMESH_API_KEY)
+  --timeout <seconds>     Request deadline, up to 3600 seconds
+                         (env: MYCOMESH_TIMEOUT_SECONDS; default: 300)
+  --allow-insecure-http   Allow cleartext HTTP to a non-loopback test gateway
+
+Session options:
+  --session-id <bytes32>  Use an already-opened V5 Session
+                         (env: MYCOMESH_SESSION_ID)
+
+Request body options:
+  --json <json|@file|->   JSON object, JSON file, or JSON from stdin
+  --model <model>         Set the request model
+  --stream                Request an SSE response
+  --no-stream             Disable streaming from a JSON base body
+
+Responses options:
+  --input <text>          Set the Responses API input
+  --max-output-tokens <n> Set max_output_tokens
+
+Chat options:
+  --message <text>        Set the user message
+  --system <text>         Prepend a system message
+  --max-tokens <n>        Set max_tokens
+  --max-completion-tokens <n>
+                         Set max_completion_tokens
+
+Other options:
+  -h, --help              Show this help
+  -v, --version           Show the CLI version
+
+When --json is omitted, piped stdin is read as a JSON request object. Explicit
+request options override fields loaded from JSON.`;
+
+class CliError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+}
+
+class HttpError extends CliError {
+  constructor(status, statusText, body) {
+    const label = [status, statusText].filter(Boolean).join(" ");
+    super(`HTTP ${label}${body ? `\n${body}` : ""}`);
+    this.name = "HttpError";
+  }
+}
+
+export async function main(argv, dependencies = {}) {
+  const env = dependencies.env ?? process.env;
+  const stdin = dependencies.stdin ?? process.stdin;
+  const stdout = dependencies.stdout ?? process.stdout;
+  const stderr = dependencies.stderr ?? process.stderr;
+  const fetchImpl = dependencies.fetch ?? globalThis.fetch;
+  const maxJsonResponseBytes =
+    dependencies.maxJsonResponseBytes ?? MAX_JSON_RESPONSE_BYTES;
+  let apiKey = env.MYCOMESH_API_KEY || "";
+  let requestTimeout;
+
+  try {
+    const parsed = parseArguments(argv, env);
+    apiKey = parsed.apiKey;
+
+    if (parsed.help) {
+      stdout.write(`${HELP}\n`);
+      return 0;
+    }
+    if (parsed.version) {
+      stdout.write(`${CLI_VERSION}\n`);
+      return 0;
+    }
+    if (typeof fetchImpl !== "function") {
+      throw new CliError("Node.js 20 or newer is required");
+    }
+
+    const request = await buildRequest(parsed, stdin);
+    requestTimeout = createRequestTimeout(parsed.timeoutSeconds);
+    const response = await sendRequest(
+      request,
+      fetchImpl,
+      requestTimeout.signal,
+      parsed.timeoutSeconds,
+    );
+    if (!response.ok) {
+      const errorBody = await readLimitedText(response.body, MAX_ERROR_BYTES);
+      throw new HttpError(response.status, response.statusText, errorBody.trim());
+    }
+
+    await writeResponse(response, stdout, maxJsonResponseBytes);
+    return 0;
+  } catch (error) {
+    const exitCode = error instanceof CliError ? error.exitCode : 1;
+    const message = requestTimeout?.signal.aborted
+      ? `request timed out after ${requestTimeout.timeoutSeconds} seconds`
+      : error instanceof Error
+        ? error.message
+        : String(error);
+    stderr.write(`mycomesh: ${redact(message, apiKey)}\n`);
+    return exitCode;
+  } finally {
+    requestTimeout?.cancel();
+  }
+}
+
+export function parseArguments(argv, env = process.env) {
+  const parsed = {
+    command: undefined,
+    baseUrl: env.MYCOMESH_BASE_URL || DEFAULT_BASE_URL,
+    apiKey: env.MYCOMESH_API_KEY || "",
+    timeoutSeconds: requestTimeoutSeconds(
+      env.MYCOMESH_TIMEOUT_SECONDS || String(DEFAULT_TIMEOUT_SECONDS),
+      "MYCOMESH_TIMEOUT_SECONDS",
+    ),
+    allowInsecureHttp: false,
+    sessionId: env.MYCOMESH_SESSION_ID || "",
+    sessionIdExplicit: false,
+    jsonSource: undefined,
+    model: undefined,
+    input: undefined,
+    message: undefined,
+    system: undefined,
+    stream: undefined,
+    maxOutputTokens: undefined,
+    maxTokens: undefined,
+    maxCompletionTokens: undefined,
+    positionals: [],
+    help: false,
+    version: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--") {
+      parsed.positionals.push(...argv.slice(index + 1));
+      break;
+    }
+    if (token === "-h" || token === "--help") {
+      parsed.help = true;
+      continue;
+    }
+    if (token === "-v" || token === "--version") {
+      parsed.version = true;
+      continue;
+    }
+    if (token === "--stream") {
+      parsed.stream = true;
+      continue;
+    }
+    if (token === "--no-stream") {
+      parsed.stream = false;
+      continue;
+    }
+    if (token === "--allow-insecure-http") {
+      parsed.allowInsecureHttp = true;
+      continue;
+    }
+    if (token.startsWith("--")) {
+      const separator = token.indexOf("=");
+      const name = separator === -1 ? token : token.slice(0, separator);
+      let value = separator === -1 ? undefined : token.slice(separator + 1);
+      if (value === undefined) {
+        index += 1;
+        value = argv[index];
+      }
+      if (value === undefined) {
+        throw new CliError(`${name} requires a value`, 2);
+      }
+      switch (name) {
+        case "--base-url":
+          parsed.baseUrl = value;
+          break;
+        case "--api-key":
+          parsed.apiKey = value;
+          break;
+        case "--timeout":
+          parsed.timeoutSeconds = requestTimeoutSeconds(value, name);
+          break;
+        case "--session-id":
+          parsed.sessionId = value;
+          parsed.sessionIdExplicit = true;
+          break;
+        case "--json":
+          parsed.jsonSource = value;
+          break;
+        case "--model":
+          parsed.model = value;
+          break;
+        case "--input":
+          parsed.input = value;
+          break;
+        case "--message":
+          parsed.message = value;
+          break;
+        case "--system":
+          parsed.system = value;
+          break;
+        case "--max-output-tokens":
+          parsed.maxOutputTokens = positiveInteger(value, name);
+          break;
+        case "--max-tokens":
+          parsed.maxTokens = positiveInteger(value, name);
+          break;
+        case "--max-completion-tokens":
+          parsed.maxCompletionTokens = positiveInteger(value, name);
+          break;
+        default:
+          throw new CliError(`unknown option: ${name}`, 2);
+      }
+      continue;
+    }
+    if (token.startsWith("-") && token !== "-") {
+      throw new CliError(`unknown option: ${token}`, 2);
+    }
+    if (parsed.command === undefined) {
+      parsed.command = token;
+    } else {
+      parsed.positionals.push(token);
+    }
+  }
+
+  if (!parsed.command && !parsed.help && !parsed.version) {
+    throw new CliError("a command is required; run mycomesh --help", 2);
+  }
+  if (parsed.command && !COMMANDS.has(parsed.command)) {
+    throw new CliError(`unknown command: ${parsed.command}`, 2);
+  }
+  if (
+    parsed.sessionId &&
+    (parsed.command === "responses" || parsed.command === "chat")
+  ) {
+    parsed.sessionId = sessionId(parsed.sessionId, "--session-id");
+  }
+  validateCommandOptions(parsed);
+  return parsed;
+}
+
+async function buildRequest(parsed, stdin) {
+  const url = endpointUrl(
+    parsed.baseUrl,
+    parsed.command,
+    parsed.allowInsecureHttp,
+  );
+  const headers = {
+    accept: "application/json",
+    "user-agent": `mycomesh-cli/${CLI_VERSION}`,
+  };
+  if (parsed.apiKey) {
+    headers.authorization = `Bearer ${parsed.apiKey}`;
+  }
+
+  if (parsed.command === "health" || parsed.command === "models") {
+    return { url, method: "GET", headers };
+  }
+
+  const body = await requestBody(parsed, stdin);
+  headers["content-type"] = "application/json";
+  if (body.stream === true) {
+    headers.accept = "text/event-stream, application/json";
+  }
+  return {
+    url,
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+  };
+}
+
+async function requestBody(parsed, stdin) {
+  let body = {};
+  if (parsed.jsonSource !== undefined) {
+    body = await parseJsonSource(parsed.jsonSource, stdin);
+  } else if (stdin && stdin.isTTY !== true) {
+    const piped = await readLimitedText(stdin, MAX_INPUT_BYTES);
+    if (piped.trim()) {
+      body = parseJsonObject(piped, "stdin");
+    }
+  }
+
+  if (parsed.model !== undefined) {
+    body.model = parsed.model;
+  }
+  if (parsed.stream !== undefined) {
+    body.stream = parsed.stream;
+  }
+  if (parsed.sessionId) {
+    body.mycomesh_session = { session_id: parsed.sessionId };
+  }
+
+  const positionalInput = parsed.positionals.length
+    ? parsed.positionals.join(" ")
+    : undefined;
+  if (parsed.command === "responses") {
+    const input = parsed.input ?? positionalInput;
+    if (input !== undefined) {
+      body.input = input;
+    }
+    if (parsed.maxOutputTokens !== undefined) {
+      body.max_output_tokens = parsed.maxOutputTokens;
+    }
+    if (body.input === undefined) {
+      throw new CliError(
+        "responses requires input in JSON, --input, or a positional argument",
+        2,
+      );
+    }
+  } else {
+    const message = parsed.message ?? positionalInput;
+    if (message !== undefined) {
+      const messages = [];
+      if (parsed.system !== undefined) {
+        messages.push({ role: "system", content: parsed.system });
+      }
+      messages.push({ role: "user", content: message });
+      body.messages = messages;
+    } else if (parsed.system !== undefined) {
+      const messages = Array.isArray(body.messages) ? body.messages : [];
+      body.messages = [
+        { role: "system", content: parsed.system },
+        ...messages,
+      ];
+    }
+    if (parsed.maxTokens !== undefined) {
+      body.max_tokens = parsed.maxTokens;
+    }
+    if (parsed.maxCompletionTokens !== undefined) {
+      body.max_completion_tokens = parsed.maxCompletionTokens;
+    }
+    if (!Array.isArray(body.messages) || body.messages.length === 0) {
+      throw new CliError(
+        "chat requires messages in JSON, --message, or a positional argument",
+        2,
+      );
+    }
+  }
+  return body;
+}
+
+async function parseJsonSource(source, stdin) {
+  if (source === "-") {
+    const text = await readLimitedText(stdin, MAX_INPUT_BYTES);
+    return parseJsonObject(text, "stdin");
+  }
+  if (source.startsWith("@")) {
+    const path = source.slice(1);
+    if (!path) {
+      throw new CliError("--json @file requires a file path", 2);
+    }
+    let contents;
+    try {
+      contents = await readFile(path);
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new CliError(`could not read JSON file: ${detail}`, 2);
+    }
+    if (contents.byteLength > MAX_INPUT_BYTES) {
+      throw new CliError(`JSON input exceeds ${MAX_INPUT_BYTES} bytes`, 2);
+    }
+    return parseJsonObject(contents.toString("utf8"), path);
+  }
+  if (Buffer.byteLength(source, "utf8") > MAX_INPUT_BYTES) {
+    throw new CliError(`JSON input exceeds ${MAX_INPUT_BYTES} bytes`, 2);
+  }
+  return parseJsonObject(source, "--json");
+}
+
+function parseJsonObject(text, source) {
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new CliError(`invalid JSON from ${source}: ${detail}`, 2);
+  }
+  if (value === null || Array.isArray(value) || typeof value !== "object") {
+    throw new CliError(`JSON from ${source} must be an object`, 2);
+  }
+  return { ...value };
+}
+
+function endpointUrl(baseUrl, command, allowInsecureHttp = false) {
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    throw new CliError("base URL must be an absolute HTTP or HTTPS URL", 2);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new CliError("base URL must use HTTP or HTTPS", 2);
+  }
+  if (url.username || url.password) {
+    throw new CliError("base URL must not contain credentials", 2);
+  }
+  if (
+    url.protocol === "http:" &&
+    !allowInsecureHttp &&
+    !isLoopbackHostname(url.hostname)
+  ) {
+    throw new CliError(
+      "remote base URLs must use HTTPS; use --allow-insecure-http only for testing",
+      2,
+    );
+  }
+  if (url.search || url.hash) {
+    throw new CliError("base URL must not contain a query string or fragment", 2);
+  }
+
+  let path = url.pathname.replace(/\/+$/, "");
+  if (command === "health") {
+    path = path.replace(/\/v1$/, "");
+    url.pathname = `${path}/health`;
+  } else {
+    if (!path.endsWith("/v1")) {
+      path = `${path}/v1`;
+    }
+    const resource = command === "chat" ? "chat/completions" : command;
+    url.pathname = `${path}/${resource}`;
+  }
+  return url;
+}
+
+function isLoopbackHostname(hostname) {
+  const normalized = hostname.toLowerCase().replace(/\.$/, "");
+  if (normalized === "localhost" || normalized === "[::1]") {
+    return true;
+  }
+  if (!/^127(?:\.[0-9]{1,3}){3}$/.test(normalized)) {
+    return false;
+  }
+  return normalized.split(".").every((part) => Number(part) <= 255);
+}
+
+async function sendRequest(request, fetchImpl, signal, timeoutSeconds) {
+  try {
+    return await fetchImpl(request.url, {
+      method: request.method,
+      headers: request.headers,
+      body: request.body,
+      redirect: "error",
+      signal,
+    });
+  } catch (error) {
+    if (signal.aborted) {
+      throw new CliError(`request timed out after ${timeoutSeconds} seconds`);
+    }
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new CliError(`request failed: ${detail}`);
+  }
+}
+
+async function writeResponse(response, output, maxJsonResponseBytes) {
+  const contentType = (response.headers.get("content-type") || "")
+    .split(";", 1)[0]
+    .trim()
+    .toLowerCase();
+
+  if (contentType === "text/event-stream") {
+    await pipeBody(response.body, output);
+    return;
+  }
+  if (contentType === "application/json" || contentType.endsWith("+json")) {
+    const text = await readLimitedText(response.body, maxJsonResponseBytes, {
+      rejectOnLimit: true,
+      label: "JSON response",
+    });
+    if (!text.trim()) {
+      return;
+    }
+    let value;
+    try {
+      value = JSON.parse(text);
+    } catch {
+      throw new CliError("server returned malformed JSON");
+    }
+    output.write(`${JSON.stringify(value, null, 2)}\n`);
+    return;
+  }
+  await pipeBody(response.body, output);
+}
+
+async function pipeBody(body, output) {
+  if (!body) {
+    return;
+  }
+  for await (const chunk of body) {
+    if (!output.write(chunk)) {
+      await once(output, "drain");
+    }
+  }
+}
+
+async function readLimitedText(
+  stream,
+  limit,
+  { rejectOnLimit = false, label = "response" } = {},
+) {
+  if (!stream) {
+    return "";
+  }
+  const chunks = [];
+  let size = 0;
+  let truncated = false;
+  for await (const rawChunk of stream) {
+    const chunk = Buffer.isBuffer(rawChunk) ? rawChunk : Buffer.from(rawChunk);
+    const remaining = limit - size;
+    if (chunk.byteLength > remaining) {
+      if (remaining > 0) {
+        chunks.push(chunk.subarray(0, remaining));
+      }
+      truncated = true;
+      break;
+    }
+    chunks.push(chunk);
+    size += chunk.byteLength;
+  }
+  const text = Buffer.concat(chunks).toString("utf8");
+  if (truncated && rejectOnLimit) {
+    throw new CliError(`${label} exceeds ${limit} bytes`);
+  }
+  return truncated ? `${text}\n[response truncated]` : text;
+}
+
+function createRequestTimeout(timeoutSeconds) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutSeconds * 1000);
+  timer.unref?.();
+  return {
+    signal: controller.signal,
+    timeoutSeconds,
+    cancel() {
+      clearTimeout(timer);
+    },
+  };
+}
+
+function requestTimeoutSeconds(value, option) {
+  const timeout = positiveInteger(String(value), option);
+  if (timeout > MAX_TIMEOUT_SECONDS) {
+    throw new CliError(
+      `${option} must not exceed ${MAX_TIMEOUT_SECONDS} seconds`,
+      2,
+    );
+  }
+  return timeout;
+}
+
+function positiveInteger(value, option) {
+  if (!/^[1-9][0-9]*$/.test(value)) {
+    throw new CliError(`${option} must be a positive integer`, 2);
+  }
+  const number = Number(value);
+  if (!Number.isSafeInteger(number)) {
+    throw new CliError(`${option} is too large`, 2);
+  }
+  return number;
+}
+
+function sessionId(value, option) {
+  if (!/^0x[0-9a-fA-F]{64}$/.test(value)) {
+    throw new CliError(`${option} must be a 32-byte 0x-prefixed hex value`, 2);
+  }
+  return value.toLowerCase();
+}
+
+function validateCommandOptions(parsed) {
+  if (parsed.help || parsed.version || !parsed.command) {
+    return;
+  }
+  const hasBodyOptions =
+    parsed.jsonSource !== undefined ||
+    parsed.model !== undefined ||
+    parsed.stream !== undefined ||
+    parsed.input !== undefined ||
+    parsed.message !== undefined ||
+    parsed.system !== undefined ||
+    parsed.maxOutputTokens !== undefined ||
+    parsed.maxTokens !== undefined ||
+    parsed.maxCompletionTokens !== undefined ||
+    parsed.positionals.length > 0;
+  if ((parsed.command === "health" || parsed.command === "models") && hasBodyOptions) {
+    throw new CliError(`${parsed.command} does not accept request body options`, 2);
+  }
+  if (
+    (parsed.command === "health" || parsed.command === "models") &&
+    parsed.sessionIdExplicit
+  ) {
+    throw new CliError(`${parsed.command} does not accept --session-id`, 2);
+  }
+  if (
+    parsed.command === "responses" &&
+    (parsed.message !== undefined ||
+      parsed.system !== undefined ||
+      parsed.maxTokens !== undefined ||
+      parsed.maxCompletionTokens !== undefined)
+  ) {
+    throw new CliError("chat options cannot be used with responses", 2);
+  }
+  if (
+    parsed.command === "chat" &&
+    (parsed.input !== undefined || parsed.maxOutputTokens !== undefined)
+  ) {
+    throw new CliError("responses options cannot be used with chat", 2);
+  }
+  if (parsed.input !== undefined && parsed.positionals.length > 0) {
+    throw new CliError("use either --input or positional input, not both", 2);
+  }
+  if (parsed.message !== undefined && parsed.positionals.length > 0) {
+    throw new CliError("use either --message or a positional message, not both", 2);
+  }
+}
+
+function redact(value, secret) {
+  let text = String(value);
+  if (!secret) {
+    return text;
+  }
+  const variants = new Set([
+    secret,
+    encodeURIComponent(secret),
+    JSON.stringify(secret).slice(1, -1),
+  ]);
+  for (const variant of variants) {
+    if (variant) {
+      text = text.split(variant).join("[REDACTED]");
+    }
+  }
+  return text;
+}