@agentskit/doc-bridge 1.4.3 → 1.5.0

package/src/fixes/proposals.ts

@@ -0,0 +1,165 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path'
+
+import { contentHashForArtifactV1, sha256NormalizedV1 } from '../index-builder/content-hash.js'
+import { FixProposalV1Schema, type FixProposalV1 } from '../schemas/knowledge.js'
+import { containedPath } from '../safety/repository.js'
+
+export type FixProposalOptions = {
+  readonly baseRevision: string
+  readonly configurationHash: string
+  readonly projectName?: string
+  readonly toolVersion?: string
+}
+
+export type FixApplyOptions = {
+  readonly currentRevision?: string
+  readonly verify?: (changedPaths: readonly string[]) => void
+}
+
+type FixChange = { readonly path: string; readonly before: string; readonly after: string }
+
+const hash = (value: unknown): string => sha256NormalizedV1(value)
+
+const artifactMetadata = (root: string, options: FixProposalOptions) => ({
+  schemaVersion: 1 as const,
+  contentHash: '0'.repeat(64),
+  contentHashAlgo: 'sha256-normalized-v1' as const,
+  project: { name: options.projectName ?? basename(resolve(root)), root: '.' },
+  sourceRevision: options.baseRevision,
+  sourceRevisionKind: options.baseRevision.length === 40 ? 'git' as const : 'content' as const,
+  configurationHash: options.configurationHash,
+  pipelineVersion: '1.0.0',
+  analyzerVersions: { fixes: options.toolVersion ?? '1.0.0' },
+})
+
+const unifiedDiff = (changes: readonly FixChange[]): string => changes.map((change) => {
+  const before = change.before.split('\n').map((line) => `-${line}`).join('\n')
+  const after = change.after.split('\n').map((line) => `+${line}`).join('\n')
+  return `--- a/${change.path}\n+++ b/${change.path}\n@@\n${before}\n${after}`
+}).join('\n')
+
+const makeProposal = (root: string, options: FixProposalOptions, changes: readonly FixChange[], preconditions: readonly string[], postconditions: readonly string[]): FixProposalV1 => {
+  const draft = {
+    ...artifactMetadata(root, options),
+    type: 'fix-proposal' as const,
+    proposalId: `fix-${hash(changes).slice(0, 20)}`,
+    baseRevision: options.baseRevision,
+    affectedFiles: changes.map(({ path, before }) => ({ path, contentHash: sha256NormalizedV1(before) })),
+    changes,
+    preconditions,
+    diff: unifiedDiff(changes),
+    postconditions,
+    status: 'proposed' as const,
+  }
+  return FixProposalV1Schema.parse({ ...draft, contentHash: contentHashForArtifactV1(draft) })
+}
+
+const walkMarkdown = (root: string, directory = root): string[] => readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+  if (entry.name === '.git' || entry.name === 'node_modules' || entry.name === 'dist' || entry.name === 'build') return []
+  const path = join(directory, entry.name)
+  if (entry.isDirectory()) return walkMarkdown(root, path)
+  return entry.isFile() && ['.md', '.mdx'].includes(extname(entry.name).toLowerCase()) ? [relative(root, path).split(sep).join('/')] : []
+})
+
+const localLink = /(!?)\[([^\]]*)\]\(([^)\s]+)(?:\s+["'][^)]*["'])?\)/g
+
+const sortJson = (value: unknown): unknown => Array.isArray(value)
+  ? value.map(sortJson)
+  : value && typeof value === 'object'
+    ? Object.fromEntries(Object.entries(value as Record<string, unknown>).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => [key, sortJson(item)]))
+    : value
+
+export const createMarkdownLinkFixProposal = (root: string, options: FixProposalOptions): FixProposalV1 | undefined => {
+  const projectRoot = realpathSync.native(resolve(root))
+  const paths = walkMarkdown(projectRoot)
+  const changes: FixChange[] = []
+  for (const path of paths) {
+    const content = readFileSync(join(projectRoot, path), 'utf8')
+    let next = content
+    for (const match of content.matchAll(localLink)) {
+      const target = match[3]
+      if (!target || match[1] === '!' || /^(?:[a-z]+:|\/|#)/i.test(target)) continue
+      const targetPath = target.split('#')[0]?.split('?')[0]
+      if (!targetPath || existsSync(resolve(projectRoot, dirname(path), targetPath))) continue
+      const targetStem = basename(targetPath, extname(targetPath)).toLowerCase()
+      const labelStem = (match[2] ?? '').trim().toLowerCase().replace(/[^a-z0-9]+/g, '')
+      const candidates = paths.filter((candidate) => basename(candidate, extname(candidate)).toLowerCase() === targetStem || basename(candidate, extname(candidate)).toLowerCase().replace(/[^a-z0-9]+/g, '') === labelStem)
+      if (candidates.length !== 1) continue
+      let replacement = relative(dirname(path), candidates[0]!).split(sep).join('/')
+      if (target.startsWith('./') && !replacement.startsWith('.')) replacement = `./${replacement}`
+      next = next.replace(match[0], match[0].replace(target, replacement))
+    }
+    if (next !== content) changes.push({ path, before: content, after: next })
+  }
+  return changes.length ? makeProposal(projectRoot, options, changes, ['Each replacement has exactly one Markdown target.'], ['All corrected local Markdown links resolve.']) : undefined
+}
+
+export const createArtifactNormalizationProposal = (root: string, artifactPath: string, options: FixProposalOptions): FixProposalV1 | undefined => {
+  const projectRoot = realpathSync.native(resolve(root))
+  const path = artifactPath.split(sep).join('/')
+  const absolute = containedPath(projectRoot, path)
+  if (!absolute || !existsSync(absolute) || !statSync(absolute).isFile()) return undefined
+  const before = readFileSync(absolute, 'utf8')
+  let after: string
+  try { after = `${JSON.stringify(sortJson(JSON.parse(before) as unknown), null, 2)}\n` } catch { return undefined }
+  return after === before ? undefined : makeProposal(projectRoot, options, [{ path: relative(projectRoot, absolute).split(sep).join('/'), before, after }], ['The artifact contains valid JSON.'], ['The artifact is valid canonical JSON with one trailing newline.'])
+}
+
+export const approveFixProposal = (proposalInput: unknown, approvedBy: string, approvedAt = new Date().toISOString()): FixProposalV1 => {
+  const proposal = FixProposalV1Schema.parse(proposalInput)
+  if (proposal.status !== 'proposed') throw new Error(`Only proposed fixes can be approved; received "${proposal.status}".`)
+  const approved = { ...proposal, status: 'approved' as const, approval: { proposalHash: proposal.contentHash, approvedAt, approvedBy }, contentHash: '0'.repeat(64) }
+  return FixProposalV1Schema.parse({ ...approved, contentHash: contentHashForArtifactV1(approved) })
+}
+
+const bindingHash = (proposal: FixProposalV1): string => {
+  const { approval: _approval, contentHash: _contentHash, status: _status, ...rest } = proposal
+  return contentHashForArtifactV1({ ...rest, contentHash: '0'.repeat(64), status: 'proposed' as const })
+}
+
+export const applyFixProposal = (root: string, proposalInput: unknown, options: FixApplyOptions = {}): FixProposalV1 => {
+  const proposal = FixProposalV1Schema.parse(proposalInput)
+  if (proposal.status !== 'approved' || !proposal.approval) throw new Error('Only an explicitly approved fix proposal can be applied.')
+  if (proposal.approval.proposalHash !== bindingHash(proposal)) throw new Error('Approval is not bound to the exact proposal content.')
+  if (options.currentRevision && options.currentRevision !== proposal.baseRevision) throw new Error('The repository revision changed since this proposal was created.')
+  if (!proposal.changes?.length) throw new Error('This proposal has no executable changes.')
+
+  const projectRoot = realpathSync.native(resolve(root))
+  const originals = new Map<string, string>()
+  const affected = new Map(proposal.affectedFiles.map((file) => [file.path, file]))
+  if (proposal.changes.some((change) => !affected.has(change.path) || affected.get(change.path)?.contentHash !== sha256NormalizedV1(change.before)) || affected.size !== proposal.changes.length) {
+    throw new Error('Proposal changes do not match its affected-file hashes.')
+  }
+  for (const file of proposal.affectedFiles) {
+    const absolute = containedPath(projectRoot, file.path)
+    if (!absolute || !existsSync(absolute)) throw new Error(`Affected file is unavailable or escapes the repository root: ${file.path}`)
+    const current = readFileSync(absolute, 'utf8')
+    if (sha256NormalizedV1(current) !== file.contentHash) throw new Error(`Affected file changed since proposal creation: ${file.path}`)
+    originals.set(absolute, current)
+  }
+
+  try {
+    for (const change of proposal.changes) {
+      const absolute = resolve(projectRoot, change.path)
+      writeFileSync(`${absolute}.docbridge-${process.pid}.tmp`, change.after, 'utf8')
+    }
+    for (const change of proposal.changes) {
+      const absolute = resolve(projectRoot, change.path)
+      renameSync(`${absolute}.docbridge-${process.pid}.tmp`, absolute)
+    }
+    for (const change of proposal.changes) {
+      if (readFileSync(resolve(projectRoot, change.path), 'utf8') !== change.after) throw new Error(`Postcondition failed for ${change.path}`)
+    }
+    options.verify?.(proposal.changes.map((change) => change.path))
+  } catch (error) {
+    for (const [absolute, content] of originals) writeFileSync(absolute, content, 'utf8')
+    for (const change of proposal.changes) {
+      const temp = `${resolve(projectRoot, change.path)}.docbridge-${process.pid}.tmp`
+      if (existsSync(temp)) unlinkSync(temp)
+    }
+    throw error
+  }
+  const applied = { ...proposal, status: 'applied' as const, contentHash: '0'.repeat(64) }
+  return FixProposalV1Schema.parse({ ...applied, contentHash: contentHashForArtifactV1(applied) })
+}

package/src/index-builder/content-hash.ts

@@ -13,7 +13,14 @@ const sortValue = (value: unknown): unknown => {
   return value
 }
 
+export const canonicalJsonV1 = (payload: unknown): string => JSON.stringify(sortValue(payload))
+
 export const sha256NormalizedV1 = (payload: unknown): string => {
-  const normalized = JSON.stringify(sortValue(payload))
+  const normalized = canonicalJsonV1(payload)
   return createHash('sha256').update(normalized, 'utf8').digest('hex')
-}
+}
+
+export const contentHashForArtifactV1 = <T extends { readonly contentHash: string }>(artifact: T): string => {
+  const { contentHash: _contentHash, ...payload } = artifact
+  return sha256NormalizedV1(payload)
+}

package/src/index.ts

@@ -15,6 +15,16 @@ export {
   type DocBridgeConfigV1,
   type AgentCorpusConfig,
   type DocumentationStandardV1Config,
+  RuleIdSchema,
+  RuleSeveritySchema,
+  RulesConfigSchema,
+  WorkflowConfigSchema,
+  RepositorySafetyConfigSchema,
+  type RuleId,
+  type RuleSeverity,
+  type RulesConfig,
+  type WorkflowConfig,
+  type RepositorySafetyConfig,
 } from './config/schema.js'
 
 export {
@@ -55,16 +65,63 @@ export {
 
 export {
   parseAgentHandoff,
+  parseAgentProposal,
   parseAgentSearch,
   parseDocBridgeConfig,
   parseDocBridgeIndex,
+  parseDiscoverySnapshot,
+  parseFixProposal,
   parseMemoryCandidate,
+  parseReconciliationReport,
+  parseWorkflowRun,
   safeParseAgentHandoff,
   type ParseIssue,
   type ParseResult,
 } from './validate.js'
 
 export { buildDocBridgeIndex, type BuildIndexOptions, type BuildIndexResult } from './index-builder/build-index.js'
+export { discoverRepository, type DiscoveryOptions } from './discovery/repository.js'
+export { containedPath, DEFAULT_SAFETY_EXCLUDES, redactSecrets, redactValue, safeWalkFiles, type SafeWalkOptions, type SafeWalkResult } from './safety/repository.js'
+export { DEFAULT_REGISTRY_AGENT_ID, createRegistryAgentAdapter, loadRegistryAgentMetadata, loadRegistryAgentRunner, persistRegistryAgentProposal, type RegistryAgentAdapter, type RegistryAgentContext, type RegistryAgentMetadata, type RegistryAgentRunner } from './agents/registry-adapter.js'
+export {
+  applyDocumentationDeclarations,
+  parseDocumentationDeclarations,
+  type DocumentationAnalysisResult,
+  type DocumentationDeclarationInput,
+  type DocumentationDeclarationOptions,
+  type DocumentationDeclarationResult,
+  type DocumentationDiagnostic,
+} from './discovery/documentation.js'
+export { reconcileKnowledge } from './reconciliation/reconcile.js'
+export { renderOfflineReport, type OfflineReportInput, type OfflineReportOptions } from './report/html.js'
+export {
+  applyFixProposal,
+  approveFixProposal,
+  createArtifactNormalizationProposal,
+  createMarkdownLinkFixProposal,
+  type FixApplyOptions,
+  type FixProposalOptions,
+} from './fixes/proposals.js'
+export {
+  WORKFLOW_STAGES,
+  loadWorkflowManifest,
+  loadWorkflowStepOutput,
+  runWorkflow,
+  type WorkflowExecutionResult,
+  type WorkflowOptions,
+  type WorkflowStage,
+  type WorkflowStageContext,
+  type WorkflowStageHandler,
+} from './workflow/engine.js'
+export {
+  evaluateRules,
+  parseRuleId,
+  parseRuleSeverity,
+  type RuleEngineOptions,
+  type RuleEvaluationResult,
+  type RuleFinding,
+  type RuleMode,
+} from './rules/engine.js'
 export {
   formatEcosystemLlmsBlock,
   formatEcosystemLlmsSection,
@@ -98,7 +155,7 @@ export {
   type DocumentationStandardRuleResult,
   type DocumentationStandardRuleStatus,
 } from './conformance/documentation-standard-v1.js'
-export { MCP_TOOLS, handleMcpRequest, startMcpStdioServer } from './mcp/server.js'
+export { MCP_TOOLS, handleMcpRequest, respondMcpRequest, startMcpStdioServer } from './mcp/server.js'
 export { installMcpConfig, mcpSnippet, type McpInstallResult, type McpInstallTarget } from './mcp/install.js'
 export { runDoctor, formatDoctorText, type DoctorReport, type DoctorIssue, type DoctorCoverage } from './doctor/run-doctor.js'
 export {
@@ -115,7 +172,47 @@ export {
   type GithubPrOptions,
   type GithubPrResult,
 } from './memory/github-pr.js'
-export { sha256NormalizedV1 } from './index-builder/content-hash.js'
+export { canonicalJsonV1, contentHashForArtifactV1, sha256NormalizedV1 } from './index-builder/content-hash.js'
+export {
+  AgentProposalV1Schema,
+  AffectedFileSchema,
+  CoverageSchema,
+  DiagnosticSeveritySchema,
+  DiscoverySnapshotV1Schema,
+  EntitySchema,
+  EvidenceSchema,
+  EvidenceSourceSchema,
+  FindingStatusSchema,
+  FixProposalStatusSchema,
+  FixChangeSchema,
+  FixProposalV1Schema,
+  KNOWLEDGE_CONTENT_HASH_ALGO,
+  KNOWLEDGE_SCHEMA_VERSION,
+  ProvenanceSchema,
+  ProjectIdentitySchema,
+  ProposalOriginSchema,
+  ReconciliationReportV1Schema,
+  RelationSchema,
+  WorkflowRunV1Schema,
+  WorkflowStepSchema,
+  WorkflowStateSchema,
+  WorkflowTransitionSchema,
+  type AgentProposalV1,
+  type DiagnosticSeverity,
+  type DiscoverySnapshotV1,
+  type Evidence,
+  type FindingStatus,
+  type FixProposalV1,
+  type FixChange,
+  type KnowledgeArtifactV1,
+  type KnowledgeDiagnostic,
+  type KnowledgeEntity,
+  type KnowledgeRelation,
+  type Provenance,
+  type ReconciliationReportV1,
+  type WorkflowRunV1,
+  type WorkflowState,
+} from './schemas/knowledge.js'
 export { IndexNotFoundError, indexFilePath, loadDocBridgeIndex, resolveRoot } from './query/load-index.js'
 export { runQuery, type QueryKind, type QueryRequest, type QueryResult } from './query/query.js'
 export { searchIndex, type SearchMatch } from './query/search.js'

package/src/mcp/server.ts

@@ -1,5 +1,5 @@
-import { readFileSync, realpathSync } from 'node:fs'
-import { relative, resolve } from 'node:path'
+import { mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
 
 import { z, ZodError } from 'zod'
 
@@ -13,6 +13,14 @@ import { runQuery } from '../query/query.js'
 import { searchIndex } from '../query/search.js'
 import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
 import { PACKAGE_VERSION } from '../version.js'
+import { loadWorkflowManifest, loadWorkflowStepOutput } from '../workflow/engine.js'
+import { parseDiscoverySnapshot, parseReconciliationReport } from '../validate.js'
+import { applyFixProposal, approveFixProposal, createArtifactNormalizationProposal, createMarkdownLinkFixProposal } from '../fixes/proposals.js'
+import { createRegistryAgentAdapter, loadRegistryAgentRunner, persistRegistryAgentProposal } from '../agents/registry-adapter.js'
+import { sha256NormalizedV1 } from '../index-builder/content-hash.js'
+import { discoverRepository } from '../discovery/repository.js'
+import { FixProposalV1Schema, type DiscoverySnapshotV1, type ReconciliationReportV1, type FixProposalV1 } from '../schemas/knowledge.js'
+import { redactValue } from '../safety/repository.js'
 
 type JsonRpcRequest = {
   readonly jsonrpc?: '2.0'
@@ -99,6 +107,47 @@ export const MCP_TOOLS = [
     annotations: { readOnlyHint: true },
     inputSchema: { type: 'object', properties: {} },
   },
+  {
+    name: 'docbridge.snapshot',
+    title: 'Read the latest discovery snapshot',
+    description: 'Read the bounded canonical repository snapshot from the latest workflow run.',
+    annotations: { readOnlyHint: true },
+    inputSchema: { type: 'object', properties: { runId: { type: 'string' } } },
+  },
+  {
+    name: 'docbridge.report',
+    title: 'Read the latest reconciliation report',
+    description: 'Read the canonical reconciliation report from the latest workflow run.',
+    annotations: { readOnlyHint: true },
+    inputSchema: { type: 'object', properties: { runId: { type: 'string' } } },
+  },
+  {
+    name: 'docbridge.diagnostics',
+    title: 'Read reconciliation diagnostics',
+    description: 'Read bounded diagnostics from the latest canonical reconciliation report.',
+    annotations: { readOnlyHint: true },
+    inputSchema: { type: 'object', properties: { status: { type: 'string' }, severity: { type: 'string' } } },
+  },
+  {
+    name: 'docbridge.relations',
+    title: 'Read architecture relations',
+    description: 'Read bounded observed and declared relations from the latest canonical snapshot.',
+    annotations: { readOnlyHint: true },
+    inputSchema: { type: 'object', properties: { kind: { type: 'string' }, limit: { type: 'number' } } },
+  },
+  {
+    name: 'docbridge.run',
+    title: 'Read workflow state',
+    description: 'Read the latest resumable workflow state and artifact references.',
+    annotations: { readOnlyHint: true },
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'docbridge.proposals',
+    title: 'Read or approve proposals',
+    description: 'Create, inspect, approve and apply deterministic proposals through the shared human-gated workflow.',
+    inputSchema: { type: 'object', properties: { action: { type: 'string', enum: ['list', 'propose-links', 'propose-normalize', 'suggest', 'approve', 'apply'] }, proposalHash: { type: 'string' }, artifactPath: { type: 'string' }, approvedBy: { type: 'string' }, proposal: { type: 'object' } } },
+  },
 ] as const
 
 const asRecord = (value: unknown): Record<string, unknown> =>
@@ -126,6 +175,11 @@ const DocGetArgsSchema = z
   })
   .refine((args) => args.id || args.path, 'doc.get requires id or path')
 
+const WorkflowRunArgsSchema = z.object({ runId: z.string().min(1).optional() })
+const DiagnosticsArgsSchema = z.object({ status: z.string().min(1).optional(), severity: z.string().min(1).optional() })
+const RelationsArgsSchema = z.object({ kind: z.string().min(1).optional(), limit: z.number().int().positive().max(500).optional() })
+const ProposalsArgsSchema = z.object({ action: z.enum(['list', 'propose-links', 'propose-normalize', 'suggest', 'approve', 'apply']).optional(), proposalHash: z.string().min(1).optional(), artifactPath: z.string().min(1).optional(), approvedBy: z.string().min(1).optional(), proposal: z.unknown().optional() })
+
 const parseToolArgs = <T>(tool: string, schema: z.ZodType<T>, value: unknown): T => {
   try {
     return schema.parse(value)
@@ -169,6 +223,45 @@ const resolveDocPath = (root: string, relPath: string): string => {
   return abs
 }
 
+const workflowStateDir = (ctx: McpContext): string => resolve(ctx.root, ctx.config.workflow?.stateDir ?? '.doc-bridge/workflow')
+
+const workflowRun = (ctx: McpContext) => loadWorkflowManifest(workflowStateDir(ctx))
+
+const ensureLatestRun = (ctx: McpContext, runId?: string) => {
+  const run = workflowRun(ctx)
+  if (runId && run.runId !== runId) throw new Error(`Unknown workflow run "${runId}"`)
+  if (run.state === 'stale' || run.state === 'failed') throw new Error(`Workflow run is ${run.state}; resume or create a valid run before reading artifacts.`)
+  return run
+}
+
+const workflowSnapshot = (ctx: McpContext, runId?: string): DiscoverySnapshotV1 => {
+  ensureLatestRun(ctx, runId)
+  return parseDiscoverySnapshot(loadWorkflowStepOutput(workflowStateDir(ctx), 'normalize'))
+}
+
+const workflowReport = (ctx: McpContext, runId?: string): ReconciliationReportV1 => {
+  ensureLatestRun(ctx, runId)
+  return parseReconciliationReport(loadWorkflowStepOutput(workflowStateDir(ctx), 'reconcile'))
+}
+
+const proposalPath = (ctx: McpContext): string => join(ctx.root, '.doc-bridge', 'proposal.json')
+const readSavedProposal = (ctx: McpContext, input: unknown): FixProposalV1 => {
+  if (input !== undefined) return FixProposalV1Schema.parse(input)
+  try { return FixProposalV1Schema.parse(JSON.parse(readFileSync(proposalPath(ctx), 'utf8')) as unknown) } catch { throw new Error(`No saved fix proposal at ${proposalPath(ctx)}.`) }
+}
+const saveProposal = (ctx: McpContext, proposal: FixProposalV1): void => { mkdirSync(join(ctx.root, '.doc-bridge'), { recursive: true }); writeFileSync(proposalPath(ctx), `${JSON.stringify(proposal, null, 2)}\n`, 'utf8') }
+
+const enabledMcpTools = (ctx: McpContext) => {
+  const configured = ctx.config.surfaces?.mcp?.tools
+  if (!configured || configured.length === MCP_TOOLS.length && MCP_TOOLS.every((tool) => configured.includes(tool.name as typeof configured[number]))) return MCP_TOOLS
+  return MCP_TOOLS.filter((tool) => configured.includes(tool.name as typeof configured[number]))
+}
+
+const assertMcpToolEnabled = (ctx: McpContext, name: string): void => {
+  if (!MCP_TOOLS.some((tool) => tool.name === name)) throw new Error(`Unknown tool "${name}"`)
+  if (!enabledMcpTools(ctx).some((tool) => tool.name === name)) throw new Error(`MCP tool "${name}" is disabled by configuration.`)
+}
+
 export const handleMcpRequest = (ctx: McpContext, request: JsonRpcRequest): unknown => {
   if (request.method === 'initialize') {
     return {
@@ -178,12 +271,14 @@ export const handleMcpRequest = (ctx: McpContext, request: JsonRpcRequest): unkn
     }
   }
 
-  if (request.method === 'tools/list') return { tools: MCP_TOOLS }
+  if (request.method === 'tools/list') return { tools: enabledMcpTools(ctx) }
 
   if (request.method === 'tools/call') {
     const params = asRecord(request.params)
     const name = params.name
     const args = asRecord(params.arguments)
+    if (typeof name !== 'string') throw new Error('MCP tools/call requires a tool name.')
+    assertMcpToolEnabled(ctx, name)
     const index = () => ctx.loadIndex?.() ?? loadDocBridgeIndex(ctx.root, ctx.config)
 
     if (name === 'handoff.resolve') {
@@ -232,6 +327,77 @@ export const handleMcpRequest = (ctx: McpContext, request: JsonRpcRequest): unkn
       })
     }
 
+    if (name === 'docbridge.snapshot') {
+      const parsed = parseToolArgs('docbridge.snapshot', WorkflowRunArgsSchema, args)
+      return textResult(redactValue(workflowSnapshot(ctx, parsed.runId)))
+    }
+
+    if (name === 'docbridge.report') {
+      const parsed = parseToolArgs('docbridge.report', WorkflowRunArgsSchema, args)
+      return textResult(redactValue(workflowReport(ctx, parsed.runId)))
+    }
+
+    if (name === 'docbridge.diagnostics') {
+      const parsed = parseToolArgs('docbridge.diagnostics', DiagnosticsArgsSchema, args)
+      const diagnostics = workflowReport(ctx).diagnostics.filter((diagnostic) =>
+        (!parsed.status || diagnostic.status === parsed.status) && (!parsed.severity || diagnostic.severity === parsed.severity),
+      )
+      return textResult(redactValue({ reportHash: workflowReport(ctx).contentHash, diagnostics }))
+    }
+
+    if (name === 'docbridge.relations') {
+      const parsed = parseToolArgs('docbridge.relations', RelationsArgsSchema, args)
+      const snapshot = workflowSnapshot(ctx)
+      return textResult({ snapshotHash: snapshot.contentHash, relations: snapshot.relations.filter((relation) => !parsed.kind || relation.kind === parsed.kind).slice(0, parsed.limit ?? 100) })
+    }
+
+    if (name === 'docbridge.run') {
+      parseToolArgs('docbridge.run', z.object({}), args)
+      return textResult(workflowRun(ctx))
+    }
+
+    if (name === 'docbridge.proposals') {
+      const parsed = parseToolArgs('docbridge.proposals', ProposalsArgsSchema, args)
+      const run = (() => { try { return workflowRun(ctx) } catch { return undefined } })()
+      if (!parsed.action || parsed.action === 'list') {
+        let proposal: FixProposalV1 | undefined
+        try { proposal = readSavedProposal(ctx, undefined) } catch { proposal = undefined }
+        return textResult(redactValue({ ...(run ? { runId: run.runId } : {}), proposals: proposal ? [proposal] : [] }))
+      }
+      if (parsed.action === 'suggest') {
+        return loadRegistryAgentRunner(ctx.root, ctx.config).then(async (runner) => {
+          const snapshot = workflowSnapshot(ctx)
+          const report = workflowReport(ctx)
+          const adapter = createRegistryAgentAdapter(ctx.root, ctx.config, runner)
+          const proposal = await adapter.run(snapshot, report)
+          const savedPath = persistRegistryAgentProposal(workflowStateDir(ctx), proposal)
+          return textResult(redactValue({ ...(run ? { runId: run.runId } : {}), proposal, proposalPath: savedPath }))
+        })
+      }
+      const discovered = discoverRepository({ root: ctx.root, config: ctx.config })
+      const options = { baseRevision: discovered.sourceRevision, configurationHash: sha256NormalizedV1(ctx.config), ...(ctx.config.project?.name ? { projectName: ctx.config.project.name } : {}) }
+      if (parsed.action === 'propose-links') {
+        const proposal = createMarkdownLinkFixProposal(ctx.root, options)
+        if (proposal) saveProposal(ctx, proposal)
+        return textResult(redactValue({ ...(run ? { runId: run.runId } : {}), proposal: proposal ?? null }))
+      }
+      if (parsed.action === 'propose-normalize') {
+        if (!parsed.artifactPath) throw new Error('docbridge.proposals propose-normalize requires artifactPath')
+        const proposal = createArtifactNormalizationProposal(ctx.root, parsed.artifactPath, options)
+        if (proposal) saveProposal(ctx, proposal)
+        return textResult(redactValue({ ...(run ? { runId: run.runId } : {}), proposal: proposal ?? null }))
+      }
+      if (parsed.action === 'approve') {
+        const proposal = approveFixProposal(readSavedProposal(ctx, parsed.proposal), parsed.approvedBy ?? 'human')
+        if (parsed.proposalHash && proposal.approval?.proposalHash !== parsed.proposalHash) throw new Error('proposalHash does not match the saved proposal')
+        saveProposal(ctx, proposal)
+        return textResult(redactValue({ ...(run ? { runId: run.runId } : {}), proposal }))
+      }
+      const proposal = applyFixProposal(ctx.root, readSavedProposal(ctx, parsed.proposal), { currentRevision: discovered.sourceRevision })
+      saveProposal(ctx, proposal)
+      return textResult(redactValue({ ...(run ? { runId: run.runId } : {}), proposal }))
+    }
+
     throw new Error(`Unknown tool "${String(name)}"`)
   }
 
@@ -246,10 +412,10 @@ const writeFrame = (payload: unknown, framing: StdioFraming): void => {
   process.stdout.write(framing === 'json-line' ? `${body}\n` : `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`)
 }
 
-const respond = (ctx: McpContext, request: JsonRpcRequest, framing: StdioFraming): void => {
+export const respondMcpRequest = async (ctx: McpContext, request: JsonRpcRequest, framing: StdioFraming): Promise<void> => {
   if (request.id === undefined) {
     try {
-      handleMcpRequest(ctx, request)
+      await handleMcpRequest(ctx, request)
     } catch {
       // Notifications do not get responses.
     }
@@ -257,7 +423,7 @@ const respond = (ctx: McpContext, request: JsonRpcRequest, framing: StdioFraming
   }
 
   try {
-    const result = handleMcpRequest(ctx, request)
+    const result = await handleMcpRequest(ctx, request)
     writeFrame({ jsonrpc: '2.0', id: request.id, result: result ?? {} }, framing)
   } catch (error) {
     writeFrame({
@@ -270,6 +436,10 @@ const respond = (ctx: McpContext, request: JsonRpcRequest, framing: StdioFraming
 
 export const startMcpStdioServer = (ctx: McpContext): void => {
   let buffer = Buffer.alloc(0)
+  let responseChain = Promise.resolve()
+  const enqueueResponse = (request: JsonRpcRequest, framing: StdioFraming): void => {
+    responseChain = responseChain.then(() => respondMcpRequest(ctx, request, framing))
+  }
   process.stdin.on('data', (chunk: Buffer) => {
     buffer = Buffer.concat([buffer, chunk])
     while (true) {
@@ -288,7 +458,7 @@ export const startMcpStdioServer = (ctx: McpContext): void => {
         if (buffer.length < bodyEnd) return
         const raw = buffer.subarray(bodyStart, bodyEnd).toString('utf8')
         buffer = buffer.subarray(bodyEnd)
-        respond(ctx, JSON.parse(raw) as JsonRpcRequest, 'content-length')
+        enqueueResponse(JSON.parse(raw) as JsonRpcRequest, 'content-length')
         continue
       }
 
@@ -298,7 +468,7 @@ export const startMcpStdioServer = (ctx: McpContext): void => {
       buffer = buffer.subarray(lineEnd + 1)
       if (!raw) continue
       try {
-        respond(ctx, JSON.parse(raw) as JsonRpcRequest, 'json-line')
+        enqueueResponse(JSON.parse(raw) as JsonRpcRequest, 'json-line')
       } catch {
         writeFrame({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }, 'json-line')
       }