Skip to content

Centralize TUI API adapter usage - #230

Merged
TraderSamwise merged 5 commits into
masterfrom
chore/next-20260623-tui-connection-adapter-5
Jun 23, 2026
Merged

Centralize TUI API adapter usage#230
TraderSamwise merged 5 commits into
masterfrom
chore/next-20260623-tui-connection-adapter-5

Conversation

@TraderSamwise

@TraderSamwise TraderSamwise commented Jun 23, 2026

Copy link
Copy Markdown
Owner

Summary

  • add a dashboard API client adapter for resource refreshes, model refreshes, and mutations
  • route TUI Project/Library/Topology refreshes, dashboard model refreshes, and dashboard mutations through the shared TUI API runtime
  • keep raw project-service HTTP calls at the transport/binding boundary only

Verification

  • yarn typecheck
  • yarn lint
  • yarn vitest run
  • yarn build
  • pre-push hook: yarn typecheck && yarn lint && yarn test

Summary by CodeRabbit

Release Notes

  • Refactor

    • Standardized dashboard state refreshes and mutations through a new lifecycle-aware API client, replacing prior service-based calls across dashboard, sessions, notifications, topology, worktrees, and library flows.
    • Improved “force refresh” and lifecycle-current gating behavior for settlement and repair scenarios.
  • Bug Fixes

    • Ensured refresh outcomes are handled consistently when the dashboard data is unavailable or refresh fails.
  • Tests

    • Added a dedicated test suite for the dashboard API client (including lifecycle/race/error cases).
    • Updated existing navigation and refresh tests to match the new refresh behavior.

@vercel

vercel Bot commented Jun 23, 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 Jun 23, 2026 5:39am

@TraderSamwise

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jun 23, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a447f9a1-14b4-4832-88c8-b6b33eb07469

📥 Commits

Reviewing files that changed from the base of the PR and between ac0141a and 57a1202.

📒 Files selected for processing (3)
  • src/multiplexer/dashboard-control.test.ts
  • src/multiplexer/dashboard-control.ts
  • src/multiplexer/tui-api-runtime.test.ts
🚧 Files skipped from review as they are similar to previous changes (1)
  • src/multiplexer/dashboard-control.ts

📝 Walkthrough

Walkthrough

Introduces src/multiplexer/dashboard-api-client.ts as a new lifecycle-aware wrapper module exporting refreshDashboardApiResource, refreshDashboardModelThroughApi, mutateDashboardApi, and two lifecycle-guard helpers. All existing direct calls to host.postToProjectService and host.refreshDashboardModelFromService across the multiplexer are replaced with these centralized helpers. The TUI API runtime mutate transport is updated to forward request options to the underlying postToProjectService call. Tests are added for the new module and updated across affected files.

Changes

Dashboard API Client Abstraction and Migration

Layer / File(s) Summary
New dashboard-api-client module and tests
src/multiplexer/dashboard-api-client.ts, src/multiplexer/dashboard-api-client.test.ts
Adds lifecycle-guard helpers (isDashboardApiLifecycleCurrent, isDashboardApiRenderLifecycleCurrent), refreshDashboardApiResource (lifecycle-gated GET with apply/ensure callbacks), refreshDashboardModelThroughApi (model refresh with error detection), and mutateDashboardApi (POST wrapper that throws on failure). Tests cover the happy path, pre-call staleness, mid-flight staleness race condition, refresh failure, and mutation transport routing.
TUI API runtime opts forwarding
src/multiplexer/tui-api-runtime.ts, src/multiplexer/tui-api-runtime.test.ts
Wires opts passthrough in the mutate transport inside getOrCreateTuiApiRuntime so timeout/request options reach host.postToProjectService. Test updated to expect the runtime mutateJson call to succeed and to verify host.postToProjectService receives the forwarded path and body.
Resource-refresh delegation: library, topology, project
src/multiplexer/library.ts, src/multiplexer/library.test.ts, src/multiplexer/topology.ts, src/multiplexer/topology.test.ts, src/multiplexer/project.ts, src/multiplexer/project.test.ts
Refactors refreshLibrary, refreshTopology, and refreshProjectObservability to delegate entirely to refreshDashboardApiResource with validate/apply/ensure callbacks, removing inline getOrCreateTuiApiRuntime().refreshJson calls, isDashboardLifecycleCurrent checks, and local try/catch blocks. Navigation-guard tests are updated to assert the service is never called after the user navigates away.
Model refresh migration to refreshDashboardModelThroughApi
src/multiplexer/dashboard-ops.ts, src/multiplexer/worktrees.ts, src/multiplexer/dashboard-view-methods.ts, src/multiplexer/index.ts, src/multiplexer/runtime-state.ts, src/multiplexer/runtime-state.test.ts, src/multiplexer/project-event-stream.ts, src/multiplexer/session-launch.ts, src/multiplexer/session-launch.test.ts, src/multiplexer/dashboard-control.ts, src/multiplexer/dashboard-control.test.ts, src/multiplexer/archives.ts, src/multiplexer/dashboard-interaction.ts, src/multiplexer/dashboard-interaction.test.ts
Migrates all host.refreshDashboardModelFromService call sites to refreshDashboardModelThroughApi. Consolidates refresh helpers in dashboard-ops (refreshDashboardModelAfterAuthoritativeMutation, new refreshDashboardModelAfterMutationError, refreshDashboardModelForSettlement). Updates worktree settlement loops, settleDashboardCreatePending, dashboardPendingActions, background lifecycle refresh, event-stream view refresh, session startup/repair, and runtime-guard auto-repair. Tests updated for the new (true, undefined) call signature. Adds new test for background refresh race condition when dashboard input epoch changes mid-flight.
Mutation call site migration to mutateDashboardApi
src/multiplexer/coordination.ts, src/multiplexer/dashboard-control.ts, src/multiplexer/dashboard-interaction.ts, src/multiplexer/dashboard-ops.ts, src/multiplexer/notifications.ts, src/multiplexer/subscreens.ts, src/multiplexer/session-runtime-core.ts
Replaces host.postToProjectService with mutateDashboardApi at all mutation call sites: coordination notification clear/read/mark-seen, statusline refresh, notification target open, worktree-failure dismiss, review request, orchestration actions, session/service spawn/fork/stop/resume/create/remove/migrate, notification mark-read, coordination subscreen mutations, and session label rename.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

  • TraderSamwise/aimux#158: Introduced the project screen and refreshProjectObservability, which this PR refactors to use refreshDashboardApiResource for unified refresh/validate/apply/ensure control flow.
  • TraderSamwise/aimux#178: Modified notification mutation paths in coordination.ts; this PR switches those same read/clear/mark-seen requests to the unified mutateDashboardApi wrapper.
  • TraderSamwise/aimux#221: Modified dashboard-control.ts's runtime-guard repair "succeed" flow to re-probe guard state; this PR simplifies the same refresh verification by delegating to refreshDashboardModelThroughApi.

Poem

🐇 A rabbit once hopped through the code, so tangled,
With postToProjectService calls all mangled.
Now mutateDashboardApi leads the way,
And lifecycle guards keep stale calls at bay.
The dashboard refreshes, clean and bright—
One tidy module, everything right! 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 2.27% 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 'Centralize TUI API adapter usage' accurately describes the main architectural change: introducing a unified dashboard API client to route TUI interactions through a shared adapter rather than direct calls.
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.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ 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 chore/next-20260623-tui-connection-adapter-5

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: 1

🧹 Nitpick comments (1)
src/multiplexer/tui-api-runtime.test.ts (1)

228-234: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add an assertion for the opts !== undefined mutate branch.

This test currently validates only the no-opts path, but the runtime change introduced a separate branch when opts are provided.

Suggested test update
   await expect(runtime.mutateJson("/agents/stop", { sessionId: "b" }, (value) => value)).resolves.toMatchObject({
     ok: true,
     value: { ok: true, body: { sessionId: "b" } },
   });
+  const opts = { timeoutMs: 10_000 };
+  await expect(
+    runtime.mutateJson("/agents/stop", { sessionId: "c" }, (value) => value, opts),
+  ).resolves.toMatchObject({
+    ok: true,
+    value: { ok: true, body: { sessionId: "c" } },
+  });

   expect(mutate).toHaveBeenCalledTimes(1);
   expect(host.postToProjectService).toHaveBeenCalledWith("/agents/stop", { sessionId: "b" });
+  expect(host.postToProjectService).toHaveBeenCalledWith("/agents/stop", { sessionId: "c" }, opts);
🤖 Prompt for 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.

In `@src/multiplexer/tui-api-runtime.test.ts` around lines 228 - 234, The test for
runtime.mutateJson currently validates the response and service call but does
not verify that the opts callback function is actually invoked when opts are
provided. Add an assertion to verify that the opts callback function (the third
parameter passed to mutateJson) was called with the correct value, ensuring the
opts !== undefined branch in the runtime implementation is properly tested and
exercised.
🤖 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/multiplexer/dashboard-control.ts`:
- Line 317: The condition at line 317 in the refreshDashboardModelThroughApi
call currently treats all false returns as repair failures, but the function
also returns false when the host is no longer in dashboard mode due to user
navigation, which is not an actual repair failure. Modify the logic to
distinguish between actual API failures and stale lifecycle state changes,
ensuring that repair is only marked as failed when there is a genuine API error
(not when the host has exited dashboard mode). This may require checking the
return value more carefully or adding additional state information to understand
whether the false return indicates a real failure versus a benign state change.

---

Nitpick comments:
In `@src/multiplexer/tui-api-runtime.test.ts`:
- Around line 228-234: The test for runtime.mutateJson currently validates the
response and service call but does not verify that the opts callback function is
actually invoked when opts are provided. Add an assertion to verify that the
opts callback function (the third parameter passed to mutateJson) was called
with the correct value, ensuring the opts !== undefined branch in the runtime
implementation is properly tested and exercised.
🪄 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: aa9209bb-8e78-415f-b03e-c8214ff2b958

📥 Commits

Reviewing files that changed from the base of the PR and between 9cb2be0 and cc52a46.

📒 Files selected for processing (27)
  • src/multiplexer/archives.ts
  • src/multiplexer/coordination.ts
  • src/multiplexer/dashboard-api-client.test.ts
  • src/multiplexer/dashboard-api-client.ts
  • src/multiplexer/dashboard-control.test.ts
  • src/multiplexer/dashboard-control.ts
  • src/multiplexer/dashboard-interaction.test.ts
  • src/multiplexer/dashboard-interaction.ts
  • src/multiplexer/dashboard-ops.ts
  • src/multiplexer/dashboard-view-methods.ts
  • src/multiplexer/index.ts
  • src/multiplexer/library.test.ts
  • src/multiplexer/library.ts
  • src/multiplexer/notifications.ts
  • src/multiplexer/project-event-stream.ts
  • src/multiplexer/project.test.ts
  • src/multiplexer/project.ts
  • src/multiplexer/runtime-state.ts
  • src/multiplexer/session-launch.test.ts
  • src/multiplexer/session-launch.ts
  • src/multiplexer/session-runtime-core.ts
  • src/multiplexer/subscreens.ts
  • src/multiplexer/topology.test.ts
  • src/multiplexer/topology.ts
  • src/multiplexer/tui-api-runtime.test.ts
  • src/multiplexer/tui-api-runtime.ts
  • src/multiplexer/worktrees.ts

Comment thread src/multiplexer/dashboard-control.ts Outdated
@TraderSamwise
TraderSamwise merged commit 17e718e into master Jun 23, 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