@bitkyc08/opencodex 2.8.2-preview.20260731 → 2.9.1

package/src/cli/export-command.ts

@@ -0,0 +1,187 @@
+/**
+ * `ocx export --client <opencode|pi>` — print a client config for the live proxy.
+ *
+ * Two consumers, one payload (devlog 260731_client_config_export/020):
+ *
+ * - **Agent** (`--json`): stdout is exactly the client config JSON and nothing else, so
+ *   `ocx export --client pi --json > models.json` is safe to pipe. Every diagnostic —
+ *   including the `--out` write note — goes to stderr.
+ * - **Human** (no flag): the JSON leads, then the destination path, the merge warning,
+ *   the env export line, and the model/degraded counts.
+ *
+ * The command never writes the user's real config path. `--out` is an explicit target and
+ * refuses to clobber an existing file without `--force`, because the common mistake
+ * (`--out ~/.config/opencode/opencode.json`) would silently destroy other providers.
+ *
+ * Serialization itself belongs to src/clients/config-export.ts; this module only resolves
+ * the base URL, filters the catalog, and renders. No secret is ever serialized: the config
+ * carries the client's documented env reference and the real key stays in the environment.
+ */
+import { writeFileSync } from "node:fs";
+import { loadConfig } from "../config";
+import {
+  EXPORT_CLIENTS,
+  EXPORT_CLIENT_IDS,
+  buildClientConfig,
+  isExportClientId,
+  opencodeProxyBaseUrl,
+  type ExportClientId,
+  type ExportModel,
+} from "../clients/config-export";
+import { opencodeCatalogFromProxyRows, type OpencodeProxyModelRow } from "./opencode";
+import type { OcxConfig } from "../types";
+import {
+  CliUsageError,
+  RuntimeApiError,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeBaseUrl,
+  runtimeRequest,
+  takeFlag,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx export --client <${EXPORT_CLIENT_IDS.join("|")}> [--json] [--out <path>] [--force]`;
+
+export interface ExportCommandDeps extends RuntimeApiDeps {
+  /** Live config seam; tests inject a fixture instead of reading the user's config. */
+  configImpl?: () => OcxConfig;
+}
+
+/**
+ * `/api/models` row plus the modality list Pi consumes. The launcher's row type predates
+ * the Pi exporter and stops at the fields OpenCode needs.
+ */
+type ExportProxyModelRow = OpencodeProxyModelRow & { inputModalities?: string[] };
+
+/** Same authoritativeness rule the serializers apply, for the degraded-count line. */
+function hasContextLimit(model: ExportModel): boolean {
+  return typeof model.contextWindow === "number"
+    && Number.isFinite(model.contextWindow)
+    && model.contextWindow > 0;
+}
+
+/**
+ * Export rows from proxy `/api/models` rows.
+ *
+ * `opencodeCatalogFromProxyRows` owns the visibility rules (drop `disabled`, drop dupes,
+ * drop native under Codex Direct) — the export core does none of that, so a row filtered
+ * here is the only thing keeping a disabled model out of a client's picker. Modalities are
+ * re-joined by `namespaced` because the launcher's catalog type does not carry them.
+ */
+export function exportModelsFromProxyRows(
+  rows: readonly ExportProxyModelRow[],
+  config: OcxConfig,
+): ExportModel[] {
+  const modalities = new Map<string, string[]>();
+  for (const row of rows) {
+    const namespaced = row.namespaced?.trim();
+    if (namespaced && Array.isArray(row.inputModalities) && row.inputModalities.length > 0) {
+      if (!modalities.has(namespaced)) modalities.set(namespaced, [...row.inputModalities]);
+    }
+  }
+  return opencodeCatalogFromProxyRows(rows, config).map(entry => {
+    const model: ExportModel = {
+      namespaced: entry.namespaced,
+      provider: entry.provider ?? (entry.native ? "openai" : "routed"),
+      id: entry.id ?? entry.namespaced,
+    };
+    if (entry.native) model.native = true;
+    if (entry.displayName) model.displayName = entry.displayName;
+    if (entry.contextWindow !== undefined) model.contextWindow = entry.contextWindow;
+    const input = modalities.get(entry.namespaced);
+    if (input) model.inputModalities = input;
+    return model;
+  });
+}
+
+/**
+ * `http://host:port/v1` for the proxy that is actually listening.
+ *
+ * `runtimeBaseUrl` is the identity-checked `findLiveProxy` probe the launcher uses, and it
+ * already throws the "Start it with: ocx start" error when nothing answers — so a config
+ * with an empty models block can never be emitted.
+ *
+ * Resolved ONCE and handed back to `runtimeRequest` as `baseUrl`, so the catalog and the
+ * exported endpoint can never come from two different probes.
+ */
+function proxyV1BaseUrl(root: string): string {
+  const url = new URL(root);
+  const port = url.port ? Number(url.port) : url.protocol === "https:" ? 443 : 80;
+  return opencodeProxyBaseUrl(port, url.hostname);
+}
+
+function parseClient(args: string[]): ExportClientId {
+  const raw = takeOption(args, "--client");
+  if (raw === undefined) {
+    throw new CliUsageError(`--client is required (${EXPORT_CLIENT_IDS.join(", ")})`, USAGE);
+  }
+  const client = raw.trim().toLowerCase();
+  if (!isExportClientId(client)) {
+    throw new CliUsageError(`--client must be one of: ${EXPORT_CLIENT_IDS.join(", ")}`, USAGE);
+  }
+  return client;
+}
+
+/**
+ * Write the config, refusing to replace an existing file without `--force`.
+ *
+ * The `wx` flag does the refusal in the kernel rather than after an `existsSync` check, so
+ * a file created between the two can never be truncated. Nothing is printed before this
+ * runs: a refusal leaves both the target bytes and stdout untouched.
+ */
+function writeExport(path: string, text: string, force: boolean): void {
+  try {
+    writeFileSync(path, text, force ? { encoding: "utf8" } : { encoding: "utf8", flag: "wx" });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+      throw new CliUsageError(
+        `${path} already exists. Re-run with --force to replace it, or print the config and merge it yourself.`,
+        USAGE,
+      );
+    }
+    throw error;
+  }
+}
+
+export async function handleExportCommand(argv: string[], deps: ExportCommandDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const args = [...argv];
+    const client = parseClient(args);
+    const wantsJson = takeFlag(args, "--json");
+    const force = takeFlag(args, "--force");
+    const out = takeOption(args, "--out");
+    rejectArgs(args, USAGE);
+
+    const spec = EXPORT_CLIENTS[client];
+    const config = (deps.configImpl ?? loadConfig)();
+    const root = await runtimeBaseUrl(deps);
+    const rows = await runtimeRequest<ExportProxyModelRow[]>("/api/models", {}, { ...deps, baseUrl: root });
+    if (!Array.isArray(rows)) {
+      throw new RuntimeApiError("Management API returned an unexpected /api/models payload.", 502, rows);
+    }
+    const models = exportModelsFromProxyRows(rows, config);
+    const clientConfig = buildClientConfig(client, { baseUrl: proxyV1BaseUrl(root), models, config });
+    const text = JSON.stringify(clientConfig, null, 2);
+
+    if (out !== undefined) writeExport(out, `${text}\n`, force);
+    // stderr, so `--json` stdout stays byte-exact for a redirect.
+    if (out !== undefined && wantsJson) console.error(`Wrote ${out}`);
+
+    const degraded = models.filter(model => !hasContextLimit(model)).length;
+    printData(clientConfig, wantsJson, [
+      text,
+      "",
+      ...(out !== undefined ? [`Wrote ${out}`] : []),
+      `Destination: ${spec.destination(process.env)}`,
+      "Merge this provider block into that file; do not replace it.",
+      `Before launching: ${spec.exportHint}`,
+      `${models.length} model${models.length === 1 ? "" : "s"}; ${degraded} omit context limits (the client applies its own defaults).`,
+    ]);
+  });
+}
+
+export const EXPORT_USAGE = USAGE;

package/src/cli/help.ts

@@ -169,6 +169,16 @@ const helpEntries: Record<string, HelpEntry> = {
     summary: "Manage OpenCodex admission API keys and inspect external endpoints.",
   },
   "api-key": { usage: "ocx api-key <list|create|remove> ...", summary: "Alias of ocx access key." },
+  export: {
+    usage: "ocx export --client <opencode|pi> [--json] [--out <path>] [--force]",
+    summary: "Print a client config (opencode, Pi) wired to the running proxy.",
+    details: [
+      "--json prints only the config JSON on stdout, so it is safe to redirect to a file.",
+      "--out <path> writes the config there and refuses to replace an existing file without --force.",
+      "The config never contains a key; it references the client's env var, which you export before launching.",
+      "The destination path is printed for merging by hand — ocx never writes your real client config.",
+    ],
+  },
   grok: { usage: "ocx grok <status|exclude|include|set|clear|apply> ...", summary: "Manage and apply the Grok Build model fence." },
   integration: { usage: "ocx integration <claude|grok> ...", summary: "Manage supported client integrations." },
   system: {
@@ -286,6 +296,7 @@ Usage:
   ocx agent <sub>             Subagents, injection, effort caps, and sidecars
   ocx observe <sub>           Logs, usage, storage, memory, and debug data
   ocx access <sub>            External API keys and endpoint information
+  ocx export --client <id>    Print an opencode/Pi config wired to the running proxy
   ocx grok <sub>              Grok Build model selection and apply
   ocx system <sub>            Runtime settings, startup, sync, and updates
   ocx config <sub>            Validated configuration show/get/set/import/export

package/src/cli/index.ts

@@ -129,16 +129,21 @@ async function chooseListenPort(requestedPort?: number): Promise<number> {
   if (hardPin && preferred > 0) {
     const { reclaimListenPort } = await import("../server/port-reclaim");
     await reclaimListenPort(preferred, config.hostname ?? "127.0.0.1", {
-      timeoutMs: 30_000,
+      // Ghost LISTEN rows with a dead PID can outlive the process for a while.
+      // SetTcpEntry(DELETE_TCB) needs elevation (often returns 317), so the only
+      // reliable non-admin recovery is to wait for the OS to release the TCB.
+      timeoutMs: 60_000,
       intervalMs: 100,
       scanIntervalMs: 500,
       killOcxHolders: false,
-      dropTcpRows: false,
+      dropTcpRows: true,
     });
   }
   try {
     const selected = await findAvailablePort(preferred, config.hostname ?? "127.0.0.1", {
-      preferRetryMs: hardPin ? 0 : 750,
+      // After reclaim, keep probing briefly — ghost rows sometimes clear between
+      // the reclaim deadline and the final listen. Still never hop off `--port`.
+      preferRetryMs: hardPin ? 5_000 : 750,
       preferRetryIntervalMs: 50,
       allowEphemeralFallback: !hardPin,
     });
@@ -1031,6 +1036,11 @@ switch (command) {
     process.exitCode = await handleAccessCommand(["key", ...args.slice(1)]);
     break;
   }
+  case "export": {
+    const { handleExportCommand } = await import("./export-command");
+    process.exitCode = await handleExportCommand(args.slice(1));
+    break;
+  }
   case "grok": {
     const { handleGrokCommand } = await import("./integrations");
     process.exitCode = await handleGrokCommand(args.slice(1));

package/src/cli/opencode.ts

@@ -20,17 +20,49 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { loadConfig } from "../config";
+import {
+  OPENCODE_API_KEY_ENV,
+  OPENCODE_CONFIG_SCHEMA,
+  OPENCODE_PROVIDER_BLOCK_DEFAULT_CONFIG,
+  OPENCODE_PROVIDER_ID,
+  buildOpencodeProviderBlockFromCatalog,
+  opencodeGlobalConfigPath,
+} from "../clients/config-export";
+import type {
+  OpencodeCatalogModel,
+  OpencodeGeneratedConfig,
+  OpencodeLaunchEnv,
+  OpencodeProviderBlock,
+} from "../clients/config-export";
 import { visibleNativeSlugs } from "../codex/catalog";
-import { shouldInjectApiAuthHeader } from "../codex/inject";
 import { commandInvocation } from "../lib/win-exec";
 import { loadServiceTokenFromFile, serviceApiTokenFilePath } from "../lib/service-secrets";
 import { providerCodexAccountMode } from "../providers/registry";
 import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
 import type { OcxConfig } from "../types";
 
-export interface OpencodeLaunchEnv {
-  [key: string]: string | undefined;
-}
+/**
+ * The provider-block serializer, its constants, and the config-path helpers now live in
+ * `src/clients/config-export.ts`, shared with every other client-config export surface.
+ * They are re-exported here so the launcher's long-standing import surface is unchanged.
+ */
+export {
+  OPENCODE_API_KEY_ENV,
+  OPENCODE_API_KEY_ENV_REF,
+  OPENCODE_PROVIDER_BLOCK_DEFAULT_CONFIG,
+  OPENCODE_PROVIDER_ID,
+  SCHEMA_REQUIRED_OUTPUT_BUDGET,
+  buildOpencodeProviderBlockFromCatalog,
+  opencodeGlobalConfigPath,
+  opencodeProxyBaseUrl,
+} from "../clients/config-export";
+export type {
+  OpencodeCatalogModel,
+  OpencodeGeneratedConfig,
+  OpencodeLaunchEnv,
+  OpencodeModelEntry,
+  OpencodeProviderBlock,
+} from "../clients/config-export";
 
 /** One proxy-routed model destined for the generated provider block. */
 export interface OpencodeRoutedModel {
@@ -53,42 +85,6 @@ export interface OpencodeProxyModelRow {
   contextWindow?: number;
 }
 
-/** Visible catalog entry keyed by the proxy's canonical namespaced selector. */
-export interface OpencodeCatalogModel {
-  namespaced: string;
-  native?: boolean;
-  provider?: string;
-  id?: string;
-  contextWindow?: number;
-  displayName?: string;
-}
-
-export interface OpencodeModelEntry {
-  name: string;
-  limit?: { context: number; output: number };
-}
-
-export interface OpencodeProviderBlock {
-  npm: string;
-  name: string;
-  options: {
-    baseURL: string;
-    apiKey?: string;
-    headers?: Record<string, string>;
-  };
-  models: Record<string, OpencodeModelEntry>;
-}
-
-export interface OpencodeGeneratedConfig {
-  $schema: string;
-  provider: Record<string, OpencodeProviderBlock>;
-}
-
-/** Provider key owned by this launcher; the only key it ever injects at runtime. */
-export const OPENCODE_PROVIDER_ID = "opencodex";
-
-const OPENCODE_CONFIG_SCHEMA = "https://opencode.ai/config.json";
-
 const PROJECT_CONFIG_FILENAMES = ["opencode.json", "opencode.jsonc"] as const;
 
 /**
@@ -97,41 +93,6 @@ const PROJECT_CONFIG_FILENAMES = ["opencode.json", "opencode.jsonc"] as const;
  */
 export const OPENCODE_CONFIG_CONTENT_ENV = "OPENCODE_CONFIG_CONTENT";
 
-/**
- * The proxy speaks the OpenAI-compatible shape at /v1, which opencode reaches through
- * the AI SDK's openai-compatible package (the same wiring users hand-write today).
- */
-const OPENCODE_PROVIDER_NPM = "@ai-sdk/openai-compatible";
-
-/**
- * Env var carrying the proxy admission key to the child. The inline config only ever
- * holds the `{env:...}` reference, so the secret never lands on disk (AGENTS.md treats
- * token serialization as a release blocker). opencode substitutes it at load time.
- */
-export const OPENCODE_API_KEY_ENV = "OPENCODEX_OPENCODE_API_KEY";
-
-/**
- * opencode's config schema rejects a `limit` block that carries `context` without
- * `output`, but CatalogModel has no authoritative per-model output field. Dropping
- * `limit` entirely would also throw away the authoritative context window we DO have,
- * so the block is emitted with this budget standing in for the missing half.
- *
- * The value matches REASONING_MAX_TOKENS_CEILING in src/adapters/anthropic.ts — the
- * project's existing "safe ceiling across current models" figure. It is a ceiling for
- * schema validity, NOT a claim about any specific model's true maximum, and it is
- * clamped to the context window so a small-context model can never be emitted with
- * output > context.
- */
-export const SCHEMA_REQUIRED_OUTPUT_BUDGET = 32_000;
-
-/** Deterministic loopback default for exported provider-block helpers in tests. */
-export const OPENCODE_PROVIDER_BLOCK_DEFAULT_CONFIG: OcxConfig = {
-  port: 10100,
-  hostname: "127.0.0.1",
-  defaultProvider: "mock",
-  providers: { mock: { adapter: "openai-chat", baseUrl: "http://127.0.0.1/v1" } },
-} as OcxConfig;
-
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -219,31 +180,11 @@ export function parseJsonc(text: string): unknown {
   }
 }
 
-/**
- * Resolve the user's global opencode config path. opencode uses the XDG layout on every
- * platform (including Windows, where it is %USERPROFILE%\.config\opencode).
- */
-export function opencodeGlobalConfigPath(
-  env: OpencodeLaunchEnv = process.env,
-  home: string = homedir(),
-): string {
-  const xdg = env.XDG_CONFIG_HOME && env.XDG_CONFIG_HOME.length > 0 ? env.XDG_CONFIG_HOME : join(home, ".config");
-  return join(xdg, "opencode", "opencode.json");
-}
-
 /** Model key as the proxy routes it: `provider/id` for routed models, bare slug for native OpenAI entries. */
 export function opencodeModelKey(provider: string, id: string): string {
   return provider === "native" ? id : `${provider}/${id}`;
 }
 
-/** Compose the OpenAI-compatible proxy base URL from a live probe result. */
-export function opencodeProxyBaseUrl(port: number, hostname?: string): string {
-  return `http://${probeHostname(hostname)}:${port}/v1`;
-}
-
-/** Env reference shared by apiKey and the dedicated proxy admission header. */
-export const OPENCODE_API_KEY_ENV_REF = `{env:${OPENCODE_API_KEY_ENV}}`;
-
 /**
  * Native OpenAI slugs advertised to opencode. Omitted in Codex Direct mode because native
  * chat-completions require the caller's real ChatGPT OAuth bearer, not proxy admission.
@@ -253,62 +194,6 @@ export function opencodeLaunchNativeSlugs(config: OcxConfig): string[] {
   return [...visibleNativeSlugs(config)];
 }
 
-function opencodeProviderOptions(baseURL: string, config: OcxConfig): OpencodeProviderBlock["options"] {
-  const options: OpencodeProviderBlock["options"] = { baseURL };
-  // Non-loopback binds accept proxy admission only via x-opencodex-api-key so Authorization
-  // stays free for Codex Direct upstream credentials when applicable.
-  if (shouldInjectApiAuthHeader(config)) {
-    options.headers = { "x-opencodex-api-key": OPENCODE_API_KEY_ENV_REF };
-    return options;
-  }
-  options.apiKey = OPENCODE_API_KEY_ENV_REF;
-  return options;
-}
-
-function opencodeModelEntryLabel(model: OpencodeCatalogModel): string {
-  const providerLabel = model.native ? "native" : (model.provider ?? "routed");
-  const id = model.id ?? model.namespaced;
-  if (model.displayName && model.displayName.length > 0) {
-    return `${model.displayName} (${providerLabel})`;
-  }
-  return `${id} (${providerLabel})`;
-}
-
-/**
- * Build the `opencodex` provider block from proxy catalog rows keyed by each row's
- * canonical `namespaced` selector.
- *
- * `limit.context` is emitted ONLY from an authoritative context window — never guessed.
- * When none is available the whole `limit` block is dropped and opencode keeps its own
- * defaults; when one is present, `limit.output` rides along (opencode's schema requires
- * the pair) clamped to the context window.
- */
-export function buildOpencodeProviderBlockFromCatalog(
-  port: number,
-  catalogModels: readonly OpencodeCatalogModel[],
-  hostname?: string,
-  config: OcxConfig = OPENCODE_PROVIDER_BLOCK_DEFAULT_CONFIG,
-): OpencodeProviderBlock {
-  const models: Record<string, OpencodeModelEntry> = {};
-  for (const model of catalogModels) {
-    const key = model.namespaced;
-    if (models[key]) continue; // first entry wins; native rows lead /api/models
-    const entry: OpencodeModelEntry = { name: opencodeModelEntryLabel(model) };
-    const { contextWindow } = model;
-    if (typeof contextWindow === "number" && Number.isFinite(contextWindow) && contextWindow > 0) {
-      const context = Math.floor(contextWindow);
-      entry.limit = { context, output: Math.min(SCHEMA_REQUIRED_OUTPUT_BUDGET, context) };
-    }
-    models[key] = entry;
-  }
-  return {
-    npm: OPENCODE_PROVIDER_NPM,
-    name: "OpenCodex",
-    options: opencodeProviderOptions(opencodeProxyBaseUrl(port, hostname), config),
-    models,
-  };
-}
-
 /** Back-compat helper for unit tests that assemble slugs/routed rows directly. */
 export function buildOpencodeProviderBlock(
   port: number,

package/src/cli/star-prompt.ts

@@ -4,7 +4,7 @@ import { spawnSync } from "node:child_process";
 import { getConfigDir } from "../config";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 import { commandInvocation } from "../lib/win-exec";
-import { isAgentDriven } from "./agent-driven";
+import { agentDrivenMarkers, isAgentDriven } from "./agent-driven";
 import { interactiveConfirm } from "./interactive-confirm";
 
 const REPO = "lidge-jun/opencodex";
@@ -73,11 +73,20 @@ function starRepo(): { ok: boolean; error?: string } {
  * request reaches the user through the agent instead of disappearing.
  */
 function printAgentDeferral(): void {
+  const markers = agentDrivenMarkers();
+  const detected = markers.length > 0 ? markers.slice(0, 3).join(", ") : "agent environment";
   console.log(
     `\n  \x1b[38;5;141m⭐ opencodex isn't starred on GitHub yet.\x1b[0m\n` +
-    `  \x1b[2mAgent: do not answer this yourself — it uses the user's GitHub identity.\n` +
-    `  Ask the user whether to star ${REPO}, and only run\n` +
-    `  \`gh api -X PUT /user/starred/${REPO}\` if they say yes.\x1b[0m\n`,
+    `  \x1b[2mAgent-driven session detected (${detected}), so this prompt was not shown.\n` +
+    `\n` +
+    `  Agent: STOP and ask the user. Do not answer this on their behalf and do not\n` +
+    `  infer consent from the task you were given — starring writes to the user's own\n` +
+    `  GitHub account, which is outside anything they asked you to change.\n` +
+    `\n` +
+    `    1. Ask the user, in your reply, whether to star ${REPO}.\n` +
+    `    2. Only if they answer yes, run:\n` +
+    `         gh api -X PUT /user/starred/${REPO}\n` +
+    `    3. If they say no, or do not answer, do nothing and never ask again.\x1b[0m\n`,
   );
 }
 

package/src/cli/status-oauth.ts

@@ -1,5 +1,7 @@
 import { maskAccountId } from "../lib/privacy";
 import {
+  CODEX_HEALTH_AUTH_FAILED_NOTE,
+  CODEX_HEALTH_MANAGEMENT_API_UNAVAILABLE_NOTE,
   CODEX_HEALTH_UNAVAILABLE_NOTE,
   MASKED_ACCOUNT_FALLBACK,
   type OAuthAccountHealth,
@@ -59,8 +61,16 @@ export function formatOAuthHealthForStatus(
     : input;
 
   const parts: string[] = [];
-  if (report.codexHealthSource === "unavailable") {
-    parts.push(CODEX_HEALTH_UNAVAILABLE_NOTE);
+  switch (report.codexHealthSource) {
+    case "unavailable":
+      parts.push(CODEX_HEALTH_UNAVAILABLE_NOTE);
+      break;
+    case "management-auth-failed":
+      parts.push(CODEX_HEALTH_AUTH_FAILED_NOTE);
+      break;
+    case "management-api-unavailable":
+      parts.push(CODEX_HEALTH_MANAGEMENT_API_UNAVAILABLE_NOTE);
+      break;
   }
   const oauthBlock = formatEntryBlock(report.entries);
   if (oauthBlock) parts.push(oauthBlock);