flare-chat-core 0.2.1 → 0.2.2

package/src/chat-core/stream/sse-events.js

@@ -1,867 +1 @@
-/**
- * SSE 事件规范化层
- */
-
-/**
- * @typedef {'thinking'|'searching'|'generating'|'completed'|string} AgentStatusType
- *
- * @typedef {Object} AgentStatusPayload
- * @property {string} agent
- * @property {AgentStatusType} status
- * @property {number|null} timestamp
- *
- * @typedef {Object} ThinkingTracePayload
- * @property {string} trace
- *
- * @typedef {Object} ExecutionSourcePayload
- * @property {string} source_type
- * @property {string} source_label
- * @property {string} title
- *
- * @typedef {Object} ExecutionTracePayload
- * @property {string} session_id
- * @property {string} step_id
- * @property {string} agent
- * @property {string} stage
- * @property {string} label
- * @property {string} detail
- * @property {string} reason
- * @property {string} status
- * @property {Array<ExecutionSourcePayload>} sources
- * @property {number|null} timestamp
- *
- * @typedef {Object} ContentPayload
- * @property {string} chunk
- *
- * @typedef {Object} TracePayload
- * @property {string} trace
- * @property {string} summary
- * @property {string} agent
- *
- * @typedef {Object} FieldSource
- * @property {number|null} confidence
- *
- * @typedef {Object} FieldProgressPayload
- * @property {Record<string, string>} fields
- * @property {Record<string, FieldSource>} sources
- * @property {number|null} progress
- * @property {Array<string>} collected
- * @property {Array<string>} missing
- * @property {Object|null} last_field
- * @property {string|null} refresh_reason
- *
- * @typedef {Object} DocPayload
- * @property {Object|null} doc
- *
- * @typedef {Object} CapabilitySuggestionPayload
- * @property {string} type
- * @property {string} reason
- * @property {string} benefit
- * @property {number} confidence
- * @property {number} estimated_cost
- *
- * @typedef {Object} ModeArtifactPayload
- * @property {string} mode_key
- * @property {string|null} project_id
- * @property {string} message_excerpt
- * @property {string} render_hint
- *
- * @typedef {Object} FieldDefinition
- * @property {string} id
- * @property {string} label
- * @property {string} priority
- *
- * @typedef {Object} FieldsUpdatedPayload
- * @property {number} total_fields
- * @property {number} base_fields
- * @property {number} category_fields
- * @property {Array<FieldDefinition>} new_fields
- * @property {string|null} refresh_reason
- *
- * @typedef {Object} WorkspaceActivationPayload
- * @property {string} function_type
- * @property {string} mode
- * @property {string} title
- * @property {boolean} trace_in_chat
- * @property {string} right_panel
- * @property {boolean} knowledge_base_available
- *
- * @typedef {Object} UICardActionPayload
- * @property {string} type
- * @property {Record<string, unknown>} payload
- *
- * @typedef {Object} UICardPayload
- * @property {string} id
- * @property {string} kind
- * @property {string} title
- * @property {string} description
- * @property {boolean} available
- * @property {string} status
- * @property {string} reason
- * @property {UICardActionPayload|null} action
- *
- * @typedef {Object} UICardsPayload
- * @property {string} scope
- * @property {Array<UICardPayload>} cards
- *
- * @typedef {Object} KnowledgeBaseStatePayload
- * @property {boolean} enabled
- * @property {string} status
- * @property {string} label
- * @property {string} message
- *
- * @typedef {Object} CategoryIdentifiedPayload
- * @property {string} category
- * @property {number|null} confidence
- *
- * @typedef {Object} SSEErrorPayload
- * @property {string} message
- */
-
-export const parseAgentStatus = (raw) => ({
-  agent: raw?.agent ?? '',
-  status: raw?.status ?? '',
-  timestamp: raw?.timestamp ?? null,
-});
-
-export const parseThinkingTrace = (raw) => ({
-  trace: raw?.trace ?? '',
-});
-
-export const parseExecutionTrace = (raw) => ({
-  session_id: raw?.session_id ?? '',
-  step_id: raw?.step_id ?? '',
-  agent: raw?.agent ?? '',
-  stage: raw?.stage ?? '',
-  label: raw?.label ?? '',
-  detail: raw?.detail ?? raw?.trace ?? '',
-  reason: raw?.reason ?? '',
-  status: raw?.status ?? raw?.step_status ?? '',
-  sources: Array.isArray(raw?.sources) ? raw.sources : [],
-  timestamp: raw?.timestamp ?? null,
-});
-
-export const parseContent = (raw) => ({
-  chunk: raw?.content ?? '',
-});
-
-export const parseAck = (raw) => ({
-  trace_id: String(raw?.trace_id || '').trim(),
-  session_id: String(raw?.session_id || '').trim(),
-  request_id: String(raw?.request_id || '').trim(),
-  mode: String(raw?.mode || '').trim(),
-  ts: Number.isFinite(Number(raw?.ts)) ? Number(raw.ts) : null,
-});
-
-export const parsePhaseEvent = (raw) => ({
-  phase: String(raw?.phase || '').trim(),
-  label: String(raw?.label || '').trim(),
-  status: String(raw?.status || '').trim(),
-  progress: Number.isFinite(Number(raw?.progress)) ? Number(raw.progress) : null,
-  meta: raw?.meta && typeof raw.meta === 'object' && !Array.isArray(raw.meta) ? raw.meta : {},
-  ts: Number.isFinite(Number(raw?.ts)) ? Number(raw.ts) : null,
-});
-
-export const parsePatch = (raw) => ({
-  scope: String(raw?.scope || '').trim(),
-  payload: raw?.payload && typeof raw.payload === 'object' && !Array.isArray(raw.payload) ? raw.payload : {},
-  ts: Number.isFinite(Number(raw?.ts)) ? Number(raw.ts) : null,
-});
-
-export const parseTextDelta = (raw) => ({
-  channel: String(raw?.channel || 'assistant').trim() || 'assistant',
-  delta: String(raw?.delta || ''),
-  ts: Number.isFinite(Number(raw?.ts)) ? Number(raw.ts) : null,
-});
-
-export const parseTextReplace = (raw) => ({
-  channel: String(raw?.channel || 'assistant').trim() || 'assistant',
-  content: String(raw?.content || ''),
-  ts: Number.isFinite(Number(raw?.ts)) ? Number(raw.ts) : null,
-});
-
-export const parseDone = (raw) => ({
-  trace_id: String(raw?.trace_id || '').trim(),
-  session_id: String(raw?.session_id || '').trim(),
-  request_id: String(raw?.request_id || '').trim(),
-  status: String(raw?.status || 'done').trim() || 'done',
-  ts: Number.isFinite(Number(raw?.ts)) ? Number(raw.ts) : null,
-});
-
-export const parseTrace = (raw) => ({
-  trace: raw?.trace ?? raw?.detail ?? '',
-  summary: raw?.summary ?? raw?.label ?? '',
-  agent: raw?.agent ?? '',
-});
-
-function resolveModeEventPayload(raw) {
-  if (raw?.payload && typeof raw.payload === 'object' && !Array.isArray(raw.payload)) {
-    return raw.payload;
-  }
-
-  return raw && typeof raw === 'object' ? raw : {};
-}
-
-function pickFirstArray(payload, keys) {
-  for (const key of keys) {
-    const value = payload?.[key];
-    if (Array.isArray(value)) {
-      return value;
-    }
-  }
-  return [];
-}
-
-function parseGuidedSession(rawGuidedSession) {
-  const payload = (rawGuidedSession && typeof rawGuidedSession === 'object' && !Array.isArray(rawGuidedSession))
-    ? rawGuidedSession
-    : {};
-  const questionQueue = (payload.question_queue && typeof payload.question_queue === 'object' && !Array.isArray(payload.question_queue))
-    ? payload.question_queue
-    : {};
-  const summary = (payload.summary && typeof payload.summary === 'object' && !Array.isArray(payload.summary))
-    ? payload.summary
-    : {};
-  const decisionPoint = (payload.decision_point && typeof payload.decision_point === 'object' && !Array.isArray(payload.decision_point))
-    ? payload.decision_point
-    : {};
-  return {
-    state: payload?.state ?? '',
-    active: payload?.active === true,
-    current_question: payload?.current_question && typeof payload.current_question === 'object' && !Array.isArray(payload.current_question)
-      ? payload.current_question
-      : null,
-    question_queue: {
-      total: Number.isFinite(Number(questionQueue?.total)) ? Number(questionQueue.total) : 0,
-      answered: Number.isFinite(Number(questionQueue?.answered)) ? Number(questionQueue.answered) : 0,
-      remaining: Number.isFinite(Number(questionQueue?.remaining)) ? Number(questionQueue.remaining) : 0,
-      pending_fields: Array.isArray(questionQueue?.pending_fields) ? questionQueue.pending_fields : [],
-    },
-    summary: {
-      text: summary?.text ?? '',
-      ready: summary?.ready === true,
-    },
-    decision_point: {
-      active: decisionPoint?.active === true,
-      actions: Array.isArray(decisionPoint?.actions) ? decisionPoint.actions : [],
-    },
-  };
-}
-
-export const parseFieldProgress = (raw) => {
-  const payload = resolveModeEventPayload(raw);
-  return {
-    intake_session_id: payload?.intake_session_id ?? '',
-    intake_session_state: payload?.intake_session_state ?? '',
-    intake_session_completed: payload?.intake_session_completed === true,
-    flow_state: payload?.flow_state ?? payload?.collection_phase ?? '',
-    fields: payload?.fields ?? {},
-    sources: payload?.sources ?? {},
-    field_entries: Array.isArray(payload?.field_entries) ? payload.field_entries : [],
-    field_groups: payload?.field_groups && typeof payload.field_groups === 'object' && !Array.isArray(payload.field_groups)
-      ? payload.field_groups
-      : {},
-    extra_fields: Array.isArray(payload?.extra_fields) ? payload.extra_fields : [],
-    progress: payload?.progress ?? null,
-    required_progress: payload?.required_progress ?? null,
-    recommended_progress: payload?.recommended_progress ?? null,
-    optional_progress: payload?.optional_progress ?? null,
-    collected: Array.isArray(payload?.collected) ? payload.collected : [],
-    missing: Array.isArray(payload?.missing) ? payload.missing : [],
-    required_collected: Array.isArray(payload?.required_collected) ? payload.required_collected : [],
-    required_missing: Array.isArray(payload?.required_missing) ? payload.required_missing : [],
-    recommended_collected: Array.isArray(payload?.recommended_collected) ? payload.recommended_collected : [],
-    recommended_missing: Array.isArray(payload?.recommended_missing) ? payload.recommended_missing : [],
-    optional_collected: Array.isArray(payload?.optional_collected) ? payload.optional_collected : [],
-    optional_missing: Array.isArray(payload?.optional_missing) ? payload.optional_missing : [],
-    last_field: payload?.last_field ?? null,
-    refresh_reason: payload?.refresh_reason ?? null,
-    field_definitions: Array.isArray(payload?.field_definitions) ? payload.field_definitions : [],
-    required_fields: Array.isArray(payload?.required_fields) ? payload.required_fields : [],
-    recommended_fields: Array.isArray(payload?.recommended_fields) ? payload.recommended_fields : [],
-    optional_fields: Array.isArray(payload?.optional_fields) ? payload.optional_fields : [],
-    intake_core_fields: Array.isArray(payload?.intake_core_fields) ? payload.intake_core_fields : [],
-    intake_supplementary_fields: Array.isArray(payload?.intake_supplementary_fields) ? payload.intake_supplementary_fields : [],
-    analysis_enrichment_fields: Array.isArray(payload?.analysis_enrichment_fields) ? payload.analysis_enrichment_fields : [],
-    field_priorities: payload?.field_priorities && typeof payload.field_priorities === 'object' && !Array.isArray(payload.field_priorities)
-      ? payload.field_priorities
-      : {},
-    current_question: payload?.current_question && typeof payload.current_question === 'object' && !Array.isArray(payload.current_question)
-      ? payload.current_question
-      : null,
-    question_progress: payload?.question_progress && typeof payload.question_progress === 'object' && !Array.isArray(payload.question_progress)
-      ? payload.question_progress
-      : { current: 0, total: 0 },
-    collection_phase: payload?.collection_phase ?? '',
-    required_missing_count: Number.isFinite(payload?.required_missing_count) ? payload.required_missing_count : null,
-    required_coverage: Number.isFinite(Number(payload?.required_coverage)) ? Number(payload.required_coverage) : 0,
-    total_coverage: Number.isFinite(Number(payload?.total_coverage)) ? Number(payload.total_coverage) : 0,
-    analysis_entry_threshold: Number.isFinite(Number(payload?.analysis_entry_threshold)) ? Number(payload.analysis_entry_threshold) : 0.8,
-    analysis_entry_eligible: payload?.analysis_entry_eligible === true,
-    active_collecting: payload?.active_collecting === true,
-    ready_for_submit: payload?.ready_for_submit === true,
-    decision_point_active: payload?.decision_point_active === true,
-    has_active_question: payload?.has_active_question === true,
-    guided_session: parseGuidedSession(payload?.guided_session),
-  };
-};
-
-export const parseDoc = (raw) => ({
-  doc: raw?.doc ?? null,
-});
-
-export const parseCapabilitySuggestion = (raw) => ({
-  type: raw?.type ?? '',
-  reason: raw?.reason ?? '',
-  benefit: raw?.benefit ?? '',
-  confidence: raw?.confidence ?? 0,
-  estimated_cost: raw?.estimated_cost ?? 0,
-});
-
-export const parseRequirementDraft = (raw) => {
-  const payload = resolveModeEventPayload(raw);
-  const draft = payload?.draft && typeof payload.draft === 'object' && !Array.isArray(payload.draft)
-    ? payload.draft
-    : {};
-
-  return {
-    intake_session_id: payload?.intake_session_id ?? '',
-    intake_session_state: payload?.intake_session_state ?? '',
-    intake_session_completed: payload?.intake_session_completed === true,
-    mode_key: payload?.mode_key ?? '',
-    project_id: payload?.project_id ?? null,
-    message_excerpt: payload?.message_excerpt ?? '',
-    draft: {
-      ...draft,
-      fields: Array.isArray(draft.fields) ? draft.fields : [],
-    },
-    render_hint: payload?.render_hint ?? 'requirement_draft',
-  };
-};
-
-export const parseNextActions = (raw) => {
-  const payload = resolveModeEventPayload(raw);
-  const actions = Array.isArray(payload?.actions)
-    ? payload.actions
-    : (Array.isArray(payload?.next_actions) ? payload.next_actions : []);
-  return {
-    intake_session_id: payload?.intake_session_id ?? '',
-    intake_session_state: payload?.intake_session_state ?? '',
-    intake_session_completed: payload?.intake_session_completed === true,
-    mode_key: payload?.mode_key ?? '',
-    flow_state: payload?.flow_state ?? payload?.collection_phase ?? '',
-    project_id: payload?.project_id ?? null,
-    message_excerpt: payload?.message_excerpt ?? '',
-    actions,
-    completion_state: payload?.completion_state ?? '',
-    required_missing: Array.isArray(payload?.required_missing) ? payload.required_missing : [],
-    recommended_missing: Array.isArray(payload?.recommended_missing) ? payload.recommended_missing : [],
-    optional_missing: Array.isArray(payload?.optional_missing) ? payload.optional_missing : [],
-    intake_core_fields: Array.isArray(payload?.intake_core_fields) ? payload.intake_core_fields : [],
-    intake_supplementary_fields: Array.isArray(payload?.intake_supplementary_fields) ? payload.intake_supplementary_fields : [],
-    analysis_enrichment_fields: Array.isArray(payload?.analysis_enrichment_fields) ? payload.analysis_enrichment_fields : [],
-    ready_for_sourcing: payload?.ready_for_sourcing ?? null,
-    status: payload?.status ?? '',
-    reason: payload?.reason ?? '',
-    chooser_required: payload?.chooser_required === true,
-    blocking_reason: payload?.blocking_reason ?? '',
-    blocking: payload?.blocking && typeof payload.blocking === 'object' && !Array.isArray(payload.blocking)
-      ? payload.blocking
-      : null,
-    target_field: payload?.target_field ?? '',
-    degrade_reason: Array.isArray(payload?.degrade_reason) ? payload.degrade_reason : [],
-    current_question: payload?.current_question && typeof payload.current_question === 'object' && !Array.isArray(payload.current_question)
-      ? payload.current_question
-      : null,
-    question_progress: payload?.question_progress && typeof payload.question_progress === 'object' && !Array.isArray(payload.question_progress)
-      ? payload.question_progress
-      : { current: 0, total: 0 },
-    collection_phase: payload?.collection_phase ?? '',
-    required_missing_count: Number.isFinite(payload?.required_missing_count) ? payload.required_missing_count : null,
-    render_hint: payload?.render_hint ?? 'next_actions',
-    required_coverage: Number.isFinite(Number(payload?.required_coverage)) ? Number(payload.required_coverage) : 0,
-    total_coverage: Number.isFinite(Number(payload?.total_coverage)) ? Number(payload.total_coverage) : 0,
-    analysis_entry_threshold: Number.isFinite(Number(payload?.analysis_entry_threshold)) ? Number(payload.analysis_entry_threshold) : 0.8,
-    analysis_entry_eligible: payload?.analysis_entry_eligible === true,
-    active_collecting: payload?.active_collecting === true,
-    ready_for_submit: payload?.ready_for_submit === true,
-    decision_point_active: payload?.decision_point_active === true,
-    has_active_question: payload?.has_active_question === true,
-    guided_session: parseGuidedSession(payload?.guided_session),
-  };
-};
-
-export const parseSourcingCandidates = (raw) => {
-  const payload = resolveModeEventPayload(raw);
-  const missing = pickFirstArray(payload, ['missing', 'base_missing', 'missing_fields', 'required_missing']);
-  return {
-    mode_key: payload?.mode_key ?? '',
-    project_id: payload?.project_id ?? null,
-    message_excerpt: payload?.message_excerpt ?? '',
-    missing,
-    base_fields: Array.isArray(payload?.base_fields) ? payload.base_fields : [],
-    base_collected: Array.isArray(payload?.base_collected) ? payload.base_collected : [],
-    base_missing: Array.isArray(payload?.base_missing) ? payload.base_missing : [],
-    base_total: Number.isFinite(payload?.base_total) ? payload.base_total : 0,
-    base_progress: Number.isFinite(payload?.base_progress) ? payload.base_progress : null,
-    base_ready_for_matching: payload?.base_ready_for_matching === true,
-    mode_state: payload?.mode_state ?? '',
-    candidate_count: Number.isFinite(payload?.candidate_count) ? payload.candidate_count : null,
-    is_placeholder: payload?.is_placeholder ?? null,
-    required_missing: Array.isArray(payload?.required_missing) ? payload.required_missing : [],
-    recommended_missing: Array.isArray(payload?.recommended_missing) ? payload.recommended_missing : [],
-    optional_missing: Array.isArray(payload?.optional_missing) ? payload.optional_missing : [],
-    actions: Array.isArray(payload?.actions) ? payload.actions : [],
-    candidates: pickFirstArray(payload, ['candidates', 'sourcing_candidates', 'candidate_list', 'results']),
-    reasoning: Array.isArray(payload?.reasoning) ? payload.reasoning : [],
-    summary: payload?.sourcing_summary ?? payload?.summary ?? null,
-    render_hint: payload?.render_hint ?? 'sourcing_candidates',
-  };
-};
-
-export const parseRiskSummary = (raw) => {
-  const payload = resolveModeEventPayload(raw);
-  const risks = pickFirstArray(payload, ['risks', 'risk_items', 'items', 'risk_list']);
-  const sources = pickFirstArray(payload, ['sources', 'references', 'evidence']);
-  return {
-    mode_key: payload?.mode_key ?? '',
-    project_id: payload?.project_id ?? null,
-    message_excerpt: payload?.message_excerpt ?? '',
-    mode_state: payload?.mode_state ?? '',
-    base_fields: Array.isArray(payload?.base_fields) ? payload.base_fields : [],
-    base_collected: Array.isArray(payload?.base_collected) ? payload.base_collected : [],
-    base_missing: Array.isArray(payload?.base_missing) ? payload.base_missing : [],
-    base_total: Number.isFinite(payload?.base_total) ? payload.base_total : 0,
-    base_progress: Number.isFinite(payload?.base_progress) ? payload.base_progress : null,
-    base_ready_for_matching: payload?.base_ready_for_matching === true,
-    is_placeholder: payload?.is_placeholder ?? null,
-    actions: Array.isArray(payload?.actions) ? payload.actions : [],
-    risks,
-    sources,
-    summary: payload?.risk_summary ?? payload?.summary ?? null,
-    render_hint: payload?.render_hint ?? 'risk_summary',
-  };
-};
-
-export const parseShortlistUpdated = (raw) => {
-  const payload = resolveModeEventPayload(raw);
-  const shortlist = pickFirstArray(payload, ['shortlist', 'shortlist_updated', 'selected_candidates', 'items']);
-  return {
-    mode_key: payload?.mode_key ?? '',
-    project_id: payload?.project_id ?? null,
-    message_excerpt: payload?.message_excerpt ?? '',
-    mode_state: payload?.mode_state ?? '',
-    base_fields: Array.isArray(payload?.base_fields) ? payload.base_fields : [],
-    base_collected: Array.isArray(payload?.base_collected) ? payload.base_collected : [],
-    base_missing: Array.isArray(payload?.base_missing) ? payload.base_missing : [],
-    base_total: Number.isFinite(payload?.base_total) ? payload.base_total : 0,
-    base_progress: Number.isFinite(payload?.base_progress) ? payload.base_progress : null,
-    base_ready_for_matching: payload?.base_ready_for_matching === true,
-    shortlist,
-    status: payload?.status ?? payload?.state ?? '',
-    reason: payload?.reason ?? payload?.message ?? '',
-    selected_count: Number.isFinite(payload?.selected_count) ? payload.selected_count : null,
-    is_placeholder: payload?.is_placeholder ?? null,
-    actions: Array.isArray(payload?.actions) ? payload.actions : [],
-    render_hint: payload?.render_hint ?? 'shortlist_updated',
-  };
-};
-
-export const parseEvaluationReportReady = (raw) => {
-  const payload = resolveModeEventPayload(raw);
-  const nestedReport = payload?.evaluation_report_ready
-    && typeof payload.evaluation_report_ready === 'object'
-    && !Array.isArray(payload.evaluation_report_ready)
-      ? payload.evaluation_report_ready
-      : {};
-  const reportSource = payload?.report
-    || nestedReport.report
-    || nestedReport;
-  const report = reportSource && typeof reportSource === 'object' && !Array.isArray(reportSource)
-    ? reportSource
-    : {};
-  const compareTable = pickFirstArray(payload, ['compare_table', 'comparison_table', 'compare_rows'])
-    || pickFirstArray(report, ['compare_table', 'comparison_table', 'compare_rows'])
-    || pickFirstArray(nestedReport, ['compare_table', 'comparison_table', 'compare_rows']);
-
-  return {
-    mode_key: payload?.mode_key ?? '',
-    project_id: payload?.project_id ?? null,
-    message_excerpt: payload?.message_excerpt ?? '',
-    mode_state: payload?.mode_state ?? '',
-    base_fields: Array.isArray(payload?.base_fields) ? payload.base_fields : [],
-    base_collected: Array.isArray(payload?.base_collected) ? payload.base_collected : [],
-    base_missing: Array.isArray(payload?.base_missing) ? payload.base_missing : [],
-    base_total: Number.isFinite(payload?.base_total) ? payload.base_total : 0,
-    base_progress: Number.isFinite(payload?.base_progress) ? payload.base_progress : null,
-    base_ready_for_matching: payload?.base_ready_for_matching === true,
-    is_placeholder: payload?.is_placeholder ?? null,
-    actions: Array.isArray(payload?.actions) ? payload.actions : [],
-    report: {
-      ...report,
-      sections: Array.isArray(report.sections) ? report.sections : [],
-    },
-    compare_table: payload?.compare_table
-      ?? payload?.comparison_table
-      ?? payload?.compare_rows
-      ?? report?.compare_table
-      ?? report?.comparison_table
-      ?? report?.compare_rows
-      ?? nestedReport?.compare_table
-      ?? nestedReport?.comparison_table
-      ?? nestedReport?.compare_rows
-      ?? compareTable,
-    render_hint: payload?.render_hint ?? 'evaluation_report_ready',
-  };
-};
-
-export const parsePlanBlock = (raw) => {
-  const payload = resolveModeEventPayload(raw);
-  return {
-    ...payload,
-    constraints: Array.isArray(payload?.constraints) ? payload.constraints : [],
-    plan: Array.isArray(payload?.plan) ? payload.plan : [],
-    acceptance: Array.isArray(payload?.acceptance) ? payload.acceptance : [],
-    actions: Array.isArray(payload?.actions) ? payload.actions : [],
-  };
-};
-
-export const parseCanvasState = (raw) => {
-  const payload = resolveModeEventPayload(raw);
-  const canvasState = payload?.canvas_state && typeof payload.canvas_state === 'object' && !Array.isArray(payload.canvas_state)
-    ? payload.canvas_state
-    : {};
-  return {
-    ...payload,
-    canvas_state: {
-      ...canvasState,
-      versions: Array.isArray(canvasState.versions) ? canvasState.versions : [],
-    },
-  };
-};
-
-export const parseCanvasRevision = (raw) => {
-  const payload = resolveModeEventPayload(raw);
-  return {
-    ...payload,
-    actions: Array.isArray(payload?.actions) ? payload.actions : [],
-  };
-};
-
-export const parseKnowledgeSearch = (raw) => {
-  const payload = resolveModeEventPayload(raw);
-  const sourceBreakdown = payload?.source_breakdown && typeof payload.source_breakdown === 'object'
-    && !Array.isArray(payload.source_breakdown)
-    ? payload.source_breakdown
-    : {};
-  return {
-    ...payload,
-    run_id: payload?.run_id ?? '',
-    query: payload?.query ?? '',
-    result_count: Number.isFinite(payload?.result_count) ? payload.result_count : null,
-    source_breakdown: {
-      local: Number.isFinite(sourceBreakdown.local) ? sourceBreakdown.local : 0,
-      mcp: Number.isFinite(sourceBreakdown.mcp) ? sourceBreakdown.mcp : 0,
-      web: Number.isFinite(sourceBreakdown.web) ? sourceBreakdown.web : 0,
-    },
-    results: Array.isArray(payload?.results) ? payload.results : [],
-  };
-};
-
-export const parseKnowledgeCitation = (raw) => {
-  const payload = resolveModeEventPayload(raw);
-  return {
-    ...payload,
-    run_id: payload?.run_id ?? '',
-    citations: Array.isArray(payload?.citations) ? payload.citations : [],
-  };
-};
-
-export const parseOrchestrationStatus = (raw) => {
-  const payload = resolveModeEventPayload(raw);
-  const activeWorkItem = payload?.active_work_item && typeof payload.active_work_item === 'object' && !Array.isArray(payload.active_work_item)
-    ? payload.active_work_item
-    : null;
-  return {
-    trace_id: payload?.trace_id ?? '',
-    intake_session_id: payload?.intake_session_id ?? '',
-    intake_session_state: payload?.intake_session_state ?? '',
-    intake_session_completed: payload?.intake_session_completed === true,
-    current_stage: payload?.current_stage ?? '',
-    detected_intent: payload?.detected_intent && typeof payload.detected_intent === 'object' && !Array.isArray(payload.detected_intent)
-      ? payload.detected_intent
-      : {},
-    confirmed_updates: Array.isArray(payload?.confirmed_updates) ? payload.confirmed_updates : [],
-    open_fields: Array.isArray(payload?.open_fields) ? payload.open_fields : [],
-    search_actions: Array.isArray(payload?.search_actions) ? payload.search_actions : [],
-    workspace_updates: payload?.workspace_updates && typeof payload.workspace_updates === 'object' && !Array.isArray(payload.workspace_updates)
-      ? payload.workspace_updates
-      : {},
-    next_action: payload?.next_action && typeof payload.next_action === 'object' && !Array.isArray(payload.next_action)
-      ? payload.next_action
-      : {},
-    next_actions: Array.isArray(payload?.next_actions) ? payload.next_actions : [],
-    active_collecting: payload?.active_collecting === true,
-    ready_for_submit: payload?.ready_for_submit === true,
-    required_coverage: Number.isFinite(Number(payload?.required_coverage)) ? Number(payload.required_coverage) : 0,
-    total_coverage: Number.isFinite(Number(payload?.total_coverage)) ? Number(payload.total_coverage) : 0,
-    analysis_entry_threshold: Number.isFinite(Number(payload?.analysis_entry_threshold)) ? Number(payload.analysis_entry_threshold) : 0.8,
-    analysis_entry_eligible: payload?.analysis_entry_eligible === true,
-    decision_point_active: payload?.decision_point_active === true,
-    has_active_question: payload?.has_active_question === true,
-    guided_session: parseGuidedSession(payload?.guided_session),
-    active_work_item: activeWorkItem,
-    active_fields: Array.isArray(payload?.active_fields) ? payload.active_fields : [],
-    hypotheses: Array.isArray(payload?.hypotheses) ? payload.hypotheses : [],
-    planner: payload?.planner && typeof payload.planner === 'object' && !Array.isArray(payload.planner)
-      ? payload.planner
-      : {},
-    chooser: payload?.chooser && typeof payload.chooser === 'object' && !Array.isArray(payload.chooser)
-      ? payload.chooser
-      : null,
-    stage_transition: payload?.stage_transition && typeof payload.stage_transition === 'object' && !Array.isArray(payload.stage_transition)
-      ? payload.stage_transition
-      : {},
-    decision_basis: Array.isArray(payload?.decision_basis) ? payload.decision_basis : [],
-    blocking: payload?.blocking && typeof payload.blocking === 'object' && !Array.isArray(payload.blocking)
-      ? payload.blocking
-      : {},
-    node: payload?.node && typeof payload.node === 'object' && !Array.isArray(payload.node)
-      ? payload.node
-      : {},
-    node_id: payload?.node_id ?? '',
-    node_state: payload?.node_state ?? '',
-    node_reason: payload?.node_reason ?? '',
-    needs_user_choice: payload?.needs_user_choice === true,
-    conversation_intent_state: payload?.conversation_intent_state ?? '',
-    session_intent_stage: payload?.session_intent_stage ?? '',
-    intent_type: payload?.intent_type ?? '',
-    procurement_relevance: payload?.procurement_relevance === true,
-    consultative_procurement_qa: payload?.consultative_procurement_qa === true,
-    escalation_target: payload?.escalation_target ?? '',
-    intake_candidate: payload?.intake_candidate === true,
-    clarification_recommended: payload?.clarification_recommended === true,
-    analysis_ready: payload?.analysis_ready === true,
-    draft_seeded: payload?.draft_seeded === true,
-    missing_key_fields: Array.isArray(payload?.missing_key_fields) ? payload.missing_key_fields : [],
-    recommended_next_step: payload?.recommended_next_step ?? '',
-    intent_and_escalation_confidence: Number.isFinite(Number(payload?.intent_and_escalation_confidence))
-      ? Number(payload.intent_and_escalation_confidence)
-      : 0,
-    intent_and_escalation_reason: payload?.intent_and_escalation_reason ?? '',
-    intent_escalation_policy: payload?.intent_escalation_policy && typeof payload.intent_escalation_policy === 'object' && !Array.isArray(payload.intent_escalation_policy)
-      ? payload.intent_escalation_policy
-      : {},
-    intent_escalation_policy_source: payload?.intent_escalation_policy_source ?? '',
-    degrade_reason: Array.isArray(payload?.degrade_reason) ? payload.degrade_reason : [],
-    content_policy: payload?.content_policy && typeof payload.content_policy === 'object' && !Array.isArray(payload.content_policy)
-      ? payload.content_policy
-      : {},
-  };
-};
-
-export const parseWorkspaceActivation = (raw) => ({
-  function_type: raw?.function_type ?? '',
-  mode: raw?.mode ?? '',
-  title: raw?.title ?? '',
-  trace_in_chat: raw?.trace_in_chat === true,
-  right_panel: raw?.right_panel ?? '',
-  knowledge_base_available: raw?.knowledge_base_available === true,
-});
-
-export const parseUICards = (raw) => ({
-  scope: raw?.scope ?? 'conversation',
-  cards: Array.isArray(raw?.cards) ? raw.cards : [],
-});
-
-export const parseKnowledgeBaseState = (raw) => ({
-  enabled: raw?.enabled === true,
-  status: raw?.status ?? '',
-  label: raw?.label ?? '',
-  message: raw?.message ?? '',
-});
-
-export const parseCategoryIdentified = (raw) => ({
-  category: raw?.category ?? raw?.level3 ?? '',
-  confidence: raw?.confidence ?? null,
-});
-
-export const parseFieldsUpdated = (raw) => ({
-  total_fields: raw?.total_fields ?? 0,
-  base_fields: raw?.base_fields ?? 0,
-  category_fields: raw?.category_fields ?? 0,
-  new_fields: Array.isArray(raw?.new_fields) ? raw.new_fields : [],
-  refresh_reason: raw?.refresh_reason ?? null,
-});
-
-export const parseInstanceProfile = (raw) => ({
-  product_name: raw?.instance_profile?.product_name ?? raw?.product_name ?? '',
-  brand_tag: raw?.instance_profile?.brand_tag ?? raw?.brand_tag ?? '',
-  logo_text: raw?.instance_profile?.logo_text ?? raw?.logo_text ?? '',
-  logo_url: raw?.instance_profile?.logo_url ?? raw?.logo_url ?? '',
-  ui_labels: raw?.instance_profile?.ui_labels ?? raw?.ui_labels ?? {},
-});
-
-export const parseModeRuntime = (raw) => ({
-  mode_key: raw?.mode_key ?? '',
-  mode_state: raw?.mode_state ?? '',
-});
-
-export const parseAgentRuntime = (raw) => ({
-  trace_id: raw?.trace_id ?? '',
-  session_id: raw?.session_id ?? '',
-  intent: raw?.intent ?? '',
-  function_type: raw?.function_type ?? '',
-  mode_key: raw?.mode_key ?? '',
-  mode_state: raw?.mode_state ?? '',
-  agent_step_count: Number.isFinite(raw?.agent_step_count) ? raw.agent_step_count : 0,
-  agent_step: Array.isArray(raw?.agent_step) ? raw.agent_step : [],
-});
-
-export const parseSkillRuntime = (raw) => ({
-  trace_id: raw?.trace_id ?? '',
-  session_id: raw?.session_id ?? '',
-  intent: raw?.intent ?? '',
-  function_type: raw?.function_type ?? '',
-  mode_key: raw?.mode_key ?? '',
-  mode_state: raw?.mode_state ?? '',
-  skill_call_count: Number.isFinite(raw?.skill_call_count) ? raw.skill_call_count : 0,
-  skill_call: Array.isArray(raw?.skill_call) ? raw.skill_call : [],
-});
-
-export const parseModeSwitchReason = (raw) => ({
-  mode_key: raw?.mode_key ?? '',
-  intent: raw?.intent ?? '',
-  source: raw?.source ?? '',
-  previous_mode: raw?.previous_mode ?? '',
-  manual_mode: raw?.manual_mode ?? '',
-  current_mode: raw?.current_mode ?? '',
-  intent_override: raw?.intent_override ?? '',
-  summary: raw?.summary ?? '',
-});
-
-export const parseSSEError = (raw) => ({
-  message: raw?.message ?? '发生错误',
-});
-
-export const PATCH_SCOPE_AUTHORITATIVE = Object.freeze([
-  'session',
-  'assistant_reply',
-  'primary_flow',
-  'checkpoint',
-  'intent_state',
-  'question',
-  'confirmed_fields',
-  'missing_fields',
-  'next_actions',
-  'analysis',
-  'observation',
-  'capabilities.field_retrieval',
-  'errors',
-]);
-
-export const PATCH_SCOPE_LEGACY_COMPAT = Object.freeze([
-  'current_question',
-  'recommendation_summary',
-]);
-
-const PATCH_SCOPE_ALLOWLIST = new Set([
-  ...PATCH_SCOPE_AUTHORITATIVE,
-  ...PATCH_SCOPE_LEGACY_COMPAT,
-]);
-
-function getByScopePath(payload, scope) {
-  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
-    return undefined;
-  }
-  const segments = String(scope || '').split('.').filter(Boolean);
-  if (!segments.length) {
-    return undefined;
-  }
-  let current = payload;
-  for (const segment of segments) {
-    if (!current || typeof current !== 'object' || Array.isArray(current) || !(segment in current)) {
-      return undefined;
-    }
-    current = current[segment];
-  }
-  return current;
-}
-
-export const parsePatchEvent = (raw) => {
-  const envelope = (raw && typeof raw === 'object' && !Array.isArray(raw)) ? raw : {};
-  const patchScope = Array.isArray(envelope.patch_scope)
-    ? envelope.patch_scope.map((item) => String(item || '').trim()).filter(Boolean)
-    : [];
-  const payload = (envelope.payload && typeof envelope.payload === 'object' && !Array.isArray(envelope.payload))
-    ? envelope.payload
-    : {};
-  const hasPayload = Object.keys(payload).length > 0;
-  const hasUnknownScope = patchScope.some((item) => !(PATCH_SCOPE_ALLOWLIST.has(item) || item.startsWith('confirmed_fields.')));
-  const hasScopePayloadMismatch = patchScope.some((scope) => {
-    const direct = payload[scope];
-    const byPath = getByScopePath(payload, scope);
-    const lastSegment = String(scope).split('.').slice(-1)[0];
-    const leaf = payload[lastSegment];
-    return direct === undefined && byPath === undefined && leaf === undefined;
-  });
-  const legacyPatchScope = patchScope.filter((scope) => PATCH_SCOPE_LEGACY_COMPAT.includes(scope));
-  const authoritativePatchScope = patchScope.filter(
-    (scope) => PATCH_SCOPE_AUTHORITATIVE.includes(scope) || scope.startsWith('confirmed_fields.')
-  );
-  const invalidReason = (() => {
-    if (envelope.message_type !== 'patch_event') {
-      return 'invalid_message_type';
-    }
-    if (!['ack', 'patch', 'error', 'final'].includes(String(envelope.event_type || '').trim())) {
-      return 'invalid_event_type';
-    }
-    if (hasPayload && patchScope.length === 0) {
-      return 'payload_without_patch_scope';
-    }
-    if (hasUnknownScope) {
-      return 'unknown_patch_scope';
-    }
-    if (patchScope.length > 0 && hasScopePayloadMismatch) {
-      return 'patch_scope_payload_mismatch';
-    }
-    return '';
-  })();
-  return {
-    contract_version: String(envelope.contract_version || 'flare.v1'),
-    message_type: 'patch_event',
-    event_type: String(envelope.event_type || '').trim(),
-    sequence: Number.isFinite(Number(envelope.sequence)) ? Number(envelope.sequence) : 0,
-    trace_id: String(envelope.trace_id || '').trim(),
-    client_request_id: String(envelope.client_request_id || '').trim(),
-    intake_session_id: String(
-      payload?.primary_flow?.intake_session_id
-      || payload?.checkpoint?.intake_session_id
-      || payload?.next_actions?.intake_session_id
-      || payload?.question?.intake_session_id
-      || payload?.intake_session_id
-      || ''
-    ).trim(),
-    intake_session_state: String(
-      payload?.primary_flow?.intake_session_state
-      || payload?.next_actions?.intake_session_state
-      || payload?.intake_session_state
-      || ''
-    ).trim(),
-    intake_session_completed: Boolean(
-      payload?.primary_flow?.intake_session_completed
-      || payload?.next_actions?.intake_session_completed
-      || payload?.intake_session_completed
-    ),
-    session: (
-      envelope.session && typeof envelope.session === 'object' && !Array.isArray(envelope.session)
-    ) ? envelope.session : { session_id: '', turn_id: '' },
-    patch_scope: patchScope,
-    authoritative_patch_scope: authoritativePatchScope,
-    legacy_patch_scope: legacyPatchScope,
-    payload,
-    final: envelope.final === true,
-    invalid: Boolean(invalidReason),
-    invalid_reason: invalidReason,
-  };
-};
+export * from '../../contracts/sse-events.js';