@yansigit/opencodex 2.36.1-dev.20260829.48 → 2.36.1

package/src/cli/inspect.ts

@@ -0,0 +1,230 @@
+/**
+ * `ocx system-surface` — the remaining routes that had no CLI caller at all (wp7).
+ *
+ * These are grouped by what an operator is trying to do, not by which server module owns them:
+ * inspecting effective configuration, reading the generated client-config snippet, toggling the
+ * native client integrations, checking request pacing and routing analytics, and reading the
+ * Codex system prompt.
+ *
+ * One route here is deliberately READ-ONLY forever. `POST /api/github/star` spends the operator's
+ * GitHub identity, and no CLI flag can carry that consent — the server requires a real dashboard
+ * session for it. So `star` reads status and says what it cannot do, rather than offering a
+ * `--yes` that would be a lie.
+ */
+import {
+  CliUsageError,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeRequest,
+  summaryLines,
+  takeFlag,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx inspect config [--json]
+  ocx inspect catalog [--json]
+  ocx inspect routing-analytics [--json]
+  ocx inspect pacing [--name <provider>] [--json]
+  ocx inspect key-providers [--json]
+  ocx inspect codex-prompt [--text] [--json]
+  ocx inspect client-config --client <id> [--json]
+  ocx inspect star [--json]
+  ocx inspect windows-tray [--json]
+  ocx integration native [list] [--json]
+  ocx integration native <claude|claude-desktop|codex|grok> <on|off> [--json]
+  ocx agent request-user-input [on|off] [--json]`;
+
+/** A read that takes no arguments beyond `--json`. */
+async function read(path: string, argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest(path, {}, deps);
+  printData(result, wantsJson, summaryLines(result));
+}
+
+const NATIVE_CLIENTS = ["claude", "claude-desktop", "codex", "grok"] as const;
+
+interface NativeClientRow {
+  clientId?: string;
+  state?: string;
+  installed?: boolean;
+  desiredEnabled?: boolean;
+  configPath?: string;
+  disableBlocked?: unknown;
+}
+
+/**
+ * The shared depth-1 flattener renders an array as "N item(s)", so a bare
+ * `integration native list` printed `clients: 4 item(s)` -- the per-client state the operator
+ * asked for was in the payload and discarded before the terminal. Same defect class wp4 fixed
+ * for the account and key tables.
+ */
+function nativeLines(payload: unknown): string[] {
+  const clients = (payload as { clients?: NativeClientRow[] } | null)?.clients;
+  if (!Array.isArray(clients) || clients.length === 0) return ["No native client integrations reported."];
+  const lines = ["CLIENT           STATE      INSTALLED  DESIRED  CONFIG"];
+  for (const row of clients) {
+    lines.push([
+      (row.clientId ?? "?").padEnd(16),
+      (row.state ?? "?").padEnd(10),
+      (row.installed === true ? "yes" : row.installed === false ? "no" : "?").padEnd(10),
+      (row.desiredEnabled === true ? "on" : row.desiredEnabled === false ? "off" : "?").padEnd(8),
+      row.configPath ?? "",
+    ].join(" ").trimEnd());
+    // A blocked disable is the reason a toggle did not take effect, so it is never silent.
+    if (row.disableBlocked !== null && row.disableBlocked !== undefined) {
+      lines.push(`  disable blocked: ${typeof row.disableBlocked === "string" ? row.disableBlocked : JSON.stringify(row.disableBlocked)}`);
+    }
+  }
+  return lines;
+}
+
+async function nativeIntegration(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const action = argv[0] && !argv[0].startsWith("-") ? argv[0] : "list";
+  const rest = argv[0] && !argv[0].startsWith("-") ? argv.slice(1) : argv;
+
+  if (action === "list") {
+    const args = [...rest];
+    const wantsJson = takeFlag(args, "--json");
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/native-integrations", {}, deps);
+    printData(result, wantsJson, nativeLines(result));
+    return;
+  }
+
+  if (!(NATIVE_CLIENTS as readonly string[]).includes(action)) {
+    throw new CliUsageError(`unknown native client ${action}; expected one of ${NATIVE_CLIENTS.join(", ")}`, USAGE);
+  }
+
+  const args = [...rest];
+  const wantsJson = takeFlag(args, "--json");
+  const state = args.shift();
+  rejectArgs(args, USAGE);
+  if (state !== "on" && state !== "off") {
+    throw new CliUsageError(`expected on or off after ${action}`, USAGE);
+  }
+
+  // Toggling rewrites the client's own config file, which is why each client has its own route
+  // rather than one route with a client parameter.
+  const result = await runtimeRequest(`/api/native-integrations/${action}`, {
+    method: "PUT",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ enabled: state === "on" }),
+  }, deps);
+  printData(result, wantsJson, summaryLines(result));
+}
+
+/**
+ * Exported unwrapped so `ocx agent request-user-input` can call it INSIDE its own
+ * `runCliAction`. Wrapping an already-wrapped handler reports one failure twice: the inner
+ * wrapper prints the error and returns a code, and the outer one prints again on the rethrow.
+ */
+export async function requestUserInputAction(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const state = args.shift();
+  rejectArgs(args, USAGE);
+
+  const path = "/api/codex-auth/features/default-mode-request-user-input";
+  // No argument means show. A read must not write the value it is reporting.
+  if (state === undefined) {
+    const result = await runtimeRequest(path, {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  if (state !== "on" && state !== "off") throw new CliUsageError("expected on or off", USAGE);
+
+  const result = await runtimeRequest(path, {
+    method: "PUT",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ enabled: state === "on" }),
+  }, deps);
+  printData(result, wantsJson, summaryLines(result));
+}
+
+async function clientConfig(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const client = takeOption(args, "--client");
+  rejectArgs(args, USAGE);
+  if (!client) throw new CliUsageError("--client is required", USAGE);
+  // The valid client list is not duplicated here: the route answers 400 naming every accepted id,
+  // which is more useful than a local list that can drift out of date.
+  const result = await runtimeRequest(`/api/client-config?client=${encodeURIComponent(client)}`, {}, deps);
+  printData(result, wantsJson, summaryLines(result));
+}
+
+async function pacing(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const name = takeOption(args, "--name");
+  rejectArgs(args, USAGE);
+  const suffix = name ? `?name=${encodeURIComponent(name)}` : "";
+  const result = await runtimeRequest(`/api/provider-request-pacing${suffix}`, {}, deps);
+  printData(result, wantsJson, summaryLines(result));
+}
+
+async function codexPrompt(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const asText = takeFlag(args, "--text");
+  rejectArgs(args, USAGE);
+  if (asText && wantsJson) throw new CliUsageError("--text and --json cannot be combined", USAGE);
+  if (asText) {
+    // The /text variant answers the prompt body itself, so it is printed verbatim rather than
+    // flattened through the summary renderer.
+    const result = await runtimeRequest<unknown>("/api/codex-prompt/text", {}, deps);
+    console.log(typeof result === "string" ? result : JSON.stringify(result, null, 2));
+    return;
+  }
+  const result = await runtimeRequest("/api/codex-prompt", {}, deps);
+  printData(result, wantsJson, summaryLines(result));
+}
+
+async function star(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest<Record<string, unknown>>("/api/github/star", {}, deps);
+  if (wantsJson) {
+    printData(result, true);
+    return;
+  }
+  printData(result, false, summaryLines(result));
+  // Said plainly, because the natural next question is "then star it", and the answer is that no
+  // CLI invocation can: the POST requires a dashboard session precisely so an agent cannot spend
+  // the operator's identity on their behalf.
+  console.log("Starring is not available from the CLI: it uses your GitHub identity, so only you can do it from the dashboard.");
+}
+
+export async function handleInspectCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const hasSub = argv[0] !== undefined && !argv[0].startsWith("-");
+    const sub = hasSub ? argv[0]! : "config";
+    const rest = hasSub ? argv.slice(1) : argv;
+    if (sub === "config") await read("/api/config", rest, deps);
+    else if (sub === "catalog") await read("/api/catalog", rest, deps);
+    else if (sub === "routing-analytics") await read("/api/routing-analytics", rest, deps);
+    else if (sub === "key-providers") await read("/api/key-providers", rest, deps);
+    else if (sub === "windows-tray") await read("/api/windows-tray", rest, deps);
+    else if (sub === "pacing") await pacing(rest, deps);
+    else if (sub === "client-config") await clientConfig(rest, deps);
+    else if (sub === "codex-prompt") await codexPrompt(rest, deps);
+    else if (sub === "star") await star(rest, deps);
+    else throw new CliUsageError(`unknown inspect command ${sub}`, USAGE);
+  });
+}
+
+export async function handleIntegrationCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const [sub, ...rest] = argv;
+    if (sub === "native" || sub === undefined) await nativeIntegration(sub === undefined ? [] : rest, deps);
+    else throw new CliUsageError(`unknown integration command ${sub}`, USAGE);
+  });
+}
+
+export const INSPECT_USAGE = USAGE;

package/src/cli/observe.ts

@@ -15,7 +15,7 @@ import { USAGE_RANGES, USAGE_SURFACES } from "../usage/summary";
 
 const USAGE = `Usage:
   ocx observe logs [--provider <name>] [--model <id>] [--status <code>]
-      [--limit <n>] [--follow] [--json|--jsonl]
+      [--conversation <id>] [--limit <n>] [--follow] [--json|--jsonl]
   ocx logs explain <request-id> [--json]
   ocx logs rebuild-index
   ocx logs index-status
@@ -50,7 +50,12 @@ function formatLog(row: LogEntry): string {
   const route = [row.provider, row.model].filter(Boolean).join("/");
   const status = row.status ?? row.statusCode ?? "?";
   const duration = row.durationMs !== undefined ? `${String(row.durationMs)}ms` : "";
-  return [time, String(status), route, duration].filter(Boolean).join("  ");
+  // The conversation id is shown because a conversation FILTER whose output never names the
+  // conversation is hard to trust: an empty result and a wrong-id result look identical (#2704).
+  const conversation = typeof row.conversationId === "string" && row.conversationId.length > 0
+    ? `conv=${row.conversationId}`
+    : "";
+  return [time, String(status), route, duration, conversation].filter(Boolean).join("  ");
 }
 
 async function logs(argv: string[], deps: RuntimeApiDeps): Promise<void> {
@@ -61,13 +66,16 @@ async function logs(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const provider = takeOption(args, "--provider");
   const model = takeOption(args, "--model");
   const status = takeOption(args, "--status");
+  // Both spellings, because the server accepts both (`request-log.ts:1032`) and an operator
+  // should not have to remember which one this surface wanted.
+  const conversationId = takeOption(args, "--conversation") ?? takeOption(args, "--conversationId");
   const limit = takeIntegerOption(args, "--limit", { min: 1 }) ?? 200;
   rejectArgs(args, USAGE);
   if (wantsJson && wantsJsonl) throw new CliUsageError("--json and --jsonl cannot be combined", USAGE);
   if (follow && wantsJson) throw new CliUsageError("--follow uses --jsonl, not --json", USAGE);
   let seen = new Set<string>();
   do {
-    const data = await runtimeRequest(`/api/logs${query({ provider, model, status, limit })}`, {}, deps);
+    const data = await runtimeRequest(`/api/logs${query({ provider, model, status, conversationId, limit })}`, {}, deps);
     const rows = logRows(data);
     if (!follow && wantsJson) printData(data, true);
     else {

package/src/cli/registry.ts

@@ -213,13 +213,29 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     usage: "ocx observe <logs|usage|storage|memory|debug|claude-inbound|injection> ...",
     summary: "Inspect proxy requests, usage, storage, memory, and debug data.",
   },
+  {
+    name: "inspect",
+    usage: "ocx inspect <config|catalog|routing-analytics|pacing|key-providers|codex-prompt|client-config|star|windows-tray> ...",
+    summary: "Read effective config, catalog, analytics, pacing, and the generated client-config snippet.",
+    details: [
+      "`inspect star` reads the repository star status only. Starring uses your GitHub identity and is available from the dashboard alone.",
+    ],
+  },
   { name: "logs", usage: "ocx logs [filters] [--follow] [--json|--jsonl]", summary: "Alias of ocx observe logs." },
   {
     name: "usage",
     usage: "ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--json]",
     summary: "Alias of ocx observe usage.",
   },
-  { name: "storage", usage: "ocx storage [--json]", summary: "Alias of ocx observe storage." },
+  {
+    name: "storage",
+    usage: "ocx storage <report|cleanup|trash|policy> ...",
+    summary: "Storage report, archived-session cleanup, trash restore, and the cleanup policy.",
+    details: [
+      "A bare `ocx storage` prints the report, as it did when this was an alias of `observe storage`.",
+      "`cleanup` previews by default and only deletes under --yes; `trash restore` and `policy run` also require --yes.",
+    ],
+  },
   { name: "memory", usage: "ocx memory [--json]", summary: "Alias of ocx observe memory." },
   {
     name: "access",
@@ -243,7 +259,14 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     usage: "ocx grok <status|exclude|include|set|clear|apply> ...",
     summary: "Manage and apply the Grok Build model fence.",
   },
-  { name: "integration", usage: "ocx integration <claude|grok|client> ...", summary: "Manage supported client integrations." },
+  {
+    name: "integration",
+    usage: "ocx integration <claude|grok|client|native> ...",
+    summary: "Manage supported client integrations, and the native client toggles.",
+    details: [
+      "`native` shows or flips the native Claude/Claude Desktop/Codex/Grok toggles; the other subcommands manage the reversible file integrations.",
+    ],
+  },
   {
     name: "system",
     usage: "ocx system <status|settings|startup|diagnostics|sync|update> ...",
@@ -350,6 +373,15 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     summary: "Check proxy health. Exits 0 if healthy, 1 otherwise.",
     details: ["Use --json for structured output: {ok, pid, port}."],
   },
+  {
+    name: "capabilities",
+    usage: "ocx capabilities [--json] [--mutating-only] [--route <path>]",
+    summary: "List the declared CLI capabilities and the management routes they drive.",
+    details: [
+      "The machine-readable surface index: start here when driving ocx programmatically instead of parsing help text.",
+      "--route <path> answers the inverse question: which commands drive this management route.",
+    ],
+  },
   {
     name: "ready",
     usage: "ocx ready [--json] [--wait [--timeout <seconds>]]",

package/src/cli/runtime-api.ts

@@ -47,15 +47,37 @@ export async function runtimeBaseUrl(deps: RuntimeApiDeps = {}): Promise<string>
   return `http://${probeHostname(live.hostname)}:${live.port}`;
 }
 
+function stringField(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key];
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+/**
+ * Compose the operator-facing message from a management error body.
+ *
+ * The server states WHY a request was refused under `reason` and WHAT TO DO under
+ * `hint` (see management-auth.ts, which sets both on a 503 when the management plane
+ * is unavailable). Both were dropped here, so a fenced management plane was
+ * indistinguishable from a generic failure and an operator had no way to tell a port
+ * collision from an ACL refusal from a stopped proxy (#2698).
+ */
 function responseMessage(body: unknown, status: number): string {
-  if (body && typeof body === "object") {
-    const record = body as Record<string, unknown>;
-    for (const key of ["error", "message", "detail"]) {
-      if (typeof record[key] === "string" && record[key]) return record[key];
-    }
-  }
   if (typeof body === "string" && body.trim()) return body.trim().slice(0, 400);
-  return `Management request failed (${status})`;
+  if (!body || typeof body !== "object") return `Management request failed (${status})`;
+  const record = body as Record<string, unknown>;
+  let primary: string | undefined;
+  for (const key of ["error", "message", "detail"]) {
+    primary = stringField(record, key);
+    if (primary) break;
+  }
+  const parts = [primary ?? `Management request failed (${status})`];
+  const reason = stringField(record, "reason");
+  // A body of {ok:false, reason:"…"} with no `error` key used to degrade to the
+  // generic line, discarding the only actionable field.
+  if (reason && reason !== primary) parts.push(`reason: ${reason}`);
+  const hint = stringField(record, "hint");
+  if (hint && hint !== primary) parts.push(`hint: ${hint}`);
+  return parts.join("\n").slice(0, 1200);
 }
 
 export async function runtimeRequest<T = unknown>(
@@ -94,6 +116,28 @@ export function takeFlag(args: string[], flag: string): boolean {
   return true;
 }
 
+/** Unicode dashes that copy-paste and IME input substitute for ASCII `-`. */
+const DASH_CLASS = /[\u2010-\u2015\u2212]/g;
+
+/**
+ * True for `--json`, `--json=true`, `-json`, and Unicode-dash spellings.
+ * Matching only the exact token `--json` is the same defect logout had: each
+ * spelling that slips through is a silent success (or, for doctor, prose on
+ * stdout after the caller asked for JSON).
+ */
+export function isJsonOption(arg: string): boolean {
+  const body = arg.replace(DASH_CLASS, "-").replace(/^-+/, "");
+  return body === "json" || body.startsWith("json=");
+}
+
+/** Remove one JSON-request spelling from `args`. Returns whether one was present. */
+export function takeJsonFlag(args: string[]): boolean {
+  const index = args.findIndex(isJsonOption);
+  if (index === -1) return false;
+  args.splice(index, 1);
+  return true;
+}
+
 export function takeOption(args: string[], flag: string): string | undefined {
   const index = args.indexOf(flag);
   if (index === -1) return undefined;

package/src/cli/status.ts

@@ -10,6 +10,8 @@ import { collectStartupHealth, type StartupHealth } from "../codex/autostart-hea
 import { getCodexRoutingKind } from "../codex/inject";
 import { diagnoseCodexShim } from "../codex/shim";
 import { displayCodexRuntimePath, effortClampAppliesToRuntime, loadLastEffortClamp, resolveCodexRuntime } from "../codex/runtime";
+import { packageVersion } from "./help";
+import { computeVersionSkew, type VersionSkew } from "./version-skew";
 import { redactSecretString, redactUserPath } from "../lib/redact";
 import { collectOrcaCodexHomeDiagnostic, type OrcaCodexHomeDiagnostic } from "../codex/home";
 import { grokFenceEndpointDrift, readGrokStatus } from "../grok/status";
@@ -70,6 +72,13 @@ export type CliStatusJson = {
     };
   };
   codexHome: OrcaCodexHomeDiagnostic;
+  /**
+   * This CLI's version against the running proxy's (#2701).
+   *
+   * Additive and optional-by-value, so `schemaVersion` stays 1: an existing consumer that
+   * ignores the key is unaffected, and `proxyVersion` is null when nothing is live.
+   */
+  versionSkew: VersionSkew;
 };
 
 export type CliStatusView = {
@@ -180,6 +189,9 @@ export async function collectStatus(): Promise<CliStatusView> {
   const pidFile = readPid();
   // Preserve an authoritative null from orphan/legacy liveness — do not restore pidFile.
   const pid = resolveStatusPid(live, pidFile);
+  // No extra request: findLiveProxy's identity probe already parsed and validated the
+  // healthz body, so the version came back with the liveness result.
+  const versionSkew = computeVersionSkew(packageVersion(), live?.version);
   const listen = live
     ? {
       port: live.port,
@@ -347,6 +359,10 @@ export async function collectStatus(): Promise<CliStatusView> {
       codexPlugins,
       codexRuntime,
       codexHome,
+      // Own field rather than a line in `codexRuntime.warning`: a stale ocx on PATH is a
+      // fact about this install, not about the Codex runtime, and filing it there would
+      // print it under the wrong heading (#2701).
+      versionSkew,
     },
   };
 }