// SPEC: PJ2026-0104010803 Workbench唯一投影 draft-2026-06-20-p2-terminal-outbox-recovery; PJ2026-010403 API契约 draft-2026-06-20-p2-terminal-outbox-recovery; PJ2026-010205 HWLAB接入 draft-2026-06-25-p0-session-warm-runner-contract; PJ2026-0102 Agent编排 draft-2026-06-17-r0; PJ2026-01060505 Workbench Performance draft-2026-06-17-p0.
// Responsibility: Code Agent HTTP result, turn, inspect, and cancel resources.

import { createHash, randomUUID } from "node:crypto";

import { M3_IO_CONTROL_ROUTE, M3_STATUS_ROUTE, describeM3StatusLive, handleM3IoControl } from "./m3-io-control.ts";
import {
  agentRunSessionEvidence,
  cancelAgentRunChatTurn,
  codeAgentAgentRunAdapterEnabled,
  initialAgentRunChatResult,
  loadPersistedAgentRunResult,
  steerAgentRunChatTurn,
  submitAgentRunChatTurn
} from "./code-agent-agentrun-adapter.ts";
import { createCodeAgentErrorPayload, handleCodeAgentChat } from "./code-agent-chat.ts";
import { defaultCodeAgentTraceStore } from "./code-agent-trace-store.ts";
import { codeAgentSessionLifecycleSummary } from "./code-agent-session-lifecycle.ts";
import { messageAuthorityTextValue } from "./code-agent-agentrun-prompt.ts";
import { createWorkbenchReadModel } from "./workbench-read-model.ts";
import { codeAgentOtelTraceFields, emitCodeAgentOtelSpan } from "./otel-trace.ts";
import {
  firstHeaderValue,
  getHeader,
  parsePositiveInteger,
  positiveInteger,
  readBody,
  safeConversationId,
  safeOpaqueId,
  safeSessionId,
  safeTraceId,
  sendJson,
  truthyFlag
} from "./server-http-utils.ts";

import {
  normalizeCodeAgentProviderProfile,
  firstNonEmptyValue,
  recordCodeAgentSessionInputFact,
  stableCodeAgentInputId,
  codeAgentInputDelivery,
  codeAgentInputStatus,
  codeAgentResultTimingFields,
  firstTimestampIso,
  firstLatestTimestampIso,
  codeAgentChatShortConnectionRequested,
  preflightCodeAgentBilling,
  recordCodeAgentBillingUsage,
  finalizeCodeAgentBillingUsage,
  releaseCodeAgentBillingReservation,
  withCodeAgentBillingReservation,
  codeAgentBillingEnabled,
  codeAgentBillingMetadata,
  sanitizeBillingReservation,
  sanitizeBillingRecord,
  sanitizeBillingRelease,
  codeAgentUsedTokens,
  normalizeTurnStatus,
  recordCodeAgentConversationFact,
  recordCodeAgentSessionOwner,
  codeAgentOwnerStatusForResult,
  textValue,
  timestampIsoOrNow,
  timestampIsoOrNull,
  codeAgentSessionOwnerEvidence,
  codeAgentContinuationEvidence,
  codeAgentFreshContinuationFailure,
  normalizeCodeAgentFailureKind,
  codeAgentFailureRequiresFreshContinuation,
  codeAgentProviderProfileEvidence,
  codeAgentTraceResultEvidence,
  codeAgentPromptMetadata,
  codeAgentPromptMetadataFromText,
  codeAgentPromptMetadataFromParts,
  codeAgentPromptFields,
  codeAgentPromptId,
  clippedPromptText,
  sha256Text,
  compactCodeAgentObject,
  codeAgentBillingReservationEvidence,
  codeAgentConversationMessagesEvidence,
  boundedConversationMessageText,
  conversationText,
  conversationTextRaw,
  codeAgentMessageTraceSuffix,
  codeAgentTurnLifecycleFields,
  codeAgentLifecycleMessageId,
  safeTurnId,
  safeMessageId,
  codeAgentConversationAgentMessageStatus,
  codeAgentPayloadHasSealedFinalResponse,
  codeAgentConversationRunnerTraceEvidence,
  codeAgentFinalResponseEvidence,
  codeAgentFinalResponseText,
  codeAgentTraceSummaryEvidence,
  annotateOwner,
  canAccessOwnedResult,
  isCodeAgentResultCanceled,
  codeAgentCancelScopeMismatch,
  cancelExpectedValues,
  cancelScopeFieldMismatch,
  cancelBlockedPayload,
  isTraceCommandTerminalStatus,
  traceSnapshotWithTerminalEvidence,
  traceSnapshotWithAttachedTerminalEvidence,
  agentRunTerminalTraceEvidence,
  agentRunTerminalFinalResponse,
  traceRetentionSummary,
  numberOrNull,
  createCodeAgentChatResultStore,
  compactCodeAgentChatResultPayload,
  terminalEvidencePayload,
  compactRunnerTraceForResult,
  traceEventLabel,
  resultTraceEventLimit,
  createCodeAgentM3HwlabApiRequestJson,
  recordCodeAgentProjectionMetrics,
  recordCodeAgentTurnReadMetric,
  turnReadDegradedReason,
  responseBodyBytes,
  statusClassLabel,
  sourceLatestSeqFromResult,
  sourceLatestAtFromResult,
  terminalSourceAtFromResult,
  projectionReason,
  nowMs,
  uniqueStrings
} from "./server-code-agent-http-support.ts";

const DEFAULT_CODE_AGENT_RESULT_TRACE_EVENT_LIMIT = 120;
const DEFAULT_CODE_AGENT_TRACE_PAGE_LIMIT = 100;
const MAX_CODE_AGENT_TRACE_PAGE_LIMIT = 100;
const DEFAULT_CODE_AGENT_TURN_STATUS_REFRESH_TIMEOUT_MS = 2500;
const DEFAULT_CODE_AGENT_PROJECT_ID = "prj_hwpod_workbench";
const DEFAULT_CODE_AGENT_PROVIDER_PROFILE = "deepseek";
const CODE_AGENT_TERMINAL_STATUSES = new Set(["completed", "failed", "blocked", "timeout", "cancelled", "canceled"]);
const CODE_AGENT_PROVIDER_PROFILE_ALIASES = Object.freeze({ codex: "codex-api" });
const CODE_AGENT_PROVIDER_PROFILE_ID_PATTERN = /^[a-z0-9][a-z0-9.-]{0,63}$/u;
const CODE_AGENT_PROVIDER_PROFILE_LABELS = Object.freeze({
  "deepseek": "DeepSeek",
  "codex-api": "Codex API",
  "gpt.pika": "gpt.pika",
  "minimax-m3": "MiniMax-M3 via AgentRun",
  "runtime-default": "运行默认"
});
const DEFAULT_CODE_AGENT_CODEX_API_MODEL = "gpt-5.5";
const DEFAULT_CODE_AGENT_CODEX_API_BASE_URL = "http://127.0.0.1:49280/responses";
const DEFAULT_CODE_AGENT_DEEPSEEK_MODEL = "deepseek-chat";
const DEFAULT_CODE_AGENT_MINIMAX_M3_MODEL = "MiniMax-M3";

export async function handleCodeAgentChatResultHttp(request, response, url, options) {
  const parts = url.pathname.split("/").filter(Boolean);
  const traceId = decodeURIComponent(parts[4] ?? "");
  if (!safeTraceId(traceId)) {
    sendJson(response, 400, {
      error: {
        code: "invalid_trace_id",
        message: "traceId must start with trc_ and contain only safe identifier characters"
      }
    });
    return;
  }
  const context = await measureCodeAgentHttpPhase(options, "result_projection_read", () => readCodeAgentCompatProjection(traceId, options));
  if (context.statusCode) {
    sendJson(response, context.statusCode, context.body);
    return;
  }
  const result = context.result;
  if (result && result.status !== "running" && !codeAgentResultUsesProjectionTerminalAuthority(result)) {
    sendJson(response, 200, codeAgentCompatProjectionPayload(compactCodeAgentChatResultPayload(result, options), context));
    return;
  }
  if (context.found) {
    const body = codeAgentTurnStatusPayload({ traceId, result, snapshot: context.trace, resultPollError: null, refreshError: context.refreshError ?? null, options });
    const resultPollTerminalReady = codeAgentResultPollTerminalReady(body);
    sendJson(response, resultPollTerminalReady ? 200 : 202, codeAgentCompatProjectionPayload({
      accepted: body.ok,
      shortConnection: true,
      ...body,
      waitingFor: resultPollTerminalReady ? body.waitingFor ?? context.trace?.waitingFor ?? "workbench-projection" : "agentrun-result",
      ...(body.terminal === true && !resultPollTerminalReady ? { status: "running", running: true, terminal: false } : {})
    }, context));
    return;
  }
  sendJson(response, 404, {
    ...codeAgentCompatProjectionPayload({ traceId, status: "unknown" }, context),
    error: {
      code: "code_agent_result_not_found",
      message: `No Code Agent result is registered for ${traceId}`
    }
  });
}

export async function handleCodeAgentTurnHttp(request, response, url, options) {
  const startedAt = nowMs();
  const parts = url.pathname.split("/").filter(Boolean);
  const traceId = decodeURIComponent(parts[3] ?? "");
  if (!safeTraceId(traceId)) {
    const body = {
      ok: false,
      status: "unknown",
      running: false,
      terminal: false,
      error: {
        code: "invalid_trace_id",
        message: "traceId must start with trc_ and contain only safe identifier characters"
      }
    };
    recordCodeAgentTurnReadMetric(options, url, 400, body, startedAt);
    sendJson(response, 400, body);
    return;
  }
  const requestOptions = codeAgentRequestScopedOptions(options);
  let completed = false;
  const emitTurnStatusReadSpan = (name, attributes = {}, error = null) => {
    void emitCodeAgentOtelSpan(name, traceId, requestOptions.env ?? process.env, {
      startTimeMs: startedAt,
      status: error ? "error" : undefined,
      error,
      attributes: {
        "http.method": "GET",
        "http.route": "/v1/agent/turns/:traceId",
        durationMs: nowMs() - startedAt,
        ...attributes
      }
    });
  };
  response.once?.("close", () => {
    if (completed) return;
    emitTurnStatusReadSpan("turn_status_read.client_closed", {
      status: "client_closed",
      phase: "response_close",
      terminal: false
    }, new Error("Code Agent turn status client connection closed before response completed."));
  });
  try {
    const projectMismatch = await measureCodeAgentHttpPhase(requestOptions, "turn_project_check", () => traceProjectMismatchSnapshot(traceId, url, requestOptions, "turn"));
    if (projectMismatch) {
      completed = true;
      recordCodeAgentTurnReadMetric(options, url, projectMismatch.statusCode, projectMismatch.body, startedAt);
      emitTurnStatusReadSpan("turn_status_read", { "http.status_code": projectMismatch.statusCode, status: projectMismatch.body?.status ?? null, terminal: projectMismatch.body?.terminal ?? null, phase: "project_check" });
      sendJson(response, projectMismatch.statusCode, projectMismatch.body);
      return;
    }
    const resolved = await measureCodeAgentHttpPhase(requestOptions, "turn_resolve_status", () => resolveCodeAgentTurnStatusSnapshot(traceId, requestOptions));
    completed = true;
    recordCodeAgentTurnReadMetric(options, url, resolved.statusCode, resolved.body, startedAt);
    emitTurnStatusReadSpan("turn_status_read", { "http.status_code": resolved.statusCode, status: resolved.body?.status ?? null, terminal: resolved.body?.terminal ?? null, phase: "resolved" });
    sendJson(response, resolved.statusCode, resolved.body);
  } catch (error) {
    completed = true;
    const body = {
      ok: false,
      status: "unknown",
      running: false,
      terminal: false,
      traceId,
      error: {
        code: error?.code ?? "turn_status_read_failed",
        message: error?.message ?? "Code Agent turn status read failed."
      },
      valuesRedacted: true
    };
    recordCodeAgentTurnReadMetric(options, url, 500, body, startedAt);
    emitTurnStatusReadSpan("turn_status_read", { "http.status_code": 500, status: body.status, terminal: false, phase: "failed", errorCode: body.error.code }, error);
    sendJson(response, 500, body);
  }
}

async function resolveCodeAgentTurnStatusSnapshot(traceId, options) {
  const context = await readCodeAgentCompatProjection(traceId, options);
  if (context.statusCode) return context;
  const body = await measureCodeAgentHttpPhase(options, "turn_payload", () => codeAgentTurnStatusPayload({
    traceId,
    result: context.result,
    snapshot: context.trace,
    resultPollError: null,
    refreshError: context.refreshError ?? null,
    options
  }));
  return { statusCode: body.ok ? 200 : 404, body: codeAgentCompatProjectionPayload(body, context) };
}

function codeAgentRequestScopedOptions(options = {}) {
  return {
    ...options,
    codeAgentTraceSessionCache: options.codeAgentTraceSessionCache instanceof Map ? options.codeAgentTraceSessionCache : new Map()
  };
}

async function measureCodeAgentHttpPhase(options, phase, callback) {
  const perf = options?.backendPerformance;
  return perf && typeof perf.measure === "function" ? await perf.measure(phase, callback) : await callback();
}

function forbiddenTurnSnapshot(traceId) {
  return {
    statusCode: 403,
    body: {
      ok: false,
      status: "unknown",
      running: false,
      terminal: false,
      traceId,
      error: {
        code: "agent_session_owner_required",
        message: "Only the session owner or admin can read this Code Agent turn status"
      }
    }
  };
}

async function readCodeAgentCompatProjection(traceId, options = {}) {
  const readModel = createWorkbenchReadModel(options, options.actor ?? null);
  const session = await readModel.getSessionByTraceId(traceId);
  let result = readModel.resultForTrace(traceId) ?? projectedSessionTraceResult(session, traceId);
  if (result && !canAccessOwnedResult(result, options.actor)) return forbiddenTurnSnapshot(traceId);
  if (result?.ownerUserId && !readModel.canReadOwner(result.ownerUserId)) return forbiddenTurnSnapshot(traceId);
  const projectionTrace = await readModel.traceSnapshot(traceId);
  let trace = traceSnapshotWithTerminalEvidence(projectionTrace, result, traceId, null);
  const projection = readModel.projectionDiagnostics({ traceId, result, trace, refreshError: null });
  recordCodeAgentProjectionMetrics(options, { result, trace, projection, refreshError: null });
  const found = Boolean(result || session || (trace && trace.status !== "missing") || trace?.persisted === true);
  return { result, session, trace, projection, found, refreshError: null };
}

function projectedSessionTraceResult(session, traceId) {
  const safeId = safeTraceId(traceId);
  if (!session || !safeId) return null;
  const snapshot = session.session && typeof session.session === "object" ? session.session : null;
  const traceResults = snapshot?.traceResults && typeof snapshot.traceResults === "object" ? snapshot.traceResults : null;
  const stored = traceResults?.[safeId] && typeof traceResults[safeId] === "object" ? traceResults[safeId] : null;
  if (!stored) return null;
  return {
    ...stored,
    traceId: safeId,
    conversationId: safeConversationId(stored.conversationId ?? session.conversationId) || null,
    sessionId: safeSessionId(stored.sessionId ?? session.id) || null,
    threadId: safeOpaqueId(stored.threadId ?? session.threadId) || null,
    ownerUserId: session.ownerUserId ?? stored.ownerUserId ?? null,
    ownerRole: session.ownerRole ?? stored.ownerRole ?? null,
    status: stored.status ?? session.status ?? null,
    valuesRedacted: true
  };
}

function codeAgentCompatProjectionPayload(payload = {}, context = {}) {
  const traceId = safeTraceId(payload.traceId ?? context.trace?.traceId) ?? null;
  const projection = context.projection && typeof context.projection === "object" ? context.projection : {};
  return {
    ...payload,
    projection,
    projectionStatus: projection.projectionStatus ?? null,
    projectionHealth: projection.projectionHealth ?? null,
    lastProjectedSeq: projection.lastProjectedSeq ?? null,
    sourceRunId: projection.sourceRunId ?? null,
    sourceCommandId: projection.sourceCommandId ?? null,
    staleMs: projection.staleMs ?? null,
    blocker: projection.blocker ?? null,
    workbench: traceId ? {
      detailOnly: true,
      turnDetailUrl: `/v1/workbench/turns/${encodeURIComponent(traceId)}`,
      traceEventsDetailUrl: `/v1/workbench/traces/${encodeURIComponent(traceId)}/events`
    } : null,
    valuesRedacted: true,
    secretMaterialStored: false
  };
}

function codeAgentResultPollTerminalReady(body = {}) {
  if (body?.terminal !== true) return false;
  return Boolean(messageAuthorityTextValue(body.finalResponse ?? body.reply ?? body.terminalEvidence?.finalResponse));
}

async function traceProjectMismatchSnapshot(traceId, url, options, resourceKind) {
  const requestedProjectId = textValue(url.searchParams.get("projectId"));
  if (!requestedProjectId || !options.accessController?.getAgentSessionByTraceId) return null;
  const session = await getCodeAgentSessionByTraceId(traceId, options);
  if (!session) return null;
  if (session.ownerUserId && options.actor?.role !== "admin" && session.ownerUserId !== options.actor?.id) return forbiddenTurnSnapshot(traceId);
  const actualProjectId = textValue(session.projectId);
  if (!actualProjectId || actualProjectId === requestedProjectId) return null;
  return {
    statusCode: 404,
    body: {
      ok: false,
      status: "not_found",
      running: false,
      terminal: false,
      traceId,
      error: {
        code: "trace_project_mismatch",
        message: `${resourceKind === "turn" ? "Agent turn" : "Agent trace"} is not visible in the requested project`
      }
    }
  };
}

async function getCodeAgentSessionByTraceId(traceId, options = {}) {
  const safeId = safeTraceId(traceId);
  if (!safeId || typeof options.accessController?.getAgentSessionByTraceId !== "function") return null;
  const cache = options.codeAgentTraceSessionCache;
  if (cache instanceof Map) {
    if (cache.has(safeId)) return cache.get(safeId);
    const session = await options.accessController.getAgentSessionByTraceId(safeId);
    cache.set(safeId, session ?? null);
    return session ?? null;
  }
  return await options.accessController.getAgentSessionByTraceId(safeId);
}

export function codeAgentTurnStatusPayload({ traceId, result, snapshot, resultPollError, refreshError, options }) {
  const resultObject = result && typeof result === "object" ? result : null;
  const snapshotObject = snapshot && typeof snapshot === "object" ? snapshot : null;
  const projectionTerminalAuthority = codeAgentResultUsesProjectionTerminalAuthority(resultObject);
  const lifecycle = codeAgentTurnLifecycleFields(traceId, resultObject ?? snapshotObject ?? {});
  const events = Array.isArray(snapshotObject?.events) ? snapshotObject.events : Array.isArray(resultObject?.runnerTrace?.events) ? resultObject.runnerTrace.events : [];
  const lastEvent = events.at(-1) ?? null;
  const finalResponse = projectionTerminalAuthority
    ? snapshotObject?.finalResponse ?? snapshotObject?.terminalEvidence?.finalResponse ?? codeAgentFinalResponseEvidence(snapshotObject ?? {}, traceId)
    : resultObject?.finalResponse ?? snapshotObject?.finalResponse ?? snapshotObject?.terminalEvidence?.finalResponse ?? codeAgentFinalResponseEvidence(resultObject ?? snapshotObject ?? {}, traceId);
  const terminalStatus = projectionTerminalAuthority
    ? codeAgentProjectionTerminalStatus(snapshotObject)
    : codeAgentAuthoritativeTerminalStatus(resultObject, snapshotObject, traceId);
  const terminalSealBlocked = Boolean(terminalStatus && isTurnTerminalStatus(terminalStatus) && !codeAgentTerminalFinalText(finalResponse, projectionTerminalAuthority ? null : resultObject, snapshotObject));
  const rawStatus = projectionTerminalAuthority
    ? normalizeTurnStatus(
      terminalStatus,
      codeAgentRunningStatus(snapshotObject?.status),
      codeAgentRunningStatus(snapshotObject?.traceStatus),
      codeAgentRunningStatus(snapshotObject?.runnerTrace?.status),
      codeAgentRunningStatus(resultObject?.status),
      "running"
    )
    : normalizeTurnStatus(
      terminalStatus,
      resultObject?.agentRun?.commandState,
      resultObject?.agentRun?.status,
      resultObject?.agentRun?.runStatus,
      codeAgentRunningStatus(snapshotObject?.status),
      codeAgentRunningStatus(snapshotObject?.traceStatus),
      codeAgentRunningStatus(snapshotObject?.runnerTrace?.status),
      codeAgentRunningStatus(resultObject?.status),
      resultObject?.agentRun?.terminalStatus,
      snapshotObject?.terminalEvidence?.traceSummary?.terminalStatus
    );
  const status = terminalSealBlocked ? "running" : rawStatus;
  const found = Boolean(resultObject || (snapshotObject && snapshotObject.status !== "missing") || snapshotObject?.persisted === true);
  const running = isTurnRunningStatus(status);
  const terminal = isTurnTerminalStatus(status);
  const runnerTrace = snapshotObject && snapshotObject.status !== "missing" ? snapshotObject : resultObject?.runnerTrace ?? null;
  const timingFields = codeAgentResultTimingFields(resultObject, snapshotObject, runnerTrace);
  return {
    ok: found,
    action: "code-agent.turn.status",
    contractVersion: "code-agent-turn-status-v1",
    status: found ? status ?? "unknown" : "unknown",
    running: found ? running : false,
    terminal: found ? terminal : false,
    traceId,
    ...lifecycle,
    conversationId: safeConversationId(resultObject?.conversationId ?? snapshotObject?.conversationId) || null,
    sessionId: safeSessionId(resultObject?.sessionId ?? resultObject?.session?.sessionId ?? snapshotObject?.sessionId) || null,
    threadId: safeOpaqueId(resultObject?.threadId ?? resultObject?.session?.threadId ?? snapshotObject?.threadId) || null,
    updatedAt: textValue(resultObject?.updatedAt ?? resultObject?.agentRun?.updatedAt ?? snapshotObject?.updatedAt ?? timingFields.lastEventAt ?? timingFields.startedAt) || null,
    ...timingFields,
    lastEventLabel: textValue(snapshotObject?.lastEventLabel ?? runnerTrace?.lastEventLabel ?? lastEvent?.label ?? lastEvent?.type) || null,
    waitingFor: terminalSealBlocked ? "final_response" : textValue(snapshotObject?.waitingFor ?? runnerTrace?.waitingFor) || null,
    terminalObserved: Boolean(terminalStatus),
    terminalObservedStatus: terminalStatus ?? null,
    terminalSealBlocked,
    resultUrl: `/v1/agent/chat/result/${encodeURIComponent(traceId)}`,
    traceUrl: `/v1/agent/traces/${encodeURIComponent(traceId)}`,
    turnUrl: `/v1/agent/turns/${encodeURIComponent(traceId)}`,
    runnerTrace: runnerTrace ? compactRunnerTraceForResult(runnerTrace, resultTraceEventLimit(options)) : null,
    agentRun: resultObject?.agentRun ?? snapshotObject?.agentRun ?? null,
    terminalEvidence: snapshotObject?.terminalEvidence ?? null,
    finalResponse,
    traceSummary: resultObject?.traceSummary ?? snapshotObject?.traceSummary ?? snapshotObject?.terminalEvidence?.traceSummary ?? null,
    retention: snapshotObject?.retention ?? null,
    eventCount: numberOrNull(snapshotObject?.eventCount ?? runnerTrace?.eventCount ?? events.length),
    error: resultPollError || refreshError
      ? codeAgentRefreshErrorPayload(resultPollError ?? refreshError, traceId, resultObject?.agentRun ?? snapshotObject?.agentRun, "turn_status_degraded")
      : resultObject?.error ?? snapshotObject?.error ?? null,
    valuesRedacted: true,
    secretMaterialStored: false
  };
}

function codeAgentResultUsesProjectionTerminalAuthority(result = null) {
  const agentRun = result?.agentRun && typeof result.agentRun === "object" ? result.agentRun : null;
  if (!agentRun || agentRun.adapter !== "agentrun-v01") return false;
  return agentRun.durableDispatch === true
    || Boolean(textValue(agentRun.dispatchIntentId ?? agentRun.commandId));
}

function codeAgentProjectionTerminalStatus(snapshotObject = null) {
  const status = normalizeTurnStatus(
    snapshotObject?.terminalEvidence?.status,
    snapshotObject?.terminalEvidence?.traceSummary?.terminalStatus,
    snapshotObject?.status
  );
  return status && isTurnTerminalStatus(status) && codeAgentSnapshotHasTerminalAuthority(snapshotObject) ? status : null;
}

function codeAgentTerminalFinalText(finalResponse = null, resultObject = null, snapshotObject = null) {
  const candidates = [
    finalResponse,
    resultObject?.finalResponse,
    snapshotObject?.finalResponse,
    snapshotObject?.terminalEvidence?.finalResponse,
    resultObject?.terminalEvidence?.finalResponse
  ];
  for (const value of candidates) {
    const text = conversationText(value);
    if (text) return text;
  }
  return codeAgentFinalResponseText(resultObject ?? {}) || codeAgentFinalResponseText(snapshotObject ?? {});
}

function codeAgentAuthoritativeTerminalStatus(resultObject, snapshotObject, traceId) {
  const sealedPayload = codeAgentPayloadHasSealedFinalResponse(resultObject ?? {}) ? resultObject : codeAgentPayloadHasSealedFinalResponse(snapshotObject ?? {}) ? snapshotObject : null;
  if (sealedPayload) {
    const sealedStatus = normalizeTurnStatus(sealedPayload?.finalResponse?.status, sealedPayload?.terminalEvidence?.finalResponse?.status, sealedPayload?.agentRun?.terminalStatus, sealedPayload?.agentRun?.status, sealedPayload?.status);
    return sealedStatus && isTurnTerminalStatus(sealedStatus) ? sealedStatus : "completed";
  }
  const snapshotStatus = normalizeTurnStatus(snapshotObject?.terminalEvidence?.traceSummary?.terminalStatus, snapshotObject?.terminalEvidence?.agentRun?.terminalStatus, snapshotObject?.terminalEvidence?.status, snapshotObject?.status);
  if (snapshotStatus && isTurnTerminalStatus(snapshotStatus) && codeAgentSnapshotHasTerminalAuthority(snapshotObject)) return snapshotStatus;
  const agentRunStatus = normalizeTurnStatus(resultObject?.agentRun?.terminalStatus, resultObject?.agentRun?.commandState, resultObject?.agentRun?.status, resultObject?.agentRun?.runStatus);
  if (agentRunStatus && isTurnTerminalStatus(agentRunStatus)) return agentRunStatus;
  const resultStatus = normalizeTurnStatus(resultObject?.status);
  if (resultStatus && isTurnTerminalStatus(resultStatus) && codeAgentResultHasTerminalAuthority(resultObject, traceId)) return resultStatus;
  return null;
}

function codeAgentSnapshotHasTerminalAuthority(snapshot = null) {
  if (!snapshot || typeof snapshot !== "object") return false;
  if (snapshot.terminal === true || snapshot.sealed === true) return true;
  if (snapshot.terminalEvidence?.available === true || snapshot.terminalEvidence?.source) return true;
  const events = Array.isArray(snapshot.events) ? snapshot.events : [];
  return events.some((event) => event?.terminal === true);
}

function codeAgentResultHasTerminalAuthority(result = null, traceId = null) {
  if (!result || typeof result !== "object") return false;
  if (result.terminal === true || result.sealed === true) return true;
  if (result.error || result.blocker) return true;
  if (codeAgentPayloadHasSealedFinalResponse(result)) return true;
  if (agentRunTerminalTraceEvidence(result, traceId)) return true;
  return Boolean(textValue(result.finishedAt ?? result.completedAt ?? result.endedAt));
}

function codeAgentRefreshErrorPayload(error, traceId, agentRun, fallbackCode) {
  return {
    code: error?.code ?? fallbackCode,
    layer: error?.layer ?? "agentrun",
    category: error?.category ?? (error?.code === "agentrun_timeout" ? "upstream-timeout" : "upstream-refresh-failed"),
    retryable: error?.retryable !== false,
    message: error?.message ?? "Code Agent turn status refresh degraded",
    traceId,
    runId: agentRun?.runId ?? error?.runId ?? null,
    commandId: agentRun?.commandId ?? error?.commandId ?? null,
    method: error?.method ?? null,
    route: error?.route ?? error?.path ?? null,
    timeoutMs: numberOrNull(error?.timeoutMs),
    timeoutStage: error?.timeoutStage ?? null,
    upstreamStatus: numberOrNull(error?.statusCode),
    managerHost: error?.managerHost ?? null,
    valuesPrinted: false
  };
}

function isTurnRunningStatus(status) {
  return status === "running";
}

function codeAgentRunningStatus(value) {
  const status = normalizeTurnStatus(value);
  return isTurnRunningStatus(status) ? status : null;
}

function isTurnTerminalStatus(status) {
  return CODE_AGENT_TERMINAL_STATUSES.has(String(status ?? "").trim().toLowerCase().replace(/_/gu, "-"));
}

export async function handleCodeAgentInspectHttp(request, response, url, options) {
  const query = {
    conversationId: safeConversationId(url.searchParams.get("conversationId")),
    sessionId: safeSessionId(url.searchParams.get("sessionId")),
    threadId: safeOpaqueId(url.searchParams.get("threadId")),
    traceId: safeTraceId(url.searchParams.get("traceId"))
  };
  const sessionRegistry = options.sessionRegistry;
  const traceStore = options.traceStore ?? defaultCodeAgentTraceStore;
  const manager = options.codexStdioManager;
  const managerDescription = manager && typeof manager.describe === "function" ? manager.describe() : null;
  const managerRecentSessions = Array.isArray(managerDescription?.recentSessions) ? managerDescription.recentSessions : [];
  const directManagerSession = query.sessionId && manager && typeof manager.get === "function"
    ? manager.get(query.sessionId, { conversationId: query.conversationId })
    : null;
  const matchedManagerSession = directManagerSession ?? managerRecentSessions.find((session) => sessionMatchesInspectQuery(session, query)) ?? null;
  const registryInspect = sessionRegistry && typeof sessionRegistry.inspect === "function"
    ? sessionRegistry.inspect(query)
    : { ok: false, status: "unavailable", traceIds: [], session: null, conversationFacts: null };
  const resultEvidence = await codeAgentInspectResultEvidence(query.traceId, options);
  const session = matchedManagerSession ?? registryInspect.session ?? resultEvidence.session ?? null;
  const conversationFacts = registryInspect.conversationFacts ?? resultEvidence.conversationFacts ?? null;
  const requestedRunnerTrace = query.traceId ? traceStore.snapshot(query.traceId) : null;
  const requestedTraceFound = Boolean(requestedRunnerTrace && requestedRunnerTrace.status !== "missing");
  const traceIds = uniqueStrings([
    requestedTraceFound ? query.traceId : null,
    session?.currentTraceId,
    session?.lastTraceId,
    conversationFacts?.latestTraceId,
    resultEvidence.latestTraceId,
    ...(Array.isArray(conversationFacts?.traceIds) ? conversationFacts.traceIds : []),
    ...(Array.isArray(registryInspect.traceIds) ? registryInspect.traceIds : [])
  ]);
  const latestTraceId = traceIds[0] ?? null;
  const runnerTrace = latestTraceId
    ? latestTraceId === query.traceId && requestedRunnerTrace
      ? requestedRunnerTrace
      : traceStore.snapshot(latestTraceId)
    : null;
  const found = Boolean(registryInspect.ok || session || latestTraceId);
  sendJson(response, found ? 200 : 404, {
    ok: found,
    action: "code-agent.chat.inspect",
    status: found ? "found" : "not_found",
    query,
    session,
    conversationFacts,
    traceIds,
    latestTraceId,
    traceUrl: latestTraceId ? `/v1/agent/traces/${encodeURIComponent(latestTraceId)}` : null,
    resultUrl: latestTraceId ? `/v1/agent/chat/result/${encodeURIComponent(latestTraceId)}` : null,
    runnerTrace,
    valuesRedacted: true,
    secretMaterialStored: false
  });
}

async function codeAgentInspectResultEvidence(traceId, options = {}) {
  if (!safeTraceId(traceId)) return { session: null, conversationFacts: null, latestTraceId: null };
  const cached = options.codeAgentChatResults?.get?.(traceId) ?? null;
  const persisted = cached ? null : await loadPersistedAgentRunResult(traceId, options);
  const result = cached ?? persisted ?? null;
  if (!result || typeof result !== "object") return { session: null, conversationFacts: null, latestTraceId: null };
  const agentRun = result.agentRun && typeof result.agentRun === "object" ? result.agentRun : null;
  const resultSession = result.session && typeof result.session === "object" ? result.session : null;
  const sessionReuse = result.sessionReuse && typeof result.sessionReuse === "object" ? result.sessionReuse : null;
  const providerTrace = result.providerTrace && typeof result.providerTrace === "object" ? result.providerTrace : null;
  const sessionId = safeSessionId(result.sessionId ?? resultSession?.sessionId ?? sessionReuse?.sessionId ?? agentRun?.sessionId) || null;
  const conversationId = safeConversationId(result.conversationId ?? resultSession?.conversationId ?? sessionReuse?.conversationId ?? agentRun?.conversationId) || null;
  const threadId = safeOpaqueId(result.threadId ?? resultSession?.threadId ?? sessionReuse?.threadId ?? providerTrace?.threadId ?? agentRun?.threadId) || null;
  const status = textValue(resultSession?.status ?? result.status ?? agentRun?.status) || null;
  const updatedAt = textValue(result.updatedAt ?? agentRun?.updatedAt ?? resultSession?.updatedAt) || null;
  const session = sessionId || conversationId || threadId ? {
    sessionId,
    conversationId,
    threadId,
    status,
    lastTraceId: traceId,
    source: "code-agent-result",
    agentRun: agentRun ? agentRunSessionEvidence(result).agentRun : null,
    valuesRedacted: true,
    secretMaterialStored: false
  } : null;
  const conversationFacts = conversationId ? {
    conversationId,
    sessionId,
    threadId,
    latestTraceId: traceId,
    traceIds: [traceId],
    turnCount: 1,
    source: "code-agent-result",
    latestStatus: status,
    updatedAt,
    valuesRedacted: true,
    secretMaterialStored: false
  } : null;
  return { session, conversationFacts, latestTraceId: traceId };
}

function sessionMatchesInspectQuery(session, query) {
  if (!session || typeof session !== "object") return false;
  if (query.sessionId && session.sessionId === query.sessionId) return true;
  if (query.threadId && session.threadId === query.threadId) return true;
  if (query.conversationId && session.conversationId === query.conversationId) return true;
  if (query.traceId && (session.currentTraceId === query.traceId || session.lastTraceId === query.traceId)) return true;
  return false;
}

export async function handleCodeAgentCancelHttp(request, response, options) {
  const body = await readBody(request, options.bodyLimitBytes);
  let params = {};

  try {
    params = body ? JSON.parse(body) : {};
  } catch (error) {
    sendJson(response, 400, {
      ...createCodeAgentErrorPayload({
        code: "parse_error",
        message: "Invalid JSON body",
        reason: error.message,
        traceId: getHeader(request, "x-trace-id") || "trc_unassigned",
        layer: "api",
        retryable: true
      })
    });
    return;
  }

  if (!params || typeof params !== "object" || Array.isArray(params)) {
    sendJson(response, 400, {
      ...createCodeAgentErrorPayload({
        code: "invalid_params",
        message: "Code Agent cancel body must be a JSON object",
        traceId: getHeader(request, "x-trace-id") || "trc_unassigned",
        layer: "api",
        retryable: true
      })
    });
    return;
  }

  const traceId = safeTraceId(getHeader(request, "x-trace-id") || params.traceId);
  const traceStore = options.traceStore ?? defaultCodeAgentTraceStore;
  const snapshot = traceId ? traceStore.snapshot(traceId) : null;
  const durableResult = traceId ? await loadPersistedAgentRunResult(traceId, options) : null;
  const currentResult = durableResult ?? (traceId ? options.codeAgentChatResults?.get(traceId) : null);
  if (currentResult?.agentRun?.commandId) {
    const mismatch = codeAgentCancelScopeMismatch(params, currentResult);
    if (mismatch) {
      traceStore.append(traceId, {
        type: "cancel",
        status: "blocked",
        label: "agentrun:cancel:scope_mismatch",
        errorCode: "cancel_scope_mismatch",
        message: `Cancel request ${mismatch.field} does not match the trace owner; AgentRun cancel was not forwarded.`,
        requested: mismatch.requested,
        expected: mismatch.expected,
        waitingFor: "cancel-scope",
        valuesPrinted: false
      });
      sendJson(response, 409, cancelBlockedPayload({
        code: "cancel_scope_mismatch",
        message: `取消请求的 ${mismatch.field} 与 trace 归属不一致，已拒绝转发 AgentRun cancel，避免误取消其他 session。`,
        traceId,
        conversationId: safeConversationId(params.conversationId) || safeConversationId(currentResult.conversationId) || null,
        sessionId: safeSessionId(params.sessionId) || safeSessionId(currentResult.sessionId) || null,
        runnerTrace: traceStore.snapshot(traceId),
        status: "blocked"
      }));
      return;
    }
    await recordCodeAgentSessionInputFact({
      params: {
        ...params,
        sessionId: currentResult.sessionId ?? currentResult.session?.sessionId ?? params.sessionId,
        messageId: codeAgentTurnLifecycleFields(traceId, currentResult).userMessageId,
        ownerUserId: options.actor?.id,
        ownerRole: options.actor?.role
      },
      options,
      traceId,
      delivery: "cancel",
      status: "promoted",
      commandId: currentResult.agentRun.commandId
    });
    const payload = await cancelAgentRunChatTurn({ traceId, currentResult, options, traceStore });
    if (payload) {
      sendJson(response, 200, payload);
      return;
    }
  }
  const sessionId = safeSessionId(params.sessionId) || safeSessionId(snapshot?.sessionId);
  const conversationId = safeConversationId(params.conversationId);
  const manager = options.codexStdioManager;

  if (!traceId) {
    sendJson(response, 400, cancelBlockedPayload({
      code: "cancel_trace_missing",
      message: "traceId is required to cancel the current Code Agent request.",
      traceId: "trc_unassigned",
      conversationId,
      sessionId
    }));
    return;
  }

  if (!manager || typeof manager.get !== "function" || typeof manager.cancel !== "function") {
    traceStore.append(traceId, {
      type: "cancel",
      status: "unsupported",
      label: "cancel:unsupported",
      errorCode: "cancel_unsupported",
      message: "Codex stdio cancel/interrupt backend is not available on this runtime.",
      waitingFor: "session-control"
    });
    const runnerTrace = traceStore.snapshot(traceId);
    sendJson(response, 501, cancelBlockedPayload({
      code: "cancel_unsupported",
      message: "当前后端不支持 Code Agent interrupt/cancel；本次按 unsupported/degraded 返回，不会静默假装已中断。",
      traceId,
      conversationId,
      sessionId,
      runnerTrace,
      status: "degraded",
      unsupported: true,
      degraded: true
    }));
    return;
  }

  if (!sessionId) {
    traceStore.append(traceId, {
      type: "cancel",
      status: "blocked",
      label: "cancel:not_cancelable",
      errorCode: "cancel_session_missing",
      message: "Cancel request did not include a bound Codex stdio sessionId.",
      waitingFor: "session-binding"
    });
    sendJson(response, 409, cancelBlockedPayload({
      code: "cancel_session_missing",
      message: "当前请求尚未暴露可取消的 Codex stdio sessionId；页面不能只隐藏 UI，已保留输入和 trace。",
      traceId,
      conversationId,
      sessionId: null,
      runnerTrace: traceStore.snapshot(traceId)
    }));
    return;
  }

  const currentSession = manager.get(sessionId, { conversationId }) ?? null;
  if (!currentSession || !["busy", "creating"].includes(currentSession.status)) {
    traceStore.append(traceId, {
      type: "cancel",
      status: "blocked",
      label: "cancel:not_in_flight",
      errorCode: "cancel_not_in_flight",
      message: `Session ${sessionId} is not an in-flight Codex stdio request.`,
      sessionId,
      sessionStatus: currentSession?.status ?? "missing"
    });
    sendJson(response, 409, cancelBlockedPayload({
      code: currentSession ? "cancel_not_in_flight" : "cancel_session_not_found",
      message: currentSession
        ? `当前 session 状态为 ${currentSession.status}，没有可取消的 in-flight Codex stdio 请求。`
        : `没有找到 sessionId=${sessionId} 的 Codex stdio session。`,
      traceId,
      conversationId,
      sessionId,
      session: currentSession,
      runnerTrace: traceStore.snapshot(traceId)
    }));
    return;
  }

  const canceledSession = manager.cancel(sessionId, {
    traceId,
    conversationId,
    reason: "user_cancel"
  });
  traceStore.append(traceId, {
    type: "cancel",
    status: "canceled",
    label: "cancel:canceled",
    message: "User canceled the current Codex stdio request.",
    sessionId,
    sessionStatus: canceledSession?.status ?? "canceled",
    sessionLifecycleStatus: codeAgentSessionLifecycleSummary({ session: canceledSession, status: "canceled" }).status,
    waitingFor: "user-retry",
    terminal: true
  });
  const runnerTraceSnapshot = traceStore.snapshot(traceId);
  const sessionSummary = codeAgentSessionLifecycleSummary({
    session: canceledSession,
    runnerTrace: runnerTraceSnapshot,
    status: "canceled"
  });
  const runnerTrace = {
    ...runnerTraceSnapshot,
    sessionLifecycleStatus: sessionSummary.status
  };
  const payload = {
    accepted: true,
    canceled: true,
    status: "canceled",
    conversationId: conversationId ?? canceledSession?.conversationId ?? null,
    sessionId,
    traceId,
    session: canceledSession,
    sessionLifecycleStatus: sessionSummary.status,
    sessionLifecycle: sessionSummary,
    sessionSummary,
    runnerTrace,
    lastTraceEvent: runnerTrace.lastEvent,
    retryable: true,
    error: {
      code: "codex_stdio_canceled",
      layer: "session",
      category: "canceled",
      retryable: true,
      message: "user canceled current Code Agent request",
      userMessage: "当前 Codex stdio 请求已取消；输入、sessionId、traceId 和最后 trace event 已保留，可重试上一条消息。",
      traceId,
      route: "/v1/agent/chat/cancel",
      toolName: "codex-stdio.cancel"
    },
    userMessage: "当前 Codex stdio 请求已取消；输入、sessionId、traceId 和最后 trace event 已保留，可重试上一条消息。",
    updatedAt: new Date().toISOString()
  };
  await recordCodeAgentSessionOwner({ payload, params: { ...params, traceId, ownerUserId: options.actor?.id, ownerRole: options.actor?.role }, options, status: "canceled" });
  recordCodeAgentConversationFact(payload, options);
  options.codeAgentChatResults?.set(traceId, annotateOwner(payload, { ownerUserId: options.actor?.id, ownerRole: options.actor?.role }));
  sendJson(response, 200, payload);
}

export { codeAgentCompatProjectionPayload, codeAgentRequestScopedOptions, measureCodeAgentHttpPhase, readCodeAgentCompatProjection, traceProjectMismatchSnapshot };
