@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
270 lines (258 loc) • 12.8 kB
text/typescript
/**
* Execute ONE advisor consultation through the proxy's own /v1/chat/completions on loopback.
*
* Same execution shape as the vision sidecar's routed describe (src/vision/routed-describe.ts):
* the loopback call re-enters the normal data plane, so model resolution, provider auth, effort
* mapping and usage accounting are the ROUTING AUTHORITY's job — the advisor never builds its own
* router and never touches provider credentials. Any model string the router accepts works here:
* a bare native model, an explicit "provider/model", or an account-qualified native model.
*
* Recursion fence: the request carries `x-opencodex-advisor-internal` set to this process's
* capability. The Chat surface checks that value before its bridge rebuilds headers and carries
* the fact into handleResponses as `advisorInternal`. A marked request never plans an advisor
* consultation (depth cap 1 — the same structure as the vision describe fence). The capability
* is not a literal and is not forwarded upstream.
*
* Failure contract: never throws. A failed consultation returns `ok: false` plus a redacted,
* bounded error string; the worker keeps going (fail-open) either with an explicit
* unavailable context or with nothing, depending on the trigger.
*/
import type { OcxConfig } from "../types";
import { localInferenceDestination, selfFetchAdmissionToken, type LocalInferenceDestination } from "../lib/local-destinations";
import { signalWithTimeout, cancelBodyOnAbort } from "../lib/abort";
import { sidecarEnter } from "../lib/sidecar-tracker";
import {
ADVISOR_INTERNAL_CAPABILITY_HEADER,
internalCallCapability,
} from "../lib/local-internal-call-capability";
import { configuredPort } from "../server/auth-cors";
import { readAdvisorReasoning } from "../server/inference/advisor-diagnostics";
import {
ADVISOR_SYSTEM_INSTRUCTION,
ADVISOR_QUESTION_ONLY_INSTRUCTION,
buildAdvisorUserPrompt,
type AdvisorContextInput,
} from "./context";
import {
ADVISOR_ADMISSION_SCOPE_HEADER,
AdvisorAdmissionScopeEncodedBoundExceeded,
encodeAdvisorAdmissionScope,
ADVISOR_ADMISSION_POLICY_HEADER,
registerAdvisorAdmissionPolicy,
} from "../server/advisor-admission-scope";
import type { AdmissionModelScope } from "../server/admission-model-scope";
import type { CapturedAdmissionPolicy } from "../types/admission-policy";
import { captureAdmissionPolicy } from "../server/capture-admission-policy";
/**
* The header the advisor presents on its own loopback request. Its VALUE is this process's
* internal-call capability — never a literal, and never trusted from an inbound caller.
*/
export { ADVISOR_INTERNAL_CAPABILITY_HEADER as ADVISOR_INTERNAL_HEADER } from "../lib/local-internal-call-capability";
/** Bound the loopback JSON response; advice is prose, not data dumps. */
const MAX_ADVISOR_RESPONSE_BYTES = 4 * 1024 * 1024;
/** Advice length cap handed to the worker. */
const MAX_ADVICE_CHARS = 16_000;
export interface AdvisorConsultationResult {
ok: boolean;
/** Advisor prose when ok; empty string otherwise. */
advice: string;
advisorModel: string;
/** True when the caller aborted the request — not a provider failure (no cooldown). */
cancelled?: boolean;
/** Redacted, bounded failure description when not ok. */
error?: string;
/** Loopback round-trip duration (ms), for logs. */
durationMs: number;
/** Token usage reported by the chat completion, when the adapter surfaced it. */
usage?: { inputTokens?: number; outputTokens?: number; totalTokens?: number };
effectiveEffort?: string | null;
}
export function advisorDestinationOrigin(
config: Pick<OcxConfig, "port" | "hostname" | "unauthenticatedLoopbackListener">,
): string {
return advisorDestination(config).origin;
}
function advisorDestination(
config: Pick<OcxConfig, "port" | "hostname" | "unauthenticatedLoopbackListener">,
): LocalInferenceDestination {
// Same port resolution rule as the vision sidecar: config.port can be 0 (ephemeral bind, tests)
// or stale after a live port override, so prefer the recorded actual bind port when present.
const port = config.port && config.port > 0
? config.port
: Number(configuredPort()) || 10_100;
return localInferenceDestination(config, port);
}
function extractContent(payload: unknown): string | undefined {
if (!payload || typeof payload !== "object") return undefined;
const choices = (payload as { choices?: unknown }).choices;
if (!Array.isArray(choices) || choices.length === 0) return undefined;
const message = (choices[0] as { message?: unknown })?.message;
if (!message || typeof message !== "object") return undefined;
const content = (message as { content?: unknown }).content;
if (typeof content === "string" && content.trim().length > 0) return content;
if (Array.isArray(content)) {
const joined = content
.map(part => (part && typeof part === "object" && typeof (part as { text?: unknown }).text === "string"
? (part as { text: string }).text
: ""))
.join("");
if (joined.trim().length > 0) return joined;
}
return undefined;
}
function extractUsage(payload: unknown): AdvisorConsultationResult["usage"] {
if (!payload || typeof payload !== "object") return undefined;
const usage = (payload as { usage?: unknown }).usage;
if (!usage || typeof usage !== "object") return undefined;
const num = (value: unknown): number | undefined => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
const inputTokens = num((usage as { prompt_tokens?: unknown }).prompt_tokens);
const outputTokens = num((usage as { completion_tokens?: unknown }).completion_tokens);
const totalTokens = num((usage as { total_tokens?: unknown }).total_tokens);
if (inputTokens === undefined && outputTokens === undefined && totalTokens === undefined) return undefined;
return { ...(inputTokens !== undefined ? { inputTokens } : {}), ...(outputTokens !== undefined ? { outputTokens } : {}), ...(totalTokens !== undefined ? { totalTokens } : {}) };
}
/**
* Base URL seam for tests; production always self-fetches the resolved local destination.
* The advisor is an internal caller: no credential material rides the override path in tests.
*/
export function advisorBaseUrl(
config: Pick<OcxConfig, "port" | "hostname" | "unauthenticatedLoopbackListener">,
): string {
return advisorDestinationOrigin(config);
}
export async function consultAdvisor(
input: AdvisorContextInput,
config: Pick<OcxConfig, "port" | "hostname" | "apiKeys" | "unauthenticatedLoopbackListener">,
effort: string,
timeoutMs: number,
abortSignal?: AbortSignal,
baseUrlOverride?: string,
admissionScope?: AdmissionModelScope,
admissionPolicy?: CapturedAdmissionPolicy,
): Promise<AdvisorConsultationResult> {
const t0 = Date.now();
// A low-level guard as well as the plan check: never fall back to task context or pay for an empty question.
if (input.contextMode === "question-only" && !input.question?.trim()) {
return {
ok: false, advice: "", advisorModel: input.advisorModel, durationMs: 0,
error: "A non-empty question is required in question-only mode; no consultation sent.",
};
}
const headers: Record<string, string> = {
"Content-Type": "application/json",
[ADVISOR_INTERNAL_CAPABILITY_HEADER]: internalCallCapability(),
};
// Admission ladder identical to the vision sidecar: env token || service token file || first
// configured API key, sent as `x-opencodex-api-key` — never Authorization. A destination that
// requires no admission gets only a credential this data plane recognizes (#7894).
const admission = selfFetchAdmissionToken(config, advisorDestination(config));
if (admission) headers["x-opencodex-api-key"] = admission;
// Keep the bounded scope envelope for transport validation; the process-local policy
// registration below owns the complete snapshot. The receiver also enforces host limits.
try {
headers[ADVISOR_ADMISSION_SCOPE_HEADER] = encodeAdvisorAdmissionScope(admissionScope ?? { providers: [], models: [] });
} catch (error) {
if (error instanceof AdvisorAdmissionScopeEncodedBoundExceeded) {
// Controlled failure before fetch: an over-bound scope must never reach the peer —
// it would be rejected mid-request — and must never be narrowed silently either.
return { ok: false, advice: "", advisorModel: input.advisorModel, error: error.message, durationMs: Date.now() - t0 };
}
throw error;
}
const requestBody = {
model: input.advisorModel,
stream: false,
reasoning_effort: effort,
messages: [
{ role: "system", content: input.contextMode === "question-only" ? ADVISOR_QUESTION_ONLY_INSTRUCTION : ADVISOR_SYSTEM_INSTRUCTION },
{ role: "user", content: buildAdvisorUserPrompt(input) },
],
};
const linkedSignal = signalWithTimeout(timeoutMs, abortSignal);
const sidecarExit = sidecarEnter("advisor");
if (abortSignal?.aborted) {
sidecarExit();
linkedSignal.cleanup();
return { ok: false, cancelled: true, advice: "", advisorModel: input.advisorModel, error: "advisor cancelled before dispatch", durationMs: Date.now() - t0 };
}
let policyRegistration: ReturnType<typeof registerAdvisorAdmissionPolicy> | undefined;
try {
policyRegistration = registerAdvisorAdmissionPolicy(admissionPolicy ?? captureAdmissionPolicy(config, undefined, admissionScope), linkedSignal.signal);
headers[ADVISOR_ADMISSION_POLICY_HEADER] = policyRegistration.token;
const res = await fetch(`${baseUrlOverride ?? advisorBaseUrl(config)}/v1/chat/completions`, {
method: "POST",
headers,
body: JSON.stringify(requestBody),
signal: linkedSignal.signal,
redirect: "manual",
proxy: false,
});
const detachBodyGuard = cancelBodyOnAbort(res.body, linkedSignal.signal);
try {
// Bounded read: count bytes per chunk and cancel the reader the moment the bound is
// exceeded, instead of materializing the full body before the length check.
let raw = "";
let totalBytes = 0;
const reader = res.body?.getReader();
if (reader) {
const decoder = new TextDecoder();
for (;;) {
const { done, value } = await reader.read();
if (done) break;
totalBytes += value.byteLength;
if (totalBytes > MAX_ADVISOR_RESPONSE_BYTES) {
try { await reader.cancel(); } catch { /* body already closing */ }
return { ok: false, advice: "", advisorModel: input.advisorModel, error: "advisor response exceeded byte bound", durationMs: Date.now() - t0 };
}
raw += decoder.decode(value, { stream: true });
}
raw += decoder.decode();
}
const durationMs = Date.now() - t0;
if (!res.ok) {
// Status only. Upstream bodies can echo the consultation prompt; they are not logged
// and not handed to the worker. display-safe body text is intentionally not copied here.
return {
ok: false, advice: "", advisorModel: input.advisorModel,
error: `advisor HTTP ${res.status}`,
durationMs,
};
}
let payload: unknown;
try { payload = JSON.parse(raw); } catch {
return { ok: false, advice: "", advisorModel: input.advisorModel, error: "advisor returned non-JSON", durationMs };
}
const content = extractContent(payload);
if (!content) {
return { ok: false, advice: "", advisorModel: input.advisorModel, error: "advisor returned no text", durationMs };
}
return {
ok: true,
advice: content.length > MAX_ADVICE_CHARS ? `${content.slice(0, MAX_ADVICE_CHARS)}… [truncated]` : content,
advisorModel: input.advisorModel,
durationMs,
effectiveEffort: readAdvisorReasoning(res.headers),
...(extractUsage(payload) ? { usage: extractUsage(payload) } : {}),
};
} finally {
detachBodyGuard();
}
} catch (e) {
const durationMs = Date.now() - t0;
// Client cancellation is not a provider failure: the caller aborted (linked signal), so the
// task must stay eligible for a later attempt rather than entering a failure cooldown.
if (abortSignal?.aborted) {
return { ok: false, cancelled: true, advice: "", advisorModel: input.advisorModel, error: "advisor cancelled by the caller", durationMs };
}
const kind = e instanceof Error && e.name === "TimeoutError" ? "timeout" : "connect_error";
return {
ok: false, advice: "", advisorModel: input.advisorModel,
error: `advisor ${kind}`,
durationMs,
};
} finally {
policyRegistration?.release();
sidecarExit();
linkedSignal.cleanup();
}
}