Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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',+ ],+ },+ );+}