Context
Operators have no visibility into how far a Knowledge Base ingestion run has progressed. During a long ingestion (re-sync, fresh deploy, large source set) the only signals are the process being alive and the eventual completion — there is no progress readout (sources seen / embedded / remaining, current phase, ETA). This is a blind spot for any operator running or supervising an ingestion.
The Problem
Ingestion is a long-running, multi-phase operation (enumerate sources → chunk → embed → upsert). Without a progress surface, an operator cannot distinguish "healthy but slow" from "stalled," cannot estimate completion, and cannot decide whether to wait or intervene. The default healthcheck deliberately stays lean (liveness/readiness) and must NOT be bloated with progress detail.
The Architectural Reality
- KB MCP server:
ai/mcp/server/knowledge-base/ (openapi.yaml + tool service + service methods).
KnowledgeBaseIngestionService / VectorService own the ingestion phases (enumerate / filter-budget / chunk / embed / upsert).- A new MCP tool touches multiple sites (openapi.yaml, tool service, service method, compliance fixtures, unit
autoConnect=false) — see the NL-tool wiring checklist; the same multi-site discipline applies to a KB tool.
The Fix
Either a new KB MCP tool get_ingestion_progress OR a field on an existing diagnostics tool (NOT the default healthcheck — keep that lean). Reports: current phase, total/seen/embedded/skipped/remaining source counts, last-progress timestamp, and (if cheaply derivable) a rate/ETA. Read-only.
Contract Ledger Matrix
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
KB get_ingestion_progress (or diagnostics field) |
KB ingestion service phase/counter state |
Read-only progress snapshot: phase + per-phase counts + last-progress ts (+ optional rate/ETA) |
If no ingestion active, report idle/last-run-summary |
openapi.yaml tool description (budget-compliant) + skill payload |
Unit coverage for active/idle/stalled snapshots |
Decision Record impact
none — adds a read-only observability surface; does not change ingestion behavior or topology.
Acceptance Criteria
Out of Scope
- Auto-intervention on a stalled ingestion (that is detect-signal / immune-system territory — see #14026).
- Bloating the default healthcheck.
Related
- #14026 — data-integrity detect-signal (a stalled/incomplete ingestion is an adjacent signal).
- #13551 — embed-drain liveness watchdog (the WAL-backlog analogue for the drain path).
Origin Session ID: 58acd7a6-778e-4fe6-b85a-4569802ac57b
Handoff Retrieval Hints: query_raw_memories("KB ingestion progress visibility get_ingestion_progress diagnostics tool"); anchors: ai/mcp/server/knowledge-base/, KnowledgeBaseIngestionService, VectorService.
Authored-by: @neo-opus-vega (Vega, Claude Opus 4.8)
Context
Operators have no visibility into how far a Knowledge Base ingestion run has progressed. During a long ingestion (re-sync, fresh deploy, large source set) the only signals are the process being alive and the eventual completion — there is no progress readout (sources seen / embedded / remaining, current phase, ETA). This is a blind spot for any operator running or supervising an ingestion.
The Problem
Ingestion is a long-running, multi-phase operation (enumerate sources → chunk → embed → upsert). Without a progress surface, an operator cannot distinguish "healthy but slow" from "stalled," cannot estimate completion, and cannot decide whether to wait or intervene. The default healthcheck deliberately stays lean (liveness/readiness) and must NOT be bloated with progress detail.
The Architectural Reality
ai/mcp/server/knowledge-base/(openapi.yaml + tool service + service methods).KnowledgeBaseIngestionService/VectorServiceown the ingestion phases (enumerate / filter-budget / chunk / embed / upsert).autoConnect=false) — see the NL-tool wiring checklist; the same multi-site discipline applies to a KB tool.The Fix
Either a new KB MCP tool
get_ingestion_progressOR a field on an existing diagnostics tool (NOT the default healthcheck — keep that lean). Reports: current phase, total/seen/embedded/skipped/remaining source counts, last-progress timestamp, and (if cheaply derivable) a rate/ETA. Read-only.Contract Ledger Matrix
get_ingestion_progress(or diagnostics field)Decision Record impact
none— adds a read-only observability surface; does not change ingestion behavior or topology.Acceptance Criteria
Out of Scope
Related
Origin Session ID: 58acd7a6-778e-4fe6-b85a-4569802ac57b
Handoff Retrieval Hints:
query_raw_memories("KB ingestion progress visibility get_ingestion_progress diagnostics tool"); anchors:ai/mcp/server/knowledge-base/,KnowledgeBaseIngestionService,VectorService.Authored-by: @neo-opus-vega (Vega, Claude Opus 4.8)