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