feat(agent-workspace): add query trace capability lane

Jacobinwwey · Jacobinwwey · commit 474259f20d89 · 2026-04-14T09:26:47.000-05:00
diff --git a/docs/brainstorms/2026-04-14-mainline-reality-reconciliation-and-next-direction-requirements.md b/docs/brainstorms/2026-04-14-mainline-reality-reconciliation-and-next-direction-requirements.md
@@ -231,6 +231,18 @@ npm run verify:agent-workspace:tauri
   - frontend payload-builder misconception endpoint/body assertions,
   - runtime endpoint/payload/message assertions for misconception inspection execution.
 
+#### M6.9 Progress Note (2026-04-14)
+
+- [Done] typed conversation capability surface expanded with `inspect_query_trace` action, `query_knowledge` operation, and `query_trace_card` presentation.
+- [Done] conversation capability emission now includes scoped query-trace inspection execution through `/api/knowledge/query`.
+- [Done] contract/runtime planners preserve bounded query payload shaping:
+  - non-empty `query` enforcement,
+  - bounded `topK`.
+- [Done] regression coverage expanded for:
+  - query-trace capability wiring in conversation output,
+  - frontend payload-builder query endpoint/body assertions,
+  - runtime endpoint/payload/message assertions for query-trace execution.
+
 ### M7 (Future): Foundation Lane Re-entry (Evidence-First)
 
 Entry criteria:
diff --git a/docs/diataxis/en/explanation/development-progress-dashboard.md b/docs/diataxis/en/explanation/development-progress-dashboard.md
@@ -203,6 +203,21 @@ Execution anchor:
   - frontend misconception payload-builder endpoint/body assertions,
   - runtime endpoint/payload/message assertions for misconception execution and rendering.
 
+## Latest Mainline Increment (2026-04-14 M6.9 Query Trace Capability Lane)
+
+- Added `inspect_query_trace` to the typed conversation action union on mainline.
+- Extended capability operation/result unions with:
+  - `query_knowledge`,
+  - `query_trace_card`.
+- Extended `runAgentConversation(...)` capability emission to include query-trace inspection through `/api/knowledge/query`.
+- Kept contract/runtime planner behavior aligned for query payload shaping:
+  - non-empty `query`,
+  - bounded `topK`.
+- Expanded regression coverage for:
+  - query-trace capability wiring in conversation output,
+  - frontend query payload-builder endpoint/body assertions,
+  - runtime endpoint/payload/message assertions for query-trace execution and rendering.
+
 ## Mainline vs Working-Branch Snapshot (2026-04-14)
 
 | Capability Slice | Working Branch (`feat/learning-multi-tutor-adapter`) | Mainline (`origin/main`) | Integration Status |
diff --git a/docs/diataxis/zh/explanation/development-progress-dashboard.md b/docs/diataxis/zh/explanation/development-progress-dashboard.md
@@ -203,6 +203,21 @@
   - 前端 misconception payload-builder 的 endpoint/body 断言，
   - runtime misconception 路径 endpoint/payload/消息断言。
 
+## 主线最新增量（2026-04-14 M6.9 检索追踪能力链路）
+
+- 主线 typed conversation action union 新增 `inspect_query_trace`。
+- capability operation/result union 同步扩展：
+  - `query_knowledge`，
+  - `query_trace_card`。
+- `runAgentConversation(...)` capability 输出新增检索追踪动作，执行路径对接 `/api/knowledge/query`。
+- contract/runtime payload 规划保持对齐：
+  - `query` 非空约束，
+  - `topK` 有界收敛。
+- 回归覆盖同步扩展：
+  - conversation 输出中的 query-trace capability 连线断言，
+  - 前端 query payload-builder 的 endpoint/body 断言，
+  - runtime query-trace 路径 endpoint/payload/消息断言。
+
 ## 主线 vs 工作分支快照（2026-04-14）
 
 | 能力切片 | 工作分支（`feat/learning-multi-tutor-adapter`） | 主线（`origin/main`） | 集成状态 |
diff --git a/src/agent_workspace.contract.parity.test.ts b/src/agent_workspace.contract.parity.test.ts
@@ -13,6 +13,7 @@ describe('agent_workspace contract parity', () => {
             'build_learning_path',
             'execute_tutor_action',
             'build_study_session',
+            'query_knowledge',
             'query_session_history',
             'query_mastery_misconceptions',
             'capture_learning_quality_snapshot',
@@ -29,6 +30,7 @@ describe('agent_workspace contract parity', () => {
             'learning_path_card',
             'tutor_action_card',
             'study_session_card',
+            'query_trace_card',
             'session_history_card',
             'mastery_misconceptions_card',
             'learning_quality_snapshot_card',
diff --git a/src/agent_workspace.frontend.test.ts b/src/agent_workspace.frontend.test.ts
@@ -187,6 +187,31 @@ describe('agent_workspace frontend operation contract', () => {
         });
     });
 
+    test('query_knowledge builds bounded query trace payload', () => {
+        const requestPlan = buildKnowledgeOperationRequestPayload({
+            request: {
+                userId: 'learner-a',
+                atomId: 'atom-2',
+                query: 'retrieval stabilization',
+                topK: 6,
+            },
+            execution: {
+                operationId: 'query_knowledge',
+            },
+        });
+
+        expect(requestPlan).toEqual({
+            operationId: 'query_knowledge',
+            endpoint: '/api/knowledge/query',
+            method: 'POST',
+            resultPresentation: 'query_trace_card',
+            body: {
+                query: 'retrieval stabilization',
+                topK: 6,
+            },
+        });
+    });
+
     test('query_session_history builds bounded history payload', () => {
         const requestPlan = buildKnowledgeOperationRequestPayload({
             request: {
@@ -369,6 +394,7 @@ describe('agent_workspace frontend operation contract', () => {
             build_learning_path: 'learning_path_card',
             execute_tutor_action: 'assistant_message',
             build_study_session: 'study_session_card',
+            query_knowledge: 'query_trace_card',
             query_session_history: 'session_history_card',
             query_mastery_misconceptions: 'mastery_misconceptions_card',
             capture_learning_quality_snapshot: 'learning_quality_snapshot_card',
@@ -380,6 +406,9 @@ describe('agent_workspace frontend operation contract', () => {
         expect(diagnostics.operationAllowedResultPresentations.build_study_session).toEqual(
             expect.arrayContaining(['study_session_card'])
         );
+        expect(diagnostics.operationAllowedResultPresentations.query_knowledge).toEqual(
+            expect.arrayContaining(['query_trace_card'])
+        );
         expect(diagnostics.operationAllowedResultPresentations.query_session_history).toEqual(
             expect.arrayContaining(['session_history_card'])
         );
diff --git a/src/agent_workspace.runtime.behavior.test.ts b/src/agent_workspace.runtime.behavior.test.ts
@@ -82,6 +82,8 @@ describe('agent workspace runtime behavior', () => {
                     ? '/api/knowledge/path'
                     : operationId === 'build_study_session'
                         ? '/api/knowledge/session/plan'
+                        : operationId === 'query_knowledge'
+                            ? '/api/knowledge/query'
                         : operationId === 'query_session_history'
                             ? '/api/knowledge/session/history'
                             : operationId === 'query_mastery_misconceptions'
@@ -111,6 +113,18 @@ describe('agent workspace runtime behavior', () => {
                         },
                     };
                 }
+                if (operationId === 'query_knowledge') {
+                    return {
+                        operationId,
+                        endpoint,
+                        method: 'POST',
+                        resultPresentation: capability.execution.resultPresentation,
+                        body: {
+                            query: request.query || request.message || '',
+                            topK: Number.isFinite(Number(request.topK)) ? Number(request.topK) : 4,
+                        },
+                    };
+                }
                 if (operationId === 'query_mastery_misconceptions') {
                     return {
                         operationId,
@@ -373,6 +387,92 @@ describe('agent workspace runtime behavior', () => {
         expect(messages.textContent || '').toContain('Study session built');
     });
 
+    test('executes query trace capability and renders retrieval summary', async () => {
+        const fetchMock = jest
+            .fn()
+            .mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    success: true,
+                    result: {
+                        userId: 'agent_user_default',
+                        message: 'Found 1 local knowledge point(s).',
+                        knowledgePoints: [
+                            {
+                                atomId: 'atom-query-1',
+                                title: 'Query Candidate',
+                                snippet: 'Inspect retrieval trace.',
+                                score: 0.79,
+                                capabilities: [
+                                    {
+                                        actionId: 'inspect_query_trace',
+                                        label: 'Query Trace',
+                                        request: {
+                                            userId: 'agent_user_default',
+                                            atomId: 'atom-query-1',
+                                            query: 'retrieval loop',
+                                            topK: 5,
+                                        },
+                                        execution: {
+                                            kind: 'knowledge_operation',
+                                            operationId: 'query_knowledge',
+                                            resultPresentation: 'query_trace_card',
+                                        },
+                                    },
+                                ],
+                            },
+                        ],
+                    },
+                }),
+            })
+            .mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    success: true,
+                    result: {
+                        items: [{ atom: { id: 'a1' } }, { atom: { id: 'a2' } }],
+                        trace: {
+                            retrievalModes: ['keyword', 'graph_traversal'],
+                            latencyMs: 17,
+                            evidenceCoverageRatio: 0.75,
+                        },
+                    },
+                }),
+            });
+        (global as unknown as Record<string, unknown>).fetch = fetchMock;
+
+        const runtime = runtimeModule.createAgentWorkspaceRuntime({ defaultUserId: 'agent_user_default' });
+        runtime.init();
+
+        const input = document.getElementById('agent-workspace-input') as HTMLTextAreaElement;
+        const form = document.getElementById('agent-workspace-form') as HTMLFormElement;
+        input.value = 'inspect query trace';
+        form.dispatchEvent(new dom!.window.Event('submit', { bubbles: true, cancelable: true }));
+        await flushAsync();
+
+        const actionButton = document.querySelector('.agent-workspace-action-button') as HTMLButtonElement;
+        expect(actionButton).not.toBeNull();
+        actionButton.click();
+        await flushAsync();
+
+        expect(fetchMock).toHaveBeenNthCalledWith(
+            2,
+            '/api/knowledge/query',
+            expect.objectContaining({ method: 'POST' })
+        );
+        const payload = JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body || '{}')) as {
+            query?: string;
+            topK?: number;
+        };
+        expect(payload.query).toBe('retrieval loop');
+        expect(payload.topK).toBe(5);
+
+        const messages = document.getElementById('agent-workspace-messages') as HTMLElement;
+        expect(messages.textContent || '').toContain('Query trace loaded');
+    });
+
     test('executes mastery misconceptions capability and renders summary message', async () => {
         const fetchMock = jest
             .fn()
diff --git a/src/agent_workspace.runtime.integration.test.ts b/src/agent_workspace.runtime.integration.test.ts
@@ -25,6 +25,7 @@ describe('agent workspace runtime integration baseline', () => {
         const runtimeSource = fs.readFileSync(runtimePath, 'utf8');
         expect(runtimeSource).toContain('/api/knowledge/conversation');
         expect(runtimeSource).toContain('/api/knowledge/session/plan');
+        expect(runtimeSource).toContain('/api/knowledge/query');
         expect(runtimeSource).toContain('/api/knowledge/session/history');
         expect(runtimeSource).toContain('/api/knowledge/mastery/misconceptions');
         expect(runtimeSource).toContain('/api/knowledge/quality/snapshot');
diff --git a/src/frontend/agent_workspace.js b/src/frontend/agent_workspace.js
@@ -32,6 +32,12 @@
                 defaultResultPresentation: 'study_session_card',
                 allowedResultPresentations: Object.freeze(['study_session_card']),
             }),
+            query_knowledge: Object.freeze({
+                endpoint: '/api/knowledge/query',
+                method: 'POST',
+                defaultResultPresentation: 'query_trace_card',
+                allowedResultPresentations: Object.freeze(['query_trace_card']),
+            }),
             query_session_history: Object.freeze({
                 endpoint: '/api/knowledge/session/history',
                 method: 'POST',
@@ -135,6 +141,13 @@
             return Math.max(1, Math.min(20, Math.floor(base)));
         }
 
+        function resolveQueryTopK(rawTopK, fallback) {
+            const numericTopK = Number(rawTopK);
+            const numericFallback = Number(fallback);
+            const base = Number.isFinite(numericTopK) ? numericTopK : (Number.isFinite(numericFallback) ? numericFallback : 4);
+            return Math.max(1, Math.min(8, Math.floor(base)));
+        }
+
         function createAgentConversationPayload(options) {
             const source = options || {};
             const userId = typeof source.userId === 'string' ? source.userId.trim() : '';
@@ -259,6 +272,23 @@
                 };
             }
 
+            if (operationId === 'query_knowledge') {
+                const query = resolveCapabilityMessage(request.query || request.message);
+                if (!query) {
+                    throw new Error('query_knowledge requires request.query or request.message.');
+                }
+                return {
+                    operationId,
+                    endpoint: config.endpoint,
+                    method: config.method,
+                    resultPresentation,
+                    body: {
+                        query,
+                        topK: resolveQueryTopK(request.topK, 4),
+                    },
+                };
+            }
+
             if (operationId === 'query_session_history') {
                 const userId = String(request.userId || '').trim();
                 if (!userId) {
diff --git a/src/frontend/agent_workspace_runtime.js b/src/frontend/agent_workspace_runtime.js
@@ -87,6 +87,13 @@
             return Math.max(1, Math.min(20, Math.floor(base)));
         }
 
+        function resolveQueryTopK(rawTopK, fallback) {
+            const numericTopK = Number(rawTopK);
+            const numericFallback = Number(fallback);
+            const base = Number.isFinite(numericTopK) ? numericTopK : (Number.isFinite(numericFallback) ? numericFallback : 4);
+            return Math.max(1, Math.min(8, Math.floor(base)));
+        }
+
         function getI18nText(key, fallback, params) {
             if (
                 globalScope
@@ -212,6 +219,22 @@
                     },
                 };
             }
+            if (operationId === 'query_knowledge') {
+                const query = trimString(request.query || request.message);
+                if (!query) {
+                    throw new Error('query_knowledge requires request.query or request.message.');
+                }
+                return {
+                    operationId,
+                    endpoint: '/api/knowledge/query',
+                    method: 'POST',
+                    resultPresentation: trimString(execution.resultPresentation) || 'query_trace_card',
+                    body: {
+                        query,
+                        topK: resolveQueryTopK(request.topK, 4),
+                    },
+                };
+            }
             if (operationId === 'query_session_history') {
                 return {
                     operationId,
@@ -587,6 +610,30 @@
                     return;
                 }
 
+                if (presentation === 'query_trace_card') {
+                    const trace = result && result.trace && typeof result.trace === 'object'
+                        ? result.trace
+                        : {};
+                    const itemsCount = Array.isArray(result && result.items) ? result.items.length : 0;
+                    const retrievalModes = Array.isArray(trace.retrievalModes) ? trace.retrievalModes.join(', ') : '';
+                    const latencyMs = Number(trace.latencyMs);
+                    const evidenceCoverageRatio = Number(trace.evidenceCoverageRatio);
+                    appendMessage(
+                        'assistant',
+                        getI18nText(
+                            'agentWorkspace.messages.queryTraceLoaded',
+                            `Query trace loaded (${itemsCount} hits, modes ${retrievalModes || 'n/a'}, latency ${Number.isFinite(latencyMs) ? latencyMs : 0} ms, evidence ${Number.isFinite(evidenceCoverageRatio) ? evidenceCoverageRatio.toFixed(2) : '0.00'}).`,
+                            {
+                                itemsCount,
+                                retrievalModes: retrievalModes || 'n/a',
+                                latencyMs: Number.isFinite(latencyMs) ? latencyMs : 0,
+                                evidenceCoverageRatio: Number.isFinite(evidenceCoverageRatio) ? evidenceCoverageRatio.toFixed(2) : '0.00',
+                            }
+                        )
+                    );
+                    return;
+                }
+
                 if (presentation === 'session_history_card') {
                     const summary = result && result.summary && typeof result.summary === 'object'
                         ? result.summary
diff --git a/src/frontend/locales/en.json b/src/frontend/locales/en.json
@@ -240,6 +240,7 @@
       "generateTransfer": "Generate Transfer",
       "generateCounterexample": "Generate Counterexample",
       "buildStudySession": "Build Session",
+      "inspectQueryTrace": "Query Trace",
       "inspectSessionHistory": "Session History",
       "inspectMasteryMisconceptions": "Mastery Misconceptions",
       "inspectLearningQualitySnapshot": "Learning Quality",
@@ -267,6 +268,8 @@
       "analyzeAnswerRequired": "Analyze answer requires a non-empty learner answer.",
       "studySessionBuildFailed": "Study session build failed.",
       "studySessionBuilt": "Study session built ({totalActions} actions, {totalEstimatedMinutes} min).",
+      "queryTraceFailed": "Query trace request failed.",
+      "queryTraceLoaded": "Query trace loaded ({itemsCount} hits, modes {retrievalModes}, latency {latencyMs} ms, evidence {evidenceCoverageRatio}).",
       "sessionHistoryFailed": "Session history request failed.",
       "sessionHistoryLoaded": "Session history loaded ({totalRecords} sessions, {totalExecutedActions} actions).",
       "masteryMisconceptionsFailed": "Mastery misconceptions request failed.",
diff --git a/src/frontend/locales/zh.json b/src/frontend/locales/zh.json
diff --git a/src/learning/KnowledgeLearningPlatform.test.ts b/src/learning/KnowledgeLearningPlatform.test.ts
diff --git a/src/learning/KnowledgeLearningPlatform.ts b/src/learning/KnowledgeLearningPlatform.ts
diff --git a/src/learning/types.ts b/src/learning/types.ts
