flare-chat-core 0.2.1 → 0.2.3

package/src/chat-core/stream/useSSEStream.js

@@ -1,356 +1 @@
-import { useRef, useState, useCallback, useEffect } from 'react';
-import { SSEClient } from './sse-client.js';
-import {
-  parseAck,
-  parseAgentStatus,
-  parseThinkingTrace,
-  parseExecutionTrace,
-  parseContent,
-  parseDone,
-  parsePatch,
-  parsePhaseEvent,
-  parseTextDelta,
-  parseTextReplace,
-  parseTrace,
-  parseFieldProgress,
-  parseDoc,
-  parseRequirementDraft,
-  parseNextActions,
-  parseSourcingCandidates,
-  parseRiskSummary,
-  parseShortlistUpdated,
-  parseEvaluationReportReady,
-  parseWorkspaceActivation,
-  parseUICards,
-  parseKnowledgeBaseState,
-  parseCategoryIdentified,
-  parseCapabilitySuggestion,
-  parseFieldsUpdated,
-  parseInstanceProfile,
-  parseModeRuntime,
-  parseAgentRuntime,
-  parseSkillRuntime,
-  parseModeSwitchReason,
-  parseKnowledgeSearch,
-  parseKnowledgeCitation,
-  parseOrchestrationStatus,
-  parseCanvasState,
-  parseCanvasRevision,
-  parsePlanBlock,
-  parsePatchEvent,
-  parseSSEError,
-} from './sse-events.js';
-
-function classifyError(errorMessage) {
-  if (!errorMessage) return 'unknown';
-
-  const lowerMsg = errorMessage.toLowerCase();
-  if (lowerMsg.includes('network') || lowerMsg.includes('fetch')) return 'network';
-  if (lowerMsg.includes('timeout') || lowerMsg.includes('timed out')) return 'timeout';
-  if (/\b(500|502|503|504)\b/.test(lowerMsg)) return 'api';
-  return 'unknown';
-}
-
-export function useSSEStream(sessionId) {
-  const clientRef = useRef(new SSEClient());
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState(null);
-  const accumulatedRef = useRef('');
-  const lastMessageRef = useRef({ content: '', handlers: {} });
-
-  const send = useCallback(async (content, handlers = {}, options = {}) => {
-    const hasSessionOverride = Object.prototype.hasOwnProperty.call(options, 'sessionIdOverride');
-    const resolvedSessionId = hasSessionOverride ? options.sessionIdOverride : sessionId;
-    if (!content.trim()) return;
-
-    lastMessageRef.current = { content, handlers, options };
-    setError(null);
-    accumulatedRef.current = '';
-    setLoading(true);
-    let latestSessionId = String(resolvedSessionId || '').trim();
-
-    const {
-      onAck,
-      onAgentStatus,
-      onThinkingTrace,
-      onExecutionTrace,
-      onContent,
-      onTextReplace,
-      onPhaseStart,
-      onPhaseUpdate,
-      onPhaseEnd,
-      onPatch,
-      onDone,
-      onTrace,
-      onWorkspaceActivation,
-      onUICards,
-      onKnowledgeBaseState,
-      onFieldProgress,
-      onRequirementDraft,
-      onNextActions,
-      onSourcingCandidates,
-      onRiskSummary,
-      onShortlistUpdated,
-      onEvaluationReportReady,
-      onCategoryIdentified,
-      onFieldsUpdated,
-      onInstanceProfile,
-      onModeRuntime,
-      onAgentRuntime,
-      onSkillRuntime,
-      onModeSwitchReason,
-      onKnowledgeSearch,
-      onKnowledgeCitation,
-      onOrchestrationStatus,
-      onCanvasState,
-      onCanvasRevision,
-      onPlanBlock,
-      onDoc,
-      onCapabilitySuggestion,
-      onPatchEvent,
-      onError,
-      onComplete,
-    } = handlers;
-
-    const eventHandler = (event) => {
-      switch (event.type) {
-        case 'ack':
-          onAck?.(parseAck(event.data));
-          break;
-        case 'phase.start':
-          onPhaseStart?.(parsePhaseEvent(event.data));
-          break;
-        case 'phase.update':
-          onPhaseUpdate?.(parsePhaseEvent(event.data));
-          break;
-        case 'phase.end':
-          onPhaseEnd?.(parsePhaseEvent(event.data));
-          break;
-        case 'patch':
-          onPatch?.(parsePatch(event.data));
-          break;
-        case 'agent_status':
-          onAgentStatus?.(parseAgentStatus(event.data));
-          break;
-        case 'thinking_trace':
-          onThinkingTrace?.(parseThinkingTrace(event.data));
-          break;
-        case 'execution_trace':
-        case 'step_started':
-        case 'step_updated':
-        case 'step_completed':
-        case 'step_failed':
-          onExecutionTrace?.(parseExecutionTrace(event.data));
-          break;
-        case 'content': {
-          const { chunk } = parseContent(event.data);
-          accumulatedRef.current += chunk;
-          onContent?.(chunk);
-          break;
-        }
-        case 'text.delta': {
-          const parsed = parseTextDelta(event.data);
-          if (parsed.channel === 'assistant' && parsed.delta) {
-            accumulatedRef.current += parsed.delta;
-            onContent?.(parsed.delta);
-          }
-          break;
-        }
-        case 'text.replace': {
-          const parsed = parseTextReplace(event.data);
-          if (parsed.channel === 'assistant') {
-            accumulatedRef.current = parsed.content;
-            onTextReplace?.(parsed.content);
-          }
-          break;
-        }
-        case 'done':
-          onDone?.(parseDone(event.data));
-          break;
-        case 'trace':
-          onTrace?.(parseTrace(event.data));
-          break;
-        case 'workspace_activation':
-          onWorkspaceActivation?.(parseWorkspaceActivation(event.data));
-          break;
-        case 'ui_cards':
-          onUICards?.(parseUICards(event.data));
-          break;
-        case 'knowledge_base_state':
-          onKnowledgeBaseState?.(parseKnowledgeBaseState(event.data));
-          break;
-        case 'field_progress':
-          onFieldProgress?.(parseFieldProgress(event.data));
-          break;
-        case 'requirement_draft':
-          onRequirementDraft?.(parseRequirementDraft(event.data));
-          break;
-        case 'next_actions':
-          onNextActions?.(parseNextActions(event.data));
-          break;
-        case 'sourcing_candidates':
-          onSourcingCandidates?.(parseSourcingCandidates(event.data));
-          break;
-        case 'risk_summary':
-          onRiskSummary?.(parseRiskSummary(event.data));
-          break;
-        case 'shortlist_updated':
-          onShortlistUpdated?.(parseShortlistUpdated(event.data));
-          break;
-        case 'evaluation_report_ready':
-          onEvaluationReportReady?.(parseEvaluationReportReady(event.data));
-          break;
-        case 'category_identified':
-          onCategoryIdentified?.(parseCategoryIdentified(event.data));
-          break;
-        case 'fields_updated':
-          onFieldsUpdated?.(parseFieldsUpdated(event.data));
-          break;
-        case 'instance_profile':
-          onInstanceProfile?.(parseInstanceProfile(event.data));
-          break;
-        case 'mode_runtime':
-          onModeRuntime?.(parseModeRuntime(event.data));
-          break;
-        case 'agent_runtime':
-          onAgentRuntime?.(parseAgentRuntime(event.data));
-          break;
-        case 'skill_runtime':
-          onSkillRuntime?.(parseSkillRuntime(event.data));
-          break;
-        case 'mode_switch_reason':
-          onModeSwitchReason?.(parseModeSwitchReason(event.data));
-          break;
-        case 'knowledge_search':
-          onKnowledgeSearch?.(parseKnowledgeSearch(event.data));
-          break;
-        case 'knowledge_citation':
-          onKnowledgeCitation?.(parseKnowledgeCitation(event.data));
-          break;
-        case 'orchestration_status':
-          onOrchestrationStatus?.(parseOrchestrationStatus(event.data));
-          break;
-        case 'canvas_state':
-          onCanvasState?.(parseCanvasState(event.data));
-          break;
-        case 'canvas_revision':
-          onCanvasRevision?.(parseCanvasRevision(event.data));
-          break;
-        case 'plan_block':
-          onPlanBlock?.(parsePlanBlock(event.data));
-          break;
-        case 'doc':
-          onDoc?.(parseDoc(event.data));
-          break;
-        case 'capability_suggestion':
-          onCapabilitySuggestion?.(parseCapabilitySuggestion(event.data));
-          break;
-        case 'patch_event':
-          {
-            const parsedPatchEvent = parsePatchEvent(event.data);
-            const patchSessionId = String(parsedPatchEvent?.session?.session_id || '').trim();
-            if (patchSessionId) {
-              latestSessionId = patchSessionId;
-            }
-            onPatchEvent?.(parsedPatchEvent);
-          }
-          break;
-        case 'error':
-          onError?.(parseSSEError(event.data));
-          break;
-        default:
-          console.warn('[SSE] unknown event type:', event.type);
-      }
-    };
-
-    const completeHandler = async () => {
-      setLoading(false);
-      await onComplete?.(accumulatedRef.current, {
-        sessionId: latestSessionId || null,
-      });
-      accumulatedRef.current = '';
-    };
-
-    const transportErrorHandler = (errorMessage) => {
-      setLoading(false);
-      const errorType = classifyError(errorMessage);
-      setError({ message: errorMessage, type: errorType });
-      onError?.({ message: errorMessage });
-      accumulatedRef.current = '';
-    };
-
-    const requestOptions = {
-      sessionId: String(resolvedSessionId || '').trim() || null,
-      content,
-      enabledCapabilities: Array.isArray(options.enabledCapabilities) ? options.enabledCapabilities : [],
-      modeKey: typeof options.modeKey === 'string' ? options.modeKey : '',
-      manualModeKey: typeof options.manualModeKey === 'string' ? options.manualModeKey : '',
-      command: typeof options.command === 'string' ? options.command : '',
-      clientRequestId: typeof options.clientRequestId === 'string' ? options.clientRequestId : '',
-      contractVersion: typeof options.contractVersion === 'string' ? options.contractVersion : '',
-      lastTurnId: typeof options.lastTurnId === 'string' ? options.lastTurnId : '',
-      payloadExtra: (
-        options.payloadExtra
-        && typeof options.payloadExtra === 'object'
-        && !Array.isArray(options.payloadExtra)
-      )
-        ? options.payloadExtra
-        : {},
-      endpoint: options.endpoint,
-      baseUrl: options.baseUrl,
-      url: options.url,
-      token: typeof options.token === 'string' ? options.token : '',
-      auth: (
-        options.auth
-        && typeof options.auth === 'object'
-        && !Array.isArray(options.auth)
-      ) ? options.auth : undefined,
-      onTiming: typeof options.onTiming === 'function' ? options.onTiming : undefined,
-    };
-
-    if (!requestOptions.enabledCapabilities.length) {
-      delete requestOptions.enabledCapabilities;
-    }
-    if (!requestOptions.modeKey) delete requestOptions.modeKey;
-    if (!requestOptions.manualModeKey) delete requestOptions.manualModeKey;
-    if (!requestOptions.command) delete requestOptions.command;
-    if (!requestOptions.clientRequestId) delete requestOptions.clientRequestId;
-    if (!requestOptions.contractVersion) delete requestOptions.contractVersion;
-    if (!requestOptions.lastTurnId) delete requestOptions.lastTurnId;
-    if (!Object.keys(requestOptions.payloadExtra || {}).length) delete requestOptions.payloadExtra;
-
-    if (!requestOptions.endpoint) delete requestOptions.endpoint;
-    if (!requestOptions.baseUrl) delete requestOptions.baseUrl;
-    if (!requestOptions.url) delete requestOptions.url;
-    if (!requestOptions.token) delete requestOptions.token;
-    if (!requestOptions.auth) delete requestOptions.auth;
-    if (!requestOptions.onTiming) delete requestOptions.onTiming;
-
-    await clientRef.current.sendMessage(
-      requestOptions,
-      eventHandler,
-      completeHandler,
-      transportErrorHandler
-    );
-  }, [sessionId]);
-
-  const retry = useCallback(async () => {
-    const { content, handlers, options } = lastMessageRef.current;
-    if (!content) return;
-    await send(content, handlers, options);
-  }, [send]);
-
-  const abort = useCallback(() => {
-    clientRef.current.abort();
-    setLoading(false);
-    accumulatedRef.current = '';
-  }, []);
-
-  useEffect(() => () => {
-    clientRef.current.abort();
-  }, []);
-
-  return { send, loading, error, retry, abort };
-}
-
-export default useSSEStream;
+export { useSSEStream, default } from '../../orchestration/useSSEStream.js';

package/src/chat-core/stream/useStreamSendController.js

@@ -0,0 +1,46 @@
+import { useCallback } from 'react';
+
+/**
+ * Stream send lifecycle controller.
+ *
+ * @param {object} params - Hook params.
+ * @param {object} params.stream - Stream adapter with `send`.
+ * @param {Function} params.onStarted - Optional started callback.
+ * @param {Function} params.onChunk - Optional chunk callback.
+ * @param {Function} params.onCompleted - Optional completed callback.
+ * @param {Function} params.onFailed - Optional failed callback.
+ * @returns {{executeStreamSend: Function}}
+ */
+export default function useStreamSendController({
+  stream,
+  onStarted,
+  onChunk,
+  onCompleted,
+  onFailed,
+} = {}) {
+  const executeStreamSend = useCallback(async (content, handlers = {}, options = {}) => {
+    if (!stream?.send) {
+      throw new Error('stream.send is required');
+    }
+
+    onStarted?.();
+
+    try {
+      await stream.send(content, {
+        ...handlers,
+        onContent: (chunk, ...args) => {
+          onChunk?.(chunk, ...args);
+          handlers?.onContent?.(chunk, ...args);
+        },
+      }, options);
+      onCompleted?.();
+    } catch (error) {
+      onFailed?.(error);
+      throw error;
+    }
+  }, [onChunk, onCompleted, onFailed, onStarted, stream]);
+
+  return { executeStreamSend };
+}
+
+export { useStreamSendController };

package/src/contracts/context-ssot.js

@@ -0,0 +1,47 @@
+export function createEmptyContext() {
+  return {
+    confirmed_fields: {},
+    missing_fields: [],
+    notes: [],
+    evidence: [],
+    sourcing_results: [],
+    analysis_results: [],
+  };
+}
+
+function toArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+export function normalizeContext(input = {}) {
+  const base = input && typeof input === 'object' ? input : {};
+  return {
+    confirmed_fields:
+      base.confirmed_fields && typeof base.confirmed_fields === 'object' && !Array.isArray(base.confirmed_fields)
+        ? { ...base.confirmed_fields }
+        : {},
+    missing_fields: toArray(base.missing_fields).map((item) => String(item || '').trim()).filter(Boolean),
+    notes: toArray(base.notes).map((item) => String(item || '')).filter(Boolean),
+    evidence: toArray(base.evidence),
+    sourcing_results: toArray(base.sourcing_results),
+    analysis_results: toArray(base.analysis_results),
+  };
+}
+
+export function mergeContextPatch(context = createEmptyContext(), patch = {}) {
+  const normalizedContext = normalizeContext(context);
+  const normalizedPatch = normalizeContext(patch);
+  return {
+    confirmed_fields: {
+      ...normalizedContext.confirmed_fields,
+      ...normalizedPatch.confirmed_fields,
+    },
+    missing_fields: normalizedPatch.missing_fields.length > 0
+      ? normalizedPatch.missing_fields
+      : normalizedContext.missing_fields,
+    notes: [...normalizedContext.notes, ...normalizedPatch.notes],
+    evidence: [...normalizedContext.evidence, ...normalizedPatch.evidence],
+    sourcing_results: [...normalizedContext.sourcing_results, ...normalizedPatch.sourcing_results],
+    analysis_results: [...normalizedContext.analysis_results, ...normalizedPatch.analysis_results],
+  };
+}

package/src/contracts/index.js

@@ -0,0 +1 @@
+export * from './sse-events.js';

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

@@ -0,0 +1,79 @@
+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 ?? '',
+});
+
+export const parseSSEError = (raw) => ({
+  message: raw?.message ?? '发生错误',
+});

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

@@ -0,0 +1,3 @@
+export * from './parsers-intake.js';
+export * from './parsers-sourcing.js';
+export * from './parsers-runtime.js';

package/src/contracts/sse-events/internal-normalizers.js

@@ -0,0 +1,143 @@
+export function resolveModeEventPayload(raw) {
+  if (raw?.payload && typeof raw.payload === 'object' && !Array.isArray(raw.payload)) {
+    return raw.payload;
+  }
+
+  return raw && typeof raw === 'object' ? raw : {};
+}
+
+export function pickFirstArray(payload, keys) {
+  for (const key of keys) {
+    const value = payload?.[key];
+    if (Array.isArray(value)) {
+      return value;
+    }
+  }
+  return [];
+}
+
+export function isPlainObject(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+export function ensureActionObject(value) {
+  return isPlainObject(value) ? value : {};
+}
+
+export function pickFirstString(candidates = []) {
+  for (const candidate of candidates) {
+    const text = String(candidate ?? '').trim();
+    if (text) {
+      return text;
+    }
+  }
+  return '';
+}
+
+export function normalizeActionPayload(rawPayload) {
+  if (isPlainObject(rawPayload)) {
+    return rawPayload;
+  }
+  return {};
+}
+
+export function normalizeAction(rawAction, index = 0) {
+  const action = ensureActionObject(rawAction);
+  const actionKey = pickFirstString([
+    action?.action_key,
+    action?.actionKey,
+    action?.key,
+    action?.id,
+  ]);
+  const label = pickFirstString([
+    action?.label,
+    action?.title,
+    action?.name,
+    actionKey,
+    'action',
+  ]);
+  const reason = pickFirstString([
+    action?.reason,
+    action?.description,
+  ]);
+  const ownerModule = pickFirstString([
+    action?.owner_module,
+    action?.ownerModule,
+  ]);
+  const policyId = pickFirstString([
+    action?.policy_id,
+    action?.policyId,
+  ]);
+  const payload = normalizeActionPayload(action?.payload);
+
+  return {
+    ...action,
+    action_key: actionKey,
+    label,
+    reason,
+    payload,
+    owner_module: ownerModule,
+    policy_id: policyId,
+    action_index: Number.isFinite(Number(action?.action_index))
+      ? Number(action.action_index)
+      : index,
+  };
+}
+
+export function normalizeActionList(rawActions) {
+  if (!Array.isArray(rawActions)) {
+    return [];
+  }
+  const normalized = [];
+  const seenActionKeys = new Set();
+
+  rawActions.forEach((rawAction, index) => {
+    const action = normalizeAction(rawAction, index);
+    const actionKey = String(action?.action_key || '').trim();
+    if (actionKey) {
+      if (seenActionKeys.has(actionKey)) {
+        return;
+      }
+      seenActionKeys.add(actionKey);
+    }
+    normalized.push(action);
+  });
+
+  return normalized;
+}
+
+export 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 : [],
+    },
+  };
+}