Feat/webui nextjs framework

[weekbin]

Change

Why

packages/webui shipped a frontend that was no longer served and ran its HTTP server from source.
Both were dead ends, and both had been worked around instead of fixed.

The server could not be shipped as source. Running it from source means the published archive
has to resolve its imports at runtime, and it cannot: every @mavis/* package is private: true
with no build output (its exports point at ./dist/*.js, which only the esbuild plugin rewrites
at build time). So "declare the dependency and import it" does not work in any published form. And a
bare specifier that reached the server without being listed in cliExternalModules produced a
runtime that failed on first import — which is how hono went missing from the archive.

The frontend was unreachable code. public/app/**, public/styles/** and public/index.html
were not what the served frontend rendered; the served frontend is a Next.js static export. They
stayed alive only because static.js kept a public/ fallback for them.

Several other mechanisms had the same shape — a workaround that outlived the limitation it was
written for, with a comment still asserting the limitation:

• the ACP wrapper hard-refused six methods before the call left the process;
• session/cancel was refused and sent as a request, so the graceful cancel path never ran and
  every stop SIGKILLed the whole engine;
• the model catalogue was scraped out of mcode's build output;
• the permission mode was local-only.

The through-line is that the webui was guessing at, or routing around, an engine it can simply ask.
This PR removes the guessing.

What

The server is one bundle, and the artifact is gated — build(webui): bundle the server and gate the artifact. scripts/build.mjs bundles server/bootstrap.js into dist/webui/server.js, sharing
the workspace-source plugin with the CLI build. scripts/check-webui-bundle.mjs is a new
verification gate so the bundle's bare specifiers, cliExternalModules and the release manifest
cannot drift apart again. The entry stays server.js at the webui root, because packages/tui's
launcher resolves exactly that path.

The frontend is the Next.js desktop stack (feat(webui): rebuild the frontend on the Next.js desktop stack), and the legacy tree plus the static.js fallback that kept it alive are gone
(refactor(webui): serve one static root and delete the unreachable legacy UI), so the server
serves a single static root.

The API moved onto Hono (refactor(webui): move the API onto Hono). OWNED_ROUTES in
server/app.js is the migration ledger, asserted by test/server/app-hono.test.js. router.js
keeps static/HTML handling, the two SSE channels (the buffered response capture cannot model a
streaming write), and /api/health + /api/settings — retained deliberately so the
origin/CORS/rate-limit gate tests exercise the legacy path and get a 200 instead of the 404 path;
the Hono app owns both endpoints for real consumers.

The server libraries are split by responsibility (refactor(webui): split the server libraries by responsibility): the four-layer better-sqlite3 resolution chain, the session-delete SQL, the
streaming chat-line writer and the context percentage each became their own module, and layout.js
is the one place the bundle resolves the webui root from the entry path.

The test tree is organised by subject (test(webui): reorganise the test tree by subject):
checks/ folds into test/, and files are named for the module or route under test
(test/lib/<module>.check.mjs, test/routes/<route>.check.mjs) instead of a shared prefix that only
recorded where a file came from.

Documentation and comments describe the current implementation (docs(webui): align the documentation and comments with the implementation, docs(webui): correct the comments and notes the ACP change falsified). Module inventories named deleted files, API.md documented fallbacks the
router does not implement, CAPABILITIES.md pointed at deleted frontend symbols, and comments
narrated how a file had evolved instead of stating what a reader cannot recover from the code. Each
claim is restated against the code. Comments now keep the external contracts — paths, environment
variables, protocol methods, ordering/idempotency invariants — and drop the rest. The 41 translation
keys no component reads are removed from both dictionaries (a key is only reachable through t(),
and MessageKey is derived from the English dictionary, so nothing flags an unused one).

The behaviour changes this PR also carries

The commits above are organised by the files they touch, so the behavioural fixes sit inside them
rather than in commits of their own. Listed here so they are not missed in review.

The ACP wrapper now reaches what the engine implements (in refactor(webui): split the server libraries + refactor(webui): move the API onto Hono). Six methods were refused before the call
left the process. Five have engine handlers, and the two with real callers also sent the wrong wire
fields:

method	engine expects	we sent
session/set_mode	modeId, validated against the session's availableModes	mode
session/set_config_option	configId	key

session/activate was refused with a comment claiming it is not a public JSON-RPC method;
extensions.ts registers it. session/fork and session/resume have no route at all, so the entry
only misreported the engine. session/delete is the one method the engine registers but never
implements, and nothing called it either — deletes go through SQL on the local_runtime_* tables.
With the refusal set gone, the refusal branch in callRpc had no reachable caller and was removed;
MCODE_ACP_CAPABILITIES now reports what the wrapper can actually reach.

Cancel goes through the engine instead of SIGKILLing it (same two commits). The engine registers
session/cancel with app.onNotification and aborts the active prompt's AbortController. The
wrapper both refused it and sent it as a request, which has no handler — so the graceful path never
executed and /api/stop always fell through to child.kill(), taking every other session in that
process down with it. It is now sent as a notification; SIGKILL is kept only for an unreachable
client and for a child that outlives the grace window.

The model catalogue and the permission mode come from the engine (in the same two commits, plus
feat(webui): rebuild the frontend on the Next.js desktop stack for the frontend re-fetch). The
catalogue was scraped from mcode's dist/cli.js and its chunks/*.js, and /api/models reported
source: "mcode-cli-bundle". The engine already publishes it as a model config option (values from
runtime.listModels) and returns it from session/new and session/load, so the route reads that
instead. /api/permissions now calls set_config_option{configId:'permissionMode'} rather than
writing local state and answering mcodeSynced: false. The config_option_update handler expected
{key, value}, while the engine sends the whole configOptions array — so it never matched and
cs.permissions could not follow a change made by another client; it now replaces the array and
re-derives the label.

Session rename is carried onto the current stack (in the frontend, Hono and server-library
commits). The rename work landed on main against the legacy frontend this branch deletes, so it is
re-implemented on the current one: the Hono route and its ledger entry, the inline rename affordance
(Enter/blur commits, Escape discards; editing swaps the row's element because a <button> may not
contain an <input>), and a titleCustom overlay in buildTree. The overlay is not cosmetic — the
sidebar reads titles from mcode's runtime db, where a user title does not exist, so without it a
rename would never reach the UI. The rename handler also drops the tree cache, or the old title
survives for its TTL.

Also merged from main during the rebase onto 0.5.2: the session-rename CRUD route, the workspace
gate on POST /api/sessions, draft↔mcode binding at session/new, and three SSE/ACP memory fixes.

Second round: the reviewer's findings, engine-sourced quota, and the defects behind the reports

The plan quota no longer comes from a key the web server stored. The usage popover read its
5-hour and weekly figures by calling MiniMax's quota endpoint with a Subscription Key the operator
pasted into the web settings — a plaintext secret in settings.json, kept in order to repeat a call
the engine already makes. It now maps the mcode/account/status ACP projection
(server/lib/usage.js), and handleUsage no longer answers {ok:true} before the figures arrive —
the popover reads the response body, so a successful fetch still rendered "unavailable". What left
with the key: the quotaEnabled / tokenPlanApiKey settings, MCODE_WEBUI_TOKEN_PLAN_KEY and its
_FILE variant, and the snapshot fields that published them. buildPersistBody() is an explicit
whitelist, so the first start after this rewrites settings.json without the retired fields rather
than leaving a credential on disk for a feature that no longer reads it. Two smaller fixes rode along:
the old parser zeroed the session* counters on every /api/usage call (they belong to the chat
flow), and the weekly reset time is recorded for the forecast instead of a hardcoded null.

The usage popover had never shown anything at all. Live verification found getQuota() calling
GET /api/usage, which no route registers — the call 404'd, so the popover rendered its failure line
whatever the engine reported. Both /api/usage and /api/usage-trigger are POST because the route
fetches from the engine and appends to the forecast history. It also drew a single row labelled
"Quota" from the 5-hour pair while weeklyRemaining / weeklyResetAt went unused, so the weekly
window was fetched and discarded; there is one row per window now, with the percentage labelled
"Used" because a bare "7%" beside "Quota" read as 7% left rather than 7% consumed.

Reviewer findings (@modacker):

• ownsRequest built a second Hono app per request just to decide dispatch;
  createHonoListener() returns { app, listener } and the bootstrap threads one app through both.
• POST /api/protocol/cancel answered an undeliverable notification with fallback: "hard_kill"
  while nothing on that path kills anything; the payload now names POST /api/stop, which carries the
  cascade.
• routes/chat.js dropped a dynamic import of a module already in the cache.
• The 32 hardcoded local_runtime_* tables in mcode-session-delete.js are left as they are — the
  reviewer marked that non-blocking and the fix belongs on the engine side (see Known gaps).

Transcript rendered raw protocol text. A tool_call_update whose tool_call never arrived
appended [status] / @ path lines with no → name header above them, and decodeTranscript
cannot attribute an indented line to a tool without one — so a run of them became a block labelled
系统. The update writes its own header now, and the decoder refuses to fabricate a system row from a
line opening with a protocol glyph. config_option_update also propagates a model change, which its
own comment had always claimed it did.

Sidebar and layout. The Local/Cloud segmented control could only ever be half real (mcode exposes
no cloud sessions), and above it sat a folder glyph whose only effect was to open the workspace panel
the toolbar already opens — setWorkspace has no caller at all, so it never switched anything. Both
are gone. The drawer no longer opens on 工作区 by itself. The AI-content disclaimer moved into the
conversation column, because as a sibling of the drawer row its text-center centred it across the
drawer too. The account menu's submenus are usable for the first time: the panel is a sibling of its
trigger, so the trigger's mouseleave closed it the instant the pointer set off toward the panel, and
right-[calc(100%-8px)] resolved to a position 8px from the trigger's left edge, laying the panel
out past the left edge of the window. Their rows also pointed at example.com and
support@example.com — links that look live and go nowhere — and are disabled rows now.

Three display corrections, measured against the engine's own database. sessionCount counted
roots + children, and every child is a session_kind='task' sub-agent: the CTAS project's pill read
371 for 175 conversations. mcodeVersion in /api/health and /api/settings was a pinned "0.1.2"
— both read the engine's agentInfo now (0.5.2 here). And the composer's model chip printed the
engine's encoded value while the dropdown a few pixels away printed the display name, so one model
had two names.

Third round: quota polling, and a model name that was never the engine's

The usage popover is polled now. It fetched only when hovered, so the figure
was as old as the last visit and the refresh button was the only way to get a
current one. startQuotaPolling (in the app store) reads it on load and every
two minutes while the page is open, and a hidden tab catches up on
visibilitychange.

Polling is a read, not a measurement. Every POST /api/usage used to append a
sample to the forecast history; one sample every two minutes would grow that file
without bound for a forecast that only reads within the weekly window. record
now decides (lib/usage.js, defaulting to true so a caller that says nothing is
unchanged), the poll sends record: false, and only the refresh button asks for
a sample.

That button could not have worked. The usage popover is portalled to
document.body, and the account menu's outside-click guard knew only about the
contact/learn-more submenu. A mousedown on the button therefore closed the menu
and unmounted the button before the click dispatched, so its onClick never ran.
The guard covers both flyouts now — the same class of bug as the submenu hover
fixed in the second round.

The composer named a model the engine had not named. GET /api/models
answers with the engine's model config option, whose value is the engine's
encoding — m:<provider>:<model>:v:<variant>. With no session there is no option,
and the route fell back to webui's own DEFAULT_MODEL, minimax_api/MiniMax-M3:
a different encoding and a different fact, rendered as the active model while
the session was running
m:custom_provider%3Aopencode-go:deepseek-v4.1-flash:v:thinking. It also wrote
that value into cs.model.name, which is what a later prompt would carry. The
route answers null now, writes nothing back, and the composer shows its neutral
label until a catalogue arrives.

A model switch does not add a session. Reported as "switching the model adds
sessions to the sidebar"; measured against a live engine (load a session, change
its model through session/set_config_option, revert) the session row count is
unchanged and no row is added — the runtime selects the model in place. Recorded
here so the next report can start from that.

Validation

Run on this PR's head, rebased onto main at 85f74a6 (0.5.2). pnpm verify — the same gates as CI,
in order — exits 0: all 16 gates pass.

check	result
pnpm build	pass — "Built MiniMax Code 0.5.2 from 6253 source files"
pnpm typecheck / pnpm webui:typecheck	pass
pnpm test:webui	1273 tests, 1271 pass, 2 skipped, 0 fail, 0 cancelled
pnpm test:webapp	183/183 pass
pnpm check:source	pass — 4541 reviewed source paths
pnpm check:tsconfig	pass — 126 package exports
pnpm check:standalone	pass
pnpm check:webui-bundle	pass — dist/webui/server.js, 434537 B, 56.6× source
pnpm test:release-tools	52 tests, 51 pass, 1 skipped
pnpm test:capabilities / test:status-contract / test:smoke / test:byok / test:artifact / test:policy	pass

Live acceptance, this round. Earlier rounds were offline only; these changes were driven against a
running engine on this host (pnpm mcode-web, dist/ built from this head) and a real browser:

hop	observed
engine → GET /api/account	tokenPlanQuotaState: available, fiveHour.remainingPercent 93, weekly.remainingPercent 85, both reset instants, identity.name MiniMax802592, tokenPlan.tier Ultra Plan — and no credential value anywhere in the payload
webui → POST /api/usage	{ok: true, source: "acp", remaining: 93, weeklyRemaining: 85, resetAt, weeklyResetAt}
browser → usage popover	two rows: "5-hour limit — Used 7% — Resets 9/23/2026 8:00 PM" and "Weekly limit — Used 15% — Resets 9/28/2026 12:00 AM", each with its own gauge; popover inside the viewport; 0 console errors
browser → sidebar	no role="tablist" and no workspace chip; no drawer auto-opened on the home screen; the disclaimer's box ends at the drawer's left edge (240→1112 of a 1400px window) and centres at 676, i.e. in the conversation column
browser → account menu	Contact us submenu opens, stays open when the pointer moves onto the panel, lays out to the right inside the viewport, both rows disabled (aria-disabled)
browser → quota polling	POST /api/usage {"record":false} fired on load with no interaction; the forecast history file stayed absent through repeated polls; clicking refresh sent {"record":true} and appended exactly one sample
GET /api/models, no session	{models: [], current: null, reason: "no_session_config"}; the composer chip renders its neutral Model label, where it previously claimed MiniMax-M3
engine, model switch	loaded a dormant session, changed model via session/set_config_option, reverted: total session rows 585 → 585, 0 added
sessionCount	CTAS pill reads 175 against the engine's database: 175 conversations, 196 sub-agent rows no longer added — the pre-fix value was 371

NOT RUN / not covered:

• Windows profile not run — this host is Linux. The bundle gate is intentionally not marked
  windows: true, since it validates an artifact only the profile that runs build produces.
• session/cancel was not exercised against a live prompt. The route now sends the engine's
  session/cancel notification rather than rejecting it, and the offline tests cover the wire shape;
  an interrupted live turn was not run.
• GET /api/usage is still unregistered. The client now uses POST; a GET returns 404 by design.
• test:capabilities failed on the last run of this host (2 of 4484), on tests this change cannot
  reach. They are packages/tui/test/unit/tui/theme/runtime.test.ts's two custom-theme reload cases,
  which wait for an fs.watch callback; both fail in isolation, on a tree where git diff e3f903b..HEAD -- packages/tui is empty, and the file imports nothing but
  packages/tui/src/tui/theme/*. The host has 294 open inotify instances against a per-user limit of
  128 with several browsers and editors running, which is why the watcher never fires. The same suite
  passed earlier in this session on this head's ancestry.

Performance: NOT RUN. perf:full is not applicable to this change.

Publication and contribution checks

• I have permission to contribute these changes under the existing licenses applicable to the changed files/packages; imported material and its provenance are identified and existing notices are preserved.
• No credentials, account data, real user content, internal source history or private review material is included.
• Added/removed source files were reviewed before regenerating release/public-source.json; new tests are declared in test/vitest-suites.json where applicable.
• Shared English/Chinese documentation and capability/verification records are updated where applicable. Mock/offline results are not described as live-service acceptance.

Notes:

• release/public-source.json was regenerated with node scripts/source-inventory.mjs --write
  (4541 paths). The three new scripts/ files and the added frontend files were reviewed first,
  since recording a file is not the same as deciding it may be published.
• New webui tests are declared in the webui package's own test script, not in
  test/vitest-suites.json — that file lists the repository-level Vitest gates, which this change
  does not add to.
• The zh-CN documents were updated alongside their English counterparts throughout.
• release/public-source.json gained exactly one path this round,
  packages/webui/server/routes/account.js — a route file added when the account card started
  reading the engine, and missed from the inventory at that time. Reviewed, then recorded; the
  file holds no credential handling.

Maintainer handoff

Publication scope or license changes: none. No dependency was removed. @mavis/shared became a
declared dependency of packages/webui (it was already imported, just undeclared).

Shared-source port: the changes are confined to packages/webui/**, docs/webui*.md and three
first-party scripts/ files. No third_party/ vendored source is touched and no upstream commit was
cherry-picked.

Reviewer follow-up

@modacker's review is answered in the commits above: the per-request Hono rebuild, the cancel payload
that promised a kill it never performed, and the dynamic import of a loaded module are all fixed, each
with a test that fails before the change. The 32 hand-written local_runtime_* tables are acknowledged
below as a known gap and left alone, as the review suggested.

Known gaps, deliberately not fixed here

• session/delete still goes through SQL. The engine registers the method in its protocol layer
  but implements no handler, so deletes write ~32 local_runtime_* tables by hand
  (server/lib/mcode-session-delete.js; sqlite-resolver.js records the probe that established
  this). Those tables are schema knowledge the webui does not own and cannot keep correct. The engine
  already has the real delete path
  (local-runtime-v2/.../sessions/lifecycle/deletion-service.ts) and already exposes extension
  methods of that shape (mcode/session/queue/delete), so the fix belongs on the engine side as an
  mcode/session/delete; the webui can then drop the SQL. Not done here because it needs a change in
  a package this distribution vendors from upstream.
• Session history is still read from the runtime db in two of three places. The engine replays a
  session's full history as session/update notifications on session/load/session/resume, and
  the webui currently drops them (nothing subscribes during the load — acp.mjs's listener window is
  scoped to a prompt, and user_message_chunk is not in its mapping). Two readers can move onto that
  replay: the switch-path backfill and the export enrichment. The switch path cannot do so as-is,
  because it never loads the session in the engine — using the replay there means making a sidebar
  click attach the session, which is a behaviour change worth reviewing on its own. The third reader
  cannot move at all: lib/transcript-sync.js polls the db so a browser tab tracks a session being
  driven by another client, whose writes are not pushed to this connection.
• test/integration/upload-limits.test.js is flaky independent of this change. An A/B probe on
  this host — 5 runs with the change set, 5 without — put the same failure rate on both (4/5 each,
  failing on client wrote N of 8388718 or a premature EPIPE). Its assertion depends on how much
  the client can push into the kernel socket buffers before the server's 413 closes the connection,
  which is not a property of this diff. Two ad-hoc test-isolation defects found while probing are
  fixed: router-boot.test.js never redirected the usage-history path, so its "fresh server"
  assertion depended on the operator's real ~/.mcode-webui/usage-history.ndjson, and
  router-readonly.test.js wrote the operator's real settings.json and events.ndjson.
• type TranscriptLine = string is a locally invented line grammar. Replacing it with the
  engine's own session/update payloads is the same change as the replay work above, so it is left
  with it rather than designed twice.

[modacker]

Summary

This is a net-positive cleanup, not a "屎山". The Hono migration uses createResponseCapture to reuse (req, res, ctx) handlers without rewriting them, the 5-gate chain is shared between Hono and the legacy router, and the cancel-as-notification fix is correct end-to-end. Three concrete findings below are worth fixing before merge.

---

Findings (actionable)

1 · ownsRequest rebuilds the entire Hono app on every request — performance regression

packages/webui/server/bootstrap.js:101 calls ownsRequest(method, pathname) without a third argument, and app.js:154-158 falls back to createHonoApp():

export function ownsRequest(method, pathname, app = null) {
  const a = app ?? createHonoApp();   // re-registers ~47 routes per request
  ...
}

createHonoListener() (line 501-503) already built a Hono app and closed it over. A Hono-owned request therefore triggers two full Hono constructions: one for the dispatch decision, one for the actual serve. The sidebar's ?refresh=1 and per-state-push polling make this non-trivial.

Fix: hoist the app to module scope (const app = createHonoApp()) and pass it into both createHonoListener and ownsRequest. Or have createHonoListener return { app, listener }.

2 · POST /api/protocol/cancel returns fallback: "hard_kill" but never hard-kills

packages/webui/server/routes/protocol.js:130-141:

const r = await cancelSession(sessionId);
if (!r.ok) {
  return respond(res, 200, {
    ok: true,
    cancelled: false,
    warning: r.error,
    code: r.code,
    fallback: "hard_kill",   // nothing actually kills here
  });
}

Only the notification was attempted. The actual gentle-then-SIGKILL cascade with the 2s grace window lives in chat.js#handleStop at /api/stop (packages/webui/server/routes/chat.js:243-289). A client UI that calls /api/protocol/cancel for "stop" reads fallback: "hard_kill" and may stop polling while the child keeps running.

Fix: rename the field to something honest (note: "notification_failed_run_api_stop_for_kill"), or chain this endpoint into the same SIGKILL path.

3 · No integration test against a real engine for the ACP changes

The headline behaviour fixes — session/cancel as notification instead of request, set_mode/set_config_option wire-field renames (modeId/configId not mode/key), the fork/resume/activate routes — are all verified against mocks. If packages/tui/src/acp/agent.ts ever registers session/cancel as a request again, this PR's tests won't catch it.

The PR description itself flags: "No live-service acceptance. Every check above is offline. packages/webui/test/** mocks the ACP client, so the ACP changes are covered at the protocol boundary, not against a running engine."

Fix: a smoke harness spawning mcode acp --mock-stub (or whatever test stub exists) and asserting the wire shape end-to-end.

---

Known / acknowledged gap (not blocking)

4 · mcode-session-delete.js hardcodes 32 local_runtime_* tables

packages/webui/server/lib/mcode-session-delete.js:24-62. The PR description flags this explicitly as "schema knowledge the webui does not own and cannot keep correct." The fix belongs on the engine side as mcode/session/delete; out of scope here.

Two consequences worth tracking:

• When mcode adds a new local_runtime_* table, the per-table try/catch classifies it as "absent" (no PRAGMA-confirmed table_info), so new message/state types degrade silently.
• _isConfirmedUnsupportedSchema (line 102-117) fails-closed after mcode ships a keyless table, but the silent orphan window between mcode release and webui release is unavoidable.

Suggest a CI sanity test that counts local_runtime_* tables in ~/.minimax/v2/sqlite and asserts the list covers them.

---

Observations (lower-impact)

• chat.js:254 dynamic await import("../lib/mcode-rpc.js") is misleading — mcode-rpc.js is already transitively loaded at chat.js boot via mcode-acp.js:17 (import { mcodePermissionToWebui } from "./mcode-rpc.js"). Static-import for consistency, or add a one-line comment.

• router.js:128-147 keeps /api/health and /api/settings only for the OY-3 gate tests — both routes are owned by Hono (app.js:78, app.js:119) in production. Legacy copies are dead code. Gate behind NODE_ENV !== 'production' or remove and target the Hono layer (it runs the same gates).

• matchHonoPath in app.js:177-198 is hand-rolled: the Limited to the patterns we actually use caveat is fine for :name-only, but a Hono router upgrade with * wildcards or optional segments would silently mis-route. Either pin a Hono router version or extend the helper.

• acp.mjs prompt() removed result.events (OOM hardening, line 228). A future session_update kind that needs events for finalize would silently lose them; the comment doesn't flag it as a deliberate gap.

• state-bus.js at 798 lines with 12+ settings.js imports — PR claims "split by responsibility" but state-bus owns per-cid state, SSE channel, alerts re-export, settings aggregation, getCidFromReq. A getRuntimeSettings() facade would let state-bus drop those imports.

---

What's right

• createResponseCapture + invokeHandler correctly avoid Promise<Promise<Response>>; the comment is accurate.
• gates.js factoring with Origin/CSRF (gate 1b) without the local-request exemption is the actual CSRF fix.
• scripts/check-webui-bundle.mjs is small but high-leverage — bare-specifier × cliExternalModules drift is exactly how hono shipped missing. 3× size floor + Hono marker + comment-aware regex is the right trio.
• Cancel-as-notification (mcode-rpc.js:97-99) and the chat.js:243-289 cascade ordering (notify → kill → 2 s grace) are correct. The resetThinkingClaim escape hatch for wasRunning=false zombie-claim case is the right defensive coding.