Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

71.0 KB
Raw Blame
import type { IncomingMessage, ServerResponse } from 'node:http';
import type { Hocuspocus } from '@hocuspocus/server';
import {
  AGENT_ICON_COLORS,
  AgentActivitySuccessSchema,
  AgentBurstDiffSuccessSchema,
  AgentPatchRequestSchema,
  AgentPatchSuccessSchema,
  AgentUndoRequestSchema,
  AgentUndoSuccessSchema,
  type AgentWriteMdRequest,
  AgentWriteMdRequestSchema,
  AgentWriteMdSuccessSchema,
  agentWriteOutcomeWireFields,
  applyPatchToFm,
  changedBlockRange,
  colorFromSeed,
  composeWithDerivedFrontmatter,
  type DiskEditReconciledWarning,
  detectFmRegion,
  EmptyRequestSchema,
  FrontmatterPatchRequestSchema,
  FrontmatterPatchSuccessSchema,
  type LintViolationWarning,
  type Principal,
  prependFrontmatter,
  RollbackRequestSchema,
  RollbackSuccessSchema,
  SaveVersionRequestSchema,
  SaveVersionSuccessSchema,
  stripFrontmatter,
  validateDocName,
} from '@inkeep/open-knowledge-core';
import { formatRollbackSubject } from '@inkeep/open-knowledge-core/shadow-repo-layout';
import { z } from 'zod';
import { captureEffect } from '../activity-log.ts';
import { listAgentActivity, synthesizeVersionDiff } from '../agent-activity.ts';
import type { AgentFocusBroadcaster } from '../agent-focus.ts';
import { type RawWriterId, 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 AgentWriteFlushOutcome,
  answeredWithSuccessOnAppRoutes,
  outcomeOfSavedWrite,
  REFUSAL_OUTCOMES,
} from '../agent-write-outcome.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 {
  ConcurrentOverwriteRefusedError,
  respondConcurrentOverwriteRefused,
} from '../concurrent-overwrite-refused-error.ts';
import type { ConflictAuthority } from '../conflict-authority.ts';
import { DocInConflictError, respondDocInConflict } from '../conflict-errors.ts';
import {
  evaluateContentDivergence,
  toContentDivergenceWarning,
} from '../content-divergence-gate.ts';
import type { ContentFilter } from '../content-filter.ts';
import { recordContributor } from '../contributor-tracker.ts';
import {
  canonicalDocName,
  registerDocExtension,
  SUPPORTED_DOC_EXTENSIONS,
  stripDocExtension,
} from '../doc-extensions.ts';
import {
  type DocumentDurabilityState,
  type StoreFailure,
  type WrittenThrough,
  writtenThroughOf,
} from '../document-durability-state.ts';
import {
  NOT_RECONCILED,
  type ReconcileBeforeWriteResult,
  reconcileDiskBeforeAgentWrite,
} from '../external-change.ts';
import { extractActorIdentity } from '../extract-actor-identity.ts';
import {
  FrontmatterMalformedError,
  respondFrontmatterMalformed,
} from '../frontmatter-malformed-error.ts';
import { recordFrontmatterEditSurface } from '../frontmatter-telemetry.ts';
import type { LinkAdvisoryPolicy, PrepareWriteLinkAdvisory } from '../link-advisory-policy.ts';
import { getLogger } from '../logger.ts';
import type { MergeHistoryRecorder } from '../merge-history.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 { respondAgentSessionCapacity } from './agent-session-capacity.ts';
import { respondBothKept } from './agent-write-response.ts';
import { type ApiRouteGroup, createApiRouteGroup } from './api-pipeline.ts';
import { errorResponse } from './error-response.ts';
import type { RouteHandler } from './method-router.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 {
  conflicts: ConflictAuthority;
  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;
    suppliedWriterId: RawWriterId | undefined;
    agentId: string;
    agentName: string;
    colorSeed: string;
    clientName: string | undefined;
    clientVersion: string | undefined;
    label: string | undefined;
  };
  docNameExistsWithAnySupportedExtension: (contentDir: string, docName: string) => boolean;
  findMissingDocCandidates: (docName: string) => string[];
  contentDir: string;
  summaryResponseFields: (normalized: NormalizedSummary) => {
    response?: SummaryResponse;
    stored: string | undefined;
  };
  sessionManager: AgentSessionManager;
  durabilityState: DocumentDurabilityState;
  hocuspocus: Hocuspocus;
  options: {
    resolveEmbed?: (basename: string, sourcePath: string) => string | null;
    contentFilter?: Pick<ContentFilter, 'isExcluded'>;
  };
  getBridgeLossReporter: (() => BridgeDeriveLossReporter | undefined) | undefined;
  mergeHistory: MergeHistoryRecorder;
  agentPresenceBroadcaster: AgentPresenceBroadcaster | undefined;
  recordContentDivergenceGate: (
    handler:
      | 'agent-write-md'
      | 'acp-document-write'
      | '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,
    writtenThrough?: WrittenThrough,
  ) => Promise<AgentWriteFlushOutcome>;
  respondPersistenceFailure: (res: ServerResponse, failure: StoreFailure, 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;
  prepareWriteLinkAdvisory: PrepareWriteLinkAdvisory;
  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;
  flushGitCommit: (() => Promise<void>) | undefined;
  commitOkArtifactWrite: (context: string) => Promise<unknown>;
  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']>;
}

interface MarkdownWriteMode {
  readonly handler: 'agent-write-md' | 'acp-document-write';
  readonly preWriteMerge: boolean;
  readonly callerReadsWriteReport: boolean;
}

const ROUTE_MARKDOWN_WRITE: MarkdownWriteMode = {
  handler: 'agent-write-md',
  preWriteMerge: true,
  callerReadsWriteReport: true,
};

const ACP_MARKDOWN_WRITE: MarkdownWriteMode = {
  handler: 'acp-document-write',
  preWriteMerge: false,
  callerReadsWriteReport: false,
};

const AcpDocumentWriteRequestSchema = z
  .object({
    docName: z.string().min(1),
    file: z.string().min(1),
    markdown: z.string(),
    extension: z.enum(SUPPORTED_DOC_EXTENSIONS).optional(),
    agentId: z.string().optional(),
    agentName: z.string().optional(),
    clientName: z.string().optional(),
  })
  .strict();

const AcpDocumentWriteSuccessSchema = z
  .object({ ...agentWriteOutcomeWireFields, timestamp: z.string().min(1) })
  .strict();

export function createAgentWriteRoutes(
  deps: AgentWriteRouteDeps,
): ApiRouteGroup & { readonly acpDocumentWrite: RouteHandler } {
  const {
    conflicts,
    getLinkAdvisoryPolicy,
    respondStaleExternalWrite,
    requireNonEmptyDocName,
    resolveAlias,
    extractAgentIdentity,
    docNameExistsWithAnySupportedExtension,
    findMissingDocCandidates,
    contentDir,
    summaryResponseFields,
    sessionManager,
    durabilityState,
    hocuspocus,
    options,
    getBridgeLossReporter,
    mergeHistory,
    agentPresenceBroadcaster,
    recordContentDivergenceGate,
    buildAgentActor,
    countNormalizedSummary,
    flushDiskAndDetectOutcome,
    respondPersistenceFailure,
    flushDocToDisk,
    agentFocusBroadcaster,
    onAgentWrite,
    computeOrphanHints,
    registerWrittenDocInFileIndex,
    prepareWriteLinkAdvisory,
    buildReconcileWarning,
    computeLintViolations,
    log,
    flushDocToGit,
    flushGitCommit,
    commitOkArtifactWrite,
    isSafeDocName,
    shadowRef,
    getPrincipal,
    contentRoot,
    safeDocPath,
    getCurrentBranch,
    docTreePathCandidates,
    stripDefaultPathTruncation,
    renameAttributionCounter,
  } = deps;

  const versionOpsService = createVersionOpsService({ getCurrentBranch, contentRoot });

  async function storePendingEdits(): Promise<void> {
    await Promise.all(
      [...hocuspocus.documents.values()]
        .filter((document) => !isSystemDoc(document.name) && !isConfigDoc(document.name))
        .map(async (document) => {
          await hocuspocus.debouncer.executeNow(`onStoreDocument-${document.name}`);
          await document.saveMutex.waitForUnlock();
        }),
    );
    await flushGitCommit?.();
  }

  function getSubscriberCount(docName: string): number {
    try {
      const doc = hocuspocus.documents.get(docName);
      return doc?.connections.size ?? 0;
    } catch {
      return 0;
    }
  }

  function respondIfDocumentMissing(
    res: ServerResponse,
    docName: string,
    handler: 'agent-patch' | 'frontmatter-patch',
  ): boolean {
    if (docNameExistsWithAnySupportedExtension(contentDir, docName)) return false;
    if ((hocuspocus.documents.get(docName)?.getText('source').length ?? 0) > 0) return false;
    const candidates = findMissingDocCandidates(docName);
    const nextStep =
      candidates.length === 0
        ? 'edit only changes an existing document; use write({ document: { path, content } }) to create one.'
        : `Did you mean ${candidates.map((c) => `"${c}"`).join(' or ')}? Retry the edit at that path.`;
    errorResponse(
      res,
      404,
      'urn:ok:error:doc-not-found',
      `No document at "${docName}" (paths are relative to the content root). ${nextStep}`,
      {
        handler,
        extensions: {
          candidates,
          committed: false,
          ...REFUSAL_OUTCOMES['urn:ok:error:doc-not-found'],
        },
      },
    );
    return true;
  }

  function getSystemSubscriberCount(): number {
    try {
      const doc = hocuspocus.documents.get(SYSTEM_DOC_NAME);
      return doc?.connections.size ?? 0;
    } catch {
      return 0;
    }
  }

  const handleAgentWriteMd = withValidation(
    AgentWriteMdRequestSchema,
    (req, res, body) => writeAgentMarkdownDocument(req, res, body, ROUTE_MARKDOWN_WRITE),
    { handler: 'agent-write-md', method: 'POST' },
  );

  function isAcpWritableDocument(docName: string, file: string): boolean {
    if (docName !== file && docName !== stripDocExtension(file)) return false;
    if (validateDocName(docName).ok) return true;
    return options.contentFilter !== undefined && !options.contentFilter.isExcluded(file);
  }

  async function writeAgentMarkdownDocument(
    _req: IncomingMessage,
    res: ServerResponse,
    body: AgentWriteMdRequest,
    mode: MarkdownWriteMode,
  ): Promise<void> {
    try {
      const linkPolicy = getLinkAdvisoryPolicy();
      const position = body.position ?? 'append';
      const effectiveDocName = requireNonEmptyDocName(body.docName, res, mode.handler);
      if (effectiveDocName === null) return;
      const resolvedDocName = canonicalDocName(resolveAlias(effectiveDocName));
      const { agentId, suppliedWriterId, 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: mode.handler,
            extensions: { ...REFUSAL_OUTCOMES['urn:ok:error:reserved-doc-name'] },
          },
        );
        return;
      }
      if (
        body.extension !== undefined &&
        !docNameExistsWithAnySupportedExtension(contentDir, resolvedDocName)
      ) {
        registerDocExtension(resolvedDocName, body.extension);
      }
      const normalizedSummary = normalizeSummary(body.summary);
      const { response: summaryResponse, stored: storedSummary } =
        summaryResponseFields(normalizedSummary);
      await sessionManager.withSessions(async (getSession) => {
        const session = await getSession(resolvedDocName, agentId, {
          displayName: agentName,
          colorSeed,
          clientName,
        });
        const writeMdReconcile = mode.preWriteMerge
          ? await reconcileDiskBeforeAgentWrite(
              durabilityState,
              hocuspocus,
              resolvedDocName,
              contentDir,
              options.resolveEmbed,
              getBridgeLossReporter?.(),
              conflicts,
              mergeHistory,
            )
          : NOT_RECONCILED;
        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;
        let writtenThrough: WrittenThrough | undefined;
        let writtenSource = '';
        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),
              suppliedWriterId,
            );
            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);
          writtenThrough = writtenThroughOf(session.dc.document);
          durabilityState.markAgentWriteStore(resolvedDocName);
          writtenSource = session.dc.document.getText('source').toString();
          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(mode.handler, writeDivergence);
          recordContributor(
            resolvedDocName,
            agentId,
            agentName,
            colorSeed,
            undefined,
            buildAgentActor({ clientName, clientVersion, label }),
            storedSummary,
          );
          if (mode.callerReadsWriteReport) {
            incrementAgentWriteCalls();
            countNormalizedSummary(normalizedSummary);
          }
        } finally {
          disposeEffectCapture?.();
          agentPresenceBroadcaster?.touchMode(agentId, 'idle');
        }
        const flushOutcome = await flushDiskAndDetectOutcome(resolvedDocName, writtenThrough);
        if (flushOutcome?.kind === 'failure') {
          respondPersistenceFailure(res, flushOutcome.failure, mode.handler);
          return;
        }
        if (flushOutcome?.kind === 'stale-external-write') {
          respondStaleExternalWrite(res, mode.handler, resolvedDocName);
          return;
        }
        flushDocToDisk(resolvedDocName, mode.handler);
        agentFocusBroadcaster?.setFocus(agentId, {
          agentName,
          currentDoc: resolvedDocName,
          writeKind: 'write',
          ts: Date.now(),
        });
        onAgentWrite?.();
        writtenSource =
          hocuspocus.documents.get(resolvedDocName)?.getText('source').toString() ?? writtenSource;
        const writeMdOutcome = outcomeOfSavedWrite(
          writeMdReconcile,
          flushOutcome,
          writeDivergence !== undefined,
        );
        if (!mode.callerReadsWriteReport) {
          registerWrittenDocInFileIndex(resolvedDocName, writtenSource);
          if (writeMdOutcome.outcome === 'both-kept') {
            respondBothKept(res, mode.handler, { timestamp }, writeMdOutcome);
            return;
          }
          successResponse(
            res,
            200,
            AcpDocumentWriteSuccessSchema,
            { timestamp, ...writeMdOutcome },
            { handler: mode.handler },
          );
          return;
        }
        const hints = await computeOrphanHints(resolvedDocName);
        registerWrittenDocInFileIndex(resolvedDocName, writtenSource);
        const renderWarnings = await validateMermaidFences(writtenSource, resolvedDocName);
        const linkAdvisory = (await prepareWriteLinkAdvisory([resolvedDocName]))(
          writtenSource,
          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(writtenSource, resolvedDocName, linkPolicy)),
          ...linkAdvisory.warnings,
        ];
        const writeMdBody = {
          timestamp,
          subscriberCount,
          systemSubscriberCount,
          ...(hints ? { hints } : {}),
          ...(summaryResponse ? { summary: summaryResponse } : {}),
          ...(writeMdAdvisories.length > 0 ? { warnings: writeMdAdvisories } : {}),
          ...linkAdvisory.links,
        };
        if (writeMdOutcome.outcome === 'both-kept') {
          respondBothKept(res, mode.handler, writeMdBody, writeMdOutcome);
          return;
        }
        successResponse(
          res,
          200,
          AgentWriteMdSuccessSchema,
          { ...writeMdBody, ...writeMdOutcome },
          { handler: mode.handler },
        );
      });
    } catch (e) {
      if (e instanceof DocInConflictError) {
        respondDocInConflict(
          res,
          e,
          mode.handler,
          conflicts.findByDocName(stripDocExtension(e.file)),
        );
        return;
      }
      if (e instanceof ConcurrentOverwriteRefusedError) {
        respondConcurrentOverwriteRefused(res, e, mode.handler);
        return;
      }
      if (e instanceof FrontmatterMalformedError) {
        respondFrontmatterMalformed(res, e, mode.handler);
        return;
      }
      if (e instanceof AgentSessionCapacityError) {
        respondAgentSessionCapacity(res, e, mode.handler);
        return;
      }
      log.error({ err: e, requestId: getRequestId(_req) }, `[${mode.handler}] handler failed`);
      errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
        handler: mode.handler,
        cause: e,
      });
    }
  }

  const acpDocumentWrite = withValidation(
    AcpDocumentWriteRequestSchema,
    async (req, res, body) => {
      if (!isAcpWritableDocument(body.docName, body.file)) {
        errorResponse(
          res,
          400,
          'urn:ok:error:invalid-request',
          `'${body.file}' is not a document OpenKnowledge keeps for the in-app agent.`,
          {
            handler: ACP_MARKDOWN_WRITE.handler,
            detail:
              'The path is excluded from the project content, so there is no document to write it through. Nothing was written.',
            extensions: { outcome: 'refused', saved: false, nextStep: 'none' },
          },
        );
        return;
      }
      const { file: _file, ...write } = body;
      await writeAgentMarkdownDocument(
        req,
        res,
        { ...write, position: 'replace' },
        ACP_MARKDOWN_WRITE,
      );
    },
    { handler: ACP_MARKDOWN_WRITE.handler, method: 'POST', maxBodyBytes: Number.POSITIVE_INFINITY },
  );

  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',
              extensions: { ...REFUSAL_OUTCOMES['urn:ok:error:reserved-doc-name'] },
            },
          );
          return;
        }
        if (respondIfDocumentMissing(res, resolvedDocName, 'frontmatter-patch')) return;
        const patch = body.patch ?? {};
        const patchKeys = Object.keys(patch);
        const normalizedSummary = normalizeSummary(body.summary);
        const { response: summaryResponse, stored: storedSummary } =
          summaryResponseFields(normalizedSummary);
        await sessionManager.withSessions(async (getSession) => {
          const session = await getSession(resolvedDocName, agentId, {
            displayName: agentName,
            colorSeed,
            clientName,
          });
          const fmReconcile = await reconcileDiskBeforeAgentWrite(
            durabilityState,
            hocuspocus,
            resolvedDocName,
            contentDir,
            options.resolveEmbed,
            getBridgeLossReporter?.(),
            conflicts,
            mergeHistory,
          );
          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;
          let fmFlushOutcome: AgentWriteFlushOutcome = null;
          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);
                if (bodyMutated) durabilityState.markAgentWriteStore(resolvedDocName);
              },
            );
          } finally {
            agentPresenceBroadcaster?.touchMode(agentId, 'idle');
          }
          let fmWrittenSource = session.dc.document.getText('source').toString();
          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,
                  ...REFUSAL_OUTCOMES['urn:ok:error:invalid-frontmatter-patch'],
                },
              },
            );
            return;
          }
          if (applied && appliedKeys.length > 0) {
            recordContributor(
              resolvedDocName,
              agentId,
              agentName,
              colorSeed,
              undefined,
              buildAgentActor({ clientName, clientVersion, label }),
              storedSummary,
            );
            incrementAgentWriteCalls();
            countNormalizedSummary(normalizedSummary);
            if (bodyMutated) {
              fmFlushOutcome = await flushDiskAndDetectOutcome(resolvedDocName);
              const flushOutcome = fmFlushOutcome;
              if (flushOutcome?.kind === 'failure') {
                respondPersistenceFailure(res, flushOutcome.failure, '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);
          fmWrittenSource =
            hocuspocus.documents.get(resolvedDocName)?.getText('source').toString() ??
            fmWrittenSource;
          registerWrittenDocInFileIndex(resolvedDocName, fmWrittenSource);
          const linkAdvisory = (await prepareWriteLinkAdvisory([resolvedDocName]))(
            fmWrittenSource,
            resolvedDocName,
            linkPolicy.suppressLogLinkAdvisories,
          );
          const fmAdvisories = [...(fmWarning ? [fmWarning] : []), ...linkAdvisory.warnings];
          const fmBody = {
            timestamp,
            subscriberCount,
            systemSubscriberCount,
            appliedKeys,
            ...(summaryResponse ? { summary: summaryResponse } : {}),
            ...(fmAdvisories.length > 0 ? { warnings: fmAdvisories } : {}),
            ...linkAdvisory.links,
          };
          const fmOutcome = outcomeOfSavedWrite(fmReconcile, fmFlushOutcome);
          if (fmOutcome.outcome === 'both-kept') {
            respondBothKept(res, 'frontmatter-patch', fmBody, fmOutcome);
            return;
          }
          successResponse(
            res,
            200,
            FrontmatterPatchSuccessSchema,
            { ...fmBody, ...fmOutcome },
            { handler: 'frontmatter-patch' },
          );
        });
      } catch (e) {
        if (e instanceof AgentSessionCapacityError) {
          respondAgentSessionCapacity(res, e, 'frontmatter-patch');
          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,
          suppliedWriterId,
          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',
              extensions: { ...REFUSAL_OUTCOMES['urn:ok:error:reserved-doc-name'] },
            },
          );
          return;
        }
        if (respondIfDocumentMissing(res, docName, 'agent-patch')) return;
        const normalizedSummary = normalizeSummary(body.summary);
        await sessionManager.withSessions(async (getSession) => {
          const session = await getSession(docName, agentId, {
            displayName: agentName,
            colorSeed,
            clientName,
          });
          const patchReconcile = await reconcileDiskBeforeAgentWrite(
            durabilityState,
            hocuspocus,
            docName,
            contentDir,
            options.resolveEmbed,
            getBridgeLossReporter?.(),
            conflicts,
            mergeHistory,
          );
          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),
                suppliedWriterId,
              );
              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);
            durabilityState.markAgentWriteStore(docName);
            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',
                extensions: { ...REFUSAL_OUTCOMES['urn:ok:error:stale-target'] },
              },
            );
            return;
          }
          if (notFound) {
            errorResponse(
              res,
              404,
              'urn:ok:error:target-not-found',
              'Text not found in document.',
              {
                handler: 'agent-patch',
                extensions: { ...REFUSAL_OUTCOMES['urn:ok:error:target-not-found'] },
              },
            );
            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',
                extensions: { ...REFUSAL_OUTCOMES['urn:ok:error:frontmatter-edit-not-supported'] },
              },
            );
            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',
                extensions: { ...REFUSAL_OUTCOMES['urn:ok:error:frontmatter-edit-not-supported'] },
              },
            );
            return;
          }
          let patchedSource = session.dc.document.getText('source').toString();
          const flushOutcome = await flushDiskAndDetectOutcome(docName);
          if (flushOutcome?.kind === 'failure') {
            respondPersistenceFailure(res, flushOutcome.failure, '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);
          patchedSource =
            hocuspocus.documents.get(docName)?.getText('source').toString() ?? patchedSource;
          registerWrittenDocInFileIndex(docName, patchedSource);
          const renderWarnings = await validateMermaidFences(patchedSource, docName);
          const linkAdvisory = (await prepareWriteLinkAdvisory([docName]))(
            patchedSource,
            docName,
            linkPolicy.suppressLogLinkAdvisories,
          );
          const patchWarning = buildReconcileWarning(patchReconcile);
          const patchDivergenceEntry =
            patchDivergence !== undefined ? toContentDivergenceWarning(patchDivergence) : undefined;
          const patchAdvisories = [
            ...(patchDivergenceEntry ? [patchDivergenceEntry] : []),
            ...(patchWarning ? [patchWarning] : []),
            ...(renderWarnings ?? []),
            ...(await computeLintViolations(patchedSource, docName, linkPolicy)),
            ...linkAdvisory.warnings,
          ];
          const patchBody = {
            timestamp,
            subscriberCount,
            systemSubscriberCount,
            ...(summaryResponse ? { summary: summaryResponse } : {}),
            ...(patchAdvisories.length > 0 ? { warnings: patchAdvisories } : {}),
            ...linkAdvisory.links,
          };
          const patchOutcome = outcomeOfSavedWrite(
            patchReconcile,
            flushOutcome,
            patchDivergence !== undefined,
          );
          if (patchOutcome.outcome === 'both-kept') {
            respondBothKept(res, 'agent-patch', patchBody, patchOutcome);
            return;
          }
          successResponse(
            res,
            200,
            AgentPatchSuccessSchema,
            { ...patchBody, ...patchOutcome },
            { handler: 'agent-patch' },
          );
        });
      } catch (e) {
        if (e instanceof DocInConflictError) {
          respondDocInConflict(
            res,
            e,
            'agent-patch',
            conflicts.findByDocName(stripDocExtension(e.file)),
          );
          return;
        }
        if (e instanceof FrontmatterMalformedError) {
          respondFrontmatterMalformed(res, e, 'agent-patch');
          return;
        }
        if (e instanceof AgentSessionCapacityError) {
          respondAgentSessionCapacity(res, e, 'agent-patch');
          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',
              extensions: { ...REFUSAL_OUTCOMES['urn:ok:error:reserved-doc-name'] },
            },
          );
          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) {
            durabilityState.markAgentWriteStore(docName);
            recordContributor(
              docName,
              connectionId,
              agentName,
              colorSeed,
              undefined,
              buildAgentActor({ clientName, clientVersion, label }),
            );
          }
        } finally {
          agentPresenceBroadcaster?.touchMode(agentId, 'idle');
        }
        let undoFlushOutcome: AgentWriteFlushOutcome = null;
        if (undone) {
          undoFlushOutcome = await flushDiskAndDetectOutcome(docName);
          const flushOutcome = undoFlushOutcome;
          if (
            flushOutcome?.kind === 'failure' &&
            !answeredWithSuccessOnAppRoutes(flushOutcome.failure)
          ) {
            respondPersistenceFailure(res, flushOutcome.failure, '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, ...outcomeOfSavedWrite(undefined, undoFlushOutcome) },
          { handler: 'agent-undo' },
        );
      } catch (e) {
        if (e instanceof DocInConflictError) {
          respondDocInConflict(
            res,
            e,
            'agent-undo',
            conflicts.findByDocName(stripDocExtension(e.file)),
          );
          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,
        );
        await storePendingEdits();
        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 rollbackConflict = conflicts.findByDocName(body.docName);
      if (rollbackConflict !== undefined) {
        respondDocInConflict(
          res,
          new DocInConflictError({ file: rollbackConflict.file }),
          'rollback',
          rollbackConflict,
        );
        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 {
        await commitOkArtifactWrite('rollback-read');
        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',
              extensions: { ...REFUSAL_OUTCOMES['urn:ok:error:doc-not-found'] },
            },
          );
          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);
        durabilityState.markAgentWriteStore(docName);
        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' &&
          !answeredWithSuccessOnAppRoutes(flushOutcome.failure)
        ) {
          respondPersistenceFailure(res, flushOutcome.failure, '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,
          {
            ...outcomeOfSavedWrite(undefined, flushOutcome, rollbackDivergence !== undefined),
            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 group = 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',
      ],
    },
  );
  return { ...group, acpDocumentWrite };
}