Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

PRD-8404: Move agent-write CRDT routes to native HTTP (#4381)

omar-inkeep36049a393d5d
diff --git a/packages/app/tests/integration/attribution-sweep-coverage.test.ts b/packages/app/tests/integration/attribution-sweep-coverage.test.ts
index 7dac8f0d1..ca67438ff 100644
--- a/packages/app/tests/integration/attribution-sweep-coverage.test.ts
+++ b/packages/app/tests/integration/attribution-sweep-coverage.test.ts
@@ -136,6 +136,8 @@ const EXEMPT_HANDLERS = new Set([
'handleLocalOpEmbeddingsClearKey',
'handleLocalOpEmbeddingsTest',
'handleTestReset',
+ 'handleTestRescanBacklinks',
+ 'handleTestRescanFiles',
'handleTestFlushGit',
'handlePrincipal',
'handleInstalledAgentsRoute',
diff --git a/packages/app/tests/integration/conflict-gate-coverage.test.ts b/packages/app/tests/integration/conflict-gate-coverage.test.ts
index 8292133fa..72dfa0aea 100644
--- a/packages/app/tests/integration/conflict-gate-coverage.test.ts
+++ b/packages/app/tests/integration/conflict-gate-coverage.test.ts
@@ -156,6 +156,7 @@ const EXEMPT_HANDLERS = new Set([
'handleSyncResolveBlocking',
'handleShareTargetStatus',
'handleTestReset',
+ 'handleTestFlushGit',
'handleTestRescanBacklinks',
'handleTestRescanFiles',
'handleSaveVersion',
diff --git a/packages/server/src/agent-write-loss-detect-coverage.test.ts b/packages/server/src/agent-write-loss-detect-coverage.test.ts
index 50bc64940..d3ee4833f 100644
--- a/packages/server/src/agent-write-loss-detect-coverage.test.ts
+++ b/packages/server/src/agent-write-loss-detect-coverage.test.ts
@@ -4,7 +4,11 @@ import { Node, Project, SyntaxKind } from 'ts-morph';
import { describe, expect, it } from 'vitest';
const here = dirname(fileURLToPath(import.meta.url));
-const SPINE_FILES = [join(here, 'api-extension.ts'), join(here, 'acp', 'thread-manager.ts')];
+const SPINE_FILES = [
+ join(here, 'api-extension.ts'),
+ join(here, 'http', 'agent-write-routes.ts'),
+ join(here, 'acp', 'thread-manager.ts'),
+];
function newProject(): Project {
return new Project({
diff --git a/packages/server/src/agent-write-pre-drain-coverage.test.ts b/packages/server/src/agent-write-pre-drain-coverage.test.ts
index 9b3e9ec74..204fa4ebc 100644
--- a/packages/server/src/agent-write-pre-drain-coverage.test.ts
+++ b/packages/server/src/agent-write-pre-drain-coverage.test.ts
@@ -4,7 +4,11 @@ import { Node, Project, SyntaxKind } from 'ts-morph';
import { describe, expect, it } from 'vitest';
const here = dirname(fileURLToPath(import.meta.url));
-const SPINE_FILES = [join(here, 'api-extension.ts'), join(here, 'acp', 'thread-manager.ts')];
+const SPINE_FILES = [
+ join(here, 'api-extension.ts'),
+ join(here, 'http', 'agent-write-routes.ts'),
+ join(here, 'acp', 'thread-manager.ts'),
+];
const FULL_BODY_OVERWRITE = new Set(['replace', 'patch']);
diff --git a/packages/server/src/api-agent-write-composition.test.ts b/packages/server/src/api-agent-write-composition.test.ts
new file mode 100644
index 000000000..f5121f9c9
--- /dev/null
+++ b/packages/server/src/api-agent-write-composition.test.ts
@@ -0,0 +1,132 @@
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, beforeAll, expect, test } from 'vitest';
+import type { BootedServer } from './boot.ts';
+import { bootCompositionRig, rawRequest } from './composition-rig.test-helper.ts';
+import { __formatContributorsForTests } from './contributor-tracker.ts';
+
+let root: string;
+let server: BootedServer;
+
+beforeAll(async () => {
+ root = mkdtempSync(join(tmpdir(), 'ok-agent-write-composition-'));
+ server = await bootCompositionRig(root);
+ await server.ready;
+}, 60_000);
+
+afterAll(async () => {
+ await server?.destroy();
+ rmSync(root, { recursive: true, force: true });
+});
+
+async function request(path: string, body?: object) {
+ const response = await rawRequest(server.port, path, {
+ method: body === undefined ? 'GET' : 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+ });
+ expect(response.status, response.body).toBe(200);
+ return JSON.parse(response.body);
+}
+
+test('write, patch, activity, diff and undo share the live session and preserve disk bytes', async () => {
+ const docName = 'native-spine';
+ const agentId = 'spine-writer';
+ const markdown = '# Exact bytes\n\nBackslash \\* and <custom>raw</custom>.\n\n';
+ await request('/api/agent-write-md', { docName, agentId, markdown, position: 'replace' });
+ const session = await server.serverInstance.sessionManager.getSession(
+ docName,
+ `agent-${agentId}`,
+ );
+ expect(session.dc.document.getText('source').toString()).toBe(markdown);
+ expect(readFileSync(join(root, `${docName}.md`), 'utf8')).toBe(markdown);
+ session.um.stopCapturing();
+ const origins: unknown[] = [];
+ const observe = (event: { transaction: { origin: unknown } }) =>
+ origins.push(event.transaction.origin);
+ session.dc.document.getText('source').observe(observe);
+ try {
+ await request('/api/agent-patch', {
+ docName,
+ agentId,
+ find: 'Exact bytes',
+ replace: 'Changed bytes',
+ });
+ expect(origins).toContain(session.origin);
+ expect(readFileSync(join(root, `${docName}.md`), 'utf8')).toBe(
+ markdown.replace('Exact bytes', 'Changed bytes'),
+ );
+ const activity = await request(`/api/agent-activity?agentId=agent-${agentId}`);
+ expect(JSON.stringify(activity)).toContain(docName);
+ const diff = await request(
+ `/api/agent-burst-diff?agentId=agent-${agentId}&docName=${docName}&keptCount=${session.um.undoStack.length}`,
+ );
+ expect(diff.before).toBe('');
+ expect(diff.after).toBe(markdown.replace('Exact bytes', 'Changed bytes'));
+ const undone = await request('/api/agent-undo', {
+ docName,
+ agentId,
+ connectionId: `agent-${agentId}`,
+ scope: 'last',
+ });
+ expect(undone.undone).toBe(true);
+ expect(session.dc.document.getText('source').toString()).toBe(markdown);
+ expect(readFileSync(join(root, `${docName}.md`), 'utf8')).toBe(markdown);
+ } finally {
+ session.dc.document.getText('source').unobserve(observe);
+ }
+});
+
+test('frontmatter patch preserves the existing body bytes', async () => {
+ const docName = 'native-frontmatter';
+ const body = '\nBody \\* <custom>raw</custom>.\n\n';
+ await request('/api/agent-write-md', {
+ docName,
+ agentId: 'fm',
+ markdown: `---\ntitle: Before\n---\n${body}`,
+ position: 'replace',
+ });
+ const result = await request('/api/frontmatter-patch', {
+ docName,
+ agentId: 'fm',
+ patch: { title: 'After' },
+ });
+ expect(result.appliedKeys).toEqual(['title']);
+ expect(readFileSync(join(root, `${docName}.md`), 'utf8')).toBe(`---\ntitle: After\n---\n${body}`);
+});
+
+test('save and rollback retain shadow history and the principal loaded after route construction', async () => {
+ const docName = 'native-version';
+ const markdown = '# Saved version\n\nExact \\* bytes.\n';
+ await request('/api/agent-write-md', {
+ docName,
+ agentId: 'version-writer',
+ markdown,
+ position: 'replace',
+ });
+ const saved = await request('/api/save-version', {
+ agentId: 'version-writer',
+ summary: 'Checkpoint',
+ });
+ const commitSha = saved.checkpointRef.split('/').at(-1);
+ expect(commitSha).toMatch(/^[a-f0-9]{40}$/);
+ await request('/api/agent-write-md', {
+ docName,
+ agentId: 'version-writer',
+ markdown: '# Changed\n',
+ position: 'replace',
+ });
+ const principal = await request('/api/principal');
+ expect(principal.id).toBeTruthy();
+ const rolledBack = await request('/api/rollback', {
+ docName,
+ commitSha,
+ principalId: 'forged-principal',
+ summary: 'Restore saved version',
+ });
+ expect(rolledBack.restoredFrom).toBe(commitSha);
+ expect(readFileSync(join(root, `${docName}.md`), 'utf8')).toBe(markdown);
+ expect(__formatContributorsForTests()).toContain(principal.id);
+ expect(__formatContributorsForTests()).not.toContain('forged-principal');
+});
diff --git a/packages/server/src/api-agent-write-extension.test.ts b/packages/server/src/api-agent-write-extension.test.ts
index 2f2ef0d38..18d118401 100644
--- a/packages/server/src/api-agent-write-extension.test.ts
+++ b/packages/server/src/api-agent-write-extension.test.ts
@@ -46,7 +46,9 @@ async function postAgentWriteMd(
if (!apiExt?.onRequest) throw new Error('API extension (priority 100) not found on server');
const req = makeJsonPostReq('/api/agent-write-md', body);
const { res, captured } = makeRes();
- await apiExt.onRequest({ request: req, response: res });
+ if (!(await server.nativeApi.dispatch(req, res))) {
+ await apiExt.onRequest({ request: req, response: res });
+ }
return captured.status;
}
diff --git a/packages/server/src/api-agent-write-native-preservation.test.ts b/packages/server/src/api-agent-write-native-preservation.test.ts
new file mode 100644
index 000000000..612a01a5e
--- /dev/null
+++ b/packages/server/src/api-agent-write-native-preservation.test.ts
@@ -0,0 +1,183 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, beforeAll, expect, test } from 'vitest';
+import type { BootedServer } from './boot.ts';
+import { bootCompositionRig, parseProblem, rawRequest } from './composition-rig.test-helper.ts';
+
+const READS = ['/api/agent-activity', '/api/agent-burst-diff'];
+const WRITES = [
+ '/api/agent-write-md',
+ '/api/frontmatter-patch',
+ '/api/agent-patch',
+ '/api/agent-undo',
+ '/api/save-version',
+ '/api/rollback',
+];
+const TEST_PATHS = [
+ '/api/test-reset',
+ '/api/test-flush-git',
+ '/api/test-rescan-backlinks',
+ '/api/test-rescan-files',
+];
+const RESIDUAL = [
+ '/api/asset',
+ '/api/asset-text',
+ '/api/skill/uninstall',
+ '/api/agent-write',
+ '/api/agent-write-batch',
+ '/api/lint/markdownlint-config',
+ '/api/lint/frontmatter-schema',
+ '/api/lint/fix',
+ '/api/agent-integrations/apply',
+];
+let root: string;
+let enabled: BootedServer;
+let disabled: BootedServer;
+let ephemeral: BootedServer;
+
+beforeAll(async () => {
+ root = mkdtempSync(join(tmpdir(), 'ok-agent-native-preservation-'));
+ for (const name of ['enabled', 'disabled', 'ephemeral']) mkdirSync(join(root, name));
+ writeFileSync(join(root, 'ephemeral', 'note.md'), '# Note\n');
+ enabled = await bootCompositionRig(join(root, 'enabled'), { enableTestRoutes: true });
+ disabled = await bootCompositionRig(join(root, 'disabled'));
+ ephemeral = await bootCompositionRig(join(root, 'ephemeral'), {
+ ephemeral: true,
+ singleDocRelPath: 'note.md',
+ });
+ await Promise.all([enabled.ready, disabled.ready, ephemeral.ready]);
+}, 60_000);
+
+afterAll(async () => {
+ await Promise.allSettled([enabled?.destroy(), disabled?.destroy(), ephemeral?.destroy()]);
+ rmSync(root, { recursive: true, force: true });
+});
+
+test('native ownership is exclusive and the remaining legacy registry matches its explicit owners', () => {
+ for (const server of [enabled, disabled]) {
+ for (const path of [...READS, ...WRITES])
+ expect(server.serverInstance.nativeApi.paths.filter((entry) => entry === path)).toHaveLength(
+ 1,
+ );
+ for (const path of RESIDUAL) expect(server.serverInstance.nativeApi.paths).not.toContain(path);
+ }
+ for (const path of TEST_PATHS) {
+ expect(enabled.serverInstance.nativeApi.paths).toContain(path);
+ expect(disabled.serverInstance.nativeApi.paths).not.toContain(path);
+ }
+ const source = readFileSync(new URL('./api-extension.ts', import.meta.url), 'utf8');
+ const registry = source.match(/const routes:[\s\S]*?= (\{[\s\S]*?\n {2}\});/)?.[1];
+ expect(registry).toBeDefined();
+
+ expect(
+ [...(registry?.matchAll(/'([^']*\/api\/[^']*)'/g) ?? [])].map((match) => match[1]).sort(),
+ ).toEqual([...RESIDUAL].sort());
+});
+
+test('ingress rejects every migrated route before method or malformed-body admission', async () => {
+ for (const path of [...READS, ...WRITES, ...TEST_PATHS]) {
+ for (const [headers, type] of [
+ [{ Host: 'evil.example' }, 'urn:ok:error:host-not-allowed'],
+ [{ Origin: 'https://evil.example' }, 'urn:ok:error:invalid-origin'],
+ [{ 'X-Forwarded-For': '127.0.0.1' }, 'urn:ok:error:host-not-allowed'],
+ ] as const) {
+ const response = await rawRequest(enabled.port, path, {
+ method: 'PATCH',
+ headers,
+ body: '{',
+ });
+ expect(response.status, `${path}: ${response.body}`).toBe(403);
+ expect(response.headers.allow).toBeUndefined();
+ expect(parseProblem(response.body).type).toBe(type);
+ }
+ }
+});
+
+test('methods, preflight, HEAD and request IDs retain the transport contracts', async () => {
+ for (const path of [...READS, ...WRITES, ...TEST_PATHS]) {
+ const allowed = READS.includes(path) ? 'GET' : 'POST';
+ const wrong = await rawRequest(enabled.port, path, {
+ method: 'PATCH',
+ headers: { 'X-Request-Id': 'spine-method' },
+ body: '{',
+ });
+ expect(wrong.status, `${path}: ${wrong.body}`).toBe(405);
+ expect(wrong.headers.allow).toBe(allowed);
+ expect(wrong.headers['x-request-id']).toBe('spine-method');
+ expect(parseProblem(wrong.body).type).toBe('urn:ok:error:method-not-allowed');
+ const head = await rawRequest(enabled.port, path, { method: 'HEAD' });
+ expect(head.status, path).toBe(405);
+ expect(head.body).toBe('');
+ const preflight = await rawRequest(enabled.port, path, { method: 'OPTIONS' });
+ expect(preflight.status, path).toBe(204);
+ }
+});
+
+test('disabled test routes retain unknown-path admission, in ephemeral servers', async () => {
+ for (const path of TEST_PATHS) {
+ const unknown = await rawRequest(disabled.port, path, { method: 'POST', body: '{' });
+ expect(unknown.status, unknown.body).toBe(404);
+ expect(parseProblem(unknown.body).type).toBe('urn:ok:error:not-found');
+ const rejected = await rawRequest(disabled.port, path, {
+ method: 'POST',
+ headers: { Origin: 'https://evil.example' },
+ body: '{',
+ });
+ expect(rejected.status).toBe(403);
+ expect(parseProblem(rejected.body).type).toBe('urn:ok:error:invalid-origin');
+ const restricted = await rawRequest(ephemeral.port, path, { method: 'POST', body: '{' });
+ expect(restricted.status, restricted.body).toBe(404);
+ }
+ for (const path of WRITES) {
+ const response = await rawRequest(ephemeral.port, path, { method: 'POST', body: '{' });
+ expect(response.status, `${path}: ${response.body}`).toBe(400);
+ }
+ for (const path of READS) {
+ const response = await rawRequest(ephemeral.port, path);
+ expect(response.status, `${path}: ${response.body}`).toBe(400);
+ }
+});
+
+test('enabled reset and rescans execute against real sessions, files and indexes', async () => {
+ const docName = 'reset-spine';
+ const write = await rawRequest(enabled.port, '/api/agent-write-md', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({
+ docName,
+ markdown: '# Reset me\n',
+ agentId: 'reset',
+ position: 'replace',
+ }),
+ });
+ expect(write.status, write.body).toBe(200);
+ expect(enabled.serverInstance.sessionManager.hasSession(docName, 'agent-reset')).toBe(true);
+ const reset = await rawRequest(
+ enabled.port,
+ `/api/test-reset?docName=${docName}&reset-okignore=false`,
+ { method: 'POST', body: '{' },
+ );
+ expect(reset.status, reset.body).toBe(200);
+ expect(enabled.serverInstance.sessionManager.hasSession(docName, 'agent-reset')).toBe(false);
+ expect(readFileSync(join(root, 'enabled', `${docName}.md`), 'utf8')).toBe('');
+ writeFileSync(
+ join(root, 'enabled', 'discovered.md'),
+ '# Discovered\n\n[Reset](reset-spine.md)\n',
+ );
+ for (const path of [
+ '/api/test-rescan-files',
+ '/api/test-rescan-backlinks',
+ '/api/test-flush-git',
+ ]) {
+ const response = await rawRequest(enabled.port, path, { method: 'POST', body: '{' });
+ expect(response.status, `${path}: ${response.body}`).toBe(200);
+ expect(JSON.parse(response.body)).toEqual({});
+ }
+ const files = await rawRequest(enabled.port, '/api/documents');
+ expect(files.status, files.body).toBe(200);
+ expect(files.body).toContain('discovered');
+ const backlinks = await rawRequest(enabled.port, '/api/backlinks?docName=reset-spine');
+ expect(backlinks.status, backlinks.body).toBe(200);
+ expect(backlinks.body).toContain('discovered');
+});
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index 6b7fa4a60..6fb09532e 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -1,3 +1,8 @@
+import { createAgentWriteRoutes } from './http/agent-write-routes.ts';
+import { createTestRoutes } from './http/test-routes.ts';
+
+export { ROLLBACK_ORIGIN } from './http/agent-write-routes.ts';
+
import { randomUUID } from 'node:crypto';
import {
createReadStream,
@@ -8,7 +13,6 @@ import {
readFileSync,
realpathSync,
statSync,
- writeFileSync,
} from 'node:fs';
import { readdir, readFile, realpath, stat } from 'node:fs/promises';
import type { IncomingMessage, ServerResponse } from 'node:http';
@@ -21,36 +25,22 @@ import {
type AdvisoryWarning,
AGENT_ICON_COLORS,
AGENTS_SKILLS_ROOT,
- AgentActivitySuccessSchema,
- AgentBurstDiffSuccessSchema,
AgentIntegrationsApplyRequestSchema,
AgentIntegrationsApplySuccessSchema,
- AgentPatchRequestSchema,
- AgentPatchSuccessSchema,
- AgentUndoRequestSchema,
- AgentUndoSuccessSchema,
AgentWriteBatchRequestSchema,
AgentWriteBatchSuccessSchema,
- AgentWriteMdRequestSchema,
- AgentWriteMdSuccessSchema,
AgentWriteRequestSchema,
AgentWriteSuccessSchema,
- applyPatchToFm,
type BatchEntryError,
- CONFIG_DOC_NAME_OKIGNORE,
type ConfigDiagnosticsReport,
changedBlockRange,
colorFromSeed,
- composeWithDerivedFrontmatter,
createCodeFenceTracker,
DEFAULT_LINTER_CONFIG,
type DiskEditReconciledWarning,
type DocumentListEntry,
- detectFmRegion,
EmptyRequestSchema,
estimateSkillCost,
- FrontmatterPatchRequestSchema,
- FrontmatterPatchSuccessSchema,
FrontmatterSchemaWriteRequestSchema,
type HeadingEntry,
type InlineAssetMediaKind,
@@ -72,31 +62,18 @@ import {
type Principal,
type ProblemType,
parseFrontmatterRecord,
- prependFrontmatter,
type ReLintFailure,
- RollbackRequestSchema,
- RollbackSuccessSchema,
readFmMap,
- SaveVersionRequestSchema,
- SaveVersionSuccessSchema,
SKILL_NAME_REGEX,
SkillScopeSchema,
SkillUninstallRequestSchema,
SkillUninstallSuccessSchema,
- SYSTEM_DOC_NAME,
scanHeadingLine,
stripFrontmatter,
summarizeLintPluginFailures,
- TestFlushGitSuccessSchema,
- TestRescanBacklinksSuccessSchema,
- TestRescanFilesSuccessSchema,
- TestResetSuccessSchema,
type ValidationDiagnostic,
} from '@inkeep/open-knowledge-core';
-import {
- formatRenameSubject,
- formatRollbackSubject,
-} from '@inkeep/open-knowledge-core/shadow-repo-layout';
+import { formatRenameSubject } from '@inkeep/open-knowledge-core/shadow-repo-layout';
import {
parseSkillDir,
pluginRepositoryUrl,
@@ -108,7 +85,6 @@ import {
} from './acp/harness-availability.ts';
import type { AcpRegistry, CustomAgentEntry } from './acp/registry.ts';
import { captureEffect } from './activity-log.ts';
-import { listAgentActivity, synthesizeVersionDiff } from './agent-activity.ts';
import type { AgentFocusBroadcaster } from './agent-focus.ts';
import type { AgentPresenceBroadcaster } from './agent-presence.ts';
import { type AgentRegistryHostSeam, applyAgentRegistryIntents } from './agent-registry-apply.ts';
@@ -120,10 +96,8 @@ import {
agentWriteLossDetect,
agentWritePreDrain,
applyAgentMarkdownWrite,
- applyAgentUndo,
iconFromClientName,
prepareAgentMarkdownParse,
- prepareFrontmatterPatchParse,
snapshotBlocks,
} from './agent-sessions.ts';
import {
@@ -135,17 +109,13 @@ import { resolveBundledSkillDir } from './build-skill-zip.ts';
import { CommentIndex } from './comments/comment-index.ts';
import { CommentService } from './comments/comment-service.ts';
import { CommentThreadStore } from './comments/thread-store.ts';
-import { CONFIG_VALIDATION_REVERT_ORIGIN } from './config-edit-origin.ts';
import {
DocInConflictError,
isDocInConflict,
RESOLUTION_OPTIONS,
respondDocInConflict,
} from './conflict-errors.ts';
-import {
- evaluateContentDivergence,
- toContentDivergenceWarning,
-} from './content-divergence-gate.ts';
+import { toContentDivergenceWarning } from './content-divergence-gate.ts';
import { recordContributor } from './contributor-tracker.ts';
import type { ResolvedSemanticConfig, SemanticSearchService } from './embeddings/index.ts';
import {
@@ -194,7 +164,6 @@ import {
resolveNativeConfigForDoc,
} from './lint/resolve-config.ts';
import { createProjectValidators } from './lint/validation-audit.ts';
-import { validateMermaidFences } from './mermaid-validator.ts';
import {
extractPageTitle,
type FrontmatterMetadata,
@@ -220,7 +189,7 @@ import { createSkillsCatalogCache } from './skills-catalog-cache.ts';
export { extractPageTitle } from './page-identity.ts';
import simpleGit from 'simple-git';
-import { parseAgentBodyFields, resolveAgentType, validateAgentId } from './agent-id.ts';
+import { parseAgentBodyFields, resolveAgentType } from './agent-id.ts';
import {
applyRenameMap,
BacklinkIndexRequiredError,
@@ -233,7 +202,7 @@ import {
ManagedRenameSourceNotFoundError,
ManagedRenameSourceTypeMismatchError,
} from './apply-managed-rename.ts';
-import { composeAndWriteRawBody, type PrecomputedParse, replaceRawBody } from './bridge-intake.ts';
+import { composeAndWriteRawBody } from './bridge-intake.ts';
import type { BridgeDeriveLossReporter } from './bridge-loss-detector.ts';
import { isConfigDoc, isLinkIndexExcludedDoc, isSystemDoc } from './cc1-broadcast.ts';
import type { ResolveStrategy } from './conflict-storage.ts';
@@ -249,7 +218,6 @@ import {
isDerivedDocumentIndexClosedError,
} from './derived-document-index.ts';
import {
- canonicalDocName,
docNameToRelativePath,
extensionlessDocTreePath,
forgetDocExtension,
@@ -275,7 +243,6 @@ import {
updateFileIndex,
upsertFolderIndexEntry as upsertFolderIndexEntryInIndex,
} from './file-watcher.ts';
-import { recordFrontmatterEditSurface } from './frontmatter-telemetry.ts';
import {
tracedCpSync,
tracedMkdirSync,
@@ -354,20 +321,15 @@ import {
} from './managed-rename-journal.ts';
import { rewriteAssetReferencesForRename } from './managed-rename-rewrite.ts';
import {
- incrementAgentPatchFindMismatches,
incrementAgentWriteCalls,
incrementSummariesProvided,
incrementSummariesTruncated,
} from './metrics.ts';
-
-import { precomputeParse } from './parse-pool.ts';
import { isWithinDir, toPosix } from './path-utils.ts';
import {
appendRenameLogEntry,
- createAncestorShaSetCache,
getOrLoadRenameLogIndex,
type RenameLogEntry,
- resolveDocPathAtCommit,
} from './rename-log.ts';
import type { PairedWriteOrigin } from './server-observers.ts';
import { createAssetService } from './services/assets.ts';
@@ -377,14 +339,7 @@ import { createSkillImportService } from './services/skill-import.ts';
import { createSkillInstallOpsService } from './services/skill-install-ops.ts';
import { createSkillPlacementOpsService } from './services/skill-placement-ops.ts';
import { createSkillReimportService } from './services/skill-reimport.ts';
-import { createVersionOpsService } from './services/version-ops.ts';
-import {
- SERVICE_WRITER,
- type ShadowRef,
- safetyCheckpoint,
- shadowGit,
- type WriterIdentity,
-} from './shadow-repo.ts';
+import { SERVICE_WRITER, type ShadowRef, shadowGit } from './shadow-repo.ts';
import { readSkillInstallModeRaw } from './skill-placements.ts';
@@ -392,28 +347,6 @@ import type { SyncEngine } from './sync-engine.ts';
import { getMeter, withSpan, withSpanSync } from './telemetry.ts';
import { computeWriteAdvisoryLinks } from './write-advisory-links.ts';
-let _hintEmittedCounter: ReturnType<ReturnType<typeof getMeter>['createCounter']> | null = null;
-function hintEmittedCounter(): ReturnType<ReturnType<typeof getMeter>['createCounter']> {
- _hintEmittedCounter ||= getMeter().createCounter('ok.preview_attach.hint_emitted', {
- description:
- 'Count of preview-attach hints emitted on write-tool responses when no editor is attached to __system__. Covers both attach-preview-once (URL exists, no browser) and start-ui (no UI running anywhere) variants — the tool side disambiguates via the warning action; the metric name is retained as-is so existing dashboards keep working.',
- });
- return _hintEmittedCounter;
-}
-
-let _agentPatchFmTouchCounter: ReturnType<ReturnType<typeof getMeter>['createCounter']> | null =
- null;
-function agentPatchFmTouchCounter(): ReturnType<ReturnType<typeof getMeter>['createCounter']> {
- _agentPatchFmTouchCounter ||= getMeter().createCounter(
- 'ok.frontmatter.agent_patch_fm_touch_total',
- {
- description:
- 'Count of agent-patch calls refused for touching the frontmatter region. Bounded labels: result ∈ {rejected, pre_deprecation_passthrough}, reason ∈ {intersect, promoted}. `intersect` is a find that MATCHED inside the existing frontmatter; `promoted` is a byte-0 replace that would CREATE frontmatter on a document that had none. They refuse for opposite reasons, so a spike in one says nothing about the other — the append/prepend surface separates the same pair via the `byte-0-promotion` class on `frontmatter-malformed-write-refused`.',
- },
- );
- return _agentPatchFmTouchCounter;
-}
-
let _renameAttributionCounter: ReturnType<ReturnType<typeof getMeter>['createCounter']> | null =
null;
function renameAttributionCounter(): ReturnType<ReturnType<typeof getMeter>['createCounter']> {
@@ -469,12 +402,6 @@ export function __resetRenameTelemetryForTesting(): void {
_renameAttributionCounter = null;
}
-export const ROLLBACK_ORIGIN = {
- source: 'local' as const,
- skipStoreHooks: false,
- context: { origin: 'rollback-apply', paired: true },
-} as const satisfies PairedWriteOrigin;
-
/**
* Exported so the bridge-invariant watcher can enforce by identity (precedent #1) and so server
* observers can resolve `context.paired` without importing the object transitively.
@@ -547,7 +474,7 @@ export async function healUnservableSkillAdmission(
state: SkillAdmissionHealState,
): Promise<boolean> {
if (!filter) return false;
- const key = [...paths].sort().join('');
+ const key = [...paths].sort().join('\0');
if (key === state.lastKey) return false;
state.lastKey = key;
if (!paths.some((p) => filter.isExcluded(p))) return false;
@@ -1772,24 +1699,6 @@ export function createApiExtension(
return getAliasMap?.().get(docName) ?? docName;
}
- function getSubscriberCount(docName: string): number {
- try {
- const doc = hocuspocus.documents.get(docName);
- return doc?.connections.size ?? 0;
- } catch {
- return 0;
- }
- }
-
- function getSystemSubscriberCount(): number {
- try {
- const doc = hocuspocus.documents.get(SYSTEM_DOC_NAME);
- return doc?.connections.size ?? 0;
- } catch {
- return 0;
- }
- }
-
function flushDocToGit(docName: string, label: string): void {
const debounceId = `onStoreDocument-${docName}`;
const l1 = hocuspocus.debouncer.isDebounced(debounceId)
@@ -3479,256 +3388,6 @@ export function createApiExtension(
{ handler: 'agent-write', method: 'POST' },
);
- const handleAgentWriteMd = withValidation(
- AgentWriteMdRequestSchema,
- async (_req, res, body) => {
- try {
- const linkPolicy = getLinkAdvisoryPolicy();
- const position = body.position ?? 'append';
- const effectiveDocName = requireNonEmptyDocName(body.docName, res, 'agent-write-md');
- if (effectiveDocName === null) return;
- const resolvedDocName = canonicalDocName(resolveAlias(effectiveDocName));
-
- const { agentId, agentName, colorSeed, clientName, clientVersion, label } =
- extractAgentIdentity(body);
-
- if (isSystemDoc(resolvedDocName) || isConfigDoc(resolvedDocName)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:reserved-doc-name',
- `'${resolvedDocName}' is a reserved document name.`,
- { handler: 'agent-write-md' },
- );
- return;
- }
-
- if (
- body.extension !== undefined &&
- !docNameExistsWithAnySupportedExtension(contentDir, resolvedDocName)
- ) {
- registerDocExtension(resolvedDocName, body.extension);
- }
-
- const normalizedSummary = normalizeSummary(body.summary);
- const { response: summaryResponse, stored: storedSummary } =
- summaryResponseFields(normalizedSummary);
- const session = await sessionManager.getSession(resolvedDocName, agentId, {
- displayName: agentName,
- colorSeed,
- clientName,
- });
-
- const writeMdReconcile = reconcileDiskBeforeAgentWrite(
- durabilityState,
- hocuspocus,
- resolvedDocName,
- contentDir,
- options.resolveEmbed,
- getBridgeLossReporter?.(),
- );
-
- const writeMdEmbedResolver = options.resolveEmbed
- ? { resolveEmbed: options.resolveEmbed, sourcePath: resolvedDocName }
- : undefined;
- const writeMdPrecomputed = await prepareAgentMarkdownParse(
- session.dc.document,
- body.markdown,
- position,
- writeMdEmbedResolver,
- );
-
- const timestamp = new Date().toISOString();
-
- let writeDivergence: AgentWriteContentDivergence | undefined;
-
- let disposeEffectCapture: (() => void) | undefined;
-
- try {
- const icon = iconFromClientName(clientName);
- const color = AGENT_ICON_COLORS[icon] ?? colorFromSeed(colorSeed ?? agentId);
- agentPresenceBroadcaster?.setPresence(agentId, {
- displayName: agentName,
- icon,
- color,
- currentDoc: resolvedDocName,
- mode: 'writing',
- ts: Date.now(),
- });
- disposeEffectCapture = captureEffect(
- session.dc.document.getText('source'),
- agentId,
- session.origin,
- colorSeed,
- clientName,
- );
- agentWritePreDrain(session.dc.document, body.markdown, position);
- session.dc.document.transact(() => {
- const beforeBlocks = snapshotBlocks(session.dc.document);
- writeDivergence = applyAgentMarkdownWrite(
- session.dc.document,
- body.markdown,
- position,
- writeMdEmbedResolver,
- writeMdPrecomputed,
- agentWriteLossDetect(session),
- );
-
- const changedBlocks =
- changedBlockRange(beforeBlocks, snapshotBlocks(session.dc.document)) ?? undefined;
- const activityMap = session.dc.document.getMap('agent-flash');
- activityMap.set(agentId, {
- agentId,
- timestamp: Date.now(),
- type: 'insert',
- description: `Added (${agentName}): ${body.markdown.trim().slice(0, 50)}`,
- ...(changedBlocks !== undefined ? { changedBlocks } : {}),
- });
- }, session.origin);
- if (writeDivergence !== undefined) {
- console.warn(
- JSON.stringify({
- event: 'agent-write-content-divergence',
- 'doc.name': resolvedDocName,
- position,
- intendedBytes: writeDivergence.intendedBytes,
- actualBytes: writeDivergence.actualBytes,
- byteDelta: writeDivergence.byteDelta,
- 'agent.id': agentId,
- 'agent.client_name': clientName,
- }),
- );
- }
- recordContentDivergenceGate('agent-write-md', writeDivergence);
- recordContributor(
- resolvedDocName,
- agentId,
- agentName,
- colorSeed,
- undefined,
- buildAgentActor({ clientName, clientVersion, label }),
- storedSummary,
- );
- incrementAgentWriteCalls();
- countNormalizedSummary(normalizedSummary);
- } finally {
- disposeEffectCapture?.();
- agentPresenceBroadcaster?.touchMode(agentId, 'idle');
- }
-
- const flushOutcome = await flushDiskAndDetectOutcome(resolvedDocName);
- if (flushOutcome?.kind === 'failure') {
- respondPersistenceFailure(res, flushOutcome.failure, 'agent-write-md');
- return;
- }
- if (flushOutcome?.kind === 'divergence') {
- respondDiskDivergence(res, 'agent-write-md');
- return;
- }
- if (flushOutcome?.kind === 'stale-external-write') {
- respondStaleExternalWrite(res, 'agent-write-md', resolvedDocName);
- return;
- }
-
- flushDocToDisk(resolvedDocName, 'agent-write-md');
-
- agentFocusBroadcaster?.setFocus(agentId, {
- agentName,
- currentDoc: resolvedDocName,
- writeKind: 'write',
- ts: Date.now(),
- });
- onAgentWrite?.();
-
- const hints = await computeOrphanHints(resolvedDocName);
-
- const writtenSource = session.dc.document.getText('source').toString();
-
- registerWrittenDocInFileIndex(resolvedDocName, writtenSource);
-
- const renderWarnings = await validateMermaidFences(writtenSource, resolvedDocName);
-
- const admittedForLinks = await collectAdmittedDocNames();
- admittedForLinks.add(resolvedDocName);
- const linkAdvisory = projectWriteAdvisoryLinks(
- computeWriteAdvisoryLinks(
- writtenSource,
- resolvedDocName,
- admittedForLinks,
- createLinkedFileExists(),
- createLinkedFolderExists(),
- ),
- resolvedDocName,
- linkPolicy.suppressLogLinkAdvisories,
- );
-
- const subscriberCount = getSubscriberCount(resolvedDocName);
- const systemSubscriberCount = getSystemSubscriberCount();
-
- if (systemSubscriberCount === 0) {
- hintEmittedCounter().add(1, {
- 'shadow.writer': 'agent',
- 'agent.type': resolveAgentType(clientName),
- });
- }
-
- const writeMdWarning = buildReconcileWarning(writeMdReconcile);
- const writeMdDivergenceEntry =
- writeDivergence !== undefined ? toContentDivergenceWarning(writeDivergence) : undefined;
- const writeMdAdvisories = [
- ...(writeMdDivergenceEntry ? [writeMdDivergenceEntry] : []),
- ...(writeMdWarning ? [writeMdWarning] : []),
- ...(renderWarnings ?? []),
- ...(await computeLintViolations(
- session.dc.document.getText('source').toString(),
- resolvedDocName,
- linkPolicy,
- )),
- ];
- successResponse(
- res,
- 200,
- AgentWriteMdSuccessSchema,
- {
- timestamp,
- subscriberCount,
- systemSubscriberCount,
- ...(hints ? { hints } : {}),
- ...(summaryResponse ? { summary: summaryResponse } : {}),
- ...(writeMdAdvisories.length > 0 ? { warnings: writeMdAdvisories } : {}),
- ...linkAdvisory,
- },
- { handler: 'agent-write-md' },
- );
- } catch (e) {
- if (e instanceof DocInConflictError) {
- respondDocInConflict(res, e, 'agent-write-md');
- return;
- }
- if (e instanceof FrontmatterMalformedError) {
- respondFrontmatterMalformed(res, e, 'agent-write-md');
- return;
- }
- if (e instanceof AgentSessionCapacityError) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:too-many-agent-sessions',
- 'Too many agent sessions.',
- { handler: 'agent-write-md', cause: e, extraHeaders: { 'Retry-After': '10' } },
- );
- return;
- }
- log.error({ err: e, requestId: getRequestId(_req) }, '[agent-write-md] handler failed');
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: 'agent-write-md',
- cause: e,
- });
- }
- },
- { handler: 'agent-write-md', method: 'POST' },
- );
-
const handleAgentWriteBatch = withValidation(
AgentWriteBatchRequestSchema,
async (_req, res, body) => {
@@ -4054,1405 +3713,33 @@ export function createApiExtension(
},
{ handler: 'agent-write-batch', method: 'POST' },
);
+ const skillPlacementOps = createSkillPlacementOpsService();
- const handleFrontmatterPatch = withValidation(
- FrontmatterPatchRequestSchema,
- async (_req, res, body) => {
- try {
- const linkPolicy = getLinkAdvisoryPolicy();
- const effectiveDocName = requireNonEmptyDocName(body.docName, res, 'frontmatter-patch');
- if (effectiveDocName === null) return;
- const resolvedDocName = resolveAlias(effectiveDocName);
-
- const { agentId, agentName, colorSeed, clientName, clientVersion, label } =
- extractAgentIdentity(body);
+ const assetService = createAssetService({
+ contentDir,
+ isPathIgnored: (relativePath) => contentFilter?.isPathIgnored(relativePath) ?? false,
+ getAttachmentFolderPath,
+ });
+ const ASSET_SERVE_ERRORS = {
+ 'missing-path': [400, 'urn:ok:error:invalid-request', 'Missing asset path.'],
+ 'unsupported-type': [415, 'urn:ok:error:unsupported-asset-type', 'Unsupported asset type.'],
+ 'not-found': [404, 'urn:ok:error:asset-not-found', 'Asset not found.'],
+ 'invalid-path': [400, 'urn:ok:error:invalid-request', 'Invalid asset path.'],
+ } as const;
- if (isSystemDoc(resolvedDocName) || isConfigDoc(resolvedDocName)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:reserved-doc-name',
- `'${resolvedDocName}' is a reserved document name.`,
- { handler: 'frontmatter-patch' },
- );
- return;
- }
-
- const patch = body.patch ?? {};
- const patchKeys = Object.keys(patch);
-
- const normalizedSummary = normalizeSummary(body.summary);
- const { response: summaryResponse, stored: storedSummary } =
- summaryResponseFields(normalizedSummary);
- const session = await sessionManager.getSession(resolvedDocName, agentId, {
- displayName: agentName,
- colorSeed,
- clientName,
- });
-
- const fmReconcile = reconcileDiskBeforeAgentWrite(
- durabilityState,
- hocuspocus,
- resolvedDocName,
- contentDir,
- options.resolveEmbed,
- getBridgeLossReporter?.(),
- );
-
- const fmPatchPrecomputed = await prepareFrontmatterPatchParse(session.dc.document, patch);
-
- const timestamp = new Date().toISOString();
-
- let editError: import('@inkeep/open-knowledge-core').FmEditError | undefined;
- let applied = false;
- let bodyMutated = false;
- const appliedKeys: string[] = [];
-
- try {
- const icon = iconFromClientName(clientName);
- const color = AGENT_ICON_COLORS[icon] ?? colorFromSeed(colorSeed ?? agentId);
- agentPresenceBroadcaster?.setPresence(agentId, {
- displayName: agentName,
- icon,
- color,
- currentDoc: resolvedDocName,
- mode: 'writing',
- ts: Date.now(),
- });
-
- withSpanSync(
- 'ok.frontmatter_patch',
- {
- attributes: {
- 'doc.name': resolvedDocName,
- 'frontmatter_patch.keys': patchKeys.length,
- },
- },
- () => {
- session.dc.document.transact(() => {
- const ytext = session.dc.document.getText('source');
- const currentFull = ytext.toString();
- const { fenced: currentFenced, body: currentBody } = detectFmRegion(currentFull);
-
- const result = applyPatchToFm(currentFenced, patch);
- if (!result.ok) {
- editError = result.error;
- return;
- }
-
- for (const key of Object.keys(patch)) {
- appliedKeys.push(key);
- }
-
- if (result.nextFenced !== currentFenced) {
- /**
- * Routed through the sanctioned `composeAndWriteRawBody` primitive
- * (precedent #38) so paired-write semantics survive.
- */
- const needsFenceSeparator =
- currentFenced === '' && currentBody !== '' && !currentBody.startsWith('\n');
- const newFull = composeWithDerivedFrontmatter(
- result.nextFenced,
- (needsFenceSeparator ? '\n' : '') + currentBody,
- ).md;
- composeAndWriteRawBody(
- session.dc.document,
- newFull,
- 'agent',
- undefined,
- fmPatchPrecomputed,
- );
- recordFrontmatterEditSurface('mcp-write');
- bodyMutated = true;
- }
- applied = true;
- }, session.origin);
- },
- );
- } finally {
- agentPresenceBroadcaster?.touchMode(agentId, 'idle');
- }
-
- if (editError) {
- let fieldErrors: Record<string, string>;
- switch (editError.kind) {
- case 'invalid_value':
- fieldErrors = { [editError.key]: editError.reason };
- break;
- case 'reserved_key':
- fieldErrors = { [editError.key]: `'${editError.key}' is reserved` };
- break;
- case 'unknown_key':
- fieldErrors = { [editError.key]: `'${editError.key}' is not a recognized key` };
- break;
- case 'duplicate_target':
- fieldErrors = { [editError.key]: `'${editError.key}' appears more than once` };
- break;
- case 'reorder_mismatch':
- fieldErrors = {
- __region__: `frontmatter reorder mismatch (expected: ${editError.expected.join(', ')}; got: ${editError.got.join(', ')})`,
- };
- break;
- case 'region_too_large':
- fieldErrors = {
- __region__: `frontmatter region too large (${editError.bytes} > ${editError.limit} bytes)`,
- };
- break;
- case 'parse_failed':
- fieldErrors = { __region__: `frontmatter region unparseable: ${editError.reason}` };
- break;
- case 'invalid_path':
- fieldErrors = {
- [editError.path.map(String).join('.') || '__path__']: editError.reason,
- };
- break;
- default: {
- const _exhaustive: never = editError;
- fieldErrors = {
- __region__: `unhandled frontmatter edit error (${String(_exhaustive)})`,
- };
- }
- }
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-frontmatter-patch',
- 'Frontmatter patch rejected: schema validation failed.',
- { handler: 'frontmatter-patch', extensions: { fieldErrors } },
- );
- return;
- }
-
- if (applied && appliedKeys.length > 0) {
- recordContributor(
- resolvedDocName,
- agentId,
- agentName,
- colorSeed,
- undefined,
- buildAgentActor({ clientName, clientVersion, label }),
- storedSummary,
- );
- incrementAgentWriteCalls();
- countNormalizedSummary(normalizedSummary);
- if (bodyMutated) {
- const flushOutcome = await flushDiskAndDetectOutcome(resolvedDocName);
- if (flushOutcome?.kind === 'failure') {
- respondPersistenceFailure(res, flushOutcome.failure, 'frontmatter-patch');
- return;
- }
- if (flushOutcome?.kind === 'divergence') {
- respondDiskDivergence(res, 'frontmatter-patch');
- return;
- }
- if (flushOutcome?.kind === 'stale-external-write') {
- respondStaleExternalWrite(res, 'frontmatter-patch', resolvedDocName);
- return;
- }
- }
- flushDocToDisk(resolvedDocName, 'frontmatter-patch');
- }
-
- agentFocusBroadcaster?.setFocus(agentId, {
- agentName,
- currentDoc: resolvedDocName,
- writeKind: 'write',
- ts: Date.now(),
- });
- onAgentWrite?.();
-
- const subscriberCount = getSubscriberCount(resolvedDocName);
- const systemSubscriberCount = getSystemSubscriberCount();
-
- if (systemSubscriberCount === 0) {
- hintEmittedCounter().add(1, {
- 'shadow.writer': 'agent',
- 'agent.type': resolveAgentType(clientName),
- });
- }
-
- const fmWarning = buildReconcileWarning(fmReconcile);
-
- registerWrittenDocInFileIndex(
- resolvedDocName,
- session.dc.document.getText('source').toString(),
- );
-
- const admittedForLinks = await collectAdmittedDocNames();
- admittedForLinks.add(resolvedDocName);
- const linkAdvisory = projectWriteAdvisoryLinks(
- computeWriteAdvisoryLinks(
- session.dc.document.getText('source').toString(),
- resolvedDocName,
- admittedForLinks,
- createLinkedFileExists(),
- ),
- resolvedDocName,
- linkPolicy.suppressLogLinkAdvisories,
- );
-
- successResponse(
- res,
- 200,
- FrontmatterPatchSuccessSchema,
- {
- timestamp,
- subscriberCount,
- systemSubscriberCount,
- appliedKeys,
- ...(summaryResponse ? { summary: summaryResponse } : {}),
- ...(fmWarning ? { warnings: [fmWarning] } : {}),
- ...linkAdvisory,
- },
- { handler: 'frontmatter-patch' },
- );
- } catch (e) {
- if (e instanceof AgentSessionCapacityError) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:too-many-agent-sessions',
- 'Too many agent sessions.',
- { handler: 'frontmatter-patch', cause: e, extraHeaders: { 'Retry-After': '10' } },
- );
- return;
- }
- log.error({ err: e, requestId: getRequestId(_req) }, '[frontmatter-patch] handler failed');
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: 'frontmatter-patch',
- cause: e,
- });
- }
- },
- { handler: 'frontmatter-patch', method: 'POST' },
- );
-
- const handleAgentPatch = withValidation(
- AgentPatchRequestSchema,
- async (_req, res, body) => {
- try {
- const linkPolicy = getLinkAdvisoryPolicy();
- const { find, replace, offset } = body;
- const effectivePatchDocName = requireNonEmptyDocName(body.docName, res, 'agent-patch');
- if (effectivePatchDocName === null) return;
- const docName = resolveAlias(effectivePatchDocName);
-
- const { agentId, agentName, colorSeed, clientName, clientVersion, label } =
- extractAgentIdentity(body);
-
- if (isSystemDoc(docName) || isConfigDoc(docName)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:reserved-doc-name',
- `'${docName}' is a reserved document name.`,
- { handler: 'agent-patch' },
- );
- return;
- }
-
- const normalizedSummary = normalizeSummary(body.summary);
- const session = await sessionManager.getSession(docName, agentId, {
- displayName: agentName,
- colorSeed,
- clientName,
- });
-
- const patchReconcile = reconcileDiskBeforeAgentWrite(
- durabilityState,
- hocuspocus,
- docName,
- contentDir,
- options.resolveEmbed,
- getBridgeLossReporter?.(),
- );
-
- const patchEmbedResolver = options.resolveEmbed
- ? { resolveEmbed: options.resolveEmbed, sourcePath: docName }
- : undefined;
- let patchPrecomputed: PrecomputedParse | undefined;
- {
- const preSnapshot = session.dc.document.getText('source').toString();
- const { frontmatter: preFm, body: preBody } = stripFrontmatter(preSnapshot);
- const preFull = prependFrontmatter(preFm, preBody);
- const prePos =
- offset == null
- ? preFull.indexOf(find)
- : preFull.slice(offset, offset + find.length) === find
- ? offset
- : -1;
- if (prePos !== -1 && prePos >= preFm.length) {
- const guessFull =
- preFull.slice(0, prePos) + replace + preFull.slice(prePos + find.length);
- patchPrecomputed = await prepareAgentMarkdownParse(
- session.dc.document,
- stripFrontmatter(guessFull).body,
- 'patch',
- patchEmbedResolver,
- );
- }
- }
-
- const timestamp = new Date().toISOString();
-
- let notFound = false;
- let staleTarget = false;
- let fmIntersect = false;
- let fmPromoted = false;
- let patchDivergence: AgentWriteContentDivergence | undefined;
- let disposeEffectCapture: (() => void) | undefined;
- try {
- const icon = iconFromClientName(clientName);
- const color = AGENT_ICON_COLORS[icon] ?? colorFromSeed(colorSeed ?? agentId);
- agentPresenceBroadcaster?.setPresence(agentId, {
- displayName: agentName,
- icon,
- color,
- currentDoc: docName,
- mode: 'writing',
- ts: Date.now(),
- });
- disposeEffectCapture = captureEffect(
- session.dc.document.getText('source'),
- agentId,
- session.origin,
- colorSeed,
- clientName,
- );
- session.dc.document.transact(() => {
- /**
- * Read current authoritative state from Y.Text, the user's intended source-form bytes
- * (Y.Text-is-truth, precedent #38); `serialize(fragment)` would compute offsets against
- * canonical bytes instead.
- */
- const ytextSnapshot = session.dc.document.getText('source').toString();
- const { frontmatter: currentFm, body: currentBody } = stripFrontmatter(ytextSnapshot);
- const currentFull = prependFrontmatter(currentFm, currentBody);
-
- const pos =
- offset == null
- ? currentFull.indexOf(find)
- : currentFull.slice(offset, offset + find.length) === find
- ? offset
- : -1;
- if (pos === -1) {
- if (offset == null) {
- notFound = true;
- } else {
- staleTarget = true;
- }
- console.warn(
- JSON.stringify({
- event: 'agent-patch-find-mismatch',
- 'doc.name': docName,
- findLength: find.length,
- replaceLength: replace.length,
- hadOffset: offset != null,
- }),
- );
- incrementAgentPatchFindMismatches();
- return;
- }
-
- if (pos < currentFm.length) {
- fmIntersect = true;
- return;
- }
-
- const newFull =
- currentFull.slice(0, pos) + replace + currentFull.slice(pos + find.length);
-
- if (currentFm === '' && stripFrontmatter(newFull).frontmatter !== '') {
- fmPromoted = true;
- return;
- }
-
- const { body: newBody } = stripFrontmatter(newFull);
- const beforeBlocks = snapshotBlocks(session.dc.document);
- patchDivergence = applyAgentMarkdownWrite(
- session.dc.document,
- newBody,
- 'patch',
- patchEmbedResolver,
- patchPrecomputed,
- agentWriteLossDetect(session),
- );
-
- const changedBlocks =
- changedBlockRange(beforeBlocks, snapshotBlocks(session.dc.document)) ?? undefined;
- const activityMap = session.dc.document.getMap('agent-flash');
- activityMap.set(agentId, {
- agentId,
- timestamp: Date.now(),
- type: 'insert',
- description: `Patched (${agentName}): ${find.slice(0, 50)}`,
- ...(changedBlocks !== undefined ? { changedBlocks } : {}),
- });
- }, session.origin);
- if (patchDivergence !== undefined) {
- console.warn(
- JSON.stringify({
- event: 'agent-write-content-divergence',
- 'doc.name': docName,
- position: 'patch',
- intendedBytes: patchDivergence.intendedBytes,
- actualBytes: patchDivergence.actualBytes,
- byteDelta: patchDivergence.byteDelta,
- 'agent.id': agentId,
- 'agent.client_name': clientName,
- }),
- );
- }
- if (!notFound && !staleTarget && !fmIntersect && !fmPromoted) {
- const { stored: storedSummary } = summaryResponseFields(normalizedSummary);
- recordContributor(
- docName,
- agentId,
- agentName,
- colorSeed,
- undefined,
- buildAgentActor({ clientName, clientVersion, label }),
- storedSummary,
- );
- incrementAgentWriteCalls();
- countNormalizedSummary(normalizedSummary);
- recordContentDivergenceGate('agent-patch', patchDivergence);
- }
- } finally {
- disposeEffectCapture?.();
- agentPresenceBroadcaster?.touchMode(agentId, 'idle');
- }
-
- if (staleTarget) {
- errorResponse(
- res,
- 409,
- 'urn:ok:error:stale-target',
- 'Target text no longer matches at the requested offset.',
- { handler: 'agent-patch' },
- );
- return;
- }
- if (notFound) {
- errorResponse(res, 404, 'urn:ok:error:target-not-found', 'Text not found in document.', {
- handler: 'agent-patch',
- });
- return;
- }
- if (fmIntersect) {
- agentPatchFmTouchCounter().add(1, { result: 'rejected', reason: 'intersect' });
- errorResponse(
- res,
- 400,
- 'urn:ok:error:frontmatter-edit-not-supported',
- 'Frontmatter edits are not supported via a body find/replace. Use edit({ document: { path, frontmatter } }) to change frontmatter, or write({ document: { path, content, position: "replace" } }) to rewrite the whole document including its YAML block.',
- { handler: 'agent-patch' },
- );
- return;
- }
- if (fmPromoted) {
- agentPatchFmTouchCounter().add(1, { result: 'rejected', reason: 'promoted' });
- errorResponse(
- res,
- 400,
- 'urn:ok:error:frontmatter-edit-not-supported',
- "This edit would turn the replacement text into the document's frontmatter: the document has no frontmatter, the match starts at byte 0, and `replace` opens a `---` fence pair — so the composed document would re-read that block as its YAML region. Use edit({ document: { path, frontmatter } }) to set frontmatter, or keep the `---` out of the first line (a leading blank line, or `***` / `___` for a thematic break).",
- { handler: 'agent-patch' },
- );
- return;
- }
-
- const flushOutcome = await flushDiskAndDetectOutcome(docName);
- if (flushOutcome?.kind === 'failure') {
- respondPersistenceFailure(res, flushOutcome.failure, 'agent-patch');
- return;
- }
- if (flushOutcome?.kind === 'divergence') {
- respondDiskDivergence(res, 'agent-patch');
- return;
- }
- if (flushOutcome?.kind === 'stale-external-write') {
- respondStaleExternalWrite(res, 'agent-patch', docName);
- return;
- }
-
- flushDocToDisk(docName, 'agent-patch');
-
- agentFocusBroadcaster?.setFocus(agentId, {
- agentName,
- currentDoc: docName,
- writeKind: 'edit',
- ts: Date.now(),
- });
- onAgentWrite?.();
-
- const subscriberCount = getSubscriberCount(docName);
- const systemSubscriberCount = getSystemSubscriberCount();
-
- if (systemSubscriberCount === 0) {
- hintEmittedCounter().add(1, {
- 'shadow.writer': 'agent',
- 'agent.type': resolveAgentType(clientName),
- });
- }
-
- const { response: summaryResponse } = summaryResponseFields(normalizedSummary);
-
- const patchedSource = session.dc.document.getText('source').toString();
-
- registerWrittenDocInFileIndex(docName, patchedSource);
-
- const renderWarnings = await validateMermaidFences(patchedSource, docName);
-
- const admittedForLinks = await collectAdmittedDocNames();
- admittedForLinks.add(docName);
- const linkAdvisory = projectWriteAdvisoryLinks(
- computeWriteAdvisoryLinks(
- patchedSource,
- docName,
- admittedForLinks,
- createLinkedFileExists(),
- ),
- docName,
- linkPolicy.suppressLogLinkAdvisories,
- );
-
- const patchWarning = buildReconcileWarning(patchReconcile);
- const patchDivergenceEntry =
- patchDivergence !== undefined ? toContentDivergenceWarning(patchDivergence) : undefined;
- const patchAdvisories = [
- ...(patchDivergenceEntry ? [patchDivergenceEntry] : []),
- ...(patchWarning ? [patchWarning] : []),
- ...(renderWarnings ?? []),
- ...(await computeLintViolations(
- session.dc.document.getText('source').toString(),
- docName,
- linkPolicy,
- )),
- ];
- successResponse(
- res,
- 200,
- AgentPatchSuccessSchema,
- {
- timestamp,
- subscriberCount,
- systemSubscriberCount,
- ...(summaryResponse ? { summary: summaryResponse } : {}),
- ...(patchAdvisories.length > 0 ? { warnings: patchAdvisories } : {}),
- ...linkAdvisory,
- },
- { handler: 'agent-patch' },
- );
- } catch (e) {
- if (e instanceof DocInConflictError) {
- respondDocInConflict(res, e, 'agent-patch');
- return;
- }
- if (e instanceof FrontmatterMalformedError) {
- respondFrontmatterMalformed(res, e, 'agent-patch');
- return;
- }
- if (e instanceof AgentSessionCapacityError) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:too-many-agent-sessions',
- 'Too many agent sessions.',
- { handler: 'agent-patch', cause: e, extraHeaders: { 'Retry-After': '10' } },
- );
- return;
- }
- log.error({ err: e, requestId: getRequestId(_req) }, '[agent-patch] handler failed');
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: 'agent-patch',
- cause: e,
- });
- }
- },
- { handler: 'agent-patch', method: 'POST' },
- );
-
- const handleAgentUndo = withValidation(
- AgentUndoRequestSchema,
- async (_req, res, body) => {
- try {
- const rawDocName = requireNonEmptyDocName(body.docName, res, 'agent-undo');
- if (rawDocName === null) return;
- const docName = resolveAlias(rawDocName);
-
- const { agentId, agentName, colorSeed, clientName, clientVersion, label } =
- extractAgentIdentity(body);
-
- if (isSystemDoc(docName) || isConfigDoc(docName)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:reserved-doc-name',
- `'${docName}' is a reserved document name.`,
- { handler: 'agent-undo' },
- );
- return;
- }
-
- const { connectionId } = body;
-
- let scope: 'last' | 'session' | 'count';
- let count: number | undefined;
- if (body.scope === 'count') {
- scope = 'count';
- count = body.count;
- } else if (body.scope === 'session' || body.scope === 'file') {
- scope = 'session';
- } else {
- scope = 'last';
- }
-
- if (!sessionManager.hasSession(docName, connectionId)) {
- errorResponse(
- res,
- 404,
- 'urn:ok:error:no-active-session',
- 'No active session for this connectionId and docName.',
- { handler: 'agent-undo' },
- );
- return;
- }
-
- const session = await sessionManager.getSession(docName, connectionId);
-
- let undone = false;
- try {
- const icon = iconFromClientName(clientName);
- const color = AGENT_ICON_COLORS[icon] ?? colorFromSeed(colorSeed ?? agentId);
- agentPresenceBroadcaster?.setPresence(agentId, {
- displayName: agentName,
- icon,
- color,
- currentDoc: docName,
- mode: 'writing',
- ts: Date.now(),
- });
- undone = applyAgentUndo(
- session,
- scope,
- options.resolveEmbed
- ? { resolveEmbed: options.resolveEmbed, sourcePath: docName }
- : undefined,
- count,
- );
- if (undone) {
- recordContributor(
- docName,
- connectionId,
- agentName,
- colorSeed,
- undefined,
- buildAgentActor({ clientName, clientVersion, label }),
- );
- }
- } finally {
- agentPresenceBroadcaster?.touchMode(agentId, 'idle');
- }
-
- if (undone) {
- const flushOutcome = await flushDiskAndDetectOutcome(docName);
- if (flushOutcome?.kind === 'failure') {
- respondPersistenceFailure(res, flushOutcome.failure, 'agent-undo');
- return;
- }
- if (flushOutcome?.kind === 'divergence') {
- respondDiskDivergence(res, 'agent-undo');
- return;
- }
- if (flushOutcome?.kind === 'stale-external-write') {
- respondStaleExternalWrite(res, 'agent-undo', docName);
- return;
- }
- flushDocToGit(docName, 'agent-undo');
- }
-
- agentFocusBroadcaster?.setFocus(connectionId, {
- agentName: connectionId,
- currentDoc: docName,
- writeKind: 'undo',
- ts: Date.now(),
- });
-
- successResponse(
- res,
- 200,
- AgentUndoSuccessSchema,
- { docName, scope, undone },
- { handler: 'agent-undo' },
- );
- } catch (e) {
- if (e instanceof DocInConflictError) {
- respondDocInConflict(res, e, 'agent-undo');
- return;
- }
- log.error({ err: e, requestId: getRequestId(_req) }, '[agent-undo] handler failed');
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: 'agent-undo',
- cause: e,
- });
- }
- },
- { handler: 'agent-undo', method: 'POST' },
- );
-
- const handleAgentActivity = withValidation(
- EmptyRequestSchema,
- async (req, res) => {
- try {
- const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
- const agentId = validateAgentId(url.searchParams.get('agentId'));
- if (agentId === null) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'agentId required (alphanumeric/_/- only).',
- { handler: 'agent-activity' },
- );
- return;
- }
- const result = listAgentActivity(sessionManager, agentId);
- successResponse(res, 200, AgentActivitySuccessSchema, result, {
- handler: 'agent-activity',
- });
- } catch (e) {
- log.error({ err: e, requestId: getRequestId(req) }, '[agent-activity] handler failed');
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: 'agent-activity',
- cause: e,
- });
- }
- },
- { handler: 'agent-activity', method: 'GET', skipBodyParse: true },
- );
-
- const handleAgentBurstDiff = withValidation(
- EmptyRequestSchema,
- async (req, res) => {
- try {
- const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
- const agentId = validateAgentId(url.searchParams.get('agentId'));
- const rawDocName = url.searchParams.get('docName');
- const keptCountStr = url.searchParams.get('keptCount');
-
- if (agentId === null) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'agentId required (alphanumeric/_/- only).',
- { handler: 'agent-burst-diff' },
- );
- return;
- }
- if (!rawDocName || rawDocName.trim() === '') {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docName parameter.', {
- handler: 'agent-burst-diff',
- });
- return;
- }
- if (!isSafeDocName(rawDocName)) {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {
- handler: 'agent-burst-diff',
- });
- return;
- }
- const docName = resolveAlias(rawDocName);
- if (isSystemDoc(docName) || isConfigDoc(docName)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:reserved-doc-name',
- `'${docName}' is a reserved document name.`,
- { handler: 'agent-burst-diff' },
- );
- return;
- }
- if (!keptCountStr || Number.isNaN(Number(keptCountStr))) {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'keptCount must be a number.', {
- handler: 'agent-burst-diff',
- });
- return;
- }
- const keptCount = Number(keptCountStr);
- if (!Number.isInteger(keptCount) || keptCount < 0) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'keptCount must be a non-negative integer.',
- { handler: 'agent-burst-diff' },
- );
- return;
- }
-
- const session = sessionManager.getLiveSession(docName, agentId);
- if (!session) {
- errorResponse(
- res,
- 404,
- 'urn:ok:error:no-active-session',
- 'No active session for this agentId and docName.',
- { handler: 'agent-burst-diff' },
- );
- return;
- }
-
- const um = session.um;
- if (keptCount > um.undoStack.length) {
- errorResponse(
- res,
- 404,
- 'urn:ok:error:not-found',
- `keptCount ${keptCount} out of range (stack has ${um.undoStack.length} items).`,
- { handler: 'agent-burst-diff' },
- );
- return;
- }
-
- const ytext = session.dc.document.getText('source');
- const { diff, before, after, properties } = synthesizeVersionDiff(
- // biome-ignore lint/suspicious/noExplicitAny: Y.StackItem is internal to yjs — structural shape matches YjsStackItemShape in agent-activity.ts
- um.undoStack as any,
- keptCount,
- ytext,
- docName,
- );
- successResponse(
- res,
- 200,
- AgentBurstDiffSuccessSchema,
- { diff, before, after, properties, generatedAt: Date.now() },
- { handler: 'agent-burst-diff' },
- );
- } catch (e) {
- log.error({ err: e, requestId: getRequestId(req) }, '[agent-burst-diff] handler failed');
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: 'agent-burst-diff',
- cause: e,
- });
- }
- },
- { handler: 'agent-burst-diff', method: 'GET', skipBodyParse: true },
- );
-
- const handleTestFlushGit = withValidation(
- EmptyRequestSchema,
- async (_req, res) => {
- try {
- await flushGitCommit?.();
- successResponse(res, 200, TestFlushGitSuccessSchema, {}, { handler: 'test-flush-git' });
- } catch (e) {
- log.error({ err: e, requestId: getRequestId(_req) }, '[test-flush-git] flush failed');
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: 'test-flush-git',
- cause: e,
- });
- }
- },
- { handler: 'test-flush-git', method: 'POST', skipBodyParse: true },
- );
-
- const handleTestReset = withValidation(
- EmptyRequestSchema,
- async (req, res) => {
- try {
- const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
- const docName = canonicalDocName(
- resolveAlias(url.searchParams.get('docName') ?? 'test-doc'),
- );
-
- let filePath: string;
- try {
- filePath = safeContentPath(docName, contentDir);
- } catch (err) {
- log.error({ err, docName }, '[test-reset] safeContentPath rejected docName');
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {
- handler: 'test-reset',
- cause: err,
- });
- return;
- }
-
- await sessionManager.closeAll(docName);
- hocuspocus.closeConnections(docName);
-
- const debounceId = `onStoreDocument-${docName}`;
- if (hocuspocus.debouncer.isDebounced(debounceId)) {
- await hocuspocus.debouncer.executeNow(debounceId);
- }
-
- const doc = hocuspocus.documents.get(docName);
- if (doc) await (forceUnloadDocument ?? hocuspocus.unloadDocument.bind(hocuspocus))(doc);
- resetDocumentDurability?.(docName);
- writeFileSync(filePath, '', 'utf-8');
- await derivedDocumentIndex?.testOnly?.resetDocumentForTest(docName);
-
- const resetOkignoreParam = url.searchParams.get('reset-okignore');
- const resetOkignore = resetOkignoreParam !== 'false';
- if (resetOkignore) {
- try {
- const okignorePath = resolve(contentDir, '.okignore');
- const okignoreDoc = hocuspocus.documents.get(CONFIG_DOC_NAME_OKIGNORE);
- if (okignoreDoc) {
- const ytext = okignoreDoc.getText('source');
- if (ytext.length > 0) {
- okignoreDoc.transact(() => {
- ytext.delete(0, ytext.length);
- }, CONFIG_VALIDATION_REVERT_ORIGIN);
- }
- }
- if (existsSync(okignorePath)) {
- writeFileSync(okignorePath, '', 'utf-8');
- }
- if (contentFilter) {
- bumpSkillsCatalogGen();
- await contentFilter.rebuildIgnorePatterns();
- }
- } catch (err) {
- log.warn({ err }, '[test-reset] okignore reset partial failure');
- }
- }
- signalChannel?.('files');
- successResponse(res, 200, TestResetSuccessSchema, {}, { handler: 'test-reset' });
- } catch (e) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: 'test-reset',
- cause: e,
- });
- }
- },
- { handler: 'test-reset', method: 'POST', skipBodyParse: true },
- );
-
- const handleTestRescanBacklinks = withValidation(
- EmptyRequestSchema,
- async (_req, res) => {
- try {
- if (!derivedDocumentIndex?.testOnly) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:backlink-index-not-configured',
- 'Backlink index is not configured.',
- { handler: 'test-rescan-backlinks' },
- );
- return;
- }
- await derivedDocumentIndex.testOnly.rescanBacklinksForTest();
- successResponse(
- res,
- 200,
- TestRescanBacklinksSuccessSchema,
- {},
- { handler: 'test-rescan-backlinks' },
- );
- } catch (e) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: 'test-rescan-backlinks',
- cause: e,
- });
- }
- },
- { handler: 'test-rescan-backlinks', method: 'POST', skipBodyParse: true },
- );
-
- const handleTestRescanFiles = withValidation(
- EmptyRequestSchema,
- async (_req, res) => {
- try {
- if (!rescanFiles) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:file-rescan-not-configured',
- 'Watcher rescan capability is not configured.',
- { handler: 'test-rescan-files' },
- );
- return;
- }
- await rescanFiles();
- signalChannel?.('files');
- successResponse(
- res,
- 200,
- TestRescanFilesSuccessSchema,
- {},
- { handler: 'test-rescan-files' },
- );
- } catch (e) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: 'test-rescan-files',
- cause: e,
- });
- }
- },
- { handler: 'test-rescan-files', method: 'POST', skipBodyParse: true },
- );
-
- const versionOpsService = createVersionOpsService({ getCurrentBranch, contentRoot });
- const skillPlacementOps = createSkillPlacementOpsService();
-
- const handleSaveVersion = withValidation(
- SaveVersionRequestSchema,
- async (_req, res, body) => {
- try {
- const saveVersionBody = body as unknown as Record<string, unknown>;
- const {
- rawAgentId: svRawAgentId,
- agentId: svAgentId,
- agentName: svAgentName,
- clientName: svClientName,
- } = extractAgentIdentity(saveVersionBody);
-
- const shadow = shadowRef?.current;
- if (!shadow) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:shadow-not-configured',
- 'Shadow repo not configured.',
- { handler: 'save-version' },
- );
- return;
- }
-
- const SAFE_ID_RE = /^[a-zA-Z0-9_-]+$/;
- let writers: WriterIdentity[] = [];
-
- if (Array.isArray(body.writers)) {
- try {
- writers = body.writers.map((w) => {
- const id = w.id ?? 'unknown';
- if (!SAFE_ID_RE.test(id)) {
- throw new Error(`Invalid writer id: ${id}`);
- }
- return {
- id,
- name: (w.name ?? 'unknown').replace(/[\r\n]/g, ''),
- email: (w.email ?? '[email protected]').replace(/[\r\n]/g, ''),
- };
- });
- } catch (e) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- e instanceof Error ? e.message : 'Invalid writer id.',
- { handler: 'save-version', cause: e },
- );
- return;
- }
- }
-
- const agentWriter =
- svRawAgentId !== undefined
- ? {
- id: svAgentId,
- name: svClientName ? `${svAgentName} (${svClientName})` : svAgentName,
- email: `${svAgentId}@openknowledge.local`,
- }
- : undefined;
- const checkpointSummary = normalizeSummary(
- typeof body.summary === 'string' ? body.summary : undefined,
- );
- const result = await versionOpsService.saveCheckpoint(shadow, {
- explicitWriters: writers,
- agentWriter,
- summary: checkpointSummary.kind === 'value' ? checkpointSummary.value : undefined,
- });
-
- successResponse(
- res,
- 200,
- SaveVersionSuccessSchema,
- {
- checkpointRef: result.checkpointRef,
- },
- { handler: 'save-version' },
- );
- } catch (e) {
- log.error({ err: e, requestId: getRequestId(_req) }, '[save-version] handler failed');
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: 'save-version',
- cause: e,
- });
- }
- },
- { handler: 'save-version', method: 'POST' },
- );
-
- const handleRollback = withValidation(
- RollbackRequestSchema,
- async (_req, res, body) => {
- const bodyObj = body as unknown as Record<string, unknown>;
- const actor = extractActorIdentity(bodyObj, getPrincipal);
- if (actor.kind === 'invalid-summary') {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {
- handler: 'rollback',
- });
- return;
- }
-
- // The check fires post-identity (precedent #24) and pre-mutation.
- const targetDoc = hocuspocus.documents.get(body.docName);
- if (targetDoc && isDocInConflict(targetDoc)) {
- respondDocInConflict(
- res,
- new DocInConflictError({ file: docNameToRelativePath(body.docName) }),
- 'rollback',
- );
- return;
- }
-
- const shadow = shadowRef?.current;
- if (!shadow) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:rollback-not-configured',
- 'Shadow repo not configured.',
- { handler: 'rollback' },
- );
- return;
- }
-
- const { docName, commitSha } = body;
-
- const resolvedContentRoot = contentRoot ?? '.';
- const pathResult = safeDocPath(docName, resolvedContentRoot);
- if ('error' in pathResult) {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', pathResult.error, {
- handler: 'rollback',
- });
- return;
- }
- const sg = shadowGit(shadow);
-
- const t0 = Date.now();
- try {
- const renameLogIndex = getOrLoadRenameLogIndex(shadow.gitDir);
- const ancestorCache = createAncestorShaSetCache();
- const branch = getCurrentBranch?.() ?? 'main';
- const historicalPath = await resolveDocPathAtCommit(
- shadow,
- docName,
- commitSha,
- branch,
- renameLogIndex,
- (name) => docTreePathCandidates(name, resolvedContentRoot),
- ancestorCache,
- );
- if (historicalPath === null) {
- errorResponse(
- res,
- 404,
- 'urn:ok:error:doc-not-found',
- `Commit ${commitSha.slice(0, 7)} does not contain document ${docName} at any known historical path.`,
- { handler: 'rollback' },
- );
- return;
- }
-
- const markdown = await sg.raw('show', `${commitSha}:${historicalPath}`);
- const timestamp = new Date().toISOString();
-
- await safetyCheckpoint(shadow, resolvedContentRoot, {
- action: 'rollback',
- context: { docName, targetSha: commitSha },
- });
-
- const document = hocuspocus.documents.get(docName);
- if (!document) {
- errorResponse(
- res,
- 409,
- 'urn:ok:error:doc-not-open',
- 'Document is not currently open — open it in the editor first.',
- { handler: 'rollback' },
- );
- return;
- }
-
- /**
- * Rollback routes through the `replaceRawBody` sibling primitive (precedent #38,
- * Y.Text-is-truth), which overwrites ytext first and derives the fragment after.
- */
- const rollbackEmbedResolver = options.resolveEmbed
- ? { resolveEmbed: options.resolveEmbed, sourcePath: docName }
- : undefined;
- const rollbackPrecomputed = await precomputeParse(markdown, rollbackEmbedResolver);
- let rollbackDivergence: AgentWriteContentDivergence | undefined;
- document.transact(() => {
- replaceRawBody(document, markdown, rollbackEmbedResolver, rollbackPrecomputed);
- rollbackDivergence = evaluateContentDivergence(
- document.getText('source').toString(),
- markdown,
- 'rollback',
- );
- }, ROLLBACK_ORIGIN);
- if (rollbackDivergence !== undefined) {
- console.warn(
- JSON.stringify({
- event: 'agent-write-content-divergence',
- 'doc.name': docName,
- position: 'rollback',
- intendedBytes: rollbackDivergence.intendedBytes,
- actualBytes: rollbackDivergence.actualBytes,
- byteDelta: rollbackDivergence.byteDelta,
- 'actor.kind': actor.kind,
- ...(actor.kind === 'agent' || actor.kind === 'principal'
- ? { 'actor.writer_id': actor.writerId }
- : {}),
- }),
- );
- }
- recordContentDivergenceGate('rollback', rollbackDivergence);
-
- let summaryResponse: SummaryResponse | undefined;
- switch (actor.kind) {
- case 'agent': {
- const shaShort = commitSha.slice(0, 8);
- const agentProvidedSummary = actor.summary.kind === 'value';
- const effectiveNormalized = agentProvidedSummary
- ? actor.summary
- : normalizeSummary(`Restored to ${shaShort}`);
- const fields = summaryResponseFields(effectiveNormalized);
- summaryResponse =
- agentProvidedSummary || !fields.response
- ? fields.response
- : stripDefaultPathTruncation(fields.response);
- recordContributor(
- docName,
- actor.writerId,
- actor.displayName,
- actor.colorSeed,
- formatRollbackSubject(docName, commitSha),
- actor.actor,
- fields.stored,
- );
- incrementAgentWriteCalls();
- countNormalizedSummary(effectiveNormalized, !agentProvidedSummary);
- break;
- }
- case 'principal': {
- const fields = summaryResponseFields(actor.summary);
- summaryResponse = fields.response;
- recordContributor(
- docName,
- actor.writerId,
- actor.displayName,
- actor.colorSeed,
- formatRollbackSubject(docName, commitSha),
- actor.actor,
- fields.stored,
- );
- countNormalizedSummary(actor.summary, false);
- break;
- }
- case 'anonymous':
- log.debug(
- { docName, commitSha: commitSha.slice(0, 8) },
- '[rollback] anonymous actor — no contributor recorded (no agentId in body and getPrincipal() returned null)',
- );
- break;
- default: {
- const _exhaustive: never = actor;
- throw new Error(
- `Unhandled actor kind in handleRollback: ${String((_exhaustive as { kind?: unknown }).kind)}`,
- );
- }
- }
- renameAttributionCounter().add(1, { kind: 'rollback', attribution_kind: actor.kind });
-
- const flushOutcome = await flushDiskAndDetectOutcome(docName);
- if (flushOutcome?.kind === 'failure') {
- respondPersistenceFailure(res, flushOutcome.failure, 'rollback');
- return;
- }
- if (flushOutcome?.kind === 'divergence') {
- respondDiskDivergence(res, 'rollback');
- return;
- }
- if (flushOutcome?.kind === 'stale-external-write') {
- respondStaleExternalWrite(res, 'rollback', docName);
- return;
- }
-
- flushDocToGit(docName, 'rollback');
-
- const duration = Date.now() - t0;
- getLogger('rollback').info(
- { docName, from: commitSha.slice(0, 8), durationMs: duration },
- 'rollback',
- );
-
- if (actor.kind === 'agent') {
- agentFocusBroadcaster?.setFocus(actor.writerId, {
- agentName: actor.displayName,
- currentDoc: docName,
- writeKind: 'rollback-apply',
- ts: Date.now(),
- });
- }
-
- const rollbackDivergenceEntry =
- rollbackDivergence !== undefined
- ? toContentDivergenceWarning(rollbackDivergence)
- : undefined;
- successResponse(
- res,
- 200,
- RollbackSuccessSchema,
- {
- restoredFrom: commitSha,
- timestamp,
- ...(summaryResponse ? { summary: summaryResponse } : {}),
- ...(rollbackDivergenceEntry ? { warnings: [rollbackDivergenceEntry] } : {}),
- },
- { handler: 'rollback' },
- );
- } catch (e) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to roll back.', {
- handler: 'rollback',
- cause: e,
- });
- }
- },
- { handler: 'rollback', method: 'POST' },
- );
-
- const assetService = createAssetService({
- contentDir,
- isPathIgnored: (relativePath) => contentFilter?.isPathIgnored(relativePath) ?? false,
- getAttachmentFolderPath,
- });
- const ASSET_SERVE_ERRORS = {
- 'missing-path': [400, 'urn:ok:error:invalid-request', 'Missing asset path.'],
- 'unsupported-type': [415, 'urn:ok:error:unsupported-asset-type', 'Unsupported asset type.'],
- 'not-found': [404, 'urn:ok:error:asset-not-found', 'Asset not found.'],
- 'invalid-path': [400, 'urn:ok:error:invalid-request', 'Invalid asset path.'],
- } as const;
-
- const handleAsset = withValidation(
- EmptyRequestSchema,
- async (req, res) => {
- try {
- const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
- const assetPath = url.searchParams.get('path');
- const resolution = assetService.resolveServableAsset(assetPath);
- if (!resolution.ok) {
- const [status, type, title] = ASSET_SERVE_ERRORS[resolution.reason];
- errorResponse(res, status, type, title, {
- handler: 'asset',
- ...(resolution.cause !== undefined ? { cause: resolution.cause } : {}),
- });
+ const handleAsset = withValidation(
+ EmptyRequestSchema,
+ async (req, res) => {
+ try {
+ const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+ const assetPath = url.searchParams.get('path');
+ const resolution = assetService.resolveServableAsset(assetPath);
+ if (!resolution.ok) {
+ const [status, type, title] = ASSET_SERVE_ERRORS[resolution.reason];
+ errorResponse(res, status, type, title, {
+ handler: 'asset',
+ ...(resolution.cause !== undefined ? { cause: resolution.cause } : {}),
+ });
return;
}
const { asset } = resolution;
@@ -6836,37 +5123,16 @@ export function createApiExtension(
'/api/lint/frontmatter-schema': handleWriteFrontmatterSchema,
'/api/lint/fix': handleLintFix,
'/api/agent-write': handleAgentWrite,
- '/api/agent-write-md': handleAgentWriteMd,
'/api/agent-write-batch': handleAgentWriteBatch,
- '/api/frontmatter-patch': handleFrontmatterPatch,
- '/api/agent-patch': handleAgentPatch,
- '/api/agent-undo': handleAgentUndo,
- '/api/agent-activity': handleAgentActivity,
- '/api/agent-burst-diff': handleAgentBurstDiff,
- '/api/save-version': handleSaveVersion,
- '/api/rollback': handleRollback,
'/api/agent-integrations/apply': handleAgentIntegrationsApply,
};
- if (enableTestRoutes) {
- routes['/api/test-reset'] = handleTestReset;
- routes['/api/test-flush-git'] = handleTestFlushGit;
- routes['/api/test-rescan-backlinks'] = handleTestRescanBacklinks;
- routes['/api/test-rescan-files'] = handleTestRescanFiles;
- }
-
const MUTATING_ROUTES: ReadonlySet<string> = new Set([
'/api/lint/markdownlint-config',
'/api/lint/frontmatter-schema',
'/api/lint/fix',
'/api/agent-write',
- '/api/agent-write-md',
'/api/agent-write-batch',
- '/api/frontmatter-patch',
- '/api/agent-patch',
- '/api/agent-undo',
- '/api/save-version',
- '/api/rollback',
'/api/test-reset',
'/api/test-flush-git',
'/api/test-rescan-backlinks',
@@ -7270,7 +5536,67 @@ export function createApiExtension(
bumpSkillsCatalogGen,
signalChannel,
});
+ const agentWriteRoutes = createAgentWriteRoutes({
+ getLinkAdvisoryPolicy,
+ respondStaleExternalWrite,
+ requireNonEmptyDocName,
+ resolveAlias,
+ extractAgentIdentity,
+ docNameExistsWithAnySupportedExtension,
+ contentDir,
+ summaryResponseFields,
+ sessionManager,
+ durabilityState,
+ hocuspocus,
+ options,
+ getBridgeLossReporter,
+ agentPresenceBroadcaster,
+ recordContentDivergenceGate,
+ buildAgentActor,
+ countNormalizedSummary,
+ flushDiskAndDetectOutcome,
+ respondPersistenceFailure,
+ respondDiskDivergence,
+ flushDocToDisk,
+ agentFocusBroadcaster,
+ onAgentWrite,
+ computeOrphanHints,
+ registerWrittenDocInFileIndex,
+ collectAdmittedDocNames,
+ createLinkedFileExists,
+ createLinkedFolderExists,
+ buildReconcileWarning,
+ computeLintViolations,
+ log,
+ flushDocToGit,
+ isSafeDocName,
+ shadowRef,
+ getPrincipal,
+ contentRoot,
+ safeDocPath,
+ getCurrentBranch,
+ docTreePathCandidates,
+ stripDefaultPathTruncation,
+ renameAttributionCounter,
+ });
+ const testRoutes = createTestRoutes({
+ resetDocumentDurability,
+ resolveAlias,
+ contentDir,
+ log,
+ sessionManager,
+ hocuspocus,
+ forceUnloadDocument,
+ derivedDocumentIndex,
+ contentFilter,
+ bumpSkillsCatalogGen,
+ signalChannel,
+ flushGitCommit,
+ rescanFiles,
+ });
const nativeGroups = [
+ agentWriteRoutes,
+ ...(enableTestRoutes ? [testRoutes] : []),
skillsTrackingRoutes,
skillsRecoveryRoutes,
skillsInstallRoutes,
diff --git a/packages/server/src/http/agent-write-routes.test.ts b/packages/server/src/http/agent-write-routes.test.ts
new file mode 100644
index 000000000..b02fb9da4
--- /dev/null
+++ b/packages/server/src/http/agent-write-routes.test.ts
@@ -0,0 +1,132 @@
+import type { IncomingMessage } from 'node:http';
+import { Readable } from 'node:stream';
+import { Hocuspocus } from '@hocuspocus/server';
+import { describe, expect, test } from 'vitest';
+import { AgentSessionManager } from '../agent-sessions.ts';
+import { makeCaptureRes } from '../composition-rig.test-helper.ts';
+import type { DocumentDurabilityState } from '../document-durability-state.ts';
+import { loggerFactory } from '../logger.ts';
+import { createAgentWriteRoutes } from './agent-write-routes.ts';
+
+type Deps = Parameters<typeof createAgentWriteRoutes>[0];
+
+function notDispatched(): never {
+ throw new Error('Dependency is not used by this test');
+}
+
+function buildGroup(overrides: Partial<Deps> = {}) {
+ const deps = {
+ getLinkAdvisoryPolicy: () => ({ links: 'warning', suppressLogLinkAdvisories: false }),
+ respondStaleExternalWrite: notDispatched,
+ requireNonEmptyDocName: (docName) => docName ?? null,
+ resolveAlias: (docName) => docName,
+ extractAgentIdentity: () => ({
+ rawAgentId: 'writer',
+ agentId: 'agent-writer',
+ agentName: 'Writer',
+ colorSeed: 'writer',
+ clientName: undefined,
+ clientVersion: undefined,
+ label: undefined,
+ }),
+ docNameExistsWithAnySupportedExtension: notDispatched,
+ contentDir: '/nonexistent-content',
+ summaryResponseFields: () => ({ stored: undefined }),
+ sessionManager: {} as AgentSessionManager,
+ durabilityState: {} as DocumentDurabilityState,
+ hocuspocus: {} as Hocuspocus,
+ options: {},
+ getBridgeLossReporter: undefined,
+ agentPresenceBroadcaster: undefined,
+ recordContentDivergenceGate: notDispatched,
+ buildAgentActor: notDispatched,
+ countNormalizedSummary: notDispatched,
+ flushDiskAndDetectOutcome: notDispatched,
+ respondPersistenceFailure: notDispatched,
+ respondDiskDivergence: notDispatched,
+ flushDocToDisk: notDispatched,
+ agentFocusBroadcaster: undefined,
+ onAgentWrite: undefined,
+ computeOrphanHints: notDispatched,
+ registerWrittenDocInFileIndex: notDispatched,
+ collectAdmittedDocNames: notDispatched,
+ createLinkedFileExists: notDispatched,
+ createLinkedFolderExists: notDispatched,
+ buildReconcileWarning: notDispatched,
+ computeLintViolations: notDispatched,
+ log: loggerFactory.getLogger('test'),
+ flushDocToGit: notDispatched,
+ isSafeDocName: notDispatched,
+ shadowRef: undefined,
+ getPrincipal: undefined,
+ contentRoot: undefined,
+ safeDocPath: notDispatched,
+ getCurrentBranch: undefined,
+ docTreePathCandidates: notDispatched,
+ stripDefaultPathTruncation: notDispatched,
+ renameAttributionCounter: notDispatched,
+ ...overrides,
+ } satisfies Deps;
+ return createAgentWriteRoutes(deps);
+}
+
+const WRITES = [
+ '/api/agent-write-md',
+ '/api/frontmatter-patch',
+ '/api/agent-patch',
+ '/api/agent-undo',
+ '/api/save-version',
+ '/api/rollback',
+];
+const READS = ['/api/agent-activity', '/api/agent-burst-diff'];
+
+describe('createAgentWriteRoutes table', () => {
+ test('registers exactly the eight agent-write paths', () => {
+ expect([...buildGroup().paths].sort()).toEqual([...WRITES, ...READS].sort());
+ });
+
+ test('classifies the six writes as mutating and the two reads as non-mutating', () => {
+ const { table } = buildGroup();
+ for (const path of WRITES) expect(table.isMutating(path), path).toBe(true);
+ for (const path of READS) expect(table.isMutating(path), path).toBe(false);
+ });
+});
+
+function makeReq(url: string, body: unknown): IncomingMessage {
+ const req = Readable.from(Buffer.from(JSON.stringify(body))) as unknown as IncomingMessage;
+ req.method = 'POST';
+ req.url = url;
+ req.headers = { host: 'localhost', 'content-type': 'application/json' };
+ return req;
+}
+
+describe('agent-write session capacity responses', () => {
+ test.each([
+ ['/api/agent-write-md', { docName: 'note', markdown: '# Note', position: 'replace' }],
+ ['/api/frontmatter-patch', { docName: 'note', patch: { title: 'Note' } }],
+ ['/api/agent-patch', { docName: 'note', find: 'old', replace: 'new' }],
+ ])('%s returns the retryable problem when the session limit is full', async (path, body) => {
+ const hocuspocus = new Hocuspocus({ quiet: true });
+ const sessionManager = new AgentSessionManager(hocuspocus, {
+ maxSessions: 1,
+ minEvictableIdleMs: Number.POSITIVE_INFINITY,
+ });
+ try {
+ await sessionManager.getSession('occupied', 'agent-occupant');
+ const group = buildGroup({ hocuspocus, sessionManager });
+ const route = group.table.resolve(path);
+ if (!route?.dispatch) throw new Error(`${path} did not resolve to a dispatch handler`);
+ const { res, captured } = makeCaptureRes();
+ await route.dispatch(makeReq(path, body), res);
+ expect(captured.status).toBe(503);
+ expect(captured.headers['content-type']).toContain('application/problem+json');
+ expect(captured.headers['retry-after']).toBe('10');
+ expect(JSON.parse(captured.body)).toMatchObject({
+ status: 503,
+ type: 'urn:ok:error:too-many-agent-sessions',
+ });
+ } finally {
+ await sessionManager.closeAll();
+ }
+ });
+});
diff --git a/packages/server/src/http/agent-write-routes.ts b/packages/server/src/http/agent-write-routes.ts
new file mode 100644
index 000000000..d14e32700
--- /dev/null
+++ b/packages/server/src/http/agent-write-routes.ts
@@ -0,0 +1,1681 @@
+import type { ServerResponse } from 'node:http';
+import type { Hocuspocus } from '@hocuspocus/server';
+import {
+ AGENT_ICON_COLORS,
+ AgentActivitySuccessSchema,
+ AgentBurstDiffSuccessSchema,
+ AgentPatchRequestSchema,
+ AgentPatchSuccessSchema,
+ AgentUndoRequestSchema,
+ AgentUndoSuccessSchema,
+ AgentWriteMdRequestSchema,
+ AgentWriteMdSuccessSchema,
+ applyPatchToFm,
+ changedBlockRange,
+ colorFromSeed,
+ composeWithDerivedFrontmatter,
+ type DiskEditReconciledWarning,
+ detectFmRegion,
+ EmptyRequestSchema,
+ FrontmatterPatchRequestSchema,
+ FrontmatterPatchSuccessSchema,
+ type LintViolationWarning,
+ type Principal,
+ prependFrontmatter,
+ RollbackRequestSchema,
+ RollbackSuccessSchema,
+ SaveVersionRequestSchema,
+ SaveVersionSuccessSchema,
+ stripFrontmatter,
+} from '@inkeep/open-knowledge-core';
+import { formatRollbackSubject } from '@inkeep/open-knowledge-core/shadow-repo-layout';
+import { captureEffect } from '../activity-log.ts';
+import { listAgentActivity, synthesizeVersionDiff } from '../agent-activity.ts';
+import type { AgentFocusBroadcaster } from '../agent-focus.ts';
+import { resolveAgentType, validateAgentId } from '../agent-id.ts';
+import type { AgentPresenceBroadcaster } from '../agent-presence.ts';
+import {
+ AgentSessionCapacityError,
+ type AgentSessionManager,
+ type AgentWriteContentDivergence,
+ agentWriteLossDetect,
+ agentWritePreDrain,
+ applyAgentMarkdownWrite,
+ applyAgentUndo,
+ iconFromClientName,
+ prepareAgentMarkdownParse,
+ prepareFrontmatterPatchParse,
+ snapshotBlocks,
+} from '../agent-sessions.ts';
+import {
+ type NormalizedSummary,
+ normalizeSummary,
+ type SummaryResponse,
+} from '../agent-write-summary.ts';
+import { composeAndWriteRawBody, type PrecomputedParse, replaceRawBody } from '../bridge-intake.ts';
+import type { BridgeDeriveLossReporter } from '../bridge-loss-detector.ts';
+import { isConfigDoc, isSystemDoc, SYSTEM_DOC_NAME } from '../cc1-broadcast.ts';
+import { DocInConflictError, isDocInConflict, respondDocInConflict } from '../conflict-errors.ts';
+import {
+ evaluateContentDivergence,
+ toContentDivergenceWarning,
+} from '../content-divergence-gate.ts';
+import { recordContributor } from '../contributor-tracker.ts';
+import {
+ canonicalDocName,
+ docNameToRelativePath,
+ registerDocExtension,
+} from '../doc-extensions.ts';
+import type { DocumentDurabilityState, StoreFailure } from '../document-durability-state.ts';
+import {
+ type ReconcileBeforeWriteResult,
+ reconcileDiskBeforeAgentWrite,
+} from '../external-change.ts';
+import { extractActorIdentity } from '../extract-actor-identity.ts';
+import type { FileIndexEntry } from '../file-watcher.ts';
+import {
+ FrontmatterMalformedError,
+ respondFrontmatterMalformed,
+} from '../frontmatter-malformed-error.ts';
+import { recordFrontmatterEditSurface } from '../frontmatter-telemetry.ts';
+import { type LinkAdvisoryPolicy, projectWriteAdvisoryLinks } from '../link-advisory-policy.ts';
+import { getLogger } from '../logger.ts';
+import { validateMermaidFences } from '../mermaid-validator.ts';
+import { incrementAgentPatchFindMismatches, incrementAgentWriteCalls } from '../metrics.ts';
+import { precomputeParse } from '../parse-pool.ts';
+import {
+ createAncestorShaSetCache,
+ getOrLoadRenameLogIndex,
+ resolveDocPathAtCommit,
+} from '../rename-log.ts';
+import type { PairedWriteOrigin } from '../server-observers.ts';
+import { createVersionOpsService } from '../services/version-ops.ts';
+import {
+ type ShadowRef,
+ safetyCheckpoint,
+ shadowGit,
+ type WriterIdentity,
+} from '../shadow-repo.ts';
+import { getMeter, withSpanSync } from '../telemetry.ts';
+import { computeWriteAdvisoryLinks } from '../write-advisory-links.ts';
+import { type ApiRouteGroup, createApiRouteGroup } 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 const ROLLBACK_ORIGIN = {
+ source: 'local' as const,
+ skipStoreHooks: false,
+ context: { origin: 'rollback-apply', paired: true },
+} as const satisfies PairedWriteOrigin;
+
+let _hintEmittedCounter: ReturnType<ReturnType<typeof getMeter>['createCounter']> | null = null;
+function hintEmittedCounter(): ReturnType<ReturnType<typeof getMeter>['createCounter']> {
+ _hintEmittedCounter ||= getMeter().createCounter('ok.preview_attach.hint_emitted', {
+ description:
+ 'Count of preview-attach hints emitted on write-tool responses when no editor is attached to __system__. Covers both attach-preview-once (URL exists, no browser) and start-ui (no UI running anywhere) variants — the tool side disambiguates via the warning action; the metric name is retained as-is so existing dashboards keep working.',
+ });
+ return _hintEmittedCounter;
+}
+
+let _agentPatchFmTouchCounter: ReturnType<ReturnType<typeof getMeter>['createCounter']> | null =
+ null;
+
+function agentPatchFmTouchCounter(): ReturnType<ReturnType<typeof getMeter>['createCounter']> {
+ _agentPatchFmTouchCounter ||= getMeter().createCounter(
+ 'ok.frontmatter.agent_patch_fm_touch_total',
+ {
+ description:
+ 'Count of agent-patch calls refused for touching the frontmatter region. Bounded labels: result ∈ {rejected, pre_deprecation_passthrough}, reason ∈ {intersect, promoted}. `intersect` is a find that MATCHED inside the existing frontmatter; `promoted` is a byte-0 replace that would CREATE frontmatter on a document that had none. They refuse for opposite reasons, so a spike in one says nothing about the other — the append/prepend surface separates the same pair via the `byte-0-promotion` class on `frontmatter-malformed-write-refused`.',
+ },
+ );
+ return _agentPatchFmTouchCounter;
+}
+
+export interface AgentWriteRouteDeps {
+ getLinkAdvisoryPolicy: () => LinkAdvisoryPolicy;
+ respondStaleExternalWrite: (res: ServerResponse, handler: string, docName: string) => void;
+ requireNonEmptyDocName: (
+ docName: string | undefined,
+ res: ServerResponse,
+ handler: string,
+ ) => string | null;
+ resolveAlias: (docName: string) => string;
+ extractAgentIdentity: (body: Record<string, unknown>) => {
+ rawAgentId: string | undefined;
+ agentId: string;
+ agentName: string;
+ colorSeed: string;
+ clientName: string | undefined;
+ clientVersion: string | undefined;
+ label: string | undefined;
+ };
+ docNameExistsWithAnySupportedExtension: (contentDir: string, docName: string) => boolean;
+ contentDir: string;
+ summaryResponseFields: (normalized: NormalizedSummary) => {
+ response?: SummaryResponse;
+ stored: string | undefined;
+ };
+ sessionManager: AgentSessionManager;
+ durabilityState: DocumentDurabilityState;
+ hocuspocus: Hocuspocus;
+ options: {
+ resolveEmbed?: (basename: string, sourcePath: string) => string | null;
+ };
+ getBridgeLossReporter: (() => BridgeDeriveLossReporter | undefined) | undefined;
+ agentPresenceBroadcaster: AgentPresenceBroadcaster | undefined;
+ recordContentDivergenceGate: (
+ handler: 'agent-write-md' | 'agent-write-batch' | 'agent-patch' | 'rollback',
+ divergence: AgentWriteContentDivergence | undefined,
+ ) => void;
+ buildAgentActor: (args: {
+ clientName: string | undefined;
+ clientVersion?: string;
+ label?: string;
+ }) => {
+ principalId?: string;
+ agentType?: string;
+ clientName?: string;
+ clientVersion?: string;
+ label?: string;
+ };
+ countNormalizedSummary: (normalized: NormalizedSummary, fromDefault?: boolean) => void;
+ flushDiskAndDetectOutcome: (
+ docName: string,
+ ) => Promise<
+ | { kind: 'failure'; failure: StoreFailure }
+ | { kind: 'divergence' }
+ | { kind: 'stale-external-write' }
+ | null
+ >;
+ respondPersistenceFailure: (res: ServerResponse, failure: StoreFailure, handler: string) => void;
+ respondDiskDivergence: (res: ServerResponse, handler: string) => void;
+ flushDocToDisk: (docName: string, label: string) => void;
+ agentFocusBroadcaster: AgentFocusBroadcaster | undefined;
+ onAgentWrite: (() => void) | undefined;
+ computeOrphanHints: (
+ docName: string,
+ ) => Promise<Array<{ type: 'orphan'; parentCandidates: string[]; message: string }> | undefined>;
+ registerWrittenDocInFileIndex: (docName: string, content: string) => void;
+ collectAdmittedDocNames: () => Promise<Set<string>>;
+ createLinkedFileExists: (
+ allFiles?: ReadonlyMap<string, FileIndexEntry>,
+ ) => (contentRootRelativePath: string) => boolean;
+ createLinkedFolderExists: () => (folderPath: string) => boolean;
+ buildReconcileWarning: (
+ reconcile: ReconcileBeforeWriteResult,
+ ) => DiskEditReconciledWarning | undefined;
+ computeLintViolations: (
+ source: string,
+ docName: string,
+ linkPolicy: LinkAdvisoryPolicy,
+ ) => Promise<LintViolationWarning[]>;
+ log: import('../logger.ts').PinoLogger;
+ flushDocToGit: (docName: string, label: string) => void;
+ isSafeDocName: (docName: string) => boolean;
+ shadowRef: ShadowRef | undefined;
+ getPrincipal: (() => Principal | null) | undefined;
+ contentRoot: string | undefined;
+ safeDocPath: (docName: string, contentRoot: string) => { path: string } | { error: string };
+ getCurrentBranch: (() => string | null) | undefined;
+ docTreePathCandidates: (docName: string, contentRoot: string) => readonly string[];
+ stripDefaultPathTruncation: (response: SummaryResponse) => SummaryResponse;
+ renameAttributionCounter: () => ReturnType<ReturnType<typeof getMeter>['createCounter']>;
+}
+
+export function createAgentWriteRoutes(deps: AgentWriteRouteDeps): ApiRouteGroup {
+ const {
+ getLinkAdvisoryPolicy,
+ respondStaleExternalWrite,
+ requireNonEmptyDocName,
+ resolveAlias,
+ extractAgentIdentity,
+ docNameExistsWithAnySupportedExtension,
+ contentDir,
+ summaryResponseFields,
+ sessionManager,
+ durabilityState,
+ hocuspocus,
+ options,
+ getBridgeLossReporter,
+ agentPresenceBroadcaster,
+ recordContentDivergenceGate,
+ buildAgentActor,
+ countNormalizedSummary,
+ flushDiskAndDetectOutcome,
+ respondPersistenceFailure,
+ respondDiskDivergence,
+ flushDocToDisk,
+ agentFocusBroadcaster,
+ onAgentWrite,
+ computeOrphanHints,
+ registerWrittenDocInFileIndex,
+ collectAdmittedDocNames,
+ createLinkedFileExists,
+ createLinkedFolderExists,
+ buildReconcileWarning,
+ computeLintViolations,
+ log,
+ flushDocToGit,
+ isSafeDocName,
+ shadowRef,
+ getPrincipal,
+ contentRoot,
+ safeDocPath,
+ getCurrentBranch,
+ docTreePathCandidates,
+ stripDefaultPathTruncation,
+ renameAttributionCounter,
+ } = deps;
+ const versionOpsService = createVersionOpsService({ getCurrentBranch, contentRoot });
+
+ function getSubscriberCount(docName: string): number {
+ try {
+ const doc = hocuspocus.documents.get(docName);
+ return doc?.connections.size ?? 0;
+ } catch {
+ return 0;
+ }
+ }
+
+ function getSystemSubscriberCount(): number {
+ try {
+ const doc = hocuspocus.documents.get(SYSTEM_DOC_NAME);
+ return doc?.connections.size ?? 0;
+ } catch {
+ return 0;
+ }
+ }
+
+ const handleAgentWriteMd = withValidation(
+ AgentWriteMdRequestSchema,
+ async (_req, res, body) => {
+ try {
+ const linkPolicy = getLinkAdvisoryPolicy();
+ const position = body.position ?? 'append';
+ const effectiveDocName = requireNonEmptyDocName(body.docName, res, 'agent-write-md');
+ if (effectiveDocName === null) return;
+ const resolvedDocName = canonicalDocName(resolveAlias(effectiveDocName));
+ const { agentId, agentName, colorSeed, clientName, clientVersion, label } =
+ extractAgentIdentity(body);
+ if (isSystemDoc(resolvedDocName) || isConfigDoc(resolvedDocName)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:reserved-doc-name',
+ `'${resolvedDocName}' is a reserved document name.`,
+ { handler: 'agent-write-md' },
+ );
+ return;
+ }
+ if (
+ body.extension !== undefined &&
+ !docNameExistsWithAnySupportedExtension(contentDir, resolvedDocName)
+ ) {
+ registerDocExtension(resolvedDocName, body.extension);
+ }
+ const normalizedSummary = normalizeSummary(body.summary);
+ const { response: summaryResponse, stored: storedSummary } =
+ summaryResponseFields(normalizedSummary);
+ const session = await sessionManager.getSession(resolvedDocName, agentId, {
+ displayName: agentName,
+ colorSeed,
+ clientName,
+ });
+ const writeMdReconcile = reconcileDiskBeforeAgentWrite(
+ durabilityState,
+ hocuspocus,
+ resolvedDocName,
+ contentDir,
+ options.resolveEmbed,
+ getBridgeLossReporter?.(),
+ );
+ const writeMdEmbedResolver = options.resolveEmbed
+ ? { resolveEmbed: options.resolveEmbed, sourcePath: resolvedDocName }
+ : undefined;
+ const writeMdPrecomputed = await prepareAgentMarkdownParse(
+ session.dc.document,
+ body.markdown,
+ position,
+ writeMdEmbedResolver,
+ );
+ const timestamp = new Date().toISOString();
+ let writeDivergence: AgentWriteContentDivergence | undefined;
+ let disposeEffectCapture: (() => void) | undefined;
+ try {
+ const icon = iconFromClientName(clientName);
+ const color = AGENT_ICON_COLORS[icon] ?? colorFromSeed(colorSeed ?? agentId);
+ agentPresenceBroadcaster?.setPresence(agentId, {
+ displayName: agentName,
+ icon,
+ color,
+ currentDoc: resolvedDocName,
+ mode: 'writing',
+ ts: Date.now(),
+ });
+ disposeEffectCapture = captureEffect(
+ session.dc.document.getText('source'),
+ agentId,
+ session.origin,
+ colorSeed,
+ clientName,
+ );
+ agentWritePreDrain(session.dc.document, body.markdown, position);
+ session.dc.document.transact(() => {
+ const beforeBlocks = snapshotBlocks(session.dc.document);
+ writeDivergence = applyAgentMarkdownWrite(
+ session.dc.document,
+ body.markdown,
+ position,
+ writeMdEmbedResolver,
+ writeMdPrecomputed,
+ agentWriteLossDetect(session),
+ );
+ const changedBlocks =
+ changedBlockRange(beforeBlocks, snapshotBlocks(session.dc.document)) ?? undefined;
+ const activityMap = session.dc.document.getMap('agent-flash');
+ activityMap.set(agentId, {
+ agentId,
+ timestamp: Date.now(),
+ type: 'insert',
+ description: `Added (${agentName}): ${body.markdown.trim().slice(0, 50)}`,
+ ...(changedBlocks !== undefined ? { changedBlocks } : {}),
+ });
+ }, session.origin);
+ if (writeDivergence !== undefined) {
+ console.warn(
+ JSON.stringify({
+ event: 'agent-write-content-divergence',
+ 'doc.name': resolvedDocName,
+ position,
+ intendedBytes: writeDivergence.intendedBytes,
+ actualBytes: writeDivergence.actualBytes,
+ byteDelta: writeDivergence.byteDelta,
+ 'agent.id': agentId,
+ 'agent.client_name': clientName,
+ }),
+ );
+ }
+ recordContentDivergenceGate('agent-write-md', writeDivergence);
+ recordContributor(
+ resolvedDocName,
+ agentId,
+ agentName,
+ colorSeed,
+ undefined,
+ buildAgentActor({ clientName, clientVersion, label }),
+ storedSummary,
+ );
+ incrementAgentWriteCalls();
+ countNormalizedSummary(normalizedSummary);
+ } finally {
+ disposeEffectCapture?.();
+ agentPresenceBroadcaster?.touchMode(agentId, 'idle');
+ }
+ const flushOutcome = await flushDiskAndDetectOutcome(resolvedDocName);
+ if (flushOutcome?.kind === 'failure') {
+ respondPersistenceFailure(res, flushOutcome.failure, 'agent-write-md');
+ return;
+ }
+ if (flushOutcome?.kind === 'divergence') {
+ respondDiskDivergence(res, 'agent-write-md');
+ return;
+ }
+ if (flushOutcome?.kind === 'stale-external-write') {
+ respondStaleExternalWrite(res, 'agent-write-md', resolvedDocName);
+ return;
+ }
+ flushDocToDisk(resolvedDocName, 'agent-write-md');
+ agentFocusBroadcaster?.setFocus(agentId, {
+ agentName,
+ currentDoc: resolvedDocName,
+ writeKind: 'write',
+ ts: Date.now(),
+ });
+ onAgentWrite?.();
+ const hints = await computeOrphanHints(resolvedDocName);
+ const writtenSource = session.dc.document.getText('source').toString();
+ registerWrittenDocInFileIndex(resolvedDocName, writtenSource);
+ const renderWarnings = await validateMermaidFences(writtenSource, resolvedDocName);
+ const admittedForLinks = await collectAdmittedDocNames();
+ admittedForLinks.add(resolvedDocName);
+ const linkAdvisory = projectWriteAdvisoryLinks(
+ computeWriteAdvisoryLinks(
+ writtenSource,
+ resolvedDocName,
+ admittedForLinks,
+ createLinkedFileExists(),
+ createLinkedFolderExists(),
+ ),
+ resolvedDocName,
+ linkPolicy.suppressLogLinkAdvisories,
+ );
+ const subscriberCount = getSubscriberCount(resolvedDocName);
+ const systemSubscriberCount = getSystemSubscriberCount();
+ if (systemSubscriberCount === 0) {
+ hintEmittedCounter().add(1, {
+ 'shadow.writer': 'agent',
+ 'agent.type': resolveAgentType(clientName),
+ });
+ }
+ const writeMdWarning = buildReconcileWarning(writeMdReconcile);
+ const writeMdDivergenceEntry =
+ writeDivergence !== undefined ? toContentDivergenceWarning(writeDivergence) : undefined;
+ const writeMdAdvisories = [
+ ...(writeMdDivergenceEntry ? [writeMdDivergenceEntry] : []),
+ ...(writeMdWarning ? [writeMdWarning] : []),
+ ...(renderWarnings ?? []),
+ ...(await computeLintViolations(
+ session.dc.document.getText('source').toString(),
+ resolvedDocName,
+ linkPolicy,
+ )),
+ ];
+ successResponse(
+ res,
+ 200,
+ AgentWriteMdSuccessSchema,
+ {
+ timestamp,
+ subscriberCount,
+ systemSubscriberCount,
+ ...(hints ? { hints } : {}),
+ ...(summaryResponse ? { summary: summaryResponse } : {}),
+ ...(writeMdAdvisories.length > 0 ? { warnings: writeMdAdvisories } : {}),
+ ...linkAdvisory,
+ },
+ { handler: 'agent-write-md' },
+ );
+ } catch (e) {
+ if (e instanceof DocInConflictError) {
+ respondDocInConflict(res, e, 'agent-write-md');
+ return;
+ }
+ if (e instanceof FrontmatterMalformedError) {
+ respondFrontmatterMalformed(res, e, 'agent-write-md');
+ return;
+ }
+ if (e instanceof AgentSessionCapacityError) {
+ errorResponse(
+ res,
+ 503,
+ 'urn:ok:error:too-many-agent-sessions',
+ 'Too many agent sessions.',
+ { handler: 'agent-write-md', cause: e, extraHeaders: { 'Retry-After': '10' } },
+ );
+ return;
+ }
+ log.error({ err: e, requestId: getRequestId(_req) }, '[agent-write-md] handler failed');
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'agent-write-md',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'agent-write-md', method: 'POST' },
+ );
+
+ const handleFrontmatterPatch = withValidation(
+ FrontmatterPatchRequestSchema,
+ async (_req, res, body) => {
+ try {
+ const linkPolicy = getLinkAdvisoryPolicy();
+ const effectiveDocName = requireNonEmptyDocName(body.docName, res, 'frontmatter-patch');
+ if (effectiveDocName === null) return;
+ const resolvedDocName = resolveAlias(effectiveDocName);
+ const { agentId, agentName, colorSeed, clientName, clientVersion, label } =
+ extractAgentIdentity(body);
+ if (isSystemDoc(resolvedDocName) || isConfigDoc(resolvedDocName)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:reserved-doc-name',
+ `'${resolvedDocName}' is a reserved document name.`,
+ { handler: 'frontmatter-patch' },
+ );
+ return;
+ }
+ const patch = body.patch ?? {};
+ const patchKeys = Object.keys(patch);
+ const normalizedSummary = normalizeSummary(body.summary);
+ const { response: summaryResponse, stored: storedSummary } =
+ summaryResponseFields(normalizedSummary);
+ const session = await sessionManager.getSession(resolvedDocName, agentId, {
+ displayName: agentName,
+ colorSeed,
+ clientName,
+ });
+ const fmReconcile = reconcileDiskBeforeAgentWrite(
+ durabilityState,
+ hocuspocus,
+ resolvedDocName,
+ contentDir,
+ options.resolveEmbed,
+ getBridgeLossReporter?.(),
+ );
+ const fmPatchPrecomputed = await prepareFrontmatterPatchParse(session.dc.document, patch);
+ const timestamp = new Date().toISOString();
+ let editError: import('@inkeep/open-knowledge-core').FmEditError | undefined;
+ let applied = false;
+ let bodyMutated = false;
+ const appliedKeys: string[] = [];
+ try {
+ const icon = iconFromClientName(clientName);
+ const color = AGENT_ICON_COLORS[icon] ?? colorFromSeed(colorSeed ?? agentId);
+ agentPresenceBroadcaster?.setPresence(agentId, {
+ displayName: agentName,
+ icon,
+ color,
+ currentDoc: resolvedDocName,
+ mode: 'writing',
+ ts: Date.now(),
+ });
+ withSpanSync(
+ 'ok.frontmatter_patch',
+ {
+ attributes: {
+ 'doc.name': resolvedDocName,
+ 'frontmatter_patch.keys': patchKeys.length,
+ },
+ },
+ () => {
+ session.dc.document.transact(() => {
+ const ytext = session.dc.document.getText('source');
+ const currentFull = ytext.toString();
+ const { fenced: currentFenced, body: currentBody } = detectFmRegion(currentFull);
+ const result = applyPatchToFm(currentFenced, patch);
+ if (!result.ok) {
+ editError = result.error;
+ return;
+ }
+ for (const key of Object.keys(patch)) {
+ appliedKeys.push(key);
+ }
+ if (result.nextFenced !== currentFenced) {
+ /**
+ * Routed through the sanctioned `composeAndWriteRawBody` primitive
+ * (precedent #38) so paired-write semantics survive.
+ */
+ const needsFenceSeparator =
+ currentFenced === '' && currentBody !== '' && !currentBody.startsWith('\n');
+ const newFull = composeWithDerivedFrontmatter(
+ result.nextFenced,
+ (needsFenceSeparator ? '\n' : '') + currentBody,
+ ).md;
+ composeAndWriteRawBody(
+ session.dc.document,
+ newFull,
+ 'agent',
+ undefined,
+ fmPatchPrecomputed,
+ );
+ recordFrontmatterEditSurface('mcp-write');
+ bodyMutated = true;
+ }
+ applied = true;
+ }, session.origin);
+ },
+ );
+ } finally {
+ agentPresenceBroadcaster?.touchMode(agentId, 'idle');
+ }
+ if (editError) {
+ let fieldErrors: Record<string, string>;
+ switch (editError.kind) {
+ case 'invalid_value':
+ fieldErrors = { [editError.key]: editError.reason };
+ break;
+ case 'reserved_key':
+ fieldErrors = { [editError.key]: `'${editError.key}' is reserved` };
+ break;
+ case 'unknown_key':
+ fieldErrors = { [editError.key]: `'${editError.key}' is not a recognized key` };
+ break;
+ case 'duplicate_target':
+ fieldErrors = { [editError.key]: `'${editError.key}' appears more than once` };
+ break;
+ case 'reorder_mismatch':
+ fieldErrors = {
+ __region__: `frontmatter reorder mismatch (expected: ${editError.expected.join(', ')}; got: ${editError.got.join(', ')})`,
+ };
+ break;
+ case 'region_too_large':
+ fieldErrors = {
+ __region__: `frontmatter region too large (${editError.bytes} > ${editError.limit} bytes)`,
+ };
+ break;
+ case 'parse_failed':
+ fieldErrors = { __region__: `frontmatter region unparseable: ${editError.reason}` };
+ break;
+ case 'invalid_path':
+ fieldErrors = {
+ [editError.path.map(String).join('.') || '__path__']: editError.reason,
+ };
+ break;
+ default: {
+ const _exhaustive: never = editError;
+ fieldErrors = {
+ __region__: `unhandled frontmatter edit error (${String(_exhaustive)})`,
+ };
+ }
+ }
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-frontmatter-patch',
+ 'Frontmatter patch rejected: schema validation failed.',
+ { handler: 'frontmatter-patch', extensions: { fieldErrors } },
+ );
+ return;
+ }
+ if (applied && appliedKeys.length > 0) {
+ recordContributor(
+ resolvedDocName,
+ agentId,
+ agentName,
+ colorSeed,
+ undefined,
+ buildAgentActor({ clientName, clientVersion, label }),
+ storedSummary,
+ );
+ incrementAgentWriteCalls();
+ countNormalizedSummary(normalizedSummary);
+ if (bodyMutated) {
+ const flushOutcome = await flushDiskAndDetectOutcome(resolvedDocName);
+ if (flushOutcome?.kind === 'failure') {
+ respondPersistenceFailure(res, flushOutcome.failure, 'frontmatter-patch');
+ return;
+ }
+ if (flushOutcome?.kind === 'divergence') {
+ respondDiskDivergence(res, 'frontmatter-patch');
+ return;
+ }
+ if (flushOutcome?.kind === 'stale-external-write') {
+ respondStaleExternalWrite(res, 'frontmatter-patch', resolvedDocName);
+ return;
+ }
+ }
+ flushDocToDisk(resolvedDocName, 'frontmatter-patch');
+ }
+ agentFocusBroadcaster?.setFocus(agentId, {
+ agentName,
+ currentDoc: resolvedDocName,
+ writeKind: 'write',
+ ts: Date.now(),
+ });
+ onAgentWrite?.();
+ const subscriberCount = getSubscriberCount(resolvedDocName);
+ const systemSubscriberCount = getSystemSubscriberCount();
+ if (systemSubscriberCount === 0) {
+ hintEmittedCounter().add(1, {
+ 'shadow.writer': 'agent',
+ 'agent.type': resolveAgentType(clientName),
+ });
+ }
+ const fmWarning = buildReconcileWarning(fmReconcile);
+ registerWrittenDocInFileIndex(
+ resolvedDocName,
+ session.dc.document.getText('source').toString(),
+ );
+ const admittedForLinks = await collectAdmittedDocNames();
+ admittedForLinks.add(resolvedDocName);
+ const linkAdvisory = projectWriteAdvisoryLinks(
+ computeWriteAdvisoryLinks(
+ session.dc.document.getText('source').toString(),
+ resolvedDocName,
+ admittedForLinks,
+ createLinkedFileExists(),
+ ),
+ resolvedDocName,
+ linkPolicy.suppressLogLinkAdvisories,
+ );
+ successResponse(
+ res,
+ 200,
+ FrontmatterPatchSuccessSchema,
+ {
+ timestamp,
+ subscriberCount,
+ systemSubscriberCount,
+ appliedKeys,
+ ...(summaryResponse ? { summary: summaryResponse } : {}),
+ ...(fmWarning ? { warnings: [fmWarning] } : {}),
+ ...linkAdvisory,
+ },
+ { handler: 'frontmatter-patch' },
+ );
+ } catch (e) {
+ if (e instanceof AgentSessionCapacityError) {
+ errorResponse(
+ res,
+ 503,
+ 'urn:ok:error:too-many-agent-sessions',
+ 'Too many agent sessions.',
+ { handler: 'frontmatter-patch', cause: e, extraHeaders: { 'Retry-After': '10' } },
+ );
+ return;
+ }
+ log.error({ err: e, requestId: getRequestId(_req) }, '[frontmatter-patch] handler failed');
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'frontmatter-patch',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'frontmatter-patch', method: 'POST' },
+ );
+
+ const handleAgentPatch = withValidation(
+ AgentPatchRequestSchema,
+ async (_req, res, body) => {
+ try {
+ const linkPolicy = getLinkAdvisoryPolicy();
+ const { find, replace, offset } = body;
+ const effectivePatchDocName = requireNonEmptyDocName(body.docName, res, 'agent-patch');
+ if (effectivePatchDocName === null) return;
+ const docName = resolveAlias(effectivePatchDocName);
+ const { agentId, agentName, colorSeed, clientName, clientVersion, label } =
+ extractAgentIdentity(body);
+ if (isSystemDoc(docName) || isConfigDoc(docName)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:reserved-doc-name',
+ `'${docName}' is a reserved document name.`,
+ { handler: 'agent-patch' },
+ );
+ return;
+ }
+ const normalizedSummary = normalizeSummary(body.summary);
+ const session = await sessionManager.getSession(docName, agentId, {
+ displayName: agentName,
+ colorSeed,
+ clientName,
+ });
+ const patchReconcile = reconcileDiskBeforeAgentWrite(
+ durabilityState,
+ hocuspocus,
+ docName,
+ contentDir,
+ options.resolveEmbed,
+ getBridgeLossReporter?.(),
+ );
+ const patchEmbedResolver = options.resolveEmbed
+ ? { resolveEmbed: options.resolveEmbed, sourcePath: docName }
+ : undefined;
+ let patchPrecomputed: PrecomputedParse | undefined;
+ {
+ const preSnapshot = session.dc.document.getText('source').toString();
+ const { frontmatter: preFm, body: preBody } = stripFrontmatter(preSnapshot);
+ const preFull = prependFrontmatter(preFm, preBody);
+ const prePos =
+ offset == null
+ ? preFull.indexOf(find)
+ : preFull.slice(offset, offset + find.length) === find
+ ? offset
+ : -1;
+ if (prePos !== -1 && prePos >= preFm.length) {
+ const guessFull =
+ preFull.slice(0, prePos) + replace + preFull.slice(prePos + find.length);
+ patchPrecomputed = await prepareAgentMarkdownParse(
+ session.dc.document,
+ stripFrontmatter(guessFull).body,
+ 'patch',
+ patchEmbedResolver,
+ );
+ }
+ }
+ const timestamp = new Date().toISOString();
+ let notFound = false;
+ let staleTarget = false;
+ let fmIntersect = false;
+ let fmPromoted = false;
+ let patchDivergence: AgentWriteContentDivergence | undefined;
+ let disposeEffectCapture: (() => void) | undefined;
+ try {
+ const icon = iconFromClientName(clientName);
+ const color = AGENT_ICON_COLORS[icon] ?? colorFromSeed(colorSeed ?? agentId);
+ agentPresenceBroadcaster?.setPresence(agentId, {
+ displayName: agentName,
+ icon,
+ color,
+ currentDoc: docName,
+ mode: 'writing',
+ ts: Date.now(),
+ });
+ disposeEffectCapture = captureEffect(
+ session.dc.document.getText('source'),
+ agentId,
+ session.origin,
+ colorSeed,
+ clientName,
+ );
+ session.dc.document.transact(() => {
+ /**
+ * Read current authoritative state from Y.Text, the user's intended source-form bytes
+ * (Y.Text-is-truth, precedent #38); `serialize(fragment)` would compute offsets against
+ * canonical bytes instead.
+ */
+ const ytextSnapshot = session.dc.document.getText('source').toString();
+ const { frontmatter: currentFm, body: currentBody } = stripFrontmatter(ytextSnapshot);
+ const currentFull = prependFrontmatter(currentFm, currentBody);
+ const pos =
+ offset == null
+ ? currentFull.indexOf(find)
+ : currentFull.slice(offset, offset + find.length) === find
+ ? offset
+ : -1;
+ if (pos === -1) {
+ if (offset == null) {
+ notFound = true;
+ } else {
+ staleTarget = true;
+ }
+ console.warn(
+ JSON.stringify({
+ event: 'agent-patch-find-mismatch',
+ 'doc.name': docName,
+ findLength: find.length,
+ replaceLength: replace.length,
+ hadOffset: offset != null,
+ }),
+ );
+ incrementAgentPatchFindMismatches();
+ return;
+ }
+ if (pos < currentFm.length) {
+ fmIntersect = true;
+ return;
+ }
+ const newFull =
+ currentFull.slice(0, pos) + replace + currentFull.slice(pos + find.length);
+ if (currentFm === '' && stripFrontmatter(newFull).frontmatter !== '') {
+ fmPromoted = true;
+ return;
+ }
+ const { body: newBody } = stripFrontmatter(newFull);
+ const beforeBlocks = snapshotBlocks(session.dc.document);
+ patchDivergence = applyAgentMarkdownWrite(
+ session.dc.document,
+ newBody,
+ 'patch',
+ patchEmbedResolver,
+ patchPrecomputed,
+ agentWriteLossDetect(session),
+ );
+ const changedBlocks =
+ changedBlockRange(beforeBlocks, snapshotBlocks(session.dc.document)) ?? undefined;
+ const activityMap = session.dc.document.getMap('agent-flash');
+ activityMap.set(agentId, {
+ agentId,
+ timestamp: Date.now(),
+ type: 'insert',
+ description: `Patched (${agentName}): ${find.slice(0, 50)}`,
+ ...(changedBlocks !== undefined ? { changedBlocks } : {}),
+ });
+ }, session.origin);
+ if (patchDivergence !== undefined) {
+ console.warn(
+ JSON.stringify({
+ event: 'agent-write-content-divergence',
+ 'doc.name': docName,
+ position: 'patch',
+ intendedBytes: patchDivergence.intendedBytes,
+ actualBytes: patchDivergence.actualBytes,
+ byteDelta: patchDivergence.byteDelta,
+ 'agent.id': agentId,
+ 'agent.client_name': clientName,
+ }),
+ );
+ }
+ if (!notFound && !staleTarget && !fmIntersect && !fmPromoted) {
+ const { stored: storedSummary } = summaryResponseFields(normalizedSummary);
+ recordContributor(
+ docName,
+ agentId,
+ agentName,
+ colorSeed,
+ undefined,
+ buildAgentActor({ clientName, clientVersion, label }),
+ storedSummary,
+ );
+ incrementAgentWriteCalls();
+ countNormalizedSummary(normalizedSummary);
+ recordContentDivergenceGate('agent-patch', patchDivergence);
+ }
+ } finally {
+ disposeEffectCapture?.();
+ agentPresenceBroadcaster?.touchMode(agentId, 'idle');
+ }
+ if (staleTarget) {
+ errorResponse(
+ res,
+ 409,
+ 'urn:ok:error:stale-target',
+ 'Target text no longer matches at the requested offset.',
+ { handler: 'agent-patch' },
+ );
+ return;
+ }
+ if (notFound) {
+ errorResponse(res, 404, 'urn:ok:error:target-not-found', 'Text not found in document.', {
+ handler: 'agent-patch',
+ });
+ return;
+ }
+ if (fmIntersect) {
+ agentPatchFmTouchCounter().add(1, { result: 'rejected', reason: 'intersect' });
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:frontmatter-edit-not-supported',
+ 'Frontmatter edits are not supported via a body find/replace. Use edit({ document: { path, frontmatter } }) to change frontmatter, or write({ document: { path, content, position: "replace" } }) to rewrite the whole document including its YAML block.',
+ { handler: 'agent-patch' },
+ );
+ return;
+ }
+ if (fmPromoted) {
+ agentPatchFmTouchCounter().add(1, { result: 'rejected', reason: 'promoted' });
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:frontmatter-edit-not-supported',
+ "This edit would turn the replacement text into the document's frontmatter: the document has no frontmatter, the match starts at byte 0, and `replace` opens a `---` fence pair — so the composed document would re-read that block as its YAML region. Use edit({ document: { path, frontmatter } }) to set frontmatter, or keep the `---` out of the first line (a leading blank line, or `***` / `___` for a thematic break).",
+ { handler: 'agent-patch' },
+ );
+ return;
+ }
+ const flushOutcome = await flushDiskAndDetectOutcome(docName);
+ if (flushOutcome?.kind === 'failure') {
+ respondPersistenceFailure(res, flushOutcome.failure, 'agent-patch');
+ return;
+ }
+ if (flushOutcome?.kind === 'divergence') {
+ respondDiskDivergence(res, 'agent-patch');
+ return;
+ }
+ if (flushOutcome?.kind === 'stale-external-write') {
+ respondStaleExternalWrite(res, 'agent-patch', docName);
+ return;
+ }
+ flushDocToDisk(docName, 'agent-patch');
+ agentFocusBroadcaster?.setFocus(agentId, {
+ agentName,
+ currentDoc: docName,
+ writeKind: 'edit',
+ ts: Date.now(),
+ });
+ onAgentWrite?.();
+ const subscriberCount = getSubscriberCount(docName);
+ const systemSubscriberCount = getSystemSubscriberCount();
+ if (systemSubscriberCount === 0) {
+ hintEmittedCounter().add(1, {
+ 'shadow.writer': 'agent',
+ 'agent.type': resolveAgentType(clientName),
+ });
+ }
+ const { response: summaryResponse } = summaryResponseFields(normalizedSummary);
+ const patchedSource = session.dc.document.getText('source').toString();
+ registerWrittenDocInFileIndex(docName, patchedSource);
+ const renderWarnings = await validateMermaidFences(patchedSource, docName);
+ const admittedForLinks = await collectAdmittedDocNames();
+ admittedForLinks.add(docName);
+ const linkAdvisory = projectWriteAdvisoryLinks(
+ computeWriteAdvisoryLinks(
+ patchedSource,
+ docName,
+ admittedForLinks,
+ createLinkedFileExists(),
+ ),
+ docName,
+ linkPolicy.suppressLogLinkAdvisories,
+ );
+ const patchWarning = buildReconcileWarning(patchReconcile);
+ const patchDivergenceEntry =
+ patchDivergence !== undefined ? toContentDivergenceWarning(patchDivergence) : undefined;
+ const patchAdvisories = [
+ ...(patchDivergenceEntry ? [patchDivergenceEntry] : []),
+ ...(patchWarning ? [patchWarning] : []),
+ ...(renderWarnings ?? []),
+ ...(await computeLintViolations(
+ session.dc.document.getText('source').toString(),
+ docName,
+ linkPolicy,
+ )),
+ ];
+ successResponse(
+ res,
+ 200,
+ AgentPatchSuccessSchema,
+ {
+ timestamp,
+ subscriberCount,
+ systemSubscriberCount,
+ ...(summaryResponse ? { summary: summaryResponse } : {}),
+ ...(patchAdvisories.length > 0 ? { warnings: patchAdvisories } : {}),
+ ...linkAdvisory,
+ },
+ { handler: 'agent-patch' },
+ );
+ } catch (e) {
+ if (e instanceof DocInConflictError) {
+ respondDocInConflict(res, e, 'agent-patch');
+ return;
+ }
+ if (e instanceof FrontmatterMalformedError) {
+ respondFrontmatterMalformed(res, e, 'agent-patch');
+ return;
+ }
+ if (e instanceof AgentSessionCapacityError) {
+ errorResponse(
+ res,
+ 503,
+ 'urn:ok:error:too-many-agent-sessions',
+ 'Too many agent sessions.',
+ { handler: 'agent-patch', cause: e, extraHeaders: { 'Retry-After': '10' } },
+ );
+ return;
+ }
+ log.error({ err: e, requestId: getRequestId(_req) }, '[agent-patch] handler failed');
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'agent-patch',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'agent-patch', method: 'POST' },
+ );
+
+ const handleAgentUndo = withValidation(
+ AgentUndoRequestSchema,
+ async (_req, res, body) => {
+ try {
+ const rawDocName = requireNonEmptyDocName(body.docName, res, 'agent-undo');
+ if (rawDocName === null) return;
+ const docName = resolveAlias(rawDocName);
+ const { agentId, agentName, colorSeed, clientName, clientVersion, label } =
+ extractAgentIdentity(body);
+ if (isSystemDoc(docName) || isConfigDoc(docName)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:reserved-doc-name',
+ `'${docName}' is a reserved document name.`,
+ { handler: 'agent-undo' },
+ );
+ return;
+ }
+ const { connectionId } = body;
+ let scope: 'last' | 'session' | 'count';
+ let count: number | undefined;
+ if (body.scope === 'count') {
+ scope = 'count';
+ count = body.count;
+ } else if (body.scope === 'session' || body.scope === 'file') {
+ scope = 'session';
+ } else {
+ scope = 'last';
+ }
+ if (!sessionManager.hasSession(docName, connectionId)) {
+ errorResponse(
+ res,
+ 404,
+ 'urn:ok:error:no-active-session',
+ 'No active session for this connectionId and docName.',
+ { handler: 'agent-undo' },
+ );
+ return;
+ }
+ const session = await sessionManager.getSession(docName, connectionId);
+ let undone = false;
+ try {
+ const icon = iconFromClientName(clientName);
+ const color = AGENT_ICON_COLORS[icon] ?? colorFromSeed(colorSeed ?? agentId);
+ agentPresenceBroadcaster?.setPresence(agentId, {
+ displayName: agentName,
+ icon,
+ color,
+ currentDoc: docName,
+ mode: 'writing',
+ ts: Date.now(),
+ });
+ undone = applyAgentUndo(
+ session,
+ scope,
+ options.resolveEmbed
+ ? { resolveEmbed: options.resolveEmbed, sourcePath: docName }
+ : undefined,
+ count,
+ );
+ if (undone) {
+ recordContributor(
+ docName,
+ connectionId,
+ agentName,
+ colorSeed,
+ undefined,
+ buildAgentActor({ clientName, clientVersion, label }),
+ );
+ }
+ } finally {
+ agentPresenceBroadcaster?.touchMode(agentId, 'idle');
+ }
+ if (undone) {
+ const flushOutcome = await flushDiskAndDetectOutcome(docName);
+ if (flushOutcome?.kind === 'failure') {
+ respondPersistenceFailure(res, flushOutcome.failure, 'agent-undo');
+ return;
+ }
+ if (flushOutcome?.kind === 'divergence') {
+ respondDiskDivergence(res, 'agent-undo');
+ return;
+ }
+ if (flushOutcome?.kind === 'stale-external-write') {
+ respondStaleExternalWrite(res, 'agent-undo', docName);
+ return;
+ }
+ flushDocToGit(docName, 'agent-undo');
+ }
+ agentFocusBroadcaster?.setFocus(connectionId, {
+ agentName: connectionId,
+ currentDoc: docName,
+ writeKind: 'undo',
+ ts: Date.now(),
+ });
+ successResponse(
+ res,
+ 200,
+ AgentUndoSuccessSchema,
+ { docName, scope, undone },
+ { handler: 'agent-undo' },
+ );
+ } catch (e) {
+ if (e instanceof DocInConflictError) {
+ respondDocInConflict(res, e, 'agent-undo');
+ return;
+ }
+ log.error({ err: e, requestId: getRequestId(_req) }, '[agent-undo] handler failed');
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'agent-undo',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'agent-undo', method: 'POST' },
+ );
+
+ const handleAgentActivity = withValidation(
+ EmptyRequestSchema,
+ async (req, res) => {
+ try {
+ const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+ const agentId = validateAgentId(url.searchParams.get('agentId'));
+ if (agentId === null) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'agentId required (alphanumeric/_/- only).',
+ { handler: 'agent-activity' },
+ );
+ return;
+ }
+ const result = listAgentActivity(sessionManager, agentId);
+ successResponse(res, 200, AgentActivitySuccessSchema, result, {
+ handler: 'agent-activity',
+ });
+ } catch (e) {
+ log.error({ err: e, requestId: getRequestId(req) }, '[agent-activity] handler failed');
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'agent-activity',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'agent-activity', method: 'GET', skipBodyParse: true },
+ );
+
+ const handleAgentBurstDiff = withValidation(
+ EmptyRequestSchema,
+ async (req, res) => {
+ try {
+ const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+ const agentId = validateAgentId(url.searchParams.get('agentId'));
+ const rawDocName = url.searchParams.get('docName');
+ const keptCountStr = url.searchParams.get('keptCount');
+ if (agentId === null) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'agentId required (alphanumeric/_/- only).',
+ { handler: 'agent-burst-diff' },
+ );
+ return;
+ }
+ if (!rawDocName || rawDocName.trim() === '') {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docName parameter.', {
+ handler: 'agent-burst-diff',
+ });
+ return;
+ }
+ if (!isSafeDocName(rawDocName)) {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {
+ handler: 'agent-burst-diff',
+ });
+ return;
+ }
+ const docName = resolveAlias(rawDocName);
+ if (isSystemDoc(docName) || isConfigDoc(docName)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:reserved-doc-name',
+ `'${docName}' is a reserved document name.`,
+ { handler: 'agent-burst-diff' },
+ );
+ return;
+ }
+ if (!keptCountStr || Number.isNaN(Number(keptCountStr))) {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'keptCount must be a number.', {
+ handler: 'agent-burst-diff',
+ });
+ return;
+ }
+ const keptCount = Number(keptCountStr);
+ if (!Number.isInteger(keptCount) || keptCount < 0) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'keptCount must be a non-negative integer.',
+ { handler: 'agent-burst-diff' },
+ );
+ return;
+ }
+ const session = sessionManager.getLiveSession(docName, agentId);
+ if (!session) {
+ errorResponse(
+ res,
+ 404,
+ 'urn:ok:error:no-active-session',
+ 'No active session for this agentId and docName.',
+ { handler: 'agent-burst-diff' },
+ );
+ return;
+ }
+ const um = session.um;
+ if (keptCount > um.undoStack.length) {
+ errorResponse(
+ res,
+ 404,
+ 'urn:ok:error:not-found',
+ `keptCount ${keptCount} out of range (stack has ${um.undoStack.length} items).`,
+ { handler: 'agent-burst-diff' },
+ );
+ return;
+ }
+ const ytext = session.dc.document.getText('source');
+ const { diff, before, after, properties } = synthesizeVersionDiff(
+ // biome-ignore lint/suspicious/noExplicitAny: Y.StackItem is internal to yjs — structural shape matches YjsStackItemShape in agent-activity.ts
+ um.undoStack as any,
+ keptCount,
+ ytext,
+ docName,
+ );
+ successResponse(
+ res,
+ 200,
+ AgentBurstDiffSuccessSchema,
+ { diff, before, after, properties, generatedAt: Date.now() },
+ { handler: 'agent-burst-diff' },
+ );
+ } catch (e) {
+ log.error({ err: e, requestId: getRequestId(req) }, '[agent-burst-diff] handler failed');
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'agent-burst-diff',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'agent-burst-diff', method: 'GET', skipBodyParse: true },
+ );
+
+ const handleSaveVersion = withValidation(
+ SaveVersionRequestSchema,
+ async (_req, res, body) => {
+ try {
+ const saveVersionBody = body as unknown as Record<string, unknown>;
+ const {
+ rawAgentId: svRawAgentId,
+ agentId: svAgentId,
+ agentName: svAgentName,
+ clientName: svClientName,
+ } = extractAgentIdentity(saveVersionBody);
+ const shadow = shadowRef?.current;
+ if (!shadow) {
+ errorResponse(
+ res,
+ 503,
+ 'urn:ok:error:shadow-not-configured',
+ 'Shadow repo not configured.',
+ { handler: 'save-version' },
+ );
+ return;
+ }
+ const SAFE_ID_RE = /^[a-zA-Z0-9_-]+$/;
+ let writers: WriterIdentity[] = [];
+ if (Array.isArray(body.writers)) {
+ try {
+ writers = body.writers.map((w) => {
+ const id = w.id ?? 'unknown';
+ if (!SAFE_ID_RE.test(id)) {
+ throw new Error(`Invalid writer id: ${id}`);
+ }
+ return {
+ id,
+ name: (w.name ?? 'unknown').replace(/[\r\n]/g, ''),
+ email: (w.email ?? '[email protected]').replace(/[\r\n]/g, ''),
+ };
+ });
+ } catch (e) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ e instanceof Error ? e.message : 'Invalid writer id.',
+ { handler: 'save-version', cause: e },
+ );
+ return;
+ }
+ }
+ const agentWriter =
+ svRawAgentId !== undefined
+ ? {
+ id: svAgentId,
+ name: svClientName ? `${svAgentName} (${svClientName})` : svAgentName,
+ email: `${svAgentId}@openknowledge.local`,
+ }
+ : undefined;
+ const checkpointSummary = normalizeSummary(
+ typeof body.summary === 'string' ? body.summary : undefined,
+ );
+ const result = await versionOpsService.saveCheckpoint(shadow, {
+ explicitWriters: writers,
+ agentWriter,
+ summary: checkpointSummary.kind === 'value' ? checkpointSummary.value : undefined,
+ });
+ successResponse(
+ res,
+ 200,
+ SaveVersionSuccessSchema,
+ {
+ checkpointRef: result.checkpointRef,
+ },
+ { handler: 'save-version' },
+ );
+ } catch (e) {
+ log.error({ err: e, requestId: getRequestId(_req) }, '[save-version] handler failed');
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'save-version',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'save-version', method: 'POST' },
+ );
+
+ const handleRollback = withValidation(
+ RollbackRequestSchema,
+ async (_req, res, body) => {
+ const bodyObj = body as unknown as Record<string, unknown>;
+ const actor = extractActorIdentity(bodyObj, getPrincipal);
+ if (actor.kind === 'invalid-summary') {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {
+ handler: 'rollback',
+ });
+ return;
+ }
+ // The check fires post-identity (precedent #24) and pre-mutation.
+ const targetDoc = hocuspocus.documents.get(body.docName);
+ if (targetDoc && isDocInConflict(targetDoc)) {
+ respondDocInConflict(
+ res,
+ new DocInConflictError({ file: docNameToRelativePath(body.docName) }),
+ 'rollback',
+ );
+ return;
+ }
+ const shadow = shadowRef?.current;
+ if (!shadow) {
+ errorResponse(
+ res,
+ 503,
+ 'urn:ok:error:rollback-not-configured',
+ 'Shadow repo not configured.',
+ { handler: 'rollback' },
+ );
+ return;
+ }
+ const { docName, commitSha } = body;
+ const resolvedContentRoot = contentRoot ?? '.';
+ const pathResult = safeDocPath(docName, resolvedContentRoot);
+ if ('error' in pathResult) {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', pathResult.error, {
+ handler: 'rollback',
+ });
+ return;
+ }
+ const sg = shadowGit(shadow);
+ const t0 = Date.now();
+ try {
+ const renameLogIndex = getOrLoadRenameLogIndex(shadow.gitDir);
+ const ancestorCache = createAncestorShaSetCache();
+ const branch = getCurrentBranch?.() ?? 'main';
+ const historicalPath = await resolveDocPathAtCommit(
+ shadow,
+ docName,
+ commitSha,
+ branch,
+ renameLogIndex,
+ (name) => docTreePathCandidates(name, resolvedContentRoot),
+ ancestorCache,
+ );
+ if (historicalPath === null) {
+ errorResponse(
+ res,
+ 404,
+ 'urn:ok:error:doc-not-found',
+ `Commit ${commitSha.slice(0, 7)} does not contain document ${docName} at any known historical path.`,
+ { handler: 'rollback' },
+ );
+ return;
+ }
+ const markdown = await sg.raw('show', `${commitSha}:${historicalPath}`);
+ const timestamp = new Date().toISOString();
+ await safetyCheckpoint(shadow, resolvedContentRoot, {
+ action: 'rollback',
+ context: { docName, targetSha: commitSha },
+ });
+ const document = hocuspocus.documents.get(docName);
+ if (!document) {
+ errorResponse(
+ res,
+ 409,
+ 'urn:ok:error:doc-not-open',
+ 'Document is not currently open — open it in the editor first.',
+ { handler: 'rollback' },
+ );
+ return;
+ }
+ /**
+ * Rollback routes through the `replaceRawBody` sibling primitive (precedent #38,
+ * Y.Text-is-truth), which overwrites ytext first and derives the fragment after.
+ */
+ const rollbackEmbedResolver = options.resolveEmbed
+ ? { resolveEmbed: options.resolveEmbed, sourcePath: docName }
+ : undefined;
+ const rollbackPrecomputed = await precomputeParse(markdown, rollbackEmbedResolver);
+ let rollbackDivergence: AgentWriteContentDivergence | undefined;
+ document.transact(() => {
+ replaceRawBody(document, markdown, rollbackEmbedResolver, rollbackPrecomputed);
+ rollbackDivergence = evaluateContentDivergence(
+ document.getText('source').toString(),
+ markdown,
+ 'rollback',
+ );
+ }, ROLLBACK_ORIGIN);
+ if (rollbackDivergence !== undefined) {
+ console.warn(
+ JSON.stringify({
+ event: 'agent-write-content-divergence',
+ 'doc.name': docName,
+ position: 'rollback',
+ intendedBytes: rollbackDivergence.intendedBytes,
+ actualBytes: rollbackDivergence.actualBytes,
+ byteDelta: rollbackDivergence.byteDelta,
+ 'actor.kind': actor.kind,
+ ...(actor.kind === 'agent' || actor.kind === 'principal'
+ ? { 'actor.writer_id': actor.writerId }
+ : {}),
+ }),
+ );
+ }
+ recordContentDivergenceGate('rollback', rollbackDivergence);
+ let summaryResponse: SummaryResponse | undefined;
+ switch (actor.kind) {
+ case 'agent': {
+ const shaShort = commitSha.slice(0, 8);
+ const agentProvidedSummary = actor.summary.kind === 'value';
+ const effectiveNormalized = agentProvidedSummary
+ ? actor.summary
+ : normalizeSummary(`Restored to ${shaShort}`);
+ const fields = summaryResponseFields(effectiveNormalized);
+ summaryResponse =
+ agentProvidedSummary || !fields.response
+ ? fields.response
+ : stripDefaultPathTruncation(fields.response);
+ recordContributor(
+ docName,
+ actor.writerId,
+ actor.displayName,
+ actor.colorSeed,
+ formatRollbackSubject(docName, commitSha),
+ actor.actor,
+ fields.stored,
+ );
+ incrementAgentWriteCalls();
+ countNormalizedSummary(effectiveNormalized, !agentProvidedSummary);
+ break;
+ }
+ case 'principal': {
+ const fields = summaryResponseFields(actor.summary);
+ summaryResponse = fields.response;
+ recordContributor(
+ docName,
+ actor.writerId,
+ actor.displayName,
+ actor.colorSeed,
+ formatRollbackSubject(docName, commitSha),
+ actor.actor,
+ fields.stored,
+ );
+ countNormalizedSummary(actor.summary, false);
+ break;
+ }
+ case 'anonymous':
+ log.debug(
+ { docName, commitSha: commitSha.slice(0, 8) },
+ '[rollback] anonymous actor — no contributor recorded (no agentId in body and getPrincipal() returned null)',
+ );
+ break;
+ default: {
+ const _exhaustive: never = actor;
+ throw new Error(
+ `Unhandled actor kind in handleRollback: ${String(
+ (
+ _exhaustive as {
+ kind?: unknown;
+ }
+ ).kind,
+ )}`,
+ );
+ }
+ }
+ renameAttributionCounter().add(1, { kind: 'rollback', attribution_kind: actor.kind });
+ const flushOutcome = await flushDiskAndDetectOutcome(docName);
+ if (flushOutcome?.kind === 'failure') {
+ respondPersistenceFailure(res, flushOutcome.failure, 'rollback');
+ return;
+ }
+ if (flushOutcome?.kind === 'divergence') {
+ respondDiskDivergence(res, 'rollback');
+ return;
+ }
+ if (flushOutcome?.kind === 'stale-external-write') {
+ respondStaleExternalWrite(res, 'rollback', docName);
+ return;
+ }
+ flushDocToGit(docName, 'rollback');
+ const duration = Date.now() - t0;
+ getLogger('rollback').info(
+ { docName, from: commitSha.slice(0, 8), durationMs: duration },
+ 'rollback',
+ );
+ if (actor.kind === 'agent') {
+ agentFocusBroadcaster?.setFocus(actor.writerId, {
+ agentName: actor.displayName,
+ currentDoc: docName,
+ writeKind: 'rollback-apply',
+ ts: Date.now(),
+ });
+ }
+ const rollbackDivergenceEntry =
+ rollbackDivergence !== undefined
+ ? toContentDivergenceWarning(rollbackDivergence)
+ : undefined;
+ successResponse(
+ res,
+ 200,
+ RollbackSuccessSchema,
+ {
+ restoredFrom: commitSha,
+ timestamp,
+ ...(summaryResponse ? { summary: summaryResponse } : {}),
+ ...(rollbackDivergenceEntry ? { warnings: [rollbackDivergenceEntry] } : {}),
+ },
+ { handler: 'rollback' },
+ );
+ } catch (e) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to roll back.', {
+ handler: 'rollback',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'rollback', method: 'POST' },
+ );
+ return createApiRouteGroup(
+ {
+ '/api/agent-write-md': handleAgentWriteMd,
+ '/api/frontmatter-patch': handleFrontmatterPatch,
+ '/api/agent-patch': handleAgentPatch,
+ '/api/agent-undo': handleAgentUndo,
+ '/api/agent-activity': handleAgentActivity,
+ '/api/agent-burst-diff': handleAgentBurstDiff,
+ '/api/save-version': handleSaveVersion,
+ '/api/rollback': handleRollback,
+ },
+ {
+ mutating: [
+ '/api/agent-write-md',
+ '/api/frontmatter-patch',
+ '/api/agent-patch',
+ '/api/agent-undo',
+ '/api/save-version',
+ '/api/rollback',
+ ],
+ },
+ );
+}
diff --git a/packages/server/src/http/test-routes.test.ts b/packages/server/src/http/test-routes.test.ts
new file mode 100644
index 000000000..b35e86ed4
--- /dev/null
+++ b/packages/server/src/http/test-routes.test.ts
@@ -0,0 +1,44 @@
+import type { Hocuspocus } from '@hocuspocus/server';
+import { describe, expect, test } from 'vitest';
+import type { AgentSessionManager } from '../agent-sessions.ts';
+import { loggerFactory } from '../logger.ts';
+import { createTestRoutes } from './test-routes.ts';
+
+type Deps = Parameters<typeof createTestRoutes>[0];
+
+function buildGroup() {
+ const deps = {
+ resetDocumentDurability: undefined,
+ resolveAlias: (docName) => docName,
+ contentDir: '/nonexistent-content',
+ log: loggerFactory.getLogger('test'),
+ sessionManager: {} as AgentSessionManager,
+ hocuspocus: {} as Hocuspocus,
+ forceUnloadDocument: undefined,
+ derivedDocumentIndex: undefined,
+ contentFilter: undefined,
+ bumpSkillsCatalogGen: () => {},
+ signalChannel: undefined,
+ flushGitCommit: undefined,
+ rescanFiles: undefined,
+ } satisfies Deps;
+ return createTestRoutes(deps);
+}
+
+const FAMILY_PATHS = [
+ '/api/test-reset',
+ '/api/test-flush-git',
+ '/api/test-rescan-backlinks',
+ '/api/test-rescan-files',
+];
+
+describe('createTestRoutes table', () => {
+ test('registers exactly the four conditional test paths', () => {
+ expect([...buildGroup().paths].sort()).toEqual([...FAMILY_PATHS].sort());
+ });
+
+ test('classifies every test path as mutating', () => {
+ const { table } = buildGroup();
+ for (const path of FAMILY_PATHS) expect(table.isMutating(path), path).toBe(true);
+ });
+});
diff --git a/packages/server/src/http/test-routes.ts b/packages/server/src/http/test-routes.ts
new file mode 100644
index 000000000..29586aa4d
--- /dev/null
+++ b/packages/server/src/http/test-routes.ts
@@ -0,0 +1,220 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { Document, Hocuspocus } from '@hocuspocus/server';
+import {
+ CONFIG_DOC_NAME_OKIGNORE,
+ EmptyRequestSchema,
+ TestFlushGitSuccessSchema,
+ TestRescanBacklinksSuccessSchema,
+ TestRescanFilesSuccessSchema,
+ TestResetSuccessSchema,
+} from '@inkeep/open-knowledge-core';
+import type { AgentSessionManager } from '../agent-sessions.ts';
+import { CONFIG_VALIDATION_REVERT_ORIGIN } from '../config-edit-origin.ts';
+import type { ContentFilter } from '../content-filter.ts';
+import { safeContentPath } from '../content-path.ts';
+import type { DerivedDocumentIndexApiPort } from '../derived-document-index.ts';
+import { canonicalDocName } from '../doc-extensions.ts';
+import { type ApiRouteGroup, createApiRouteGroup } 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 TestRouteDeps {
+ resetDocumentDurability: ((docName: string) => void) | undefined;
+ resolveAlias: (docName: string) => string;
+ contentDir: string;
+ log: import('../logger.ts').PinoLogger;
+ sessionManager: AgentSessionManager;
+ hocuspocus: Hocuspocus;
+ forceUnloadDocument: ((document: Document) => Promise<void>) | undefined;
+ derivedDocumentIndex: DerivedDocumentIndexApiPort | undefined;
+ contentFilter: ContentFilter | undefined;
+ bumpSkillsCatalogGen: () => void;
+ signalChannel: ((channel: 'files' | 'lint-config' | 'comments') => void) | undefined;
+ flushGitCommit: (() => Promise<void>) | undefined;
+ rescanFiles: (() => void | Promise<void>) | undefined;
+}
+
+export function createTestRoutes(deps: TestRouteDeps): ApiRouteGroup {
+ const {
+ resetDocumentDurability,
+ resolveAlias,
+ contentDir,
+ log,
+ sessionManager,
+ hocuspocus,
+ forceUnloadDocument,
+ derivedDocumentIndex,
+ contentFilter,
+ bumpSkillsCatalogGen,
+ signalChannel,
+ flushGitCommit,
+ rescanFiles,
+ } = deps;
+ const handleTestReset = withValidation(
+ EmptyRequestSchema,
+ async (req, res) => {
+ try {
+ const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+ const docName = canonicalDocName(
+ resolveAlias(url.searchParams.get('docName') ?? 'test-doc'),
+ );
+ let filePath: string;
+ try {
+ filePath = safeContentPath(docName, contentDir);
+ } catch (err) {
+ log.error({ err, docName }, '[test-reset] safeContentPath rejected docName');
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {
+ handler: 'test-reset',
+ cause: err,
+ });
+ return;
+ }
+ await sessionManager.closeAll(docName);
+ hocuspocus.closeConnections(docName);
+ const debounceId = `onStoreDocument-${docName}`;
+ if (hocuspocus.debouncer.isDebounced(debounceId)) {
+ await hocuspocus.debouncer.executeNow(debounceId);
+ }
+ const doc = hocuspocus.documents.get(docName);
+ if (doc) await (forceUnloadDocument ?? hocuspocus.unloadDocument.bind(hocuspocus))(doc);
+ resetDocumentDurability?.(docName);
+ writeFileSync(filePath, '', 'utf-8');
+ await derivedDocumentIndex?.testOnly?.resetDocumentForTest(docName);
+ const resetOkignoreParam = url.searchParams.get('reset-okignore');
+ const resetOkignore = resetOkignoreParam !== 'false';
+ if (resetOkignore) {
+ try {
+ const okignorePath = resolve(contentDir, '.okignore');
+ const okignoreDoc = hocuspocus.documents.get(CONFIG_DOC_NAME_OKIGNORE);
+ if (okignoreDoc) {
+ const ytext = okignoreDoc.getText('source');
+ if (ytext.length > 0) {
+ okignoreDoc.transact(() => {
+ ytext.delete(0, ytext.length);
+ }, CONFIG_VALIDATION_REVERT_ORIGIN);
+ }
+ }
+ if (existsSync(okignorePath)) {
+ writeFileSync(okignorePath, '', 'utf-8');
+ }
+ if (contentFilter) {
+ bumpSkillsCatalogGen();
+ await contentFilter.rebuildIgnorePatterns();
+ }
+ } catch (err) {
+ log.warn({ err }, '[test-reset] okignore reset partial failure');
+ }
+ }
+ signalChannel?.('files');
+ successResponse(res, 200, TestResetSuccessSchema, {}, { handler: 'test-reset' });
+ } catch (e) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'test-reset',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'test-reset', method: 'POST', skipBodyParse: true },
+ );
+
+ const handleTestFlushGit = withValidation(
+ EmptyRequestSchema,
+ async (_req, res) => {
+ try {
+ await flushGitCommit?.();
+ successResponse(res, 200, TestFlushGitSuccessSchema, {}, { handler: 'test-flush-git' });
+ } catch (e) {
+ log.error({ err: e, requestId: getRequestId(_req) }, '[test-flush-git] flush failed');
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'test-flush-git',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'test-flush-git', method: 'POST', skipBodyParse: true },
+ );
+
+ const handleTestRescanBacklinks = withValidation(
+ EmptyRequestSchema,
+ async (_req, res) => {
+ try {
+ if (!derivedDocumentIndex?.testOnly) {
+ errorResponse(
+ res,
+ 503,
+ 'urn:ok:error:backlink-index-not-configured',
+ 'Backlink index is not configured.',
+ { handler: 'test-rescan-backlinks' },
+ );
+ return;
+ }
+ await derivedDocumentIndex.testOnly.rescanBacklinksForTest();
+ successResponse(
+ res,
+ 200,
+ TestRescanBacklinksSuccessSchema,
+ {},
+ { handler: 'test-rescan-backlinks' },
+ );
+ } catch (e) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'test-rescan-backlinks',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'test-rescan-backlinks', method: 'POST', skipBodyParse: true },
+ );
+
+ const handleTestRescanFiles = withValidation(
+ EmptyRequestSchema,
+ async (_req, res) => {
+ try {
+ if (!rescanFiles) {
+ errorResponse(
+ res,
+ 503,
+ 'urn:ok:error:file-rescan-not-configured',
+ 'Watcher rescan capability is not configured.',
+ { handler: 'test-rescan-files' },
+ );
+ return;
+ }
+ await rescanFiles();
+ signalChannel?.('files');
+ successResponse(
+ res,
+ 200,
+ TestRescanFilesSuccessSchema,
+ {},
+ { handler: 'test-rescan-files' },
+ );
+ } catch (e) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'test-rescan-files',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'test-rescan-files', method: 'POST', skipBodyParse: true },
+ );
+ return createApiRouteGroup(
+ {
+ '/api/test-reset': handleTestReset,
+ '/api/test-flush-git': handleTestFlushGit,
+ '/api/test-rescan-backlinks': handleTestRescanBacklinks,
+ '/api/test-rescan-files': handleTestRescanFiles,
+ },
+ {
+ mutating: [
+ '/api/test-reset',
+ '/api/test-flush-git',
+ '/api/test-rescan-backlinks',
+ '/api/test-rescan-files',
+ ],
+ },
+ );
+}