Skip to content

feat(expose): warm previews from project cache#369

Merged
TraderSamwise merged 5 commits into
masterfrom
feat/expose-snapshot-cache
Jul 20, 2026
Merged

feat(expose): warm previews from project cache#369
TraderSamwise merged 5 commits into
masterfrom
feat/expose-snapshot-cache

Conversation

@TraderSamwise

@TraderSamwise TraderSamwise commented Jul 20, 2026

Copy link
Copy Markdown
Owner

Summary

  • add a project-service Exposé preview cache that periodically captures pane tails in the background
  • enrich switchable-agent and global Exposé item responses with cached preview snapshots when available
  • keep request-time Exposé item routes non-capturing and covered by cache/unit tests

Validation

  • yarn vitest run src/expose-preview-cache.test.ts src/fast-control.test.ts src/metadata-server.test.ts src/daemon.test.ts src/tmux/expose.test.ts
  • yarn vitest run src/expose-preview-cache.test.ts src/metadata-server.test.ts src/daemon.test.ts
  • yarn typecheck
  • yarn lint
  • yarn build
  • yarn test

Summary by CodeRabbit

  • New Features
    • Added optional includePreview=1 support to expose items and switchable-agent controls to return cached terminal preview snapshots when available.
    • Introduced a background preview snapshot cache that tracks demanded items and periodically refreshes snapshots during active windows.
  • Bug Fixes
    • Preview snapshots are preserved when later captures fail, and served consistently for canonical and normalized project root paths.
  • Tests
    • Added end-to-end coverage for preview caching behavior (refresh windows, in-flight demand handling, eviction) and verified includePreview=1 request/response wiring across expose scopes.

@vercel

vercel Bot commented Jul 20, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
app Ready Ready Preview, Comment Jul 20, 2026 3:37pm

@coderabbitai

coderabbitai Bot commented Jul 20, 2026

Copy link
Copy Markdown

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: da1d0521-ff65-49a5-8eb1-7badd3311b80

📥 Commits

Reviewing files that changed from the base of the PR and between bb3d108 and 156aa2d.

📒 Files selected for processing (3)
  • src/daemon.ts
  • src/expose-preview-cache.test.ts
  • src/expose-preview-cache.ts
🚧 Files skipped from review as they are similar to previous changes (2)
  • src/daemon.ts
  • src/expose-preview-cache.ts

📝 Walkthrough

Walkthrough

Changes

Adds an in-memory tmux preview cache with lifecycle management, periodic refresh, failure resilience, and project-root normalization. Metadata and daemon expose responses include available per-window preview snapshots when requested.

Expose preview snapshots

Layer / File(s) Summary
Preview cache lifecycle and capture
src/expose-preview-cache.ts, src/expose-preview-cache.test.ts, src/tmux/runtime-manager.ts
Adds project-scoped caching, asynchronous tmux capture, refresh scheduling, target tracking, lifecycle handling, and coverage for snapshots, pruning, scheduling, and capture failures.
Metadata server integration
src/metadata-server.ts, src/metadata-server.test.ts
Configures and manages the cache, tracks switchable-agent items, and attaches cached snapshots to serialized responses.
Daemon expose response integration
src/daemon.ts
Reads includePreview=1, looks up snapshots by project root and window ID, and passes them into expose-item serialization.
Preview request contract and TUI wiring
src/project-api-contract.ts, src/tmux/expose-model.ts, src/tmux/expose-model.test.ts
Adds the typed preview flag to expose-item requests for worktree, project, and global scopes, with URL assertions.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant MetadataServer
  participant ExposePreviewCache
  participant TmuxRuntimeManager
  Client->>MetadataServer: request switchable agents with includePreview=1
  MetadataServer->>ExposePreviewCache: track items and read snapshots
  ExposePreviewCache->>TmuxRuntimeManager: capture target output asynchronously
  TmuxRuntimeManager-->>ExposePreviewCache: return captured output
  ExposePreviewCache-->>MetadataServer: return preview snapshot
  MetadataServer-->>Client: serialized item with preview snapshot
Loading

Possibly related PRs

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title is concise and matches the main change: adding project-cache-backed Exposé preview warming.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/expose-snapshot-cache

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/expose-preview-cache.ts`:
- Around line 79-83: Prevent trackedTargets from retaining dead windows
indefinitely by adding failure-based eviction to the refresh/capture flow around
trackItems and refresh. Track consecutive capture failures per target, remove a
target after repeated failures, and ensure successful captures reset its failure
state; add a test verifying a repeatedly failing target is eventually dropped.
- Around line 93-100: Remove the synchronous tmux capture from
ExposePreviewCache.refresh by making the refresh/capture flow asynchronous and
updating TmuxRuntimeManager.captureTarget to use a non-blocking execution
mechanism. Ensure schedule handles the asynchronous refresh completion and
errors without blocking the event loop, while preserving timer cleanup and
refresh behavior.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 29afdfdc-0de5-466d-9cb3-91a84c137fae

📥 Commits

Reviewing files that changed from the base of the PR and between 9b2ccfd and 266d2ee.

📒 Files selected for processing (5)
  • src/daemon.ts
  • src/expose-preview-cache.test.ts
  • src/expose-preview-cache.ts
  • src/metadata-server.test.ts
  • src/metadata-server.ts

Comment thread src/expose-preview-cache.ts
Comment thread src/expose-preview-cache.ts
@TraderSamwise

Copy link
Copy Markdown
Owner Author

Sub-agent review finding fixed in 7a40995: preview snapshots are now gated behind includePreview=1, and the TUI Exposé loader is the caller that opts into preview payloads. Plain /control/switchable-agents responses no longer include raw terminal preview output.

@TraderSamwise

Copy link
Copy Markdown
Owner Author

Sub-agent review finding fixed in c4dacb0: preview warming now captures only the current trackItems() demand set, so a worktree-scoped Exposé request no longer fans out into project-wide tmux captures.

@TraderSamwise

Copy link
Copy Markdown
Owner Author

Sub-agent review finding fixed in c4dacb0: the preview cache no longer prunes scoped route items against a context-free scope=all list, so teammate-scoped demand can be captured instead of being dropped before refresh.

@TraderSamwise

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 20, 2026

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/expose-preview-cache.ts`:
- Around line 86-92: Update the pruning logic in the target-tracking flow to
delete each removed window’s entry from snapshots alongside trackedTargets and
failureCounts. In the capture completion and rejection handlers, verify that the
current tracked target for the window is the same target object that initiated
the capture before mutating snapshots or failure state, preventing stale
in-flight results from repopulating cache state. Add a regression test covering
a demand swap while capture is in flight.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8be63af5-eb3b-47fc-9c39-8dfa0940d8e0

📥 Commits

Reviewing files that changed from the base of the PR and between 7a40995 and c4dacb0.

📒 Files selected for processing (3)
  • src/expose-preview-cache.test.ts
  • src/expose-preview-cache.ts
  • src/metadata-server.ts
💤 Files with no reviewable changes (1)
  • src/metadata-server.ts

Comment thread src/expose-preview-cache.ts Outdated
@TraderSamwise

Copy link
Copy Markdown
Owner Author

Sub-agent review findings fixed in 156aa2d: preview demand is now unioned per active window with expiry instead of replacing the whole cache on every request, and refresh batches abort/reschedule when demand generation changes.

@TraderSamwise

Copy link
Copy Markdown
Owner Author

Sub-agent review finding fixed in 156aa2d: in-flight preview captures now use stable window-id plus demand generation checks, so identical re-demand is accepted while expired/recreated demand rejects stale output.

@TraderSamwise

Copy link
Copy Markdown
Owner Author

Sub-agent review findings fixed in 156aa2d: global includePreview=1 now marks grouped project demand through the preview-cache registry before reading snapshots.

@TraderSamwise
TraderSamwise merged commit f866aad into master Jul 20, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant