flare-chat-core 0.2.0 → 0.2.2

package/src/contracts/sse-events/parsers-intake.js

@@ -0,0 +1,235 @@
+import {
+  normalizeAction,
+  normalizeActionList,
+  parseGuidedSession,
+  resolveModeEventPayload,
+} from './internal-normalizers.js';
+
+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 rawActions = Array.isArray(payload?.actions)
+    ? payload.actions
+    : (Array.isArray(payload?.next_actions) ? payload.next_actions : []);
+  const actions = normalizeActionList(rawActions);
+  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 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;
+  const nextAction = normalizeAction(payload?.next_action, 0);
+  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: nextAction,
+    next_actions: normalizeActionList(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 ?? '',
+    analysis_route: payload?.analysis_route && typeof payload.analysis_route === 'object' && !Array.isArray(payload.analysis_route)
+      ? payload.analysis_route
+      : {},
+    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
+      : {},
+  };
+};

package/src/contracts/sse-events/parsers-runtime.js

@@ -0,0 +1,37 @@
+import {
+  normalizeActionList,
+  resolveModeEventPayload,
+} from './internal-normalizers.js';
+
+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: normalizeActionList(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: normalizeActionList(payload?.actions),
+  };
+};

package/src/contracts/sse-events/parsers-sourcing.js

@@ -0,0 +1,179 @@
+import {
+  normalizeActionList,
+  pickFirstArray,
+  resolveModeEventPayload,
+} from './internal-normalizers.js';
+
+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 ?? '',
+    requested_top_k: Number.isFinite(Number(payload?.requested_top_k)) ? Number(payload.requested_top_k) : 8,
+    returned_count: Number.isFinite(Number(payload?.returned_count)) ? Number(payload.returned_count) : null,
+    has_more: payload?.has_more === true,
+    next_top_k: Number.isFinite(Number(payload?.next_top_k)) ? Number(payload.next_top_k) : null,
+    append_mode: payload?.append_mode === true,
+    lock_existing_order: payload?.lock_existing_order !== false,
+    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: normalizeActionList(payload?.actions),
+    candidates: pickFirstArray(payload, ['candidates', 'sourcing_candidates', 'candidate_list', 'results']),
+    new_results: pickFirstArray(payload, ['new_results']),
+    all_results: pickFirstArray(payload, ['all_results']),
+    source_meta: payload?.source_meta && typeof payload.source_meta === 'object' && !Array.isArray(payload.source_meta)
+      ? payload.source_meta
+      : {},
+    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: normalizeActionList(payload?.actions),
+    risks,
+    sources,
+    source_meta: payload?.source_meta && typeof payload.source_meta === 'object' && !Array.isArray(payload.source_meta)
+      ? payload.source_meta
+      : {},
+    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: normalizeActionList(payload?.actions),
+    source_meta: payload?.source_meta && typeof payload.source_meta === 'object' && !Array.isArray(payload.source_meta)
+      ? payload.source_meta
+      : {},
+    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_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: normalizeActionList(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,
+    source_meta: payload?.source_meta && typeof payload.source_meta === 'object' && !Array.isArray(payload.source_meta)
+      ? payload.source_meta
+      : {},
+    render_hint: payload?.render_hint ?? 'evaluation_report_ready',
+  };
+};
+
+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 : [],
+  };
+};

package/src/contracts/sse-events/patch-event-parser.js

@@ -0,0 +1,121 @@
+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,
+  };
+};

package/src/contracts/sse-events/runtime-parsers.js

@@ -0,0 +1,79 @@
+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 ?? '',
+});

package/src/contracts/sse-events.js

@@ -0,0 +1,4 @@
+export * from './sse-events/base-parsers.js';
+export * from './sse-events/runtime-parsers.js';
+export * from './sse-events/domain-parsers.js';
+export * from './sse-events/patch-event-parser.js';

package/src/index.js

@@ -1 +1,6 @@
 export * from './chat-core/index.js';
+export * from './app/index.js';
+export * from './state/index.js';
+export * from './orchestration/index.js';
+export * from './adapters/index.js';
+export * from './contracts/index.js';