@bitkyc08/opencodex 2.83.0 → 2.84.0

package/src/link/management-routes.ts

@@ -0,0 +1,89 @@
+/**
+ * The read-only management surface a Remote Link Child may reach on its Home (#6957).
+ *
+ * Default deny: a path is readable only when it is listed here, the method is GET or HEAD, and
+ * the query does not ask the Home to refresh upstream state. Everything else is refused on both
+ * ends: the Child's listener and CLI refuse before sending, and the Home's link listener answers
+ * 404 for any other path under the prefix. No route here returns a credential value; provider
+ * and account projections report presence and masked identities only.
+ *
+ * A link read must not change the Home. The Home runs these reads passively
+ * (`src/lib/passive-read.ts`): model discovery, which reaches provider upstreams and persists the
+ * initial model selection of a pending provider, config writes and diagnostics do not run (#6959).
+ * `tests/server/link-management-relay.test.ts` reads every path here and asserts that the Home
+ * config and its upstreams are untouched.
+ */
+export const LINK_MANAGEMENT_PREFIX = "/v1/link-management";
+/** The Home's OpenCodex-owned Codex settings a Child applies when it syncs. */
+export const LINK_CODEX_SETTINGS_PATH = `${LINK_MANAGEMENT_PREFIX}/codex-settings`;
+
+export const LINK_MANAGEMENT_READ_PATHS: readonly string[] = [
+  "/api/system/health",
+  "/api/startup-health",
+  "/api/providers",
+  "/api/settings",
+  "/api/usage",
+  "/api/effort-caps",
+  "/api/injection-model",
+  "/api/shadow-call-settings",
+  "/api/sidecar-settings",
+  "/api/v2",
+  "/api/provider-quotas",
+  "/api/codex-auth/active",
+  "/api/codex-auth/accounts",
+  "/api/oauth/accounts",
+  "/api/providers/keys",
+  "/api/oauth/providers",
+  "/api/catalog",
+  "/api/system/memory",
+  "/api/provider-presets",
+  "/api/provider-context-caps",
+];
+const READ_PATHS = new Set(LINK_MANAGEMENT_READ_PATHS);
+/**
+ * Query keys that make a read trigger upstream work on the Home: forced refreshes and the
+ * per-account quota probes `?quota=1` starts on the OAuth-account and key-pool reads.
+ * `/api/models`, `/api/model-presets`, `/api/subagent-models` and `/api/subagent-model-fallback`
+ * are absent for the same reason: they run live provider discovery and may persist initial model
+ * selection. The preset preview exists only to decide a write a Child cannot make.
+ */
+const REFRESH_KEYS = ["refresh", "reload", "force", "quota"];
+
+/** Is `method path?query` (a Home management path, without the link prefix) readable over the link? */
+export function linkManagementReadAllowed(method: string, pathname: string, search: URLSearchParams | string = ""): boolean {
+  const upper = method.toUpperCase();
+  if (upper !== "GET" && upper !== "HEAD") return false;
+  if (!READ_PATHS.has(pathname)) return false;
+  const query = typeof search === "string" ? new URLSearchParams(search) : search;
+  return !REFRESH_KEYS.some(key => query.has(key));
+}
+
+/** The Home management URL a prefixed link request names, or null when it names none. */
+export function linkManagementTarget(url: URL): URL | null {
+  if (!url.pathname.startsWith(`${LINK_MANAGEMENT_PREFIX}/api/`)) return null;
+  const target = new URL(url.href);
+  target.pathname = url.pathname.slice(LINK_MANAGEMENT_PREFIX.length);
+  return target;
+}
+
+/** Home side: may the hub-link listener dispatch this request to the link management handler? */
+export function linkManagementRouteAllowed(url: URL, req: Request): boolean {
+  if (req.headers.has("upgrade")) return false;
+  if (url.pathname === LINK_CODEX_SETTINGS_PATH) return req.method === "GET" && url.search === "";
+  const target = linkManagementTarget(url);
+  return target !== null && linkManagementReadAllowed(req.method, target.pathname, target.searchParams);
+}
+
+export function isLinkManagementPath(pathname: string): boolean {
+  return pathname === LINK_MANAGEMENT_PREFIX || pathname.startsWith(`${LINK_MANAGEMENT_PREFIX}/`);
+}
+
+/**
+ * The one refusal every management surface on a link Child uses: the dashboard relay, the CLI,
+ * and the Child's listener. It names the Home and the link and never suggests a relay transport.
+ * `homePhrase` is "Home <name>" or "its Home" when the Child does not know the Home's name.
+ */
+export function linkChildManagementRefusal(homePhrase: string, linkId: string, operation = "This management command"): string {
+  return `This machine is a Remote Link Child managed by ${homePhrase} (link ${linkId}). `
+    + `${operation} runs on the Home, not on this Child: use the Home's dashboard or run the command there. No request was sent.`;
+}

package/src/link/remote-probe.ts

@@ -0,0 +1,38 @@
+import { MEMORY_DRAIN_RESTART_MS, REPLACEMENT_READY_TIMEOUT_MS } from "../lib/system-restart-contract";
+
+export const LINK_COMMAND_WORK_MS = 15_000;
+export const LINK_COMMAND_MAX_MS = 60_000;
+export const LINK_RELAY_VERIFY_MS = 15_000;
+export const LINK_CATALOG_MAX_BYTES = 4 * 1024 * 1024;
+
+/** Probe latency pays for SSH setup without making the remote work window unbounded. */
+export function linkCommandBudget(latencyMs = 0): number {
+  const latency = Number.isFinite(latencyMs) ? Math.max(0, latencyMs) : 0;
+  return Math.min(LINK_COMMAND_MAX_MS, LINK_COMMAND_WORK_MS + Math.ceil(latency * 4));
+}
+
+export function linkRestartBudget(latencyMs = 0): number {
+  return MEMORY_DRAIN_RESTART_MS + REPLACEMENT_READY_TIMEOUT_MS + linkCommandBudget(latencyMs);
+}
+
+/** Credential-free Child HTTP probe. Ignore curlrc/proxies; never follow a redirect. */
+export function remoteChildHttpArgv(port: number, path: "healthz" | "v1/catalog", timeoutMs = LINK_RELAY_VERIFY_MS): string[] {
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("invalid Child port");
+  const seconds = Math.max(1, Math.ceil(Math.min(LINK_RELAY_VERIFY_MS, timeoutMs) / 1000));
+  return ["sh", "-c", 'curl -q --noproxy "*" --silent --show-error --fail --connect-timeout 3 --max-time "$3" --write-out "\\n%{http_code}" "http://127.0.0.1:$1/$2"', "ocx-child-http", String(port), path, String(seconds)];
+}
+
+export const REMOTE_CURL_PREFLIGHT = ["sh", "-c", 'command -v curl >/dev/null 2>&1 && curl -q --version >/dev/null 2>&1', "ocx-curl-preflight"];
+
+export function parseChildHttp(stdout: string): unknown {
+  const match = /\n200$/.exec(stdout.trimEnd());
+  if (!match) throw new Error("Child HTTP probe did not return 200");
+  return JSON.parse(stdout.trimEnd().slice(0, match.index));
+}
+
+export function isChildHealth(value: unknown, role: "standalone" | "client", expectedPort: number): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const body = value as Record<string, unknown>;
+  return body.port === expectedPort && body.service === "opencodex" && Number.isInteger(body.pid) && (body.pid as number) > 0
+    && (role === "client" ? body.role === "client" : (body.role === undefined || body.role === "standalone") && body.restartCapability === "v1");
+}

package/src/link/ssh-argv.ts

@@ -131,15 +131,36 @@ export function buildExecArgv(options: ExecArgvOptions): string[] {
   ];
 }
 
+/** The POSIX shell's exit status for a command it could not find. */
+export const REMOTE_COMMAND_NOT_FOUND = 127;
+/** Reserved prelude status: the remote OS cannot run the POSIX Remote Link workflow. */
+export const REMOTE_PLATFORM_UNSUPPORTED = 125;
+
 /**
  * The remote sh script for every ocx call. `quoteRemote` single-quotes it, so the login shell
  * passes it through untouched and `$HOME`/`$PATH` expand in the remote `sh`; the arguments reach
- * ocx as `"$@"` without another round of parsing. The fallback directories are appended, so an
- * ocx the remote PATH already resolves keeps winning. A missing ocx exits 127.
+ * ocx as `"$@"` without another round of parsing. Desktop binaries precede PATH candidates;
+ * each candidate must run --version successfully. A missing runnable ocx exits 127.
  */
-export const REMOTE_OCX_SCRIPT = 'PATH="$PATH:$HOME/.bun/bin:$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin"; exec ocx "$@"';
-/** The POSIX shell's exit status for a command it could not find. */
-export const REMOTE_COMMAND_NOT_FOUND = 127;
+export const REMOTE_OCX_SCRIPT = `export PATH="$PATH:$HOME/.bun/bin:$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin"
+case "$(uname -s 2>/dev/null)" in Windows*|MSYS*|MINGW*|CYGWIN*) exit ${REMOTE_PLATFORM_UNSUPPORTED};; esac
+try_ocx() {
+  if [ -x "$1" ] && "$1" --version >/dev/null 2>&1; then
+    executable=$1
+    shift
+    exec "$executable" "$@"
+  fi
+}
+for candidate in "$HOME/.opencodex-desktop/bin/ocx" "/Applications/OpenCodex.app/Contents/MacOS/ocx" "/usr/bin/ocx"; do
+  try_ocx "$candidate" "$@"
+done
+remaining=$PATH
+while :; do
+  directory=\${remaining%%:*}
+  try_ocx "\${directory:-.}/ocx" "$@"
+  case "$remaining" in *:*) remaining=\${remaining#*:};; *) break;; esac
+done
+exit ${REMOTE_COMMAND_NOT_FOUND}`;
 
 export function remoteOcxArgv(args: readonly string[]): string[] {
   return ["sh", "-c", REMOTE_OCX_SCRIPT, "ocx", ...args];

package/src/link/ssh-runner.ts

@@ -1,6 +1,8 @@
 import { homedir } from "node:os";
 
 const DEFAULT_OUTPUT_BYTES = 64 * 1024;
+const MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+const TUNNEL_OUTPUT_EXIT_GRACE_MS = 250;
 const HINT_MAX_CHARS = 160;
 // Written as escapes on purpose: invisible and bidi controls must never sit literally in source.
 const ANSI_SEQUENCE = /\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b\[[0-?]*[ -/]*[@-~]|\u001b[@-_]/g;
@@ -93,10 +95,21 @@ export class SshRunnerError extends Error {
   }
 }
 
-async function readOutput(stream: ReadableStream<Uint8Array>, maxBytes: number, kill?: () => void, fatalUtf8 = true): Promise<string> {
+async function readOutput(stream: ReadableStream<Uint8Array>, maxBytes: number, kill?: () => void, fatalUtf8 = true, exited?: Promise<number>, signal?: AbortSignal): Promise<string> {
   const reader = stream.getReader();
   const chunks: Uint8Array[] = [];
   let total = 0;
+  let finished = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const cancel = (): void => { void reader.cancel().catch(() => {}); };
+  const onExit = (): void => {
+    if (!finished) timer = setTimeout(cancel, TUNNEL_OUTPUT_EXIT_GRACE_MS);
+  };
+  signal?.addEventListener("abort", cancel, { once: true });
+  if (signal?.aborted) cancel();
+  // A descendant may inherit a pipe after ssh exits. Cancellation completes pending reads
+  // immediately; do not await the underlying source's possibly unbounded cancel promise.
+  void exited?.then(onExit, onExit);
   try {
     for (;;) {
       const next = await reader.read();
@@ -104,11 +117,15 @@ async function readOutput(stream: ReadableStream<Uint8Array>, maxBytes: number,
       total += next.value.byteLength;
       if (total > maxBytes) {
         kill?.();
+        cancel();
         throw new SshRunnerError("output_limit", `ssh output exceeded ${maxBytes} bytes`);
       }
       chunks.push(next.value);
     }
   } finally {
+    finished = true;
+    if (timer !== undefined) clearTimeout(timer);
+    signal?.removeEventListener("abort", cancel);
     reader.releaseLock();
   }
   const bytes = new Uint8Array(total);
@@ -149,8 +166,8 @@ export function createSshRunner(deps: { spawn?: typeof Bun.spawn; timeoutMs?: nu
     } catch (error) {
       throw new SshRunnerError("spawn", `could not spawn ${argv[0] ?? "ssh"}`, { cause: error });
     }
-    const stdout = readOutput(outputStream(child.stdout), DEFAULT_OUTPUT_BYTES, () => defaultKill(child, "SIGTERM"));
-    const stderr = readOutput(outputStream(child.stderr), DEFAULT_OUTPUT_BYTES, () => defaultKill(child, "SIGTERM"), false);
+    const stdout = readOutput(outputStream(child.stdout), DEFAULT_OUTPUT_BYTES, () => defaultKill(child, "SIGTERM"), true, child.exited);
+    const stderr = readOutput(outputStream(child.stderr), DEFAULT_OUTPUT_BYTES, () => defaultKill(child, "SIGTERM"), false, child.exited);
     void stdout.catch(() => {});
     void stderr.catch(() => {});
     return {
@@ -165,9 +182,13 @@ export function createSshRunner(deps: { spawn?: typeof Bun.spawn; timeoutMs?: nu
 
   return {
     async run(argv, options = {}) {
+      const timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
+      if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
+        throw new SshRunnerError("timeout", "timeoutMs must be a positive integer at most 2147483647");
+      }
       const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_OUTPUT_BYTES;
-      if (!Number.isInteger(maxOutputBytes) || maxOutputBytes < 0) {
-        throw new SshRunnerError("output_limit", "maxOutputBytes must be a non-negative integer");
+      if (!Number.isInteger(maxOutputBytes) || maxOutputBytes < 0 || maxOutputBytes > MAX_OUTPUT_BYTES) {
+        throw new SshRunnerError("output_limit", `maxOutputBytes must be an integer between 0 and ${MAX_OUTPUT_BYTES}`);
       }
       let child: Bun.Subprocess;
       try {
@@ -181,41 +202,50 @@ export function createSshRunner(deps: { spawn?: typeof Bun.spawn; timeoutMs?: nu
         throw new SshRunnerError("spawn", `could not spawn ${argv[0] ?? "ssh"}`, { cause: error });
       }
 
-      const stdout = readOutput(outputStream(child.stdout), Math.min(maxOutputBytes, DEFAULT_OUTPUT_BYTES), () => defaultKill(child, "SIGTERM"));
-      const stderr = readOutput(outputStream(child.stderr), Math.min(maxOutputBytes, DEFAULT_OUTPUT_BYTES), () => defaultKill(child, "SIGTERM"), false);
-      if (options.stdin !== undefined) {
-        try {
-          const input = child.stdin;
-          if (!input || typeof input === "number") throw new Error("ssh stdin was not piped");
-          await input.write(options.stdin);
-          await input.end();
-        } catch (error) {
-          child.kill("SIGTERM");
-          throw new SshRunnerError("spawn", "could not write ssh stdin", { cause: error });
-        }
-      }
-
-      const timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
-      let timedOut = false;
+      const cancellation = new AbortController();
+      let stdout: Promise<string> | undefined;
+      let stderr: Promise<string> | undefined;
       let timer: ReturnType<typeof setTimeout> | undefined;
       const timeout = new Promise<never>((_, reject) => {
         timer = setTimeout(() => {
-          timedOut = true;
-          defaultKill(child, "SIGTERM");
           reject(new SshRunnerError("timeout", `ssh command exceeded ${timeoutMs}ms`));
         }, timeoutMs);
       });
       try {
-        const code = await Promise.race([child.exited, timeout]);
-        const [out, err] = await Promise.all([stdout, stderr]);
-        if (timedOut) throw new SshRunnerError("timeout", `ssh command exceeded ${timeoutMs}ms`);
+        const outStream = outputStream(child.stdout), errStream = outputStream(child.stderr);
+        stdout = readOutput(outStream, maxOutputBytes, undefined, true, undefined, cancellation.signal);
+        stderr = readOutput(errStream, Math.min(maxOutputBytes, DEFAULT_OUTPUT_BYTES), undefined, false, undefined, cancellation.signal);
+        const stdin = async (): Promise<void> => {
+          if (options.stdin === undefined) return;
+          try {
+            const input = child.stdin;
+            if (!input || typeof input === "number") throw new Error("ssh stdin was not piped");
+            await input.write(options.stdin);
+            // A timed-out write may settle later; do not start another operation after failure.
+            if (cancellation.signal.aborted) return;
+            await input.end();
+          } catch (error) {
+            throw new SshRunnerError("spawn", "could not write ssh stdin", { cause: error });
+          }
+        };
+        // Observe all rejections immediately, including errors arriving after timeout. One
+        // deadline covers stdin, exit and EOF: an inherited output pipe is still unfinished work.
+        const [, code, out, err] = await Promise.race([
+          Promise.all([stdin(), child.exited, stdout, stderr]), timeout,
+        ]);
         return { code, stdout: out, stderr: err };
       } catch (error) {
+        cancellation.abort();
+        // Only terminate this local SSH child. A kill failure must not hide the original error.
+        try { defaultKill(child, "SIGTERM"); } catch { /* Preserve the command failure when an already-gone child cannot be signalled. */ }
         if (error instanceof SshRunnerError) throw error;
         throw new SshRunnerError("spawn", "ssh command failed", { cause: error });
       } finally {
         if (timer !== undefined) clearTimeout(timer);
-        void Promise.allSettled([stdout, stderr, child.exited]);
+        void child.exited.catch(() => {});
+        // reader.cancel closes pending reads even if the source's cancel promise never settles.
+        // Do not await stdin or process exit: neither is guaranteed to settle after SIGTERM.
+        await Promise.allSettled([stdout, stderr]);
       }
     },
     spawnTunnel,
@@ -227,3 +257,4 @@ export function createSshRunner(deps: { spawn?: typeof Bun.spawn; timeoutMs?: nu
 }
 
 export const SSH_OUTPUT_CAP_BYTES = DEFAULT_OUTPUT_BYTES;
+export const SSH_MAX_OUTPUT_BYTES = MAX_OUTPUT_BYTES;

package/src/link/status-projection.ts

@@ -2,6 +2,7 @@ import type { LinkStore } from "./store";
 import type { LinkTunnelStatus } from "./supervisor";
 import type { TunnelState } from "./tunnel-state";
 import { readCompensation, type CompensationStore } from "./compensation";
+import type { OcxClientConnectionConfig } from "../types";
 
 export type LinkWireState = "connecting" | "connected" | "reconnecting" | "failed" | "idle";
 
@@ -25,6 +26,8 @@ export interface LinkStatusDto {
   };
 }
 
+export interface ClientLinkIdentity { direction: "hub-initiated" | "client-initiated"; alias?: string }
+
 export interface LinkListenerStatusProjection {
   state: "off" | "listening" | "failed";
   port: number | null;
@@ -32,6 +35,7 @@ export interface LinkListenerStatusProjection {
 
 export interface LinkStatusConfig {
   runtimeRole?: "standalone" | "hub" | "client";
+  client?: Pick<OcxClientConnectionConfig, "transport" | "link" | "serverUrl" | "connectedAt">;
 }
 
 function asWireState(state: TunnelState | "client-owned"): LinkWireState {
@@ -60,7 +64,7 @@ function stateDetails(
 
 /**
  * Project private link state into the exact K16 wire DTO. `clientChild` lets a client-side caller
- * report a child state this module cannot read itself (an invalid client sidecar); link code
+ * report a child state this module cannot read itself (including an invalid client sidecar); link code
  * stays free of client imports, so the caller supplies it.
  */
 export function projectLinkStatus(
@@ -70,6 +74,7 @@ export function projectLinkStatus(
   config: LinkStatusConfig,
   compensation: CompensationStore = readCompensation(),
   clientChild: LinkStatusDto["child"] = null,
+  identity: ClientLinkIdentity | null = null,
 ): LinkStatusDto {
   const byId = new Map(supervisorStates.map(status => [status.linkId, status]));
   const links = store.links.map(record => ({
@@ -79,18 +84,31 @@ export function projectLinkStatus(
     ...stateDetails(record, byId.get(record.id), compensation),
     tunnelPort: record.tunnelPort,
   }));
-  const childRecord = config.runtimeRole === "client" ? store.links[0] : undefined;
-  const invalidClientSidecar = config.runtimeRole === "client" ? clientChild : null;
+  const childRecord = config.runtimeRole === "client"
+    ? (config.client?.transport === "link" ? store.links.find(record => record.id === config.client?.link?.linkId) : store.links[0])
+    : undefined;
+  const projectedClientChild = config.runtimeRole === "client" ? clientChild : null;
   const childStatus = childRecord
     ? stateDetails(childRecord, byId.get(childRecord.id), compensation)
     : undefined;
   const role = config.runtimeRole === "client"
     ? "child"
     : store.links.length > 0 ? "home" : "standalone";
+  // Home owns the record and reverse SSH process. The Child's persisted connection supplies
+  // identity and port, while an optional caller observation supplies live tunnel state.
+  const client = config.runtimeRole === "client" && config.client?.transport === "link" ? config.client : undefined;
+  const child = projectedClientChild ?? (childRecord && childStatus ? { alias: childRecord.alias, ...childStatus }
+    : client?.link ? { alias: identity?.alias ?? client.serverUrl, state: "idle" as const, since: client.connectedAt, reason: null } : null);
+  if (client?.link && child && identity) {
+    const active = links.find(link => link.id === client.link!.linkId);
+    const projected = { id: client.link.linkId, direction: identity.direction, tunnelPort: client.link.tunnelPort, ...child, alias: identity.alias ?? child.alias };
+    if (active) Object.assign(active, projected, compensation.entries[active.id] && childRecord ? stateDetails(childRecord, byId.get(active.id), compensation) : {});
+    else links.push(projected);
+  }
   return {
     role,
     listener: { state: listenerStatus.state, port: listenerStatus.port },
     links,
-    child: invalidClientSidecar ?? (childRecord && childStatus ? { alias: childRecord.alias, ...childStatus } : null),
+    child,
   };
 }