@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
text/typescript
/**
* 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);
},
};
}