UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

375 lines (349 loc) • 19.4 kB
import type { LinkStore } from "./store"; import type { LinkTunnelStatus } from "./supervisor"; import type { TunnelState } from "./tunnel-state"; import { readCompensation, type CompensationStore } from "./compensation"; import { EMPTY_LINK_CHILD_PARITY, type LinkChildParity } from "./child-parity"; import { linkPeerStatus, type LinkLocalPeer, type LinkPeerStatus } from "./compatibility"; import type { LinkPeerEntry } from "./peer-report"; import type { OcxClientConnectionConfig } from "../types"; import { isLinkIdle, LINK_DELIVERY_DEGRADED_THRESHOLD, type LinkActivitySnapshot } from "./child-activity"; import { catalogVerdict, type CatalogPull, type CatalogRevision, type CatalogState } from "./child-catalog-freshness"; import type { ChildObservation, ChildOp, ChildOperationSummary } from "./child-observations"; import type { InstallKind, UpdateRoute } from "./child-update-contract"; import type { LinkHoldsSummary } from "./ws-activity-holds"; import { compareStrictSemver, parseStrictSemver } from "../lib/strict-semver"; import type { LinkTrafficCounters } from "./traffic"; export type LinkWireState = "connecting" | "connected" | "reconnecting" | "failed" | "idle"; export interface LinkStatusDto { role: "standalone" | "home" | "child"; listener: { state: "off" | "listening" | "failed"; port: number | null }; links: Array<LinkChildParity & { id: string; alias: string; direction: "hub-initiated" | "client-initiated"; state: LinkWireState; since: string; reason: string | null; tunnelPort: number; childKind?: "full" | "ephemeral"; /** Exclusive links only (structure/remote-link.md, "Explicit route"); absent on every other row. */ exclusive?: true; explicitRoute?: import("./explicit-route").ExplicitRoute; /** Home only: what the link carried from this Child, and the compatibility verdict. */ peer?: LinkPeerStatus; /** Home-initiated links on request (`?diagnostics=1`): retry progress and the last failure. */ tunnel?: LinkTunnelDiagnostics; /** Home-initiated links on request (`?relayHealth=1`): delivery evidence for the current tunnel. */ relayHealth?: LinkRelayHealth; /** Home rows on request (`?children=1`): versions, update route, catalog freshness, activity and operations. */ child?: LinkChildOpsStatus; /** Links with several routes, on request (`?routes=1`): each route's rest and last outcome. */ routes?: LinkRouteWire[]; /** The route the proven tunnel uses and when it was proven; null while none is proven. */ route?: { name: string; index: number; since: string } | null; /** Why the link cannot run its routes right now, or null. */ routeBlocked?: "ssh_client_unsupported" | "stop_unconfirmed" | null; /** Rows on request (`?transport=1`): the live link WebSocket counters (design T4 section 9.3). */ ws?: LinkWsStatus; /** On request (`?traffic=1`): body bytes this machine relayed or served for the link since `since`. */ traffic?: LinkTrafficCounters; }>; child: null | { alias: string; state: LinkWireState; since: string; reason: string | null; }; /** This build's version and link protocol, the side every `peer` verdict compares against. */ local?: LinkLocalPeer; } /** * The Home's account of one `-R` tunnel: ssh attempts since it was last connected, when the next * one is due (null while one runs or none is scheduled), the last state change and the last * failure. `cause` is a fixed word from `tunnel-history.ts`, never ssh output. */ export interface LinkTunnelDiagnostics { attempt: number; nextRetryAt: string | null; lastTransition: { from: LinkWireState; to: LinkWireState; at: string; cause: string | null } | null; lastFailure: { cause: string; at: string } | null; } export const LINK_RELAY_DEGRADED_GUIDANCE = "Run ocx link check --link-id <id>. If requests keep dropping, run ocx link reconnect --link-id <id> when the link is idle."; export interface LinkRelayHealth { relayAuthentication: "observed" | "unknown"; delivery: "degraded" | "observed" | "unknown"; inferenceReadiness: "unknown"; recentInterruptions: number; guidance?: typeof LINK_RELAY_DEGRADED_GUIDANCE; } /** No probe or routing decision. Only authenticated HTTP model delivery seen on the current Home tunnel. */ export function attachLinkRelayHealth( dto: LinkStatusDto, generationOf: (linkId: string) => string | undefined, activityOf: (linkId: string) => LinkActivitySnapshot | undefined, ): void { if (dto.role !== "home") return; for (const link of dto.links) { if (link.direction !== "hub-initiated") continue; const generation = link.state === "connected" ? generationOf(link.id) : undefined; const snapshot = generation === undefined ? undefined : activityOf(link.id)?.httpDelivery; const evidence = snapshot?.generation === generation ? snapshot : undefined; const recentInterruptions = evidence?.recentInterruptions ?? 0; const degraded = recentInterruptions >= LINK_DELIVERY_DEGRADED_THRESHOLD; link.relayHealth = { relayAuthentication: evidence?.recentAuthentication ? "observed" : "unknown", delivery: degraded ? "degraded" : evidence?.recentSettled ? "observed" : "unknown", inferenceReadiness: "unknown", recentInterruptions, ...(degraded ? { guidance: LINK_RELAY_DEGRADED_GUIDANCE } : {}), }; } } function iso(at: number): string { return new Date(at).toISOString(); } /** One route of a multi-route link on the wire. The class is a fixed word, never ssh output. */ export interface LinkRouteWire { name: string; eligibleAt: string | null; lastOutcome: { class: "transient" | "readiness" | "grant_unobserved" | "forward" | "auth" | "hostkey"; at: string } | null; } /** * Add route fields to each link the supervisor runs with several routes. Opt-in like `tunnel`: * an older `ocx link status` validates rows key by key. Route names are SSH host aliases; this * document is served only to the Home's admin token or dashboard session, never over the relay. */ export function attachLinkRoutes(dto: LinkStatusDto, supervisorStates: readonly LinkTunnelStatus[]): LinkStatusDto { const byId = new Map(supervisorStates.map(status => [status.linkId, status])); for (const link of dto.links) { const status = byId.get(link.id); if (!status || status.direction !== "hub-initiated" || !status.routes) continue; const { routes, route, blocked } = status.routes; link.routes = routes.map(entry => ({ name: entry.name, eligibleAt: entry.eligibleAt === null ? null : iso(entry.eligibleAt), lastOutcome: entry.lastOutcome ? { class: entry.lastOutcome.class, at: iso(entry.lastOutcome.at) } : null, })); link.route = route ? { name: route.name, index: route.index, since: iso(route.since) } : null; link.routeBlocked = blocked; } return dto; } /** Why the Home refused a link WebSocket upgrade, as counted (design T4 section 9.3). */ export type LinkWsRefusal = "aborted" | "draining" | "unauthorized" | "unavailable" | "memory" | "cap" | "failed"; /** Why a link WebSocket closed: the Home's own fence, or the peer's close code. */ export type LinkWsCloseReason = "revoked" | "disabled" | "idle" | "age" | "client" | "dropped" | "other"; /** In memory, display only, reset at restart. */ export interface LinkWsCounters { open: number; upgrades: number; refused: Partial<Record<LinkWsRefusal, number>>; closes: Partial<Record<LinkWsCloseReason, number>>; } export interface LinkWsStatus extends LinkWsCounters { holds: number } /** `?transport=1`: every row gets `ws`; a Home without counters reports zeros. Rows are the current links only. */ export function attachLinkTransport(dto: LinkStatusDto, counters: (linkId: string) => LinkWsCounters | null, holds: (linkId: string) => number): LinkStatusDto { for (const link of dto.links) { const current = counters(link.id) ?? { open: 0, upgrades: 0, refused: {}, closes: {} }; link.ws = { open: current.open, upgrades: current.upgrades, refused: { ...current.refused }, closes: { ...current.closes }, holds: holds(link.id) }; } return dto; } /** Add `tunnel` to each Home-initiated link the supervisor reports. */ export function attachLinkTunnelDiagnostics(dto: LinkStatusDto, supervisorStates: readonly LinkTunnelStatus[]): LinkStatusDto { const byId = new Map(supervisorStates.map(status => [status.linkId, status])); for (const link of dto.links) { const status = byId.get(link.id); if (!status || status.direction !== "hub-initiated") continue; const { state, history, forwardRetryAt } = status; const due = forwardRetryAt ?? ((state.kind === "failed" || state.kind === "reconnecting") && state.inFlight !== true ? state.retryAt : undefined); link.tunnel = { attempt: history?.attempt ?? 0, nextRetryAt: due === undefined ? null : iso(due), lastTransition: history?.lastTransition ? { from: history.lastTransition.from, to: history.lastTransition.to, at: iso(history.lastTransition.at), cause: history.lastTransition.cause } : null, lastFailure: history?.lastFailure ? { cause: history.lastFailure.cause, at: iso(history.lastFailure.at) } : null, }; } return dto; } /** Add `traffic` to every row (#3023). A Home counts in its hub-link listener, a Child in its link transport. */ export function attachLinkTraffic(dto: LinkStatusDto, traffic: (linkId: string) => LinkTrafficCounters): LinkStatusDto { for (const link of dto.links) link.traffic = traffic(link.id); return dto; } /** Add this build's identity and, on a Home, each Child's observed peer status. */ export function attachLinkPeers(dto: LinkStatusDto, local: LinkLocalPeer, observation: (linkId: string) => LinkPeerEntry): LinkStatusDto { if (dto.role === "home") { for (const link of dto.links) link.peer = linkPeerStatus(local, observation(link.id)); } dto.local = local; return dto; } /** One Home row's `child` block. `codex` stays null until the Child reports its Codex state (wp8). */ export interface LinkChildOpsStatus { homeVersion: string; runningVersion: string | null; installedVersion: string | null; installKind: InstallKind | null; versionSkew: "same" | "behind" | "ahead" | "unknown"; update: { route: UpdateRoute | null; reason: string | null; observedAt: string | null }; catalog: { state: CatalogState; pulledAt: number | null; homeChangedAt: number | null }; codex: null; activity: { idle: boolean; inFlight: number; lastDataEndAt: number | null }; activeJob: { jobId: string; op: ChildOp; state: "queued" | "running" } | null; lastOperation: ChildOperationSummary | null; /** Link WebSocket activity holds and their reasons (D8); present only while something holds the link. */ holds?: LinkHoldsSummary; } export interface LinkChildOpsSources { homeVersion: string; now: number; idleAfterMs: number; peerVersion(linkId: string): string | null; observation(linkId: string): ChildObservation | null; activity(linkId: string): LinkActivitySnapshot | null; catalogPull(linkId: string): CatalogPull | null; revision: CatalogRevision | null; activeJob(linkId: string): LinkChildOpsStatus["activeJob"]; /** Optional: a Home without link WebSocket holds omits the key on every row. */ holds?(linkId: string): LinkHoldsSummary | null; } function versionSkew(version: string | null, homeVersion: string): LinkChildOpsStatus["versionSkew"] { const child = parseStrictSemver(version); const home = parseStrictSemver(homeVersion); if (!child || !home) return "unknown"; const order = compareStrictSemver(child, home); return order === 0 ? "same" : order < 0 ? "behind" : "ahead"; } /** The newer of the relay's in-memory pull and the cached one. */ function latestPull(memory: CatalogPull | null, cached: ChildObservation | null): CatalogPull | null { const stored = cached?.catalogPulledAt != null && cached.catalogPulledEtag != null ? { at: cached.catalogPulledAt, etag: cached.catalogPulledEtag } : null; if (!memory) return stored; return stored && stored.at > memory.at ? stored : memory; } /** * Home rows only. Skew compares installed ?? running with homeVersion; ocx-child and unparsable versions are "unknown". * An entry observe never wrote (source "inspect" with route "none", the default a carried-only write creates) reads as * not observed. Missing activity reads busy, never idle. */ export function attachLinkChildOps(dto: LinkStatusDto, sources: LinkChildOpsSources): LinkStatusDto { if (dto.role !== "home") return dto; for (const link of dto.links) { const cached = sources.observation(link.id); const observed = cached && !(cached.source === "inspect" && cached.updateRoute === "none") ? cached : null; const runningVersion = parseStrictSemver(sources.peerVersion(link.id)) ? sources.peerVersion(link.id) : null; const installedVersion = observed?.installedVersion ?? null; const installKind = observed?.installKind ?? null; const ocxChild = installKind === "ocx-child" || link.childKind === "ephemeral"; const pull = latestPull(sources.catalogPull(link.id), cached); const snapshot = sources.activity(link.id); const held = sources.holds?.(link.id) ?? null; link.child = { homeVersion: sources.homeVersion, runningVersion, installedVersion, installKind, versionSkew: ocxChild ? "unknown" : versionSkew(installedVersion ?? runningVersion, sources.homeVersion), update: observed ? { route: observed.updateRoute, reason: observed.updateReason, observedAt: observed.observedAt } : { route: null, reason: null, observedAt: null }, catalog: { state: catalogVerdict(pull?.etag ?? null, cached?.catalogSyncedEtag ?? null, sources.revision), pulledAt: pull?.at ?? null, homeChangedAt: sources.revision?.changedAt ?? null }, codex: null, activity: snapshot ? { idle: isLinkIdle(snapshot, sources.now, sources.idleAfterMs), inFlight: snapshot.inFlight, lastDataEndAt: snapshot.lastDataEndAt } : { idle: false, inFlight: 0, lastDataEndAt: null }, activeJob: sources.activeJob(link.id), lastOperation: cached?.lastOperation ?? null, ...(held ? { holds: held } : {}), }; } return dto; } export interface ClientLinkIdentity { direction: "hub-initiated" | "client-initiated"; alias?: string } export interface LinkListenerStatusProjection { state: "off" | "listening" | "failed"; port: number | null; } export interface LinkStatusConfig { runtimeRole?: "standalone" | "hub" | "client"; client?: Pick<OcxClientConnectionConfig, "transport" | "link" | "serverUrl" | "connectedAt">; } function asWireState(state: TunnelState | "client-owned"): LinkWireState { if (state === "client-owned") return "idle"; return state.kind; } function stateDetails( record: LinkStore["links"][number], status: LinkTunnelStatus | undefined, compensation?: CompensationStore, ): { state: LinkWireState; since: string; reason: string | null } { const failure = compensation?.entries[record.id]; if (failure) return { state: "failed", since: failure.since, reason: failure.reason }; if (!status || status.state === "client-owned") { return { state: "idle", since: record.createdAt, reason: null }; } // An unsettled revoke keeps the tunnel down until it is resolved (src/link/operations-journal.ts, revokeSuspendsLink). // It comes first: resolving it is the step to take, and an orphan of that link is reaped like any other meanwhile. if (status.suspended) return { state: "failed", since: status.suspended.since, reason: "revoke_unsettled" }; if (status.orphan === "orphan-unverified") { return { state: "failed", since: record.createdAt, reason: "stale tunnel may hold the port" }; } const tunnel = status.state; if (status.routes?.blocked === "ssh_client_unsupported" && !status.routes.route) { return { state: "failed", since: new Date(tunnel.kind === "idle" ? Date.parse(record.createdAt) : tunnel.since).toISOString(), reason: "ssh_client_unsupported" }; } const reason = tunnel.kind === "failed" ? tunnel.reason : null; const since = tunnel.kind === "idle" ? record.createdAt : new Date(tunnel.since).toISOString(); return { state: asWireState(tunnel), since, reason }; } /** * 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 (including an invalid client sidecar); link code * stays free of client imports, so the caller supplies it. */ export function projectLinkStatus( store: LinkStore, supervisorStates: readonly LinkTunnelStatus[], listenerStatus: LinkListenerStatusProjection, config: LinkStatusConfig, compensation: CompensationStore = readCompensation(), clientChild: LinkStatusDto["child"] = null, identity: ClientLinkIdentity | null = null, /** The Home's view of each Child's last apply (OCX-6); every field is null without a report. */ parity: (linkId: string) => LinkChildParity = () => EMPTY_LINK_CHILD_PARITY, ): LinkStatusDto { const byId = new Map(supervisorStates.map(status => [status.linkId, status])); const links = store.links.map(record => ({ id: record.id, alias: record.alias, direction: record.direction, ...stateDetails(record, byId.get(record.id), compensation), tunnelPort: record.tunnelPort, ...(record.childKind ? { childKind: record.childKind } : {}), ...(record.exclusive ? { exclusive: true as const } : {}), ...(record.explicitRoute ? { explicitRoute: { ...record.explicitRoute } } : {}), ...parity(record.id), })); 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, ...parity(client.link.linkId), }; 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, }; }