flare-chat-core 0.2.0 → 0.2.2

package/src/chat-core/messages/buildTimelineItems.knowledge-citation.test.mjs

@@ -0,0 +1,183 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { buildTimelineItems } from './buildTimelineItems.js';
+
+test('buildTimelineItems appends knowledge_citation artifact from streaming state', () => {
+  const timeline = buildTimelineItems({
+    messages: [
+      {
+        message_id: 'm1',
+        role: 'user',
+        content: 'hello',
+        created_at: '2026-04-19T00:00:00Z',
+      },
+    ],
+    streaming: {
+      content: '',
+      knowledgeCitation: {
+        run_id: 'retrieval-1',
+        citations: [{
+          citation_id: 'cite_1',
+          source_id: 'src-1',
+          matched_text: '公司20周年庆典礼品采购',
+          score: 0.23,
+        }],
+      },
+      roundKey: 'rk-1',
+    },
+  });
+
+  const citationItem = timeline.items.find((item) => item.type === 'knowledge_citation');
+  assert.ok(citationItem);
+  assert.equal(citationItem.id, 'knowledge-citation-retrieval-1');
+  assert.equal(citationItem.payload.run_id, 'retrieval-1');
+  assert.equal(citationItem.payload.citations[0].source_id, 'src-1');
+});
+
+test('buildTimelineItems skips knowledge_citation artifact when citations are non-hit noise', () => {
+  const timeline = buildTimelineItems({
+    messages: [
+      {
+        message_id: 'm1',
+        role: 'user',
+        content: 'hello',
+        created_at: '2026-04-19T00:00:00Z',
+      },
+    ],
+    streaming: {
+      content: '',
+      knowledgeCitation: {
+        run_id: 'retrieval-noise',
+        citations: [
+          {
+            citation_id: 'cite_noise',
+            source_id: 'src-noise',
+            score: 0.0001,
+            snippet: '周年庆',
+          },
+        ],
+      },
+      roundKey: 'rk-1',
+    },
+  });
+
+  const citationItem = timeline.items.find((item) => item.type === 'knowledge_citation');
+  assert.equal(citationItem, undefined);
+});
+
+test('buildTimelineItems appends knowledge_search artifact from streaming state', () => {
+  const timeline = buildTimelineItems({
+    messages: [
+      {
+        message_id: 'm1',
+        role: 'user',
+        content: 'hello',
+        created_at: '2026-04-19T00:00:00Z',
+      },
+    ],
+    streaming: {
+      content: '',
+      knowledgeSearch: {
+        run_id: 'search-1',
+        query: '上海大型erp供应商',
+        results: [{ id: 'vendor-1', name: 'Vendor A' }],
+      },
+      roundKey: 'rk-1',
+    },
+  });
+
+  const searchItem = timeline.items.find((item) => item.type === 'knowledge_search');
+  assert.ok(searchItem);
+  assert.equal(searchItem.id, 'knowledge-search-search-1');
+  assert.equal(searchItem.payload.query, '上海大型erp供应商');
+});
+
+test('buildTimelineItems appends sourcing_candidates artifact from streaming state', () => {
+  const timeline = buildTimelineItems({
+    messages: [
+      {
+        message_id: 'm1',
+        role: 'user',
+        content: 'hello',
+        created_at: '2026-04-19T00:00:00Z',
+      },
+    ],
+    streaming: {
+      content: '',
+      sourcingCandidates: {
+        run_id: 'source-1',
+        candidates: [{ supplier_id: 'sup-1', supplier_name: 'Vendor A' }],
+      },
+      roundKey: 'rk-1',
+    },
+  });
+
+  const sourcingItem = timeline.items.find((item) => item.type === 'sourcing_candidates');
+  assert.ok(sourcingItem);
+  assert.equal(sourcingItem.id, 'sourcing-candidates-source-1');
+});
+
+test('buildTimelineItems keeps executionCards on thinking item for step-by-step display', () => {
+  const timeline = buildTimelineItems({
+    messages: [
+      {
+        message_id: 'm1',
+        role: 'user',
+        content: 'hello',
+        created_at: '2026-04-19T00:00:00Z',
+      },
+    ],
+    executionCards: [
+      { step_id: 'context_binding', label: '上下文绑定', detail: '绑定 2 个来源', status: 'completed' },
+    ],
+    streaming: {
+      content: '',
+      executionTrace: { step_id: 'llm', label: '生成回复', status: 'running' },
+      roundKey: 'rk-2',
+    },
+  });
+
+  const thinkingItem = timeline.items.find((item) => item.type === 'thinking');
+  assert.ok(thinkingItem);
+  assert.equal(Array.isArray(thinkingItem.executionCards), true);
+  assert.equal(thinkingItem.executionCards.length, 1);
+  assert.equal(thinkingItem.executionCards[0].step_id, 'context_binding');
+});
+
+test('buildTimelineItems keeps only latest assistant historical thinking item', () => {
+  const timeline = buildTimelineItems({
+    messages: [
+      {
+        message_id: 'u1',
+        role: 'user',
+        content: 'hello',
+        created_at: '2026-04-19T00:00:00Z',
+      },
+      {
+        message_id: 'a1',
+        role: 'assistant',
+        content: 'first answer',
+        created_at: '2026-04-19T00:00:01Z',
+        execution_trace: { step_id: 'knowledge_search', status: 'completed' },
+      },
+      {
+        message_id: 'u2',
+        role: 'user',
+        content: 'next',
+        created_at: '2026-04-19T00:00:02Z',
+      },
+      {
+        message_id: 'a2',
+        role: 'assistant',
+        content: 'second answer',
+        created_at: '2026-04-19T00:00:03Z',
+        execution_trace: { step_id: 'knowledge_search', status: 'completed' },
+      },
+    ],
+    streaming: {},
+  });
+
+  const thinkingItems = timeline.items.filter((item) => item.type === 'thinking');
+  assert.equal(thinkingItems.length, 1);
+  assert.equal(thinkingItems[0].id, 'thinking-a2');
+});

package/src/chat-core/messages/contextUsageDefaults.js

@@ -0,0 +1,3 @@
+export const CONTEXT_USAGE_WINDOW_TOKEN_LIMIT = 258000;
+export const CONTEXT_USAGE_TOKEN_ESTIMATE_DIVISOR = 2.4;
+export const CONTEXT_USAGE_BASE_TOKENS_PER_MESSAGE = 32;

package/src/chat-core/messages/contextUsageViewModel.js

@@ -0,0 +1,147 @@
+function coercePositiveInteger(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    return 0;
+  }
+  return Math.max(0, Math.round(parsed));
+}
+
+function extractTimelineMessageText(item) {
+  if (!item || typeof item !== 'object') {
+    return '';
+  }
+  const candidates = [item.content, item.text, item.message, item.value];
+  for (const candidate of candidates) {
+    const normalized = String(candidate || '').replace(/\s+/g, ' ').trim();
+    if (normalized) {
+      return normalized;
+    }
+  }
+  return '';
+}
+
+function extractContextUsageFromTrace(trace) {
+  if (!trace || typeof trace !== 'object' || Array.isArray(trace)) {
+    return null;
+  }
+  if (String(trace.step_id || '').trim() !== 'context_usage') {
+    return null;
+  }
+  const detail = String(trace.detail || '').trim();
+  if (!detail) {
+    return null;
+  }
+  const modeMatch = detail.match(/mode=([^;/]+)\/([^;]+)/);
+  const profileMatch = detail.match(/profile=([^;]+)/);
+  const tokenMatch = detail.match(/tokens≈(\d+)/);
+  return {
+    mode_key: modeMatch ? String(modeMatch[1] || '').trim() : '',
+    mode_state: modeMatch ? String(modeMatch[2] || '').trim() : '',
+    profile: profileMatch ? String(profileMatch[1] || '').trim() : '',
+    token_estimate: {
+      total_prompt_tokens_estimate: tokenMatch ? coercePositiveInteger(tokenMatch[1]) : 0,
+    },
+  };
+}
+
+function resolveLatestTimelineContextUsage(items) {
+  const timelineItems = Array.isArray(items) ? items : [];
+  for (let index = timelineItems.length - 1; index >= 0; index -= 1) {
+    const item = timelineItems[index];
+    if (String(item?.type || '').trim() === 'message' && String(item?.role || '').trim() === 'assistant') {
+      const usage = item?.contextUsage;
+      if (usage && typeof usage === 'object' && !Array.isArray(usage)) {
+        return { source: 'backend', usage };
+      }
+    }
+    if (String(item?.type || '').trim() === 'thinking') {
+      const usage = extractContextUsageFromTrace(item?.executionTrace);
+      if (usage) {
+        return { source: 'stream_trace', usage };
+      }
+    }
+  }
+  return { source: 'estimate', usage: null };
+}
+
+function buildLayerSummaryLabel(layers) {
+  if (!Array.isArray(layers) || layers.length === 0) {
+    return '';
+  }
+  const normalizedLayers = layers.filter((layer) => layer && typeof layer === 'object');
+  if (normalizedLayers.length === 0) {
+    return '';
+  }
+  const includedLayers = normalizedLayers.filter((layer) => layer.included !== false).length;
+  return `layers ${includedLayers}/${normalizedLayers.length}`;
+}
+
+function buildBudgetStatusLabel({ tokens, limit }) {
+  if (!Number.isFinite(tokens) || !Number.isFinite(limit) || limit <= 0) {
+    return '';
+  }
+  const ratio = tokens / limit;
+  if (ratio >= 1) {
+    return '超限';
+  }
+  if (ratio >= 0.85) {
+    return '临界';
+  }
+  if (ratio >= 0.6) {
+    return '偏高';
+  }
+  return '正常';
+}
+
+export function buildContextUsageViewModel({
+  timelineItems,
+  fallbackTokenLimit,
+  tokenEstimateDivisor = 2.4,
+  baseTokensPerMessage = 32,
+}) {
+  const normalizedTimelineItems = Array.isArray(timelineItems) ? timelineItems : [];
+  const messageItems = normalizedTimelineItems.filter((item) => String(item?.type || '').trim() === 'message');
+  const messageTexts = messageItems.map((item) => extractTimelineMessageText(item)).filter(Boolean);
+  const messageCount = messageTexts.length;
+  const textCharCount = messageTexts.reduce((total, text) => total + text.length, 0);
+  const { source, usage } = resolveLatestTimelineContextUsage(timelineItems);
+  const sourceLabel = source === 'backend'
+    ? '后端'
+    : (source === 'stream_trace' ? '流式' : '估算');
+  const totalTokens = coercePositiveInteger(usage?.token_estimate?.total_prompt_tokens_estimate);
+  const tokenLimit = coercePositiveInteger(usage?.budget_tokens?.total_tokens) || coercePositiveInteger(fallbackTokenLimit);
+  const byChars = tokenEstimateDivisor > 0 ? Math.round(textCharCount / tokenEstimateDivisor) : 0;
+  const byMessages = messageCount * coercePositiveInteger(baseTokensPerMessage);
+  const estimatedTokens = totalTokens > 0 ? totalTokens : Math.max(byChars, byMessages, 0);
+  const windowPercent = tokenLimit > 0
+    ? Math.max(0, Math.min(100, Math.round((estimatedTokens / tokenLimit) * 100)))
+    : 0;
+  const modeKey = String(usage?.mode_key || '').trim();
+  const modeState = String(usage?.mode_state || '').trim();
+  const profile = String(usage?.profile || '').trim();
+  const status = buildBudgetStatusLabel({ tokens: estimatedTokens, limit: tokenLimit });
+  const layerSummary = buildLayerSummaryLabel(usage?.layers);
+  const profileLabel = profile ? ` · ${profile}` : '';
+  const modeLabel = modeKey ? ` · ${modeKey}${modeState ? `/${modeState}` : ''}` : '';
+  const statusLabel = status ? ` · ${status}` : '';
+  const layerLabel = layerSummary ? ` · ${layerSummary}` : '';
+  const budgetLabel = tokenLimit > 0
+    ? `${estimatedTokens.toLocaleString('zh-CN')} / ${tokenLimit.toLocaleString('zh-CN')}`
+    : `${estimatedTokens.toLocaleString('zh-CN')}`;
+  return {
+    source,
+    usage,
+    modeKey,
+    modeState,
+    profile,
+    status,
+    layerSummary,
+    messageCount,
+    textCharCount,
+    totalTokens,
+    estimatedTokens,
+    tokenLimit,
+    windowPercent,
+    text: `${sourceLabel}${profileLabel}${modeLabel}${statusLabel}${layerLabel} · ${budgetLabel}`,
+  };
+}

package/src/chat-core/messages/contextUsageViewModel.test.mjs

@@ -0,0 +1,74 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { buildContextUsageViewModel } from './contextUsageViewModel.js';
+
+test('buildContextUsageViewModel prefers backend usage over stream trace', () => {
+  const result = buildContextUsageViewModel({
+    timelineItems: [
+      {
+        type: 'thinking',
+        executionTrace: {
+          step_id: 'context_usage',
+          detail: 'mode=auto/running; profile=medium; tokens≈444',
+        },
+      },
+      {
+        type: 'message',
+        role: 'assistant',
+        content: 'done',
+        contextUsage: {
+          profile: 'heavy',
+          token_estimate: {
+            total_prompt_tokens_estimate: 123,
+          },
+          layers: [
+            { included: true },
+            { included: false },
+          ],
+        },
+      },
+    ],
+    fallbackTokenLimit: 1000,
+  });
+
+  assert.equal(result.source, 'backend');
+  assert.equal(result.estimatedTokens, 123);
+  assert.equal(result.profile, 'heavy');
+  assert.equal(result.layerSummary, 'layers 1/2');
+});
+
+test('buildContextUsageViewModel falls back to stream trace then estimate', () => {
+  const traceResult = buildContextUsageViewModel({
+    timelineItems: [
+      {
+        type: 'thinking',
+        executionTrace: {
+          step_id: 'context_usage',
+          detail: 'mode=requirement/collecting; profile=light; tokens≈333',
+        },
+      },
+    ],
+    fallbackTokenLimit: 1000,
+  });
+
+  assert.equal(traceResult.source, 'stream_trace');
+  assert.equal(traceResult.estimatedTokens, 333);
+  assert.equal(traceResult.modeKey, 'requirement');
+
+  const estimateResult = buildContextUsageViewModel({
+    timelineItems: [
+      {
+        type: 'message',
+        role: 'user',
+        content: '需要一份采购计划。',
+      },
+    ],
+    fallbackTokenLimit: 1000,
+    tokenEstimateDivisor: 2,
+    baseTokensPerMessage: 10,
+  });
+
+  assert.equal(estimateResult.source, 'estimate');
+  assert.ok(estimateResult.estimatedTokens > 0);
+  assert.equal(estimateResult.tokenLimit, 1000);
+});

package/src/chat-core/messages/useContextUsageViewModel.js

@@ -0,0 +1,41 @@
+import { useMemo } from 'react';
+import { buildTimelineItems } from './buildTimelineItems.js';
+import { buildContextUsageViewModel } from './contextUsageViewModel.js';
+
+export function useContextUsageViewModel({
+  timelineItems,
+  chatSessionState,
+  fallbackTokenLimit = 12000,
+  tokenEstimateDivisor = 2.4,
+  baseTokensPerMessage = 32,
+  loading = false,
+}) {
+  const resolvedTimelineItems = useMemo(() => {
+    if (Array.isArray(timelineItems)) {
+      return timelineItems;
+    }
+    const timeline = buildTimelineItems({
+      messages: chatSessionState?.messages,
+      uiCards: chatSessionState?.uiCards,
+      executionCards: chatSessionState?.executionCards,
+      streaming: chatSessionState?.streaming,
+    }, { loading });
+    return timeline.items;
+  }, [
+    chatSessionState?.executionCards,
+    chatSessionState?.messages,
+    chatSessionState?.streaming,
+    chatSessionState?.uiCards,
+    loading,
+    timelineItems,
+  ]);
+
+  return useMemo(() => buildContextUsageViewModel({
+    timelineItems: resolvedTimelineItems,
+    fallbackTokenLimit,
+    tokenEstimateDivisor,
+    baseTokensPerMessage,
+  }), [resolvedTimelineItems, fallbackTokenLimit, tokenEstimateDivisor, baseTokensPerMessage]);
+}
+
+export default useContextUsageViewModel;

package/src/chat-core/orchestration/useBasicSendHandler.js

@@ -0,0 +1,55 @@
+import { useCallback } from 'react';
+
+/**
+ * Compose a basic send handler from preflight/execution/recovery boundaries.
+ *
+ * @param {object} params - Hook params.
+ * @param {Function} params.resolveSendPreflight - Preflight resolver.
+ * @param {Function} params.executeSendRound - Round executor.
+ * @param {Function} params.handleSendFailureRecovery - Failure recovery handler.
+ * @param {Array<any>} params.emptyArray - Shared immutable empty array.
+ * @returns {{handleSend: Function}}
+ */
+export default function useBasicSendHandler({
+  resolveSendPreflight,
+  executeSendRound,
+  handleSendFailureRecovery,
+  emptyArray = [],
+}) {
+  const handleSend = useCallback(async (options = {}) => {
+    let isFirstDraftSend = false;
+    let preserveInputOnError = false;
+    let content = '';
+    let attachedSessionFilesSnapshot = emptyArray;
+
+    try {
+      const sendPreflight = await resolveSendPreflight?.(options);
+      if (!sendPreflight || sendPreflight.blocked) {
+        return;
+      }
+
+      attachedSessionFilesSnapshot = sendPreflight.attachedSessionFilesSnapshot || emptyArray;
+      isFirstDraftSend = sendPreflight.isFirstDraftSend === true;
+      preserveInputOnError = sendPreflight.preserveInputOnError === true;
+      content = sendPreflight.content || '';
+
+      await executeSendRound?.({
+        sendPreflight,
+        isFirstDraftSend,
+      });
+      return true;
+    } catch (error) {
+      handleSendFailureRecovery?.({
+        preserveInputOnError,
+        isFirstDraftSend,
+        content,
+        attachedSessionFilesSnapshot,
+      });
+      return error;
+    }
+  }, [emptyArray, executeSendRound, handleSendFailureRecovery, resolveSendPreflight]);
+
+  return { handleSend };
+}
+
+export { useBasicSendHandler };

package/src/chat-core/pipelines/build-action-request.js

@@ -0,0 +1,46 @@
+import { resolvePayloadExtra } from './build-stream-request.js';
+
+export function buildRealActionRequestBody({
+  action = {},
+  options = {},
+  scope = {},
+}) {
+  const normalizedAction = (
+    action
+    && typeof action === 'object'
+    && !Array.isArray(action)
+  ) ? action : {};
+  const payloadExtra = resolvePayloadExtra(options);
+  const actionPayload = (
+    normalizedAction.payload
+    && typeof normalizedAction.payload === 'object'
+    && !Array.isArray(normalizedAction.payload)
+  ) ? normalizedAction.payload : {};
+  const resolvedProjectId = String(scope?.projectId || '').trim();
+  const resolvedUserId = String(scope?.userId || '').trim();
+  const sessionId = String(options.sessionIdOverride || '').trim();
+
+  return {
+    tenant_id: 'default',
+    instance_id: 'default',
+    domain_pack_version: 'v1',
+    session_id: sessionId || null,
+    intent: 'default',
+    project_id: resolvedProjectId || null,
+    user_id: resolvedUserId || null,
+    action_key: String(normalizedAction.action_key || '').trim() || null,
+    target_mode: String(
+      normalizedAction.target_mode
+      || actionPayload.target_mode
+      || ''
+    ).trim() || null,
+    action_status: String(normalizedAction.status || '').trim() || null,
+    action_reason: String(normalizedAction.reason || '').trim() || null,
+    payload: {
+      ...actionPayload,
+      ...payloadExtra,
+      project_id: resolvedProjectId || null,
+      user_id: resolvedUserId || null,
+    },
+  };
+}

package/src/chat-core/pipelines/build-stream-request.js

@@ -0,0 +1,74 @@
+import { resolveEntities } from './entity-extraction.js';
+
+function normalizeRefs(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter((item) => item !== undefined && item !== null);
+}
+
+export function resolvePayloadExtra(options = {}) {
+  return (
+    options?.payloadExtra
+    && typeof options.payloadExtra === 'object'
+    && !Array.isArray(options.payloadExtra)
+  ) ? options.payloadExtra : {};
+}
+
+export function resolveStreamRefs(options = {}) {
+  const payloadExtra = resolvePayloadExtra(options);
+
+  const contextRefs = Array.isArray(options?.context_refs)
+    ? normalizeRefs(options.context_refs)
+    : normalizeRefs(payloadExtra.context_refs);
+  const knowledgeRefs = Array.isArray(options?.knowledge_refs)
+    ? normalizeRefs(options.knowledge_refs)
+    : normalizeRefs(payloadExtra.knowledge_refs);
+
+  return {
+    context_refs: contextRefs,
+    knowledge_refs: knowledgeRefs,
+  };
+}
+
+export function buildRealStreamRequestBody({
+  content,
+  options = {},
+  scope = {},
+}) {
+  const resolvedProjectId = String(scope?.projectId || '').trim();
+  const resolvedUserId = String(scope?.userId || '').trim();
+  const sessionId = String(options.sessionIdOverride || '').trim();
+  const payloadExtra = resolvePayloadExtra(options);
+  const modeKey = String(options?.modeKey || payloadExtra.mode || '').trim();
+  const manualModeKey = String(options?.manualModeKey || payloadExtra.manual_mode || '').trim();
+  const command = String(options?.command || payloadExtra.command || 'send_message').trim() || 'send_message';
+  const refs = resolveStreamRefs(options);
+  const entities = resolveEntities({
+    text: content,
+    entities: Array.isArray(options?.entities) ? options.entities : payloadExtra.entities,
+  });
+  return {
+    tenant_id: 'default',
+    instance_id: 'default',
+    domain_pack_version: 'v1',
+    session_id: sessionId || null,
+    command,
+    intent: 'default',
+    ...(modeKey ? { mode: modeKey } : {}),
+    ...(manualModeKey ? { manual_mode: manualModeKey } : {}),
+    project_id: resolvedProjectId || null,
+    user_id: resolvedUserId || null,
+    payload: {
+      message: content,
+      ...(modeKey ? { mode: modeKey } : {}),
+      ...(manualModeKey ? { manual_mode: manualModeKey } : {}),
+      project_id: resolvedProjectId || null,
+      user_id: resolvedUserId || null,
+      ...payloadExtra,
+      entities,
+    },
+    context_refs: refs.context_refs,
+    knowledge_refs: refs.knowledge_refs,
+  };
+}