Skip to content

@ picker cannot search skills or agents; typed @agent mentions never reach the backend router from the TUI #6648

Description

@bug-ops

Description

The @ picker searches files only. Skills and sub-agents — both first-class, named, user-facing entities — have no discovery surface in the composer. Worse, the backend already routes @agent-name-prefixed messages to sub-agents (dispatch_agent_command), but that path is unreachable from the TUI keyboard because the @ key is monopolized by the file picker and never inserts the character (today it is reachable via paste only).

This issue extends the inline @ mention picker (#6647, prerequisite) with category tabs so one gesture covers files, skills, and agents.

Current Behavior

  • Picker data source is the file index exclusively (crates/zeph-tui/src/file_picker.rs).
  • Backend @agent mention routing exists and falls back gracefully: crates/zeph-core/src/agent/slash_commands.rs:88 routes any @-prefixed message → :162 dispatch_agent_command builds the known-agent list from SubAgentManager::definitions() and falls through to the LLM on no match. crates/zeph-subagent/src/command.rs:313 parse_mention is documented as agent-first with file-reference fallback.
  • Skill catalog is available via SkillRegistry::all_meta() (crates/zeph-skills/src/registry.rs:330; SkillMeta has name, description).
  • Agent definitions are available via SubAgentManager::definitions() / SubAgentDef::load_all (crates/zeph-subagent/src/def.rs:635).
  • The TUI process currently receives only runtime-active skill names and sub-agent status via MetricsSnapshot (crates/zeph-core/src/metrics.rs:377,508) — not the full catalogs with descriptions.
  • specs/UX/mention-routing.md (research(ux): Goose v1.32.0 — @agent mention chat and desktop notifications on task completion #3327) deferred @agent mention UX pending an agent registry; SubAgentManager::definitions() now fills that role for local presets.

Expected Behavior

The inline @ popup gains category tabs: All | Files | Skills | Agents.

  • Default tab is All: a single fuzzy-ranked list across all three categories, each row carrying a type marker (e.g. [f]/[s]/[a] or themed glyphs).
  • / switch tabs while the popup is open (cursor movement inside the query is not needed — Backspace edits it; both keys are re-claimed by the popup only while it is open).
  • Rows for skills and agents render name — description (description dimmed, truncated to fit); file rows render the repo-relative path.
  • Selection semantics on accept (Tab/Enter):
    • File → inserts the bare repo-relative path + trailing space (status quo).
    • Skill → inserts the skill name as plain text + trailing space. No forced activation: the semantic skill matcher picks it up through the normal flow. (Forced skill injection is a possible future follow-up, out of scope.)
    • Agent → inserts @agent-name + trailing space (sigil retained). When the message starts with the mention, the existing backend routing dispatches it to the sub-agent; unknown names fall through to the LLM per specs/UX/mention-routing.md invariants (never error, full original message in history, security pre-screen not bypassed).
  • All three categories are filtered by the same query with the same nucleo_matcher engine.
  • Empty catalogs degrade gracefully: a tab with no entries shows a dimmed no skills loaded / no agents defined row; All simply omits the category.

Data plumbing

Full SkillMeta and SubAgentDef catalogs must reach the TUI. Options (implementer's choice, spec will fix one):

  • extend the existing snapshot/event channel with catalog fields, or
  • load directly in the TUI on popup open, like open_file_picker does with FileIndex::build (must go through the task supervisor / spawn_blocking; catalogs are small, a cached load with TTL mirrors the file-index pattern).

Catalog loading must respect the Spinner Rule (visible status while loading) and the no-blocking-on-render-thread invariant.

Non-goals / coordination

  • No new routing semantics: message dispatch behavior is untouched; this issue only makes the already-implemented @agent path typeable and discoverable.
  • No forced skill activation mechanism.
  • Depends on the inline picker rework (modal @ file picker blocks prompt typing and swallows literal @ characters #6647); the tab bar and category sources build on its popup.
  • specs/UX/mention-routing.md should be updated from "deferred" to reflect the delivered picker surface (spec change tracked with this issue).

Environment

  • Version: main @ v0.22.3
  • Crates: zeph-tui (feature tui), read-only use of zeph-skills, zeph-subagent catalogs

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2High value, medium complexityenhancementNew feature or requestskillszeph-skills cratesub-agentsSub-agent orchestrationtuiTUI dashboarduxUser experience

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions