@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
191 lines (184 loc) • 10.5 kB
text/typescript
import type { OcxConfig } from "../../types";
import type { LowQuotaEvent } from "../../codex/low-quota-events";
import type { Channel } from "../../update/index";
import type { UpdateCheckResult } from "../../update/job";
import type { NativeProfileApiDeps } from "../../codex/native-profile-api";
import type { CodexLogGuardProtectionDeps } from "../../codex/log-guard/protection";
import type { CodexLogGuardMaintenanceDeps } from "../../codex/log-guard/maintenance";
import type { StartupHealth } from "../../codex/autostart-health";
import type { StartupInstallAction } from "../startup-action-control";
import type { ManagementPrincipal, ManagementSessionControl } from "../management-auth";
import type { CatalogModel } from "../../codex/catalog";
import type { refreshOwnedCatalogIntegrations } from "../../integrations/catalog-refresh";
import type { Paths as CodexPromptPaths } from "../../codex/prompt-layers";
import type { injectGrokConfig } from "../../grok/inject";
import type { removeDesktop3pStandardPivot, writeDesktop3pConfig } from "../../claude/desktop-3p";
import type { ClaudeDesktopPolicyProbeOptions, ClaudeDesktopPolicyState } from "../../claude/desktop-policy";
import type { RuntimePortState } from "../../config/process-state";
import type { CursorInstall } from "../../integrations/cursor-detect";
import type { CursorEffortTable } from "../../integrations/cursor-effort-table";
import type { CatalogDisposition, ConvergeCodex } from "../../codex/convergence-types";
import type {
performCodexRestart,
readCodexAppServerState,
} from "../../codex/app-server-restart-service";
import type { RequestMetricsSnapshotter } from "../request-metrics";
import type { RemoteWorkspaceHub } from "../../remote-control/workspace-hub";
import type { RemoteWorkspaceSessionService } from "../../remote-control/workspace-sessions";
import type { LinkSupervisor } from "../../link/supervisor";
import type { LinkListenerLifecycle } from "../index/link-listener";
import type { SshRunner } from "../../link/ssh-runner";
import type { LinkStore } from "../../link/store";
import type { IssuedApiKey } from "./oauth-account-routes";
export type RemoteWorkspaceHubApi = Pick<RemoteWorkspaceHub,
"identity" | "createPairingGrant" | "assertPairingSourceAllowed" | "pairDevice"
| "authenticateDeviceToken" | "attachConnection" | "updateDeviceCapabilities"
| "detachConnection" | "listDevices" | "revokeDevice" | "closeAllConnections">;
export type RemoteWorkspaceSessionsApi = Pick<RemoteWorkspaceSessionService,
"availability" | "list" | "create" | "prompt" | "submitPrompt" | "stop" | "shutdown">;
export interface ManagementRequestIngress {
trustedLoopback: boolean;
guiSessionIssuance?: import("../gui-session").GuiSessionIssuance | null;
}
export interface ManagementApiDeps {
/** Bound to this server's lifecycle owner; absent in direct route tests. */
listLowQuotaEvents?: (limit?: number) => LowQuotaEvent[];
/** Bound Claude intercept state, injectable for isolated management-route tests. */
getClaudeInterceptState?: typeof import("../../claude/intercept/runtime").getClaudeInterceptState;
/** Reconciliation seam for field-scoped rollback tests. */
reconcileClaudeFirstPartySettings?: typeof import("../../claude/first-party-settings").reconcileClaudeFirstPartySettings;
/** Read-only process-local aggregate metrics; absent keeps the scrape route unavailable. */
requestMetrics?: RequestMetricsSnapshotter;
checkPackageUpdate?: (channel: Channel) => Promise<UpdateCheckResult>;
remoteWorkspaceHub?: RemoteWorkspaceHubApi;
remoteWorkspaceSessions?: RemoteWorkspaceSessionsApi;
/** The listener retains and awaits teardown only after this optional subsystem activates. */
remoteWorkspaceStopping?: () => boolean;
onRemoteWorkspaceShutdown?: (shutdown: () => Promise<void>) => void;
/** Isolates automatic owned-client writes in route tests. */
refreshOwnedCatalogIntegrations?: typeof refreshOwnedCatalogIntegrations;
/** Platform seam for capability projections; does not alter host-level startup behavior. */
platform?: NodeJS.Platform;
toggleCodexMultiAgentV2?: (enabled: boolean) => void;
toggleDefaultModeRequestUserInput?: (enabled: boolean) => void;
createManagementConvergeCodex?: (config: Readonly<OcxConfig>) => ConvergeCodex;
/** Test-only destination for best-effort Claude agent-definition sync. */
claudeAgentConfigDir?: string;
/** Startup-health seam keeps route tests from launching platform probes. */
getCachedStartupHealth?: (config: Pick<OcxConfig, "codexAutoStart">) => Promise<StartupHealth>;
/**
* Persistence seam for route-level tests. Production leaves this unset and uses
* `saveConfigPreservingClaudeCode`; tests that pass an in-memory fixture config
* MUST inject a no-op/spy so the fixture can never overwrite the user's real
* OPENCODEX_HOME (incident: devlog 260730.../070).
*/
saveConfigPreservingClaudeCode?: (config: OcxConfig) => void;
/**
* Catalog seam for the Grok toggle (WP2, devlog 260803_integrations_toggle_all
* Rev 3 N2). Production leaves this unset and the route dynamic-imports the
* real one — a static import would close a cycle with management-api.ts.
* Tests stub it to orphan the fixture file mid-fetch (the r7 recheck test).
*/
fetchAllModels?: (config: OcxConfig) => Promise<CatalogModel[]>;
/**
* Writer seam for the Grok toggle: lets a test place the file in any state
* between the pre-write recheck and the write itself (the r8 post-inspection
* tests). Production leaves this unset and uses the real writer.
*/
injectGrokConfig?: typeof injectGrokConfig;
/** Desktop mutation seams keep route tests inside temporary config libraries. */
removeDesktop3pStandardPivot?: typeof removeDesktop3pStandardPivot;
writeDesktop3pConfig?: typeof writeDesktop3pConfig;
/** Read-only Windows MDM policy seam for status/apply tests. */
probeClaudeDesktopPolicy?: (
options?: ClaudeDesktopPolicyProbeOptions,
) => ClaudeDesktopPolicyState | Promise<ClaudeDesktopPolicyState>;
/**
* Runtime-state seam: the fence must name the host/port the RUNNING process
* bound (agent-settings-routes.ts:99-103 pattern), and a test must not depend
* on the developer's real runtime state file.
*/
readRuntimePort?: (pid: number) => RuntimePortState | null;
loadCursorEffortTable?: (install: CursorInstall | undefined) => CursorEffortTable | null;
clearThreadAccountMap?: () => void;
clearProviderQuotaCache?: () => void;
primeCodexPoolQuotas?: (config: OcxConfig, reason: string) => Promise<void> | void;
runStartupInstallAction?: (
action: StartupInstallAction,
options?: { repair?: boolean },
) => Promise<{ message: string }>;
/**
* Native-main profile persistence seam for server-boundary tests. Production
* leaves this unset, so the route creates its normal NativeProfileManager.
*/
/**
* Codex app-server restart seam (devlog/_fin/260815_gui_codex_restart).
* Grouped rather than three separate fields: the route is an adapter over one
* service, and a route test that could not stub it would really terminate the
* developer's own Codex app-servers.
*/
codexRestartService?: {
readState: typeof readCodexAppServerState;
performRestart: typeof performCodexRestart;
};
nativeProfileApi?: NativeProfileApiDeps;
/**
* Log Guard mutation seam. Production leaves this unset and therefore uses the
* owner-verified process enumerator, trusted L namespace and real config store.
* Route tests inject all three so they cannot depend on local Codex processes
* or create lock/config state outside the fixture.
*/
codexLogGuardProtectionDeps?: CodexLogGuardProtectionDeps;
/**
* Log Guard maintenance seam. Production reuses the same fail-closed process
* enumerator and L namespace as Protect; route tests keep all maintenance
* state inside their temporary Codex home.
*/
codexLogGuardMaintenanceDeps?: CodexLogGuardMaintenanceDeps;
/**
* Prompt-layer path seam. Production leaves this unset and
* `src/codex/prompt-layers.ts` resolves the real CODEX_HOME. A route test
* that could not inject paths would read AND WRITE the developer's live
* ~/.codex/config.toml — the same class of incident
* `saveConfigPreservingClaudeCode` above exists to prevent.
*/
codexPromptPaths?: CodexPromptPaths;
/** Link seams are getters so the optional listener and supervisor are singletons. */
linkSupervisor?: () => LinkSupervisor;
linkListener?: () => Pick<LinkListenerLifecycle<unknown>, "ensureStarted" | "status" | "close" | "onAuthenticatedCatalog">;
readLinkStore?: () => LinkStore;
writeLinkStore?: (store: LinkStore) => void;
linkKnownHostsPath?: () => string;
sshRunner?: SshRunner;
issueApiKey?: (config: OcxConfig, name: string) => IssuedApiKey;
revokeApiKey?: (config: OcxConfig, id: string) => boolean;
loadLinkCandidates?: () => Array<{ alias: string; source: "ssh_config" | "tailscale" }>;
/** The port this runtime listens on; a join is refused unless it is the configured port. */
liveListenPort?: () => number | undefined;
now?: () => number;
}
export interface ManagementContext {
req: Request;
url: URL;
config: OcxConfig;
deps: ManagementApiDeps;
/** Installed package version projected through bounded system identity routes. */
version: string;
/**
* Which credential authorized this request, resolved by the auth gate before
* dispatch. Routes that spend the USER's identity (not just the proxy's) must
* branch on this instead of on request headers: the admin token is readable by
* anything running as the user, so a token holder can forge any header a route
* might otherwise treat as browser evidence. Undefined only in direct-dispatch
* tests, which are treated as the untrusted `admin-token` case.
*/
principal?: ManagementPrincipal;
/** Narrow current-session revocation seam; contains neither the token nor session map. */
sessionControl?: ManagementSessionControl;
/** Whether the request arrived through a trusted loopback ingress. */
trustedLoopbackIngress: boolean;
/** The issuance mode of the session, when the principal is a GUI session. */
guiSessionIssuance: import("../gui-session").GuiSessionIssuance | null;
convergeCodexCatalog: () => Promise<CatalogDisposition>;
syncClaudeAgentDefsBestEffort: () => Promise<void>;
}