UNPKG

@bitkyc08/opencodex

Version:

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

393 lines (374 loc) • 18.6 kB
/** * The advisor request plan: what the optional subsystem registers into the core Responses path. * * Created PER REQUEST through the activated factory called by the sidecar planner — never * at module load and never globally. All mutable state is request-scoped except the bounded * task-scoped preflight ledger (src/advisor/state.ts). * * Responsibilities: * - decide whether the advisor applies to this request (settings + capability of the path); * - preflight: one automatic consultation ATTEMPT per task when the orientation evidence exists, * claimed atomically in the ledger and injected as user-role advisory data; * - manual: back the synthetic `advisor` tool guard with real consultations through the routing * authority (loopback chat completion); * - observability: one structured log line per consultation — proof that the advisor actually * ran (worker model, advisor model, trigger, duration, status, usage). * * Preflight injection transport: the runtime-owned instruction is fixed developer policy; * all Advisor-generated bytes are a separate JSON-quoted user-role advisory message. Manual * consultations remain paired tool results. No automatic path fabricates a tool call or * places Advisor output in developer/system content. User-role advice can still contain * hostile recommendations; the fixed policy tells the worker how to interpret that data. */ import type { OcxConfig, OcxParsedRequest, OcxTool } from "../types"; import type { AdvisorPlan, AdvisorConsultOutcome } from "../server/responses/advisor-slot"; import { createAdvisorGuard, MAX_ADVISOR_CONSULTATIONS_PER_REQUEST } from "../server/responses/advisor-slot"; import { resolveAdvisorSettings, type AdvisorContextMode, type AdvisorPolicy } from "./settings"; import { consultAdvisor } from "./consult"; import { buildAdvisorTool } from "./synthetic-tool"; import { sanitizeLogMetadataString } from "../lib/redact"; import { advisorLedgerKey, createAdvisorPreflightLedger, hasOrientationEvidence, historyHasManualAdvisorResult, type AdvisorPreflightLedger, } from "./state"; import { formatAdvisorAdvice, advisorPreflightMessages, formatAdvisorUnavailable } from "./context"; import { advisorActivityStore, type AdvisorActivityStore, type AdvisorTrigger } from "./activity"; import { advisorPlanRootConfig } from "../server/responses/advisor-plan-slot"; import { createAdvisorTaskBudget, type AdvisorTaskBudget } from "./budget"; import { collectAdvisorRepairEvidence, type AdvisorRepairEvidence } from "./evidence"; import type { AdmissionModelScope } from "../server/admission-model-scope"; /** * Process-local task ledger. Bounded (entries + per-state TTL) in src/advisor/state.ts; one * instance per process so the claim is atomic across concurrent requests. Not durable by design * — see the documented restart limitation. */ const sharedPreflightLedger = createAdvisorPreflightLedger(); export const ADVISOR_SHARED_LEDGER = sharedPreflightLedger; export interface AdvisorRuntimeDeps { config: Pick<OcxConfig, "advisor" | "port" | "hostname" | "apiKeys" | "unauthenticatedLoopbackListener">; /** Routed worker identity for logs and the advisor payload, e.g. "deepseek-chat (provider deepseek)". */ workerIdentity: string; workerModelId: string; admissionScope?: AdmissionModelScope; admissionPolicy?: import("../types/admission-policy").CapturedAdmissionPolicy; abortSignal?: AbortSignal; /** Test seam; production always self-fetches the resolved local destination. */ baseUrlOverride?: string; /** Test seam; production uses the process-wide ledger. */ ledger?: AdvisorPreflightLedger; budget?: AdvisorTaskBudget; activities?: AdvisorActivityStore; /** Deterministic clock seam for the ledger's TTL/cooldown arithmetic (tests only). */ now?: () => number; /** * Test seam: runs after a preflight claim is taken and before the consultation * dispatch, so a test can revoke consent in the claim-to-outbound window. */ afterPreflightClaim?: () => void; } export interface AdvisorRuntimePlan extends AdvisorPlan { readonly policy: AdvisorPolicy; readonly toolEnabled: boolean; readonly tool: import("../types").OcxTool; /** * The automatic preflight pass. Returns true when advice was injected. A cancelled * consultation injects nothing and leaves the task eligible for a later attempt. */ preflightInject(parsed: OcxParsedRequest): Promise<boolean>; /** Attach the stream guard for the synthetic tool to the parsed request. */ attachGuard(parsed: OcxParsedRequest): void; } export function createAdvisorRuntimePlan(deps: AdvisorRuntimeDeps): AdvisorRuntimePlan | null { const initial = resolveAdvisorSettings(deps.config); // A model is required before the synthetic tool exists. Consent is checked at every // consultation against the live config, so an enabled advisor without current consent can // still refuse a manual call in-band without sending task context. Disabled, or enabled // with no model, stays off the path. if (!initial.enabled || initial.model.trim() === "") return null; const ledger = deps.ledger ?? sharedPreflightLedger; const now = deps.now ?? (() => Date.now()); const budget = deps.budget ?? createAdvisorTaskBudget(); // Identity-scoped state must key on the LIVE config: `GET /api/advisor/activity` reads the store // of the management context's own config, so a request-scoped view (the Claude replay config) // would record consultations the dashboard and CLI never see. const activities = deps.activities ?? advisorActivityStore(advisorPlanRootConfig(deps.config)); // Management PUT mutates this same config object (`config.advisor = ...`). Re-resolving // at dispatch is what makes a mid-request consent revocation stop outbound transfer. const liveSettings = () => resolveAdvisorSettings(deps.config); // Request-scoped state: born here, dies with the request. Never global. const fingerprints = new Set<string>(); let preflightUsed = false; let consultations = 0; // Capture before automatic user-role advisory injection. Continuations belong to this // original task; an injected advisory must never mint another spending allowance. let identity: { preflight?: string; budget?: string } | undefined; const identify = (parsed: OcxParsedRequest) => identity ??= { preflight: advisorLedgerKey(parsed, deps.workerModelId), budget: advisorLedgerKey(parsed, ""), }; const taskKey = (parsed: OcxParsedRequest): string | undefined => identify(parsed).preflight; const logConsultation = ( trigger: AdvisorTrigger, outcome: { ok: boolean; cancelled?: boolean; durationMs: number; error?: string; usage?: { inputTokens?: number; outputTokens?: number; totalTokens?: number } }, advisorModel: string, ): void => { const usage = outcome.usage ? ` usage=in=${outcome.usage.inputTokens ?? "?"} out=${outcome.usage.outputTokens ?? "?"}` : ""; const status = outcome.ok ? "ok" : outcome.cancelled ? "cancelled" : "failed"; const errorNote = outcome.ok || outcome.cancelled ? "" : ` error=${sanitizeLogMetadataString(outcome.error ?? "unknown", 160) ?? "unknown"}`; // One structured line per consultation: model ids, timing, and a bounded status. No prompt, // no tool output, no capability. console.warn( `[advisor] consultation ${status} trigger=${trigger} worker=${deps.workerModelId}` + ` advisor=${advisorModel} durationMs=${outcome.durationMs}${usage}${errorNote}`, ); }; const runConsultation = async ( parsed: OcxParsedRequest, reason: AdvisorTrigger, question: string | undefined, evidence?: AdvisorRepairEvidence, abortSignal?: AbortSignal, ): Promise<AdvisorConsultOutcome> => { const consultationSignal = abortSignal && deps.abortSignal ? AbortSignal.any([deps.abortSignal, abortSignal]) : abortSignal ?? deps.abortSignal; const current = liveSettings(); if (!current.enabled || current.model.trim() === "") { return { ok: false, isError: true, blocked: "settings", content: formatAdvisorUnavailable( reason === "manual" ? "manual" : "preflight", "advisor is not configured", ), }; } // Consent is operator config. Task text, the worker, and the advisor cannot grant it. // The live object is re-read here so a revocation after plan creation still blocks // outbound transfer. No fingerprint, no ledger write, no fetch. if (current.contextSharingConsent === null) { console.warn( `[advisor] consultation blocked trigger=${reason} reason=advisor_context_sharing_consent_required`, ); return { ok: false, isError: true, blocked: "consent", content: formatAdvisorUnavailable( "consent", "advisor_context_sharing_consent_required", ), }; } if (current.contextMode === "question-only") { // A mode change after an automatic claim is operator policy, not a provider failure. if (reason !== "manual") { return { ok: false, isError: true, blocked: "settings", content: "" }; } if (!question?.trim()) { return { ok: false, isError: true, content: formatAdvisorUnavailable("manual", "Question-only mode requires a self-contained question. Include the necessary background in question; no consultation sent."), }; } } // Same-consultation dedup within this request: identical trigger + focus returns a // non-advice outcome instead of a second expert call. const fingerprint = `${reason}|${question ?? ""}|${evidence?.id ?? ""}`; let result; if (fingerprints.has(fingerprint)) { result = { ok: false, advice: "", advisorModel: current.model, error: "duplicate consultation request (already consulted with this focus in this request)", durationMs: 0, }; return { ok: false, isError: true, content: formatAdvisorUnavailable(reason === "manual" ? "manual" : "preflight", result.error), }; } if (consultationSignal?.aborted) return { ok: false, isError: true, cancelled: true, content: "" }; const budgetKey = identify(parsed).budget; const requestCapped = consultations >= MAX_ADVISOR_CONSULTATIONS_PER_REQUEST; if (requestCapped || (current.policy === "adaptive" && budgetKey && !budget.reserve(budgetKey, current.maxConsultationsPerTask, now()).ok)) { const id = activities.start({ trigger: reason, workerModel: deps.workerModelId, advisorModel: current.model, requestedEffort: current.effort }, now()); const blocked = requestCapped ? "limit" : "budget"; activities.finish(id, { status: "blocked", durationMs: 0, blockReason: blocked }); return { ok: false, isError: true, blocked, content: formatAdvisorUnavailable(blocked, requestCapped ? "per-request consultation limit reached; no consultation sent" : "task budget exhausted or unavailable; no consultation sent") }; } consultations += 1; fingerprints.add(fingerprint); const startedAt = now(); const activityId = activities.start({ trigger: reason, workerModel: deps.workerModelId, advisorModel: current.model, requestedEffort: current.effort }, startedAt); try { result = await consultAdvisor( { parsed, workerIdentity: deps.workerIdentity, advisorModel: current.model, reason, contextMode: current.contextMode, ...(evidence ? { evidence } : {}), ...(question !== undefined ? { question } : {}), }, deps.config, current.effort, current.timeoutMs, consultationSignal, deps.baseUrlOverride, deps.admissionScope, deps.admissionPolicy, ); } catch (error) { activities.finish(activityId, { status: "failed", durationMs: Math.max(0, now() - startedAt) }); throw error; } activities.finish(activityId, { status: result.ok ? "ok" : result.cancelled ? "cancelled" : "failed", durationMs: result.durationMs, effectiveEffort: result.effectiveEffort ?? null, ...(result.usage ? { usage: result.usage } : {}), }); logConsultation(reason, result, current.model); if (result.ok) { // A genuine result suppresses further automatic consultation for the task. Manual success // settles it too: a task the worker already had advised does not need a preflight attempt. if (reason === "manual") { const key = taskKey(parsed); // A manual consultation owns no preflight claim; this records the FACT that the task was // advised, which is true whichever consultation produced the advice. if (key) ledger.markAdvised(key, now()); } return { ok: true, isError: false, content: formatAdvisorAdvice({ advisorModel: result.advisorModel, reason, advice: result.advice, channel: reason === "manual" ? "manual" : "preflight", }), }; } return { ok: false, isError: true, ...(result.cancelled ? { cancelled: true } : {}), content: formatAdvisorUnavailable(reason === "manual" ? "manual" : "preflight", result.error ?? "unavailable"), }; }; const preflightInject = async (parsed: OcxParsedRequest): Promise<boolean> => { const task = identify(parsed); const current = liveSettings(); if (current.contextMode === "question-only" || current.policy === "manual" || preflightUsed || deps.abortSignal?.aborted) return false; // No consent, disabled, or no model: do not claim, do not inject, do not send task context. if (!current.enabled || current.model.trim() === "" || current.contextSharingConsent === null) return false; // A genuine MANUAL consultation already advised this task (verifiable tool-result // provenance), or the task has no orientation evidence yet: skip. // Adaptive automation needs a stable identity for its durable task budget. Legacy // preflight keeps its documented identity-less, request-scoped behavior. if (current.policy === "adaptive" && !task.budget) return false; const evidence = current.policy === "adaptive" ? collectAdvisorRepairEvidence(parsed) : undefined; const reason = evidence ? "repair_failure" : "preflight"; if (!evidence && (historyHasManualAdvisorResult(parsed) || !hasOrientationEvidence(parsed))) return false; // Atomic claim. A client with a stable conversation identity participates in the // process-global ledger, so concurrent requests for one task consult at most once and a // settled task is not re-consulted. A client with NO stable identity stays out of the // ledger on purpose: request-scoped dedup plus genuine in-history provenance are the only // suppression it gets — fail-open, so two independent identity-less conversations can never // suppress each other through a shared guess. const baseKey = taskKey(parsed); const key = evidence && baseKey ? `${baseKey}:repair:${evidence.id}` : baseKey; let claimToken: string | undefined; if (key) { const claim = ledger.claim(key, now()); if (claim.state !== "claimed") return false; claimToken = claim.token; } preflightUsed = true; deps.afterPreflightClaim?.(); let outcome: AdvisorConsultOutcome; try { outcome = await runConsultation(parsed, reason, undefined, evidence); } catch (error) { if (key && claimToken) ledger.fail(key, claimToken, now()); console.warn(`[advisor] consultation failed trigger=${reason} worker=${deps.workerModelId} error=plan_threw`); parsed.context.messages = [ ...parsed.context.messages, { role: "user", content: "An automatic advisor consultation could not be completed. Continue with your own judgment.", timestamp: Date.now(), }, ]; void error; return false; } if (outcome.blocked) { // Operator revoked consent (or disabled the sidecar) after the claim: not a provider // failure. Release so the task is not put on cooldown and nothing is injected. if (key && claimToken) ledger.release(key, claimToken, now()); return false; } if (outcome.ok) { if (key && claimToken) ledger.complete(key, claimToken, now()); } else if (outcome.cancelled) { // Client cancellation is not a provider failure: no cooldown, the task may retry later. if (key && claimToken) ledger.release(key, claimToken, now()); // Nothing to inject — the caller is gone or aborting; do not add noise to a live turn. return false; } else { if (key && claimToken) ledger.fail(key, claimToken, now()); } parsed.context.messages = [ ...parsed.context.messages, ...advisorPreflightMessages(outcome.content), ]; return outcome.ok; }; const plan: AdvisorPlan = { shouldCountManualConsultation: question => liveSettings().contextMode !== "question-only" || Boolean(question?.trim()), consult: (parsed, reason, question, abortSignal) => runConsultation(parsed, reason, question, undefined, abortSignal), // The guard's own failure/limit text goes through the same runtime-owned, marker-neutralized // formatter so no guard path can emit text that looks like a genuine advice wrapper. formatUnavailable: (kind, error) => formatAdvisorUnavailable(kind, error), }; // Sidecar paths compare the advisor tool by reference, so each context mode keeps one object. const advisorTools = new Map<AdvisorContextMode, OcxTool>(); const advisorTool = (): OcxTool => { const mode = liveSettings().contextMode; let tool = advisorTools.get(mode); if (!tool) advisorTools.set(mode, tool = buildAdvisorTool(mode)); return tool; }; return { policy: initial.policy, // The synthetic tool is only safe where the guard can intercept: run-turn adapters own their // own loops, so they get preflight support but never the tool (documented limitation). toolEnabled: initial.enabled, get tool() { return advisorTool(); }, shouldCountManualConsultation: plan.shouldCountManualConsultation, consult: plan.consult, formatUnavailable: plan.formatUnavailable, preflightInject, attachGuard: parsed => { parsed._advisorGuard = createAdvisorGuard(plan); }, }; }