@bitkyc08/opencodex 2.6.32 → 2.7.1-preview.20260710

package/src/adapters/cursor/protobuf-request.ts

@@ -22,6 +22,8 @@ import {
   McpToolResultSchema,
   ModelDetailsSchema,
   ResumeActionSchema,
+  RequestContextSchema,
+  RequestContextEnvSchema,
   ThinkingMessageSchema,
   ToolCallSchema,
   UserMessageActionSchema,
@@ -39,6 +41,24 @@ import {
 
 const encoder = new TextEncoder();
 
+/** Runtime timezone for protobuf RequestContextEnv (dynamic, never hardcoded). */
+function runtimeTimeZone(): string {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone ?? "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+
+/** Builds a RequestContext with env.timeZone populated dynamically. */
+function buildRequestContext() {
+  return create(RequestContextSchema, {
+    env: create(RequestContextEnvSchema, {
+      timeZone: runtimeTimeZone(),
+    }),
+  });
+}
+
 function jsonBlob(value: unknown): Uint8Array {
   return encoder.encode(JSON.stringify(value));
 }
@@ -307,11 +327,14 @@ export function encodeCursorRunRequest(request: CursorRunRequest): Uint8Array {
               text,
               messageId: crypto.randomUUID(),
             }),
+            requestContext: buildRequestContext(),
           }),
         }
       : {
           case: "resumeAction",
-          value: create(ResumeActionSchema, {}),
+          value: create(ResumeActionSchema, {
+            requestContext: buildRequestContext(),
+          }),
         },
   });
 

package/src/adapters/cursor/request-builder.ts

@@ -8,17 +8,18 @@ import type {
 } from "../../types";
 import { namespacedToolName } from "../../types";
 import type { CursorRequestMessage, CursorRunRequest } from "./types";
+import { cursorCodexToWireModelId } from "./discovery";
 import { cursorEffortSuffix } from "./effort-map";
 
 /**
  * Resolve a `cursor/<model>` selection + Codex reasoning effort to the actual Cursor model id. Cursor
- * encodes the effort as a per-model suffix (`claude-4.6-opus-high`); `cursorEffortSuffix` picks the
- * right tier for that specific model (top effort → the model's top tier, e.g. `-max`/`-xhigh`) or
- * `undefined` for non-reasoning models like `composer-2.5`. A fully-qualified id (one that isn't a
- * known effort base) passes through unchanged.
+* encodes the effort as a per-model suffix (`claude-4.6-opus-high`); `cursorEffortSuffix` picks the
+ * right tier for that specific model (literal pass-through, with rank clamp fallback) or
+* `undefined` for non-reasoning models like `composer-2.5`. A fully-qualified id (one that isn't a
+* known effort base) passes through unchanged.
  */
 function normalizeCursorModelId(modelId: string, reasoning?: string): string {
-  const id = modelId.startsWith("cursor/") ? modelId.slice("cursor/".length) : modelId;
+  const id = cursorCodexToWireModelId(modelId);
   const suffix = cursorEffortSuffix(id, reasoning);
   return suffix ? `${id}-${suffix}` : id;
 }

package/src/adapters/cursor/transport-retry.ts

@@ -1,6 +1,8 @@
 import type { CursorRunRequest, CursorServerMessage } from "./types";
 import type { CursorTransport, CursorTransportFactory, CursorTransportFactoryInput } from "./transport";
 import { abortError, sleepWithAbort } from "../../lib/upstream-retry";
+import { debugProviderDiagnostic } from "../../lib/debug";
+import { safeCursorErrorMessage } from "./cursor-errors";
 
 // Compat: historical name for the shared abortable sleep, kept for external callers.
 export { sleepWithAbort as abortAwareSleep } from "../../lib/upstream-retry";
@@ -20,6 +22,8 @@ export function isRetryableCursorError(err: unknown): boolean {
   const message = err instanceof Error ? err.message : typeof err === "string" ? err : "";
   const haystack = `${code} ${message}`.toLowerCase();
   if (/auth|unauthor|forbidden|invalid|permission|denied|not found|unsupported/.test(haystack)) return false;
+  if (/resource.exhausted|resource_exhausted|rate limit|too many requests|throttl/.test(haystack)) return false;
+  if (haystack.includes("nghttp2_cancel") || haystack.includes("stream suspended")) return false;
   return (
     haystack.includes("econnreset") ||
     haystack.includes("econnrefused") ||
@@ -27,7 +31,7 @@ export function isRetryableCursorError(err: unknown): boolean {
     haystack.includes("enetunreach") ||
     haystack.includes("eai_again") ||
     haystack.includes("goaway") ||
-    haystack.includes("nghttp2") ||
+    (haystack.includes("nghttp2") && !haystack.includes("nghttp2_cancel")) ||
     haystack.includes("socket hang up") ||
     haystack.includes("connection reset") ||
     haystack.includes("unavailable") ||
@@ -83,8 +87,23 @@ export async function runCursorTurnWithRetry(
         !signal?.aborted &&
         requestUncommitted(transport) &&
         isRetryableCursorError(err);
-      if (!canRetry) throw err;
-      await sleepWithAbort(cursorRetryDelayMs(attempt), signal);
+      if (!canRetry) {
+        debugProviderDiagnostic("cursor", "no-retry", {
+          attempt,
+          reason: safeCursorErrorMessage(err instanceof Error ? err.message : String(err)),
+          emittedAny,
+          committed: !requestUncommitted(transport),
+          aborted: !!signal?.aborted,
+        });
+        throw err;
+      }
+      const backoffMs = cursorRetryDelayMs(attempt);
+      debugProviderDiagnostic("cursor", "retry", {
+        attempt,
+        reason: safeCursorErrorMessage(err instanceof Error ? err.message : String(err)),
+        backoffMs,
+      });
+      await sleepWithAbort(backoffMs, signal);
     } finally {
       await transport.close?.();
     }

package/src/adapters/cursor.ts

@@ -1,7 +1,7 @@
 import type { AdapterEvent, OcxProviderConfig } from "../types";
 import type { ProviderAdapter } from "./base";
 import { cursorExecDeniedMessage } from "./cursor/exec-policy";
-import { safeCursorErrorMessage } from "./cursor/cursor-errors";
+import { isCursorBenignCancelError, safeCursorErrorMessage } from "./cursor/cursor-errors";
 import { createCursorKvStore, type CursorKvStore } from "./cursor/kv-store";
 import { mapCursorServerMessage } from "./cursor/message-mapper";
 import { createCursorRequest, generatedCursorConversationId } from "./cursor/request-builder";
@@ -91,6 +91,7 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
           },
         );
       } catch (err) {
+        if (isCursorBenignCancelError(err)) return;
         const partialUsage = (err as { partialUsage?: import("../types").OcxUsage }).partialUsage;
         emit({ type: "error", message: safeCursorTransportError(err), ...(partialUsage ? { usage: partialUsage } : {}) });
       }

package/src/adapters/openai-chat.ts

@@ -76,7 +76,9 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
             type: "function",
             function: { name: namespacedToolName(tc.namespace, tc.name), arguments: JSON.stringify(tc.arguments) },
           }));
-          if (!chatMsg.content) chatMsg.content = null;
+          // "" instead of null: strict validators (xAI: "Each message must have at least one
+          // content element", langchain#34140) reject content-less assistant history entries.
+          if (!chatMsg.content) chatMsg.content = "";
         }
         if (chatMsg.reasoning_content !== undefined && chatMsg.content === undefined && chatMsg.tool_calls === undefined) {
           chatMsg.content = "";
@@ -97,7 +99,7 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
           const name = safeToolName(msg.toolName);
           out.push({
             role: "assistant",
-            content: null,
+            content: "",
             tool_calls: [{
               id: toolCallId,
               type: "function",
@@ -166,6 +168,20 @@ function usageFromOpenAIChat(usage: Record<string, unknown> | undefined): OcxUsa
   };
 }
 
+function thinkingBudgetForEffort(parsed: OcxParsedRequest, reasoningEffort: string): number | undefined {
+  if (parsed.options.reasoning === "minimal") return 0;
+  const maxBudget = parsed.options.maxOutputTokens ?? 32768;
+  const fractions: Record<string, number> = {
+    low: 0.20,
+    medium: 0.50,
+    high: 0.75,
+    xhigh: 0.90,
+    max: 1.0,
+  };
+  const fraction = fractions[reasoningEffort];
+  return fraction === undefined ? undefined : Math.max(1, Math.floor(maxBudget * fraction));
+}
+
 export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAdapter {
   return {
     name: "openai-chat",
@@ -196,7 +212,10 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
       if (parsed.options.stopSequences !== undefined) body.stop = parsed.options.stopSequences;
       const reasoningEffort = mapReasoningEffort(provider, parsed.modelId, parsed.options.reasoning);
       if (reasoningEffort !== undefined) {
-        if (modelInList(provider.thinkingToggleModels, parsed.modelId)) {
+        if (modelInList(provider.thinkingBudgetModels, parsed.modelId)) {
+          const budget = thinkingBudgetForEffort(parsed, reasoningEffort);
+          if (budget !== undefined) body.thinking_budget = budget;
+        } else if (modelInList(provider.thinkingToggleModels, parsed.modelId)) {
           // Vendor thinking-toggle wire (MiMo v2.x, GLM 5/5.1): the mapped value is the toggle
           // state, sent as `thinking: {type}` — these models ignore/reject reasoning_effort.
           if (reasoningEffort === "enabled" || reasoningEffort === "disabled") {
@@ -213,7 +232,15 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
         body.frequency_penalty = parsed.options.frequencyPenalty;
       }
 
-      if (tools) body.parallel_tool_calls = false;
+      if (tools) {
+        // Default-ON for chat-completions providers (user decision 260709): the buffered
+        // parser assembles multi-call streams safely, so `parallelToolCalls: false` is the
+        // only per-provider opt-out; Codex's request bit can still force false per request.
+        // Rationale + provider evidence: devlog/_plan/260709_parallel_tool_calls.
+        body.parallel_tool_calls = provider.parallelToolCalls === false
+          ? false
+          : parsed.options.parallelToolCalls !== false;
+      }
       if (parsed.stream) {
         body.stream_options = { include_usage: true };
       }
@@ -235,8 +262,26 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
       const reader = response.body.getReader();
       const decoder = new TextDecoder();
       let buffer = "";
-      let currentToolCallId = "";
-      let currentToolCallName = "";
+      // Streamed tool calls are BUFFERED until a terminal signal, then flushed as atomic
+      // start/delta/end sequences. The bridge treats text/reasoning deltas as barriers that
+      // close an open tool-call item (bridge.ts closeCurrentToolCall on text_delta), so
+      // emitting calls incrementally would orphan later argument deltas whenever a provider
+      // interleaves content — and parallel tool calls (multiple ids, index-keyed continuation
+      // chunks, whole-chunk calls) cannot be represented live without overlapping sequences.
+      // Keyed by `index` (OpenAI wire standard), falling back to `id`, falling back to the
+      // last-seen call for providers that omit both on continuation chunks.
+      interface PendingToolCall { key: string; id: string; name: string; args: string }
+      const pendingToolCalls: PendingToolCall[] = [];
+      let toolCallSeq = 0;
+      const flushToolCalls = function* (): Generator<AdapterEvent> {
+        for (const call of pendingToolCalls) {
+          if (!call.id) call.id = `call_${++toolCallSeq}`;
+          yield { type: "tool_call_start", id: call.id, name: call.name };
+          if (call.args.length > 0) yield { type: "tool_call_delta", arguments: call.args };
+          yield { type: "tool_call_end" };
+        }
+        pendingToolCalls.length = 0;
+      };
       let pendingUsage: OcxUsage | undefined;
       // Track terminal signals so a socket EOF without any terminator can fail closed instead of
       // being reported as a clean completion (silent truncation). A graceful close is either an
@@ -252,10 +297,7 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
         if (!line.startsWith("data: ")) return "continue";
         const payload = line.slice(6).trim();
         if (payload === "[DONE]") {
-          if (currentToolCallId) {
-            yield { type: "tool_call_end" };
-            currentToolCallId = "";
-          }
+          yield* flushToolCalls();
           yield { type: "done", usage: pendingUsage };
           return "terminate";
         }
@@ -273,7 +315,7 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
         // classified response.failed (bridge case "error") — never a truncated completion.
         if (chunk.error) {
           const err = chunk.error as { message?: string } | undefined;
-          if (currentToolCallId) yield { type: "tool_call_end" };
+          yield* flushToolCalls();
           yield { type: "error", message: err?.message ?? "upstream error" };
           return "terminate";
         }
@@ -302,25 +344,34 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
             yield { type: "reasoning_raw_delta", text: delta.reasoning_content };
           }
 
-          const toolCalls = delta.tool_calls as { index: number; id?: string; function?: { name?: string; arguments?: string } }[] | undefined;
+          const toolCalls = delta.tool_calls as { index?: number; id?: string; function?: { name?: string; arguments?: string } }[] | undefined;
           if (toolCalls) {
             for (const tc of toolCalls) {
-              if (tc.id && tc.id !== currentToolCallId) {
-                if (currentToolCallId) yield { type: "tool_call_end" };
-                currentToolCallId = tc.id;
-                currentToolCallName = tc.function?.name ?? "";
-                yield { type: "tool_call_start", id: tc.id, name: currentToolCallName };
-              }
-              if (tc.function?.arguments) {
-                yield { type: "tool_call_delta", arguments: tc.function.arguments };
+              const key = typeof tc.index === "number"
+                ? `i:${tc.index}`
+                : tc.id
+                ? `id:${tc.id}`
+                : pendingToolCalls[pendingToolCalls.length - 1]?.key;
+              let call = key !== undefined ? pendingToolCalls.find(c => c.key === key) : undefined;
+              // Mixed keying rescue: a call opened under an index key must still absorb an
+              // id-only continuation for the same provider id (and vice versa) instead of
+              // splitting into two calls that share one call_id downstream.
+              if (!call && tc.id) call = pendingToolCalls.find(c => c.id === tc.id);
+              if (!call) {
+                call = { key: key ?? `seq:${pendingToolCalls.length}`, id: "", name: "", args: "" };
+                pendingToolCalls.push(call);
               }
+              if (tc.id && !call.id) call.id = tc.id;
+              if (tc.function?.name && !call.name) call.name = tc.function.name;
+              if (tc.function?.arguments) call.args += tc.function.arguments;
             }
           }
         }
 
-        if (choices[0].finish_reason === "tool_calls" && currentToolCallId) {
-          yield { type: "tool_call_end" };
-          currentToolCallId = "";
+        // Any non-empty finish_reason ends the generation: flush assembled tool calls as
+        // atomic sequences (covers "tool_calls" AND providers that close tool turns with "stop").
+        if (typeof choices[0].finish_reason === "string" && choices[0].finish_reason) {
+          yield* flushToolCalls();
         }
         return "continue";
       };
@@ -347,9 +398,7 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
         if (buffer.length > 0) {
           if ((yield* handleDataLine(buffer)) === "terminate") return;
         }
-        if (currentToolCallId) {
-          yield { type: "tool_call_end" };
-        }
+        yield* flushToolCalls();
         // Reader EOF. A graceful close shows at least one terminal signal: `[DONE]` (returns above),
         // a non-null finish_reason (sawFinish), or a trailing usage chunk (providers emit usage only
         // at end-of-generation). If NONE of those were seen, the stream was cut mid-flight — fail

package/src/bridge.ts

@@ -1,5 +1,5 @@
 import type { AdapterEvent, OcxUsage } from "./types";
-import { classifyError, type OcxErrorPayload } from "./lib/errors";
+import { adapterFailureFromMessage, classifyError, type OcxErrorPayload } from "./lib/errors";
 import { encodeCompactionSummary } from "./responses/compaction";
 import { encodeReasoningEnvelope, type ReasoningEnvelope } from "./responses/reasoning-envelope";
 import { usageDisplayTotalTokens, usageInputTokensWithCacheDetail } from "./usage/totals";
@@ -40,6 +40,8 @@ function responseError(status: number, type: string, message: string): OcxErrorP
   return classifyError(status, type, message);
 }
 
+export { adapterFailureFromMessage } from "./lib/errors";
+
 /**
  * Build the native `WebSearchAction::Search` payload from the queries that ran. codex-rs prefers a
  * non-empty `query` over `queries` for the cell label, and only renders "<first> ..." when `query`
@@ -184,6 +186,7 @@ export function bridgeToResponsesSSE(
           if (currentMsg) closeCurrentMessage();
           if (currentReasoning) closeCurrentReasoning();
           if (currentRawReasoning) closeCurrentRawReasoning();
+          flushHiddenRawReasoning();
           if (currentToolCall) closeCurrentToolCall();
           if (currentWebSearch) closeCurrentWebSearch("failed", []);
           emit("response.incomplete", {
@@ -236,6 +239,23 @@ export function bridgeToResponsesSSE(
         finishedItems.push(item as OutputItem);
         outputIndex++;
       };
+      // hideThinkingSummary for RAW reasoning (openai-chat reasoning_content, kiro tags): no
+      // visible reasoning item is emitted — the app renders nothing, so tool cells keep grouping
+      // like native models — but the text still round-trips in a txt-only ocxr1 envelope so
+      // preserveReasoningContentModels replay (GLM interleaved thinking) keeps working. Direct
+      // encodeReasoningEnvelope: takeReasoningEnvelope's sig/red guard would drop txt-only.
+      let hiddenRawReasoningText = "";
+      const flushHiddenRawReasoning = () => {
+        if (!hiddenRawReasoningText) return;
+        const encrypted = encodeReasoningEnvelope({ txt: hiddenRawReasoningText });
+        hiddenRawReasoningText = "";
+        const itemId = `rs_${uuid()}`;
+        const item = { type: "reasoning", id: itemId, summary: [] as never[], encrypted_content: encrypted };
+        emit("response.output_item.added", { output_index: outputIndex, item });
+        emit("response.output_item.done", { output_index: outputIndex, item });
+        finishedItems.push(item as OutputItem);
+        outputIndex++;
+      };
       // Full assistant text of a compaction turn (across message boundaries) — becomes the
       // synthetic compaction item's payload on done.
       let compactionText = "";
@@ -392,6 +412,7 @@ export function bridgeToResponsesSSE(
             case "text_delta": {
               if (currentReasoning) closeCurrentReasoning();
               if (currentRawReasoning) closeCurrentRawReasoning();
+              flushHiddenRawReasoning();
               if (currentToolCall) closeCurrentToolCall();
               if (!currentMsg) {
                 const itemId = `msg_${uuid()}`;
@@ -417,6 +438,7 @@ export function bridgeToResponsesSSE(
               if (options?.hideThinkingSummary) { hiddenThinkingText += event.thinking; break; }
               if (currentMsg) closeCurrentMessage();
               if (currentRawReasoning) closeCurrentRawReasoning();
+              flushHiddenRawReasoning();
               if (currentToolCall) closeCurrentToolCall();
               if (!currentReasoning) {
                 const itemId = `rs_${uuid()}`;
@@ -448,6 +470,7 @@ export function bridgeToResponsesSSE(
               break;
             }
             case "reasoning_raw_delta": {
+              if (options?.hideThinkingSummary) { hiddenRawReasoningText += event.text; break; }
               if (currentMsg) closeCurrentMessage();
               if (currentReasoning) closeCurrentReasoning();
               if (currentToolCall) closeCurrentToolCall();
@@ -468,6 +491,7 @@ export function bridgeToResponsesSSE(
               if (currentMsg) closeCurrentMessage();
               if (currentReasoning) closeCurrentReasoning();
               if (currentRawReasoning) closeCurrentRawReasoning();
+              flushHiddenRawReasoning();
               if (currentToolCall) closeCurrentToolCall();
               const itemId = `fc_${uuid()}`;
               const mapped = toolNsMap?.get(event.name);
@@ -522,6 +546,7 @@ export function bridgeToResponsesSSE(
               if (currentMsg) closeCurrentMessage();
               if (currentReasoning) closeCurrentReasoning();
               if (currentRawReasoning) closeCurrentRawReasoning();
+              flushHiddenRawReasoning();
               if (currentToolCall) closeCurrentToolCall();
               if (currentWebSearch) closeCurrentWebSearch("completed", []);
               emit("response.output_item.added", {
@@ -556,6 +581,7 @@ export function bridgeToResponsesSSE(
               if (currentMsg) closeCurrentMessage();
               if (currentReasoning) closeCurrentReasoning();
               if (currentRawReasoning) closeCurrentRawReasoning();
+              flushHiddenRawReasoning();
               if (currentToolCall) closeCurrentToolCall();
               if (currentWebSearch) closeCurrentWebSearch("completed", []);
               // Redacted-only turns (or hidden thinking without a trailing signature event) still
@@ -584,16 +610,18 @@ export function bridgeToResponsesSSE(
               if (currentMsg) closeCurrentMessage();
               if (currentReasoning) closeCurrentReasoning();
               if (currentRawReasoning) closeCurrentRawReasoning();
+              flushHiddenRawReasoning();
               if (currentToolCall) closeCurrentToolCall();
               if (currentWebSearch) closeCurrentWebSearch("failed", []);
+              const failure = adapterFailureFromMessage(event.message);
               emit("response.failed", {
                 response: {
                   ...responseSnapshot("failed", finishedItems),
                   // Partial consumption from a mid-stream upstream failure: surfaced so the request
                   // log can record real tokens instead of usageStatus "unreported" with 0.
                   ...(event.usage ? { usage: responsesUsage(event.usage) } : {}),
-                  error: responseError(502, "upstream_error", event.message),
-                  last_error: responseError(502, "upstream_error", event.message),
+                  error: failure.error,
+                  last_error: failure.error,
                 },
               });
               reportTerminal("failed");
@@ -603,6 +631,7 @@ export function bridgeToResponsesSSE(
           }
         }
       } catch (err) {
+        flushHiddenRawReasoning();
         if (currentWebSearch) closeCurrentWebSearch("failed", []);
         emit("response.failed", {
           response: {
@@ -623,6 +652,7 @@ export function bridgeToResponsesSSE(
         if (currentMsg) closeCurrentMessage();
         if (currentReasoning) closeCurrentReasoning();
         if (currentRawReasoning) closeCurrentRawReasoning();
+        flushHiddenRawReasoning();
         if (currentToolCall) closeCurrentToolCall();
         if (currentWebSearch) closeCurrentWebSearch("failed", []);
         emit("response.incomplete", {
@@ -723,6 +753,15 @@ export function buildResponseJSON(
   };
   const flushRawReasoning = () => {
     if (!currentRawReasoning) return;
+    if (options?.hideThinkingSummary === true) {
+      // Same contract as the streaming path: no visible reasoning, txt-only envelope round-trip.
+      output.push({
+        type: "reasoning", id: `rs_${uuid()}`, summary: [],
+        encrypted_content: encodeReasoningEnvelope({ txt: currentRawReasoning }),
+      });
+      currentRawReasoning = "";
+      return;
+    }
     output.push({
       type: "reasoning", id: `rs_${uuid()}`, summary: [],
       content: [{ type: "reasoning_text", text: currentRawReasoning }],

package/src/cli/debug.ts

@@ -0,0 +1,203 @@
+import { findLiveProxy, probeHostname } from "../server/proxy-liveness";
+import { DEBUG_ENV, type DebugSettingsView } from "../lib/debug-settings";
+import { runningProxyUpdateHeaders } from "../oauth/login-cli";
+
+type DebugScope = "provider" | "usage";
+
+async function requireLiveProxy() {
+  const live = await findLiveProxy();
+  if (!live) {
+    console.error("Proxy is not running. Start it with: ocx start");
+    process.exit(1);
+  }
+  return live;
+}
+
+async function fetchDebugSettings(): Promise<DebugSettingsView> {
+  const live = await requireLiveProxy();
+  try {
+    const res = await fetch(`http://${probeHostname(live.hostname)}:${live.port}/api/debug`, {
+      headers: runningProxyUpdateHeaders(),
+    });
+    if (!res.ok) {
+      console.error(`Failed to read debug settings (${res.status})`);
+      process.exit(1);
+    }
+    return await res.json() as DebugSettingsView;
+  } catch (err) {
+    console.error(`Proxy is running but /api/debug is unreachable: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+
+async function putDebugSettings(body: Record<string, unknown>): Promise<DebugSettingsView> {
+  const live = await requireLiveProxy();
+  const res = await fetch(`http://${probeHostname(live.hostname)}:${live.port}/api/debug`, {
+    method: "PUT",
+    headers: runningProxyUpdateHeaders(),
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    console.error(`Failed to update debug settings (${res.status})${text ? `: ${text.slice(0, 200)}` : ""}`);
+    process.exit(1);
+  }
+  return await res.json() as DebugSettingsView;
+}
+
+function printScopeStatus(scope: DebugScope, view: DebugSettingsView): void {
+  if (scope === "provider") {
+    console.log(`Provider debug: ${view.enabled ? "ON" : "off"}`);
+    console.log(`  env=${view.env.debug ? "on" : "off"}, runtime=${view.runtimeOverride.debug === undefined ? "env/default" : view.runtimeOverride.debug ? "on" : "off"}`);
+    console.log("  Tail: ocx debug provider logs [-f]");
+  } else {
+    console.log(`Usage debug: ${view.usage ? "ON" : "off"}`);
+    console.log(`  env=${view.env.usage ? "on" : "off"}, runtime=${view.runtimeOverride.usage === undefined ? "env/default" : view.runtimeOverride.usage ? "on" : "off"}`);
+    console.log("  Tail: ocx debug usage logs [-f] (via running proxy API)");
+  }
+}
+
+function envDebugEnabled(): boolean {
+  return process.env.OCX_DEBUG === "1"
+    || process.env.OCX_DEBUG_FRAMES === "1";
+}
+
+async function printProviderLogs(follow: boolean): Promise<void> {
+  const live = await requireLiveProxy();
+  const base = `http://${probeHostname(live.hostname)}:${live.port}/api/debug/logs`;
+
+  let after = 0;
+  try {
+    const res = await fetch(`${base}?limit=500`, { headers: runningProxyUpdateHeaders() });
+    if (!res.ok) {
+      console.error(`Failed to read debug logs (${res.status})`);
+      process.exit(1);
+    }
+    const entries = await res.json() as { seq: number; line: string }[];
+    for (const entry of entries) console.log(entry.line);
+    if (entries.length > 0) after = entries[entries.length - 1]!.seq;
+  } catch (err) {
+    console.error(`Failed to read debug logs: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+
+  if (!follow) return;
+
+  while (true) {
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    try {
+      const res = await fetch(`${base}?after=${after}&limit=500`, { headers: runningProxyUpdateHeaders() });
+      if (!res.ok) continue;
+      const entries = await res.json() as { seq: number; line: string }[];
+      for (const entry of entries) console.log(entry.line);
+      if (entries.length > 0) after = entries[entries.length - 1]!.seq;
+    } catch {
+      /* keep following */
+    }
+  }
+}
+
+async function printUsageLogs(follow: boolean): Promise<void> {
+  const live = await requireLiveProxy();
+  const base = `http://${probeHostname(live.hostname)}:${live.port}/api/debug/usage-logs`;
+
+  let after = 0;
+  try {
+    const res = await fetch(`${base}?limit=500`, { headers: runningProxyUpdateHeaders() });
+    if (!res.ok) {
+      console.error(`Failed to read usage debug logs (${res.status})`);
+      process.exit(1);
+    }
+    const entries = await res.json() as { seq: number; line: string }[];
+    for (const entry of entries) console.log(entry.line);
+    if (entries.length === 0) console.log("(empty — enable with: ocx debug usage on)");
+    if (entries.length > 0) after = entries[entries.length - 1]!.seq;
+  } catch (err) {
+    console.error(`Failed to read usage debug logs: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+
+  if (!follow) return;
+
+  while (true) {
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    try {
+      const res = await fetch(`${base}?after=${after}&limit=500`, { headers: runningProxyUpdateHeaders() });
+      if (!res.ok) continue;
+      const entries = await res.json() as { seq: number; line: string }[];
+      for (const entry of entries) console.log(entry.line);
+      if (entries.length > 0) after = entries[entries.length - 1]!.seq;
+    } catch {
+      /* keep following */
+    }
+  }
+}
+
+async function handleScopeCommand(scope: DebugScope, actionArgv: string[]): Promise<void> {
+  const action = (actionArgv[0] ?? "status").trim().toLowerCase();
+
+  if (action === "on" || action === "off") {
+    const enabled = action === "on";
+    const body = scope === "provider" ? { debug: enabled } : { usage: enabled };
+    printScopeStatus(scope, await putDebugSettings(body));
+    console.log(`\n${scope} debug is now ${enabled ? "enabled" : "disabled"}.`);
+    return;
+  }
+
+  if (action === "status") {
+    printScopeStatus(scope, await fetchDebugSettings());
+    return;
+  }
+
+  if (action === "reset") {
+    const resetKey = scope === "provider" ? "provider" : "usage";
+    printScopeStatus(scope, await putDebugSettings({ reset: resetKey }));
+    console.log(`\nRuntime override cleared for ${scope}; effective value follows env again.`);
+    return;
+  }
+
+  if (action === "logs") {
+    const follow = actionArgv.slice(1).some(arg => arg === "-f" || arg === "--follow");
+    if (scope === "provider") await printProviderLogs(follow);
+    else await printUsageLogs(follow);
+    return;
+  }
+
+  console.error(`Usage: ocx debug ${scope} on|off|status|reset|logs [-f]`);
+  process.exit(1);
+}
+
+function printTopLevelHelp(): void {
+  console.log("Debug commands (proxy must be running):");
+  console.log("");
+  console.log("  ocx debug provider on|off|status|reset|logs [-f]");
+  console.log("  ocx debug usage on|off|status|reset|logs [-f]");
+  console.log("");
+  console.log("Env defaults on start:");
+  console.log("  provider → OCX_DEBUG=1 (legacy OCX_DEBUG_FRAMES still works)");
+  console.log(`  usage    → ${DEBUG_ENV.usage}=1`);
+}
+
+export async function handleDebugCommand(argv: string[]): Promise<void> {
+  const sub = (argv[0] ?? "").trim().toLowerCase();
+
+  if (sub === "provider" || sub === "usage") {
+    await handleScopeCommand(sub, argv.slice(1));
+    return;
+  }
+
+  if (sub === "" || sub === "help" || sub === "--help" || sub === "-h") {
+    const live = await findLiveProxy();
+    if (!live) {
+      console.log("Proxy is not running — env defaults for the next start:");
+      console.log(`  provider → OCX_DEBUG = ${envDebugEnabled() ? "on" : "off"}`);
+      console.log(`  usage    → ${DEBUG_ENV.usage} = ${process.env[DEBUG_ENV.usage] === "1" ? "on" : "off"}`);
+      console.log("");
+    }
+    printTopLevelHelp();
+    return;
+  }
+
+  printTopLevelHelp();
+  process.exit(1);
+}