Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(open-knowledge): bundle checkpoint refs, agent effects, drop counts (#2735)

Andrew Mikofalvya8072a2fbaeb
diff --git a/.changeset/bundle-checkpoint-effects-drop-counts.md b/.changeset/bundle-checkpoint-effects-drop-counts.md
new file mode 100644
index 000000000..cb9ee7930
--- /dev/null
+++ b/.changeset/bundle-checkpoint-effects-drop-counts.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Diagnostics bundles now capture more of what matters for content-loss triage. The full bundle stages the shadow repo's recovery-checkpoint refs (`state/checkpoint-refs.txt` — ref name, date, and content-free subject per checkpoint) and a new `state/agent-effects.json` snapshot of the per-document agent activity ring buffers, served by a new loopback-only `GET /api/metrics/agent-effects` endpoint that summarizes agent writes as character counts (never raw text). Doc names in the new artifacts are anonymized by the existing `--redact` pass, which now also hashes the agent-presence bundle's `currentDoc` path so a redacted `state/agent-presence.json` no longer leaks the document a person was editing. The web client's log forwarder also stops losing entries silently: drops from buffer overflow or failed uploads are counted and recorded as an explicit `droppedSinceLastFlush` gap marker in the server log on the next delivered batch, and a failed recovery-checkpoint write now also emits a structured server-log line with doc and branch context.
diff --git a/knip.config.ts b/knip.config.ts
index 9633755a0..16d637b4b 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -119,9 +119,7 @@ export default {
'packages/server': {
entry: ['src/**/*.test.ts'],
project: 'src/**',
- ignoreDependencies: [
- '@types/shell-quote',
- ],
+ ignoreDependencies: ['@types/shell-quote'],
},
'packages/cli': {
entry: ['src/**/*.test.ts', 'scripts/*.ts', 'tests/**/*.ts'],
diff --git a/packages/app/src/lib/install-client-log-forwarder.test.ts b/packages/app/src/lib/install-client-log-forwarder.test.ts
index a39695e58..d43d85e55 100644
--- a/packages/app/src/lib/install-client-log-forwarder.test.ts
+++ b/packages/app/src/lib/install-client-log-forwarder.test.ts
@@ -228,6 +228,109 @@ describe('installClientLogForwarder', () => {
expect((entry?.message as string).length).toBeLessThanOrEqual(8192);
});
+ test('a failed POST is counted and carried as droppedSinceLastFlush on the next batch', async () => {
+ let failNext = true;
+ const fetchSpy = mock((_url: string, _init?: RequestInit) =>
+ failNext
+ ? Promise.reject(new Error('network down'))
+ : Promise.resolve(new Response(null, { status: 200 })),
+ );
+ const { con } = install(fetchSpy);
+
+ con.warn('lost-1');
+ con.warn('lost-2');
+ handle?.flushNow();
+ await new Promise((r) => setTimeout(r, 0)); // let the rejection handler run
+
+ failNext = false;
+ con.warn('delivered');
+ handle?.flushNow();
+ expect(fetchSpy).toHaveBeenCalledTimes(2);
+ const body = bodyOf(fetchSpy) as { entries: unknown[]; droppedSinceLastFlush?: number };
+ expect(body.entries).toHaveLength(1);
+ expect(body.droppedSinceLastFlush).toBe(2);
+ });
+
+ test('a non-2xx response counts the batch as dropped', async () => {
+ let reject = true;
+ const fetchSpy = mock((_url: string, _init?: RequestInit) =>
+ Promise.resolve(new Response(null, { status: reject ? 500 : 200 })),
+ );
+ const { con } = install(fetchSpy);
+
+ con.warn('rejected');
+ handle?.flushNow();
+ await new Promise((r) => setTimeout(r, 0));
+
+ reject = false;
+ con.warn('delivered');
+ handle?.flushNow();
+ const body = bodyOf(fetchSpy) as { droppedSinceLastFlush?: number };
+ expect(body.droppedSinceLastFlush).toBe(1);
+ });
+
+ test('a sustained failing burst past the entry cap preserves the accumulated drop count on recovery', async () => {
+ // The reconnect-storm scenario the feature targets: entries arrive faster
+ // than they can be delivered while the server is unreachable. Each auto-flush
+ // at the entry cap drains the queue and fails its POST — the failed-batch
+ // accounting must accumulate across cycles and ride the first delivered batch
+ // once the server recovers. (The ring-overflow `shift` in `enqueue` is not
+ // exercised here: the flush-at-cap drains the queue at exactly the cap, so it
+ // never grows past it — the failed-POST path is the real bound.)
+ let failNext = true;
+ const fetchSpy = mock((_url: string, _init?: RequestInit) =>
+ failNext
+ ? Promise.reject(new Error('network down'))
+ : Promise.resolve(new Response(null, { status: 200 })),
+ );
+ const { con } = install(fetchSpy);
+
+ // Two full cap-sized batches, all failing → two auto-flush cycles.
+ for (let i = 0; i < RENDERER_LOG_MAX_ENTRIES * 2; i++) con.warn(`storm-${i}`);
+ await new Promise((r) => setTimeout(r, 0)); // let both rejection handlers run
+
+ failNext = false;
+ con.warn('delivered');
+ handle?.flushNow();
+ const body = bodyOf(fetchSpy) as { entries: unknown[]; droppedSinceLastFlush?: number };
+ expect(body.entries).toHaveLength(1);
+ expect(body.droppedSinceLastFlush).toBe(RENDERER_LOG_MAX_ENTRIES * 2);
+ });
+
+ test('drop count resets after a delivered batch (field absent when zero)', async () => {
+ let failNext = true;
+ const fetchSpy = mock((_url: string, _init?: RequestInit) =>
+ failNext
+ ? Promise.reject(new Error('network down'))
+ : Promise.resolve(new Response(null, { status: 200 })),
+ );
+ const { con } = install(fetchSpy);
+
+ con.warn('lost');
+ handle?.flushNow();
+ await new Promise((r) => setTimeout(r, 0));
+
+ failNext = false;
+ con.warn('carries the count');
+ handle?.flushNow();
+ await new Promise((r) => setTimeout(r, 0)); // let the success handler subtract
+
+ con.warn('clean batch');
+ handle?.flushNow();
+ const body = bodyOf(fetchSpy) as { entries: unknown[]; droppedSinceLastFlush?: number };
+ expect(body.entries).toHaveLength(1);
+ expect(body.droppedSinceLastFlush).toBeUndefined();
+ });
+
+ test('no droppedSinceLastFlush field when nothing was dropped', () => {
+ const fetchSpy = makeFetchSpy();
+ const { con } = install(fetchSpy);
+ con.warn('all good');
+ handle?.flushNow();
+ const body = bodyOf(fetchSpy) as { droppedSinceLastFlush?: number };
+ expect(body.droppedSinceLastFlush).toBeUndefined();
+ });
+
test('uninstall restores console and clears the marker (fresh install works)', () => {
const fetchSpy = makeFetchSpy();
const con = makeFakeConsole();
diff --git a/packages/app/src/lib/install-client-log-forwarder.ts b/packages/app/src/lib/install-client-log-forwarder.ts
index 5237b5db6..8a14be77d 100644
--- a/packages/app/src/lib/install-client-log-forwarder.ts
+++ b/packages/app/src/lib/install-client-log-forwarder.ts
@@ -145,6 +145,12 @@ export function installClientLogForwarder(
// Set while flushing so neither the flush path nor any transitive console
// call it triggers gets re-captured (recursion guard).
let inForward = false;
+ // Entries lost since the last delivered batch (ring overflow + failed
+ // POSTs). Carried as `droppedSinceLastFlush` on the next successful batch so
+ // the persisted log records that a gap exists — the drops cluster exactly
+ // when diagnostics matter most (reconnect storms), and a silent gap reads
+ // as "nothing happened".
+ let droppedSinceLastFlush = 0;
const original: ConsoleLike = {
log: con.log.bind(con),
@@ -161,19 +167,43 @@ export function installClientLogForwarder(
if (queue.length === 0) return;
const entries = queue.splice(0, RENDERER_LOG_MAX_ENTRIES);
pendingBytes = 0;
+ // Snapshot the drop count at send time: on delivery only this snapshot is
+ // subtracted (not a reset to 0), so drops that accrue while the POST is in
+ // flight survive to the next batch.
+ const droppedAtSend = droppedSinceLastFlush;
inForward = true;
try {
void doFetch('/api/client-logs', {
method: 'POST',
headers: { 'content-type': 'application/json' },
keepalive: true,
- body: JSON.stringify({ entries }),
- }).catch(() => {
- // Network failure — drop. Never surface; never console.* here (would
- // re-capture). The entries are already removed from the queue.
- });
+ body: JSON.stringify(
+ droppedAtSend > 0 ? { entries, droppedSinceLastFlush: droppedAtSend } : { entries },
+ ),
+ }).then(
+ (res) => {
+ if (res.ok) {
+ // Clamp at zero: `inForward` is released in the `finally` before this
+ // promise settles, so a second flush can fire and snapshot the same
+ // non-zero `droppedAtSend`. Two overlapping 2xx deliveries would then
+ // each subtract it and drive the counter negative, suppressing the
+ // next genuine gap marker. The clamp keeps double-reporting from
+ // going below zero.
+ droppedSinceLastFlush = Math.max(0, droppedSinceLastFlush - droppedAtSend);
+ } else {
+ // Non-2xx: the server rejected the batch; these entries are gone.
+ droppedSinceLastFlush += entries.length;
+ }
+ },
+ () => {
+ // Network failure — drop. Never surface; never console.* here (would
+ // re-capture). The entries are already removed from the queue.
+ droppedSinceLastFlush += entries.length;
+ },
+ );
} catch {
// Synchronous failure (e.g. serialization) — drop the batch.
+ droppedSinceLastFlush += entries.length;
} finally {
inForward = false;
}
@@ -185,7 +215,10 @@ export function installClientLogForwarder(
// Bounded ring — drop oldest under sustained backpressure.
if (queue.length > RENDERER_LOG_MAX_ENTRIES) {
const dropped = queue.shift();
- if (dropped) pendingBytes -= estimateEntryBytes(dropped);
+ if (dropped) {
+ pendingBytes -= estimateEntryBytes(dropped);
+ droppedSinceLastFlush += 1;
+ }
}
// Flush on entry count OR byte budget — the byte cap keeps each POST under
// the browser's ~64KB `keepalive` limit so unload-time flushes aren't
diff --git a/packages/app/tests/integration/api-error-envelope/metrics-agent-effects.test.ts b/packages/app/tests/integration/api-error-envelope/metrics-agent-effects.test.ts
new file mode 100644
index 000000000..c44e16182
--- /dev/null
+++ b/packages/app/tests/integration/api-error-envelope/metrics-agent-effects.test.ts
@@ -0,0 +1,107 @@
+/**
+ * Per-handler narrow-integration smoke test for `handleMetricsAgentEffects`.
+ *
+ * Asserts the canonical RFC 9457 wire shape for
+ * `GET /api/metrics/agent-effects`. This handler shares the same
+ * auth-before-method-dispatch ordering as `handleMetricsAgentPresence`
+ * (loopback gate → host-allowlist gate → method check) so a bad Host never
+ * leaks "verb the endpoint expects" via 405.
+ *
+ * Coverage:
+ * - happy path: 200 + `application/json` + body parses against
+ * `MetricsAgentEffectsSuccessSchema`, no `ok` discriminator.
+ * - populated path: an agent write is captured into the doc's ring buffer
+ * and surfaces as a summarized per-doc block (character counts only —
+ * never the raw delta text).
+ * - DNS-rebinding Host → 403 `urn:ok:error:host-not-allowed` (must
+ * emit BEFORE the method check).
+ * - method-not-allowed on POST → 405 `urn:ok:error:method-not-allowed`
+ * with `Allow: GET`.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import {
+ MetricsAgentEffectsSuccessSchema,
+ ProblemDetailsSchema,
+} from '@inkeep/open-knowledge-core';
+import { HARNESS_BOOT_TIMEOUT_MS } from '../harness-boot-timeout';
+import { fetchWithHostHeader } from '../host-header-request.test-helper';
+import { createTestServer, type TestServer } from '../test-harness';
+
+let server: TestServer;
+
+beforeAll(async () => {
+ server = await createTestServer();
+}, HARNESS_BOOT_TIMEOUT_MS);
+
+afterAll(async () => {
+ await server.cleanup();
+});
+
+describe('metrics-agent-effects envelope (RFC 9457)', () => {
+ test('happy path emits flat success body with application/json', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/metrics/agent-effects`);
+ expect(res.status).toBe(200);
+ expect(res.headers.get('content-type')).toBe('application/json');
+
+ const body = await res.json();
+ expect(MetricsAgentEffectsSuccessSchema.safeParse(body).success).toBe(true);
+ expect((body as Record<string, unknown>).ok).toBeUndefined();
+ });
+
+ test('an agent write surfaces as a summarized per-doc block (no raw delta text)', async () => {
+ const docName = `agent-effects-populated-${crypto.randomUUID().slice(0, 8)}`;
+ const written = '# Agent effects probe\n';
+ const writeRes = await fetch(`http://127.0.0.1:${server.port}/api/agent-write-md`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ markdown: written, position: 'replace', docName }),
+ });
+ expect(writeRes.status).toBe(200);
+
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/metrics/agent-effects`);
+ expect(res.status).toBe(200);
+ const parsed = MetricsAgentEffectsSuccessSchema.safeParse(await res.json());
+ expect(parsed.success).toBe(true);
+ if (!parsed.success) return;
+
+ const block = parsed.data.effects.find((b) => b['doc.name'] === docName);
+ expect(block).toBeDefined();
+ expect(block?.entries.length).toBeGreaterThan(0);
+ const entry = block?.entries[0];
+ expect(entry?.insertedChars).toBeGreaterThan(0);
+ // Summaries only: the response must never carry the written text.
+ expect(JSON.stringify(parsed.data)).not.toContain('Agent effects probe');
+ });
+
+ test('DNS-rebinding Host emits 403 urn:ok:error:host-not-allowed BEFORE method check', async () => {
+ const res = await fetchWithHostHeader(
+ `http://127.0.0.1:${server.port}/api/metrics/agent-effects`,
+ 'evil.example.com',
+ { method: 'POST' },
+ );
+ // Auth-before-method-dispatch ordering: bad Host → 403, NOT 405.
+ expect(res.status).toBe(403);
+ expect(res.headers.get('content-type')).toBe('application/problem+json');
+
+ const parsed = ProblemDetailsSchema.safeParse(await res.json());
+ expect(parsed.success).toBe(true);
+ if (parsed.success) {
+ expect(parsed.data.type).toBe('urn:ok:error:host-not-allowed');
+ }
+ });
+
+ test('method-not-allowed on POST (with valid Host) emits problem+json with Allow: GET', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/metrics/agent-effects`, {
+ method: 'POST',
+ });
+ expect(res.status).toBe(405);
+ expect(res.headers.get('allow')).toBe('GET');
+
+ const parsed = ProblemDetailsSchema.safeParse(await res.json());
+ expect(parsed.success).toBe(true);
+ if (parsed.success) {
+ expect(parsed.data.type).toBe('urn:ok:error:method-not-allowed');
+ }
+ });
+});
diff --git a/packages/app/tests/integration/attribution-sweep-coverage.test.ts b/packages/app/tests/integration/attribution-sweep-coverage.test.ts
index da42fb579..eaa92a3a7 100644
--- a/packages/app/tests/integration/attribution-sweep-coverage.test.ts
+++ b/packages/app/tests/integration/attribution-sweep-coverage.test.ts
@@ -188,6 +188,10 @@ const EXEMPT_HANDLERS = new Set([
'handleMetricsReconciliation',
'handleMetricsParseHealth',
'handleMetricsAgentPresence',
+ // `/api/metrics/agent-effects` — GET-only loopback + host-gated diagnostic
+ // (per-doc agent-effects ring-buffer summaries). Read path, no writes,
+ // nothing to attribute — same posture as `handleMetricsAgentPresence`.
+ 'handleMetricsAgentEffects',
// `/api/client-logs` — web/browser renderer console-log ingest. Writes only
// to the `renderer` pino log (diagnostics), no Y.Docs / agent content; gated
// by `checkLocalOpSecurity` like the local-op handlers. No identity needed.
diff --git a/packages/app/tests/integration/client-logs-endpoint.test.ts b/packages/app/tests/integration/client-logs-endpoint.test.ts
index 9d7b04777..902cb33db 100644
--- a/packages/app/tests/integration/client-logs-endpoint.test.ts
+++ b/packages/app/tests/integration/client-logs-endpoint.test.ts
@@ -57,6 +57,23 @@ describe('POST /api/client-logs', () => {
expect(body.accepted).toBe(2);
});
+ test('accepts a batch carrying a droppedSinceLastFlush gap marker', async () => {
+ const res = await postLogs({
+ entries: [{ level: 'warn', message: 'after a reconnect storm' }],
+ droppedSinceLastFlush: 7,
+ });
+ expect(res.status).toBe(200);
+ expect(((await res.json()) as { accepted: number }).accepted).toBe(1);
+ });
+
+ test('rejects a negative droppedSinceLastFlush with 400', async () => {
+ const res = await postLogs({
+ entries: [{ level: 'warn', message: 'x' }],
+ droppedSinceLastFlush: -1,
+ });
+ expect(res.status).toBe(400);
+ });
+
test('accepts an empty batch (accepted: 0)', async () => {
const res = await postLogs({ entries: [] });
expect(res.status).toBe(200);
diff --git a/packages/app/tests/integration/conflict-gate-coverage.test.ts b/packages/app/tests/integration/conflict-gate-coverage.test.ts
index 935b0ac2d..8f5fa0023 100644
--- a/packages/app/tests/integration/conflict-gate-coverage.test.ts
+++ b/packages/app/tests/integration/conflict-gate-coverage.test.ts
@@ -125,6 +125,11 @@ const EXEMPT_HANDLERS = new Set([
'handleMetricsReconciliation',
'handleMetricsParseHealth',
'handleMetricsAgentPresence',
+ // `/api/metrics/agent-effects` — GET-only loopback + host-gated diagnostic
+ // summarizing the per-doc `Y.Map('agent-effects')` ring buffers. Reads only;
+ // targets no Y.Doc write, so the per-doc conflict gate does not apply — same
+ // posture as its `handleMetricsAgentPresence` sibling.
+ 'handleMetricsAgentEffects',
// `/api/__embed-detect` — read-only loopback + host-gated diagnostic for the
// embedded-viewer detection spikes; reads the in-process UA ring buffer and
// returns boolean signals, targets no Y.Doc, so the per-doc conflict gate
diff --git a/packages/cli/src/diagnose/bundle-redact.test.ts b/packages/cli/src/diagnose/bundle-redact.test.ts
index 948553238..2fe6333b7 100644
--- a/packages/cli/src/diagnose/bundle-redact.test.ts
+++ b/packages/cli/src/diagnose/bundle-redact.test.ts
@@ -358,6 +358,78 @@ describe('redactStagedBundle — contentDir substitution', () => {
expect(Object.values(result.docNameMap)).toContain('live-doc');
});
+ test('hashes the real `currentDoc` field the presence endpoint emits', () => {
+ // The live `/api/metrics/agent-presence` wire body carries the doc path
+ // under `currentDoc`, not `doc.name`. The walker must hash that exact key
+ // so a staged presence artifact never leaks the doc a human is editing.
+ const stagingDir = makeStagingDir();
+ const contentDir = '/Users/test/notes';
+ writeStaged(
+ stagingDir,
+ 'state/agent-presence.json',
+ `${JSON.stringify({
+ presence: {
+ 'agent-a1': {
+ displayName: 'Claude',
+ icon: 'claude',
+ color: '#abc',
+ currentDoc: 'meetings/secret-standup',
+ mode: 'writing',
+ ts: 1,
+ },
+ },
+ })}`,
+ );
+
+ const result = redactStagedBundle({ stagingDir, contentDir });
+
+ const after = JSON.parse(readStaged(stagingDir, 'state/agent-presence.json'));
+ expect(after.presence['agent-a1'].currentDoc).toMatch(/^doc:[a-f0-9]{8}$/);
+ expect(JSON.stringify(after)).not.toContain('meetings/secret-standup');
+ expect(Object.values(result.docNameMap)).toContain('meetings/secret-standup');
+ });
+
+ test('leaves a null `currentDoc` untouched (only strings hash)', () => {
+ const stagingDir = makeStagingDir();
+ const contentDir = '/Users/test/notes';
+ writeStaged(
+ stagingDir,
+ 'state/agent-presence.json',
+ `${JSON.stringify({
+ presence: { 'agent-a1': { currentDoc: null, mode: 'idle', ts: 1 } },
+ })}`,
+ );
+
+ redactStagedBundle({ stagingDir, contentDir });
+
+ const after = JSON.parse(readStaged(stagingDir, 'state/agent-presence.json'));
+ expect(after.presence['agent-a1'].currentDoc).toBeNull();
+ });
+
+ test('hashes doc.name values in state/agent-effects.json via the walker pass', () => {
+ const stagingDir = makeStagingDir();
+ const contentDir = '/Users/test/notes';
+ writeStaged(
+ stagingDir,
+ 'state/agent-effects.json',
+ `${JSON.stringify({
+ effects: [
+ {
+ 'doc.name': 'meetings/standup',
+ entries: [{ sessionId: 'agent-a1', agentType: 'claude', ts: 1, insertedChars: 4 }],
+ },
+ ],
+ })}`,
+ );
+
+ const result = redactStagedBundle({ stagingDir, contentDir });
+
+ const after = JSON.parse(readStaged(stagingDir, 'state/agent-effects.json'));
+ expect(after.effects[0]['doc.name']).toMatch(/^doc:[a-f0-9]{8}$/);
+ expect(after.effects[0].entries[0].sessionId).toBe('agent-a1');
+ expect(Object.values(result.docNameMap)).toContain('meetings/standup');
+ });
+
test('strings that do not include contentDir are passed through verbatim', () => {
const stagingDir = makeStagingDir();
const contentDir = '/Users/test/notes';
diff --git a/packages/cli/src/diagnose/bundle-redact.ts b/packages/cli/src/diagnose/bundle-redact.ts
index 045ad5d32..79e95bdc7 100644
--- a/packages/cli/src/diagnose/bundle-redact.ts
+++ b/packages/cli/src/diagnose/bundle-redact.ts
@@ -31,8 +31,12 @@ const HASH_HEX_LEN = 8;
// Keys whose values are treated as doc-name-shaped. The OTLP attribute pair
// form sets `key` to one of these and stores the value under `value.stringValue`;
// the Pino flat form sets the key directly on the log record. Single source
-// for both shapes — extending DOC_NAME_KEYS covers both at once.
-const DOC_NAME_KEYS = new Set(['doc.name']);
+// for both shapes — extending DOC_NAME_KEYS covers both at once. `currentDoc`
+// is the workspace-relative doc path carried by `agent-presence.json` entries;
+// hashing it keeps a redacted presence artifact from leaking the doc a human
+// was editing (same anonymization guarantee the `doc.name`-keyed effects
+// artifact already gets).
+const DOC_NAME_KEYS = new Set(['doc.name', 'currentDoc']);
export interface RedactStagedBundleOpts {
/** Absolute path to the staging dir (contains telemetry/, logs/, state/). */
@@ -263,10 +267,10 @@ function walkDirFiles(dir: string): string[] {
}
}
-// State files that are JSON-shaped get a full walker pass (agent-presence may
-// carry per-agent doc.name fields; runtime.json may carry the contentDir).
-// Other state files get substring-only substitution.
-const STATE_JSON_FILES = new Set(['agent-presence.json', 'runtime.json']);
+// State files that are JSON-shaped get a full walker pass (agent-presence and
+// agent-effects may carry per-doc `doc.name` fields; runtime.json may carry
+// the contentDir). Other state files get substring-only substitution.
+const STATE_JSON_FILES = new Set(['agent-presence.json', 'agent-effects.json', 'runtime.json']);
export function redactStagedBundle(opts: RedactStagedBundleOpts): RedactStagedBundleResult {
const ctx: RedactCtx = {
diff --git a/packages/cli/src/diagnose/bundle.test.ts b/packages/cli/src/diagnose/bundle.test.ts
index 7f8b60c76..37385c8db 100644
--- a/packages/cli/src/diagnose/bundle.test.ts
+++ b/packages/cli/src/diagnose/bundle.test.ts
@@ -44,7 +44,9 @@ afterEach(() => {
function makeDeterministicDeps(over: Partial<CollectBundleDeps> = {}): CollectBundleDeps {
return {
fetchAgentPresence: async () => null,
+ fetchAgentEffects: async () => null,
readShadowHead: () => null,
+ readCheckpointRefs: () => null,
now: () => new Date('2026-05-28T14:22:01.000Z'),
okVersion: () => '0.7.99',
readDesktopEnv: () => null,
@@ -310,6 +312,48 @@ describe('collectBundle — server status', () => {
collected.cleanup();
});
+ test('lock present + agent-effects 2xx → agent-effects.json staged', async () => {
+ const contentDir = makeTmpDir();
+ writeAt(
+ contentDir,
+ '.ok/local/server.lock',
+ JSON.stringify({ pid: 1, port: 4711, hostname: 'h', startedAt: 't', worktreeRoot: '/' }),
+ );
+ let queriedPort = -1;
+ const deps = makeDeterministicDeps({
+ fetchAgentPresence: async () => JSON.stringify({ presence: {} }),
+ fetchAgentEffects: async (port) => {
+ queriedPort = port;
+ return JSON.stringify({ effects: [] });
+ },
+ });
+ const collected = await collectBundle({ contentDir, deps });
+
+ expect(queriedPort).toBe(4711);
+ const effectsPath = join(collected.stagingDir, 'state', 'agent-effects.json');
+ expect(existsSync(effectsPath)).toBe(true);
+ expect(JSON.parse(readFileSync(effectsPath, 'utf-8'))).toEqual({ effects: [] });
+ collected.cleanup();
+ });
+
+ test('agent-effects failure never affects serverStatus (presence is the probe)', async () => {
+ const contentDir = makeTmpDir();
+ writeAt(
+ contentDir,
+ '.ok/local/server.lock',
+ JSON.stringify({ pid: 1, port: 4711, hostname: 'h', startedAt: 't', worktreeRoot: '/' }),
+ );
+ const deps = makeDeterministicDeps({
+ fetchAgentPresence: async () => JSON.stringify({ presence: {} }),
+ fetchAgentEffects: async () => null,
+ });
+ const collected = await collectBundle({ contentDir, deps });
+
+ expect(collected.manifest.serverStatus).toBe('running');
+ expect(existsSync(join(collected.stagingDir, 'state', 'agent-effects.json'))).toBe(false);
+ collected.cleanup();
+ });
+
test('corrupt lock → not-running, lock still staged for forensics', async () => {
const contentDir = makeTmpDir();
writeAt(contentDir, '.ok/local/server.lock', 'not json {');
@@ -345,6 +389,28 @@ describe('collectBundle — state files', () => {
collected.cleanup();
});
+ test('checkpoint-refs.txt is written when readCheckpointRefs returns content', async () => {
+ const contentDir = makeTmpDir();
+ const listing =
+ 'refs/checkpoints/main/deadbee\t2026-05-28T14:00:00+00:00\tcheckpoint: Before concurrent merge @ 2026-05-28T14:00:00.000Z\n';
+ const deps = makeDeterministicDeps({
+ readCheckpointRefs: () => listing,
+ });
+ const collected = await collectBundle({ contentDir, deps });
+ expect(readFileSync(join(collected.stagingDir, 'state', 'checkpoint-refs.txt'), 'utf-8')).toBe(
+ listing,
+ );
+ expect(collected.manifest.files.map((f) => f.path)).toContain('state/checkpoint-refs.txt');
+ collected.cleanup();
+ });
+
+ test('checkpoint-refs.txt is omitted when readCheckpointRefs returns null', async () => {
+ const contentDir = makeTmpDir();
+ const collected = await collectBundle({ contentDir, deps: makeDeterministicDeps() });
+ expect(existsSync(join(collected.stagingDir, 'state', 'checkpoint-refs.txt'))).toBe(false);
+ collected.cleanup();
+ });
+
test('last-server-exit.json is staged when the desktop host wrote one', async () => {
const contentDir = makeTmpDir();
const body = `${JSON.stringify(
diff --git a/packages/cli/src/diagnose/bundle.ts b/packages/cli/src/diagnose/bundle.ts
index ba63ba839..26f5e037e 100644
--- a/packages/cli/src/diagnose/bundle.ts
+++ b/packages/cli/src/diagnose/bundle.ts
@@ -202,12 +202,28 @@ export interface CollectBundleDeps {
* on any failure (network, timeout, non-2xx).
*/
fetchAgentPresence?: (port: number) => Promise<string | null>;
+ /**
+ * Fetch the running server's `GET /api/metrics/agent-effects` response
+ * (per-doc agent activity ring-buffer summaries), within the 1s budget.
+ * Returns the response body string on 2xx, or `null` on any failure.
+ * Best-effort like agent-presence; a `null` never affects `serverStatus`.
+ */
+ fetchAgentEffects?: (port: number) => Promise<string | null>;
/**
* Read the last 50 entries of the shadow repo log at
* `<contentDir>/.git/ok/`. Returns the stdout string or `null` if the
* shadow repo is missing or git fails.
*/
readShadowHead?: (contentDir: string) => string | null;
+ /**
+ * List the most recent `refs/checkpoints/*` refs of the shadow repo at
+ * `<contentDir>/.git/ok/` — the content-loss / rescue recovery snapshots.
+ * One tab-separated line per ref: ref name, creation date, commit subject
+ * (the subject is a content-free label; the commit BODY, which can carry
+ * doc names and lost content, is deliberately not read). Returns the
+ * listing string or `null` if the shadow repo is missing or git fails.
+ */
+ readCheckpointRefs?: (contentDir: string) => string | null;
/** Returns the current timestamp. Override in tests for determinism. */
now?: () => Date;
/** Returns the OK CLI's package version. */
@@ -322,6 +338,7 @@ export const _pathHelpersForTests = {
const AGENT_PRESENCE_TIMEOUT_MS = 1000;
const SHADOW_GIT_LOG_LIMIT = 50;
+const CHECKPOINT_REF_LIMIT = 50;
async function defaultFetchAgentPresence(port: number): Promise<string | null> {
try {
@@ -338,6 +355,21 @@ async function defaultFetchAgentPresence(port: number): Promise<string | null> {
}
}
+async function defaultFetchAgentEffects(port: number): Promise<string | null> {
+ try {
+ const response = await fetch(`http://127.0.0.1:${port}/api/metrics/agent-effects`, {
+ signal: AbortSignal.timeout(AGENT_PRESENCE_TIMEOUT_MS),
+ });
+ if (!response.ok) return null;
+ return await response.text();
+ } catch {
+ // Same all-failures-collapse-to-null posture as agent-presence — a
+ // server without the endpoint (older version) or not running must not
+ // fail the bundle.
+ return null;
+ }
+}
+
function defaultReadShadowHead(contentDir: string): string | null {
const shadowDir = join(contentDir, '.git', 'ok');
if (!existsSync(shadowDir)) return null;
@@ -350,6 +382,31 @@ function defaultReadShadowHead(contentDir: string): string | null {
return result.stdout ?? '';
}
+function defaultReadCheckpointRefs(contentDir: string): string | null {
+ const shadowDir = join(contentDir, '.git', 'ok');
+ if (!existsSync(shadowDir)) return null;
+ // `%(contents:subject)` only: checkpoint commit bodies carry an
+ // `ok-checkpoint-v1` JSON line with the doc name and (for merge-loss
+ // checkpoints) lost-content substrings — the subject is a content-free
+ // label, so restricting the format keeps the artifact safe to stage as
+ // plain text under the same redaction rules as shadow-head.txt.
+ const result = spawnSync(
+ 'git',
+ [
+ '-C',
+ shadowDir,
+ 'for-each-ref',
+ '--sort=-creatordate',
+ `--count=${CHECKPOINT_REF_LIMIT}`,
+ '--format=%(refname)%09%(creatordate:iso-strict)%09%(contents:subject)',
+ 'refs/checkpoints/',
+ ],
+ withHiddenWindowsConsole({ encoding: 'utf-8', timeout: 2000 }),
+ );
+ if (result.error || result.status !== 0) return null;
+ return result.stdout ?? '';
+}
+
export function defaultReadDesktopEnv(): DesktopMetadata | null {
const electronVersion = process.env.OK_DESKTOP_VERSION;
const packagedRaw = process.env.OK_DESKTOP_PACKAGED;
@@ -569,7 +626,9 @@ export async function collectBundle(opts: CollectBundleOpts): Promise<CollectedB
const projectDir = resolve(opts.projectDir ?? opts.contentDir);
const deps = opts.deps ?? {};
const fetchAgentPresence = deps.fetchAgentPresence ?? defaultFetchAgentPresence;
+ const fetchAgentEffects = deps.fetchAgentEffects ?? defaultFetchAgentEffects;
const readShadowHead = deps.readShadowHead ?? defaultReadShadowHead;
+ const readCheckpointRefs = deps.readCheckpointRefs ?? defaultReadCheckpointRefs;
const now = deps.now ?? (() => new Date());
const okVersion = deps.okVersion ?? (() => PACKAGE_VERSION);
const readDesktopEnv = deps.readDesktopEnv ?? defaultReadDesktopEnv;
@@ -621,6 +680,13 @@ export async function collectBundle(opts: CollectBundleOpts): Promise<CollectedB
} else {
serverStatusReason = `agent-presence endpoint at :${lockPort} unreachable`;
}
+ // Agent-effects ring-buffer summaries — best effort, never affects
+ // serverStatus (presence remains the liveness probe; an older server
+ // without this endpoint is still "running").
+ const agentEffects = await fetchAgentEffects(lockPort);
+ if (agentEffects !== null) {
+ writeFileSync(join(stagingDir, 'state', 'agent-effects.json'), agentEffects);
+ }
}
// Shadow-repo head — best effort.
@@ -629,6 +695,16 @@ export async function collectBundle(opts: CollectBundleOpts): Promise<CollectedB
writeFileSync(join(stagingDir, 'state', 'shadow-head.txt'), shadowHead);
}
+ // Recovery-checkpoint refs (`refs/checkpoints/*`) — best effort. The
+ // default-branch shadow log above never shows these one-shot refs, yet
+ // they are the primary artifact for the content-loss bug class: their
+ // presence, kind-bearing subjects, and timestamps tell the recipient
+ // whether (and when) the bridge detected potential loss.
+ const checkpointRefs = readCheckpointRefs(contentDir);
+ if (checkpointRefs !== null) {
+ writeFileSync(join(stagingDir, 'state', 'checkpoint-refs.txt'), checkpointRefs);
+ }
+
// last-spawn-error.log (Electron host writes this when a spawn fails).
stageFileIfPresent(
join(lockDir, 'last-spawn-error.log'),
diff --git a/packages/core/src/bridge/bind-frontmatter-doc.ts b/packages/core/src/bridge/bind-frontmatter-doc.ts
index 8f9d95287..c014b1413 100644
--- a/packages/core/src/bridge/bind-frontmatter-doc.ts
+++ b/packages/core/src/bridge/bind-frontmatter-doc.ts
@@ -1,4 +1,3 @@
-
import type * as Y from 'yjs';
import type { Err, Ok, Result } from '../config/result.ts';
import { type FrontmatterValidationError, toFrontmatterIssue } from '../frontmatter/errors.ts';
diff --git a/packages/core/src/bridge/bridge-invariant.ts b/packages/core/src/bridge/bridge-invariant.ts
index 8bfdb40cd..005627195 100644
--- a/packages/core/src/bridge/bridge-invariant.ts
+++ b/packages/core/src/bridge/bridge-invariant.ts
@@ -1,4 +1,3 @@
-
import { fnv1aDigest } from './hash-util.ts';
export type BridgeInvariantSite = 'observer-b' | 'persistence' | 'test-harness';
diff --git a/packages/core/src/bridge/doc-boundary-space.ts b/packages/core/src/bridge/doc-boundary-space.ts
index c18c086d5..8890f6739 100644
--- a/packages/core/src/bridge/doc-boundary-space.ts
+++ b/packages/core/src/bridge/doc-boundary-space.ts
@@ -1,4 +1,3 @@
-
import { FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';
const LEADING_BOUNDARY_RE = /^(?:\r?\n)+/;
diff --git a/packages/core/src/bridge/growth-detect.ts b/packages/core/src/bridge/growth-detect.ts
index 463e89595..9d9c244b0 100644
--- a/packages/core/src/bridge/growth-detect.ts
+++ b/packages/core/src/bridge/growth-detect.ts
@@ -1,4 +1,3 @@
-
const DEFAULT_MIN_SUBSTANTIVE_LINE_LENGTH = 16;
export const DUPLICATION_GATE_MIN_LINE_LENGTH = 8;
diff --git a/packages/core/src/bridge/merge-three-way.ts b/packages/core/src/bridge/merge-three-way.ts
index 3c927eb47..3ab9cc6ef 100644
--- a/packages/core/src/bridge/merge-three-way.ts
+++ b/packages/core/src/bridge/merge-three-way.ts
@@ -38,7 +38,6 @@ function mergeThreeWayImpl(baseline: string, userText: string, agentText: string
return parts.join('\n');
}
-
export type BridgeMergeContentLossSide = 'user' | 'agent';
export type BridgeMergeContentLossWhich = 'substring' | 'order' | 'growth';
diff --git a/packages/core/src/bridge/normalize.ts b/packages/core/src/bridge/normalize.ts
index 3f0880aa5..4b8890476 100644
--- a/packages/core/src/bridge/normalize.ts
+++ b/packages/core/src/bridge/normalize.ts
@@ -1,4 +1,3 @@
-
const COMMONMARK_ESCAPE_RE = /\\([!"#$%&'()*+,\-./:;<=>?@[\]^_`{|}~])/g;
const TABLE_ALIGN_ROW_RE = /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)+\|?\s*$/;
diff --git a/packages/core/src/bridge/pm-structural-equivalence.ts b/packages/core/src/bridge/pm-structural-equivalence.ts
index 0be5203e4..754dc5cc2 100644
--- a/packages/core/src/bridge/pm-structural-equivalence.ts
+++ b/packages/core/src/bridge/pm-structural-equivalence.ts
@@ -32,7 +32,6 @@ const BR_SENTINEL: PmStructuralNode = { type: '__br__' };
const BR_LITERAL_RE = /^<br\s*\/?>$/i;
-
interface DegradeEntry {
readonly label: string;
readonly severity: ToleranceClassSeverity;
@@ -128,7 +127,6 @@ export interface ComparePmStructuralOptions {
ignoreAttrs?: (attrKey: string) => boolean;
}
-
/** Rebuild a node with `fn` applied to each child; identity when childless.
* Shared by the degrade canonicalizers so none re-implements the walk. */
function mapChildren(
@@ -250,7 +248,6 @@ function applyDegrades(tree: PmStructuralNode): {
return { normalized: current, fired };
}
-
export function comparePmStructural(
expected: PmStructuralNode,
actual: PmStructuralNode,
diff --git a/packages/core/src/bridge/subsequence.ts b/packages/core/src/bridge/subsequence.ts
index dca644141..af20de1e2 100644
--- a/packages/core/src/bridge/subsequence.ts
+++ b/packages/core/src/bridge/subsequence.ts
@@ -1,4 +1,3 @@
-
/** True when `needle` is a subsequence of `haystack` (two-pointer, O(n+m)):
* insertions in `haystack` are free; any dropped or substituted `needle` byte
* fails. */
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 950792556..666c3e892 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -561,6 +561,10 @@ export {
AgentActivitySuccessSchema,
type AgentBurstDiffSuccess,
AgentBurstDiffSuccessSchema,
+ AgentEffectEntrySchema,
+ type AgentEffectEntryWire,
+ AgentEffectsDocSchema,
+ type AgentEffectsDocWire,
type AgentPatchRequest,
AgentPatchRequestSchema,
type AgentPatchSuccess,
@@ -736,6 +740,8 @@ export {
LocalOpOkInitRequestSchema,
type LocalOpOkInitResponse,
LocalOpOkInitResponseSchema,
+ type MetricsAgentEffectsSuccess,
+ MetricsAgentEffectsSuccessSchema,
type MetricsAgentPresenceSuccess,
MetricsAgentPresenceSuccessSchema,
type MetricsParseHealthSuccess,
diff --git a/packages/core/src/markdown/callout-transformer.ts b/packages/core/src/markdown/callout-transformer.ts
index a363dfd54..83d47404a 100644
--- a/packages/core/src/markdown/callout-transformer.ts
+++ b/packages/core/src/markdown/callout-transformer.ts
@@ -1,4 +1,3 @@
-
import type { Blockquote, Paragraph, Root } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.ts
index 47f0d07e4..193e286b0 100644
--- a/packages/core/src/markdown/comment-promoter.ts
+++ b/packages/core/src/markdown/comment-promoter.ts
@@ -1,4 +1,3 @@
-
import type { Nodes, Paragraph, PhrasingContent, Root, RootContent, Text } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/dedent-block-jsx-close.ts b/packages/core/src/markdown/dedent-block-jsx-close.ts
index b6299a948..ece5c02a1 100644
--- a/packages/core/src/markdown/dedent-block-jsx-close.ts
+++ b/packages/core/src/markdown/dedent-block-jsx-close.ts
@@ -1,4 +1,3 @@
-
import { findFencedRegions, isInsideFence } from './fence-regions.ts';
const INDENTED_BLOCK_JSX_CLOSE_RE = /^([ ]{1,3})(<\/[A-Z][A-Za-z0-9_]*\s*>)([ \t]*)$/gm;
diff --git a/packages/core/src/markdown/details-accordion-promoter.ts b/packages/core/src/markdown/details-accordion-promoter.ts
index acd398aa6..54774764a 100644
--- a/packages/core/src/markdown/details-accordion-promoter.ts
+++ b/packages/core/src/markdown/details-accordion-promoter.ts
@@ -1,4 +1,3 @@
-
import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/fence-regions.ts b/packages/core/src/markdown/fence-regions.ts
index fb5ac8e8a..c7518d614 100644
--- a/packages/core/src/markdown/fence-regions.ts
+++ b/packages/core/src/markdown/fence-regions.ts
@@ -1,4 +1,3 @@
-
const FENCE_RE = /^(`{3,}|~{3,})/gm;
export function findFencedRegions(src: string): Array<[number, number]> {
diff --git a/packages/core/src/markdown/fixtures/index.ts b/packages/core/src/markdown/fixtures/index.ts
index 6931623c7..00f5771ee 100644
--- a/packages/core/src/markdown/fixtures/index.ts
+++ b/packages/core/src/markdown/fixtures/index.ts
@@ -1,4 +1,3 @@
-
import { readFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -9,7 +8,6 @@ function fixturePath(...segments: string[]): string {
return resolve(FIXTURES_DIR, ...segments);
}
-
interface GfmExample {
section: string;
markdown: string;
@@ -19,7 +17,6 @@ export function loadGfmExamples(): GfmExample[] {
return JSON.parse(readFileSync(fixturePath('gfm', 'examples.json'), 'utf8')) as GfmExample[];
}
-
interface MdxCrashEntry {
id: string;
input: string;
@@ -71,7 +68,6 @@ export function loadLargeEmbedFixtures(): LargeEmbedFixture[] {
) as LargeEmbedFixture[];
}
-
export function loadPrd6955Before(): string {
return readFileSync(fixturePath('regression', 'prd-6955-before.md'), 'utf8');
}
@@ -80,7 +76,6 @@ export function loadPrd6955CorruptedTriplicated(): string {
return readFileSync(fixturePath('regression', 'prd-6955-corrupted-triplicated.md'), 'utf8');
}
-
export interface NgPinnedCase {
id: string;
name: string;
@@ -97,7 +92,6 @@ export function loadNgPinnedCases(): NgPinnedCase[] {
) as NgPinnedCase[];
}
-
export function loadLargeRealistic(): string {
return readFileSync(fixturePath('perf', 'large-realistic.md'), 'utf8');
}
diff --git a/packages/core/src/markdown/fixtures/perf/generate.ts b/packages/core/src/markdown/fixtures/perf/generate.ts
index daa3ef82b..8b1eb8519 100644
--- a/packages/core/src/markdown/fixtures/perf/generate.ts
+++ b/packages/core/src/markdown/fixtures/perf/generate.ts
@@ -1,4 +1,3 @@
-
import { writeFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -11,7 +10,6 @@ const BASELINE_ONLY_COUNTS = [500, 2500] as const;
const SEED = 0xf1de1117;
-
function mulberry32(seed: number): () => number {
let a = seed >>> 0;
return () => {
@@ -38,7 +36,6 @@ function pickWeighted<T>(rand: () => number, items: readonly [T, number][]): T {
return items[items.length - 1][0];
}
-
const WORDS = [
'lorem',
'ipsum',
@@ -156,7 +153,6 @@ function mdxBlock(rand: () => number): string {
return `<${name}>\n\n${sentence(rand)}\n\n</${name}>`;
}
-
type BlockKind = 'paragraph' | 'heading' | 'list' | 'code' | 'table' | 'mdx';
const MIX: readonly [BlockKind, number][] = [
@@ -195,7 +191,6 @@ function generateDocument(blockCount: number, seed: number): string {
return `${blocks.join('\n\n')}\n`;
}
-
function main(): void {
for (const count of [...BLOCK_COUNTS, ...BASELINE_ONLY_COUNTS]) {
const doc = generateDocument(count, SEED);
diff --git a/packages/core/src/markdown/guard-flanking-matrix.ts b/packages/core/src/markdown/guard-flanking-matrix.ts
index 32c055c5b..420dc0fe5 100644
--- a/packages/core/src/markdown/guard-flanking-matrix.ts
+++ b/packages/core/src/markdown/guard-flanking-matrix.ts
@@ -7,7 +7,6 @@ import {
import { BACKSLASH_GUARD_SUBSTITUTIONS, encodeBackslashEscapes } from './backslash-escape-guard.ts';
import { ENTITY_REF_GUARD_SUBSTITUTIONS, encodeEntityRefs } from './entity-ref-guard.ts';
-
export const ATTENTION_DELIMITERS = ['*', '_', '**', '~~', '=='] as const;
export type FlankClass = 'whitespace' | 'punctuation' | 'other';
diff --git a/packages/core/src/markdown/handler-shadow-audit.ts b/packages/core/src/markdown/handler-shadow-audit.ts
index 283913255..2653473da 100644
--- a/packages/core/src/markdown/handler-shadow-audit.ts
+++ b/packages/core/src/markdown/handler-shadow-audit.ts
@@ -1,4 +1,3 @@
-
export interface HandlerShadowWitness {
input: string;
expect: 'byte' | 'byte-and-reparse-type';
diff --git a/packages/core/src/markdown/highlight-promoter.ts b/packages/core/src/markdown/highlight-promoter.ts
index 6319f264f..f55912407 100644
--- a/packages/core/src/markdown/highlight-promoter.ts
+++ b/packages/core/src/markdown/highlight-promoter.ts
@@ -1,4 +1,3 @@
-
import type { Nodes, Parent, PhrasingContent, Root, Text } from 'mdast';
import type { MdxJsxTextElement } from 'mdast-util-mdx';
import { SKIP, visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/html-to-mdast.ts b/packages/core/src/markdown/html-to-mdast.ts
index 2f082e6d0..78fdfeb02 100644
--- a/packages/core/src/markdown/html-to-mdast.ts
+++ b/packages/core/src/markdown/html-to-mdast.ts
@@ -1,4 +1,3 @@
-
import type { Root as HastRoot } from 'hast';
import type { Root as MdastRoot } from 'mdast';
import rehypeParse from 'rehype-parse';
@@ -76,8 +75,7 @@ export function htmlToMdast(html: string, options?: HtmlToMdastOptions): MdastRo
throw new HtmlPayloadTooLargeError(html.length, maxBytes);
}
- const processor = unified()
- .use(rehypeParse, { fragment: true });
+ const processor = unified().use(rehypeParse, { fragment: true });
for (const plugin of cleanupPlugins) {
processor.use(plugin);
diff --git a/packages/core/src/markdown/image-promoter.ts b/packages/core/src/markdown/image-promoter.ts
index 994eb6917..706fa9afb 100644
--- a/packages/core/src/markdown/image-promoter.ts
+++ b/packages/core/src/markdown/image-promoter.ts
@@ -1,4 +1,3 @@
-
import type { Image, Paragraph, Root } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/index.ts b/packages/core/src/markdown/index.ts
index fc30bda02..8b36807fd 100644
--- a/packages/core/src/markdown/index.ts
+++ b/packages/core/src/markdown/index.ts
@@ -1,4 +1,3 @@
-
import {
type FromProseMirrorOptions,
fromPmMark,
@@ -197,7 +196,6 @@ export class MarkdownManager {
}
}
-
const registry = createRegistry();
function destructureAttrs(
@@ -246,7 +244,6 @@ function destructureAttrs(
return result;
}
-
function hasDirtyDescendant(node: PmNode): boolean {
let found = false;
node.descendants((child) => {
@@ -266,7 +263,6 @@ function effectiveDirty(node: PmNode, freshnessChecker?: StructuralFreshnessChec
return freshnessChecker ? freshnessChecker.isDiverged(node.toJSON()) : false;
}
-
function isEmptyMdastParagraph(node: MdastNodes): boolean {
if (node.type !== 'paragraph') return false;
const children = node.children ?? [];
@@ -335,7 +331,6 @@ function extractTextFromMdastNodes(nodes: MdastNodes[]): string {
return out;
}
-
import {
AUDIO_EXTENSIONS,
FILE_ATTACHMENT_EXTENSIONS,
@@ -582,7 +577,6 @@ function buildMdastToPmHandlers(
}));
}
-
if (m.emphasis) {
handlers.emphasis = toPmMark(m.emphasis, (node: Emphasis) => ({
sourceDelimiter: node.data?.sourceDelimiter ?? '*',
@@ -663,7 +657,6 @@ function buildMdastToPmHandlers(
}));
}
-
if (m.link) {
const sourceLiteralMark = m.sourceLiteral;
handlers.link = (node: Link, _parent: MdastParent, state: MdastToPmState) => {
@@ -942,7 +935,6 @@ function buildMdastToPmHandlers(
};
}
-
const blockUnknownHandler = (node: {
type: string;
position?: { start: { offset: number }; end: { offset: number } };
@@ -1068,7 +1060,6 @@ function buildMdastToPmHandlers(
return handlers as RemarkProseMirrorOptions['handlers'];
}
-
function buildPmToMdastHandlers(
schema: Schema,
freshness: FreshnessCheckerHolder,
diff --git a/packages/core/src/markdown/lint/config-schemas.ts b/packages/core/src/markdown/lint/config-schemas.ts
index 207cd95c2..e78a1381d 100644
--- a/packages/core/src/markdown/lint/config-schemas.ts
+++ b/packages/core/src/markdown/lint/config-schemas.ts
@@ -29,7 +29,6 @@ const fullPluginShape = Object.fromEntries(
LINT_PLUGINS.map((plugin) => [plugin.id, plugin.sliceSchema]),
) as z.ZodRawShape;
-
export const LinterConfigSchema = z.object({
enabled: z.boolean(),
plugins: z.object(fullPluginShape),
diff --git a/packages/core/src/markdown/lint/default-config.ts b/packages/core/src/markdown/lint/default-config.ts
index a51f2ffb0..d48eea5e4 100644
--- a/packages/core/src/markdown/lint/default-config.ts
+++ b/packages/core/src/markdown/lint/default-config.ts
@@ -6,7 +6,6 @@ export const DEFAULT_MARKDOWNLINT_CONFIG: Record<string, MarkdownlintRuleSetting
MD013: false,
};
-
export function resolveMarkdownlintConfig(
rules: Record<string, MarkdownlintRuleSetting> | undefined,
): Configuration {
diff --git a/packages/core/src/markdown/lint/index.ts b/packages/core/src/markdown/lint/index.ts
index 3baacdeb7..d1a5ab4dc 100644
--- a/packages/core/src/markdown/lint/index.ts
+++ b/packages/core/src/markdown/lint/index.ts
@@ -1,4 +1,3 @@
-
import { LINT_PLUGINS, type LinterConfig } from './plugins.ts';
import type { LintDiagnostic } from './types.ts';
diff --git a/packages/core/src/markdown/lint/plugins.ts b/packages/core/src/markdown/lint/plugins.ts
index 65a1b564c..1cd40ef3a 100644
--- a/packages/core/src/markdown/lint/plugins.ts
+++ b/packages/core/src/markdown/lint/plugins.ts
@@ -1,4 +1,3 @@
-
import { z } from 'zod';
import { DEFAULT_MARKDOWNLINT_CONFIG, resolveMarkdownlintConfig } from './default-config.ts';
import { fixMarkdownText, runMarkdownlint } from './markdownlint-runner.ts';
@@ -9,7 +8,6 @@ import {
type MarkdownlintSlice,
} from './types.ts';
-
const MarkdownlintRuleSettingSchema = z.union([
z.boolean(),
z.enum(MARKDOWNLINT_RULE_SEVERITIES),
diff --git a/packages/core/src/markdown/lint/types.ts b/packages/core/src/markdown/lint/types.ts
index 3651bd7eb..617f6e5b9 100644
--- a/packages/core/src/markdown/lint/types.ts
+++ b/packages/core/src/markdown/lint/types.ts
@@ -1,4 +1,3 @@
-
export const LINT_PLUGIN_IDS = ['markdownlint'] as const;
export type LintPluginId = (typeof LINT_PLUGIN_IDS)[number];
@@ -42,7 +41,6 @@ export interface MarkdownlintSlice {
rules: Record<string, MarkdownlintRuleSetting>;
}
-
interface RuleOptionSpecBase {
key: string;
description: string;
diff --git a/packages/core/src/markdown/math-promoter.ts b/packages/core/src/markdown/math-promoter.ts
index bd79424c7..a5b511f25 100644
--- a/packages/core/src/markdown/math-promoter.ts
+++ b/packages/core/src/markdown/math-promoter.ts
@@ -1,4 +1,3 @@
-
import type { Code, Root } from 'mdast';
import type { Math as MdastMath } from 'mdast-util-math';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
diff --git a/packages/core/src/markdown/mdast-to-hast-handlers.ts b/packages/core/src/markdown/mdast-to-hast-handlers.ts
index f84967798..679c72ef7 100644
--- a/packages/core/src/markdown/mdast-to-hast-handlers.ts
+++ b/packages/core/src/markdown/mdast-to-hast-handlers.ts
@@ -1,4 +1,3 @@
-
import type { Comment, Element, ElementContent, Properties } from 'hast';
import type { FootnoteDefinition, FootnoteReference } from 'mdast';
import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx';
diff --git a/packages/core/src/markdown/mdast-to-html.ts b/packages/core/src/markdown/mdast-to-html.ts
index df788a80d..8ce2b2492 100644
--- a/packages/core/src/markdown/mdast-to-html.ts
+++ b/packages/core/src/markdown/mdast-to-html.ts
@@ -1,4 +1,3 @@
-
import type { Element, Root as HastRoot, Text as HastText } from 'hast';
import type { Root as MdastRoot, Text as MdastText } from 'mdast';
import type { Handler } from 'mdast-util-to-hast';
diff --git a/packages/core/src/markdown/merged-walker.ts b/packages/core/src/markdown/merged-walker.ts
index fa3cfcd86..bfd7e3109 100644
--- a/packages/core/src/markdown/merged-walker.ts
+++ b/packages/core/src/markdown/merged-walker.ts
@@ -1,4 +1,3 @@
-
import type { Nodes, Parent, Root } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/mermaid-promoter.ts b/packages/core/src/markdown/mermaid-promoter.ts
index 17ed2b829..1a897fca8 100644
--- a/packages/core/src/markdown/mermaid-promoter.ts
+++ b/packages/core/src/markdown/mermaid-promoter.ts
@@ -1,4 +1,3 @@
-
import type { Code, Root } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/parse-with-fallback.ts b/packages/core/src/markdown/parse-with-fallback.ts
index 7e4a9a48b..9864b3b60 100644
--- a/packages/core/src/markdown/parse-with-fallback.ts
+++ b/packages/core/src/markdown/parse-with-fallback.ts
@@ -168,7 +168,6 @@ export function parseRecursive(
}
}
-
interface VFilePlace {
offset?: number;
start?: { offset?: number };
@@ -187,7 +186,6 @@ function extractErrorOffset(err: unknown): number | undefined {
return undefined;
}
-
interface Region {
start: number;
end: number;
@@ -211,7 +209,6 @@ function nearestBlankLineAfter(src: string, offset: number): number | null {
return null;
}
-
export interface TagEvent {
kind: 'open' | 'close' | 'self-close';
name: string;
@@ -358,7 +355,6 @@ function findFallbackRegion(src: string, errorOffset: number): Region {
return { start: blockStart, end: blockEnd };
}
-
interface SourceBlock {
src: string;
start: number;
@@ -456,7 +452,6 @@ function tryPerBlockFallback(
};
}
-
function wholeDocRawText(source: string): JSONContent {
return {
type: 'doc',
diff --git a/packages/core/src/markdown/parser-drop-closure.ts b/packages/core/src/markdown/parser-drop-closure.ts
index 43d420187..e6ab4fd57 100644
--- a/packages/core/src/markdown/parser-drop-closure.ts
+++ b/packages/core/src/markdown/parser-drop-closure.ts
@@ -1,4 +1,3 @@
-
export type DroppedTokenAdjudication =
| {
kind: 'format-dof-axis';
diff --git a/packages/core/src/markdown/pipeline.ts b/packages/core/src/markdown/pipeline.ts
index e9e507469..7f2d5adca 100644
--- a/packages/core/src/markdown/pipeline.ts
+++ b/packages/core/src/markdown/pipeline.ts
@@ -1,4 +1,3 @@
-
import {
type FromProseMirrorOptions,
fromProseMirror,
diff --git a/packages/core/src/markdown/position-aware-join.ts b/packages/core/src/markdown/position-aware-join.ts
index f8f5e8530..5a5e4c42a 100644
--- a/packages/core/src/markdown/position-aware-join.ts
+++ b/packages/core/src/markdown/position-aware-join.ts
@@ -1,4 +1,3 @@
-
import type { Join } from 'mdast-util-to-markdown';
import type { Position } from 'unist';
diff --git a/packages/core/src/markdown/position-slice.ts b/packages/core/src/markdown/position-slice.ts
index e5b4c9eba..0f399d34c 100644
--- a/packages/core/src/markdown/position-slice.ts
+++ b/packages/core/src/markdown/position-slice.ts
@@ -1,4 +1,3 @@
-
import type { Nodes, Root } from 'mdast';
import { visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
@@ -477,8 +476,7 @@ export function applyPositionSliceToNode(
const first = source[startOff];
if (first !== '[' && first !== '<' && !node.title) {
node.data.sourceStyle = 'gfm-autolink';
- }
- else if (first === '[') {
+ } else if (first === '[') {
const slice = source.slice(startOff, endOff);
const closeBracketIdx = slice.lastIndexOf('](');
if (closeBracketIdx !== -1) {
diff --git a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
index ca225ce9b..db10fa54b 100644
--- a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
+++ b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
@@ -1,4 +1,3 @@
-
import type { Comment, Element, Root, Text } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
index 3a2524a9a..34068d103 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
@@ -1,4 +1,3 @@
-
import type { Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
index 2279a0189..93151d43b 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
@@ -1,4 +1,3 @@
-
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
index a0f467c42..188f02d83 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
@@ -1,4 +1,3 @@
-
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
index 4e8542a21..4ba2c3418 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
@@ -1,4 +1,3 @@
-
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
index a3c96b24a..1a74b1272 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
@@ -1,4 +1,3 @@
-
import type { Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
index e95cf43d6..de35e7b79 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
@@ -1,4 +1,3 @@
-
import type { Comment, Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
index ffdb4d5b5..b4be1b2ea 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
@@ -1,4 +1,3 @@
-
import type { Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
index e2a96d1a7..3c8d88b7c 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
@@ -1,4 +1,3 @@
-
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/resolve-image-url.ts b/packages/core/src/markdown/resolve-image-url.ts
index 0389575ac..cf2c9da8e 100644
--- a/packages/core/src/markdown/resolve-image-url.ts
+++ b/packages/core/src/markdown/resolve-image-url.ts
@@ -1,4 +1,3 @@
-
import { isRelativeUrl } from './safe-url.ts';
function isDevDiagnosticContext(): boolean {
diff --git a/packages/core/src/markdown/safe-url.ts b/packages/core/src/markdown/safe-url.ts
index 8be632ba4..4d3250d3a 100644
--- a/packages/core/src/markdown/safe-url.ts
+++ b/packages/core/src/markdown/safe-url.ts
@@ -1,4 +1,3 @@
-
export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;
const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');
diff --git a/packages/core/src/markdown/serialize-helpers.ts b/packages/core/src/markdown/serialize-helpers.ts
index 542204403..46cc6a074 100644
--- a/packages/core/src/markdown/serialize-helpers.ts
+++ b/packages/core/src/markdown/serialize-helpers.ts
@@ -1,4 +1,3 @@
-
import type { Node as PmNode } from '@tiptap/pm/model';
import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import type { PropDef, SerializeContext } from '../registry/types.ts';
diff --git a/packages/core/src/markdown/single-dollar-math-promoter.ts b/packages/core/src/markdown/single-dollar-math-promoter.ts
index fe73659e6..be97d4d62 100644
--- a/packages/core/src/markdown/single-dollar-math-promoter.ts
+++ b/packages/core/src/markdown/single-dollar-math-promoter.ts
@@ -1,4 +1,3 @@
-
import type { PhrasingContent, Root, Text } from 'mdast';
import type { InlineMath } from 'mdast-util-math';
import { SKIP, visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/to-markdown-handlers.ts b/packages/core/src/markdown/to-markdown-handlers.ts
index 7bce04302..8f4e9a41c 100644
--- a/packages/core/src/markdown/to-markdown-handlers.ts
+++ b/packages/core/src/markdown/to-markdown-handlers.ts
@@ -1,4 +1,3 @@
-
import type { Nodes, Parents } from 'mdast';
import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import type { Handle, Info, State } from 'mdast-util-to-markdown';
diff --git a/packages/core/src/markdown/unknown-mdast-guard.ts b/packages/core/src/markdown/unknown-mdast-guard.ts
index c5bfd2386..cd245c38c 100644
--- a/packages/core/src/markdown/unknown-mdast-guard.ts
+++ b/packages/core/src/markdown/unknown-mdast-guard.ts
@@ -1,4 +1,3 @@
-
import type { Root as MdastRoot } from 'mdast';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/whitespace-char-ref.ts b/packages/core/src/markdown/whitespace-char-ref.ts
index ac9f5239b..d578476a7 100644
--- a/packages/core/src/markdown/whitespace-char-ref.ts
+++ b/packages/core/src/markdown/whitespace-char-ref.ts
@@ -1,4 +1,3 @@
-
const INLINE_WHITESPACE_BY_CODE: ReadonlyMap<number, string> = new Map([
[0x20, ' '],
[0x09, '\t'],
diff --git a/packages/core/src/markdown/wiki-link-micromark.ts b/packages/core/src/markdown/wiki-link-micromark.ts
index afd9936fe..6dad26200 100644
--- a/packages/core/src/markdown/wiki-link-micromark.ts
+++ b/packages/core/src/markdown/wiki-link-micromark.ts
@@ -17,7 +17,6 @@ declare module 'micromark-util-types' {
}
}
-
const CODE_BANG = 33; // !
const CODE_LBRACKET = 91; // [
const CODE_RBRACKET = 93; // ]
@@ -261,7 +260,6 @@ export function wikiLinkSyntax(): Extension {
};
}
-
function enterWikiLink(this: CompileContext, token: Token) {
this.enter(
{
@@ -387,7 +385,6 @@ export const wikiLinkToMarkdown: {
unsafe: [{ character: '[', inConstruct: ['phrasing'] }],
};
-
const MICROMARK_EXT = wikiLinkSyntax();
export function remarkWikiLink(this: Processor) {
diff --git a/packages/core/src/schemas/api/client-logs.test.ts b/packages/core/src/schemas/api/client-logs.test.ts
index 837ba659a..b4e9bf065 100644
--- a/packages/core/src/schemas/api/client-logs.test.ts
+++ b/packages/core/src/schemas/api/client-logs.test.ts
@@ -38,6 +38,17 @@ describe('ClientLogsRequestSchema', () => {
expect(ClientLogsRequestSchema.safeParse({ entries }).success).toBe(false);
});
+ test('accepts an optional droppedSinceLastFlush count; rejects a negative one', () => {
+ const entries = [{ level: 'info' as const, message: 'x' }];
+ expect(ClientLogsRequestSchema.safeParse({ entries, droppedSinceLastFlush: 3 }).success).toBe(
+ true,
+ );
+ expect(ClientLogsRequestSchema.safeParse({ entries }).success).toBe(true);
+ expect(ClientLogsRequestSchema.safeParse({ entries, droppedSinceLastFlush: -1 }).success).toBe(
+ false,
+ );
+ });
+
test('rejects an oversized message', () => {
const result = ClientLogsRequestSchema.safeParse({
entries: [{ level: 'error', message: 'a'.repeat(RENDERER_LOG_MAX_MESSAGE_BYTES + 1) }],
diff --git a/packages/core/src/schemas/api/client-logs.ts b/packages/core/src/schemas/api/client-logs.ts
index 26d168548..73a978c6a 100644
--- a/packages/core/src/schemas/api/client-logs.ts
+++ b/packages/core/src/schemas/api/client-logs.ts
@@ -33,10 +33,17 @@ export const ClientLogEntrySchema = z
.loose() satisfies StandardSchemaV1;
export type ClientLogEntry = z.infer<typeof ClientLogEntrySchema>;
-/** Request body for `POST /api/client-logs` — a bounded batch of entries. */
+/**
+ * Request body for `POST /api/client-logs` — a bounded batch of entries.
+ * `droppedSinceLastFlush` is the number of entries the client forwarder lost
+ * since its last delivered batch (buffer overflow or failed POSTs — reconnect
+ * storms are the typical cause); the server records it so the persisted log
+ * carries an explicit gap marker instead of silently missing entries.
+ */
export const ClientLogsRequestSchema = z
.object({
entries: z.array(ClientLogEntrySchema).max(RENDERER_LOG_MAX_ENTRIES),
+ droppedSinceLastFlush: z.number().int().min(0).optional(),
})
.loose() satisfies StandardSchemaV1;
export type ClientLogsRequest = z.infer<typeof ClientLogsRequestSchema>;
diff --git a/packages/core/src/schemas/api/metrics.test.ts b/packages/core/src/schemas/api/metrics.test.ts
index 7cbd36a21..b0e7d067e 100644
--- a/packages/core/src/schemas/api/metrics.test.ts
+++ b/packages/core/src/schemas/api/metrics.test.ts
@@ -7,6 +7,7 @@ import {
AgentBurstDiffSuccessSchema,
AgentPresenceEntrySchema,
InstalledAgentsSuccessSchema,
+ MetricsAgentEffectsSuccessSchema,
MetricsAgentPresenceSuccessSchema,
MetricsParseHealthSuccessSchema,
MetricsReconciliationSuccessSchema,
@@ -326,6 +327,49 @@ describe('MetricsAgentPresenceSuccessSchema', () => {
});
});
+describe('MetricsAgentEffectsSuccessSchema', () => {
+ test('parses an empty effects list', () => {
+ expect(MetricsAgentEffectsSuccessSchema.safeParse({ effects: [] }).success).toBe(true);
+ });
+ test('parses a populated per-doc block with summarized entries', () => {
+ expect(
+ MetricsAgentEffectsSuccessSchema.safeParse({
+ effects: [
+ {
+ 'doc.name': 'meetings/standup',
+ entries: [
+ {
+ sessionId: 'agent-a1',
+ agentType: 'claude',
+ ts: 1,
+ insertedChars: 12,
+ deletedChars: 0,
+ },
+ ],
+ },
+ ],
+ }).success,
+ ).toBe(true);
+ });
+ test('rejects body missing effects field', () => {
+ expect(MetricsAgentEffectsSuccessSchema.safeParse({}).success).toBe(false);
+ });
+ test('rejects a negative character count', () => {
+ expect(
+ MetricsAgentEffectsSuccessSchema.safeParse({
+ effects: [
+ {
+ 'doc.name': 'a',
+ entries: [
+ { sessionId: 's', agentType: 't', ts: 1, insertedChars: -1, deletedChars: 0 },
+ ],
+ },
+ ],
+ }).success,
+ ).toBe(false);
+ });
+});
+
describe('InstalledAgentsSuccessSchema', () => {
test('parses a populated boolean record', () => {
expect(
diff --git a/packages/core/src/schemas/api/metrics.ts b/packages/core/src/schemas/api/metrics.ts
index a836262f7..c9076e4ea 100644
--- a/packages/core/src/schemas/api/metrics.ts
+++ b/packages/core/src/schemas/api/metrics.ts
@@ -1,10 +1,11 @@
/**
* metrics + agent activity + test handlers.
*
- * Eight handlers — `handleAgentActivity`, `handleAgentBurstDiff`,
+ * Nine handlers — `handleAgentActivity`, `handleAgentBurstDiff`,
* `handleTestReset`, `handleTestRescanBacklinks`,
* `handleMetricsReconciliation`, `handleMetricsParseHealth`,
- * `handleMetricsAgentPresence`, `handleInstalledAgentsRoute`. No new URN
+ * `handleMetricsAgentPresence`, `handleMetricsAgentEffects`,
+ * `handleInstalledAgentsRoute`. No new URN
* tokens — every error path reuses existing tokens (`invalid-request`,
* `reserved-doc-name`, `no-active-session`, `not-found`, `loopback-required`,
* `host-not-allowed`, `invalid-origin`, `method-not-allowed`,
@@ -166,6 +167,51 @@ export const MetricsAgentPresenceSuccessSchema = z
.loose() satisfies StandardSchemaV1;
export type MetricsAgentPresenceSuccess = z.infer<typeof MetricsAgentPresenceSuccessSchema>;
+/**
+ * One summarized agent-effects ring-buffer entry on
+ * `MetricsAgentEffectsSuccessSchema.effects[].entries`. Deltas are reduced to
+ * character counts — the diagnostic signal is who wrote how much to which doc
+ * and when; the raw delta text (user content) never leaves the live doc via
+ * this endpoint.
+ */
+export const AgentEffectEntrySchema = z
+ .object({
+ sessionId: z.string().min(1),
+ agentType: z.string().min(1),
+ ts: z.number().int().min(0),
+ insertedChars: z.number().int().min(0),
+ deletedChars: z.number().int().min(0),
+ })
+ .loose() satisfies StandardSchemaV1;
+export type AgentEffectEntryWire = z.infer<typeof AgentEffectEntrySchema>;
+
+/**
+ * One per-doc block on `MetricsAgentEffectsSuccessSchema.effects`. The doc
+ * name is carried under the literal key `doc.name` — the same key the
+ * diagnostics-bundle redactor hashes — so a staged copy of this response is
+ * anonymized by the existing pass without a redactor change.
+ */
+export const AgentEffectsDocSchema = z
+ .object({
+ 'doc.name': z.string().min(1),
+ entries: z.array(AgentEffectEntrySchema),
+ })
+ .loose() satisfies StandardSchemaV1;
+export type AgentEffectsDocWire = z.infer<typeof AgentEffectsDocSchema>;
+
+/**
+ * Success response for `GET /api/metrics/agent-effects`. Aggregates the
+ * bounded per-doc `agent-effects` ring buffers across currently-loaded docs
+ * (never force-loads unloaded ones). Loopback + Host-allowlist gated like
+ * `/api/metrics/agent-presence`.
+ */
+export const MetricsAgentEffectsSuccessSchema = z
+ .object({
+ effects: z.array(AgentEffectsDocSchema),
+ })
+ .loose() satisfies StandardSchemaV1;
+export type MetricsAgentEffectsSuccess = z.infer<typeof MetricsAgentEffectsSuccessSchema>;
+
/**
* Success response for `GET /api/installed-agents`. Returns a flat boolean
* record keyed by agent scheme name (`claude` / `codex` / `cursor`). The
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index 4cefaaec8..6a70a0226 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -128,6 +128,8 @@ import {
MANAGED_ARTIFACT_PREFIX_SKILL,
MANAGED_ARTIFACT_PREFIX_TEMPLATE,
MarkdownlintRuleWriteRequestSchema,
+ type MetricsAgentEffectsSuccess,
+ MetricsAgentEffectsSuccessSchema,
MetricsAgentPresenceSuccessSchema,
MetricsParseHealthSuccessSchema,
MetricsReconciliationSuccessSchema,
@@ -251,7 +253,7 @@ import busboy from 'busboy';
import { fileTypeFromBuffer } from 'file-type';
import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
import { z } from 'zod';
-import { captureEffect } from './activity-log.ts';
+import { captureEffect, type EffectValue } 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';
@@ -8784,6 +8786,92 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
}
}
+ 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 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
@@ -17707,6 +17795,21 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
async (_req, res, body) => {
try {
const logger = getLogger('renderer');
+ if (body.droppedSinceLastFlush !== undefined && body.droppedSinceLastFlush > 0) {
+ // Gap marker: the forwarder lost entries (buffer overflow / failed
+ // POSTs) between the previous delivered batch and this one. Persist
+ // it as its own line so a log reader knows the silence was loss,
+ // not inactivity.
+ logger.warn(
+ {
+ source: 'renderer-console',
+ transport: 'web',
+ event: 'client-log-entries-dropped',
+ droppedSinceLastFlush: body.droppedSinceLastFlush,
+ },
+ 'client-log-entries-dropped',
+ );
+ }
for (const entry of body.entries) {
// Per-entry guard: one entry that trips a pino serialization fault
// must not drop the rest of the batch (the response still reports the
@@ -18633,6 +18736,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
'/api/metrics/reconciliation': handleMetricsReconciliation,
'/api/metrics/parse-health': handleMetricsParseHealth,
'/api/metrics/agent-presence': handleMetricsAgentPresence,
+ '/api/metrics/agent-effects': handleMetricsAgentEffects,
'/api/__embed-detect': handleEmbedDetect,
'/api/server-info': handleServerInfo,
'/api/share/construct-url': handleShareConstructUrl,
diff --git a/packages/server/src/server-observers.ts b/packages/server/src/server-observers.ts
index 85e2bb9be..d7081b90c 100644
--- a/packages/server/src/server-observers.ts
+++ b/packages/server/src/server-observers.ts
@@ -60,6 +60,7 @@ import {
} from './bridge-watchdog.ts';
import { isConfigDoc, isSystemDoc } from './cc1-broadcast.ts';
import { recordFrontmatterEditSurface } from './frontmatter-telemetry.ts';
+import { getLogger } from './logger.ts';
import { computeMapDrivenBodySplice } from './map-driven-splice.ts';
import {
incrementBridgeMergeCheckpointCreated,
@@ -81,6 +82,14 @@ import {
import { type ShadowHandle, saveInMemoryCheckpoint } from './shadow-repo.ts';
import { setActiveSpanAttributes, withSpanSync } from './telemetry.ts';
+/**
+ * Pino line for checkpoint-write failures, alongside the existing
+ * console.warn: a failed checkpoint means the recovery snapshot for a
+ * detected content-loss event was NOT persisted, and the pino sink is what
+ * reaches the local log files (and, through them, diagnostics bundles).
+ */
+const checkpointLog = getLogger('server-observers');
+
// ─────────────────────────────────────────────────────────────
// Origin constant
// ─────────────────────────────────────────────────────────────
@@ -675,6 +684,10 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
message: err.message,
stack: err.stack?.split('\n').slice(0, 4).join('\n'),
});
+ checkpointLog.warn(
+ { err, 'doc.name': opts.docName ?? null, branch, kind: 'bridge-merge-loss' },
+ 'checkpoint write failed',
+ );
});
});
};
@@ -759,6 +772,10 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
message: e.message,
stack: e.stack?.split('\n').slice(0, 4).join('\n'),
});
+ checkpointLog.warn(
+ { err: e, 'doc.name': docName, branch, kind: 'observer-a-duplication' },
+ 'checkpoint write failed',
+ );
});
});
};
@@ -1100,6 +1117,10 @@ export function setupServerObservers(opts: SetupServerObserversOpts): () => void
message: e.message,
stack: e.stack?.split('\n').slice(0, 4).join('\n'),
});
+ checkpointLog.warn(
+ { err: e, 'doc.name': docName, branch, kind: 'producer-guard-loss' },
+ 'checkpoint write failed',
+ );
});
});
};