mycomesh-consumer 0.1.0 → 0.1.2

package/README.md

@@ -1,9 +1,9 @@
 # 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.
+Local-first launcher and request CLI for the MycoMesh OpenAI-compatible
+Consumer edge. With no arguments it starts the pinned Docker runtime, opens the
+wallet and funding page, waits for a V5 Session, and opens Codex through the
+loopback proxy.
 
 The package is published as `mycomesh-consumer`. `mycomesh-consumer` and the
 short `mycomesh` command are equivalent.
@@ -11,10 +11,9 @@ 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
+- Docker Desktop/Engine with Compose V2
+- The official Codex dependency installed with this npm package
+- An injected browser wallet on Sepolia with enough ETH for transaction gas
 
 For local development, install it directly from the repository:
 
@@ -26,14 +25,27 @@ For an npm install from the public registry:
 
 ```sh
 npm install --global mycomesh-consumer
-mycomesh-consumer health
+mycomesh-consumer
 ```
 
-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.
+No checkout, separate Codex install, host Python, GNU Make, public Gateway URL, or command arguments are
+required. The command always prints the local onboarding URL and opens it when
+possible. Connect the wallet, mint/deposit test tUSDC, and approve the one-time
+V5 `openSession`; Codex opens after `/ready` confirms the Session on-chain.
+Wallet keys stay in the browser wallet. Consumer credentials, transport
+identity, and Session state stay in a protected Docker volume.
 
-For a one-shot command without a global install:
+The runtime image is pinned by digest. Stop it without deleting state with:
+
+```sh
+mycomesh-consumer --stop
+```
+
+Use `--no-browser` on a headless machine or `--no-codex` to leave only the
+local proxy running. Standard proxy variables are forwarded into the Consumer;
+loopback proxy hosts are translated to `host.docker.internal`.
+
+The existing stateless API commands remain available. For example:
 
 ```sh
 npx --yes --package=mycomesh-consumer mycomesh-consumer health
@@ -58,10 +70,10 @@ 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:
+The zero-argument launcher configures Codex directly with a temporary
+`mycomesh` model provider and does not modify `~/.codex/config.toml`. For manual
+API commands, read the local credentials with the repository operator command
+or provide explicit values:
 
 ```sh
 export MYCOMESH_BASE_URL=http://127.0.0.1:8110/v1
@@ -70,9 +82,10 @@ 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.
+the same local Consumer wallet. A standard OpenAI client may omit the
+`mycomesh_session` extension when it calls the local proxy: the proxy selects
+the latest verified active Session. A public Gateway can still be used
+explicitly with `--base-url`, but it is never the default.
 
 ## Commands
 
@@ -92,11 +105,10 @@ mycomesh chat \
   --max-completion-tokens 500
 ```
 
-The CLI validates `MYCOMESH_SESSION_ID` and adds the required
+The request CLI validates `MYCOMESH_SESSION_ID` and adds the
 `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.
+for one command. The local proxy also accepts a standard OpenAI-shaped request
+without the extension and binds its latest verified Session.
 
 Use `--stream` to request SSE. SSE bytes are forwarded to stdout as they arrive,
 without rewriting event boundaries:

package/bin/mycomesh-consumer.mjs

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

package/bin/mycomesh.mjs

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

package/consumer.compose.yml

@@ -0,0 +1,83 @@
+services:
+  consumer-volume-init:
+    image: ${MYCOMESH_NODE_IMAGE:?MYCOMESH_NODE_IMAGE is required}
+    user: "0:0"
+    network_mode: none
+    restart: "no"
+    read_only: true
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    cap_add:
+      - CHOWN
+      - DAC_OVERRIDE
+    volumes:
+      - mycomesh-consumer-data:/volumes/consumer
+    entrypoint: ["/bin/sh", "-ec", "chown -R 10001:10001 /volumes/consumer"]
+
+  consumer:
+    image: ${MYCOMESH_NODE_IMAGE:?MYCOMESH_NODE_IMAGE is required}
+    user: "10001:10001"
+    restart: unless-stopped
+    pids_limit: 128
+    mem_limit: 256m
+    cpus: "1.0"
+    logging:
+      driver: json-file
+      options:
+        max-size: 10m
+        max-file: "3"
+    init: true
+    read_only: true
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    working_dir: /data
+    environment:
+      MYCOMESH_CONSUMER_DATA_DIR: /data
+      MYCOMESH_CONSUMER_NETWORK_CONFIG: /app/deployments/sepolia-provider-network.json
+      MYCOMESH_CONSUMER_PUBLIC_BASE_URL: http://127.0.0.1:8110/v1
+      MYCOMESH_CONSUMER_WEB_DIR: /app/web
+      MYCOMESH_CONSUMER_DISCOVERY_URLS: ${MYCOMESH_CONSUMER_DISCOVERY_URLS:-}
+      MYCOMESH_CONSUMER_SESSION_LIFETIME_SECONDS: ${MYCOMESH_CONSUMER_SESSION_LIFETIME_SECONDS:-86400}
+      MYCOMESH_CONSUMER_SESSION_MAX_AMOUNT_UNITS: ${MYCOMESH_CONSUMER_SESSION_MAX_AMOUNT_UNITS:-10000000}
+      MYCOMESH_CONSUMER_REQUEST_TIMEOUT_SECONDS: ${MYCOMESH_CONSUMER_REQUEST_TIMEOUT_SECONDS:-300}
+      MYCOMESH_CONSUMER_MAX_REQUEST_BYTES: ${MYCOMESH_CONSUMER_MAX_REQUEST_BYTES:-1048576}
+      MYCOMESH_CONSUMER_REQUEST_BODY_TIMEOUT_SECONDS: ${MYCOMESH_CONSUMER_REQUEST_BODY_TIMEOUT_SECONDS:-30}
+      HTTP_PROXY: ${MYCOMESH_CONSUMER_HTTP_PROXY:-}
+      HTTPS_PROXY: ${MYCOMESH_CONSUMER_HTTPS_PROXY:-}
+      ALL_PROXY: ${MYCOMESH_CONSUMER_ALL_PROXY:-}
+      NO_PROXY: ${MYCOMESH_CONSUMER_NO_PROXY:-127.0.0.1,localhost,::1}
+      http_proxy: ${MYCOMESH_CONSUMER_HTTP_PROXY:-}
+      https_proxy: ${MYCOMESH_CONSUMER_HTTPS_PROXY:-}
+      all_proxy: ${MYCOMESH_CONSUMER_ALL_PROXY:-}
+      no_proxy: ${MYCOMESH_CONSUMER_NO_PROXY:-127.0.0.1,localhost,::1}
+    extra_hosts:
+      - host.docker.internal:host-gateway
+    ports:
+      - "127.0.0.1:8110:8110"
+    volumes:
+      - mycomesh-consumer-data:/data
+    tmpfs:
+      - /tmp:size=32m,mode=1777
+    depends_on:
+      consumer-volume-init:
+        condition: service_completed_successfully
+    stop_grace_period: 15s
+    healthcheck:
+      test:
+        - CMD
+        - python
+        - -c
+        - "import json, urllib.request; value=json.load(urllib.request.urlopen('http://127.0.0.1:8110/health', timeout=3)); assert value.get('ok') is True; assert value.get('gateway_dependency') is False; assert value.get('browser_app_ready') is True"
+      interval: 15s
+      timeout: 5s
+      retries: 4
+      start_period: 10s
+    entrypoint: ["python", "-m", "gateway.local_consumer"]
+    command: ["serve", "--host", "0.0.0.0", "--port", "8110"]
+
+volumes:
+  mycomesh-consumer-data:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mycomesh-consumer",
-  "version": "0.1.0",
-  "description": "Stateless MycoMesh Consumer CLI for the local loopback edge or an explicit HTTPS Gateway.",
+  "version": "0.1.2",
+  "description": "Local-first MycoMesh Consumer launcher and OpenAI-compatible request CLI.",
   "publishConfig": {
     "access": "public"
   },
@@ -14,11 +14,17 @@
     "bin/mycomesh.mjs",
     "bin/mycomesh-consumer.mjs",
     "src/cli.mjs",
+    "src/consumer.mjs",
+    "scripts/start-consumer.sh",
+    "consumer.compose.yml",
     "README.md"
   ],
   "engines": {
     "node": ">=20"
   },
+  "dependencies": {
+    "@openai/codex": "0.146.0"
+  },
   "scripts": {
     "test": "node --test"
   },

package/scripts/start-consumer.sh

@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+COMPOSE_FILE="$SCRIPT_DIR/../consumer.compose.yml"
+PROJECT_NAME="mycomesh-consumer"
+NODE_IMAGE="${MYCOMESH_NODE_IMAGE:-}"
+CODEX_COMMAND="${MYCOMESH_CODEX_COMMAND:-codex}"
+READY_TIMEOUT="${MYCOMESH_CONSUMER_READY_TIMEOUT_SECONDS:-1800}"
+NO_BROWSER=0
+NO_CODEX=0
+STOP=0
+DRY_RUN=0
+CODEX_ARGS=()
+
+die() {
+  printf 'error: %s\n' "$*" >&2
+  exit 64
+}
+
+is_docker_cli() {
+  local candidate="${1-}" version_output
+  [[ -n "$candidate" && -x "$candidate" && ! -d "$candidate" ]] || return 1
+  case "$candidate" in */node_modules/*) return 1 ;; esac
+  version_output="$("$candidate" --version 2>/dev/null)" || return 1
+  [[ "$version_output" == "Docker version "* ]] || return 1
+  "$candidate" compose version >/dev/null 2>&1 || return 1
+}
+
+find_docker_cli() {
+  local configured="${MYCOMESH_DOCKER_CLI:-}" path_entry candidate name fallback old_ifs="$IFS"
+  if [[ -n "$configured" ]]; then
+    candidate="$configured"
+    [[ "$candidate" == */* ]] || candidate="$(command -v "$candidate" 2>/dev/null || true)"
+    is_docker_cli "$candidate" || die "MYCOMESH_DOCKER_CLI is not a Docker CLI with Compose V2"
+    printf '%s' "$candidate"
+    return
+  fi
+  IFS=:
+  for path_entry in ${PATH:-}; do
+    [[ -n "$path_entry" ]] || path_entry=.
+    for name in docker docker.exe; do
+      candidate="$path_entry/$name"
+      if is_docker_cli "$candidate"; then
+        IFS="$old_ifs"
+        printf '%s' "$candidate"
+        return
+      fi
+    done
+  done
+  IFS="$old_ifs"
+  for fallback in /usr/local/bin/docker /opt/homebrew/bin/docker /usr/bin/docker \
+    /Applications/Docker.app/Contents/Resources/bin/docker \
+    '/c/Program Files/Docker/Docker/resources/bin/docker.exe'; do
+    if is_docker_cli "$fallback"; then
+      printf '%s' "$fallback"
+      return
+    fi
+  done
+  die "Docker Desktop/Engine with Compose V2 is required"
+}
+
+rewrite_loopback_proxy() {
+  local value="${1-}" scheme authority suffix userinfo host_port tail=""
+  case "$value" in *$'\n'*|*$'\r'*) die "Consumer proxy URLs must be single-line values" ;; esac
+  if [[ ! "$value" =~ ^([A-Za-z][A-Za-z0-9+.-]*://)([^/?#]*)(.*)$ ]]; then
+    printf '%s' "$value"
+    return
+  fi
+  scheme="${BASH_REMATCH[1]}"; authority="${BASH_REMATCH[2]}"; suffix="${BASH_REMATCH[3]}"
+  userinfo=""; host_port="$authority"
+  if [[ "$authority" == *@* ]]; then userinfo="${authority%@*}@"; host_port="${authority##*@}"; fi
+  if [[ "$host_port" == "127.0.0.1" ]]; then :
+  elif [[ "$host_port" == 127.0.0.1:* ]]; then tail="${host_port#127.0.0.1}"
+  elif [[ "$host_port" == "[::1]" ]]; then :
+  elif [[ "$host_port" == "[::1]:"* ]]; then tail="${host_port#\[::1\]}"
+  elif [[ "$host_port" =~ ^[Ll][Oo][Cc][Aa][Ll][Hh][Oo][Ss][Tt](:.*)?$ ]]; then tail="${BASH_REMATCH[1]}"
+  else printf '%s' "$value"; return
+  fi
+  printf '%s' "${scheme}${userinfo}host.docker.internal${tail}${suffix}"
+}
+
+prepare_proxy_env() {
+  local all_proxy_value no_proxy_value
+  all_proxy_value="${MYCOMESH_CONSUMER_ALL_PROXY:-${all_proxy:-${ALL_PROXY:-}}}"
+  export MYCOMESH_CONSUMER_HTTP_PROXY="$(rewrite_loopback_proxy "${MYCOMESH_CONSUMER_HTTP_PROXY:-${http_proxy:-${HTTP_PROXY:-$all_proxy_value}}}")"
+  export MYCOMESH_CONSUMER_HTTPS_PROXY="$(rewrite_loopback_proxy "${MYCOMESH_CONSUMER_HTTPS_PROXY:-${https_proxy:-${HTTPS_PROXY:-$all_proxy_value}}}")"
+  export MYCOMESH_CONSUMER_ALL_PROXY="$(rewrite_loopback_proxy "$all_proxy_value")"
+  no_proxy_value="${MYCOMESH_CONSUMER_NO_PROXY:-${no_proxy:-${NO_PROXY:-}}}"
+  export MYCOMESH_CONSUMER_NO_PROXY="${no_proxy_value:+${no_proxy_value},}127.0.0.1,localhost,::1"
+  export NO_PROXY="$MYCOMESH_CONSUMER_NO_PROXY"
+  export no_proxy="$MYCOMESH_CONSUMER_NO_PROXY"
+}
+
+run() {
+  if ((DRY_RUN)); then printf '+'; printf ' %q' "$@"; printf '\n'; else "$@"; fi
+}
+
+compose() {
+  run "$DOCKER" compose --project-name "$PROJECT_NAME" --file "$COMPOSE_FILE" "$@"
+}
+
+open_browser() {
+  local url="$1" opener=""
+  printf 'MycoMesh Consumer onboarding: %s\n' "$url"
+  ((NO_BROWSER)) && return
+  case "$(uname -s 2>/dev/null || printf unknown)" in
+    Darwin) opener=open ;;
+    Linux*) command -v xdg-open >/dev/null 2>&1 && opener=xdg-open ;;
+    MINGW*|MSYS*|CYGWIN*)
+      if command -v cmd.exe >/dev/null 2>&1; then cmd.exe /c start "" "$url" >/dev/null 2>&1 & return; fi ;;
+  esac
+  if [[ -n "$opener" ]]; then "$opener" "$url" >/dev/null 2>&1 &
+  else printf '%s\n' "Open this URL in a browser to connect a wallet, fund it, and activate a V5 Session."; fi
+}
+
+while (($#)); do
+  case "$1" in
+    --node-image) (($# >= 2)) || die "--node-image requires a value"; NODE_IMAGE="$2"; shift 2 ;;
+    --codex-command) (($# >= 2)) || die "--codex-command requires a value"; CODEX_COMMAND="$2"; shift 2 ;;
+    --ready-timeout) (($# >= 2)) || die "--ready-timeout requires a value"; READY_TIMEOUT="$2"; shift 2 ;;
+    --no-browser) NO_BROWSER=1; shift ;;
+    --no-codex) NO_CODEX=1; shift ;;
+    --stop) STOP=1; shift ;;
+    --dry-run) DRY_RUN=1; shift ;;
+    --) shift; CODEX_ARGS=("$@"); break ;;
+    *) die "unknown option: $1" ;;
+  esac
+done
+
+[[ -f "$COMPOSE_FILE" ]] || die "bundled Consumer Compose file is missing"
+[[ "$NODE_IMAGE" =~ ^[A-Za-z0-9][A-Za-z0-9._/-]*@sha256:[a-f0-9]{64}$ ]] || die "Consumer image must be pinned by digest"
+[[ "$READY_TIMEOUT" =~ ^[1-9][0-9]*$ ]] || die "--ready-timeout must be a positive integer"
+((READY_TIMEOUT <= 86400)) || die "--ready-timeout must not exceed 86400 seconds"
+
+DOCKER="$(find_docker_cli)"
+if ((!DRY_RUN)); then "$DOCKER" info >/dev/null 2>&1 || die "Docker Engine/Desktop is not running"; fi
+prepare_proxy_env
+export MYCOMESH_NODE_IMAGE="$NODE_IMAGE"
+
+if ((STOP)); then
+  compose stop consumer
+  printf '%s\n' "MycoMesh Consumer stopped. Its wallet and Session state remain in the Docker volume."
+  exit 0
+fi
+
+compose pull consumer-volume-init consumer
+if ! compose up -d --wait --wait-timeout 90 consumer; then
+  printf '%s\n' "Consumer startup failed. Check whether another process owns 127.0.0.1:8110." >&2
+  "$DOCKER" compose --project-name "$PROJECT_NAME" --file "$COMPOSE_FILE" logs --tail=120 consumer >&2 || true
+  exit 1
+fi
+url="http://127.0.0.1:8110/app/playground"
+open_browser "$url"
+
+if ((DRY_RUN || NO_CODEX)); then
+  printf '%s\n' "MycoMesh Consumer is running at http://127.0.0.1:8110/v1"
+  ((DRY_RUN)) && printf '%s\n' "Dry run complete; no container or Codex process was started."
+  exit 0
+fi
+
+printf '%s\n' "Waiting for the browser to activate the local V5 Session..."
+command -v curl >/dev/null 2>&1 || die "curl is required while waiting for wallet onboarding"
+started_at="$(date +%s)"
+while ! curl --noproxy '*' --fail --silent --max-time 3 http://127.0.0.1:8110/ready >/dev/null 2>&1; do
+  if (( $(date +%s) - started_at >= READY_TIMEOUT )); then
+    die "timed out waiting for the local Consumer V5 Session; reopen $url"
+  fi
+  sleep 2
+done
+
+if ! codex_env="$("$DOCKER" compose --project-name "$PROJECT_NAME" --file "$COMPOSE_FILE" exec -T consumer python -m gateway.local_consumer codex-env)"; then
+  die "could not load Codex credentials from the local Consumer"
+fi
+eval "$codex_env"
+unset codex_env
+if ! command -v "$CODEX_COMMAND" >/dev/null 2>&1; then
+  printf "error: Consumer is ready, but '%s' is not installed on this host\n" "$CODEX_COMMAND" >&2
+  exit 127
+fi
+
+printf '%s\n' "Opening Codex through the local MycoMesh Consumer."
+exec "$CODEX_COMMAND" \
+  -c 'model="gpt-5.5"' \
+  -c 'model_provider="mycomesh"' \
+  -c 'model_providers.mycomesh.name="MycoMesh"' \
+  -c 'model_providers.mycomesh.base_url="http://127.0.0.1:8110/v1"' \
+  -c 'model_providers.mycomesh.env_key="MYCOMESH_API_KEY"' \
+  -c 'model_providers.mycomesh.wire_api="responses"' \
+  "${CODEX_ARGS[@]}"

package/src/cli.mjs

@@ -1,7 +1,7 @@
 import { once } from "node:events";
 import { readFile } from "node:fs/promises";
 
-const CLI_VERSION = "0.1.0";
+const CLI_VERSION = "0.1.2";
 // 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.

package/src/consumer.mjs

@@ -0,0 +1,208 @@
+import { spawn as defaultSpawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const CONSUMER_RELEASE_VERSION = "0.1.2";
+const DEFAULT_NODE_IMAGE =
+  "ghcr.io/charleslzp/mycomesh-node@sha256:341fff4ee5d1d820d2149c5b1fc4de619ef0abbb41c83408ad8a9f8bfbf31d10";
+const API_COMMANDS = new Set(["health", "models", "responses", "chat"]);
+const API_VALUE_OPTIONS = new Set([
+  "--base-url",
+  "--api-key",
+  "--timeout",
+  "--session-id",
+  "--json",
+  "--model",
+  "--input",
+  "--message",
+  "--system",
+  "--max-output-tokens",
+  "--max-tokens",
+  "--max-completion-tokens",
+]);
+
+const HELP = `Usage: mycomesh-consumer [options] [-- codex-options]
+
+Start the local MycoMesh Consumer. No options are needed.
+
+The default command starts the pinned Docker runtime, opens the local wallet
+and funding page, waits for an activated V5 Session, then opens Codex through
+the loopback Consumer at http://127.0.0.1:8110/v1.
+
+Options:
+  --no-browser          Print the onboarding URL without opening it
+  --no-codex            Start the Consumer and browser without opening Codex
+  --stop                Stop the Consumer without deleting its wallet state
+  --codex-command PATH  Codex executable (default: codex)
+  --ready-timeout SEC   Wallet onboarding timeout (default: 1800)
+  --node-image IMAGE    Advanced: override the pinned Consumer image
+  --dry-run             Print the planned Docker operations
+  -h, --help            Show this help
+  -v, --version         Show the package version
+
+Existing API commands remain available:
+  mycomesh-consumer health
+  mycomesh-consumer models
+  mycomesh-consumer responses "hello"
+  mycomesh-consumer chat "hello"
+
+Docker Desktop/Engine is required. The package installs official Codex and
+wallet keys remain in the browser wallet; local Consumer credentials and
+Sessions remain in a protected Docker volume.`;
+
+class ConsumerCliError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = "ConsumerCliError";
+    this.exitCode = exitCode;
+  }
+}
+
+export async function main(argv, dependencies = {}) {
+  const env = dependencies.env ?? process.env;
+  const stdout = dependencies.stdout ?? process.stdout;
+  const stderr = dependencies.stderr ?? process.stderr;
+  try {
+    const parsed = parseArguments(argv, env);
+    if (parsed.help) {
+      stdout.write(`${HELP}\n`);
+      return 0;
+    }
+    if (parsed.version) {
+      stdout.write(`${CONSUMER_RELEASE_VERSION}\n`);
+      return 0;
+    }
+    const script = dependencies.scriptPath
+      ?? fileURLToPath(new URL("../scripts/start-consumer.sh", import.meta.url));
+    return await runScript(script, toScriptArgs(parsed), {
+      env,
+      spawn: dependencies.spawn ?? defaultSpawn,
+    });
+  } catch (error) {
+    const exitCode = error instanceof ConsumerCliError ? error.exitCode : 1;
+    const message = error instanceof Error ? error.message : String(error);
+    stderr.write(`mycomesh consumer: ${message}\n`);
+    return exitCode;
+  }
+}
+
+export function parseArguments(argv, env = process.env) {
+  const parsed = {
+    nodeImage: env.MYCOMESH_NODE_IMAGE || DEFAULT_NODE_IMAGE,
+    codexCommand: env.MYCOMESH_CODEX_COMMAND || bundledCodexCommand(),
+    readyTimeout: env.MYCOMESH_CONSUMER_READY_TIMEOUT_SECONDS || undefined,
+    noBrowser: false,
+    noCodex: false,
+    stop: false,
+    dryRun: false,
+    help: false,
+    version: false,
+    codexArgs: [],
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--") {
+      parsed.codexArgs = 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 === "--no-browser") {
+      parsed.noBrowser = true;
+      continue;
+    }
+    if (token === "--no-codex") {
+      parsed.noCodex = true;
+      continue;
+    }
+    if (token === "--stop") {
+      parsed.stop = true;
+      continue;
+    }
+    if (token === "--dry-run") {
+      parsed.dryRun = true;
+      continue;
+    }
+    const separator = token.indexOf("=");
+    const name = separator === -1 ? token : token.slice(0, separator);
+    let value = separator === -1 ? undefined : token.slice(separator + 1);
+    if (!["--node-image", "--codex-command", "--ready-timeout"].includes(name)) {
+      throw new ConsumerCliError(`unknown option: ${token}`, 2);
+    }
+    if (value === undefined) {
+      index += 1;
+      value = argv[index];
+    }
+    if (!value) throw new ConsumerCliError(`${name} requires a value`, 2);
+    if (name === "--node-image") parsed.nodeImage = value;
+    if (name === "--codex-command") parsed.codexCommand = value;
+    if (name === "--ready-timeout") parsed.readyTimeout = value;
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9._/-]*@sha256:[a-f0-9]{64}$/.test(parsed.nodeImage)) {
+    throw new ConsumerCliError("Consumer image must be pinned by digest", 2);
+  }
+  if (parsed.readyTimeout && !/^[1-9][0-9]*$/.test(parsed.readyTimeout)) {
+    throw new ConsumerCliError("--ready-timeout must be a positive integer", 2);
+  }
+  return parsed;
+}
+
+function bundledCodexCommand() {
+  try {
+    return createRequire(import.meta.url).resolve("@openai/codex/bin/codex.js");
+  } catch {
+    return "codex";
+  }
+}
+
+export function isApiInvocation(argv) {
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--") return false;
+    if (token.startsWith("--")) {
+      const name = token.split("=", 1)[0];
+      if (!token.includes("=") && API_VALUE_OPTIONS.has(name)) index += 1;
+      continue;
+    }
+    if (token.startsWith("-")) continue;
+    return API_COMMANDS.has(token);
+  }
+  return false;
+}
+
+export function toScriptArgs(parsed) {
+  const args = ["--node-image", parsed.nodeImage];
+  if (parsed.codexCommand) args.push("--codex-command", parsed.codexCommand);
+  if (parsed.readyTimeout) args.push("--ready-timeout", parsed.readyTimeout);
+  if (parsed.noBrowser) args.push("--no-browser");
+  if (parsed.noCodex) args.push("--no-codex");
+  if (parsed.stop) args.push("--stop");
+  if (parsed.dryRun) args.push("--dry-run");
+  if (parsed.codexArgs.length) args.push("--", ...parsed.codexArgs);
+  return args;
+}
+
+function runScript(script, args, { env, spawn }) {
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn("bash", [script, ...args], { env: { ...env }, stdio: "inherit" });
+    } catch (error) {
+      reject(new ConsumerCliError(`could not start bash: ${error.message}`));
+      return;
+    }
+    child.once("error", (error) => reject(new ConsumerCliError(`could not start bash: ${error.message}`)));
+    child.once("exit", (code, signal) => {
+      resolve(typeof code === "number" ? code : 128 + ({ SIGHUP: 1, SIGINT: 2, SIGTERM: 15 }[signal] ?? 1));
+    });
+  });
+}
+
+export { CONSUMER_RELEASE_VERSION, DEFAULT_NODE_IMAGE, HELP as CONSUMER_HELP };