Build web API parity foundation

[TraderSamwise]

Summary

• add an app-side project API route coverage guard against the shared metadata-server contract
• add typed app wrappers for project management, diagnostics, interaction, statusline, and cleanup routes
• centralize project-update refresh routing for API-backed app views, desktop-state cache, and notification feed

Verification

• cd app && yarn test
• cd app && yarn typecheck
• yarn typecheck
• push hook: yarn typecheck && yarn lint && yarn test (153 files, 1929 tests)

Summary by CodeRabbit

• New Features
  • Expanded project controls with health/diagnostics views, agent management actions, interaction handling, status refresh, and cleanup tools.
  • Improved project update handling so the right parts of the app refresh more reliably when project data changes.
• Bug Fixes
  • Tightened route-coverage tracking to keep app routes aligned with the project API and highlight planned gaps more clearly.
• Tests
  • Added coverage for new API wrappers, refresh mapping, and route parity checks.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
app	Ready	Preview, Comment	Jun 26, 2026 2:04am

[TraderSamwise]

@coderabbitai review

[coderabbitai]

✅ 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]

Warning

Review limit reached

@TraderSamwise, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 54 minutes and 6 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e8815b9a-73cf-4923-a703-e1f96c68b2c1

📥 Commits

Reviewing files that changed from the base of the PR and between de95ecf and 3a3ca6d.

📒 Files selected for processing (3)

• app/stores/projectViews.test.ts
• app/stores/projectViews.ts
• src/project-api-contract.ts

📝 Walkthrough

Walkthrough

This PR extends the project API contract and client wrappers with health, diagnostics, agent, interaction, graveyard, and status endpoints. It also adds route-coverage parity checks and changes project-update refresh routing to use a registry-driven view mapping.

Changes

Project API surface and refresh routing

Layer / File(s)	Summary
Contract types src/project-api-contract.ts	Adds health/diagnostics responses, agent and interaction request/response types, and graveyard cleanup contracts.
Route coverage map app/lib/project-api-route-coverage.ts, app/lib/project-api-route-coverage.test.ts	Adds the route coverage union/map and tests that compare covered routes and planned routes with PROJECT_API_ROUTES.
API wrappers app/lib/api.ts, app/lib/api.test.ts	Adds project API wrappers for health, diagnostics, agents, interactions, graveyard cleanup, statusline refresh, and operation-failure clearing, with relay-proxy coverage tests for the wrapper set.
Refresh routing app/stores/projectViews.ts, app/stores/projectViews.test.ts, app/app/(main)/_layout.tsx	Replaces the service-view touch check with registry-driven predicates for project API views, desktop-state polling, and notification feed, and routes projectUpdate events through them.

Sequence Diagram(s)

sequenceDiagram
  participant MainLayout
  participant projectUpdateTouchesProjectApiView
  participant projectUpdateTouchesDesktopState
  participant projectUpdateTouchesNotificationFeed

  MainLayout->>projectUpdateTouchesProjectApiView: event.views
  MainLayout->>projectUpdateTouchesDesktopState: event.views
  MainLayout->>projectUpdateTouchesNotificationFeed: event.views
  alt project API view touched
    MainLayout->>MainLayout: kick projectApiViewRefreshNonceAtom
  end
  alt desktop-state touched
    MainLayout->>MainLayout: refresh desktop-state polling
  end
  alt notification-feed touched
    MainLayout->>MainLayout: refresh durable notification feed
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• TraderSamwise/aimux#184: Shares the app/lib/api.ts client-wrapper layer and expands contract-backed route access.
• TraderSamwise/aimux#245: Touches the projectUpdate refresh routing in app/app/(main)/_layout.tsx and related notification-feed refresh behavior.

Poem

I hopped through routes with twitchy nose,
And counted every API pose.
New agents, views, and refresh chimes,
All tucked in neat, determined rhymes.
🐰 Crunch, crunch—my carrot cheers the code.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the PR’s main goal: establishing web API parity foundations for app-side project features.
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 unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/web-api-parity-foundation

---

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