@bitkyc08/opencodex 2.83.0 → 2.86.0

package/src/client/link-home.ts

@@ -0,0 +1,248 @@
+/**
+ * A Remote Link Child's view of its Home (#6957): the Home's name for refusal and status text,
+ * the Home's OpenCodex-owned Codex settings, and authenticated read-only management reads.
+ *
+ * Every read goes through the connection-bound link relay (`fetchBoundLinkRelay`): the link key
+ * is sent only after the listener on the tunnel port proves it holds the same link identity, so a
+ * process that took the tunnel port never sees the key.
+ */
+import { chmodSync, lstatSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFile, isMissingPathError } from "../config/atomic-write";
+import { readBoundedResponseBytes } from "../lib/bounded-body";
+import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
+import { hardenSecretDir } from "../lib/windows-secret-acl";
+import {
+  parseHomeCodexSettingsDocument,
+  type HomeCodexSettingsDocument,
+} from "../link/codex-settings";
+import {
+  LINK_CODEX_SETTINGS_PATH,
+  LINK_MANAGEMENT_PREFIX,
+  linkManagementReadAllowed,
+} from "../link/management-routes";
+import { linkDir } from "../link/paths";
+import type { OcxClientConnectionConfig } from "../types";
+import { fetchBoundLinkRelay } from "./link-relay-transport";
+import { readClientLinkState, type ClientLinkState } from "./link-state";
+
+const RECORD_MAX_BYTES = 64 * 1024;
+const SETTINGS_MAX_BYTES = 64 * 1024;
+const READ_TIMEOUT_MS = 10_000;
+
+export interface LinkHomeDeps {
+  /** Trusted complete-send test seam; production uses the connection-bound transport. */
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+}
+
+/** The connection fields a Home read needs; connect calls these before its state is committed. */
+export type LinkHomeConnection = Pick<OcxClientConnectionConfig, "transport" | "link" | "apiKeyId">;
+
+export interface HomeCodexSettingsRecord {
+  linkId: string;
+  fetchedAt: string;
+  document: HomeCodexSettingsDocument;
+}
+
+export function homeCodexSettingsPath(): string {
+  return join(linkDir(), "home-codex-settings.json");
+}
+
+function linkTarget(connection: LinkHomeConnection, admissionKey: string) {
+  if (connection.transport !== "link" || !connection.link) throw new Error("not a Remote Link Child");
+  return {
+    tunnelPort: connection.link.tunnelPort,
+    linkId: connection.link.linkId,
+    apiKeyId: connection.apiKeyId,
+    admissionKey,
+  };
+}
+
+/** The last applied Home settings for this link, or null when absent, malformed or another link's. */
+export function readHomeCodexSettingsRecord(linkId: string, path = homeCodexSettingsPath()): HomeCodexSettingsRecord | null {
+  try {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.size > RECORD_MAX_BYTES) return null;
+    const raw = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+    const record = raw as Record<string, unknown>;
+    if (record.linkId !== linkId || typeof record.fetchedAt !== "string" || Number.isNaN(Date.parse(record.fetchedAt))) return null;
+    const document = parseHomeCodexSettingsDocument(record.document);
+    return document ? { linkId, fetchedAt: record.fetchedAt, document } : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeHomeCodexSettingsRecord(record: HomeCodexSettingsRecord, path = homeCodexSettingsPath()): void {
+  const dir = linkDir();
+  assertNotRealHomeUnderTest(join(dir, ".."));
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  if (process.platform === "win32") hardenSecretDir(dir, { required: true });
+  else chmodSync(dir, 0o700);
+  atomicWriteFile(path, `${JSON.stringify(record, null, 2)}\n`);
+  if (process.platform !== "win32") chmodSync(path, 0o600);
+}
+
+export function clearHomeCodexSettingsRecord(path = homeCodexSettingsPath()): void {
+  try { unlinkSync(path); } catch (error) { if (!isMissingPathError(error)) throw error; }
+}
+
+/**
+ * The Home's name as this Child knows it: the SSH alias of a Child-initiated link, else the
+ * host name the Home published with its Codex settings, else null ("its Home").
+ */
+export function linkHomeName(
+  connection: OcxClientConnectionConfig,
+  readSidecar: () => ClientLinkState | null = readClientLinkState,
+): string | null {
+  const linkId = connection.link?.linkId;
+  if (!linkId) return null;
+  try {
+    const sidecar = readSidecar();
+    if (sidecar && sidecar.linkId === linkId) return sidecar.alias;
+  } catch { /* an unreadable sidecar names nothing */ }
+  return readHomeCodexSettingsRecord(linkId)?.document.home.name ?? null;
+}
+
+/** "Home home-box" or "its Home": the phrase every link Child message uses. */
+export function linkHomePhrase(
+  connection: OcxClientConnectionConfig,
+  readSidecar?: () => ClientLinkState | null,
+): string {
+  const name = linkHomeName(connection, readSidecar);
+  return name ? `Home ${name}` : "its Home";
+}
+
+/**
+ * A `fetch` for the existing data-plane reads (`/v1/hub-state`, `/v1/usage`) that sends each
+ * request through the connection-bound link relay, so the link key reaches only the Home.
+ */
+export function linkBoundFetch(connection: LinkHomeConnection, admissionKey: string): typeof fetch {
+  const target = linkTarget(connection, admissionKey);
+  return ((input: RequestInfo | URL, init?: RequestInit) => {
+    // A Request keeps its method, headers and signal unless init overrides them.
+    const request = input instanceof Request ? input : null;
+    const url = request ? request.url : String(input);
+    return fetchBoundLinkRelay(target, url, {
+      ...(request ? { method: request.method, headers: request.headers, signal: request.signal } : {}),
+      ...(init ?? {}),
+      redirect: "manual",
+    });
+  }) as typeof fetch;
+}
+
+/**
+ * One authenticated, read-only management read on the Home. `path` is a Home management path
+ * with an optional query (`/api/providers`); anything outside the shared allowlist throws before
+ * a request is built.
+ */
+export async function fetchLinkHomeManagement(
+  connection: LinkHomeConnection,
+  admissionKey: string,
+  path: string,
+  init: { method?: "GET" | "HEAD"; signal?: AbortSignal } = {},
+  deps: LinkHomeDeps = {},
+): Promise<Response> {
+  const method = init.method ?? "GET";
+  const local = new URL(path, "http://link.invalid");
+  if (local.origin !== "http://link.invalid" || !linkManagementReadAllowed(method, local.pathname, local.searchParams)) {
+    throw new Error("path is not readable over the Remote Link");
+  }
+  const target = linkTarget(connection, admissionKey);
+  const destination = `http://127.0.0.1:${target.tunnelPort}${LINK_MANAGEMENT_PREFIX}${local.pathname}${local.search}`;
+  const signal = init.signal
+    ? AbortSignal.any([init.signal, AbortSignal.timeout(deps.timeoutMs ?? READ_TIMEOUT_MS)])
+    : AbortSignal.timeout(deps.timeoutMs ?? READ_TIMEOUT_MS);
+  const request: RequestInit = {
+    method,
+    headers: { accept: "application/json", authorization: `Bearer ${admissionKey}` },
+    redirect: "manual",
+    signal,
+  };
+  return deps.fetchImpl ? deps.fetchImpl(destination, request) : fetchBoundLinkRelay(target, destination, request);
+}
+
+export type HomeCodexSettingsFetch =
+  | { kind: "fresh"; document: HomeCodexSettingsDocument }
+  | { kind: "unsupported" }
+  | { kind: "failed"; reason: string };
+
+export async function fetchHomeCodexSettings(
+  connection: LinkHomeConnection,
+  admissionKey: string,
+  deps: LinkHomeDeps = {},
+): Promise<HomeCodexSettingsFetch> {
+  let response: Response;
+  try {
+    const target = linkTarget(connection, admissionKey);
+    const destination = `http://127.0.0.1:${target.tunnelPort}${LINK_CODEX_SETTINGS_PATH}`;
+    const request: RequestInit = {
+      method: "GET",
+      headers: { accept: "application/json", authorization: `Bearer ${admissionKey}` },
+      redirect: "manual",
+      signal: AbortSignal.timeout(deps.timeoutMs ?? READ_TIMEOUT_MS),
+    };
+    response = deps.fetchImpl ? await deps.fetchImpl(destination, request) : await fetchBoundLinkRelay(target, destination, request);
+  } catch (error) {
+    return { kind: "failed", reason: error instanceof Error && error.name === "LinkRelayAuthenticationError" ? error.message : "the Home is unreachable" };
+  }
+  if (response.status === 404) {
+    try { await response.body?.cancel(); } catch { /* best effort */ }
+    return { kind: "unsupported" };
+  }
+  if (!response.ok) {
+    try { await response.body?.cancel(); } catch { /* best effort */ }
+    return { kind: "failed", reason: `the Home answered HTTP ${response.status}` };
+  }
+  try {
+    const result = await readBoundedResponseBytes(response, { maxBytes: SETTINGS_MAX_BYTES, signal: AbortSignal.timeout(deps.timeoutMs ?? READ_TIMEOUT_MS) });
+    if (result.oversized) return { kind: "failed", reason: "the Home's settings exceeded the allowed size" };
+    const document = parseHomeCodexSettingsDocument(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(result.bytes)));
+    return document ? { kind: "fresh", document } : { kind: "failed", reason: "the Home returned an unreadable settings document" };
+  } catch {
+    return { kind: "failed", reason: "the Home returned an unreadable settings document" };
+  }
+}
+
+export type HomeCodexSettingsSource =
+  | { source: "home"; document: HomeCodexSettingsDocument; fetchedAt: string }
+  | { source: "cached"; document: HomeCodexSettingsDocument; fetchedAt: string; reason: string }
+  | { source: "local"; reason: string };
+
+/**
+ * The settings a sync applies. A failed read reuses the last record for this link so a brief
+ * outage never flips the Child back to its local values; a Home that predates the route leaves
+ * the Child's local values in place and says so. A fresh read is NOT recorded here: the caller
+ * records it with `recordHomeCodexSettings` only after the injection that applies it succeeds,
+ * because `ocx status` reads the record as "applied".
+ */
+export async function resolveHomeCodexSettings(
+  connection: LinkHomeConnection,
+  admissionKey: string,
+  deps: LinkHomeDeps & { now?: () => Date } = {},
+): Promise<HomeCodexSettingsSource> {
+  const linkId = connection.link?.linkId;
+  if (!linkId) return { source: "local", reason: "not a Remote Link Child" };
+  const fetched = await fetchHomeCodexSettings(connection, admissionKey, deps);
+  if (fetched.kind === "fresh") {
+    return { source: "home", document: fetched.document, fetchedAt: (deps.now ?? (() => new Date()))().toISOString() };
+  }
+  if (fetched.kind === "unsupported") {
+    clearHomeCodexSettingsRecord();
+    return { source: "local", reason: "the Home does not publish Codex settings; upgrade the Home" };
+  }
+  const cached = readHomeCodexSettingsRecord(linkId);
+  return cached
+    ? { source: "cached", document: cached.document, fetchedAt: cached.fetchedAt, reason: fetched.reason }
+    : { source: "local", reason: fetched.reason };
+}
+
+/** Record settings a successful injection applied. Best effort: the config is already written. */
+export function recordHomeCodexSettings(linkId: string, settings: HomeCodexSettingsSource): void {
+  if (settings.source !== "home") return;
+  try {
+    writeHomeCodexSettingsRecord({ linkId, fetchedAt: settings.fetchedAt, document: settings.document });
+  } catch { /* the next sync records it */ }
+}

package/src/client/link-management-relay.ts

@@ -0,0 +1,61 @@
+/**
+ * The Child end of the Remote Link management relay (#6957).
+ *
+ * The Child's dashboard reaches its Home's management reads at `/api/machine/hub-relay/api/*`,
+ * the same base a hub client's dashboard uses. The browser authenticates to the Child with the
+ * Child's own dashboard session; this relay drops every browser header, builds a fresh GET for
+ * the Home's `/v1/link-management` prefix and sends it through the connection-bound link relay,
+ * which attaches the link key only after the tunnel listener proves the link identity. Anything
+ * outside the shared read allowlist is refused here, before a request exists.
+ */
+import { HUB_RELAY_RESPONSE_BODY_MAX_BYTES } from "./hub-relay";
+import type { LinkIngress } from "./link-ingress";
+import { relayLinkDataRequest } from "./link-relay";
+import {
+  LINK_MANAGEMENT_PREFIX,
+  linkChildManagementRefusal,
+  linkManagementReadAllowed,
+  linkManagementRouteAllowed,
+} from "../link/management-routes";
+
+export const LINK_CHILD_READ_ONLY = "link_child_read_only";
+
+export function linkChildRefusalResponse(homePhrase: string, linkId: string, operation: string): Response {
+  return Response.json({
+    error: linkChildManagementRefusal(homePhrase, linkId, operation),
+    code: LINK_CHILD_READ_ONLY,
+    linkId,
+  }, { status: 403, headers: { "cache-control": "no-store" } });
+}
+
+export async function relayLinkManagementRead(
+  req: Request,
+  suffix: string,
+  ingress: LinkIngress,
+  homePhrase: string,
+): Promise<Response> {
+  const linkId = ingress.linkId ?? "unknown";
+  const query = suffix.indexOf("?");
+  const pathname = query === -1 ? suffix : suffix.slice(0, query);
+  const search = query === -1 ? "" : suffix.slice(query);
+  if (!linkManagementReadAllowed(req.method, pathname, new URLSearchParams(search.slice(1)))) {
+    return linkChildRefusalResponse(homePhrase, linkId, `${req.method.toUpperCase()} ${pathname}`);
+  }
+  const admissionKey = ingress.linkKey();
+  if (!admissionKey) return Response.json({ error: "link_credential_unavailable" }, { status: 503 });
+  const outbound = new Request(`http://127.0.0.1${LINK_MANAGEMENT_PREFIX}${pathname}${search}`, {
+    method: req.method,
+    headers: { accept: "application/json" },
+    signal: req.signal,
+  });
+  return relayLinkDataRequest(outbound, {
+    tunnelPort: ingress.tunnelPort,
+    admissionKey,
+    linkId: ingress.linkId,
+    apiKeyId: ingress.apiKeyId,
+  }, {
+    ...ingress.relay,
+    bodyLimitBytes: HUB_RELAY_RESPONSE_BODY_MAX_BYTES,
+    routeAllowed: linkManagementRouteAllowed,
+  });
+}

package/src/client/link-relay.ts

@@ -69,6 +69,11 @@ export interface LinkRelayDeps {
   /** The longest a request waits for a reconnecting tunnel, from its first wait. */
   holdMs?: number;
   now?: () => number;
+  /**
+   * The route table this relay enforces. Defaults to the data-plane table; only the Child's
+   * authenticated management relay passes the read-only management table (#6957).
+   */
+  routeAllowed?: (url: URL, req: Request) => boolean;
 }
 
 export const LINK_RELAY_RETRY_AFTER_SECONDS = 1;
@@ -305,7 +310,7 @@ export async function relayLinkDataRequest(
   deps: LinkRelayDeps = {},
 ): Promise<Response> {
   const url = new URL(req.url);
-  if (!linkRouteAllowed(url, req)) return jsonError(404, "not_found");
+  if (!(deps.routeAllowed ?? linkRouteAllowed)(url, req)) return jsonError(404, "not_found");
   let destination: string;
   try { destination = linkRelayDestination(url, target); } catch { return jsonError(404, "not_found"); }
   const validation = validateHubRelayRequestHeaders(linkFramingHeaders(req.headers));

package/src/client/link-status.ts

@@ -1,3 +1,7 @@
+import { lstatSync } from "node:fs";
+import { isMissingPathError } from "../config/atomic-write";
+import { readClientLinkState, childLinkMarkerPath } from "./link-state";
+import type { ClientLinkIdentity } from "../link/status-projection";
 import type { LinkStatusDto } from "../link/status-projection";
 import type { ClientLinkState } from "./link-state";
 import type { ClientLinkSupervisorStatus } from "./link-tunnel";
@@ -37,3 +41,13 @@ function childState(sidecar: ClientLinkSidecarRead, supervisor: ClientLinkSuperv
     reason: supervisor.probe ?? (tunnel.kind === "failed" ? tunnel.reason : null),
   };
 }
+
+/** Only client-owned evidence can establish who owns the tunnel. Unreadable evidence stays unknown. */
+export function clientLinkStatusIdentity(linkId: string): ClientLinkIdentity | null {
+  try {
+    const sidecar = readClientLinkState();
+    if (sidecar) return sidecar.linkId === linkId ? { direction: "client-initiated", alias: sidecar.alias } : null;
+    try { lstatSync(childLinkMarkerPath()); return null; }
+    catch (error) { return isMissingPathError(error) ? { direction: "hub-initiated" } : null; }
+  } catch { return null; }
+}

package/src/client/machine-api.ts

@@ -3,6 +3,7 @@ import { diagnoseCodexShim, installCodexShim, uninstallCodexShim } from "../code
 import { readManagementJsonBody } from "../server/management/body";
 import type { OcxClientConnectionConfig } from "../types";
 import { disconnectClient, syncConnectedClient } from "./connect";
+import { linkHomeName } from "./link-home";
 import { isLinkConnection } from "./state";
 
 export type HubReachability = "unknown" | "online" | "offline" | "unauthorized";
@@ -19,6 +20,8 @@ export interface MachineStatusV1 {
   connectedAt: string;
   catalogSyncedAt?: string;
   hubReachability: HubReachability;
+  /** Present only on a Remote Link Child: the dashboard shows "managed by Home <name>". */
+  link?: { linkId: string; home: string | null; readOnly: true };
 }
 
 export interface MachineApiDeps {
@@ -27,6 +30,8 @@ export interface MachineApiDeps {
   scheduleStandaloneRecycle: (disconnectedTokenFingerprint: string) => void;
   hubReachability?: () => HubReachability;
   setHubReachability?: (value: HubReachability) => void;
+  /** Link mode: the Home's name as this listener knows it (sidecar alias or recorded host name). */
+  linkHomeName?: () => string | null;
 }
 
 const defaultDeps: MachineApiDeps = {
@@ -52,24 +57,26 @@ async function jsonBody(req: Request): Promise<unknown | Response> {
 function statusPayload(req: Request, state: OcxClientConnectionConfig, deps: MachineApiDeps): MachineStatusV1 {
   const machineBase = new URL(req.url).origin;
   // A link Child's management URL is the tunnel, whose hub-link ingress serves no /api/* and no
-  // session bootstrap. Its dashboard reads the Child's own listener instead (`/api/link/status`).
+  // session bootstrap. Its dashboard therefore uses this listener's relay base: the browser holds
+  // only this listener's session, and the listener relays allowlisted reads to the Home with the
+  // link key (#6957, src/client/link-management-relay.ts).
   const linkMode = isLinkConnection(state);
+  const relay = linkMode || state.managementTransport === "relay";
   return {
     mode: "client",
     connected: true,
     machineBase,
-    sharedBase: linkMode
-      ? machineBase
-      : state.managementTransport === "relay"
-        ? `${machineBase}/api/machine/hub-relay`
-        : state.managementUrl,
+    sharedBase: relay ? `${machineBase}/api/machine/hub-relay` : state.managementUrl,
     sharedServerOrigin: linkMode ? machineBase : state.managementUrl,
-    managementTransport: state.managementTransport,
+    managementTransport: relay ? "relay" : state.managementTransport,
     apiKeyId: state.apiKeyId,
     protocolVersion: state.protocolVersion,
     connectedAt: state.connectedAt,
     ...(state.catalogSyncedAt ? { catalogSyncedAt: state.catalogSyncedAt } : {}),
     hubReachability: deps.hubReachability?.() ?? "unknown",
+    ...(linkMode && state.link
+      ? { link: { linkId: state.link.linkId, home: deps.linkHomeName ? deps.linkHomeName() : linkHomeName(state), readOnly: true as const } }
+      : {}),
   };
 }
 

package/src/client/machine-listener.ts

@@ -23,6 +23,8 @@ import { projectClientLinkChild, type ClientLinkSidecarRead } from "./link-statu
 import type { ClientLinkSupervisorStatus } from "./link-tunnel";
 import { packageVersion } from "../lib/package-version";
 import { linkRouteAllowed } from "../link/routes";
+import { linkHomeName, linkHomePhrase } from "./link-home";
+import { relayLinkManagementRead } from "./link-management-relay";
 
 const VERSION = packageVersion("0.0.0");
 const GUI_SPA_PATHS = new Set([
@@ -100,6 +102,8 @@ export function startMachineListener(
   if (linkMode && !connection.link) throw new Error("link machine listener requires link transport metadata");
   const managementAuth = deps.managementAuthState ?? initializeManagementAuthState(config);
   let hubReachability: HubReachability = "unknown";
+  const readSidecar = deps.readSidecar ?? (() => readClientLinkState());
+  const sidecarOrNull = () => { const read = readSidecarSafely(readSidecar); return read === "invalid" ? null : read; };
   const machineApiDeps: MachineApiDeps = {
     sync: deps.machineApi?.sync ?? syncConnectedClient,
     disconnect: deps.machineApi?.disconnect ?? disconnectClient,
@@ -108,8 +112,11 @@ export function startMachineListener(
     }),
     hubReachability: deps.machineApi?.hubReachability ?? (() => hubReachability),
     setHubReachability: deps.machineApi?.setHubReachability ?? (value => { hubReachability = value; }),
+    ...(linkMode ? { linkHomeName: () => linkHomeName(connection, sidecarOrNull) } : {}),
   };
-  const relayEnabled = !linkMode && connection.managementTransport === "relay";
+  // A link Child relays its dashboard's management reads to the Home over the link (#6957);
+  // a hub client relays over its management transport when that is `relay`.
+  const relayEnabled = linkMode || connection.managementTransport === "relay";
   // Link mode only. Everything is resolved once here, so a relayed request reads no file and
   // builds no policy: the key is cached, the loopback policy is fixed at bind like the listener.
   const inboundBodyLimit = resolveInboundBodyLimitBytes(config.maxInboundBodyBytes);
@@ -123,8 +130,6 @@ export function startMachineListener(
       relay: { fetchImpl: deps.fetchImpl, bodyLimitBytes: inboundBodyLimit, tunnel: deps.linkTunnel, ...deps.linkRelay },
     }
     : null;
-  const readSidecar = deps.readSidecar ?? (() => readClientLinkState());
-
   return (deps.serve ?? (options => Bun.serve(options)))({
     port: port ?? config.port ?? 10100,
     hostname: "127.0.0.1",
@@ -147,9 +152,29 @@ export function startMachineListener(
       }
       if (url.pathname.startsWith("/api/machine/hub-relay/")) {
         if (!relayEnabled) return json404(req);
+        const prefix = "/api/machine/hub-relay";
+        if (linkIngress) {
+          const suffix = `${url.pathname.slice(prefix.length)}${url.search}`;
+          // The dashboard's shared plane bootstraps here. On a link Child that plane is this
+          // listener, so it receives this listener's own session; no Home credential exists.
+          if (suffix === "/opencodex-session") {
+            if (req.method !== "GET") return json404(req);
+            const session = issueGuiSession(req, config, managementAuth, { trustedTailscaleIngress: false });
+            return session ? serveSessionBootstrap(session) : Response.json({ error: "session unavailable" }, { status: 503 });
+          }
+          const authError = requireManagementAuth(req, managementAuth, config);
+          if (authError) return authError;
+          if (managementPrincipal(req, managementAuth, config) !== "gui-session") {
+            return Response.json({ error: "opencodex machine GUI session required" }, { status: 401 });
+          }
+          const response = await relayLinkManagementRead(req, suffix, linkIngress, linkHomePhrase(connection, sidecarOrNull));
+          if (response.status === 401) hubReachability = "unauthorized";
+          else if (response.status >= 500) hubReachability = "offline";
+          else if (response.status !== 403) hubReachability = "online";
+          return response;
+        }
         const authError = requireMachineAuth(req, managementAuth, config);
         if (authError) return authError;
-        const prefix = "/api/machine/hub-relay";
         const suffix = `${url.pathname.slice(prefix.length)}${url.search}`;
         const response = await relayHubManagementRequest(req, suffix, {
           managementUrl: connection.managementUrl,

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

@@ -202,6 +202,7 @@ export interface ExportContext {
 export type DroidReasoningDefaults = Record<string, string>;
 
 export type ExportClientId =
+  | "qoder"
   | "opencode"
   | "pi"
   | "omp"

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

@@ -9,8 +9,9 @@ import { shouldInjectApiAuthHeader } from "../../codex/inject";
 
 
 /**
- * Authoritative context window, or undefined. Never guesses: a missing, non-finite, or
- * non-positive value means the serializer omits every context-derived field.
+ * Validate the supplied catalog window (which may be a labelled vendor estimate).
+ * A missing, non-finite, or non-positive value omits every context-derived field;
+ * this serializer does not independently infer a window.
  */
 export function authoritativeContextWindow(contextWindow: number | undefined): number | undefined {
   if (typeof contextWindow === "number" && Number.isFinite(contextWindow) && contextWindow > 0) {

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

@@ -0,0 +1,93 @@
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { isLoopbackHostname, shouldInjectApiAuthHeader } from "../../codex/loopback-target";
+import { formatSelectorConjunction } from "../../integrations/merge";
+import { ClientPathError } from "../config-export";
+import type { ExportContext, ManagedContribution, OpencodeLaunchEnv } from "./contracts";
+import { LOOPBACK_API_KEY_PLACEHOLDER, OPENCODE_PROVIDER_ID } from "./constants";
+import { authoritativeContextWindow, normalizeExportModels } from "./model-metadata";
+
+/**
+ * Qoder's configuration directory: `QODER_CONFIG_DIR` when set, otherwise `~/.qoder`
+ * (https://docs.qoder.com/cli/settings-reference). Export and detection both resolve it here.
+ * A relative override is refused because opencodex and Qoder would anchor it to different cwds.
+ */
+export function qoderHomeDir(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  const override = env.QODER_CONFIG_DIR?.trim();
+  if (!override) return join(home, ".qoder");
+  if (override === "~") return home;
+  if (override.startsWith("~/") || override.startsWith("~\\")) return join(home, override.slice(2));
+  if (!isAbsolute(override)) {
+    throw new ClientPathError(
+      `QODER_CONFIG_DIR must be an absolute path or start with ~; "${override}" depends on the working directory, `
+      + "so opencodex and Qoder would disagree about which file it names.",
+    );
+  }
+  return override;
+}
+
+export function qoderConfigPath(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  return join(qoderHomeDir(env, home), "settings.json");
+}
+
+/** Qoder IDE and qodercli share this provider and custom-model catalog. */
+export function buildQoderClientConfig(ctx: ExportContext) {
+  if (shouldInjectApiAuthHeader(ctx.config) || !isLoopbackHostname(new URL(ctx.baseUrl).hostname)) {
+    throw new Error("Qoder's placeholder API key requires a loopback-only listener.");
+  }
+  return qoderDocument(ctx);
+}
+
+function qoderDocument(ctx: ExportContext) {
+  const models = normalizeExportModels(ctx.models);
+  return {
+    providers: {
+      [OPENCODE_PROVIDER_ID]: {
+        type: "openai-compatible",
+        protocol: "openai",
+        displayName: "opencodex",
+        baseUrl: ctx.baseUrl,
+        apiKey: LOOPBACK_API_KEY_PLACEHOLDER,
+        ...(models[0] ? { defaultModel: models[0].namespaced } : {}),
+        models: models.map(model => ({ model: model.namespaced })),
+      },
+    },
+    modelConfigs: {
+      customModels: models.map(model => ({
+        provider: OPENCODE_PROVIDER_ID,
+        apiKey: LOOPBACK_API_KEY_PLACEHOLDER,
+        model: model.namespaced,
+        baseURL: ctx.baseUrl,
+        displayName: model.namespaced,
+        maxInputTokens: authoritativeContextWindow(model.contextWindow) ?? 128000,
+      })),
+    },
+  };
+}
+
+export type QoderGeneratedConfig = ReturnType<typeof buildQoderClientConfig>;
+
+export function summarizeQoder(document: unknown): { modelCount: number; modelsWithoutLimits: number } {
+  const models = (document as QoderGeneratedConfig | undefined)?.modelConfigs?.customModels ?? [];
+  return { modelCount: models.length, modelsWithoutLimits: 0 };
+}
+
+export function buildQoderContribution(ctx: ExportContext): ManagedContribution {
+  // The writer gates admission before applying. Classification and disable must
+  // still work after the operator changes the proxy to a non-loopback bind.
+  const doc = qoderDocument(ctx);
+  return {
+    clientId: "qoder",
+    fragments: [
+      { path: ["providers", OPENCODE_PROVIDER_ID], value: doc.providers[OPENCODE_PROVIDER_ID] },
+      ...doc.modelConfigs.customModels.map(model => {
+        const selector = formatSelectorConjunction([
+          { field: "provider", value: OPENCODE_PROVIDER_ID },
+          { field: "model", value: model.model },
+        ]);
+        if (selector === null) throw new Error("Qoder model ID cannot be represented by a managed array selector.");
+        return { path: ["modelConfigs", "customModels", selector], value: model };
+      }),
+    ],
+  };
+}