KB empty response should be cloud-ingestion aware

Context

A live cloud KB diagnostic run on 2026-07-01 found the Knowledge Base server healthy, the Chroma collection present, and the collection count at 0. Calling ask_knowledge_base() against that empty collection returned this guidance:

The knowledge base collection is empty. Populate it with the release artifact via 'npm run ai:download-kb' (or build locally with 'npm run ai:sync-kb').

That message is correct for a local single-repo Neo checkout, but it is misleading for cloud tenant ingestion. A cloud deployment can be intentionally empty until push-mode or pull-mode tenant ingestion writes chunks. In that topology, the first diagnostic branch should point to ingestion state, inspect_deployment / get_deployment_state_snapshot, get_ingestion_progress, tenantRepos[], push hooks, or the bulk tenant ingest path, not only to local curated-KB rebuild/download commands.

Live latest-open sweep: checked the latest 20 open GitHub issues at 2026-07-01T18:28Z; no equivalent open issue found. Closest adjacent tickets were #14408 (deployment snapshot completeness), #14404 (graph-only tenantRepo discovery), and #14396 (tenant-repo-sync diagnostics), which cover deployment diagnostics rather than the query response string. A2A in-flight sweep checked the latest 30 messages; no competing [lane-claim] / [lane-intent] for cloud-aware empty-KB response guidance was present. Semantic KB ticket sweep for empty knowledge base response cloud deployment download-kb sync-kb tenant ingestion ticket returned historical cloud-ingestion work, not this exact response-guidance defect. Exact content sweep found historical #12969, which deliberately added the local ai:download-kb / ai:sync-kb hint, plus the current hard-coded string and tests.

The Problem

The empty-KB response currently collapses two different operator states into one local remedy:

1. Local single-repo Neo checkout has no curated KB rows yet.
2. Cloud deployment KB is healthy but no tenant content has been ingested yet, or tenant ingestion is misconfigured/stale.

For state 1, npm run ai:download-kb / npm run ai:sync-kb is useful. For state 2, that guidance can send operators toward the wrong layer. The correct next diagnostic is to ask why ingestion did not write chunks:

• Is the cloud deployment using push mode or pull mode?
• Does get_ingestion_progress() show an active, completed, skipped, or failed run?
• Does inspect_deployment() expose tenantRepoSync state, including configured repo count and stable failure codes?
• Does the deployment have a mounted kb-config.yaml or graph tenant config for pull mode?
• Did tenant push/bulk ingestion run and report per-file errors?

The remote KB tool should not require the operator or agent to already know this distinction when the collection is empty.

The Architectural Reality

Current source anchors:

• ai/services/knowledge-base/SearchService.mjs:276 returns the local-only empty-collection answer from the ask() path.
• test/playwright/unit/ai/services/knowledge-base/SearchService.noModel.spec.mjs:43 pins that exact answer before model resolution.
• test/playwright/unit/ai/services/knowledge-base/SearchService.spec.mjs:345 asserts the response contains npm run ai:download-kb and npm run ai:sync-kb.
• learn/agentos/cloud-deployment/Troubleshooting.md:185 already frames cloud empty-KB as an ingestion-state question.
• learn/agentos/cloud-deployment/TenantIngestionModel.md:287 says remote diagnostics should use the deployment-state bridge for healthy-but-empty cloud KBs.

The response belongs in the KB search/query layer, not in deployment-state producer logic. It is the user-facing fallback emitted when query context is empty. The implementation must preserve local behavior while making the cloud or remote profile branch explicit.

The Fix

Make the empty-collection ask_knowledge_base response deployment-aware:

• Preserve the local single-repo guidance for local/stdin/default curated KB setups.
• When the KB server is running in a cloud/remote tenant-ingestion profile, return guidance that points first to tenant ingestion diagnostics:
  • get_ingestion_progress() for active/last source-run state.
  • inspect_deployment / get_deployment_state_snapshot for pull-mode tenantRepoSync and deployment bridge state.
  • push-mode ingest_source_files / tenant bulk CLI paths where appropriate.
• Avoid naming any tenant or deployment in the generic response.
• Update the tests so local and cloud/remote empty-collection branches are both pinned.
• Keep answer shape stable: {answer, references: []}.

Contract Ledger Matrix

Decision Record impact

Aligned with ADR 0014 cloud deployment topology and the existing cloud-native KB ingestion model. No ADR amendment expected. This changes diagnostic copy and test coverage, not ingestion authority or tenant isolation semantics.

Acceptance Criteria

• Local empty-collection ask_knowledge_base() still recommends npm run ai:download-kb / npm run ai:sync-kb.
• Cloud or remote tenant-ingestion empty-collection ask_knowledge_base() points to ingestion diagnostics before local curated-KB rebuild commands.
• The response names get_ingestion_progress() and inspect_deployment / get_deployment_state_snapshot where applicable.
• Answer shape stays {answer, references: []}.
• Tests cover local empty response, cloud/remote empty response, and the no-model guard path.
• Cloud troubleshooting docs remain consistent with the tool response.

Out of Scope

• Changing ingestion scheduling, tenant repo sync, Git credentials, or deployment-state snapshot schema.
• Changing Chroma collection creation behavior.
• Changing ai:download-kb or ai:sync-kb semantics.
• Naming any private tenant, repository, or deployment.

Related

• #14408
• #14404
• #14396
• #12969 historical context for the local ai:download-kb hint.
• ai/services/knowledge-base/SearchService.mjs
• learn/agentos/cloud-deployment/Troubleshooting.md
• learn/agentos/cloud-deployment/TenantIngestionModel.md

Origin Session ID: c0dfa949-22de-4daf-bbd2-1e093383fefc

Handoff Retrieval Hints: empty knowledge base response cloud deployment, SearchService empty collection download-kb sync-kb, ask_knowledge_base cloud-aware empty KB guidance.