@bitkyc08/opencodex 2.76.0 → 2.77.0

package/src/cli/root.ts

@@ -8,11 +8,13 @@
  * the exit paths and the shim preflight, then returns the dispatchable head
  * for the command switch in src/cli/index.ts.
  */
-import { hasHelpFlag, printSubcommandUsage, printUsage, printVersion } from "./help";
+import { printFullUsage, printSubcommandUsage, printUsage, printVersion } from "./help";
 import { parseReadyArgs, type ReadyArgs } from "./ready";
 import { parseResolveArgs, type ResolveArgs } from "./resolve";
 import { parseStopApproval } from "./stop-approval";
 import { maybeAutoRestoreCodexShim } from "./codex-shim-autorestore";
+import { findCommand } from "./registry";
+import { printUnknownCommand } from "./help-recovery";
 
 export interface CliHead {
   kind: "version" | "help" | "ready" | "resolve" | "command";
@@ -20,6 +22,10 @@ export interface CliHead {
   args: string[];
   /** For kind "help": the subcommand whose usage should print, if any. */
   helpTarget?: string;
+  /** Explicit multi-token help topic; never passed to command execution. */
+  helpPath?: string[];
+  /** Complete static reference requested from root help. */
+  helpAll?: boolean;
   /** Present only for `ready`; undefined when the ready args failed to parse. */
   readyArgs?: ReadyArgs;
   /** Present only for `resolve`; undefined when the resolve args failed to parse. */
@@ -32,19 +38,26 @@ export function parseCliHead(argv: string[]): CliHead {
   if (command === "--version" || command === "-v" || command === "version") {
     return { kind: "version", command, args };
   }
-  if (command === undefined || command === "help" || command === "--help" || command === "-h") {
-    // `ocx help <sub>` carries the subcommand; bare/flag help prints the full usage.
+  const boundary = argv.indexOf("--");
+  const prefix = boundary < 0 ? argv : argv.slice(0, boundary);
+  const rootHelp = command === undefined || command === "help" || command === "--help" || command === "-h";
+  const commandHelp = prefix[1] === "help";
+  if (rootHelp || commandHelp || prefix.slice(1).some(value => value === "--help" || value === "-h")) {
+    const topic = rootHelp ? prefix.slice(1)
+      : commandHelp ? [command!, ...prefix.slice(2)] : prefix;
+    // Options and their operands are not part of a help topic. Keep argv intact.
+    const option = topic.findIndex((value, index) => value.startsWith("-")
+      && (index > 0 || (rootHelp && ["--all", "--help", "-h"].includes(value))));
+    const path = option < 0 ? topic : topic.slice(0, option);
     return {
       kind: "help",
       command,
       args,
-      ...(command === "help" && args[1] ? { helpTarget: args[1] } : {}),
+      ...(path.length ? { helpTarget: path[0] } : {}),
+      ...(path.length > 1 ? { helpPath: path } : {}),
+      ...(rootHelp && path.length === 0 && prefix.includes("--all") ? { helpAll: true } : {}),
     };
   }
-  if (command !== "help" && hasHelpFlag(args.slice(1))) {
-    // `ocx <cmd> --help|-h|help` prints that command's usage, not the full list.
-    return { kind: "help", command, args, helpTarget: command };
-  }
   // P1: pre-parse `ocx ready` and reject invalid arguments with exit 64 BEFORE
   // maybeAutoRestoreCodexShim (or any discovery/probe/filesystem-capable global
   // preflight) runs. `ready --help` / `help ready` already exited above, so this
@@ -72,7 +85,11 @@ export async function runCli(argv: string[]): Promise<CliHead> {
       printVersion();
       process.exit(0);
     case "help": {
-      if (head.helpTarget) printSubcommandUsage(head.helpTarget);
+      if (head.helpAll) printFullUsage();
+      else if (head.helpTarget) printSubcommandUsage(head.helpTarget, head.helpPath, {
+        fallbackToParent: head.command !== "help" && head.command !== "--help"
+          && head.command !== "-h" && head.args[1] !== "help",
+      });
       else printUsage();
       process.exit(0);
     }
@@ -104,6 +121,10 @@ export async function runCli(argv: string[]): Promise<CliHead> {
       return head;
     }
     case "command":
+      if (head.command !== "internal" && !findCommand(head.command ?? "")) {
+        printUnknownCommand(head.command);
+        process.exit(1);
+      }
       if (head.command === "stop" && !parseStopApproval(head.args.slice(1)).ok) {
         console.error("Usage: ocx stop [--json [--expect-pid <pid> --expect-port <port> --expect-hostname <host> --expect-config-home <home> --expect-cli-version <version> --expect-compatibility-token <hex>]]");
         process.exit(64);

package/src/cli/runtime-api.ts

@@ -471,7 +471,7 @@ export async function readSecretBytes(
 
 export function printData(value: unknown, wantsJson: boolean, lines?: string[]): void {
   if (wantsJson || !lines) console.log(JSON.stringify(value, null, 2));
-  else for (const line of lines) console.log(line);
+  else for (const line of lines) console.log(terminalSafeText(line));
 }
 
 /**

package/src/cli/tray-proxy.ts

@@ -128,11 +128,12 @@ export function reobserveRestartReplacement(
   deadlineAt: number,
   observe: (end: number) => Promise<ProxyRestartDiscovery>,
 ): Promise<ProxyRestartDiscovery> {
-  const windowMs = Math.min(5_000, deadlineAt - Date.now());
+  const now = Date.now();
+  const windowMs = Math.min(5_000, deadlineAt - now);
   if (windowMs < 1_500) return Promise.resolve({
     status: "uncertain", error: new Error("restart_reobserve_window_exhausted"),
   });
-  const end = Date.now() + windowMs;
+  const end = now + windowMs;
   return pollReplacementDeparture(() => observe(end), previous, () => Date.now() + 750 < end, () => Bun.sleep(250));
 }
 

package/src/clients/config-export/contracts.ts

@@ -1,7 +1,10 @@
 // Shared client export contracts.
+import { canonicalizeReasoningEfforts } from "../../reasoning-effort";
 import type { OcxConfig } from "../../types";
 import type { ConfigFormat } from "../../integrations/serialize";
 
+export const DROID_DEFAULT_EFFORT_HEADER = "x-opencodex-droid-default-effort";
+
 /**
  * One entry opencodex owns inside a client's config: the JSON path to it and
  * the value we put there.
@@ -38,6 +41,12 @@ export interface OpencodeCatalogModel {
   id?: string;
   contextWindow?: number;
   maxTokens?: number;
+  /**
+   * Authoritative input ceiling, distinct from `contextWindow` (GPT-5.6 advertises 922k
+   * usable input under a 1.05M window). Carried from the catalog row so a client that has a
+   * separate input limit never treats the whole window as prompt budget.
+   */
+  maxInputTokens?: number;
   displayName?: string;
   /**
    * Declared input modalities, carried verbatim from `/api/models`. Serialized as opencode's
@@ -54,6 +63,9 @@ export interface OpencodeCatalogModel {
    * model-level setting — see {@link opencodeEffortVariants} for why.
    */
   defaultReasoningEffort?: string;
+  supportsTools?: boolean;
+  supportsReasoning?: boolean;
+  supportsReasoningSummaries?: boolean;
 }
 
 /**
@@ -73,10 +85,94 @@ export interface ExportModel {
   displayName?: string;
   contextWindow?: number;
   maxTokens?: number;
+  /** Authoritative input ceiling; optional and never guessed from the context window. */
+  maxInputTokens?: number;
   inputModalities?: string[];
   /** Optional effort ladder exported only to clients that support it. */
   reasoningEfforts?: string[];
   defaultReasoningEffort?: string;
+  supportsTools?: boolean;
+  supportsReasoning?: boolean;
+  supportsReasoningSummaries?: boolean;
+}
+
+/**
+ * Effective, override-applied export metadata for one model row: what a client export should
+ * serialize, as distinct from the raw editor representation `/api/models` also carries.
+ *
+ * Custom rows are the reason this exists. Their row fields are the operator's stored
+ * OVERRIDES (an absent field means "not overridden", an empty ladder means "no rungs"), so a
+ * serializer reading only them drops every capability the model inherits from the provider,
+ * the registry, or the gathered catalog. The management row list resolves that projection
+ * from the same canonical sources routed rows use and attaches it additively — the raw
+ * override fields stay exactly what the editor wrote.
+ */
+export interface EffectiveModelExportMetadata {
+  contextWindow?: number;
+  /** Input ceiling; distinct from `contextWindow`, carried only when a source asserts one. */
+  maxInputTokens?: number;
+  /** Output ceiling (a catalog row's `maxOutputTokens`). */
+  maxTokens?: number;
+  inputModalities?: string[];
+  /** Effective ladder; `[]` is an explicit "no rungs" declaration and survives as `[]`. */
+  reasoningEfforts?: string[];
+  /**
+   * A default some canonical source declared — never one synthesized from the ladder's
+   * preference order, and only when it is a member of the effective ladder. An empty
+   * ladder suppresses it entirely: there is no rung to default to.
+   */
+  defaultReasoningEffort?: string;
+  supportsTools?: boolean;
+  supportsReasoning?: boolean;
+  supportsReasoningSummaries?: boolean;
+}
+
+/**
+ * The per-row evidence the capability booleans are derived from. Only positive, canonical
+ * signals — no independent provider fact tables, no name-based inference.
+ */
+export interface ExportCapabilityEvidence {
+  native?: boolean;
+  reasoningEfforts?: readonly string[];
+  supportsReasoningSummaries?: boolean;
+  /** Normalized upstream capability names a catalog row carried (e.g. `"tools"`). */
+  capabilities?: readonly string[];
+  /** Provider-level parallel tool call opt-in for this model. */
+  parallelToolCalls?: boolean;
+}
+
+/**
+ * Tool support a canonical source positively asserts, or undefined when nothing is known.
+ *
+ * Mirrors the routing reader (`src/routing/capability.ts`): a catalog row without `"tools"`
+ * is UNKNOWN, never a negative — the row may simply not enumerate capabilities. `native`
+ * rows and the parallel-call opt-in are positive evidence on their own.
+ */
+export function knownToolsSupport(evidence: ExportCapabilityEvidence): boolean | undefined {
+  if (evidence.native === true) return true;
+  if (evidence.capabilities?.includes("tools") === true) return true;
+  if (evidence.parallelToolCalls === true) return true;
+  return undefined;
+}
+
+/**
+ * Reasoning support a canonical source positively asserts, or undefined when nothing is
+ * known.
+ *
+ * Never `false` from a missing or empty effort ladder: an empty ladder says "no ADJUSTABLE
+ * effort", which is not the claim "cannot reason" — a model can reason at a fixed depth with
+ * no rung to select. Known evidence is a positive reasoning rung (the catalog's own statement
+ * that the model accepts reasoning parameters) or delivered reasoning summaries. `none` is
+ * the off sentinel, not a rung: a ladder of only `none` offers an off variant and asserts
+ * nothing about whether the model reasons, so it is not positive evidence on its own.
+ */
+export function knownReasoningSupport(evidence: ExportCapabilityEvidence): boolean | undefined {
+  if (evidence.supportsReasoningSummaries === true) return true;
+  if (evidence.reasoningEfforts !== undefined
+    && canonicalizeReasoningEfforts(evidence.reasoningEfforts).some(effort => effort !== "none")) {
+    return true;
+  }
+  return undefined;
 }
 
 export interface ExportContext {
@@ -88,8 +184,12 @@ export interface ExportContext {
    * admission from `apiKey` to the `x-opencodex-api-key` header.
    */
   config?: OcxConfig;
+  droidReasoningDefaults?: DroidReasoningDefaults;
 }
 
+/** Namespaced model selector to one of that model's declared reasoning efforts. */
+export type DroidReasoningDefaults = Record<string, string>;
+
 export type ExportClientId =
   | "opencode"
   | "pi"

package/src/clients/config-export/droid.ts

@@ -1,9 +1,11 @@
 import { win32, join } from "node:path";
 import { homedir } from "node:os";
 import { exportPresentationLabel } from "../model-presentation";
-import type { ExportContext, ManagedContribution, OpencodeLaunchEnv } from "./contracts";
+import type { DroidReasoningDefaults, ExportContext, ExportModel, ManagedContribution, OpencodeLaunchEnv } from "./contracts";
 import { normalizeExportModels } from "./model-metadata";
-import { formatSelectorConjunction } from "../../integrations/merge";
+import { formatSelectorConjunction, readPath } from "../../integrations/merge";
+
+import { DROID_DEFAULT_EFFORT_HEADER } from "./contracts";
 
 /** Factory personal settings: https://docs.factory.ai/model-independence/byok */
 export interface DroidModelEntry {
@@ -12,6 +14,7 @@ export interface DroidModelEntry {
   baseUrl: string;
   provider: "generic-chat-completion-api";
   noImageSupport: boolean;
+  extraHeaders?: Record<string, string>;
 }
 
 export interface DroidGeneratedConfig { customModels: DroidModelEntry[] }
@@ -43,11 +46,60 @@ function buildDroidRows(ctx: ExportContext): Array<{ row: DroidModelEntry; selec
       baseUrl: ctx.baseUrl,
       provider: "generic-chat-completion-api",
       noImageSupport: !model.inputModalities?.includes("image"),
+      ...(ctx.droidReasoningDefaults && Object.hasOwn(ctx.droidReasoningDefaults, model.namespaced)
+        ? { extraHeaders: { [DROID_DEFAULT_EFFORT_HEADER]: ctx.droidReasoningDefaults[model.namespaced]! } }
+        : {}),
     } });
   }
   return rows;
 }
 
+export function droidReasoningModels(models: readonly ExportModel[]): Array<{ model: string; label: string; efforts: string[] }> {
+  const effortsByModel = new Map(normalizeExportModels(models).map(model => [model.namespaced, model.reasoningEfforts ?? []]));
+  return buildDroidRows({ baseUrl: "", models }).map(({ row }) => ({
+    model: row.model,
+    label: row.displayName.replace(/^OpenCodex: /, ""),
+    efforts: effortsByModel.get(row.model) ?? [],
+  }));
+}
+
+export function droidDefaultsFromOwnedRows(
+  ctx: ExportContext,
+  document: unknown,
+  fragmentPaths: readonly (readonly string[])[],
+): DroidReasoningDefaults {
+  const exportableModels = new Map(droidReasoningModels(ctx.models).map(model => [model.model, model.efforts]));
+  const defaults: DroidReasoningDefaults = {};
+  for (const path of fragmentPaths) {
+    if (path.length !== 2 || path[0] !== "customModels") continue;
+    const value = readPath(document, path);
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    const current = value as Record<string, unknown>;
+    if (typeof current.model !== "string" || !exportableModels.has(current.model)) continue;
+    const headers = current.extraHeaders;
+    if (!headers || typeof headers !== "object" || Array.isArray(headers)) continue;
+    const header = headers as Record<string, unknown>;
+    const effort = header[DROID_DEFAULT_EFFORT_HEADER];
+    if (typeof effort !== "string" || !exportableModels.get(current.model)?.includes(effort)) continue;
+    defaults[current.model] = effort;
+  }
+  return defaults;
+}
+
+export function validateDroidReasoningDefaults(
+  models: readonly ExportModel[],
+  defaults: unknown,
+): string | null {
+  if (!defaults || typeof defaults !== "object" || Array.isArray(defaults)) return "droidReasoningDefaults must be an object";
+  const addressable = new Map(droidReasoningModels(models).map(model => [model.model, model.efforts]));
+  for (const [model, effort] of Object.entries(defaults)) {
+    const efforts = addressable.get(model);
+    if (!efforts) return `model ${model} is not currently exportable to Droid`;
+    if (typeof effort !== "string" || !efforts.includes(effort)) return `effort for ${model} is not declared by that model`;
+  }
+  return null;
+}
+
 export function buildDroidClientConfig(ctx: ExportContext): DroidGeneratedConfig {
   const rows = buildDroidRows(ctx);
   if (ctx.models.length > 0 && rows.length === 0) {

package/src/clients/config-export/kilo.ts

@@ -14,9 +14,11 @@ import {
   normalizeExportModels,
   opencodeModelCapabilities,
   outputBudgetFor,
+  inputBudgetFor,
   proxyAdmissionHeaders,
   singleFragment,
 } from "./model-metadata";
+import { legacyReasoningMetadata, type LegacyEffortVariant } from "./reasoning-metadata";
 
 export const KILO_CONFIG_CANDIDATES = [
   "kilo.jsonc",
@@ -28,9 +30,14 @@ export const KILO_CONFIG_CANDIDATES = [
 
 export interface KiloModelEntry {
   name: string;
-  limit?: { context: number; output: number };
+  limit?: { context: number; input?: number; output: number };
   attachment?: boolean;
   modalities?: { input: string[]; output: string[] };
+  tool_call?: boolean;
+  reasoning?: boolean;
+  interleaved?: { field: "reasoning_content" };
+  options?: { reasoningEffort: string };
+  variants?: Record<string, LegacyEffortVariant>;
 }
 
 export interface KiloProviderBlock {
@@ -77,11 +84,14 @@ function kiloProviderBlock(ctx: ExportContext): KiloProviderBlock {
   const config = ctx.config ?? OPENCODE_PROVIDER_BLOCK_DEFAULT_CONFIG;
   const models: Record<string, KiloModelEntry> = {};
   for (const model of normalizeExportModels(ctx.models)) {
-    const entry: KiloModelEntry = { name: exportModelLabel(model) };
+    const entry: KiloModelEntry = { name: exportModelLabel(model), ...legacyReasoningMetadata(model) };
     const context = authoritativeContextWindow(model.contextWindow);
     if (context !== undefined) {
       entry.limit = { context, output: outputBudgetFor(context, model) };
+      const input = inputBudgetFor(context, model);
+      if (input !== undefined) entry.limit.input = input;
     }
+    if (typeof model.supportsTools === "boolean") entry.tool_call = model.supportsTools;
     const capabilities = opencodeModelCapabilities(model.inputModalities);
     if (capabilities) {
       entry.attachment = capabilities.attachment;

package/src/clients/config-export/model-metadata.ts

@@ -29,6 +29,12 @@ export function outputBudgetFor(context: number, model: OpencodeCatalogModel): n
   return Math.min(limit, context);
 }
 
+/** Input limits are optional: unlike output, a missing limit needs no schema fallback. */
+export function inputBudgetFor(context: number, model: OpencodeCatalogModel): number | undefined {
+  const limit = authoritativeContextWindow(model.maxInputTokens);
+  return limit === undefined ? undefined : Math.min(limit, context);
+}
+
 /**
  * Modalities a given client's schema will actually accept.
  *
@@ -89,12 +95,12 @@ export function inputModalitiesForClient(
 const OPENCODE_INPUT_MODALITIES: ReadonlySet<string> = new Set(["text", "audio", "image", "video", "pdf"]);
 
 /**
- * opencode's per-model capability fields for one catalog row, or `undefined` when the row
+ * Legacy per-model modality fields for one catalog row, or `undefined` when the row
  * declares nothing.
  *
- * `undefined` rather than `{ input: ["text"] }`: opencode already computes an entry without
- * capabilities as text-only, and leaving the keys out keeps every model that declares
- * nothing byte-identical to what shipped before. A declared list is carried across as-is, so
+ * `undefined` rather than guessing `{ input: ["text"] }`: unknown capabilities leave the
+ * client's fallback assumptions in place. V2 translates these lists into native capability
+ * fields; legacy clients also receive the attachment flag. A declared list is carried across as-is, so
  * an audio-only row keeps `attachment: true` instead of being rewritten to text it cannot
  * read — the same call Pi's exporter makes, in the opposite direction.
  */

package/src/clients/config-export/reasoning-metadata.ts

@@ -0,0 +1,47 @@
+import { canonicalizeReasoningEfforts, isDeclaredReasoningEffort } from "../../reasoning-effort";
+import { knownReasoningSupport, type OpencodeCatalogModel } from "./contracts";
+
+/** Unknown and explicitly empty ladders have different client-side meanings. */
+export function exportReasoningEfforts(model: OpencodeCatalogModel): string[] | undefined {
+  return model.reasoningEfforts === undefined ? undefined : canonicalizeReasoningEfforts(model.reasoningEfforts);
+}
+
+/** Carry an authoritative default, never invent one or revive a cleared ladder. */
+export function exportDefaultReasoningEffort(model: OpencodeCatalogModel): string | undefined {
+  const effort = model.defaultReasoningEffort;
+  if (typeof effort !== "string" || !isDeclaredReasoningEffort(effort)) return undefined;
+  const efforts = exportReasoningEfforts(model);
+  return efforts === undefined || efforts.includes(effort) ? effort : undefined;
+}
+
+export type LegacyEffortVariant = { reasoningEffort: string } | { disabled: true };
+
+/** Shared V1-family controls. A disabled-only map suppresses client-invented effort ladders. */
+export function legacyReasoningMetadata(model: OpencodeCatalogModel): {
+  reasoning?: boolean;
+  options?: { reasoningEffort: string };
+  interleaved?: { field: "reasoning_content" };
+  variants?: Record<string, LegacyEffortVariant>;
+} {
+  const efforts = exportReasoningEfforts(model);
+  const reasoning = model.supportsReasoning ?? knownReasoningSupport({
+    ...model, reasoningEfforts: efforts,
+  });
+  const defaultEffort = exportDefaultReasoningEffort(model);
+  // Both legacy runtimes merge generated variants with config, then filter disabled IDs.
+  // An unrelated sentinel leaves their generated choices alive. Disable the actual IDs
+  // instead (live-tested on Kilo 7.8.3, checked against stock OpenCode V1's merge).
+  const suppressed: Record<string, LegacyEffortVariant> = Object.fromEntries(
+    ["none", "minimal", "low", "medium", "high", "xhigh", "max"].map(id => [id, { disabled: true }]),
+  );
+  const variants = efforts?.length
+    ? Object.fromEntries(efforts.map(effort => [effort, { reasoningEffort: effort }]))
+    : reasoning === true ? suppressed : undefined;
+  return {
+    ...(typeof reasoning === "boolean" ? { reasoning } : {}),
+    ...(defaultEffort !== undefined ? { options: { reasoningEffort: defaultEffort } } : {}),
+    ...(reasoning === true || model.supportsReasoningSummaries === true
+      ? { interleaved: { field: "reasoning_content" } } : {}),
+    ...(variants !== undefined ? { variants } : {}),
+  };
+}