feat(agent-workspace): persist operator diagnostics reports via sidecar

Jacobinwwey · Jacobinwwey · commit 27a2684a5f0a · 2026-04-16T06:36:10.000-05:00
diff --git a/docs/brainstorms/2026-04-16-mainline-ci-stabilization-and-m7-direction-requirements.md b/docs/brainstorms/2026-04-16-mainline-ci-stabilization-and-m7-direction-requirements.md
@@ -258,6 +258,30 @@ Deliverables:
   - `npm test -- src/agent_workspace.runtime.behavior.test.ts --runInBand`
   - `npm run test:agent-workspace:contracts`
 
+### M7.7 (Now): Operator Route/Index Persistence and CI Evidence Gate Hardening (Lane Ops Bridge)
+
+Deliverables:
+
+- add sidecar route/index persistence for agent workspace diagnostics reports.
+- add runtime persistence bridge and harden CI evidence gates to fail fast on route/wiring drift.
+
+#### M7.7 Progress Note (2026-04-16)
+
+- [Done] expanded `src/server.ts` with diagnostics report persistence routes:
+  - `POST /api/knowledge/operator/agent-workspace-diagnostics/report`,
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/index`,
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/latest`,
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/report?reportId=...`.
+- [Done] expanded `src/frontend/agent_workspace_runtime.js` with `persistDiagnosticsReport()` to export and persist diagnostics via sidecar route.
+- [Done] expanded evidence coverage:
+  - `src/server.migration.test.ts` now asserts persist/index/latest/read-by-id flow and runtime-data file persistence,
+  - `src/knowledge.api.contract.test.ts` asserts operator diagnostics route contract presence,
+  - `src/agent_workspace.verification.contract.test.ts` + `scripts/verify-agent-workspace-runtime.js` assert runtime gate hardening.
+- [Done] verification evidence:
+  - `npm test -- src/server.migration.test.ts --runInBand --testNamePattern "agent workspace diagnostics report"`
+  - `npm run test:agent-workspace:contracts`
+  - `npm run verify:agent-workspace:runtime`
+
 ## Success Criteria
 
 - CI failure mode that previously blocked the three agent-workspace suites is eliminated on mainline.
@@ -267,4 +291,4 @@ Deliverables:
 
 ## Next Step
 
-Proceed to `/prompts:ce-plan` using this document as the source for `M7.7` decomposition (operator route/index persistence and CI evidence gate hardening), while preserving M7 lane boundary constraints.
+Proceed to `/prompts:ce-plan` using this document as the source for `M7.8` decomposition (operator runbook replay triage and bounded retention governance), while preserving M7 lane boundary constraints.
diff --git a/docs/diataxis/en/explanation/development-progress-dashboard.md b/docs/diataxis/en/explanation/development-progress-dashboard.md
@@ -331,6 +331,25 @@ Execution anchor:
   - `npm test -- src/agent_workspace.runtime.behavior.test.ts --runInBand`
   - `npm run test:agent-workspace:contracts`
 
+## Latest Mainline Increment (2026-04-16 M7.7 Operator Route/Index Persistence and CI Gate Hardening Lane)
+
+- Added sidecar persistence routes in `src/server.ts` for operator diagnostics report storage and retrieval:
+  - `POST /api/knowledge/operator/agent-workspace-diagnostics/report`,
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/index`,
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/latest`,
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/report?reportId=...`.
+- Added runtime bridge surface in `src/frontend/agent_workspace_runtime.js`:
+  - `persistDiagnosticsReport()` now exports snapshot/trend/index and persists it through the sidecar route.
+- Added executable evidence for route/index persistence:
+  - `src/server.migration.test.ts` now validates persist -> index -> latest -> read-by-id flow and file persistence in `runtime_data/agent_workspace_diagnostics/`.
+- Hardened runtime CI evidence gate:
+  - `scripts/verify-agent-workspace-runtime.js` now asserts diagnostics persistence route wiring and runtime `persistDiagnosticsReport` surface,
+  - `src/agent_workspace.verification.contract.test.ts` and `src/knowledge.api.contract.test.ts` now fail fast on route/gate drift.
+- Verification evidence:
+  - `npm test -- src/server.migration.test.ts --runInBand --testNamePattern \"agent workspace diagnostics report\"`
+  - `npm run test:agent-workspace:contracts`
+  - `npm run verify:agent-workspace:runtime`
+
 ## 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
@@ -333,6 +333,25 @@
   - `npm test -- src/agent_workspace.runtime.behavior.test.ts --runInBand`
   - `npm run test:agent-workspace:contracts`
 
+## 主线最新增量（2026-04-16 M7.7 运维路由/索引持久化与 CI 门禁加固链路）
+
+- 已在 `src/server.ts` 增加运维诊断报告持久化与读取路由：
+  - `POST /api/knowledge/operator/agent-workspace-diagnostics/report`,
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/index`,
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/latest`,
+  - `GET /api/knowledge/operator/agent-workspace-diagnostics/report?reportId=...`。
+- 已在 `src/frontend/agent_workspace_runtime.js` 增加运行时桥接接口：
+  - `persistDiagnosticsReport()` 导出 snapshot/trend/index 并通过 sidecar 路由持久化。
+- 已补可执行证据覆盖 route/index 持久化闭环：
+  - `src/server.migration.test.ts` 覆盖 persist -> index -> latest -> read-by-id 链路，并验证 `runtime_data/agent_workspace_diagnostics/` 文件落盘。
+- 已加固 runtime CI 证据门禁：
+  - `scripts/verify-agent-workspace-runtime.js` 新增诊断持久化路由与 runtime `persistDiagnosticsReport` 接线断言，
+  - `src/agent_workspace.verification.contract.test.ts` 与 `src/knowledge.api.contract.test.ts` 新增 fail-fast 契约断言，防止路由/门禁漂移。
+- 验证证据：
+  - `npm test -- src/server.migration.test.ts --runInBand --testNamePattern \"agent workspace diagnostics report\"`
+  - `npm run test:agent-workspace:contracts`
+  - `npm run verify:agent-workspace:runtime`
+
 ## 主线 vs 工作分支快照（2026-04-14）
 
 | 能力切片 | 工作分支（`feat/learning-multi-tutor-adapter`） | 主线（`origin/main`） | 集成状态 |
diff --git a/scripts/verify-agent-workspace-runtime.js b/scripts/verify-agent-workspace-runtime.js
@@ -87,10 +87,27 @@ function verifyAgentWorkspaceRuntime(repoRoot = path.resolve(__dirname, '..')) {
   assert(fs.existsSync(contractFilePath), `Missing contract file: ${contractFilePath}`);
 
   const serverSource = readText(serverPath);
+  const runtimeSource = readText(runtimeFilePath);
   assert(
     serverSource.includes('/api/knowledge/conversation'),
     'Missing /api/knowledge/conversation runtime route in src/server.ts'
   );
+  assert(
+    serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/report'),
+    'Missing diagnostics report persistence route in src/server.ts'
+  );
+  assert(
+    serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/index'),
+    'Missing diagnostics report index route in src/server.ts'
+  );
+  assert(
+    serverSource.includes('/api/knowledge/operator/agent-workspace-diagnostics/latest'),
+    'Missing diagnostics report latest route in src/server.ts'
+  );
+  assert(
+    runtimeSource.includes('persistDiagnosticsReport'),
+    'Missing persistDiagnosticsReport runtime surface in src/frontend/agent_workspace_runtime.js'
+  );
 
   runNpm(repoRoot, ['run', 'test:agent-workspace:contracts']);
 
@@ -101,6 +118,8 @@ function verifyAgentWorkspaceRuntime(repoRoot = path.resolve(__dirname, '..')) {
       'frontend runtime shell exists',
       'frontend contract module exists',
       'conversation route wiring exists',
+      'diagnostics report persistence routes exist',
+      'runtime diagnostics persistence surface exists',
       'agent workspace contract test suite passes',
     ],
   };
diff --git a/src/agent_workspace.runtime.behavior.test.ts b/src/agent_workspace.runtime.behavior.test.ts
@@ -46,6 +46,7 @@ type AgentRuntimeModule = {
             };
         };
         exportDiagnosticsReport: (options?: { format?: string }) => string | Record<string, unknown>;
+        persistDiagnosticsReport: (options?: { endpoint?: string; source?: string }) => Promise<Record<string, unknown>>;
     };
 };
 
@@ -1603,6 +1604,20 @@ describe('agent workspace runtime behavior', () => {
                         divergencePaths: [{ id: 'divergence-1' }],
                     },
                 }),
+            })
+            .mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    success: true,
+                    result: {
+                        metadata: {
+                            reportId: 'awd-1',
+                            source: 'agent-workspace-runtime',
+                        },
+                        indexCount: 1,
+                    },
+                }),
             });
         (global as unknown as Record<string, unknown>).fetch = fetchMock;
 
@@ -1706,5 +1721,35 @@ describe('agent workspace runtime behavior', () => {
                 }),
             ])
         );
+
+        const persistResult = await runtime.persistDiagnosticsReport();
+        expect(persistResult).toEqual(
+            expect.objectContaining({
+                metadata: expect.objectContaining({
+                    reportId: 'awd-1',
+                }),
+                indexCount: 1,
+            })
+        );
+        const persistCall = fetchMock.mock.calls[3];
+        expect(persistCall[0]).toBe('/api/knowledge/operator/agent-workspace-diagnostics/report');
+        expect(persistCall[1]).toEqual(
+            expect.objectContaining({
+                method: 'POST',
+            })
+        );
+        const persistedBody = JSON.parse(String(persistCall[1].body));
+        expect(persistedBody.source).toBe('agent-workspace-runtime');
+        expect(persistedBody.report).toEqual(
+            expect.objectContaining({
+                snapshot: expect.objectContaining({
+                    conversationRequests: 2,
+                }),
+                trend: expect.objectContaining({
+                    replayCandidateRate: 0.5,
+                }),
+                index: expect.any(Object),
+            })
+        );
     });
 });
diff --git a/src/agent_workspace.runtime.integration.test.ts b/src/agent_workspace.runtime.integration.test.ts
@@ -31,6 +31,7 @@ describe('agent workspace runtime integration baseline', () => {
         expect(runtimeSource).toContain('/api/knowledge/mastery/misconceptions');
         expect(runtimeSource).toContain('/api/knowledge/quality/snapshot');
         expect(runtimeSource).toContain('/api/knowledge/memory/policy');
+        expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/report');
         expect(runtimeSource).toContain('focusOnNode');
         expect(runtimeSource).toContain('enterFocusMode');
         expect(runtimeSource).toContain('agent-workspace-path-docked');
@@ -41,6 +42,7 @@ describe('agent workspace runtime integration baseline', () => {
         expect(runtimeSource).toContain('getDiagnosticsTrendSnapshot');
         expect(runtimeSource).toContain('getDiagnosticsIndexSnapshot');
         expect(runtimeSource).toContain('exportDiagnosticsReport');
+        expect(runtimeSource).toContain('persistDiagnosticsReport');
         expect(runtimeSource).toContain('DIAGNOSTIC_RUNBOOK_LINKS');
         expect(runtimeSource).toContain('__noteConnectionAgentWorkspaceRuntimeInstance');
     });
diff --git a/src/agent_workspace.verification.contract.test.ts b/src/agent_workspace.verification.contract.test.ts
@@ -44,6 +44,10 @@ describe('agent workspace verification script contracts', () => {
     const tauriSource = fs.readFileSync(tauriVerifyPath, 'utf8');
 
     expect(runtimeSource).toContain('verifyAgentWorkspaceRuntime');
+    expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/report');
+    expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/index');
+    expect(runtimeSource).toContain('/api/knowledge/operator/agent-workspace-diagnostics/latest');
+    expect(runtimeSource).toContain('persistDiagnosticsReport');
     expect(browserSource).toContain('verifyAgentWorkspaceBrowser');
     expect(tauriSource).toContain('verifyAgentWorkspaceTauri');
   });
diff --git a/src/frontend/agent_workspace_runtime.js b/src/frontend/agent_workspace_runtime.js
@@ -688,6 +688,17 @@
                 return report;
             }
 
+            async function persistDiagnosticsReport(options = {}) {
+                const endpoint = trimString(options && options.endpoint)
+                    || '/api/knowledge/operator/agent-workspace-diagnostics/report';
+                const source = trimString(options && options.source) || 'agent-workspace-runtime';
+                const report = exportDiagnosticsReport();
+                return requestJson(endpoint, {
+                    source,
+                    report,
+                });
+            }
+
             function resolveUserId() {
                 const fallback = trimString(options.defaultUserId) || 'agent_user_default';
                 const candidate = trimString(dom.userIdInput && dom.userIdInput.value);
@@ -1455,6 +1466,7 @@
                 getDiagnosticsTrendSnapshot,
                 getDiagnosticsIndexSnapshot,
                 exportDiagnosticsReport,
+                persistDiagnosticsReport,
                 _state: state,
             };
         }
diff --git a/src/knowledge.api.contract.test.ts b/src/knowledge.api.contract.test.ts
@@ -9,6 +9,9 @@ describe('Knowledge mastery API contract wiring', () => {
         const endpoints = [
             '/api/knowledge/state',
             '/api/knowledge/store-diagnostics',
+            '/api/knowledge/operator/agent-workspace-diagnostics/index',
+            '/api/knowledge/operator/agent-workspace-diagnostics/latest',
+            '/api/knowledge/operator/agent-workspace-diagnostics/report',
             '/api/knowledge/store/reload',
             '/api/knowledge/ingest',
             '/api/knowledge/ingest-diff',
diff --git a/src/server.migration.test.ts b/src/server.migration.test.ts
@@ -420,6 +420,122 @@ describe('server migration settings routes', () => {
     expect(response.body.runtime.authToken).toBeUndefined();
   });
 
+  test('persists agent workspace diagnostics report and exposes index/latest/read-by-id routes', async () => {
+    const reportPayload = {
+      snapshot: {
+        conversationRequests: 2,
+        replayCandidateTurns: 1,
+        turnCounts: {
+          user: 2
+        },
+        capabilityEvents: [
+          { eventId: 'cap_1', status: 'success' },
+          { eventId: 'cap_2', status: 'success' }
+        ],
+        lastFailure: null
+      },
+      trend: {
+        userTurns: 2
+      },
+      index: {
+        capabilityIndex: {
+          operationIds: ['build_learning_path']
+        }
+      }
+    };
+
+    const createResponse = await requestJson(
+      port,
+      'POST',
+      '/api/knowledge/operator/agent-workspace-diagnostics/report',
+      {
+        source: 'server-migration-test',
+        report: reportPayload
+      }
+    );
+    expect(createResponse.status).toBe(200);
+    expect(createResponse.body.success).toBe(true);
+    expect(createResponse.body.result).toEqual(
+      expect.objectContaining({
+        indexCount: 1,
+        metadata: expect.objectContaining({
+          reportId: expect.stringMatching(/^awd-/),
+          source: 'server-migration-test',
+          summary: expect.objectContaining({
+            conversationRequests: 2,
+            replayCandidateTurns: 1,
+            userTurns: 2,
+            capabilityEvents: 2,
+            hasLastFailure: false
+          })
+        })
+      })
+    );
+    const reportId = createResponse.body.result.metadata.reportId as string;
+
+    const indexResponse = await requestJson(
+      port,
+      'GET',
+      '/api/knowledge/operator/agent-workspace-diagnostics/index'
+    );
+    expect(indexResponse.status).toBe(200);
+    expect(indexResponse.body.success).toBe(true);
+    expect(indexResponse.body.count).toBe(1);
+    expect(indexResponse.body.index[0]).toEqual(
+      expect.objectContaining({
+        reportId,
+        source: 'server-migration-test'
+      })
+    );
+
+    const latestResponse = await requestJson(
+      port,
+      'GET',
+      '/api/knowledge/operator/agent-workspace-diagnostics/latest'
+    );
+    expect(latestResponse.status).toBe(200);
+    expect(latestResponse.body.success).toBe(true);
+    expect(latestResponse.body.latest).toEqual(
+      expect.objectContaining({
+        metadata: expect.objectContaining({
+          reportId,
+          source: 'server-migration-test'
+        }),
+        report: expect.objectContaining({
+          snapshot: expect.objectContaining({
+            conversationRequests: 2
+          })
+        })
+      })
+    );
+
+    const byIdResponse = await requestJson(
+      port,
+      'GET',
+      `/api/knowledge/operator/agent-workspace-diagnostics/report?reportId=${encodeURIComponent(reportId)}`
+    );
+    expect(byIdResponse.status).toBe(200);
+    expect(byIdResponse.body.success).toBe(true);
+    expect(byIdResponse.body.result).toEqual(
+      expect.objectContaining({
+        metadata: expect.objectContaining({
+          reportId
+        }),
+        report: expect.objectContaining({
+          snapshot: expect.objectContaining({
+            conversationRequests: 2
+          })
+        })
+      })
+    );
+
+    const reportPath = path.join(runtimeDataDir, 'agent_workspace_diagnostics', `${reportId}.json`);
+    await expect(fs.promises.readFile(reportPath, 'utf8')).resolves.toContain('"conversationRequests": 2');
+    await expect(
+      fs.promises.readFile(path.join(runtimeDataDir, 'agent_workspace_diagnostics', 'index.v1.json'), 'utf8')
+    ).resolves.toContain(reportId);
+  });
+
   test('server runtime path avoids synchronous filesystem APIs', () => {
     const serverSourcePath = path.join(__dirname, 'server.ts');
     const serverSource = fs.readFileSync(serverSourcePath, 'utf8');
diff --git a/src/server.ts b/src/server.ts
