Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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): ApiRequestPi
if (!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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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,
+ };
+}