Atlas foundation: codebase-knowledge layer in Pathfinder (off-by-default)#94
Merged
Conversation
A transient failure in markAtlasCachePagesStaleForSources caused executeJob to reject, so onReindexComplete never fired for a reindex that actually succeeded — suppressing bash-instance refresh, llms.txt/ faq.txt cache clearing, and the reindex audit. Wrap the Atlas cache invalidation call in its own try/catch that logs and continues, keeping it before the callback but unable to suppress it.
The per-page catch in gardenAtlasCachePages persisted the generation error to the DB but never logged it, leaving operators blind. Worse, the recordAtlasCachePageGenerationError call was unguarded: if it threw (e.g. "Atlas cache page not found" on a concurrently deleted/re-keyed row, or any transient DB error), the rejection escaped the loop and aborted the entire gardening pass, losing all prior progress and never returning a summary. Now the generation failure is logged via console.error, and the bookkeeping call is wrapped in its own try/catch that logs and continues so a single page's bookkeeping failure can't poison the batch. Adds a red-green test covering the bookkeeping-throws case.
- parseSseMessages now skips empty/whitespace `data:` frames (keepalives) and wraps per-event JSON.parse so unparseable frames are skipped instead of crashing the search command with an opaque "Unexpected end of JSON input" error. - DEFAULT_TOOL is now "atlas-search" to match the Atlas tool name in pathfinder.example.yaml, so `atlas search "x"` targets Atlas by default instead of the docs search tool. Adds red-green tests: an empty `data:` SSE frame that previously crashed, and a default-tool assertion pinned to "atlas-search".
…path keys Finding 1 (HIGH): approveAtlasCandidate silently returned 200 without queuing a reindex when no orchestrator was wired (Atlas sources but no search/knowledge tools). Now log a loud, actionable error and surface reindexQueued:boolean in the JSON response. The orchestrator-present 200 path is unchanged. Finding 2: the path-param approve/reject routes used :canonicalKey, which a literal "/" in a real key (e.g. "github-pr:atlas:owner/repo:42") would truncate, addressing the wrong key. Switch to an Express 5 wildcard param (*canonicalKey) and reconstruct/decode the full key in atlasCanonicalKey, so both %2F-escaped and literal-slash keys round-trip. Body-based routes are untouched. Tests: add red-green coverage for both findings in atlas-ratification-endpoints.test.ts.
The path-param wildcard routes (POST /api/atlas/candidates/*canonicalKey/ approve and /reject) double-decoded the key (Express 5 decodes wildcard segments, then decodeURIComponent ran again, corrupting %XX keys), were body/path-inconsistent, and were fully redundant with the working body-based routes. Drop both registrations and the now-unused atlasCanonicalKey(req) helper. Keep the body routes, atlasCanonicalKeyFromBody, and the approve-without-orchestrator fix. Convert the surviving tests to the body route and remove the path-param-only slash-key test.
Add an `atlas feedback` subcommand that wraps the submit-feedback collect tool through a shared callTool helper. Harden response-frame selection: coerced JSON-RPC id matching, id-less error/result fallback, result.isError surfaced as exit 1, missing-response now fails loud, and non-array content is guarded. Add fail-loud guards for the `--for` and `--tool` flags.
jpr5
added a commit
that referenced
this pull request
Jun 6, 2026
## Summary Version-only release cut. Bumps `@copilotkit/pathfinder` **1.13.3 → 1.14.0** so the version-gated `publish-release.yml` workflow fires on merge and publishes `@copilotkit/pathfinder@1.14.0` to npm — carrying the new `bin.atlas` CLI. The server/source code is **unchanged from #94** (commit `d43b88e`), which is already deployed to prod; this PR only changes the version (`package.json`, `package-lock.json`, `src/cli.ts`) and adds a CHANGELOG entry. ### Why - The npm publish is version-gated: pushing to `main` publishes only when `package.json` version is unpublished. `1.14.0` is not yet on npm (verified `npm view @copilotkit/pathfinder@1.14.0` → 404), so merging this fires the publish. - Unblocks internal-skills #121, which needs to pin `@copilotkit/pathfinder@1.14.0` for the `atlas` CLI. ### What 1.14.0 ships (all from #94, now released) - **`atlas` CLI** — first-party client as `bin.atlas`: `atlas search` + `atlas feedback`, with hardened `tools/call` response handling. - **`prepublishOnly` build guard** — the published tarball always ships a fresh `dist/` (incl. `dist/atlas-cli.js`). - **Atlas foundation** — off-by-default codebase-knowledge layer: additive schema, ratification endpoints, gardener, webhook PR ingestion. Disabled unless explicitly enabled; existing deployments unaffected. ### Bump rationale Minor bump (new additive `atlas` CLI feature, backward compatible). Repo uses a plain `package.json` version bump (no changesets/release-please). `src/cli.ts` `.version()` bumped in lockstep to satisfy the `version-sync` CI gate and the publish workflow's "Verify CLI version matches package version" check. ## Local gate results (node 25 / `/tmp/pf-release`) - prettier `--check` (package.json, src/cli.ts, CHANGELOG.md): **clean** - `scripts/check-version-sync.sh`: **✓ in sync (1.14.0)** - `npx tsc --noEmit`: **0 errors** - `npm run build`: **succeeds**, emits `dist/atlas-cli.js`, `dist/cli.js`, `dist/index.js` - `npm test`: **3712 passed (254 files)** after build (CI test job builds before testing, matching this order) ## Merge note Do **not** auto-merge. The orchestrator will merge after the prod deploy is confirmed healthy; merge fires the npm publish.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the Atlas foundation to Pathfinder — an agent-maintained codebase-knowledge layer (the "codebase-memory" quadrant alongside auto-memory, handoffs, and episodic memory). This PR lands the foundation dormant / off-by-default: the schema, providers, gardener, ratification endpoints, webhook ingestion, analytics, and a thin
atlasCLI are all present and tested, but no operational loop is scheduled and no behavior changes for existing Pathfinder users.What's included
atlas_seed_entries(durable inputs — decisions/corrections/inbox/schema) andatlas_cache_pages(regenerable derived pages). Durability attaches to inputs, not the wiki.AtlasDataProvider(src/db/atlas.ts) — seed + cache persistence.src/indexing/atlas-gardener.ts) — regenerates cache pages from seed; hardened error path (logs failures, guards bookkeeping).src/server.ts) — body-param routes for approving/rejecting seed entries (path-param variants intentionally dropped — see below).src/webhooks/) — capture is webhook-driven server-side, not agent-driven.src/db/analytics.ts) — Atlas retrievals excluded from standard/analytics.atlas-cli.ts— thin stateless MCP client so agents (esp. Codex, which struggles with MCP reconnect) get a first-classatlas search "<question>"access path without configuring an MCP server.Scope notes
Deferred wiring follow-up (pilot prerequisite — NOT in this PR)
The operational loop is a deliberate follow-up, required before the pilot:
service:session tagging on retrievalsseed_pathwiring (seed lives in a privatebackofficesidecar for the pilot, not in-repo)Pilot repos:
copilotkit/copilotkit+ag-ui-protocol/ag-ui.Test plan
tsc --noEmit— 0 errors