Skip to content

Commit e0e292a

Browse files
JacobinwweyJacobinwwey
committed
feat: preserve vector stage in conversation traces
1 parent aa0521f commit e0e292a

8 files changed

Lines changed: 203 additions & 1 deletion

‎docs/brainstorms/2026-04-19-mainline-progress-reconciliation-and-post-m7-direction-requirements.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,7 @@ This document re-baselines current mainline truth on 2026-04-19, records what ch
162162
- `npm test -- src/learning/KnowledgeLearningPlatform.persistence.test.ts --runInBand`
163163
- The current working branch remains a reference source for future lanes, not a justification for direct wide merge.
164164

165-
## Execution Note (2026-04-20 M8.1-M8.5)
165+
## Execution Note (2026-04-20 M8.1-M8.6)
166166

167167
- The smallest executed post-M7 slice is now an evidence bundle, not an adapter claim:
168168
- `npm run verify:foundation:readiness`
@@ -182,6 +182,9 @@ This document re-baselines current mainline truth on 2026-04-19, records what ch
182182
- The next bounded execution slice after that exposes staged vector metadata through query traces:
183183
- query responses now surface vector `mode`, `status`, and `candidateCount`
184184
- the agent-workspace query-trace card now renders that metadata directly instead of hiding the prefilter stage.
185+
- The next bounded execution slice after that propagates the same staged vector metadata through conversation traces:
186+
- `runAgentConversation(...)` now preserves bounded `vectorAcceleration` and `evidenceCoverageRatio` fields
187+
- runtime diagnostics snapshots keep that same metadata in `lastConversation`, so operator evidence no longer drops the staged vector path.
185188
- Current expected outcome on `main` remains:
186189
- status `in_progress`
187190
- decision `no-go`

‎docs/diataxis/en/explanation/development-progress-dashboard.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -639,6 +639,21 @@ Execution anchor:
639639
- `npm run docs:diataxis:check`
640640
- `npm run docs:site:build`
641641

642+
## Latest Mainline Increment (2026-04-20 M8.6 Conversation Trace Vector Visibility)
643+
644+
- Extended `runAgentConversation(...)` trace payloads so conversation-level diagnostics no longer hide the staged vector path:
645+
- `src/learning/types.ts`
646+
- `src/learning/KnowledgeLearningPlatform.ts`
647+
- Conversation traces now propagate:
648+
- `vectorAcceleration`
649+
- `evidenceCoverageRatio`
650+
- Agent-workspace runtime diagnostics snapshots now persist the same bounded conversation trace metadata in `lastConversation`:
651+
- `src/frontend/agent_workspace_runtime.js`
652+
- `src/agent_workspace.runtime.behavior.test.ts`
653+
- Added focused regression coverage for conversation-trace propagation without changing conversation capability behavior:
654+
- `src/learning/KnowledgeLearningPlatform.test.ts`
655+
- `src/agent_workspace.runtime.behavior.test.ts`
656+
642657
## Latest Mainline Increment (2026-04-20 M8.5 Query Trace Vector Visibility)
643658

644659
- Extended public query-trace payloads so the staged vector boundary is inspectable instead of implicit:

‎docs/diataxis/zh/explanation/development-progress-dashboard.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -642,6 +642,21 @@
642642
- `npm run docs:diataxis:check`
643643
- `npm run docs:site:build`
644644

645+
## 主线最新增量（2026-04-20 M8.6 Conversation Trace 向量阶段可见性）
646+
647+
- 已扩展 `runAgentConversation(...)` 的 trace 载荷，使对话层诊断不再隐藏 staged vector 路径：
648+
- `src/learning/types.ts`
649+
- `src/learning/KnowledgeLearningPlatform.ts`
650+
- conversation trace 现在继续透传：
651+
- `vectorAcceleration`
652+
- `evidenceCoverageRatio`
653+
- agent-workspace runtime diagnostics snapshot 现在会在 `lastConversation` 中持久化同一份受限对话 trace 元数据：
654+
- `src/frontend/agent_workspace_runtime.js`
655+
- `src/agent_workspace.runtime.behavior.test.ts`
656+
- 已补 conversation-trace 透传的聚焦回归，且未改变 capability 行为：
657+
- `src/learning/KnowledgeLearningPlatform.test.ts`
658+
- `src/agent_workspace.runtime.behavior.test.ts`
659+
645660
## 主线最新增量（2026-04-20 M8.5 Query Trace 向量阶段可见性）
646661

647662
- 已扩展公共 query-trace 载荷，让当前 staged vector 边界可被直接检查，而不是隐含在实现内部：

‎src/agent_workspace.runtime.behavior.test.ts‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -296,6 +296,20 @@ describe('agent workspace runtime behavior', () => {
296296
result: {
297297
userId: 'agent_user_default',
298298
message: 'Found 1 local knowledge point(s).',
299+
trace: {
300+
generatedAt: '2026-04-20T04:00:00.000Z',
301+
asOf: '2026-04-20T04:00:00.000Z',
302+
queryTopK: 4,
303+
resolvedKnowledgePoints: 1,
304+
retrievalModes: ['keyword', 'graph_traversal', 'temporal_filter'],
305+
vectorAcceleration: {
306+
mode: 'local_prefilter',
307+
status: 'prefilter_only',
308+
candidateCount: 1,
309+
},
310+
evidenceCoverageRatio: 1,
311+
latencyMs: 11,
312+
},
299313
knowledgePoints: [
300314
{
301315
atomId: 'atom-path-1',
@@ -479,6 +493,20 @@ describe('agent workspace runtime behavior', () => {
479493
result: {
480494
userId: 'agent_user_default',
481495
message: 'Found 1 local knowledge point(s).',
496+
trace: {
497+
generatedAt: '2026-04-20T04:00:01.000Z',
498+
asOf: '2026-04-20T04:00:01.000Z',
499+
queryTopK: 4,
500+
resolvedKnowledgePoints: 1,
501+
retrievalModes: ['keyword', 'graph_traversal', 'temporal_filter'],
502+
vectorAcceleration: {
503+
mode: 'local_prefilter',
504+
status: 'prefilter_only',
505+
candidateCount: 1,
506+
},
507+
evidenceCoverageRatio: 1,
508+
latencyMs: 12,
509+
},
482510
knowledgePoints: [
483511
{
484512
atomId: 'atom-session-1',
@@ -552,6 +580,20 @@ describe('agent workspace runtime behavior', () => {
552580
result: {
553581
userId: 'agent_user_default',
554582
message: 'Found 1 local knowledge point(s).',
583+
trace: {
584+
generatedAt: '2026-04-20T04:00:00.000Z',
585+
asOf: '2026-04-20T04:00:00.000Z',
586+
queryTopK: 4,
587+
resolvedKnowledgePoints: 1,
588+
retrievalModes: ['keyword', 'graph_traversal', 'temporal_filter'],
589+
vectorAcceleration: {
590+
mode: 'local_prefilter',
591+
status: 'prefilter_only',
592+
candidateCount: 1,
593+
},
594+
evidenceCoverageRatio: 1,
595+
latencyMs: 11,
596+
},
555597
knowledgePoints: [
556598
{
557599
atomId: 'atom-query-1',
@@ -644,6 +686,20 @@ describe('agent workspace runtime behavior', () => {
644686
result: {
645687
userId: 'agent_user_default',
646688
message: 'Found 1 local knowledge point(s).',
689+
trace: {
690+
generatedAt: '2026-04-20T04:00:01.000Z',
691+
asOf: '2026-04-20T04:00:01.000Z',
692+
queryTopK: 4,
693+
resolvedKnowledgePoints: 1,
694+
retrievalModes: ['keyword', 'graph_traversal', 'temporal_filter'],
695+
vectorAcceleration: {
696+
mode: 'local_prefilter',
697+
status: 'prefilter_only',
698+
candidateCount: 1,
699+
},
700+
evidenceCoverageRatio: 1,
701+
latencyMs: 12,
702+
},
647703
knowledgePoints: [
648704
{
649705
atomId: 'atom-guardrail-1',
@@ -723,6 +779,20 @@ describe('agent workspace runtime behavior', () => {
723779
result: {
724780
userId: 'agent_user_default',
725781
message: 'Found 1 local knowledge point(s).',
782+
trace: {
783+
generatedAt: '2026-04-20T04:00:00.000Z',
784+
asOf: '2026-04-20T04:00:00.000Z',
785+
queryTopK: 4,
786+
resolvedKnowledgePoints: 1,
787+
retrievalModes: ['keyword', 'graph_traversal', 'temporal_filter'],
788+
vectorAcceleration: {
789+
mode: 'local_prefilter',
790+
status: 'prefilter_only',
791+
candidateCount: 1,
792+
},
793+
evidenceCoverageRatio: 1,
794+
latencyMs: 11,
795+
},
726796
knowledgePoints: [
727797
{
728798
atomId: 'atom-misconception-1',
@@ -811,6 +881,20 @@ describe('agent workspace runtime behavior', () => {
811881
result: {
812882
userId: 'agent_user_default',
813883
message: 'Found 1 local knowledge point(s).',
884+
trace: {
885+
generatedAt: '2026-04-20T04:00:01.000Z',
886+
asOf: '2026-04-20T04:00:01.000Z',
887+
queryTopK: 4,
888+
resolvedKnowledgePoints: 1,
889+
retrievalModes: ['keyword', 'graph_traversal', 'temporal_filter'],
890+
vectorAcceleration: {
891+
mode: 'local_prefilter',
892+
status: 'prefilter_only',
893+
candidateCount: 1,
894+
},
895+
evidenceCoverageRatio: 1,
896+
latencyMs: 12,
897+
},
814898
knowledgePoints: [
815899
{
816900
atomId: 'atom-followup-1',
@@ -888,6 +972,20 @@ describe('agent workspace runtime behavior', () => {
888972
result: {
889973
userId: 'agent_user_default',
890974
message: 'Found 1 local knowledge point(s).',
975+
trace: {
976+
generatedAt: '2026-04-20T04:00:00.000Z',
977+
asOf: '2026-04-20T04:00:00.000Z',
978+
queryTopK: 4,
979+
resolvedKnowledgePoints: 1,
980+
retrievalModes: ['keyword', 'graph_traversal', 'temporal_filter'],
981+
vectorAcceleration: {
982+
mode: 'local_prefilter',
983+
status: 'prefilter_only',
984+
candidateCount: 1,
985+
},
986+
evidenceCoverageRatio: 1,
987+
latencyMs: 11,
988+
},
891989
knowledgePoints: [
892990
{
893991
atomId: 'atom-transfer-1',
@@ -965,6 +1063,20 @@ describe('agent workspace runtime behavior', () => {
9651063
result: {
9661064
userId: 'agent_user_default',
9671065
message: 'Found 1 local knowledge point(s).',
1066+
trace: {
1067+
generatedAt: '2026-04-20T04:00:01.000Z',
1068+
asOf: '2026-04-20T04:00:01.000Z',
1069+
queryTopK: 4,
1070+
resolvedKnowledgePoints: 1,
1071+
retrievalModes: ['keyword', 'graph_traversal', 'temporal_filter'],
1072+
vectorAcceleration: {
1073+
mode: 'local_prefilter',
1074+
status: 'prefilter_only',
1075+
candidateCount: 1,
1076+
},
1077+
evidenceCoverageRatio: 1,
1078+
latencyMs: 12,
1079+
},
9681080
knowledgePoints: [
9691081
{
9701082
atomId: 'atom-analyze-1',
@@ -1540,6 +1652,20 @@ describe('agent workspace runtime behavior', () => {
15401652
result: {
15411653
userId: 'agent_user_default',
15421654
message: 'Found 1 local knowledge point(s).',
1655+
trace: {
1656+
generatedAt: '2026-04-20T04:00:00.000Z',
1657+
asOf: '2026-04-20T04:00:00.000Z',
1658+
queryTopK: 4,
1659+
resolvedKnowledgePoints: 1,
1660+
retrievalModes: ['keyword', 'graph_traversal', 'temporal_filter'],
1661+
vectorAcceleration: {
1662+
mode: 'local_prefilter',
1663+
status: 'prefilter_only',
1664+
candidateCount: 1,
1665+
},
1666+
evidenceCoverageRatio: 1,
1667+
latencyMs: 11,
1668+
},
15431669
knowledgePoints: [
15441670
{
15451671
atomId: 'atom-diagnostic-1',
@@ -1574,6 +1700,20 @@ describe('agent workspace runtime behavior', () => {
15741700
result: {
15751701
userId: 'agent_user_default',
15761702
message: 'Found 1 local knowledge point(s).',
1703+
trace: {
1704+
generatedAt: '2026-04-20T04:00:01.000Z',
1705+
asOf: '2026-04-20T04:00:01.000Z',
1706+
queryTopK: 4,
1707+
resolvedKnowledgePoints: 1,
1708+
retrievalModes: ['keyword', 'graph_traversal', 'temporal_filter'],
1709+
vectorAcceleration: {
1710+
mode: 'local_prefilter',
1711+
status: 'prefilter_only',
1712+
candidateCount: 1,
1713+
},
1714+
evidenceCoverageRatio: 1,
1715+
latencyMs: 12,
1716+
},
15771717
knowledgePoints: [
15781718
{
15791719
atomId: 'atom-diagnostic-1',
@@ -1657,6 +1797,13 @@ describe('agent workspace runtime behavior', () => {
16571797
status: 'success',
16581798
replayCandidate: true,
16591799
knowledgePoints: 1,
1800+
retrievalModes: ['keyword', 'graph_traversal', 'temporal_filter'],
1801+
vectorAcceleration: expect.objectContaining({
1802+
mode: 'local_prefilter',
1803+
status: 'prefilter_only',
1804+
candidateCount: 1,
1805+
}),
1806+
evidenceCoverageRatio: 1,
16601807
})
16611808
);
16621809

‎src/frontend/agent_workspace_runtime.js‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1356,6 +1356,14 @@
13561356
status: 'success',
13571357
replayCandidate: replayMarker.replayCandidate,
13581358
knowledgePoints: knowledgePoints.length,
1359+
retrievalModes: Array.isArray(result && result.trace && result.trace.retrievalModes)
1360+
? result.trace.retrievalModes.slice()
1361+
: [],
1362+
vectorAcceleration: result && result.trace && result.trace.vectorAcceleration
1363+
&& typeof result.trace.vectorAcceleration === 'object'
1364+
? { ...result.trace.vectorAcceleration }
1365+
: null,
1366+
evidenceCoverageRatio: Number(result && result.trace && result.trace.evidenceCoverageRatio),
13591367
};
13601368
appendMessage('assistant', trimString(result && result.message));
13611369
state.latestKnowledgePoints = knowledgePoints;

‎src/learning/KnowledgeLearningPlatform.test.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,12 @@ describe('KnowledgeLearningPlatform', () => {
138138
expect(result.trace.queryTopK).toBe(3);
139139
expect(result.trace.resolvedKnowledgePoints).toBe(result.knowledgePoints.length);
140140
expect(result.trace.retrievalModes).toContain('keyword');
141+
expect(result.trace.vectorAcceleration).toEqual({
142+
mode: 'local_prefilter',
143+
status: 'prefilter_only',
144+
candidateCount: expect.any(Number),
145+
});
146+
expect(result.trace.evidenceCoverageRatio).toBeGreaterThan(0);
141147

142148
const firstPoint = result.knowledgePoints[0];
143149
expect(firstPoint.capabilities.length).toBeGreaterThanOrEqual(18);

‎src/learning/KnowledgeLearningPlatform.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1134,6 +1134,8 @@ export class KnowledgeLearningPlatform implements KnowledgeLearningPlatformAPI {
11341134
queryTopK,
11351135
resolvedKnowledgePoints: knowledgePoints.length,
11361136
retrievalModes: queryResult.trace.retrievalModes,
1137+
vectorAcceleration: queryResult.trace.vectorAcceleration,
1138+
evidenceCoverageRatio: queryResult.trace.evidenceCoverageRatio,
11371139
latencyMs: Date.now() - conversationStartedAtMs,
11381140
},
11391141
};

‎src/learning/types.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -653,6 +653,12 @@ export interface AgentConversationResponse {
653653
queryTopK: number;
654654
resolvedKnowledgePoints: number;
655655
retrievalModes: string[];
656+
vectorAcceleration: {
657+
mode: 'disabled' | 'local_prefilter';
658+
status: 'inactive' | 'prefilter_only' | 'independent';
659+
candidateCount: number;
660+
};
661+
evidenceCoverageRatio: number;
656662
latencyMs: number;
657663
};
658664
}

0 commit comments

Comments
 (0)