mecatui: /agent command and picker for session-scoped agent definitions

[kantord]

Summary and stack

Adds the TUI entrypoint for the agent-bound session API in #2003: /agent <name> creates a named-definition session; bare /agent opens a filterable picker. /agents remains the definition-details view.

Stack: main → #2003, backend → this PR. The current diff against the backend is only cmd/mecatui/: 15 files, +653/−4. The backend fixes and test cleanup were placed in #2003, then merged into this branch without rewriting published history. There were no additional TUI code changes in that backend repair pass.

Design provenance and review scope

The underlying root-session semantics come from the design-only #1783, including the human approval, and the reviewed/merged Plan / Interface #1815. The ADR was renumbered to 0353 in #1812. Permanent references: ADR snapshot and merged acceptance criteria/resolved decisions. #2105 removed that process scaffolding from main.

Those checkpoints accepted the backend design, not this implementation or every command/picker UX choice. This PR still needs its own client/UX review. Main has continued to move; the current implementation and integration checks, not the retired task list, are the evidence for review.

Behavior

• /agent <name> sends agent_definition_name through the existing client/session interface.
• Bare /agent, including from the slash palette, lists definitions, filters by text, and creates the selected definition on Enter. Submitting the command closes the slash palette.
• The request carries the operator's active provider/model selection. Under the agreed backend precedence, an explicit request pair wins over the definition's pair. Thus the command can override a definition's model pin; changing that UI choice is a separate decision, not an unspecified server rule.
• An unknown name produces a nonfatal status message rather than a terminal connection screen. The operator can enter another command.
• The picker supports keyboard selection and wheel scrolling; mouse-click row selection is not implemented.

Verification — October 15, 2026

Automated checks

The integrated backend-plus-TUI tree passed local task lint, the full task --concurrency 1 test and task --concurrency 1 test:race suites, and the offline demo's tool → permission ask → approval → result flow. The full suites include cmd/mecatui and its subpackages. Docs, generated-contract/API checks, SDK typecheck/discovery tests, and the site build also passed during the implementation pass.

The full suites were serialized, with a short temporary root and an isolated loopback namespace to avoid host fixture conflicts; setup capabilities were dropped before testing. No tests were disabled. After the stack was rearranged, head c704ae874 was verified tree-identical to the tested working tree. These results do not certify an untested future integration with newer main, and do not replace CI.

Client/UI coverage is in agent request tests and command/picker tests. The detailed backend alias, authority, persistence, ownership, and transport regression evidence is in #2003, rather than duplicated here.

Separate manual smoke report

The operator supplied an additional agent-assisted manual report using locally built mecated and mecatui, the offline mock provider, loopback with authentication disabled, and temporary HOME/XDG/workspace directories. No operator credentials or paid providers were used. This working-tree run was not pinned to an immutable final commit.

Reported TUI observations:

• The picker listed the configured definitions and filtered them by text.
• Choosing reviewer created a bound session with server-enforced plan mode.
• /agent nope produced a recoverable status message.

The same manual pass drove HTTP/SSE and gRPC creation, exact binding echoes, mode/limit clamps, runtime turn limits, restricted tool calls, aliases, rejection paths, fork/clear, and a persistent-server restart. #2003 records those observations and their limitations. In particular, the mock smoke does not prove real-model behavior, authenticated deployed ownership isolation, or mixed-version client safety.

API compatibility and remaining client review items

No new wire fields are introduced by this TUI-only diff; it consumes #2003's additive API-major-1 contract. That backend now advertises session_agent_definitions; the previous description saying no feature identifier existed is obsolete.

This PR is still a draft. The following client gaps are not fixed by the backend changes or by a passing happy-path smoke:

1. Mixed-version safety: CreateSessionWithAgent currently sends the field without requiring session_agent_definitions, and the shared create helper does not validate resolved_agent_definition_name. An older server can ignore the field and create an ordinary session. Require support and validate the echo before treating the session as bound. See client request and response handling.
2. Failed handoff: the command resets the local session state and closes the old session before the replacement create succeeds. A nonfatal error message does not mean the previous session/view was preserved. Review and test failure-safe handoff. See handoff implementation.
3. Effective state and error presentation: the ready message carries the requested mode, while the server may clamp it; all InvalidArgument create errors are labeled as an unknown definition, including unavailable-provider errors. Verify/refetch the enforced mode and preserve the actual error cause. The manual server-side plan-mode observation does not independently establish correct UI mode display.

These are implementation review items, not reasons to reopen the already accepted root-session design. Review/merge #2003 first, keep this PR based on its updated head, and finish these client checks before declaring the TUI ready.

What the local checks do not establish

No manual live-provider run, authenticated multi-owner deployment, Unix-socket-only test of the inner client-MCP guard, live TypeScript SDK journey, or deployed mecak8s/Redis/remote-driver/TLS/mTLS/microVM/execution-template qualification was performed in the reported smoke pass. Those require appropriate fixtures or environments and can be performed before merge; they are not inherently post-merge-only checks.

Main integration update: #2003 now includes main at ce0f816e0 through c4b5b1fe0. Its sole textual conflict was resolved by retaining both independent changelog entries, and full local lint/docs/offline/race/demo checks passed on the merged backend. This PR incorporates that backend in 62cdfcb8c; the TUI package race suite and scoped lint passed again, and the diff remains 15 TUI-only files. Both PRs are conflict-free at this update. The manual smoke observations above were not rerun during conflict resolution. Latest CI and the outstanding client items above remain required; merging main did not fix those client issues.