@iislee/opencodex 2.11.0 → 2.35.0

package/src/cli/system-restart-client.ts

@@ -0,0 +1,146 @@
+import { readRuntimePort } from "../config/process-state";
+import {
+  LOCAL_ATTESTATION_CHALLENGE_HEADER,
+  LOCAL_ATTESTATION_PROOF_HEADER,
+  createLocalAttestationChallenge,
+  verifyLocalAttestationProof,
+} from "../lib/local-management-attestation";
+import {
+  SYSTEM_RESTART_CAPABILITY_HEADER,
+  SYSTEM_RESTART_CAPABILITY_VERSION,
+  SYSTEM_RESTART_EXPECTED_PID_HEADER,
+  SYSTEM_RESTART_METHOD,
+  SYSTEM_RESTART_NONCE_HEADER,
+  SYSTEM_RESTART_PATH,
+  createSystemRestartCapability,
+} from "../lib/system-restart-contract";
+import {
+  findLiveProxy,
+  isOpencodexHealthz,
+  probeHostname,
+  type HealthzIdentity,
+  type LiveProxy,
+} from "../server/proxy-liveness";
+import type { ProxyRestartRequestOutcome } from "./tray-proxy";
+
+export const SYSTEM_RESTART_REQUEST_TIMEOUT_MS = 5_000;
+export const SYSTEM_RESTART_ATTESTATION_TIMEOUT_MS = 4_000;
+
+export interface BoundSystemRestartDeps {
+  fetchImpl?: typeof fetch;
+  readRuntime?: typeof readRuntimePort;
+  findLive?: typeof findLiveProxy;
+  createChallenge?: () => string;
+  now?: () => number;
+}
+
+function rejected(code: string): ProxyRestartRequestOutcome {
+  return { accepted: false, uncertain: false, error: new Error(code) };
+}
+
+function uncertain(code: string): ProxyRestartRequestOutcome {
+  return { accepted: false, uncertain: true, error: new Error(code) };
+}
+
+function remaining(deadlineAt: number, now: () => number, cap: number): number {
+  return Math.max(0, Math.min(cap, deadlineAt - now()));
+}
+
+function sameRestartTarget(expected: LiveProxy, observed: LiveProxy | null): boolean {
+  return expected.pid !== null
+    && observed?.source === "runtime"
+    && observed.pid === expected.pid
+    && observed.port === expected.port;
+}
+
+/**
+ * Send one restart request to the exact runtime proxy observed by the caller.
+ *
+ * No reusable admin credential is sent. After the listener proves possession of
+ * its per-process runtime secret, the client derives a capability bound to this
+ * method, path, PID, and port. The expected PID is repeated so a replacement that
+ * wins the port between proof and POST rejects the request.
+ */
+export async function requestBoundSystemRestart(
+  target: LiveProxy,
+  deadlineAt: number,
+  deps: BoundSystemRestartDeps = {},
+): Promise<ProxyRestartRequestOutcome> {
+  if (target.source !== "runtime" || target.pid === null) return rejected("restart_target_unattested");
+
+  const now = deps.now ?? Date.now;
+  const readRuntime = deps.readRuntime ?? readRuntimePort;
+  const runtime = readRuntime(target.pid);
+  if (!runtime?.attestationSecret || runtime.pid !== target.pid || runtime.port !== target.port) {
+    return rejected("restart_target_runtime_mismatch");
+  }
+
+  const attestationBudget = remaining(deadlineAt, now, SYSTEM_RESTART_ATTESTATION_TIMEOUT_MS);
+  if (attestationBudget <= 0) return rejected("restart_deadline_expired");
+
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const challenge = (deps.createChallenge ?? createLocalAttestationChallenge)();
+  const baseUrl = `http://${probeHostname(target.hostname)}:${target.port}`;
+  let proofResponse: Response;
+  try {
+    proofResponse = await fetchImpl(`${baseUrl}/healthz`, {
+      headers: { [LOCAL_ATTESTATION_CHALLENGE_HEADER]: challenge },
+      signal: AbortSignal.timeout(attestationBudget),
+    });
+  } catch {
+    return rejected("restart_attestation_unreachable");
+  }
+  const body = await proofResponse.json().catch(() => null) as HealthzIdentity | null;
+  const proof = proofResponse.headers.get(LOCAL_ATTESTATION_PROOF_HEADER);
+  if (
+    !proofResponse.ok
+    || !isOpencodexHealthz(body)
+    || body?.pid !== target.pid
+    || !verifyLocalAttestationProof(runtime.attestationSecret, challenge, target.pid, target.port, proof)
+  ) {
+    return rejected("restart_attestation_failed");
+  }
+  if (body.restartCapability !== SYSTEM_RESTART_CAPABILITY_VERSION) {
+    // A pre-update proxy accepts only the reusable management credential and cannot
+    // bind the operation to the attested PID. Refuse before POST rather than weakening
+    // the exact-process contract or replaying a stop/start transaction.
+    return rejected("restart_capability_unsupported");
+  }
+
+  let observed: LiveProxy | null;
+  try {
+    observed = await (deps.findLive ?? findLiveProxy)({ deadlineAt, nowFn: now });
+  } catch {
+    return rejected("restart_target_recheck_failed");
+  }
+  if (!sameRestartTarget(target, observed)) return rejected("restart_target_changed");
+
+  const capability = createSystemRestartCapability(
+    runtime.attestationSecret,
+    challenge,
+    SYSTEM_RESTART_METHOD,
+    SYSTEM_RESTART_PATH,
+    target.pid,
+    target.port,
+  );
+  if (!capability) return rejected("restart_capability_unavailable");
+
+  const requestBudget = remaining(deadlineAt, now, SYSTEM_RESTART_REQUEST_TIMEOUT_MS);
+  if (requestBudget <= 0) return rejected("restart_deadline_expired");
+  try {
+    const response = await fetchImpl(`${baseUrl}${SYSTEM_RESTART_PATH}`, {
+      method: SYSTEM_RESTART_METHOD,
+      headers: {
+        [SYSTEM_RESTART_EXPECTED_PID_HEADER]: String(target.pid),
+        [SYSTEM_RESTART_NONCE_HEADER]: challenge,
+        [SYSTEM_RESTART_CAPABILITY_HEADER]: capability,
+      },
+      signal: AbortSignal.timeout(requestBudget),
+    });
+    return response.ok ? { accepted: true } : rejected(`restart_request_http_${response.status}`);
+  } catch {
+    // The server may have accepted the restart before the response connection failed.
+    // The coordinator observes the original PID for replacement instead of replaying.
+    return uncertain("restart_request_outcome_unknown");
+  }
+}

package/src/cli/tray-proxy.ts

@@ -8,6 +8,8 @@ export interface TrayProxyServiceState {
 
 export interface TrayProxyStartIo {
   findLive: () => Promise<TrayProxyLive | null>;
+  /** Normal Start is idempotent; restart fallback refuses a target that reappeared. */
+  existingIsSuccess?: boolean;
   diagnoseService: () => TrayProxyServiceState;
   startService: () => void | Promise<void>;
   startDirect: () => void | Promise<void>;
@@ -16,10 +18,101 @@ export interface TrayProxyStartIo {
   error: (message: string) => void;
 }
 
+export interface ProxyRestartLive {
+  pid: number | null;
+  port: number;
+  hostname?: string;
+  source: "runtime" | "config";
+}
+
+export type ProxyRestartRequestOutcome =
+  | { accepted: true }
+  | { accepted: false; uncertain: boolean; error?: unknown };
+
+export type ProxyRestartResult =
+  | { ok: true; mode: "started" }
+  | { ok: true; mode: "skipped" }
+  | { ok: true; mode: "restarted"; live: ProxyRestartLive }
+  | { ok: false; phase: "start" | "identity" | "request" | "replacement"; error?: unknown };
+
+export type ProxyRestartDiscovery =
+  | { status: "live"; live: ProxyRestartLive }
+  | { status: "absent" }
+  | { status: "uncertain"; error?: unknown };
+
+export interface ProxyRestartDiscoveryIo {
+  findLive: () => Promise<ProxyRestartLive | null>;
+  waitBetweenChecks?: () => Promise<void>;
+  expired?: () => boolean;
+}
+
+export interface ProxyRestartIo {
+  findLive: () => Promise<ProxyRestartDiscovery>;
+  startWhenStopped: () => boolean | "skipped" | Promise<boolean | "skipped">;
+  requestInPlaceRestart: (
+    previous: ProxyRestartLive,
+  ) => ProxyRestartRequestOutcome | Promise<ProxyRestartRequestOutcome>;
+  waitForReplacement: (previous: ProxyRestartLive) => Promise<ProxyRestartLive | null>;
+}
+
+/**
+ * Confirm absence twice before restart is allowed to select a start-only path.
+ * A live target appearing during confirmation is uncertainty, not success: the
+ * caller must not claim it restarted a process it never asked to restart.
+ */
+export async function discoverStableProxyForRestart(
+  io: ProxyRestartDiscoveryIo,
+): Promise<ProxyRestartDiscovery> {
+  let first: ProxyRestartLive | null;
+  try {
+    first = await io.findLive();
+  } catch (error) {
+    return { status: "uncertain", error };
+  }
+  if (first) return { status: "live", live: first };
+  if (io.expired?.()) {
+    return { status: "uncertain", error: new Error("restart_discovery_deadline_expired") };
+  }
+
+  await (io.waitBetweenChecks ?? (() => Bun.sleep(100)))();
+  let second: ProxyRestartLive | null;
+  try {
+    second = await io.findLive();
+  } catch (error) {
+    return { status: "uncertain", error };
+  }
+  if (second) {
+    return {
+      status: "uncertain",
+      error: new Error("restart_target_appeared_during_absence_confirmation"),
+    };
+  }
+  if (io.expired?.()) {
+    return { status: "uncertain", error: new Error("restart_discovery_deadline_expired") };
+  }
+  return { status: "absent" };
+}
+
+export function isProxyReplacement(
+  previous: ProxyRestartLive,
+  candidate: ProxyRestartLive | null,
+): candidate is ProxyRestartLive & { pid: number } {
+  return previous.pid !== null
+    && candidate?.pid !== null
+    && candidate?.pid !== undefined
+    && candidate.source === "runtime"
+    && candidate.port === previous.port
+    && candidate.pid !== previous.pid;
+}
+
 /** Side-effect coordinator for the tray's fixed proxy-start action. */
 export async function runTrayProxyStart(io: TrayProxyStartIo): Promise<boolean> {
   const live = await io.findLive();
   if (live) {
+    if (io.existingIsSuccess === false) {
+      io.error("Proxy appeared while restart was confirming absence; no start was attempted.");
+      return false;
+    }
     io.info(`Proxy already running on port ${live.port}.`);
     return true;
   }
@@ -43,10 +136,64 @@ export async function runTrayProxyStart(io: TrayProxyStartIo): Promise<boolean>
   return true;
 }
 
-export async function runTrayProxyRestart(io: {
-  stop: () => boolean | Promise<boolean>;
-  start: () => boolean | Promise<boolean>;
-}): Promise<boolean> {
-  if (!await io.stop()) return false;
-  return io.start();
+/**
+ * Shared restart transaction for both `ocx restart` and the Windows tray.
+ *
+ * A live proxy restarts itself through POST /api/system/restart. That lifecycle owns
+ * drain, supervisor handoff, exact replacement identity, and managed-routing
+ * preservation. Re-implementing restart as `stop` + `start` here races a late service
+ * child and lets ordinary /api/stop restore native routing between the two halves.
+ * When no proxy is live there is nothing to recycle, so restart degrades to the
+ * caller's normal start path.
+ */
+export async function runProxyRestart(io: ProxyRestartIo): Promise<ProxyRestartResult> {
+  let discovery: ProxyRestartDiscovery;
+  try {
+    discovery = await io.findLive();
+  } catch (error) {
+    return { ok: false, phase: "request", error };
+  }
+
+  if (discovery.status === "uncertain") {
+    return { ok: false, phase: "request", error: discovery.error };
+  }
+
+  if (discovery.status === "absent") {
+    try {
+      const started = await io.startWhenStopped();
+      if (started === "skipped") return { ok: true, mode: "skipped" };
+      return started ? { ok: true, mode: "started" } : { ok: false, phase: "start" };
+    } catch (error) {
+      return { ok: false, phase: "start", error };
+    }
+  }
+
+  const previous = discovery.live;
+
+  if (previous.pid === null || previous.source !== "runtime") {
+    return { ok: false, phase: "identity" };
+  }
+
+  let request: ProxyRestartRequestOutcome;
+  try {
+    request = await io.requestInPlaceRestart(previous);
+  } catch (error) {
+    // The request may have reached the proxy before the response connection failed.
+    // Keep observing the original identity; never replay or fall back to stop/start.
+    request = { accepted: false, uncertain: true, error };
+  }
+
+  if (!request.accepted && !request.uncertain) {
+    return { ok: false, phase: "request", error: request.error };
+  }
+
+  try {
+    const replacement = await io.waitForReplacement(previous);
+    if (replacement) return { ok: true, mode: "restarted", live: replacement };
+    return request.accepted
+      ? { ok: false, phase: "replacement" }
+      : { ok: false, phase: "request", error: request.error };
+  } catch (error) {
+    return { ok: false, phase: "replacement", error };
+  }
 }

package/src/cli/usage-report.ts

@@ -0,0 +1,184 @@
+/**
+ * Human rendering for `ocx usage`.
+ *
+ * Kept out of `observe.ts` and away from the shared `summaryLines()` helper on
+ * purpose. `summaryLines()` is a generic depth-1 flattener shared with
+ * storage/memory/debug/claude-inbound/injection; it renders any array as
+ * "N item(s)", which is why every per-model and per-provider cost the server
+ * computes used to vanish before reaching the terminal. Deepening it would
+ * change five unrelated commands.
+ *
+ * Formatting follows the existing CLI house style: dynamic `padEnd` columns
+ * (as in `formatAccountTable`), plain text, no ANSI colour.
+ */
+
+interface CostRow {
+  provider: string;
+  model?: string;
+  requests: number;
+  totalTokens: number;
+  estimatedCostUsd?: number;
+}
+
+interface UsageReportInput {
+  range?: string;
+  surface?: string;
+  since?: number | null;
+  summary?: {
+    requests?: number;
+    totalTokens?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedInputTokens?: number;
+    estimatedCostUsd?: number;
+    unpricedRequests?: number;
+    unmeteredRequests?: number;
+  };
+  models?: CostRow[];
+  providers?: CostRow[];
+  days?: { date: string; requests: number; totalTokens: number; estimatedCostUsd?: number }[];
+  filter?: { provider: string | null; model: string | null; matched: boolean; comboOverlap: boolean };
+  /**
+   * Per-account totals the API already returns and the CLI discarded (#2700).
+   *
+   * Withheld by the server -- sent as `[]` -- whenever a provider or model filter is active,
+   * because account rows are not provider-partitioned in a way the projection could honestly
+   * re-derive (summary.ts, reasoned around :865-872). An empty array therefore means two very
+   * different things, and the renderer must say which.
+   */
+  accounts?: {
+    accountLogLabel: string;
+    ambiguous?: boolean;
+    requests: number;
+    totalTokens: number;
+    estimatedCostUsd?: number;
+  }[];
+}
+
+const MAX_MODEL_ROWS = 10;
+
+function terminalText(value: string): string {
+  return value.replace(/[\x00-\x1f\x7f-\x9f]/g, character => {
+    const code = character.charCodeAt(0);
+    return code <= 0x7f
+      ? `\\x${code.toString(16).padStart(2, "0")}`
+      : `\\u${code.toString(16).padStart(4, "0")}`;
+  });
+}
+
+function count(value: number | undefined): string {
+  return (value ?? 0).toLocaleString("en-US");
+}
+
+/**
+ * Matches the dashboard's `~$` with four fraction digits. Estimates below a
+ * hundredth of a cent still read as a number rather than collapsing to $0.00,
+ * which matters when a single request is being inspected.
+ */
+function usd(value: number | undefined): string {
+  if (typeof value !== "number" || !Number.isFinite(value)) return "—";
+  return `~$${value.toFixed(4)}`;
+}
+
+function table(header: string[], rows: string[][]): string[] {
+  if (rows.length === 0) return [];
+  header = header.map(terminalText);
+  rows = rows.map(row => row.map(terminalText));
+  const widths = header.map((h, i) => Math.max(h.length, ...rows.map(r => (r[i] ?? "").length)));
+  const line = (cols: string[]): string => cols.map((c, i) => (c ?? "").padEnd(widths[i]!)).join("  ").trimEnd();
+  return [line(header), ...rows.map(line)];
+}
+
+function describeScope(data: UsageReportInput): string {
+  const parts = [`Usage — ${data.range ?? "?"}`];
+  if (data.surface && data.surface !== "all") parts.push(`surface=${data.surface}`);
+  if (data.filter?.provider) parts.push(`provider=${data.filter.provider}`);
+  if (data.filter?.model) parts.push(`model=${data.filter.model}`);
+  return terminalText(parts.join(", "));
+}
+
+export function formatUsageReport(data: UsageReportInput): string[] {
+  const summary = data.summary ?? {};
+  const lines: string[] = [describeScope(data), ""];
+
+  if (data.filter && !data.filter.matched) {
+    const what = [data.filter.provider && `provider "${data.filter.provider}"`, data.filter.model && `model "${data.filter.model}"`]
+      .filter(Boolean).join(" and ");
+    lines.push(`No usage recorded for ${terminalText(what)} in this range.`);
+    lines.push("Check the spelling against `ocx usage --json`, or widen --range.");
+    return lines;
+  }
+
+  const tokenSplit = [
+    summary.inputTokens !== undefined ? `in ${count(summary.inputTokens)}` : null,
+    summary.outputTokens !== undefined ? `out ${count(summary.outputTokens)}` : null,
+    summary.cachedInputTokens ? `cached ${count(summary.cachedInputTokens)}` : null,
+  ].filter(Boolean).join(" / ");
+
+  lines.push(`Requests   ${count(summary.requests)}`);
+  lines.push(`Tokens     ${count(summary.totalTokens)}${tokenSplit ? `  (${tokenSplit})` : ""}`);
+  lines.push(`Est. cost  ${usd(summary.estimatedCostUsd)}    API list-price equivalent (this range)`);
+
+  const unpriced = summary.unpricedRequests ?? 0;
+  const unmetered = summary.unmeteredRequests ?? 0;
+  if (unpriced > 0 || unmetered > 0) {
+    // Spelled out because a $0 total is ambiguous otherwise: it can mean "no
+    // spend" or "no price row matched", and those are very different answers.
+    lines.push(`           ${count(unpriced)} unpriced, ${count(unmetered)} unmetered excluded from ~$`);
+  }
+
+  const providers = (data.providers ?? []).filter(row => row.requests > 0);
+  if (providers.length > 0) {
+    lines.push("");
+    lines.push(...table(
+      ["PROVIDER", "REQUESTS", "TOKENS", "EST. COST"],
+      providers.map(row => [row.provider, count(row.requests), count(row.totalTokens), usd(row.estimatedCostUsd)]),
+    ));
+  }
+
+  // Per-account spend (#2700). The two empty cases are distinguished deliberately: printing an
+  // empty table under a filter would repeat the silently-wrong-output defect this unit removes,
+  // because "what did this provider cost me per account" is the most natural way to ask and the
+  // server cannot answer it honestly.
+  const accountFilterActive = Boolean(data.filter?.provider || data.filter?.model);
+  const accounts = (data.accounts ?? []).filter(row => row.requests > 0);
+  if (accountFilterActive) {
+    lines.push("");
+    lines.push("ACCOUNT: not reported under a provider or model filter; run without filters for per-account totals.");
+  } else if (accounts.length > 0) {
+    lines.push("");
+    lines.push(...table(
+      ["ACCOUNT", "REQUESTS", "TOKENS", "EST. COST"],
+      accounts.map(row => [
+        // An ambiguous row aggregates several accounts, so reading it as one account draws the
+        // wrong conclusion. Mark it rather than presenting it as a single identity.
+        row.ambiguous ? `${terminalText(row.accountLogLabel)} (ambiguous)` : terminalText(row.accountLogLabel),
+        count(row.requests),
+        count(row.totalTokens),
+        usd(row.estimatedCostUsd),
+      ]),
+    ));
+  }
+
+  const models = (data.models ?? []).filter(row => row.requests > 0);
+  if (models.length > 0) {
+    lines.push("");
+    const shown = models.slice(0, MAX_MODEL_ROWS);
+    lines.push(...table(
+      ["MODEL", "PROVIDER", "REQUESTS", "TOKENS", "EST. COST"],
+      shown.map(row => [row.model ?? "-", row.provider, count(row.requests), count(row.totalTokens), usd(row.estimatedCostUsd)]),
+    ));
+    if (models.length > shown.length) {
+      lines.push(`... ${models.length - shown.length} more (use --json)`);
+    }
+  }
+
+  if (data.filter?.comboOverlap) {
+    lines.push("");
+    lines.push("Some requests ran as combos, so per-model request counts can overlap. Cost does not.");
+  }
+
+  lines.push("");
+  lines.push("Not a billing receipt. Subscription usage or provider credits may apply instead.");
+  return lines;
+}