@bitkyc08/opencodex 2.83.0 → 2.86.0

package/src/advisor/runtime.ts

@@ -0,0 +1,305 @@
+/**
+ * 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 } from "../types";
+import type { AdvisorPlan, AdvisorConsultOutcome } from "../server/responses/advisor-slot";
+import { createAdvisorGuard } from "../server/responses/advisor-slot";
+import { resolveAdvisorSettings } 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";
+
+/**
+ * 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;
+  abortSignal?: AbortSignal;
+  /** Test seam; production always self-fetches the resolved local destination. */
+  baseUrlOverride?: string;
+  /** Test seam; production uses the process-wide ledger. */
+  ledger?: AdvisorPreflightLedger;
+  /** 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: "manual" | "preflight";
+  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());
+  // 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;
+
+  const taskKey = (parsed: OcxParsedRequest): string | undefined =>
+    advisorLedgerKey(parsed, deps.workerModelId);
+
+  const logConsultation = (
+    trigger: "manual" | "preflight",
+    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: "manual" | "preflight",
+    question: string | undefined,
+  ): Promise<AdvisorConsultOutcome> => {
+    const current = liveSettings();
+    if (!current.enabled || current.model.trim() === "") {
+      return {
+        ok: false,
+        isError: true,
+        blocked: "settings",
+        content: formatAdvisorUnavailable(
+          reason === "preflight" ? "preflight" : "manual",
+          "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",
+        ),
+      };
+    }
+    // Same-consultation dedup within this request: identical trigger + focus returns a
+    // non-advice outcome instead of a second expert call.
+    const fingerprint = `${reason}|${question ?? ""}`;
+    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 === "preflight" ? "preflight" : "manual", result.error),
+      };
+    }
+    fingerprints.add(fingerprint);
+    result = await consultAdvisor(
+      {
+        parsed,
+        workerIdentity: deps.workerIdentity,
+        advisorModel: current.model,
+        reason,
+        ...(question !== undefined ? { question } : {}),
+      },
+      deps.config,
+      current.effort,
+      current.timeoutMs,
+      deps.abortSignal,
+      deps.baseUrlOverride,
+    );
+    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 === "preflight" ? "preflight" : "manual",
+        }),
+      };
+    }
+    return {
+      ok: false,
+      isError: true,
+      ...(result.cancelled ? { cancelled: true } : {}),
+      content: formatAdvisorUnavailable(reason === "preflight" ? "preflight" : "manual", result.error ?? "unavailable"),
+    };
+  };
+
+  const preflightInject = async (parsed: OcxParsedRequest): Promise<boolean> => {
+    const current = liveSettings();
+    if (current.policy !== "preflight" || preflightUsed) 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.
+    if (historyHasManualAdvisorResult(parsed)) return false;
+    if (!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 key = taskKey(parsed);
+    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, "preflight", undefined);
+    } catch (error) {
+      if (key && claimToken) ledger.fail(key, claimToken, now());
+      console.warn(`[advisor] consultation failed trigger=preflight 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 = {
+    consult: (parsed, reason, question) => runConsultation(parsed, reason, question),
+    // 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),
+  };
+
+  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,
+    tool: buildAdvisorTool(),
+    consult: plan.consult,
+    formatUnavailable: plan.formatUnavailable,
+    preflightInject,
+    attachGuard: parsed => {
+      parsed._advisorGuard = createAdvisorGuard(plan);
+    },
+  };
+}

package/src/advisor/settings.ts

@@ -0,0 +1,135 @@
+/**
+ * The single reader of `advisor` config.
+ *
+ * Nothing else reads the `advisor` key directly: the sidecar planner, the management API and the
+ * CLI all resolve through here, so they cannot disagree about defaults or validity. Type-only
+ * config import keeps this module free of runtime edges.
+ */
+import type { OcxConfig } from "../types";
+import { ADVISOR_CONTEXT_SHARING_CONSENT_VERSION } from "./disclosure";
+
+export { ADVISOR_CONTEXT_SHARING_CONSENT_VERSION };
+
+export type AdvisorPolicy = "manual" | "preflight";
+
+export const ADVISOR_EFFORTS = ["low", "medium", "high", "xhigh", "max", "ultra"] as const;
+export type AdvisorEffort = (typeof ADVISOR_EFFORTS)[number];
+
+export const ADVISOR_POLICIES = ["manual", "preflight"] as const;
+
+export interface AdvisorSettings {
+  enabled: boolean;
+  model: string;
+  effort: AdvisorEffort;
+  policy: AdvisorPolicy;
+  timeoutMs: number;
+  /**
+   * Current context-sharing consent, or null when absent, stale, or malformed.
+   * `enabled` does not imply this. Only the current version allows data transfer.
+   */
+  contextSharingConsent: typeof ADVISOR_CONTEXT_SHARING_CONSENT_VERSION | null;
+  /** Where each resolved value came from, so the GUI/CLI can show real runtime state. */
+  sources: {
+    enabled: "default" | "configured";
+    model: "default" | "configured";
+    effort: "default" | "configured";
+    policy: "default" | "configured";
+    contextSharingConsent: "default" | "configured";
+  };
+}
+
+export const DEFAULT_ADVISOR_SETTINGS: Readonly<AdvisorSettings> = Object.freeze({
+  enabled: false,
+  model: "",
+  effort: "max",
+  policy: "manual",
+  timeoutMs: 120_000,
+  contextSharingConsent: null,
+  sources: Object.freeze({
+    enabled: "default",
+    model: "default",
+    effort: "default",
+    policy: "default",
+    contextSharingConsent: "default",
+  }),
+});
+
+type Rec = Record<string, unknown>;
+function isRec(value: unknown): value is Rec {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+export function isValidAdvisorEffort(value: unknown): value is AdvisorEffort {
+  return typeof value === "string" && (ADVISOR_EFFORTS as readonly string[]).includes(value);
+}
+
+export function isValidAdvisorPolicy(value: unknown): value is AdvisorPolicy {
+  return typeof value === "string" && (ADVISOR_POLICIES as readonly string[]).includes(value);
+}
+
+/** True only for the current context-sharing consent version. Anything else is not a grant. */
+export function isCurrentAdvisorContextSharingConsent(
+  value: unknown,
+): value is typeof ADVISOR_CONTEXT_SHARING_CONSENT_VERSION {
+  return value === ADVISOR_CONTEXT_SHARING_CONSENT_VERSION;
+}
+
+/**
+ * Resolve advisor settings with conservative defaults for every absent or malformed field.
+ * A malformed block resolves to fully disabled defaults rather than throwing: the advisor is
+ * optional and must never take the request path down with it.
+ */
+export function resolveAdvisorSettings(config: Pick<OcxConfig, "advisor">): AdvisorSettings {
+  const raw: unknown = config.advisor;
+  if (!isRec(raw)) return { ...DEFAULT_ADVISOR_SETTINGS, sources: { ...DEFAULT_ADVISOR_SETTINGS.sources } };
+  const enabled = typeof raw.enabled === "boolean" ? raw.enabled : DEFAULT_ADVISOR_SETTINGS.enabled;
+  const model = typeof raw.model === "string" ? raw.model.trim() : DEFAULT_ADVISOR_SETTINGS.model;
+  const effort = isValidAdvisorEffort(raw.effort) ? raw.effort : DEFAULT_ADVISOR_SETTINGS.effort;
+  const policy = isValidAdvisorPolicy(raw.policy) ? raw.policy : DEFAULT_ADVISOR_SETTINGS.policy;
+  const timeoutRaw = raw.timeoutMs;
+  const timeoutMs = typeof timeoutRaw === "number" && Number.isFinite(timeoutRaw) && timeoutRaw >= 1_000
+    ? Math.min(Math.floor(timeoutRaw), 600_000)
+    : DEFAULT_ADVISOR_SETTINGS.timeoutMs;
+  // A present but non-current value (stale version, wrong type) resolves as no consent.
+  // The stored bytes are left untouched; this reader never writes an upgrade.
+  const consentConfigured = Object.prototype.hasOwnProperty.call(raw, "contextSharingConsent");
+  const contextSharingConsent = isCurrentAdvisorContextSharingConsent(raw.contextSharingConsent)
+    ? raw.contextSharingConsent
+    : null;
+  return {
+    enabled,
+    model,
+    effort,
+    policy,
+    timeoutMs,
+    contextSharingConsent,
+    sources: {
+      enabled: typeof raw.enabled === "boolean" ? "configured" : "default",
+      model: typeof raw.model === "string" && raw.model.trim() !== "" ? "configured" : "default",
+      effort: isValidAdvisorEffort(raw.effort) ? "configured" : "default",
+      policy: isValidAdvisorPolicy(raw.policy) ? "configured" : "default",
+      contextSharingConsent: consentConfigured ? "configured" : "default",
+    },
+  };
+}
+
+/**
+ * Whether a consultation may send task context. Requires the switch, a model, and the
+ * current context-sharing consent. `enabled` is not consent. A miss fails closed for the
+ * data transfer and leaves the worker request itself running.
+ */
+export function advisorRunnable(settings: AdvisorSettings): boolean {
+  return settings.enabled
+    && settings.model.trim() !== ""
+    && settings.contextSharingConsent === ADVISOR_CONTEXT_SHARING_CONSENT_VERSION;
+}
+
+/**
+ * Enabled, with a model, but without current consent. The management surface reports
+ * `advisor_context_sharing_consent_required` and the runtime sends no task context.
+ */
+export function advisorContextSharingBlocked(settings: AdvisorSettings): boolean {
+  return settings.enabled
+    && settings.model.trim() !== ""
+    && settings.contextSharingConsent !== ADVISOR_CONTEXT_SHARING_CONSENT_VERSION;
+}