FE-870: Renderer golden coverage and agent-context tools#217
Conversation
The per-turn pushed context blocks (workspace + graph seeds) are a session-context-composition concern, not a system-prompt one. Relocate them and the AgentPrompt*Context types + renderSoftReadinessEstimate from .pi/extensions/system-prompts into src/session/agent-context-seed.ts, so the prompt layer consumes a context bundle it no longer owns. The Pi extension performs the PULL (queryGraph) and delegates RENDER/COMPOSE to composeAgentContextSeed. Verbatim move; output and tests unchanged. Amp-Thread-ID: https://ampcode.com/threads/T-019ecb11-98d3-716c-9224-f95c9e6b28ca Co-authored-by: Amp <amp@ampcode.com>
Per-turn prompt composition re-ran the expensive SQL pair queryGraph + getElicitationGaps every turn, even when the graph was unchanged (e.g. cycling operational modes / agent prompts). Add a cheap latestGraphLsn reader path and a world-read memo that gates those reads behind the per-spec graph clock: unchanged (spec, lsn) reuses prior reads, a changed LSN or spec refreshes. Lens-dependent seed rendering still happens fresh per prompt; only the underlying reads are cached. Amp-Thread-ID: https://ampcode.com/threads/T-019ecb11-98d3-716c-9224-f95c9e6b28ca Co-authored-by: Amp <amp@ampcode.com>
|
Warning This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
This stack of pull requests is managed by Graphite. Learn more about stacking. |
lunelson
changed the title
PR SummaryMedium Risk Overview Graph readers gain Smaller deltas: Brunch CLI uses Reviewed by Cursor Bugbot for commit c5dd2a2. Bugbot is set up for automated code reviews on this repo. Configure here. |
There was a problem hiding this comment.
Pull request overview
This PR advances the “renderer/context coverage frontier” by moving per-turn agent context seed rendering into session/ (so prompt composition consumes a prepared bundle), adding a cheap graph LSN read to avoid unnecessary graph/gap reads across mode/prompt recompositions, and updating the .pi/agents asset topology.
Changes:
- Introduces
composeAgentContextSeed/renderWorkspaceSeed/renderGraphSeedinsrc/session/agent-context-seed.tswith new golden-ish unit tests. - Adds
latestGraphLsnand threads alatestLsnread through graph reader interfaces, plus aWorldReadCachememo in prompt composition to reusequeryGraph/getElicitationGapswhen the LSN is unchanged. - Refactors CLI arg parsing to
node:utilparseArgs, and updates.pi/agentsmarkdown layout + build asset copy step accordingly.
Reviewed changes
Copilot reviewed 28 out of 32 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| src/web/app.test.tsx | Adds a window.scrollTo stub for jsdom-based web tests. |
| src/session/agent-context-seed.ts | New session-owned renderer for the per-turn pushed context blocks (workspace + selected-spec graph). |
| src/session/agent-context-seed.test.ts | Adds/adjusts tests covering workspace seed rendering and context seed composition. |
| src/graph/workspace-store.ts | Threads a cheap LSN read (latestLsn) into spec-scoped graph readers. |
| src/graph/queries.ts | Exposes latestGraphLsn and reuses it in queryGraph clock stamping. |
| src/dev/tier-2-harness.ts | Allows tier-2 harness boots to override agent services; adds a no-model services helper. |
| src/dev/faux-harness.test.ts | Updates harness stubs to satisfy the new latestLsn reader shape. |
| src/dev/brunch-dev.ts | Centralizes BRUNCH_DEV env gating in a dev utility module. |
| src/app/brunch.ts | Refactors CLI parsing to parseArgs; moves isBrunchDevEnabled import to src/dev/. |
| src/app/brunch.test.ts | Updates CLI tests to match the new boolean flag parsing behavior. |
| src/app/brunch-tui.ts | Moves isBrunchDevEnabled import and threads latestLsn into prompt graph reads. |
| src/app/brunch-tui.test.ts | Updates prompt graph read stubs with latestLsn. |
| src/.pi/extensions/system-prompts/world-reads.ts | Adds a memo/cache to reuse graph/gap reads when (specId, lsn) is unchanged. |
| src/.pi/extensions/system-prompts/world-reads.test.ts | Adds tests proving read reuse vs refresh based on LSN/spec changes. |
| src/.pi/extensions/system-prompts/seed/workspace.ts | Deleted (workspace seed rendering relocated to src/session/agent-context-seed.ts). |
| src/.pi/extensions/system-prompts/seed/workspace.test.ts | Deleted (tests relocated to src/session/agent-context-seed.test.ts). |
| src/.pi/extensions/system-prompts/seed/graph.ts | Deleted (graph seed rendering relocated to src/session/agent-context-seed.ts). |
| src/.pi/extensions/system-prompts/index.ts | Switches to WorldReadCache + composeAgentContextSeed for prompt context assembly. |
| src/.pi/extensions/system-prompts/compose.ts | Imports readiness estimate rendering/types from the new session context-seed module. |
| src/.pi/extensions/runtime/state.ts | Removes the definitions prompt-resource family path logic; simplifies resource locations to skills. |
| src/.pi/extensions/graph/index.ts | Extends GraphReaders with latestLsn(specId) for cheap change detection. |
| src/.pi/extensions/graph/command-adapter.ts | Cleans up unused graph-slice type import. |
| src/.pi/agents/reviewer.md | Adds a reviewer agent definition markdown at the new flat path. |
| src/.pi/agents/README.md | Updates topology docs for flat src/.pi/agents/{agent}.md layout. |
| src/.pi/agents/elicitor.md | Adds an elicitor agent definition markdown at the new flat path. |
| src/.pi/tests/prompting.test.ts | Updates prompt context stubs with latestLsn. |
| src/.pi/tests/graph-tools.test.ts | Wires latestGraphLsn into graph readers used by graph tool tests. |
| src/.pi/tests/extension-registry.test.ts | Updates extension registry stubs with latestLsn. |
| package.json | Updates build:pi-assets to copy flat agent markdown files (excluding README). |
| package-lock.json | Adjusts pi-ai bin path entry (likely from lock regeneration). |
| memory/SPEC.md | Updates spec text to reflect the new flat .pi/agents layout. |
| docs/archive/PLAN_HISTORY.md | Updates archived plan boundary text to reflect the new .pi/agents layout. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| const lsn = graphReads.latestLsn(specId); | ||
| if (cached && cached.specId === specId && cached.lsn === lsn) { | ||
| return cached.reads; | ||
| } | ||
| const reads: WorldReads = { | ||
| graph: graphReads.queryGraph(), | ||
| gaps: graphReads.getElicitationGaps(specId), | ||
| }; | ||
| cached = { specId, lsn, reads }; | ||
| return reads; |
| beforeAll(() => { | ||
| Object.defineProperty(window, 'scrollTo', { value: vi.fn(), writable: true }); | ||
| }); |
Stack Context
This stack is a post-demo rehabilitation pass. The previous PRs stabilize runtime/tooling and clarify prompt/runtime topology; this PR starts the deferred renderer/context coverage frontier.
What?
Why?
Renderer output is lossy and LLM/user-facing, so it needs golden locks plus semantic invariants. This PR focuses on that RENDER-stage coverage without making it a ship gate.