Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
feat(ok): Wave 2 group 2: orphans/hubs + metrics native (PRD-7827) (#3268)
omar-inkeepfa5716fcb765
diff --git a/packages/app/tests/integration/attribution-sweep-coverage.test.ts b/packages/app/tests/integration/attribution-sweep-coverage.test.tsindex 624f3679d..854154142 100644--- a/packages/app/tests/integration/attribution-sweep-coverage.test.ts+++ b/packages/app/tests/integration/attribution-sweep-coverage.test.ts@@ -26,7 +26,7 @@ const source = readFileSync(API_EXT_PATH, 'utf8');*/const HANDLER_SOURCES = [source,- ...['skills-sh-handlers.ts', 'http/link-graph-routes.ts'].map((file) =>+ ...['skills-sh-handlers.ts', 'http/link-graph-routes.ts', 'http/metrics-routes.ts'].map((file) =>readFileSync(join(import.meta.dirname, '../../../server/src', file), 'utf8'),),];diff --git a/packages/app/tests/integration/conflict-gate-coverage.test.ts b/packages/app/tests/integration/conflict-gate-coverage.test.tsindex 34a583047..2768dd481 100644--- a/packages/app/tests/integration/conflict-gate-coverage.test.ts+++ b/packages/app/tests/integration/conflict-gate-coverage.test.ts@@ -35,7 +35,7 @@ const source = readFileSync(API_EXT_PATH, 'utf8');*/const HANDLER_SOURCES = [source,- ...['skills-sh-handlers.ts', 'http/link-graph-routes.ts'].map((file) =>+ ...['skills-sh-handlers.ts', 'http/link-graph-routes.ts', 'http/metrics-routes.ts'].map((file) =>readFileSync(join(import.meta.dirname, '../../../server/src', file), 'utf8'),),];diff --git a/packages/app/tests/integration/error-envelope-coverage.test.ts b/packages/app/tests/integration/error-envelope-coverage.test.tsindex a53da8f4b..635de2ea3 100644--- a/packages/app/tests/integration/error-envelope-coverage.test.ts+++ b/packages/app/tests/integration/error-envelope-coverage.test.ts@@ -32,6 +32,7 @@ const HANDLER_SOURCES = ['api-extension.ts','skills-sh-handlers.ts','http/link-graph-routes.ts',+ 'http/metrics-routes.ts',].map((file) => ({file,text: readFileSync(join(SERVER_SRC, file), 'utf8'),diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.tsindex 1a19a0b6b..ae5d1e171 100644--- a/packages/server/src/api-extension.ts+++ b/packages/server/src/api-extension.ts@@ -91,11 +91,9 @@ import {FrontmatterPatchSuccessSchema,FrontmatterSchemasListSuccessSchema,FrontmatterSchemaWriteRequestSchema,- getParseHealth,type HeadingEntry,HistorySuccessSchema,HistoryVersionSuccessSchema,- HubsSuccessSchema,type InlineAssetMediaKind,InstallSkillRequestSchema,InstallSkillSuccessSchema,@@ -141,17 +139,9 @@ import {MANAGED_ARTIFACT_PREFIX_SKILL,MANAGED_ARTIFACT_PREFIX_TEMPLATE,MarkdownlintRuleWriteRequestSchema,- type MetricsAgentEffectsSuccess,- MetricsAgentEffectsSuccessSchema,- MetricsAgentPresenceSuccessSchema,- MetricsParseHealthSuccessSchema,- MetricsReconciliationSuccessSchema,- type MetricsWatcherRecentSuccess,- MetricsWatcherRecentSuccessSchema,mediaKindForSidebarAssetExtension,OK_DIR,OPENKNOWLEDGE_SKILLS_REPO,- OrphansSuccessSchema,PageHeadingsSuccessSchema,PagesSuccessSchema,PROJECT_SKILL_EDITOR_IDS,@@ -312,10 +302,10 @@ import {registryPlatformKey,} from './acp/registry.ts';import { MAX_ACP_THREADS } from './acp/thread-manager.ts';-import { captureEffect, type EffectValue } from './activity-log.ts';+import { captureEffect } from './activity-log.ts';import { listAgentActivity, synthesizeVersionDiff } from './agent-activity.ts';import type { AgentFocusBroadcaster } from './agent-focus.ts';-import { type AgentPresenceBroadcaster, BROADCASTER_EVICTION_MS } from './agent-presence.ts';+import type { AgentPresenceBroadcaster } from './agent-presence.ts';import {AgentSessionCapacityError,type AgentSessionManager,@@ -549,7 +539,6 @@ import {type DerivedDocumentIndexApiPort,type DerivedDocumentIndexMutation,isDerivedDocumentIndexClosedError,- isDerivedOrphanMode,} from './derived-document-index.ts';import {docNameToRelativePath,@@ -574,7 +563,6 @@ import {type DiskEvent,type FileIndexEntry,type FolderIndexEntry,- getWatcherDecisionRingSnapshot,registerWrite,removeFolderIndexEntries as removeFolderIndexEntriesFromIndex,updateFileIndex,@@ -612,6 +600,7 @@ import { errnoCode, parseQuery } from './http/handler-utils.ts';import { assertSingleRouterOwnership, type NativeApiHandle } from './http/http-app.ts';import { createLinkGraphRoutes } from './http/link-graph-routes.ts';import { methodRouter } from './http/method-router.ts';+import { createMetricsRoutes } from './http/metrics-routes.ts';import { getRequestId } from './http/request-id.ts';import { validateBody, withValidation } from './http/request-validation.ts';import { successResponse } from './http/success-response.ts';@@ -662,7 +651,6 @@ import {} from './managed-rename-journal.ts';import { rewriteAssetReferencesForRename } from './managed-rename-rewrite.ts';import {- getMetrics,incrementAgentPatchFindMismatches,incrementAgentWriteCalls,incrementSummariesProvided,@@ -7247,85 +7235,6 @@ export function createApiExtension({ handler: 'comment-counts', method: 'GET', skipBodyParse: true },);- const handleOrphans = withValidation(- EmptyRequestSchema,- async (req, res) => {- if (!derivedDocumentIndex) {- errorResponse(- res,- 503,- 'urn:ok:error:backlink-index-not-configured',- 'Backlink index is not configured.',- { handler: 'orphans' },- );- return;- }- try {- const url = new URL(req.url ?? '', 'http://localhost');- const mode = url.searchParams.get('mode') ?? 'both';- if (!isDerivedOrphanMode(mode)) {- errorResponse(- res,- 400,- 'urn:ok:error:invalid-request',- 'Invalid orphan mode. Allowed values: incoming, outgoing, both.',- { handler: 'orphans' },- );- return;- }-- const orphans = (- await derivedDocumentIndex.getOrphans([...getFileIndex().keys()], mode)- ).map((docName) => ({- docName,- title: readPageTitleForDocName(docName),- }));- successResponse(res, 200, OrphansSuccessSchema, { orphans }, { handler: 'orphans' });- } catch (e) {- respondToDerivedIndexQueryFailure(res, e, {- handler: 'orphans',- failureTitle: 'Failed to read orphan pages.',- });- }- },- { handler: 'orphans', method: 'GET', skipBodyParse: true },- );-- const handleHubs = withValidation(- EmptyRequestSchema,- async (req, res) => {- if (!derivedDocumentIndex) {- errorResponse(- res,- 503,- 'urn:ok:error:backlink-index-not-configured',- 'Backlink index is not configured.',- { handler: 'hubs' },- );- return;- }- try {- const url = new URL(req.url ?? '', 'http://localhost');- const rawLimit = url.searchParams.get('limit');- const parsed = rawLimit ? Number.parseInt(rawLimit, 10) : 20;- const limit = Number.isFinite(parsed) && parsed > 0 ? parsed : 20;- const admitted = await collectAdmittedDocNames();- const hubs = (await derivedDocumentIndex.getHubs(limit)).map((hub) => ({- docName: hub.docName,- title: readPageTitleForLinkedDocName(hub.docName, admitted),- count: hub.count,- }));- successResponse(res, 200, HubsSuccessSchema, { hubs }, { handler: 'hubs' });- } catch (e) {- respondToDerivedIndexQueryFailure(res, e, {- handler: 'hubs',- failureTitle: 'Failed to read hub pages.',- });- }- },- { handler: 'hubs', method: 'GET', skipBodyParse: true },- );-const handleAgentPatch = withValidation(AgentPatchRequestSchema,async (_req, res, body) => {@@ -8980,48 +8889,6 @@ export function createApiExtension({ handler: 'rollback', method: 'POST' },);- const handleMetricsReconciliation = withValidation(- EmptyRequestSchema,- async (_req, res) => {- try {- successResponse(res, 200, MetricsReconciliationSuccessSchema, getMetrics(), {- handler: 'metrics-reconciliation',- });- } catch (e) {- log.error(- { err: e, requestId: getRequestId(_req) },- '[metrics-reconciliation] handler failed',- );- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {- handler: 'metrics-reconciliation',- cause: e,- });- }- },- { handler: 'metrics-reconciliation', method: 'GET', skipBodyParse: true },- );-- const handleMetricsParseHealth = withValidation(- EmptyRequestSchema,- async (_req, res) => {- try {- successResponse(res, 200, MetricsParseHealthSuccessSchema, getParseHealth(), {- handler: 'metrics-parse-health',- });- } catch (e) {- log.error(- { err: e, requestId: getRequestId(_req) },- '[metrics-parse-health] handler failed',- );- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {- handler: 'metrics-parse-health',- cause: e,- });- }- },- { handler: 'metrics-parse-health', method: 'GET', skipBodyParse: true },- );-/*** GET /api/server-info*@@ -9263,222 +9130,6 @@ export function createApiExtension(successResponse(res, 200, PrincipalSuccessSchema, principal, { handler: 'principal' });}- async function handleMetricsAgentPresence(- req: IncomingMessage,- res: ServerResponse,- ): Promise<void> {- // Loopback + Host-header gate — matches /api/workspace. The presence map- // exposes per-agent identity (`displayName` — operator-configured AGENT- // label) and the workspace-relative path each agent is currently writing- // to (`currentDoc`). Those are local-editing-only signals; if a user- // deploys to `0.0.0.0` / reverse-proxies the port, cross-origin pages or- // LAN peers MUST NOT be able to read the map. Authorization runs before- // method dispatch so a bad Host never leaks "verb the endpoint expects"- // via 405 (same pattern + rationale as handleWorkspace — see its- // comment block for the ASVS / DNS-rebinding background).- if (!isLoopbackAddress(req.socket.remoteAddress)) {- errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {- handler: 'metrics-agent-presence',- });- return;- }- if (!isAllowedWorkspaceHostHeader(req.headers.host)) {- errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {- handler: 'metrics-agent-presence',- });- return;- }- if (req.method !== 'GET') {- errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {- handler: 'metrics-agent-presence',- extraHeaders: { Allow: 'GET' },- });- return;- }- try {- // Pre-filter stale entries using the same threshold the broadcaster- // uses for opportunistic eviction (runs inside setPresence). Eviction- // is write-triggered — if the last agent disconnects without the- // keepalive close firing (proxy ate the frame, `-9` kill) and no other- // agent writes after, the raw map keeps the zombie entry. Clients- // already filter with their own 5s TTL so this is invisible to the- // bar, but `/api/metrics/agent-presence` would otherwise lie to- // operators. Filtering here matches what a "live" read returns- // without paying for a sparse timer.- const rawPresence = agentPresenceBroadcaster?.getPresenceMap() ?? {};- const now = Date.now();- const presence: typeof rawPresence = {};- for (const [agentId, entry] of Object.entries(rawPresence)) {- if (now - entry.ts < BROADCASTER_EVICTION_MS) {- presence[agentId] = entry;- }- }- successResponse(- res,- 200,- MetricsAgentPresenceSuccessSchema,- { presence },- { handler: 'metrics-agent-presence' },- );- } catch (e) {- log.error(- { err: e, requestId: getRequestId(req) },- '[metrics-agent-presence] handler failed',- );- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {- handler: 'metrics-agent-presence',- cause: e,- });- }- }-- async function handleMetricsAgentEffects(- req: IncomingMessage,- res: ServerResponse,- ): Promise<void> {- // Diagnostic view of the per-doc `agent-effects` ring buffers, which- // otherwise live only inside live Y.Docs and are invisible to bundles.- // Loopback + Host-header gated with auth-before-method-dispatch ordering- // — same pattern + rationale as `handleMetricsAgentPresence` (per-agent- // identity plus per-doc write timing are local-editing-only signals).- if (!isLoopbackAddress(req.socket.remoteAddress)) {- errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {- handler: 'metrics-agent-effects',- });- return;- }- if (!isAllowedWorkspaceHostHeader(req.headers.host)) {- errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {- handler: 'metrics-agent-effects',- });- return;- }- if (req.method !== 'GET') {- errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {- handler: 'metrics-agent-effects',- extraHeaders: { Allow: 'GET' },- });- return;- }- // Tracks the doc being summarized so a throw in the per-doc reduction (e.g.- // a malformed `EffectValue` from an older schema) names its source in the- // catch log. Rides the `doc.name` key the bundle redactor hashes.- let failingDocName: string | undefined;- try {- // Currently-loaded docs only — iterating `hocuspocus.documents` never- // materializes an unloaded doc. The `share.has` probe avoids even- // creating the lazy Y.Map placeholder on docs no agent ever wrote to.- const effects: MetricsAgentEffectsSuccess['effects'] = [];- for (const [effectsDocName, document] of hocuspocus.documents) {- if (isSystemDoc(effectsDocName) || isConfigDoc(effectsDocName)) continue;- if (!document.share.has('agent-effects')) continue;- failingDocName = effectsDocName;- const effectsMap = document.getMap<EffectValue>('agent-effects');- if (effectsMap.size === 0) continue;- // Deltas reduce to character counts: the diagnostic signal is who- // wrote how much to which doc and when. Raw delta text is user- // content and stays in the live doc.- const entries = [...effectsMap.values()]- .map((effect) => {- let insertedChars = 0;- let deletedChars = 0;- for (const op of effect.delta) {- if (typeof op.insert === 'string') insertedChars += op.insert.length;- else if (op.insert !== undefined) insertedChars += 1;- if (typeof op.delete === 'number') deletedChars += op.delete;- }- return {- sessionId: effect.sessionId,- agentType: effect.agent_type,- ts: effect.timestamp,- insertedChars,- deletedChars,- };- })- .sort((a, b) => a.ts - b.ts);- // The doc name rides under the literal `doc.name` key — the key the- // diagnostics-bundle redactor hashes — so a staged copy of this- // response is anonymized by the existing pass.- effects.push({ 'doc.name': effectsDocName, entries });- }- effects.sort((a, b) => a['doc.name'].localeCompare(b['doc.name']));- successResponse(- res,- 200,- MetricsAgentEffectsSuccessSchema,- { effects },- { handler: 'metrics-agent-effects' },- );- } catch (e) {- log.error({ err: e, 'doc.name': failingDocName }, '[metrics-agent-effects] handler failed');- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {- handler: 'metrics-agent-effects',- cause: e,- });- }- }-- async function handleMetricsWatcherRecent(- req: IncomingMessage,- res: ServerResponse,- ): Promise<void> {- // Diagnostic view of the file-watcher's recent-decisions ring — the- // record of which disk events were dispatched, skipped as self-writes,- // or dropped (and why), which otherwise lives only in server memory.- // Loopback + Host-header gated with auth-before-method-dispatch ordering- // — same pattern + rationale as `handleMetricsAgentEffects` (which files- // changed on this machine, and when, is a local-editing-only signal).- if (!isLoopbackAddress(req.socket.remoteAddress)) {- errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {- handler: 'metrics-watcher-recent',- });- return;- }- if (!isAllowedWorkspaceHostHeader(req.headers.host)) {- errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {- handler: 'metrics-watcher-recent',- });- return;- }- if (req.method !== 'GET') {- errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {- handler: 'metrics-watcher-recent',- extraHeaders: { Allow: 'GET' },- });- return;- }- try {- // Ring paths are already normalized (last two segments) at record- // time. The wire carries them under the literal `doc.name` key — the- // key the diagnostics-bundle redactor hashes — so a staged copy of- // this response is anonymized by the existing pass.- const decisions: MetricsWatcherRecentSuccess['decisions'] =- getWatcherDecisionRingSnapshot().map((record) => ({- ts: record.ts,- decision: record.decision,- kind: record.kind,- 'doc.name': record.path,- pathRole: record.pathRole,- }));- successResponse(- res,- 200,- MetricsWatcherRecentSuccessSchema,- { decisions },- { handler: 'metrics-watcher-recent' },- );- } catch (e) {- log.error(- { err: e, requestId: getRequestId(req) },- '[metrics-watcher-recent] handler failed',- );- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {- handler: 'metrics-watcher-recent',- cause: e,- });- }- }-async function handleEmbedDetect(req: IncomingMessage, res: ServerResponse): Promise<void> {// Diagnostic endpoint for the Cursor / Codex / Claude Code embedded-viewer// detection spikes. Reads from the in-process ring buffer populated in@@ -22416,8 +22067,6 @@ export function createApiExtension('/api/documents': handleDocumentList,'/api/comment-counts': handleCommentCounts,'/api/link-preview': handleLinkPreview,- '/api/orphans': handleOrphans,- '/api/hubs': handleHubs,'/api/pages': handlePages,'/api/folder-config': handleFolderConfig,'/api/template': handleTemplate,@@ -22475,11 +22124,6 @@ export function createApiExtension('/api/save-version': handleSaveVersion,'/api/history': handleHistory,'/api/rollback': handleRollback,- '/api/metrics/reconciliation': handleMetricsReconciliation,- '/api/metrics/parse-health': handleMetricsParseHealth,- '/api/metrics/agent-presence': handleMetricsAgentPresence,- '/api/metrics/agent-effects': handleMetricsAgentEffects,- '/api/metrics/watcher-recent': handleMetricsWatcherRecent,'/api/__embed-detect': handleEmbedDetect,'/api/server-info': handleServerInfo,'/api/acp/catalog': handleAcpCatalog,@@ -22633,11 +22277,10 @@ export function createApiExtension(table: apiRouteTable,});- // The natively-routed link/graph read group (`http/link-graph-routes.ts`).- // Its paths live in the Hono app only — deliberately absent from `routes`- // above (a route lives in exactly one router). The handle rides the same- // shared pipeline with the group's own table, so gate behavior is identical- // to the legacy dispatch by construction.+ // The natively-routed route groups. Their paths live in the Hono app only —+ // deliberately absent from `routes` above (a route lives in exactly one+ // router). Each group rides the same shared pipeline with its own table, so+ // gate behavior is identical to the legacy dispatch by construction.const linkGraphRoutes = createLinkGraphRoutes({hocuspocus,derivedDocumentIndex,@@ -22650,18 +22293,39 @@ export function createApiExtension(resolveAlias,respondToDerivedIndexQueryFailure,});+ const metricsRoutes = createMetricsRoutes({+ hocuspocus,+ agentPresenceBroadcaster,+ isAllowedWorkspaceHostHeader,+ log,+ });+ const nativeGroups = [linkGraphRoutes, metricsRoutes];// "A route lives in exactly one router" — enforced at construction, not- // just documented; covers every future group aggregated into the native- // paths. Throw semantics pinned in `http/http-app.test.ts`.- assertSingleRouterOwnership(linkGraphRoutes.paths, routes);- const nativeApi: NativeApiHandle = {- paths: linkGraphRoutes.paths,- dispatch: createApiRequestPipeline({+ // just documented; covers every group aggregated into the native paths.+ // Throw semantics pinned in `http/http-app.test.ts`.+ const nativePaths = nativeGroups.flatMap((group) => [...group.paths]);+ assertSingleRouterOwnership(nativePaths, routes);+ // Multi-group composition: paths concatenate; dispatch chains the per-group+ // pipelines in order. Safe because the pipeline declines (returns false,+ // zero side effects) BEFORE any request observation when a group's table+ // does not resolve the URL — only the owning group's pipeline runs the+ // admission gates and dispatch span.+ const groupDispatches = nativeGroups.map((group) =>+ createApiRequestPipeline({log,remotePublicHost,ephemeral,- table: linkGraphRoutes.table,+ table: group.table,}),+ );+ const nativeApi: NativeApiHandle = {+ paths: nativePaths,+ dispatch: async (req, res) => {+ for (const dispatch of groupDispatches) {+ if (await dispatch(req, res)) return true;+ }+ return false;+ },};return {diff --git a/packages/server/src/api-link-graph-composition.test.ts b/packages/server/src/api-link-graph-composition.test.tsindex d4b3964e9..743d9c595 100644--- a/packages/server/src/api-link-graph-composition.test.ts+++ b/packages/server/src/api-link-graph-composition.test.ts@@ -51,6 +51,8 @@ describe('link/graph group over the composed listener — served natively', () ='/api/forward-links?docName=alpha','/api/link-graph','/api/dead-links',+ '/api/orphans',+ '/api/hubs','/api/tags','/api/suggest-links?docName=alpha',]) {diff --git a/packages/server/src/api-metrics-composition.test.ts b/packages/server/src/api-metrics-composition.test.tsnew file mode 100644index 000000000..3fe9228fa--- /dev/null+++ b/packages/server/src/api-metrics-composition.test.ts@@ -0,0 +1,164 @@+import { mkdtempSync, writeFileSync } from 'node:fs';+import { mkdtemp, rm } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { resolve } from 'node:path';+import { afterAll, beforeAll, describe, expect, test } from 'vitest';+import type { BootedServer } from './boot.ts';+import { bootCompositionRig, parseProblem, rawRequest } from './composition-rig.test-helper.ts';++/**+ * Characterization: the natively-routed metrics read group over a REAL socket+ * through the composed `bootServer` stack — the SECOND native group, so a 200+ * here also proves the multi-group `nativeApi` composition (concatenated+ * paths, chained per-group pipeline dispatches): the link/graph group's table+ * declines these URLs and the chain falls through to the metrics pipeline.+ * Mirrors `api-link-graph-composition.test.ts` for the group-1 pins.+ *+ * The three gated diagnostics (agent-presence, agent-effects, watcher-recent)+ * enforce loopback + Host INLINE, before method dispatch — the pins below+ * hold the gate-before-405 ordering (a bad Host must never learn the verb).+ */++let tmpRoot: string;+let server: BootedServer;+let ephemeral: BootedServer;++beforeAll(async () => {+ tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-metrics-native-'));+ const contentDir = mkdtempSync(resolve(tmpRoot, 'content-'));+ writeFileSync(resolve(contentDir, 'alpha.md'), '# Alpha\n\nBody.\n', 'utf-8');+ server = await bootCompositionRig(contentDir);+ await server.ready;++ const ephemeralDir = mkdtempSync(resolve(tmpRoot, 'ephemeral-'));+ writeFileSync(resolve(ephemeralDir, 'note.md'), '# note\n', 'utf-8');+ ephemeral = await bootCompositionRig(ephemeralDir, {+ ephemeral: true,+ singleDocRelPath: 'note.md',+ });+ await ephemeral.ready;+}, 60_000);++afterAll(async () => {+ await Promise.allSettled([server?.destroy(), ephemeral?.destroy()]);+ await rm(tmpRoot, { recursive: true, force: true });+});++describe('metrics group over the composed listener — served natively', () => {+ test('every route in the group answers (absent from the legacy registry)', async () => {+ for (const path of [+ '/api/metrics/reconciliation',+ '/api/metrics/parse-health',+ '/api/metrics/agent-presence',+ '/api/metrics/agent-effects',+ '/api/metrics/watcher-recent',+ ]) {+ const res = await fetch(`http://127.0.0.1:${server.port}${path}`);+ expect(res.status, path).toBe(200);+ expect(res.headers.get('content-type'), path).toBe('application/json');+ expect(res.headers.get('x-request-id'), path).not.toBeNull();+ }+ });++ test('both chained groups answer on one server (multi-group dispatch)', async () => {+ // Group 1 (link/graph) resolves first in the chain; group 2 (metrics)+ // only answers after group 1 declines. One server, both arms live.+ const linkGraph = await fetch(`http://127.0.0.1:${server.port}/api/backlinks?docName=alpha`);+ expect(linkGraph.status).toBe(200);+ const metrics = await fetch(`http://127.0.0.1:${server.port}/api/metrics/reconciliation`);+ expect(metrics.status).toBe(200);+ });++ test('method gate holds on an ungated route (POST answers 405 + Allow: GET)', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/metrics/reconciliation`, {+ method: 'POST',+ });+ expect(res.status).toBe(405);+ expect(res.headers.get('allow')).toBe('GET');+ });++ test('gated diagnostics refuse a rebound Host with 403 (inline gate survives the lift)', async () => {+ for (const path of [+ '/api/metrics/agent-presence',+ '/api/metrics/agent-effects',+ '/api/metrics/watcher-recent',+ ]) {+ const res = await rawRequest(server.port, path, {+ headers: { Host: 'evil.example' },+ });+ expect(res.status, path).toBe(403);+ expect(parseProblem(res.body).type, path).toBe('urn:ok:error:host-not-allowed');+ }+ });++ test('gate-before-405: a bad Host on a wrong verb gets 403, never the verb hint', async () => {+ const res = await rawRequest(server.port, '/api/metrics/agent-presence', {+ method: 'POST',+ headers: { Host: 'evil.example' },+ });+ expect(res.status).toBe(403);+ expect(res.headers.allow).toBeUndefined();+ });++ test('gated diagnostics answer the method gate once the Host passes (POST → 405 + Allow: GET)', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/metrics/agent-presence`, {+ method: 'POST',+ });+ expect(res.status).toBe(405);+ expect(res.headers.get('allow')).toBe('GET');+ });++ test('foreign Origin is refused before dispatch on a ported route', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/metrics/reconciliation`, {+ headers: { Origin: 'https://evil.example' },+ });+ expect(res.status).toBe(403);+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-origin');+ });++ test('allowed browser Origin gets CORS reflection on a ported route', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/metrics/reconciliation`, {+ headers: { Origin: 'http://localhost:5173' },+ });+ expect(res.status).toBe(200);+ expect(res.headers.get('access-control-allow-origin')).toBe('http://localhost:5173');+ expect(res.headers.get('vary')).toContain('Origin');+ });++ test('OPTIONS preflight answers 204 on a ported route', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/metrics/reconciliation`, {+ method: 'OPTIONS',+ headers: { Origin: 'http://localhost:5173' },+ });+ expect(res.status).toBe(204);+ expect(res.headers.get('access-control-allow-methods')).toBe('GET, POST, PUT, DELETE, OPTIONS');+ });++ test('any forwarding header trips the proxied-request refusal on a ported route', async () => {+ const res = await rawRequest(server.port, '/api/metrics/reconciliation', {+ headers: { 'X-Forwarded-For': '203.0.113.7' },+ });+ expect(res.status).toBe(403);+ const body = parseProblem(res.body);+ expect(body.type).toBe('urn:ok:error:host-not-allowed');+ expect(body.detail ?? body.title).toContain('Proxied request refused');+ });++ test('read posture parity: an UNGATED read ANSWERS under a rebound Host in normal mode', async () => {+ // Same deliberate pin as the link-graph suite: reads without an inline+ // gate are Origin-gated but NOT Host/loopback-gated. When the hosted-auth+ // work flips that posture, this assertion flips in the same PR.+ const res = await rawRequest(server.port, '/api/metrics/reconciliation', {+ headers: { Host: 'evil.example' },+ });+ expect(res.status).toBe(200);+ });++ test('ephemeral mode Host-gates the ported reads too', async () => {+ const res = await rawRequest(ephemeral.port, '/api/metrics/reconciliation', {+ headers: { Host: 'evil.example' },+ });+ expect(res.status).toBe(403);+ expect(parseProblem(res.body).type).toBe('urn:ok:error:host-not-allowed');+ });+});diff --git a/packages/server/src/http/api-pipeline.test.ts b/packages/server/src/http/api-pipeline.test.tsindex 9fd2a28f8..580294388 100644--- a/packages/server/src/http/api-pipeline.test.ts+++ b/packages/server/src/http/api-pipeline.test.ts@@ -130,6 +130,28 @@ describe('natively-mounted /api routes run the shared admission pipeline', () =>const res = await fetch(`${rig.baseUrl}/api/native-declined`);expect(res.status).toBe(299);expect(rig.legacyCalls).toEqual(['/api/native-declined']);+ // Decline is side-effect-FREE (pipeline docblock step 0): the declining+ // pipeline must not have touched the response — no request-id echo,+ // no CORS headers. The multi-group chain depends on this: every group+ // before the owning one declines the same request.+ expect(res.headers.get('x-request-id')).toBeNull();+ expect(res.headers.get('access-control-allow-methods')).toBeNull();+ } finally {+ await rig.close();+ }+ });++ test('a declined path skips the gates too — foreign Origin falls through, not 403', async () => {+ // The decline precedes the Origin gate: a chained group must never+ // refuse a request it does not own (the owning table — here the legacy+ // dispatch — applies its own gates).+ const rig = await bootNativeRig();+ try {+ const res = await fetch(`${rig.baseUrl}/api/native-declined`, {+ headers: { Origin: 'https://evil.example' },+ });+ expect(res.status).toBe(299);+ expect(rig.legacyCalls).toEqual(['/api/native-declined']);} finally {await rig.close();}diff --git a/packages/server/src/http/api-pipeline.ts b/packages/server/src/http/api-pipeline.tsindex 84d67b8fc..efe01b9ac 100644--- a/packages/server/src/http/api-pipeline.ts+++ b/packages/server/src/http/api-pipeline.ts@@ -13,6 +13,12 @@** The gate ORDER is load-bearing and mirrors the historical hook exactly:*+ * 0. table resolve — a URL the table declines returns `false` HERE, before+ * any request observation. Load-bearing for the multi-group native+ * chain (`api-extension.ts` runs one pipeline per group in turn): only+ * the owning group's pipeline may observe the request, so a probe or+ * request-id write hoisted above the resolve would fire once per+ * declining group for every request a later group owns.* 1. embed-probe observation (ring buffer drained by `/api/__embed-detect`)* 2. request-id resolve + echo + `api.access` log wiring — BEFORE the gates* so even gate-rejected responses carry the `x-request-id` echo@@ -136,6 +142,9 @@ export function createApiRequestPipeline(opts: ApiPipelineOptions): ApiRequestPiif (!url) return false;const resolution = table.resolve(url);+ // Decline with ZERO side effects — see step 0 in the module docblock;+ // moving any observation above this return double-records chained-group+ // requests.if (!resolution) return false;// Per-request client-context observation for embed-detection spikes.diff --git a/packages/server/src/http/http-app.test.ts b/packages/server/src/http/http-app.test.tsindex 739c4e95d..3d7e39b0b 100644--- a/packages/server/src/http/http-app.test.ts+++ b/packages/server/src/http/http-app.test.ts@@ -121,4 +121,28 @@ describe('assertSingleRouterOwnership', () => {}),).not.toThrow();});++ // The native list is the concatenation of every group's paths — the same+ // one-router rule applies WITHIN it, or two groups could silently answer+ // from whichever sits earlier in the dispatch chain.+ test('throws when two native groups claim the same path', () => {+ expect(() =>+ assertSingleRouterOwnership(['/api/backlinks', '/api/metrics/x', '/api/backlinks'], {}),+ ).toThrow('route(s) claimed by more than one native route group: /api/backlinks');+ });++ test("throws when one native group's wildcard covers another native path", () => {+ expect(() => assertSingleRouterOwnership(['/api/tags/*', '/api/tags/special'], {})).toThrow(+ '/api/tags/special (under a native wildcard)',+ );+ });++ test('passes for disjoint native groups concatenated, wildcard base included', () => {+ expect(() =>+ assertSingleRouterOwnership(+ ['/api/backlinks', '/api/tags/*', '/api/metrics/reconciliation', '/api/tags'],+ {},+ ),+ ).not.toThrow();+ });});diff --git a/packages/server/src/http/http-app.ts b/packages/server/src/http/http-app.tsindex da294afff..d73b6bba3 100644--- a/packages/server/src/http/http-app.ts+++ b/packages/server/src/http/http-app.ts@@ -107,6 +107,12 @@ export function admitRequestSurface(* legacy record key that falls under a native wildcard's namespace (the* wildcard claims everything below its prefix, so such a key is just as* shadowed as an exact duplicate).+ *+ * `nativePaths` is the CONCATENATION of every native group's paths, so the+ * same rule applies within the native set: two groups claiming one path (or+ * one group's wildcard covering another group's path) would silently answer+ * from whichever group sits earlier in the dispatch chain. Those collisions+ * throw here too, with their own message.*/export function assertSingleRouterOwnership(nativePaths: readonly string[],@@ -123,6 +129,24 @@ export function assertSingleRouterOwnership(`route(s) present in both the legacy dispatch record and a native route group: ${conflicts.join(', ')}`,);}++ const seen = new Set<string>();+ const nativeDuplicates: string[] = [];+ for (const p of nativePaths) {+ if (seen.has(p)) nativeDuplicates.push(p);+ seen.add(p);+ }+ // A wildcard's own entry is `${prefix}*` — exclude it; everything else+ // under the prefix (exact paths AND narrower wildcards) is shadowed.+ const nativeShadowed = nativePaths+ .filter((p) => wildcardPrefixes.some((prefix) => p !== `${prefix}*` && p.startsWith(prefix)))+ .map((p) => `${p} (under a native wildcard)`);+ const nativeConflicts = [...new Set([...nativeDuplicates, ...nativeShadowed])];+ if (nativeConflicts.length > 0) {+ throw new Error(+ `route(s) claimed by more than one native route group: ${nativeConflicts.join(', ')}`,+ );+ }}export interface CreateHttpAppOptions {diff --git a/packages/server/src/http/link-graph-routes.ts b/packages/server/src/http/link-graph-routes.tsindex ea131be65..b1d4e7c9b 100644--- a/packages/server/src/http/link-graph-routes.ts+++ b/packages/server/src/http/link-graph-routes.ts@@ -1,10 +1,11 @@/*** The link/graph read family — `backlinks`, `backlink-counts`,- * `forward-links`, `link-graph`, `dead-links`, `tags-list`, `tags-for-name`,- * `suggest-links` — lifted out of `api-extension.ts` as the first natively-- * routed Wave 2 group. Same lift shape as `skills-sh-handlers.ts`: what the- * handlers closed over in the extension arrives as- * {@link LinkGraphRouteDeps}, and the handler bodies are unchanged.+ * `forward-links`, `link-graph`, `dead-links`, `orphans`, `hubs`,+ * `tags-list`, `tags-for-name`, `suggest-links` — lifted out of+ * `api-extension.ts` as the first natively-routed Wave 2 group. Same lift+ * shape as `skills-sh-handlers.ts`: what the handlers closed over in the+ * extension arrives as {@link LinkGraphRouteDeps}, and the handler bodies+ * are unchanged.** Unlike the skills.sh handlers, this group does NOT return to the legacy* route table: `createLinkGraphRoutes` returns an {@link ApiRouteTable} +@@ -21,13 +22,19 @@ import {DeadLinksSuccessSchema,EmptyRequestSchema,ForwardLinksSuccessSchema,+ HubsSuccessSchema,LinkGraphSuccessSchema,+ OrphansSuccessSchema,SuggestLinksSuccessSchema,TagsForNameSuccessSchema,TagsListSuccessSchema,} from '@inkeep/open-knowledge-core';import { isConfigDoc, isSystemDoc } from '../cc1-broadcast.ts';-import type { DerivedDocumentIndexApiPort, DerivedGraphNode } from '../derived-document-index.ts';+import {+ type DerivedDocumentIndexApiPort,+ type DerivedGraphNode,+ isDerivedOrphanMode,+} from '../derived-document-index.ts';import type { FileIndexEntry } from '../file-watcher.ts';import type { FrontmatterMetadata } from '../page-identity.ts';import { SuggestLinksTargetNotFoundError, suggestLinks } from '../suggest-links.ts';@@ -400,6 +407,85 @@ export function createLinkGraphRoutes(deps: LinkGraphRouteDeps): LinkGraphRoutes{ handler: 'dead-links', method: 'GET', skipBodyParse: true },);+ const handleOrphans = withValidation(+ EmptyRequestSchema,+ async (req, res) => {+ if (!derivedDocumentIndex) {+ errorResponse(+ res,+ 503,+ 'urn:ok:error:backlink-index-not-configured',+ 'Backlink index is not configured.',+ { handler: 'orphans' },+ );+ return;+ }+ try {+ const url = new URL(req.url ?? '', 'http://localhost');+ const mode = url.searchParams.get('mode') ?? 'both';+ if (!isDerivedOrphanMode(mode)) {+ errorResponse(+ res,+ 400,+ 'urn:ok:error:invalid-request',+ 'Invalid orphan mode. Allowed values: incoming, outgoing, both.',+ { handler: 'orphans' },+ );+ return;+ }++ const orphans = (+ await derivedDocumentIndex.getOrphans([...getFileIndex().keys()], mode)+ ).map((docName) => ({+ docName,+ title: readPageTitleForDocName(docName),+ }));+ successResponse(res, 200, OrphansSuccessSchema, { orphans }, { handler: 'orphans' });+ } catch (e) {+ respondToDerivedIndexQueryFailure(res, e, {+ handler: 'orphans',+ failureTitle: 'Failed to read orphan pages.',+ });+ }+ },+ { handler: 'orphans', method: 'GET', skipBodyParse: true },+ );++ const handleHubs = withValidation(+ EmptyRequestSchema,+ async (req, res) => {+ if (!derivedDocumentIndex) {+ errorResponse(+ res,+ 503,+ 'urn:ok:error:backlink-index-not-configured',+ 'Backlink index is not configured.',+ { handler: 'hubs' },+ );+ return;+ }+ try {+ const url = new URL(req.url ?? '', 'http://localhost');+ const rawLimit = url.searchParams.get('limit');+ const parsed = rawLimit ? Number.parseInt(rawLimit, 10) : 20;+ const limit = Number.isFinite(parsed) && parsed > 0 ? parsed : 20;+ const admitted = await collectAdmittedDocNames();+ const hubs = (await derivedDocumentIndex.getHubs(limit)).map((hub) => ({+ docName: hub.docName,+ title: readPageTitleForLinkedDocName(hub.docName, admitted),+ count: hub.count,+ }));+ successResponse(res, 200, HubsSuccessSchema, { hubs }, { handler: 'hubs' });+ } catch (e) {+ respondToDerivedIndexQueryFailure(res, e, {+ handler: 'hubs',+ failureTitle: 'Failed to read hub pages.',+ });+ }+ },+ { handler: 'hubs', method: 'GET', skipBodyParse: true },+ );+const handleSuggestLinks = withValidation(EmptyRequestSchema,async (req, res) => {@@ -548,6 +634,8 @@ export function createLinkGraphRoutes(deps: LinkGraphRouteDeps): LinkGraphRoutes'/api/forward-links': handleForwardLinks,'/api/link-graph': handleLinkGraph,'/api/dead-links': handleDeadLinks,+ '/api/orphans': handleOrphans,+ '/api/hubs': handleHubs,'/api/tags': handleTagsList,'/api/suggest-links': handleSuggestLinks,};diff --git a/packages/server/src/http/metrics-routes.ts b/packages/server/src/http/metrics-routes.tsnew file mode 100644index 000000000..6573e97a8--- /dev/null+++ b/packages/server/src/http/metrics-routes.ts@@ -0,0 +1,356 @@+/**+ * The metrics read family — `metrics-reconciliation`, `metrics-parse-health`,+ * `metrics-agent-presence`, `metrics-agent-effects`, `metrics-watcher-recent`+ * — lifted out of `api-extension.ts` as the second natively-routed Wave 2+ * group. Same lift shape as `link-graph-routes.ts`: what the handlers closed+ * over in the extension arrives as {@link MetricsRouteDeps}, and the handler+ * bodies are unchanged.+ *+ * Being the SECOND group is the point: the extension aggregates every group+ * into one `nativeApi` handle (paths concatenated, per-group pipeline+ * dispatches chained), so this file proves the multi-group composition the+ * first group deferred.+ *+ * The agent-presence / agent-effects / watcher-recent handlers carry their+ * loopback + Host gates INLINE, ahead of method dispatch (OWASP ASVS V4.1.1 —+ * a bad Host must never learn the verb via 405). That contract is different+ * from the pipeline's `isMutating` mechanism, which gates before dispatch but+ * ALSO before the per-route 404/405 machinery for mutating writes — so these+ * gates deliberately stay in the handler bodies and `isMutating` stays false.+ * The Host predicate arrives as a dep because the extension widens it in+ * remote mode (the tunnel's public Host is as legitimate as loopback).+ */++import type { IncomingMessage, ServerResponse } from 'node:http';+import type { Hocuspocus } from '@hocuspocus/server';+import {+ EmptyRequestSchema,+ getParseHealth,+ type MetricsAgentEffectsSuccess,+ MetricsAgentEffectsSuccessSchema,+ MetricsAgentPresenceSuccessSchema,+ MetricsParseHealthSuccessSchema,+ MetricsReconciliationSuccessSchema,+ type MetricsWatcherRecentSuccess,+ MetricsWatcherRecentSuccessSchema,+} from '@inkeep/open-knowledge-core';+import type { EffectValue } from '../activity-log.ts';+import { type AgentPresenceBroadcaster, BROADCASTER_EVICTION_MS } from '../agent-presence.ts';+import { isConfigDoc, isSystemDoc } from '../cc1-broadcast.ts';+import { getWatcherDecisionRingSnapshot } from '../file-watcher.ts';+import type { PinoLogger } from '../logger.ts';+import { isLoopbackAddress } from '../loopback.ts';+import { getMetrics } from '../metrics.ts';+import type { ApiRouteTable } from './api-pipeline.ts';+import { errorResponse } from './error-response.ts';+import { getRequestId } from './request-id.ts';+import { withValidation } from './request-validation.ts';+import { successResponse } from './success-response.ts';++export interface MetricsRouteDeps {+ hocuspocus: Hocuspocus;+ agentPresenceBroadcaster: AgentPresenceBroadcaster | undefined;+ /**+ * The extension's remote-widened workspace-Host predicate — in remote mode+ * the tunnel's public Host passes alongside the loopback names.+ */+ isAllowedWorkspaceHostHeader: (host: string | undefined) => boolean;+ log: PinoLogger;+}++export interface MetricsRoutes {+ /** Hono patterns for the native mount (`NativeApiHandle.paths`). */+ paths: readonly string[];+ /** The group's view for the shared /api/* admission pipeline. */+ table: ApiRouteTable;+}++export function createMetricsRoutes(deps: MetricsRouteDeps): MetricsRoutes {+ const { hocuspocus, agentPresenceBroadcaster, isAllowedWorkspaceHostHeader, log } = deps;++ const handleMetricsReconciliation = withValidation(+ EmptyRequestSchema,+ async (_req, res) => {+ try {+ successResponse(res, 200, MetricsReconciliationSuccessSchema, getMetrics(), {+ handler: 'metrics-reconciliation',+ });+ } catch (e) {+ log.error(+ { err: e, requestId: getRequestId(_req) },+ '[metrics-reconciliation] handler failed',+ );+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {+ handler: 'metrics-reconciliation',+ cause: e,+ });+ }+ },+ { handler: 'metrics-reconciliation', method: 'GET', skipBodyParse: true },+ );++ const handleMetricsParseHealth = withValidation(+ EmptyRequestSchema,+ async (_req, res) => {+ try {+ successResponse(res, 200, MetricsParseHealthSuccessSchema, getParseHealth(), {+ handler: 'metrics-parse-health',+ });+ } catch (e) {+ log.error(+ { err: e, requestId: getRequestId(_req) },+ '[metrics-parse-health] handler failed',+ );+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {+ handler: 'metrics-parse-health',+ cause: e,+ });+ }+ },+ { handler: 'metrics-parse-health', method: 'GET', skipBodyParse: true },+ );++ async function handleMetricsAgentPresence(+ req: IncomingMessage,+ res: ServerResponse,+ ): Promise<void> {+ // Loopback + Host-header gate — matches /api/workspace. The presence map+ // exposes per-agent identity (`displayName` — operator-configured AGENT+ // label) and the workspace-relative path each agent is currently writing+ // to (`currentDoc`). Those are local-editing-only signals; if a user+ // deploys to `0.0.0.0` / reverse-proxies the port, cross-origin pages or+ // LAN peers MUST NOT be able to read the map. Authorization runs before+ // method dispatch so a bad Host never leaks "verb the endpoint expects"+ // via 405 (same pattern + rationale as handleWorkspace — see its+ // comment block for the ASVS / DNS-rebinding background).+ if (!isLoopbackAddress(req.socket.remoteAddress)) {+ errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {+ handler: 'metrics-agent-presence',+ });+ return;+ }+ if (!isAllowedWorkspaceHostHeader(req.headers.host)) {+ errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {+ handler: 'metrics-agent-presence',+ });+ return;+ }+ if (req.method !== 'GET') {+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {+ handler: 'metrics-agent-presence',+ extraHeaders: { Allow: 'GET' },+ });+ return;+ }+ try {+ // Pre-filter stale entries using the same threshold the broadcaster+ // uses for opportunistic eviction (runs inside setPresence). Eviction+ // is write-triggered — if the last agent disconnects without the+ // keepalive close firing (proxy ate the frame, `-9` kill) and no other+ // agent writes after, the raw map keeps the zombie entry. Clients+ // already filter with their own 5s TTL so this is invisible to the+ // bar, but `/api/metrics/agent-presence` would otherwise lie to+ // operators. Filtering here matches what a "live" read returns+ // without paying for a sparse timer.+ const rawPresence = agentPresenceBroadcaster?.getPresenceMap() ?? {};+ const now = Date.now();+ const presence: typeof rawPresence = {};+ for (const [agentId, entry] of Object.entries(rawPresence)) {+ if (now - entry.ts < BROADCASTER_EVICTION_MS) {+ presence[agentId] = entry;+ }+ }+ successResponse(+ res,+ 200,+ MetricsAgentPresenceSuccessSchema,+ { presence },+ { handler: 'metrics-agent-presence' },+ );+ } catch (e) {+ log.error(+ { err: e, requestId: getRequestId(req) },+ '[metrics-agent-presence] handler failed',+ );+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {+ handler: 'metrics-agent-presence',+ cause: e,+ });+ }+ }++ async function handleMetricsAgentEffects(+ req: IncomingMessage,+ res: ServerResponse,+ ): Promise<void> {+ // Diagnostic view of the per-doc `agent-effects` ring buffers, which+ // otherwise live only inside live Y.Docs and are invisible to bundles.+ // Loopback + Host-header gated with auth-before-method-dispatch ordering+ // — same pattern + rationale as `handleMetricsAgentPresence` (per-agent+ // identity plus per-doc write timing are local-editing-only signals).+ if (!isLoopbackAddress(req.socket.remoteAddress)) {+ errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {+ handler: 'metrics-agent-effects',+ });+ return;+ }+ if (!isAllowedWorkspaceHostHeader(req.headers.host)) {+ errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {+ handler: 'metrics-agent-effects',+ });+ return;+ }+ if (req.method !== 'GET') {+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {+ handler: 'metrics-agent-effects',+ extraHeaders: { Allow: 'GET' },+ });+ return;+ }+ // Tracks the doc being summarized so a throw in the per-doc reduction (e.g.+ // a malformed `EffectValue` from an older schema) names its source in the+ // catch log. Rides the `doc.name` key the bundle redactor hashes.+ let failingDocName: string | undefined;+ try {+ // Currently-loaded docs only — iterating `hocuspocus.documents` never+ // materializes an unloaded doc. The `share.has` probe avoids even+ // creating the lazy Y.Map placeholder on docs no agent ever wrote to.+ const effects: MetricsAgentEffectsSuccess['effects'] = [];+ for (const [effectsDocName, document] of hocuspocus.documents) {+ if (isSystemDoc(effectsDocName) || isConfigDoc(effectsDocName)) continue;+ if (!document.share.has('agent-effects')) continue;+ failingDocName = effectsDocName;+ const effectsMap = document.getMap<EffectValue>('agent-effects');+ if (effectsMap.size === 0) continue;+ // Deltas reduce to character counts: the diagnostic signal is who+ // wrote how much to which doc and when. Raw delta text is user+ // content and stays in the live doc.+ const entries = [...effectsMap.values()]+ .map((effect) => {+ let insertedChars = 0;+ let deletedChars = 0;+ for (const op of effect.delta) {+ if (typeof op.insert === 'string') insertedChars += op.insert.length;+ else if (op.insert !== undefined) insertedChars += 1;+ if (typeof op.delete === 'number') deletedChars += op.delete;+ }+ return {+ sessionId: effect.sessionId,+ agentType: effect.agent_type,+ ts: effect.timestamp,+ insertedChars,+ deletedChars,+ };+ })+ .sort((a, b) => a.ts - b.ts);+ // The doc name rides under the literal `doc.name` key — the key the+ // diagnostics-bundle redactor hashes — so a staged copy of this+ // response is anonymized by the existing pass.+ effects.push({ 'doc.name': effectsDocName, entries });+ }+ effects.sort((a, b) => a['doc.name'].localeCompare(b['doc.name']));+ successResponse(+ res,+ 200,+ MetricsAgentEffectsSuccessSchema,+ { effects },+ { handler: 'metrics-agent-effects' },+ );+ } catch (e) {+ log.error({ err: e, 'doc.name': failingDocName }, '[metrics-agent-effects] handler failed');+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {+ handler: 'metrics-agent-effects',+ cause: e,+ });+ }+ }++ async function handleMetricsWatcherRecent(+ req: IncomingMessage,+ res: ServerResponse,+ ): Promise<void> {+ // Diagnostic view of the file-watcher's recent-decisions ring — the+ // record of which disk events were dispatched, skipped as self-writes,+ // or dropped (and why), which otherwise lives only in server memory.+ // Loopback + Host-header gated with auth-before-method-dispatch ordering+ // — same pattern + rationale as `handleMetricsAgentEffects` (which files+ // changed on this machine, and when, is a local-editing-only signal).+ if (!isLoopbackAddress(req.socket.remoteAddress)) {+ errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {+ handler: 'metrics-watcher-recent',+ });+ return;+ }+ if (!isAllowedWorkspaceHostHeader(req.headers.host)) {+ errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {+ handler: 'metrics-watcher-recent',+ });+ return;+ }+ if (req.method !== 'GET') {+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {+ handler: 'metrics-watcher-recent',+ extraHeaders: { Allow: 'GET' },+ });+ return;+ }+ try {+ // Ring paths are already normalized (last two segments) at record+ // time. The wire carries them under the literal `doc.name` key — the+ // key the diagnostics-bundle redactor hashes — so a staged copy of+ // this response is anonymized by the existing pass.+ const decisions: MetricsWatcherRecentSuccess['decisions'] =+ getWatcherDecisionRingSnapshot().map((record) => ({+ ts: record.ts,+ decision: record.decision,+ kind: record.kind,+ 'doc.name': record.path,+ pathRole: record.pathRole,+ }));+ successResponse(+ res,+ 200,+ MetricsWatcherRecentSuccessSchema,+ { decisions },+ { handler: 'metrics-watcher-recent' },+ );+ } catch (e) {+ log.error(+ { err: e, requestId: getRequestId(req) },+ '[metrics-watcher-recent] handler failed',+ );+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {+ handler: 'metrics-watcher-recent',+ cause: e,+ });+ }+ }++ const routes: Record<string, (req: IncomingMessage, res: ServerResponse) => Promise<void>> = {+ '/api/metrics/reconciliation': handleMetricsReconciliation,+ '/api/metrics/parse-health': handleMetricsParseHealth,+ '/api/metrics/agent-presence': handleMetricsAgentPresence,+ '/api/metrics/agent-effects': handleMetricsAgentEffects,+ '/api/metrics/watcher-recent': handleMetricsWatcherRecent,+ };++ const table: ApiRouteTable = {+ resolve(url) {+ const handler = routes[url];+ if (handler) {+ return { template: url, dispatch: (req, res) => handler(req, res) };+ }+ return null;+ },+ // None of these routes rode the legacy MUTATING_ROUTES gate. The three+ // gated diagnostics enforce loopback + Host INLINE, before method+ // dispatch (gate-before-405) — a different contract from the pipeline's+ // mutating gate, so they deliberately do not migrate onto it.+ isMutating: () => false,+ };++ return {+ paths: Object.keys(routes),+ table,+ };+}