@uptomic/career-mentor-cli 0.1.0

package/dist/index.js

@@ -0,0 +1,1945 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { realpathSync } from "node:fs";
+import { readFile as readFileFromDisk } from "node:fs/promises";
+import { basename, extname } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// ../career-mentor-sdk/dist/index.js
+class CareerMentorError extends Error {
+  code;
+  status;
+  requestId;
+  retryAfter;
+  constructor(message, options) {
+    super(message);
+    this.name = "CareerMentorError";
+    this.code = options.code;
+    this.status = options.status;
+    this.requestId = options.requestId;
+    this.retryAfter = options.retryAfter;
+  }
+}
+
+class CareerMentorApiError extends CareerMentorError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "CareerMentorApiError";
+  }
+}
+
+class CareerMentorRequestError extends CareerMentorError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "CareerMentorRequestError";
+  }
+}
+var SDK_VERSION = "0.1.0";
+var DEFAULT_TIMEOUT_MS = 30000;
+var DEFAULT_USER_AGENT = `career-mentor-typescript/${SDK_VERSION}`;
+var MAX_ERROR_MESSAGE_LENGTH = 300;
+var MAX_HEADER_VALUE_LENGTH = 512;
+var MAX_RUN_EVENT_LIMIT = 1000;
+var MAX_SSE_BUFFER_LENGTH = 1e6;
+var RUN_WAIT_RECONNECT_INITIAL_DELAY_MS = 100;
+var RUN_WAIT_RECONNECT_MAX_DELAY_MS = 1000;
+var CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/;
+var CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/g;
+var EVENT_CURSOR_PATTERN = /^\d+-\d+$/;
+var UUID_V7_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function invalidConfiguration(message) {
+  throw new CareerMentorRequestError(message, { code: "INVALID_CONFIGURATION" });
+}
+function normalizeBaseUrl(value) {
+  if (!value.trim()) {
+    invalidConfiguration("Career Mentor API baseUrl is required.");
+  }
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    invalidConfiguration("Career Mentor API baseUrl must be an absolute HTTP(S) URL.");
+  }
+  if (!["http:", "https:"].includes(parsed.protocol)) {
+    invalidConfiguration("Career Mentor API baseUrl must use HTTP or HTTPS.");
+  }
+  const loopbackHost = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1" || parsed.hostname === "[::1]";
+  if (parsed.protocol === "http:" && !loopbackHost) {
+    invalidConfiguration("Career Mentor API baseUrl must use HTTPS unless it targets the local loopback interface.");
+  }
+  if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+    invalidConfiguration("Career Mentor API baseUrl must not include credentials, query, or hash.");
+  }
+  parsed.pathname = parsed.pathname.replace(/\/+$/, "");
+  return parsed.toString().replace(/\/$/, "");
+}
+function requirePositiveTimeout(value) {
+  if (!(Number.isFinite(value) && value > 0)) {
+    invalidConfiguration("Career Mentor request timeoutMs must be a positive finite number.");
+  }
+  return value;
+}
+function requireToken(value) {
+  const token = value.trim();
+  if (!token || CONTROL_CHARACTER.test(token)) {
+    invalidConfiguration("Career Mentor capability token is invalid.");
+  }
+  return token;
+}
+function requireRunId(value) {
+  const runId = value.trim();
+  if (!UUID_V7_PATTERN.test(runId)) {
+    invalidConfiguration("Career Mentor capability runId must be a UUIDv7 identifier.");
+  }
+  return runId;
+}
+function requireEventCursor(value, label) {
+  if (value === undefined)
+    return;
+  if (!EVENT_CURSOR_PATTERN.test(value)) {
+    invalidConfiguration(`${label} must be a Redis stream cursor such as 0-0.`);
+  }
+  return value;
+}
+function requireEventLimit(value) {
+  if (value === undefined)
+    return;
+  if (!(Number.isInteger(value) && value >= 1 && value <= MAX_RUN_EVENT_LIMIT)) {
+    invalidConfiguration(`Career Mentor run event limit must be between 1 and ${MAX_RUN_EVENT_LIMIT}.`);
+  }
+  return value;
+}
+function runEventsPath(runId, options) {
+  const search = new URLSearchParams;
+  const after = requireEventCursor(options.after, "Career Mentor run event after cursor");
+  const limit = requireEventLimit(options.limit);
+  if (after !== undefined)
+    search.set("after", after);
+  if (limit !== undefined)
+    search.set("limit", String(limit));
+  const query = search.toString();
+  return `/api/v1/runs/${encodeURIComponent(requireRunId(runId))}/events${query ? `?${query}` : ""}`;
+}
+function setTransportHeader(headers, name, value) {
+  if (value === undefined)
+    return;
+  if (!value || value.length > MAX_HEADER_VALUE_LENGTH || CONTROL_CHARACTER.test(value)) {
+    throw new CareerMentorRequestError(`${name} is invalid.`, { code: "INVALID_HEADER" });
+  }
+  headers.set(name, value);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertJsonSafe(value, seen = new Set) {
+  if (value === null || typeof value === "string" || typeof value === "boolean")
+    return;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new CareerMentorRequestError("Capability input must contain finite numbers.", {
+        code: "INVALID_JSON"
+      });
+    }
+    return;
+  }
+  if (typeof value !== "object") {
+    throw new CareerMentorRequestError("Capability input must be JSON-safe.", {
+      code: "INVALID_JSON"
+    });
+  }
+  if (seen.has(value)) {
+    throw new CareerMentorRequestError("Capability input must not contain cycles.", {
+      code: "INVALID_JSON"
+    });
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (const item of value)
+      assertJsonSafe(item, seen);
+  } else {
+    if (Object.getOwnPropertySymbols(value).length > 0) {
+      throw new CareerMentorRequestError("Capability input must not contain symbol keys.", {
+        code: "INVALID_JSON"
+      });
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new CareerMentorRequestError("Capability input must contain plain JSON objects.", {
+        code: "INVALID_JSON"
+      });
+    }
+    for (const item of Object.values(value))
+      assertJsonSafe(item, seen);
+  }
+  seen.delete(value);
+}
+function serializeJson(value) {
+  assertJsonSafe(value);
+  return JSON.stringify(value);
+}
+function readSafeString(value) {
+  if (typeof value !== "string")
+    return;
+  const normalized = value.replace(CONTROL_CHARACTERS, " ").trim();
+  return normalized ? normalized.slice(0, MAX_ERROR_MESSAGE_LENGTH) : undefined;
+}
+function parseRetryAfter(value) {
+  if (!value)
+    return;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0)
+    return seconds;
+  const date = Date.parse(value);
+  if (Number.isNaN(date))
+    return;
+  return Math.max(0, Math.ceil((date - Date.now()) / 1000));
+}
+async function readJson(response, requestId) {
+  try {
+    return await response.json();
+  } catch {
+    throw new CareerMentorApiError("Career Mentor API returned invalid JSON.", {
+      code: "INVALID_RESPONSE",
+      status: response.status,
+      requestId: response.headers.get("x-request-id") ?? requestId
+    });
+  }
+}
+function apiErrorFromResponse(response, payload, fallbackRequestId) {
+  const error = isRecord(payload) && isRecord(payload["error"]) ? payload["error"] : undefined;
+  const code = readSafeString(error?.["code"]) ?? `HTTP_${response.status}`;
+  const requestId = (isRecord(payload) ? readSafeString(payload["requestId"]) : undefined) ?? readSafeString(response.headers.get("x-request-id")) ?? fallbackRequestId;
+  const apiMessage = readSafeString(error?.["message"]);
+  const message = response.status >= 500 ? "Career Mentor API request failed." : apiMessage ?? `Career Mentor API request failed with status ${response.status}.`;
+  return new CareerMentorApiError(message, {
+    code,
+    status: response.status,
+    requestId,
+    retryAfter: parseRetryAfter(response.headers.get("retry-after"))
+  });
+}
+function invalidResponse(response, fallbackRequestId) {
+  return new CareerMentorApiError("Career Mentor API returned an invalid response.", {
+    code: "INVALID_RESPONSE",
+    status: response.status,
+    requestId: response.headers.get("x-request-id") ?? fallbackRequestId
+  });
+}
+function translateTransportError(error, didTimeout, options) {
+  if (didTimeout) {
+    return new CareerMentorRequestError("Career Mentor API request timed out.", {
+      code: "TIMEOUT",
+      requestId: options.requestId
+    });
+  }
+  if (options.signal?.aborted) {
+    return new CareerMentorRequestError("Career Mentor API request was aborted.", {
+      code: "REQUEST_ABORTED",
+      requestId: options.requestId
+    });
+  }
+  if (error instanceof CareerMentorError)
+    return error;
+  return new CareerMentorRequestError("Career Mentor API request failed.", {
+    code: "NETWORK_ERROR",
+    requestId: options.requestId
+  });
+}
+function runWaitTimeoutError(requestId) {
+  return new CareerMentorRequestError("Career Mentor API request timed out.", {
+    code: "TIMEOUT",
+    requestId
+  });
+}
+function runWaitAbortedError(requestId) {
+  return new CareerMentorRequestError("Career Mentor API request was aborted.", {
+    code: "REQUEST_ABORTED",
+    requestId
+  });
+}
+function remainingRunWaitTimeout(deadline, options) {
+  if (options.signal?.aborted)
+    throw runWaitAbortedError(options.requestId);
+  const remaining = deadline - Date.now();
+  if (remaining <= 0)
+    throw runWaitTimeoutError(options.requestId);
+  return remaining;
+}
+async function waitBeforeRunReconnect(delayMs, deadline, options) {
+  const remaining = remainingRunWaitTimeout(deadline, options);
+  const boundedDelay = Math.min(delayMs, remaining);
+  await new Promise((resolve, reject) => {
+    let timer;
+    const cleanup = () => {
+      if (timer !== undefined)
+        clearTimeout(timer);
+      options.signal?.removeEventListener("abort", abort);
+    };
+    const abort = () => {
+      cleanup();
+      reject(runWaitAbortedError(options.requestId));
+    };
+    if (options.signal?.aborted) {
+      abort();
+      return;
+    }
+    options.signal?.addEventListener("abort", abort, { once: true });
+    timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, boundedDelay);
+  });
+  remainingRunWaitTimeout(deadline, options);
+}
+async function* readSseLines(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder;
+  let buffer = "";
+  let completed = false;
+  try {
+    while (true) {
+      const next = await reader.read();
+      if (next.done) {
+        completed = true;
+        buffer += decoder.decode();
+        break;
+      }
+      buffer += decoder.decode(next.value, { stream: true });
+      if (buffer.length > MAX_SSE_BUFFER_LENGTH) {
+        throw new Error("Career Mentor SSE frame exceeded the maximum size.");
+      }
+      let newline = buffer.indexOf(`
+`);
+      while (newline !== -1) {
+        const rawLine = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        yield rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+        newline = buffer.indexOf(`
+`);
+      }
+    }
+    if (buffer)
+      yield buffer.endsWith("\r") ? buffer.slice(0, -1) : buffer;
+  } finally {
+    if (!completed) {
+      try {
+        await reader.cancel();
+      } catch {}
+    }
+    reader.releaseLock();
+  }
+}
+function parseSseEvent(frame, response, fallbackRequestId) {
+  if (frame.data.length === 0)
+    return;
+  if (!(frame.id && frame.eventType && EVENT_CURSOR_PATTERN.test(frame.id))) {
+    throw invalidResponse(response, fallbackRequestId);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(frame.data.join(`
+`));
+  } catch {
+    throw invalidResponse(response, fallbackRequestId);
+  }
+  if (!isRecord(parsed) || parsed["id"] !== frame.id || parsed["type"] !== frame.eventType || typeof parsed["status"] !== "string" || typeof parsed["timestamp"] !== "string" || typeof parsed["terminal"] !== "boolean" || !Object.hasOwn(parsed, "data")) {
+    throw invalidResponse(response, fallbackRequestId);
+  }
+  return parsed;
+}
+async function* parseSseEvents(stream, response, fallbackRequestId) {
+  let frame = { data: [], eventType: undefined, id: undefined };
+  for await (const line of readSseLines(stream)) {
+    if (line === "") {
+      const event = parseSseEvent(frame, response, fallbackRequestId);
+      if (event)
+        yield event;
+      frame = { data: [], eventType: undefined, id: undefined };
+      continue;
+    }
+    if (line.startsWith(":"))
+      continue;
+    const separator = line.indexOf(":");
+    const field = separator === -1 ? line : line.slice(0, separator);
+    const rawValue = separator === -1 ? "" : line.slice(separator + 1);
+    const value = rawValue.startsWith(" ") ? rawValue.slice(1) : rawValue;
+    if (field === "data")
+      frame.data.push(value);
+    else if (field === "event")
+      frame.eventType = value;
+    else if (field === "id")
+      frame.id = value;
+  }
+  const finalEvent = parseSseEvent(frame, response, fallbackRequestId);
+  if (finalEvent)
+    yield finalEvent;
+}
+
+class CareerMentorClient {
+  baseUrl;
+  timeoutMs;
+  userAgent;
+  token;
+  fetch;
+  constructor(options) {
+    this.baseUrl = normalizeBaseUrl(options.baseUrl);
+    this.token = requireToken(options.token);
+    this.timeoutMs = requirePositiveTimeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    this.userAgent = options.userAgent?.trim() || DEFAULT_USER_AGENT;
+    if (this.userAgent.length > MAX_HEADER_VALUE_LENGTH || CONTROL_CHARACTER.test(this.userAgent)) {
+      invalidConfiguration("Career Mentor SDK userAgent is invalid.");
+    }
+    const fetchImplementation = options.fetch ?? globalThis.fetch;
+    if (typeof fetchImplementation !== "function") {
+      invalidConfiguration("A Fetch API implementation is required.");
+    }
+    this.fetch = fetchImplementation;
+  }
+  async list(options = {}) {
+    return await this.request("/api/v1/capabilities", "GET", undefined, options, [200]);
+  }
+  async get(name, options = {}) {
+    return await this.request(`/api/v1/capabilities/${encodeURIComponent(name)}`, "GET", undefined, options, [200]);
+  }
+  async invoke(name, input, options = {}) {
+    return await this.request(`/api/v1/capabilities/${encodeURIComponent(name)}/invoke`, "POST", serializeJson(input), options, [200, 202]);
+  }
+  async getRun(runId, options = {}) {
+    return await this.request(`/api/v1/runs/${encodeURIComponent(requireRunId(runId))}`, "GET", undefined, options, [200]);
+  }
+  async listRunEvents(runId, options = {}) {
+    return await this.request(runEventsPath(runId, options), "GET", undefined, options, [200]);
+  }
+  async* streamRunEvents(runId, options = {}) {
+    const lastEventId = requireEventCursor(options.lastEventId, "Career Mentor Last-Event-ID cursor");
+    const opened = await this.openRequest(runEventsPath(runId, options), "GET", undefined, options, {
+      accept: "text/event-stream",
+      ...lastEventId ? { lastEventId } : {}
+    });
+    try {
+      if (opened.response.status !== 200) {
+        const payload = await readJson(opened.response, options.requestId);
+        throw apiErrorFromResponse(opened.response, payload, options.requestId);
+      }
+      if (!opened.response.headers.get("content-type")?.toLowerCase().startsWith("text/event-stream")) {
+        throw invalidResponse(opened.response, options.requestId);
+      }
+      if (!opened.response.body)
+        throw invalidResponse(opened.response, options.requestId);
+      for await (const event of parseSseEvents(opened.response.body, opened.response, options.requestId)) {
+        if (opened.controller.signal.aborted)
+          throw opened.controller.signal.reason;
+        yield event;
+      }
+      if (opened.controller.signal.aborted)
+        throw opened.controller.signal.reason;
+    } catch (error) {
+      throw translateTransportError(error, opened.didTimeout(), options);
+    } finally {
+      opened.cleanup();
+    }
+  }
+  async waitForRun(runId, options = {}) {
+    const timeoutMs = requirePositiveTimeout(options.timeoutMs ?? this.timeoutMs);
+    const deadline = Date.now() + timeoutMs;
+    let lastEventId = requireEventCursor(options.lastEventId, "Career Mentor Last-Event-ID cursor");
+    let reconnectAttempt = 0;
+    while (true) {
+      const remainingTimeoutMs = remainingRunWaitTimeout(deadline, options);
+      for await (const event of this.streamRunEvents(runId, {
+        ...options,
+        timeoutMs: remainingTimeoutMs,
+        ...lastEventId ? { lastEventId } : {}
+      })) {
+        remainingRunWaitTimeout(deadline, options);
+        lastEventId = event.id;
+        if (event.terminal)
+          return event;
+      }
+      const reconnectDelayMs = Math.min(RUN_WAIT_RECONNECT_INITIAL_DELAY_MS * 2 ** Math.min(reconnectAttempt, 10), RUN_WAIT_RECONNECT_MAX_DELAY_MS);
+      reconnectAttempt += 1;
+      await waitBeforeRunReconnect(reconnectDelayMs, deadline, options);
+    }
+  }
+  async request(path, method, body, options, acceptedStatuses) {
+    const opened = await this.openRequest(path, method, body, options, {
+      accept: "application/json"
+    });
+    try {
+      const payload = await readJson(opened.response, options.requestId);
+      if (opened.controller.signal.aborted)
+        throw opened.controller.signal.reason;
+      if (!acceptedStatuses.includes(opened.response.status)) {
+        throw apiErrorFromResponse(opened.response, payload, options.requestId);
+      }
+      if (!isRecord(payload))
+        throw invalidResponse(opened.response, options.requestId);
+      return payload;
+    } catch (error) {
+      throw translateTransportError(error, opened.didTimeout(), options);
+    } finally {
+      opened.cleanup();
+    }
+  }
+  async openRequest(path, method, body, options, requestHeaders) {
+    const headers = new Headers({
+      Accept: requestHeaders.accept,
+      Authorization: `Bearer ${this.token}`,
+      "User-Agent": this.userAgent,
+      "X-Career-Mentor-SDK-Version": SDK_VERSION
+    });
+    if (body !== undefined)
+      headers.set("Content-Type", "application/json");
+    setTransportHeader(headers, "X-Request-Id", options.requestId);
+    setTransportHeader(headers, "X-Agent-Session-Id", options.agentSessionId);
+    setTransportHeader(headers, "Idempotency-Key", options.idempotencyKey);
+    setTransportHeader(headers, "Last-Event-ID", requestHeaders.lastEventId);
+    const timeoutMs = requirePositiveTimeout(options.timeoutMs ?? this.timeoutMs);
+    const controller = new AbortController;
+    let didTimeout = false;
+    const forwardAbort = () => controller.abort(options.signal?.reason);
+    if (options.signal?.aborted)
+      forwardAbort();
+    else
+      options.signal?.addEventListener("abort", forwardAbort, { once: true });
+    const timeout = setTimeout(() => {
+      didTimeout = true;
+      controller.abort();
+    }, timeoutMs);
+    const cleanup = () => {
+      clearTimeout(timeout);
+      options.signal?.removeEventListener("abort", forwardAbort);
+    };
+    try {
+      const response = await this.fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        signal: controller.signal,
+        ...body === undefined ? {} : { body }
+      });
+      return {
+        cleanup,
+        controller,
+        didTimeout: () => didTimeout,
+        response
+      };
+    } catch (error) {
+      cleanup();
+      throw translateTransportError(error, didTimeout, options);
+    }
+  }
+}
+
+// src/auth.ts
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, rename, rm, unlink, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+var CAPABILITY_TOKEN_ENV = "CAREER_MENTOR_CAPABILITY_TOKEN";
+var CAPABILITY_TOKEN_FILE_ENV = "CAREER_MENTOR_CAPABILITY_TOKEN_FILE";
+var AUTH_APP_URL_ENV = "CAREER_MENTOR_AUTH_APP_URL";
+var DEFAULT_AUTH_APP_URL = "https://app.uptomic.com";
+var DEFAULT_AUTH_EXPIRES_IN_DAYS = 7;
+var DEFAULT_AUTH_TIMEOUT_MS = 5 * 60 * 1000;
+var MAX_CREDENTIAL_BYTES = 8192;
+var MAX_SCOPE_COUNT = 50;
+var TOKEN_PATTERN = /^cmcp_[A-Za-z0-9_-]+$/;
+var SCOPE_PATTERN = /^[a-z][a-z0-9_]*:[a-z][a-z0-9_]*$/;
+
+class BrowserAuthError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "BrowserAuthError";
+    this.code = code;
+  }
+}
+function isNodeError(error) {
+  return error instanceof Error && "code" in error;
+}
+function requireCapabilityToken(value) {
+  const token = value.trim();
+  if (!(token.length <= MAX_CREDENTIAL_BYTES && TOKEN_PATTERN.test(token))) {
+    throw new BrowserAuthError("AUTH_CREDENTIAL_INVALID", "Career Mentor capability token is invalid.");
+  }
+  return token;
+}
+function defaultCredentialFile() {
+  return join(homedir(), ".career-mentor", "capability-token");
+}
+function resolveCredentialFile(explicitPath, environmentPath) {
+  return explicitPath?.trim() || environmentPath?.trim() || defaultCredentialFile();
+}
+function parseRequestedScopes(value) {
+  if (!value?.trim())
+    return [];
+  const scopes = Array.from(new Set(value.split(/[,\s]+/).map((scope) => scope.trim()).filter(Boolean)));
+  if (scopes.length > MAX_SCOPE_COUNT || scopes.some((scope) => !SCOPE_PATTERN.test(scope))) {
+    throw new BrowserAuthError("AUTH_INPUT_INVALID", "Requested capability scopes are invalid.");
+  }
+  return scopes;
+}
+function parseSecureAppUrl(value) {
+  let appUrl;
+  try {
+    appUrl = new URL(value);
+  } catch {
+    throw new BrowserAuthError("AUTH_INPUT_INVALID", "Career Mentor auth app URL is invalid.");
+  }
+  const loopbackHost = appUrl.hostname === "localhost" || appUrl.hostname === "127.0.0.1" || appUrl.hostname === "[::1]";
+  if (!["http:", "https:"].includes(appUrl.protocol) || appUrl.protocol === "http:" && !loopbackHost || appUrl.username || appUrl.password || appUrl.search || appUrl.hash) {
+    throw new BrowserAuthError("AUTH_INPUT_INVALID", "Career Mentor auth app URL must use HTTPS unless it targets local loopback.");
+  }
+  return appUrl;
+}
+function buildAgentAuthUrl(params) {
+  const appUrl = parseSecureAppUrl(params.appUrl);
+  if (!(Number.isInteger(params.expiresInDays) && params.expiresInDays >= 1)) {
+    throw new BrowserAuthError("AUTH_INPUT_INVALID", "Token expiry must be a positive integer.");
+  }
+  const url = new URL("/account/agent-auth", appUrl);
+  url.searchParams.set("client", params.clientName);
+  url.searchParams.set("code_challenge", params.codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("expires_in_days", String(params.expiresInDays));
+  url.searchParams.set("redirect_uri", params.redirectUri);
+  if (params.scopes.length > 0)
+    url.searchParams.set("scope", params.scopes.join(" "));
+  url.searchParams.set("state", params.state);
+  return url.toString();
+}
+async function readManagedCredential(filePath) {
+  let handle;
+  try {
+    const noFollow = process.platform === "win32" ? 0 : constants.O_NOFOLLOW;
+    handle = await open(filePath, constants.O_RDONLY | noFollow);
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT")
+      return;
+    throw new BrowserAuthError("AUTH_FILE_INVALID", "Managed credential file could not be opened.");
+  }
+  try {
+    const metadata = await handle.stat();
+    if (!metadata.isFile() || metadata.size > MAX_CREDENTIAL_BYTES) {
+      throw new BrowserAuthError("AUTH_FILE_INVALID", "Managed credential file is invalid.");
+    }
+    if (process.platform !== "win32" && (metadata.mode & 63) !== 0) {
+      throw new BrowserAuthError("AUTH_FILE_PERMISSIONS", "Managed credential file permissions must be 0600.");
+    }
+    return requireCapabilityToken(await handle.readFile("utf8"));
+  } finally {
+    await handle.close();
+  }
+}
+async function resolveCredential(params) {
+  if (params.flagToken?.trim()) {
+    return { source: "--token", token: requireCapabilityToken(params.flagToken) };
+  }
+  if (params.envToken?.trim()) {
+    return {
+      source: "CAREER_MENTOR_CAPABILITY_TOKEN",
+      token: requireCapabilityToken(params.envToken)
+    };
+  }
+  const token = await readManagedCredential(params.credentialFile);
+  return token ? { source: "managed_file", token } : undefined;
+}
+async function writeCredentialFile(filePath, token) {
+  const validatedToken = requireCapabilityToken(token);
+  const directory = dirname(filePath);
+  const temporaryFile = join(directory, `.capability-token.${process.pid}.${randomBytes(8).toString("hex")}.tmp`);
+  try {
+    await mkdir(directory, { mode: 448, recursive: true });
+    await writeFile(temporaryFile, `${validatedToken}
+`, {
+      flag: "wx",
+      mode: 384
+    });
+    await chmod(temporaryFile, 384);
+    await rename(temporaryFile, filePath);
+    await chmod(filePath, 384);
+  } catch (error) {
+    if (error instanceof BrowserAuthError)
+      throw error;
+    throw new BrowserAuthError("AUTH_FILE_INVALID", "Managed credential file could not be written.");
+  } finally {
+    await rm(temporaryFile, { force: true });
+  }
+}
+async function logoutCredential(filePath) {
+  try {
+    const metadata = await lstat(filePath);
+    if (metadata.isDirectory()) {
+      throw new BrowserAuthError("AUTH_FILE_INVALID", "Managed credential path is not a file.");
+    }
+    await unlink(filePath);
+    return { removed: true };
+  } catch (error) {
+    if (error instanceof BrowserAuthError)
+      throw error;
+    if (isNodeError(error) && error.code === "ENOENT")
+      return { removed: false };
+    throw new BrowserAuthError("AUTH_FILE_INVALID", "Managed credential file could not be removed.");
+  }
+}
+function sendHtml(response, status, message) {
+  response.writeHead(status, {
+    "cache-control": "no-store",
+    "content-security-policy": "default-src 'none'; script-src 'unsafe-inline'",
+    "content-type": "text/html; charset=utf-8",
+    "referrer-policy": "no-referrer",
+    "x-content-type-options": "nosniff"
+  });
+  response.end(`<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title>Career Mentor Agent Access</title>
+    <script>history.replaceState(null, document.title, location.pathname);</script>
+  </head>
+  <body>
+    <h1>${message}</h1>
+    <p>This window can be closed.</p>
+  </body>
+</html>`);
+}
+function listen(server, port) {
+  return new Promise((resolve, reject) => {
+    const onError = () => reject(new BrowserAuthError("AUTH_SERVER_FAILED", "Loopback server failed."));
+    server.once("error", onError);
+    server.listen(port ?? 0, "127.0.0.1", () => {
+      server.off("error", onError);
+      resolve();
+    });
+  });
+}
+function closeServer(server) {
+  if (!server.listening)
+    return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    server.close((error) => {
+      if (error)
+        reject(new BrowserAuthError("AUTH_SERVER_FAILED", "Loopback server failed."));
+      else
+        resolve();
+    });
+  });
+}
+async function startLoopbackCallbackServer(params) {
+  if (!(params.state && Number.isFinite(params.timeoutMs) && params.timeoutMs > 0)) {
+    throw new BrowserAuthError("AUTH_SERVER_FAILED", "Loopback server configuration is invalid.");
+  }
+  let settled = false;
+  let timeout;
+  let resolveCallback = () => {
+    return;
+  };
+  let rejectCallback = () => {
+    return;
+  };
+  const waitForCallback = new Promise((resolve, reject) => {
+    resolveCallback = resolve;
+    rejectCallback = reject;
+  });
+  const settleSuccess = (token) => {
+    if (settled)
+      return;
+    settled = true;
+    if (timeout)
+      clearTimeout(timeout);
+    resolveCallback(token);
+  };
+  const settleError = (error) => {
+    if (settled)
+      return;
+    settled = true;
+    if (timeout)
+      clearTimeout(timeout);
+    rejectCallback(error);
+  };
+  const abort = () => settleError(new BrowserAuthError("AUTH_ABORTED", "Browser authorization was aborted."));
+  const server = createServer((request, response) => {
+    const requestUrl = new URL(request.url ?? "/", "http://127.0.0.1");
+    if (request.method !== "GET" || requestUrl.pathname !== "/callback") {
+      sendHtml(response, 404, "Unknown callback path.");
+      return;
+    }
+    if (requestUrl.searchParams.get("error")) {
+      sendHtml(response, 400, "Agent token authorization failed.");
+      settleError(new BrowserAuthError("AUTH_CALLBACK_FAILED", "Browser authorization failed."));
+      return;
+    }
+    if (requestUrl.searchParams.get("state") !== params.state) {
+      sendHtml(response, 400, "Invalid authorization state.");
+      settleError(new BrowserAuthError("AUTH_STATE_MISMATCH", "Browser authorization state did not match."));
+      return;
+    }
+    const code = requestUrl.searchParams.get("code");
+    if (!(code && /^[A-Za-z0-9_-]{8,512}$/.test(code))) {
+      sendHtml(response, 400, "Missing or invalid authorization code.");
+      settleError(new BrowserAuthError("AUTH_CALLBACK_FAILED", "Browser authorization code was invalid."));
+      return;
+    }
+    sendHtml(response, 200, "Agent token authorized. You can return to the terminal.");
+    settleSuccess({ code });
+  });
+  try {
+    await listen(server, params.port);
+  } catch (error) {
+    await closeServer(server);
+    throw error;
+  }
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    await closeServer(server);
+    throw new BrowserAuthError("AUTH_SERVER_FAILED", "Loopback callback port was unavailable.");
+  }
+  timeout = setTimeout(() => settleError(new BrowserAuthError("AUTH_TIMEOUT", "Browser authorization timed out.")), params.timeoutMs);
+  if (params.signal?.aborted)
+    abort();
+  else
+    params.signal?.addEventListener("abort", abort, { once: true });
+  server.on("error", () => {
+    settleError(new BrowserAuthError("AUTH_SERVER_FAILED", "Loopback server failed."));
+  });
+  return {
+    close: async () => {
+      if (timeout)
+        clearTimeout(timeout);
+      params.signal?.removeEventListener("abort", abort);
+      await closeServer(server);
+    },
+    port: address.port,
+    redirectUri: `http://127.0.0.1:${address.port}/callback`,
+    waitForCallback
+  };
+}
+function browserLaunchCommand(url, platform = process.platform) {
+  if (platform === "darwin")
+    return { command: "open", args: [url] };
+  if (platform === "win32") {
+    return { command: "rundll32.exe", args: ["url.dll,FileProtocolHandler", url] };
+  }
+  return { command: "xdg-open", args: [url] };
+}
+async function openUrlInBrowser(url) {
+  const { args, command } = browserLaunchCommand(url);
+  await new Promise((resolve, reject) => {
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.once("error", () => reject(new BrowserAuthError("AUTH_BROWSER_OPEN_FAILED", "Browser could not be opened.")));
+    child.once("spawn", () => {
+      child.unref();
+      resolve();
+    });
+  });
+}
+async function exchangeAuthorizationCode(params) {
+  const controller = new AbortController;
+  let timedOut = false;
+  const forwardAbort = () => controller.abort(params.signal?.reason);
+  if (params.signal?.aborted)
+    forwardAbort();
+  else
+    params.signal?.addEventListener("abort", forwardAbort, { once: true });
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, params.timeoutMs);
+  try {
+    const appUrl = parseSecureAppUrl(params.appUrl);
+    const exchangeInput = {
+      code: params.code,
+      codeVerifier: params.codeVerifier,
+      redirectUri: params.redirectUri
+    };
+    const response = await params.fetch(new URL("/api/v1/auth/agent/exchange", appUrl), {
+      method: "POST",
+      headers: { Accept: "application/json", "Content-Type": "application/json" },
+      body: JSON.stringify(exchangeInput),
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      if (response.status === 408 || response.status === 429 || response.status >= 500) {
+        throw new BrowserAuthError("AUTH_SERVER_FAILED", "Authorization exchange is temporarily unavailable.");
+      }
+      if (response.status === 422) {
+        throw new BrowserAuthError("AUTH_INPUT_INVALID", "Authorization exchange input was invalid.");
+      }
+      throw new BrowserAuthError("AUTH_CALLBACK_FAILED", "Authorization exchange was rejected.");
+    }
+    let payload;
+    try {
+      payload = await response.json();
+    } catch {
+      throw new BrowserAuthError("AUTH_CALLBACK_FAILED", "Authorization exchange was invalid.");
+    }
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload) || !Array.isArray(payload["scopes"])) {
+      throw new BrowserAuthError("AUTH_CALLBACK_FAILED", "Authorization exchange was invalid.");
+    }
+    const record = payload;
+    const scopes = record["scopes"];
+    const expiresAt = record["expiresAt"];
+    if (typeof record["token"] !== "string" || typeof record["tokenPrefix"] !== "string" || !record["token"].startsWith(`${record["tokenPrefix"]}_`) || !Array.isArray(scopes) || scopes.some((scope) => typeof scope !== "string") || typeof expiresAt !== "string" || Number.isNaN(Date.parse(expiresAt))) {
+      throw new BrowserAuthError("AUTH_CALLBACK_FAILED", "Authorization exchange was invalid.");
+    }
+    return {
+      expiresAt,
+      scopes,
+      token: requireCapabilityToken(record["token"]),
+      tokenPrefix: record["tokenPrefix"]
+    };
+  } catch (error) {
+    if (timedOut) {
+      throw new BrowserAuthError("AUTH_TIMEOUT", "Browser authorization timed out.");
+    }
+    if (params.signal?.aborted) {
+      throw new BrowserAuthError("AUTH_ABORTED", "Browser authorization was aborted.");
+    }
+    if (error instanceof BrowserAuthError)
+      throw error;
+    throw new BrowserAuthError("AUTH_SERVER_FAILED", "Authorization exchange failed.");
+  } finally {
+    clearTimeout(timeout);
+    params.signal?.removeEventListener("abort", forwardAbort);
+  }
+}
+async function runBrowserAuthLogin(options, overrides = {}) {
+  const startedAt = Date.now();
+  const state = (overrides.generateState ?? (() => randomBytes(32).toString("base64url")))();
+  const codeVerifier = (overrides.generateCodeVerifier ?? (() => randomBytes(48).toString("base64url")))();
+  if (!/^[A-Za-z0-9._~-]{43,128}$/.test(codeVerifier)) {
+    throw new BrowserAuthError("AUTH_INPUT_INVALID", "PKCE code verifier is invalid.");
+  }
+  const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url");
+  const callback = await startLoopbackCallbackServer({
+    ...options.port !== undefined ? { port: options.port } : {},
+    ...options.signal ? { signal: options.signal } : {},
+    state,
+    timeoutMs: options.timeoutMs
+  });
+  try {
+    const authorizationUrl = buildAgentAuthUrl({
+      appUrl: options.appUrl,
+      clientName: options.clientName,
+      codeChallenge,
+      expiresInDays: options.expiresInDays,
+      redirectUri: callback.redirectUri,
+      scopes: options.scopes,
+      state
+    });
+    await options.onLaunch({
+      authorizationUrl,
+      openBrowser: options.openBrowser,
+      redirectUri: callback.redirectUri
+    });
+    if (options.openBrowser)
+      await (overrides.openUrl ?? openUrlInBrowser)(authorizationUrl);
+    const captured = await callback.waitForCallback;
+    const remainingTimeoutMs = Math.max(1, options.timeoutMs - (Date.now() - startedAt));
+    const exchanged = await exchangeAuthorizationCode({
+      appUrl: options.appUrl,
+      code: captured.code,
+      codeVerifier,
+      fetch: overrides.fetch ?? globalThis.fetch,
+      redirectUri: callback.redirectUri,
+      ...options.signal ? { signal: options.signal } : {},
+      timeoutMs: remainingTimeoutMs
+    });
+    await writeCredentialFile(options.credentialFile, exchanged.token);
+    return {
+      credentialFile: options.credentialFile,
+      expiresAt: exchanged.expiresAt,
+      scopes: [...exchanged.scopes]
+    };
+  } finally {
+    await callback.close();
+  }
+}
+
+// src/cli.ts
+var CLI_VERSION = "0.1.0";
+var DEFAULT_API_URL = "https://app.uptomic.com";
+var CLI_EXIT_CODE = Object.freeze({
+  SUCCESS: 0,
+  INTERNAL: 1,
+  USAGE: 2,
+  AUTH: 3,
+  NOT_FOUND: 4,
+  CONFLICT_OR_LIMIT: 5,
+  UNAVAILABLE: 6,
+  API_ERROR: 7,
+  RUN_FAILED: 8,
+  RUN_CANCELLED: 9,
+  INTERRUPTED: 130
+});
+var TERMINAL_RUN_STATUS = {
+  SUCCEEDED: "succeeded",
+  FAILED: "failed",
+  CANCELLED: "cancelled"
+};
+var CONTROL_CHARACTERS2 = /[\u0000-\u001f\u007f]/g;
+var CONTROL_CHARACTER2 = /[\u0000-\u001f\u007f]/;
+var MAX_SAFE_MESSAGE_LENGTH = 500;
+var MAX_TIMEOUT_MS = 2147483647;
+var MAX_ARTIFACT_UPLOAD_BYTES = 10485760;
+var ARTIFACT_CONTENT_TYPES = new Map([
+  [".doc", "application/msword"],
+  [".docx", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"],
+  [".jpeg", "image/jpeg"],
+  [".jpg", "image/jpeg"],
+  [".md", "text/markdown"],
+  [".pdf", "application/pdf"],
+  [".png", "image/png"],
+  [".txt", "text/plain"],
+  [".webp", "image/webp"]
+]);
+var ARTIFACT_TYPES = new Set([
+  "resume",
+  "certificate",
+  "portfolio",
+  "recommendation",
+  "performance_review",
+  "award",
+  "course_completion",
+  "project",
+  "publication",
+  "other"
+]);
+var VALUE_FLAGS = new Set([
+  "agent-session-id",
+  "after",
+  "app-url",
+  "client",
+  "credential-file",
+  "endpoint",
+  "expires-in-days",
+  "idempotency-key",
+  "input",
+  "input-file",
+  "last-event-id",
+  "limit",
+  "name",
+  "port",
+  "request-id",
+  "scopes",
+  "timeout-ms",
+  "timeout-seconds",
+  "token",
+  "type"
+]);
+var BOOLEAN_FLAGS = new Set(["create", "help", "no-open", "version"]);
+var TRANSPORT_FLAGS = new Set([
+  "agent-session-id",
+  "credential-file",
+  "endpoint",
+  "request-id",
+  "timeout-ms",
+  "token"
+]);
+
+class CliUsageError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "CliUsageError";
+    this.code = code;
+  }
+}
+function usageError(code, message) {
+  throw new CliUsageError(code, message);
+}
+function parseFlagToken(argv, index) {
+  const token = argv[index];
+  if (!token?.startsWith("--") || token === "--") {
+    usageError("INVALID_FLAG", "Expected a long-form CLI flag.");
+  }
+  const separator = token.indexOf("=");
+  const name = token.slice(2, separator === -1 ? undefined : separator);
+  const inlineValue = separator === -1 ? undefined : token.slice(separator + 1);
+  if (!(VALUE_FLAGS.has(name) || BOOLEAN_FLAGS.has(name))) {
+    usageError("UNKNOWN_FLAG", `Unknown flag --${name}.`);
+  }
+  if (BOOLEAN_FLAGS.has(name)) {
+    if (inlineValue !== undefined) {
+      usageError("INVALID_FLAG", `Flag --${name} does not accept a value.`);
+    }
+    return { consumed: 1, name, value: true };
+  }
+  const nextValue = inlineValue ?? argv[index + 1];
+  if (nextValue === undefined || inlineValue === undefined && nextValue.startsWith("--")) {
+    usageError("MISSING_FLAG_VALUE", `Flag --${name} requires a value.`);
+  }
+  return { consumed: inlineValue === undefined ? 2 : 1, name, value: nextValue };
+}
+function parseArgs(argv) {
+  const flags = {};
+  const positionals = [];
+  let parseFlags = true;
+  for (let index = 0;index < argv.length; ) {
+    const token = argv[index];
+    if (token === undefined)
+      break;
+    if (parseFlags && token === "--") {
+      parseFlags = false;
+      index += 1;
+      continue;
+    }
+    if (parseFlags && token.startsWith("--")) {
+      const parsed = parseFlagToken(argv, index);
+      if (flags[parsed.name] !== undefined) {
+        usageError("DUPLICATE_FLAG", `Flag --${parsed.name} may only be provided once.`);
+      }
+      flags[parsed.name] = parsed.value;
+      index += parsed.consumed;
+      continue;
+    }
+    positionals.push(token);
+    index += 1;
+  }
+  return { flags, positionals };
+}
+function stringFlag(flags, name) {
+  const value = flags[name];
+  return typeof value === "string" ? value : undefined;
+}
+function cleanOptional(value) {
+  const normalized = value?.trim();
+  return normalized ? normalized : undefined;
+}
+function normalizeEndpoint(value) {
+  let endpoint;
+  try {
+    endpoint = new URL(value);
+  } catch {
+    usageError("INVALID_ENDPOINT", "The API endpoint must be an absolute HTTP(S) URL.");
+  }
+  if (!["http:", "https:"].includes(endpoint.protocol)) {
+    usageError("INVALID_ENDPOINT", "The API endpoint must use HTTP or HTTPS.");
+  }
+  if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {
+    usageError("INVALID_ENDPOINT", "The API endpoint must not include credentials, query, or hash.");
+  }
+  endpoint.pathname = endpoint.pathname.replace(/\/+$/, "");
+  return endpoint.toString().replace(/\/$/, "");
+}
+function parseTimeout(value) {
+  if (value === undefined)
+    return 30000;
+  if (!/^\d+$/.test(value)) {
+    usageError("INVALID_TIMEOUT", "Timeout must be a positive integer in milliseconds.");
+  }
+  const timeoutMs = Number(value);
+  if (!(timeoutMs > 0 && timeoutMs <= MAX_TIMEOUT_MS)) {
+    usageError("INVALID_TIMEOUT", `Timeout must be between 1 and ${MAX_TIMEOUT_MS} milliseconds.`);
+  }
+  return timeoutMs;
+}
+function parseIntegerFlag(flags, name, defaultValue, minimum, maximum) {
+  const rawValue = cleanOptional(stringFlag(flags, name));
+  if (rawValue === undefined)
+    return defaultValue;
+  if (!/^\d+$/.test(rawValue)) {
+    usageError("INVALID_FLAG_VALUE", `Flag --${name} must be an integer.`);
+  }
+  const value = Number(rawValue);
+  if (!(value >= minimum && value <= maximum)) {
+    usageError("INVALID_FLAG_VALUE", `Flag --${name} must be between ${minimum} and ${maximum}.`);
+  }
+  return value;
+}
+function authClientName(value) {
+  const clientName = (value ?? "Career Mentor CLI").replace(CONTROL_CHARACTERS2, "").replace(/\s+/g, " ").trim();
+  return (clientName || "Career Mentor CLI").slice(0, 80);
+}
+async function resolveConfig(flags, env) {
+  const flagToken = cleanOptional(stringFlag(flags, "token"));
+  const envToken = cleanOptional(env[CAPABILITY_TOKEN_ENV]);
+  const credentialFile = resolveCredentialFile(cleanOptional(stringFlag(flags, "credential-file")), cleanOptional(env[CAPABILITY_TOKEN_FILE_ENV]));
+  const credential = await resolveCredential({
+    credentialFile,
+    ...envToken ? { envToken } : {},
+    ...flagToken ? { flagToken } : {}
+  });
+  const endpoint = normalizeEndpoint(cleanOptional(stringFlag(flags, "endpoint")) ?? cleanOptional(env["CAREER_MENTOR_API_URL"]) ?? DEFAULT_API_URL);
+  return {
+    agentSessionId: cleanOptional(stringFlag(flags, "agent-session-id")) ?? cleanOptional(env["CAREER_MENTOR_AGENT_SESSION_ID"]),
+    credentialFile,
+    endpoint,
+    idempotencyKey: cleanOptional(stringFlag(flags, "idempotency-key")) ?? cleanOptional(env["CAREER_MENTOR_IDEMPOTENCY_KEY"]),
+    requestId: cleanOptional(stringFlag(flags, "request-id")) ?? cleanOptional(env["CAREER_MENTOR_REQUEST_ID"]),
+    timeoutMs: parseTimeout(cleanOptional(stringFlag(flags, "timeout-ms")) ?? cleanOptional(env["CAREER_MENTOR_TIMEOUT_MS"])),
+    token: credential?.token,
+    tokenSource: credential?.source ?? null
+  };
+}
+function requireToken2(config) {
+  if (!config.token) {
+    usageError("MISSING_CAPABILITY_TOKEN", "Run cm auth login, set CAREER_MENTOR_CAPABILITY_TOKEN, or pass --token.");
+  }
+  return config.token;
+}
+function validateFlags(flags, allowed) {
+  for (const name of Object.keys(flags)) {
+    if (!(allowed.has(name) || name === "help" || name === "version")) {
+      usageError("UNSUPPORTED_FLAG", `Flag --${name} is not valid for this command.`);
+    }
+  }
+}
+function expectPositionals(positionals, expected, usage) {
+  if (positionals.length !== expected) {
+    usageError("INVALID_COMMAND", `Usage: ${usage}`);
+  }
+}
+function makeClient(config, fetch) {
+  return new CareerMentorClient({
+    baseUrl: config.endpoint,
+    token: requireToken2(config),
+    timeoutMs: config.timeoutMs,
+    userAgent: `career-mentor-cli/${CLI_VERSION}`,
+    ...fetch ? { fetch } : {}
+  });
+}
+function requestOptions(config, signal) {
+  return {
+    timeoutMs: config.timeoutMs,
+    ...config.requestId ? { requestId: config.requestId } : {},
+    ...config.agentSessionId ? { agentSessionId: config.agentSessionId } : {},
+    ...signal ? { signal } : {}
+  };
+}
+async function defaultReadStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin)
+    chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf8");
+}
+function parseInputJson(value) {
+  let parsed;
+  try {
+    parsed = JSON.parse(value.replace(/^\uFEFF/, ""));
+  } catch {
+    usageError("INVALID_INPUT_JSON", "Capability input must be valid JSON.");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    usageError("INVALID_INPUT_JSON", "Capability input must be a JSON object.");
+  }
+  return parsed;
+}
+async function readCapabilityInput(flags, readFile, readStdin) {
+  const inline = stringFlag(flags, "input");
+  const inputFile = stringFlag(flags, "input-file");
+  if (inline !== undefined && inputFile !== undefined) {
+    usageError("DUPLICATE_INPUT", "Use either --input or --input-file, not both.");
+  }
+  if (inline !== undefined)
+    return parseInputJson(inline);
+  if (inputFile === undefined)
+    return {};
+  let contents;
+  try {
+    contents = inputFile === "-" ? await readStdin() : await readFile(inputFile);
+  } catch {
+    usageError("INPUT_READ_FAILED", "Could not read the capability input file.");
+  }
+  return parseInputJson(contents);
+}
+function sanitizeMessage(message, secrets) {
+  let sanitized = message.replace(CONTROL_CHARACTERS2, " ").trim();
+  for (const secret of [...secrets].filter(Boolean).sort((a, b) => b.length - a.length)) {
+    sanitized = sanitized.split(secret).join("[REDACTED]");
+  }
+  return sanitized.slice(0, MAX_SAFE_MESSAGE_LENGTH) || "Career Mentor CLI request failed.";
+}
+function apiExitCode(status) {
+  if (status === 400 || status === 422)
+    return CLI_EXIT_CODE.USAGE;
+  if (status === 401 || status === 403)
+    return CLI_EXIT_CODE.AUTH;
+  if (status === 404)
+    return CLI_EXIT_CODE.NOT_FOUND;
+  if (status === 409 || status === 429)
+    return CLI_EXIT_CODE.CONFLICT_OR_LIMIT;
+  if (status === 408 || status >= 500)
+    return CLI_EXIT_CODE.UNAVAILABLE;
+  return CLI_EXIT_CODE.API_ERROR;
+}
+function terminalRunExitCode(event) {
+  if (event.status === TERMINAL_RUN_STATUS.SUCCEEDED)
+    return CLI_EXIT_CODE.SUCCESS;
+  if (event.status === TERMINAL_RUN_STATUS.FAILED)
+    return CLI_EXIT_CODE.RUN_FAILED;
+  if (event.status === TERMINAL_RUN_STATUS.CANCELLED)
+    return CLI_EXIT_CODE.RUN_CANCELLED;
+  throw new CareerMentorError("Career Mentor returned an invalid terminal run event.", {
+    code: "INVALID_RESPONSE"
+  });
+}
+function mapError(error, secrets) {
+  if (error instanceof CliUsageError) {
+    return {
+      code: error.code,
+      exitCode: CLI_EXIT_CODE.USAGE,
+      message: sanitizeMessage(error.message, secrets)
+    };
+  }
+  if (error instanceof BrowserAuthError) {
+    const exitCode = error.code === "AUTH_ABORTED" ? CLI_EXIT_CODE.INTERRUPTED : error.code === "AUTH_TIMEOUT" || error.code === "AUTH_BROWSER_OPEN_FAILED" || error.code === "AUTH_SERVER_FAILED" ? CLI_EXIT_CODE.UNAVAILABLE : error.code === "AUTH_STATE_MISMATCH" || error.code === "AUTH_CALLBACK_FAILED" ? CLI_EXIT_CODE.AUTH : CLI_EXIT_CODE.USAGE;
+    return {
+      code: error.code,
+      exitCode,
+      message: sanitizeMessage(error.message, secrets)
+    };
+  }
+  if (error instanceof CareerMentorRequestError) {
+    const exitCode = error.code === "REQUEST_ABORTED" ? CLI_EXIT_CODE.INTERRUPTED : error.code === "NETWORK_ERROR" || error.code === "TIMEOUT" ? CLI_EXIT_CODE.UNAVAILABLE : CLI_EXIT_CODE.USAGE;
+    return {
+      code: error.code,
+      exitCode,
+      message: sanitizeMessage(error.message, secrets),
+      ...error.requestId ? { requestId: error.requestId } : {}
+    };
+  }
+  if (error instanceof CareerMentorApiError) {
+    return {
+      code: error.code,
+      exitCode: apiExitCode(error.status),
+      message: sanitizeMessage(error.message, secrets),
+      status: error.status,
+      ...error.requestId ? { requestId: error.requestId } : {},
+      ...error.retryAfter !== undefined ? { retryAfter: error.retryAfter } : {}
+    };
+  }
+  if (error instanceof CareerMentorError) {
+    return {
+      code: error.code,
+      exitCode: CLI_EXIT_CODE.API_ERROR,
+      message: sanitizeMessage(error.message, secrets),
+      ...error.requestId ? { requestId: error.requestId } : {}
+    };
+  }
+  return {
+    code: "CLI_INTERNAL_ERROR",
+    exitCode: CLI_EXIT_CODE.INTERNAL,
+    message: "Career Mentor CLI failed."
+  };
+}
+function helpDocument() {
+  return {
+    cli: "career-mentor",
+    version: CLI_VERSION,
+    sdkVersion: SDK_VERSION,
+    usage: "cm <command> [arguments] [flags]",
+    commands: {
+      "auth login": {
+        usage: "cm auth login [--no-open] [--scopes <csv>] [--expires-in-days <days>]",
+        description: "Authorize and store a scoped user token through a loopback browser handoff."
+      },
+      "auth status": {
+        usage: "cm auth status",
+        description: "Show credential source and status without exposing the token."
+      },
+      "auth logout": {
+        usage: "cm auth logout",
+        description: "Delete only the locally managed credential file."
+      },
+      doctor: { usage: "cm doctor", description: "Verify configuration and hosted API access." },
+      "capabilities list": {
+        usage: "cm capabilities list",
+        description: "List capabilities available to the current token."
+      },
+      "capabilities describe": {
+        usage: "cm capabilities describe <name>",
+        description: "Return the exact manifest and JSON schemas for one capability."
+      },
+      invoke: {
+        usage: "cm invoke <name> [--input <json> | --input-file <path|->]",
+        description: "Invoke a published capability without polling."
+      },
+      "artifacts upload": {
+        usage: "cm artifacts upload <path> [--create --type <artifact-type> [--name <name>]]",
+        description: "Upload and register a local Career Vault file; create and analyze an artifact only when --create is explicit."
+      },
+      "photos list": {
+        usage: "cm photos list",
+        description: "List current-user profile photos in display order."
+      },
+      "photos add": {
+        usage: "cm photos add <registered-file-id>",
+        description: "Attach an already registered current-user image file."
+      },
+      "photos default": {
+        usage: "cm photos default <photo-id>",
+        description: "Set one owned profile photo as default."
+      },
+      "photos reorder": {
+        usage: "cm photos reorder <photo-id> [photo-id...]",
+        description: "Replace the complete owned photo order."
+      },
+      "photos delete": {
+        usage: "cm photos delete <photo-id>",
+        description: "Prepare reviewed profile-photo deletion; this command never auto-confirms."
+      },
+      "files delete": {
+        usage: "cm files delete <registered-file-id>",
+        description: "Prepare reviewed registered-file deletion only when it has no authoritative references."
+      },
+      "runs get": {
+        usage: "cm runs get <run-id>",
+        description: "Get current status for a user-owned asynchronous run."
+      },
+      "runs events": {
+        usage: "cm runs events <run-id> [--after <cursor>] [--limit <count>]",
+        description: "Replay a bounded page of run events."
+      },
+      "runs wait": {
+        usage: "cm runs wait <run-id> [--after <cursor>] [--last-event-id <cursor>] [--limit <count>]",
+        description: "Reconnect across bounded streams, print one terminal event, and return its outcome exit code."
+      },
+      "runs watch": {
+        usage: "cm runs watch <run-id> [--after <cursor>] [--last-event-id <cursor>] [--limit <count>]",
+        description: "Subscribe to run events as JSON Lines until the SSE session closes."
+      }
+    },
+    flags: {
+      "--endpoint": "Career Mentor origin; defaults to CAREER_MENTOR_API_URL or production.",
+      "--token": "Capability token; prefer CAREER_MENTOR_CAPABILITY_TOKEN to avoid shell history.",
+      "--timeout-ms": "Positive request timeout; runs wait applies one overall budget.",
+      "--request-id": "Request correlation ID.",
+      "--agent-session-id": "Agent session correlation ID.",
+      "--idempotency-key": "Invocation idempotency key.",
+      "--input": "Inline capability input JSON object.",
+      "--input-file": "Capability input JSON file; use - for stdin.",
+      "--create": "Create and analyze a Career Vault artifact after file registration.",
+      "--type": "Artifact type required with --create.",
+      "--name": "Artifact display name used with --create; defaults to the filename.",
+      "--after": "Replay events strictly after a Redis stream cursor.",
+      "--last-event-id": "SSE reconnect cursor; takes precedence over --after.",
+      "--limit": "Run event page size from 1 to 1000.",
+      "--credential-file": "Managed token file; defaults to ~/.career-mentor/capability-token.",
+      "--app-url": "Career Mentor browser authorization origin.",
+      "--scopes": "Explicit comma- or whitespace-separated token scopes.",
+      "--expires-in-days": "Requested browser-auth token lifetime.",
+      "--timeout-seconds": "Bounded browser callback wait.",
+      "--no-open": "Print the authorization URL diagnostic without opening a browser."
+    },
+    environment: {
+      CAREER_MENTOR_API_URL: "Hosted API origin.",
+      CAREER_MENTOR_CAPABILITY_TOKEN: "Managed user capability token.",
+      CAREER_MENTOR_CAPABILITY_TOKEN_FILE: "Managed capability token file.",
+      CAREER_MENTOR_AUTH_APP_URL: "Browser authorization origin.",
+      CAREER_MENTOR_TIMEOUT_MS: "Default request timeout in milliseconds.",
+      CAREER_MENTOR_REQUEST_ID: "Default request correlation ID.",
+      CAREER_MENTOR_AGENT_SESSION_ID: "Default agent session correlation ID.",
+      CAREER_MENTOR_IDEMPOTENCY_KEY: "Default invocation idempotency key."
+    },
+    exitCodes: {
+      [CLI_EXIT_CODE.SUCCESS]: "success",
+      [CLI_EXIT_CODE.INTERNAL]: "unexpected_internal_error",
+      [CLI_EXIT_CODE.USAGE]: "usage_or_input",
+      [CLI_EXIT_CODE.AUTH]: "authentication_or_authorization",
+      [CLI_EXIT_CODE.NOT_FOUND]: "not_found",
+      [CLI_EXIT_CODE.CONFLICT_OR_LIMIT]: "conflict_or_rate_limit",
+      [CLI_EXIT_CODE.UNAVAILABLE]: "network_timeout_or_service_unavailable",
+      [CLI_EXIT_CODE.API_ERROR]: "other_api_error",
+      [CLI_EXIT_CODE.RUN_FAILED]: "capability_run_failed",
+      [CLI_EXIT_CODE.RUN_CANCELLED]: "capability_run_cancelled",
+      [CLI_EXIT_CODE.INTERRUPTED]: "interrupted"
+    }
+  };
+}
+function writeJson(write, value) {
+  write(`${JSON.stringify(value)}
+`);
+}
+async function invokePublishedCapability(client, name, input, options) {
+  return await client.invoke(name, input, options);
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function capabilityResultData(value, capabilityName) {
+  const result = isRecord2(value) ? value["result"] : undefined;
+  const data = isRecord2(result) ? result["data"] : undefined;
+  if (!isRecord2(data)) {
+    throw new CareerMentorError(`Career Mentor returned invalid ${capabilityName} data.`, {
+      code: "INVALID_RESPONSE"
+    });
+  }
+  return data;
+}
+function artifactContentType(filePath) {
+  const extension = extname(filePath).toLowerCase();
+  const contentType = ARTIFACT_CONTENT_TYPES.get(extension);
+  if (!contentType) {
+    usageError("UNSUPPORTED_FILE_TYPE", "Supported artifact files are PDF, DOC, DOCX, JPEG, PNG, WebP, Markdown, and plain text.");
+  }
+  return contentType;
+}
+function artifactType(flags) {
+  const type = cleanOptional(stringFlag(flags, "type"));
+  if (type !== undefined && !ARTIFACT_TYPES.has(type)) {
+    usageError("INVALID_ARTIFACT_TYPE", `Unsupported artifact type: ${type}.`);
+  }
+  return type;
+}
+function isLoopbackHost(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+}
+function parseUploadAuthorization(response, expected) {
+  const data = capabilityResultData(response, "upload authorization");
+  const requiredHeaders = data["requiredHeaders"];
+  const uploadUrl = data["uploadUrl"];
+  const s3Key = data["s3Key"];
+  if (typeof uploadUrl !== "string" || typeof s3Key !== "string" || !isRecord2(requiredHeaders) || requiredHeaders["contentType"] !== expected.contentType || requiredHeaders["contentLength"] !== expected.size) {
+    throw new CareerMentorError("Career Mentor returned invalid upload authorization data.", {
+      code: "INVALID_RESPONSE"
+    });
+  }
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(uploadUrl);
+  } catch {
+    throw new CareerMentorError("Career Mentor returned an invalid upload URL.", {
+      code: "INVALID_RESPONSE"
+    });
+  }
+  if (parsedUrl.username || parsedUrl.password || parsedUrl.protocol !== "https:" && !(parsedUrl.protocol === "http:" && isLoopbackHost(parsedUrl.hostname))) {
+    throw new CareerMentorError("Career Mentor returned an unsafe upload URL.", {
+      code: "INVALID_RESPONSE"
+    });
+  }
+  return { s3Key, uploadUrl: parsedUrl.toString() };
+}
+async function putArtifactBytes(params) {
+  const controller = new AbortController;
+  let didTimeout = false;
+  const forwardAbort = () => controller.abort(params.signal?.reason);
+  if (params.signal?.aborted)
+    forwardAbort();
+  else
+    params.signal?.addEventListener("abort", forwardAbort, { once: true });
+  const timeout = setTimeout(() => {
+    didTimeout = true;
+    controller.abort();
+  }, params.timeoutMs);
+  const requestBody = new ArrayBuffer(params.bytes.byteLength);
+  new Uint8Array(requestBody).set(params.bytes);
+  try {
+    const response = await params.fetch(params.uploadUrl, {
+      body: requestBody,
+      headers: {
+        "Content-Length": String(params.bytes.byteLength),
+        "Content-Type": params.contentType
+      },
+      method: "PUT",
+      redirect: "error",
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      throw new CareerMentorApiError("Artifact byte upload failed.", {
+        code: "ARTIFACT_UPLOAD_FAILED",
+        status: response.status
+      });
+    }
+  } catch (error) {
+    if (didTimeout) {
+      throw new CareerMentorRequestError("Artifact byte upload timed out.", { code: "TIMEOUT" });
+    }
+    if (params.signal?.aborted) {
+      throw new CareerMentorRequestError("Artifact byte upload was aborted.", {
+        code: "REQUEST_ABORTED"
+      });
+    }
+    if (error instanceof CareerMentorError)
+      throw error;
+    throw new CareerMentorRequestError("Artifact byte upload failed.", { code: "NETWORK_ERROR" });
+  } finally {
+    clearTimeout(timeout);
+    params.signal?.removeEventListener("abort", forwardAbort);
+  }
+}
+async function runCli(argv, options = {}) {
+  const stdout = options.stdout ?? ((text) => void process.stdout.write(text));
+  const stderr = options.stderr ?? ((text) => void process.stderr.write(text));
+  const env = options.env ?? process.env;
+  let secrets = [];
+  try {
+    const parsed = parseArgs(argv);
+    if (parsed.flags["version"] === true) {
+      writeJson(stdout, { cli: "career-mentor", version: CLI_VERSION });
+      return CLI_EXIT_CODE.SUCCESS;
+    }
+    if (parsed.flags["help"] === true || parsed.positionals[0] === "help" || parsed.positionals.length === 0) {
+      writeJson(stdout, helpDocument());
+      return CLI_EXIT_CODE.SUCCESS;
+    }
+    const command = parsed.positionals[0];
+    const subcommand = parsed.positionals[1];
+    if (command === "auth" && subcommand === "login") {
+      expectPositionals(parsed.positionals, 2, "cm auth login [browser auth flags]");
+      validateFlags(parsed.flags, new Set([
+        "app-url",
+        "client",
+        "credential-file",
+        "expires-in-days",
+        "no-open",
+        "port",
+        "scopes",
+        "timeout-seconds"
+      ]));
+      const credentialFile = resolveCredentialFile(cleanOptional(stringFlag(parsed.flags, "credential-file")), cleanOptional(env[CAPABILITY_TOKEN_FILE_ENV]));
+      const expiresInDays = parseIntegerFlag(parsed.flags, "expires-in-days", DEFAULT_AUTH_EXPIRES_IN_DAYS, 1, 365) ?? DEFAULT_AUTH_EXPIRES_IN_DAYS;
+      const timeoutSeconds = parseIntegerFlag(parsed.flags, "timeout-seconds", DEFAULT_AUTH_TIMEOUT_MS / 1000, 1, 1800) ?? DEFAULT_AUTH_TIMEOUT_MS / 1000;
+      const port = parseIntegerFlag(parsed.flags, "port", undefined, 1, 65535);
+      const openBrowser = parsed.flags["no-open"] !== true;
+      const result = await runBrowserAuthLogin({
+        appUrl: normalizeEndpoint(cleanOptional(stringFlag(parsed.flags, "app-url")) ?? cleanOptional(env[AUTH_APP_URL_ENV]) ?? cleanOptional(env["CAREER_MENTOR_API_URL"]) ?? DEFAULT_AUTH_APP_URL),
+        clientName: authClientName(stringFlag(parsed.flags, "client")),
+        credentialFile,
+        expiresInDays,
+        onLaunch: async (launch) => {
+          writeJson(stderr, openBrowser ? {
+            diagnostic: {
+              code: "AUTH_BROWSER_OPENING",
+              message: "Complete authorization in the opened browser."
+            }
+          } : {
+            diagnostic: {
+              code: "AUTHORIZATION_URL",
+              message: "Open this URL to authorize the CLI.",
+              url: launch.authorizationUrl
+            }
+          });
+        },
+        openBrowser,
+        ...port !== undefined ? { port } : {},
+        scopes: parseRequestedScopes(stringFlag(parsed.flags, "scopes")),
+        ...options.signal ? { signal: options.signal } : {},
+        timeoutMs: timeoutSeconds * 1000
+      }, {
+        ...options.fetch ? { fetch: options.fetch } : {},
+        ...options.browserAuth
+      });
+      writeJson(stdout, {
+        ok: true,
+        credential: { source: "managed_file", file: result.credentialFile },
+        scopes: result.scopes,
+        expiresAt: result.expiresAt
+      });
+      return CLI_EXIT_CODE.SUCCESS;
+    }
+    if (command === "auth" && subcommand === "logout") {
+      expectPositionals(parsed.positionals, 2, "cm auth logout [--credential-file <path>]");
+      validateFlags(parsed.flags, new Set(["credential-file"]));
+      const credentialFile = resolveCredentialFile(cleanOptional(stringFlag(parsed.flags, "credential-file")), cleanOptional(env[CAPABILITY_TOKEN_FILE_ENV]));
+      const result = await logoutCredential(credentialFile);
+      writeJson(stdout, { ok: true, credentialFile, removed: result.removed });
+      return CLI_EXIT_CODE.SUCCESS;
+    }
+    const config = await resolveConfig(parsed.flags, env);
+    if (config.token)
+      secrets = [config.token];
+    if (command === "auth") {
+      expectPositionals(parsed.positionals, 2, "cm auth status [credential flags]");
+      if (subcommand !== "status") {
+        usageError("UNKNOWN_COMMAND", "Unknown auth command. Use login, status, or logout.");
+      }
+      validateFlags(parsed.flags, new Set(["credential-file", "endpoint", "token"]));
+      const ok = Boolean(config.token);
+      writeJson(stdout, {
+        ok,
+        endpoint: config.endpoint,
+        credential: { configured: ok, source: config.tokenSource }
+      });
+      return ok ? CLI_EXIT_CODE.SUCCESS : CLI_EXIT_CODE.USAGE;
+    }
+    if (command === "doctor") {
+      expectPositionals(parsed.positionals, 1, "cm doctor [transport flags]");
+      validateFlags(parsed.flags, TRANSPORT_FLAGS);
+      if (!config.token) {
+        writeJson(stdout, {
+          ok: false,
+          endpoint: config.endpoint,
+          checks: [
+            { name: "endpoint", ok: true },
+            { name: "token", ok: false },
+            { name: "api", ok: false, skipped: true, reason: "token_not_configured" }
+          ]
+        });
+        return CLI_EXIT_CODE.USAGE;
+      }
+      try {
+        const catalog = await makeClient(config, options.fetch).list(requestOptions(config, options.signal));
+        writeJson(stdout, {
+          ok: true,
+          endpoint: config.endpoint,
+          capabilityCount: catalog.capabilities.length,
+          checks: [
+            { name: "endpoint", ok: true },
+            { name: "token", ok: true },
+            { name: "api", ok: true }
+          ]
+        });
+        return CLI_EXIT_CODE.SUCCESS;
+      } catch (error) {
+        const mapped = mapError(error, secrets);
+        writeJson(stdout, {
+          ok: false,
+          endpoint: config.endpoint,
+          checks: [
+            { name: "endpoint", ok: true },
+            { name: "token", ok: true },
+            {
+              name: "api",
+              ok: false,
+              error: {
+                code: mapped.code,
+                message: mapped.message,
+                ...mapped.status ? { status: mapped.status } : {},
+                ...mapped.requestId ? { requestId: mapped.requestId } : {}
+              }
+            }
+          ]
+        });
+        return mapped.exitCode;
+      }
+    }
+    if (!(command === "invoke" || command === "runs" || command === "capabilities" || command === "artifacts" || command === "photos" || command === "files")) {
+      usageError("UNKNOWN_COMMAND", "Unknown command. Run cm help for the command contract.");
+    }
+    const client = makeClient(config, options.fetch);
+    const baseRequestOptions = requestOptions(config, options.signal);
+    const invokeOptions = {
+      ...baseRequestOptions,
+      ...config.idempotencyKey ? { idempotencyKey: config.idempotencyKey } : {}
+    };
+    if (command === "photos") {
+      validateFlags(parsed.flags, new Set([...TRANSPORT_FLAGS, "idempotency-key"]));
+      let capabilityName;
+      let input;
+      if (subcommand === "list") {
+        expectPositionals(parsed.positionals, 2, "cm photos list");
+        capabilityName = "list_profile_photos";
+        input = {};
+      } else if (subcommand === "add") {
+        expectPositionals(parsed.positionals, 3, "cm photos add <registered-file-id>");
+        capabilityName = "add_profile_photo";
+        input = { fileId: parsed.positionals[2] };
+      } else if (subcommand === "default") {
+        expectPositionals(parsed.positionals, 3, "cm photos default <photo-id>");
+        capabilityName = "set_default_profile_photo";
+        input = { photoId: parsed.positionals[2] };
+      } else if (subcommand === "delete") {
+        expectPositionals(parsed.positionals, 3, "cm photos delete <photo-id>");
+        capabilityName = "propose_delete_profile_photo";
+        input = { photoId: parsed.positionals[2] };
+      } else if (subcommand === "reorder") {
+        if (parsed.positionals.length < 3) {
+          usageError("INVALID_COMMAND", "Usage: cm photos reorder <photo-id> [photo-id...]");
+        }
+        capabilityName = "reorder_profile_photos";
+        input = { photoIds: parsed.positionals.slice(2) };
+      } else {
+        usageError("UNKNOWN_COMMAND", "Unknown photos command. Use list, add, default, reorder, or delete.");
+      }
+      writeJson(stdout, await invokePublishedCapability(client, capabilityName, input, invokeOptions));
+      return CLI_EXIT_CODE.SUCCESS;
+    }
+    if (command === "files") {
+      expectPositionals(parsed.positionals, 3, "cm files delete <registered-file-id>");
+      if (subcommand !== "delete") {
+        usageError("UNKNOWN_COMMAND", "Unknown files command. Use delete.");
+      }
+      validateFlags(parsed.flags, new Set([...TRANSPORT_FLAGS, "idempotency-key"]));
+      writeJson(stdout, await invokePublishedCapability(client, "propose_delete_registered_file", { fileId: parsed.positionals[2] }, invokeOptions));
+      return CLI_EXIT_CODE.SUCCESS;
+    }
+    if (command === "artifacts") {
+      expectPositionals(parsed.positionals, 3, "cm artifacts upload <path> [--create --type <artifact-type> [--name <name>]]");
+      if (subcommand !== "upload") {
+        usageError("UNKNOWN_COMMAND", "Unknown artifacts command. Use upload.");
+      }
+      validateFlags(parsed.flags, new Set([...TRANSPORT_FLAGS, "create", "idempotency-key", "name", "type"]));
+      const filePath = parsed.positionals[2];
+      if (!filePath)
+        usageError("MISSING_FILE_PATH", "Artifact file path is required.");
+      const filename = basename(filePath);
+      if (!filename || filename.length > 200 || filename === "." || filename === ".." || CONTROL_CHARACTER2.test(filename)) {
+        usageError("INVALID_FILENAME", "Artifact filename must be 1 to 200 safe characters.");
+      }
+      const contentType = artifactContentType(filePath);
+      const shouldCreateArtifact = parsed.flags["create"] === true;
+      const requestedArtifactType = artifactType(parsed.flags);
+      const requestedName = cleanOptional(stringFlag(parsed.flags, "name"));
+      if (!shouldCreateArtifact && (requestedArtifactType !== undefined || requestedName !== undefined)) {
+        usageError("CREATE_FLAG_REQUIRED", "Use --create with --type or --name.");
+      }
+      if (shouldCreateArtifact && requestedArtifactType === undefined) {
+        usageError("MISSING_ARTIFACT_TYPE", "Flag --type is required with --create.");
+      }
+      let bytes;
+      try {
+        bytes = options.readBinaryFile ? await options.readBinaryFile(filePath) : new Uint8Array(await readFileFromDisk(filePath));
+      } catch {
+        usageError("FILE_READ_FAILED", "Could not read the artifact file.");
+      }
+      if (!(bytes.byteLength >= 1 && bytes.byteLength <= MAX_ARTIFACT_UPLOAD_BYTES)) {
+        usageError("INVALID_FILE_SIZE", `Artifact file size must be between 1 and ${MAX_ARTIFACT_UPLOAD_BYTES} bytes.`);
+      }
+      const authorizationResponse = await invokePublishedCapability(client, "initiate_artifact_upload", { filename, contentType, size: bytes.byteLength }, invokeOptions);
+      const authorization = parseUploadAuthorization(authorizationResponse, {
+        contentType,
+        size: bytes.byteLength
+      });
+      secrets = [...secrets, authorization.uploadUrl, authorization.s3Key];
+      await putArtifactBytes({
+        bytes,
+        contentType,
+        fetch: options.fetch ?? globalThis.fetch,
+        ...options.signal ? { signal: options.signal } : {},
+        timeoutMs: config.timeoutMs,
+        uploadUrl: authorization.uploadUrl
+      });
+      const registrationResponse = await invokePublishedCapability(client, "register_artifact_upload", {
+        filename,
+        contentType,
+        size: bytes.byteLength,
+        s3Key: authorization.s3Key,
+        parseText: false,
+        calculateHash: true
+      }, baseRequestOptions);
+      const file = capabilityResultData(registrationResponse, "file registration");
+      if (!shouldCreateArtifact) {
+        writeJson(stdout, { ok: true, file });
+        return CLI_EXIT_CODE.SUCCESS;
+      }
+      const fileId = file["fileId"];
+      if (typeof fileId !== "string") {
+        throw new CareerMentorError("Career Mentor returned invalid file registration data.", {
+          code: "INVALID_RESPONSE"
+        });
+      }
+      const defaultArtifactName = basename(filename, extname(filename));
+      const artifactResponse = await invokePublishedCapability(client, "create_artifact", {
+        fileId,
+        name: requestedName ?? defaultArtifactName,
+        type: requestedArtifactType
+      }, baseRequestOptions);
+      writeJson(stdout, {
+        ok: true,
+        file,
+        artifact: capabilityResultData(artifactResponse, "artifact creation")
+      });
+      return CLI_EXIT_CODE.SUCCESS;
+    }
+    if (command === "invoke") {
+      expectPositionals(parsed.positionals, 2, "cm invoke <name> [--input <json> | --input-file <path|->]");
+      validateFlags(parsed.flags, new Set([...TRANSPORT_FLAGS, "idempotency-key", "input", "input-file"]));
+      const name = parsed.positionals[1];
+      if (!name)
+        usageError("MISSING_CAPABILITY_NAME", "Capability name is required.");
+      const input = await readCapabilityInput(parsed.flags, options.readFile ?? (async (path) => await readFileFromDisk(path, "utf8")), options.readStdin ?? defaultReadStdin);
+      writeJson(stdout, await invokePublishedCapability(client, name, input, invokeOptions));
+      return CLI_EXIT_CODE.SUCCESS;
+    }
+    if (command === "runs") {
+      expectPositionals(parsed.positionals, 3, "cm runs <get|events|wait|watch> <run-id>");
+      const runId = parsed.positionals[2];
+      if (!runId)
+        usageError("MISSING_RUN_ID", "Capability run ID is required.");
+      if (subcommand === "get") {
+        validateFlags(parsed.flags, TRANSPORT_FLAGS);
+        writeJson(stdout, await client.getRun(runId, baseRequestOptions));
+        return CLI_EXIT_CODE.SUCCESS;
+      }
+      const after = cleanOptional(stringFlag(parsed.flags, "after"));
+      const rawLimit = cleanOptional(stringFlag(parsed.flags, "limit"));
+      const eventOptions = {
+        ...baseRequestOptions,
+        ...after ? { after } : {},
+        ...rawLimit ? { limit: Number(rawLimit) } : {}
+      };
+      if (subcommand === "events") {
+        validateFlags(parsed.flags, new Set([...TRANSPORT_FLAGS, "after", "limit"]));
+        writeJson(stdout, await client.listRunEvents(runId, eventOptions));
+        return CLI_EXIT_CODE.SUCCESS;
+      }
+      if (subcommand === "watch") {
+        validateFlags(parsed.flags, new Set([...TRANSPORT_FLAGS, "after", "last-event-id", "limit"]));
+        const lastEventId = cleanOptional(stringFlag(parsed.flags, "last-event-id"));
+        for await (const event of client.streamRunEvents(runId, {
+          ...eventOptions,
+          ...lastEventId ? { lastEventId } : {}
+        })) {
+          writeJson(stdout, event);
+        }
+        return CLI_EXIT_CODE.SUCCESS;
+      }
+      if (subcommand === "wait") {
+        validateFlags(parsed.flags, new Set([...TRANSPORT_FLAGS, "after", "last-event-id", "limit"]));
+        const lastEventId = cleanOptional(stringFlag(parsed.flags, "last-event-id"));
+        const terminal = await client.waitForRun(runId, {
+          ...eventOptions,
+          ...lastEventId ? { lastEventId } : {}
+        });
+        const exitCode = terminalRunExitCode(terminal);
+        writeJson(stdout, terminal);
+        return exitCode;
+      }
+      usageError("UNKNOWN_COMMAND", "Unknown runs command. Use get, events, wait, or watch.");
+    }
+    if (subcommand === "list") {
+      expectPositionals(parsed.positionals, 2, "cm capabilities list [transport flags]");
+      validateFlags(parsed.flags, TRANSPORT_FLAGS);
+      writeJson(stdout, await client.list(baseRequestOptions));
+      return CLI_EXIT_CODE.SUCCESS;
+    }
+    if (subcommand === "describe") {
+      expectPositionals(parsed.positionals, 3, "cm capabilities describe <name> [transport flags]");
+      validateFlags(parsed.flags, TRANSPORT_FLAGS);
+      const name = parsed.positionals[2];
+      if (!name)
+        usageError("MISSING_CAPABILITY_NAME", "Capability name is required.");
+      writeJson(stdout, await client.get(name, baseRequestOptions));
+      return CLI_EXIT_CODE.SUCCESS;
+    }
+    usageError("UNKNOWN_COMMAND", "Unknown capabilities command. Use list or describe.");
+  } catch (error) {
+    const mapped = mapError(error, secrets);
+    writeJson(stderr, { ok: false, error: mapped });
+    return mapped.exitCode;
+  }
+}
+function isEntrypoint() {
+  const entrypoint = process.argv[1];
+  if (entrypoint === undefined)
+    return false;
+  try {
+    return pathToFileURL(realpathSync(entrypoint)).href === import.meta.url;
+  } catch {
+    return false;
+  }
+}
+if (isEntrypoint()) {
+  const controller = new AbortController;
+  const abort = () => controller.abort();
+  process.once("SIGINT", abort);
+  process.once("SIGTERM", abort);
+  try {
+    process.exitCode = await runCli(process.argv.slice(2), { signal: controller.signal });
+  } finally {
+    process.removeListener("SIGINT", abort);
+    process.removeListener("SIGTERM", abort);
+  }
+}
+export {
+  runCli,
+  parseArgs,
+  DEFAULT_API_URL,
+  CLI_VERSION,
+  CLI_EXIT_CODE
+};