feat(tui): implement TUI @-mode reference system for agent and resource references #9337

Open
opened 2026-04-14 15:09:16 +00:00 by HAL9000 · 1 comment
Owner

Metadata

  • Branch: feat/tui-reference-system-at-mode
  • Commit Message: feat(tui): implement TUI @-mode reference system for agent and resource references
  • Milestone: v3.7.0

Background and Context

The v3.7.0 milestone (M8: TUI Implementation) explicitly includes a "Reference and command input system (@, /, ! modes)" as part of its scope, governed by ADR-046 (Reference/Command System). The @-mode reference system is the primary mechanism by which users can bind messages to specific actors, attach project resources, and include files in context — all from within the TUI prompt input.

Currently, the TUI prompt input accepts free-form text only. There is no mechanism to reference agents, resources, or files inline. Without @-mode, users cannot direct messages to specific actors or attach contextual resources to a prompt without leaving the TUI. This creates a significant usability gap for multi-agent workflows and context-aware interactions.

The @-mode reference system must be triggered by typing @ in the prompt input, display a real-time filtered autocomplete overlay, and resolve selected references when the prompt is submitted. Three reference types are required: @agent (binds the message to a specific actor), @resource (adds a project resource to the message context), and @file (adds a specific file to the message context). References are inserted as @namespace/name tokens in the prompt text.


Expected Behavior

  • Typing @ in the TUI prompt input triggers an autocomplete overlay listing all available references
  • The overlay groups references by type: agents, resources, and files
  • Typing additional characters after @ filters the list in real-time (prefix match)
  • Arrow keys (/) navigate the filtered list; Enter selects the highlighted item
  • Escape dismisses the overlay without inserting a reference
  • The selected reference is inserted as @namespace/name at the cursor position in the prompt
  • Multiple @ references can be included in a single prompt
  • On prompt submission, @agent references bind the message to the specified actor
  • On prompt submission, @resource references add the named resource to the message context
  • On prompt submission, @file references add the specified file to the message context
  • If a referenced agent, resource, or file does not exist, a clear inline error is shown before submission
  • The autocomplete overlay is styled with the Dracula theme and does not obscure the prompt input

Acceptance Criteria

  • Typing @ in the prompt input opens the reference autocomplete overlay
  • The overlay lists all available @agent, @resource, and @file references
  • Typing after @ filters the list in real-time using prefix matching
  • Arrow keys navigate the list; Enter selects and inserts @namespace/name into the prompt
  • Escape dismisses the overlay without modifying the prompt
  • Multiple @ references can coexist in a single prompt string
  • On submission, @agent references correctly bind the message to the specified actor
  • On submission, @resource references add the named resource to the message context
  • On submission, @file references add the specified file to the message context
  • Invalid references (non-existent agent/resource/file) produce a clear inline error before submission
  • The overlay is styled with the Dracula theme and does not obscure the prompt input
  • Unit tests cover: overlay trigger, real-time filtering, keyboard navigation, reference insertion, resolution logic, and error handling
  • Integration tests verify end-to-end reference resolution on prompt submission
  • Test coverage ≥ 97% for all new code paths

Subtasks

  • Define ReferenceType enum and ResolvedReference dataclass in src/cleveragents/tui/references/
  • Implement ReferenceRegistry that aggregates available agents, resources, and files
  • Implement ReferenceAutocompleteOverlay Textual widget with real-time filtering and keyboard navigation
  • Integrate overlay trigger into PromptInput widget: detect @ keypress and open overlay
  • Implement reference token insertion logic (@namespace/name) at cursor position
  • Implement multi-reference coexistence: parse and track all @ tokens in the prompt string
  • Implement reference resolution pipeline in the prompt submission handler:
    • @agent → bind message to actor
    • @resource → attach resource to message context
    • @file → attach file to message context
  • Implement inline validation: check all @ tokens against the registry before submission
  • Apply Dracula theme styling to the autocomplete overlay
  • Write unit tests for ReferenceRegistry, ReferenceAutocompleteOverlay, and resolution pipeline
  • Write integration tests for end-to-end @-mode reference flow
  • Update TUI documentation / ADR-046 implementation notes

Definition of Done

This issue is closed when:

  1. Typing @ in the TUI prompt input opens a styled autocomplete overlay listing all available agents, resources, and files
  2. Real-time filtering, keyboard navigation, and reference insertion all work correctly
  3. All three reference types (@agent, @resource, @file) are resolved correctly on prompt submission
  4. Invalid references produce a clear inline error and block submission
  5. All unit and integration tests pass with ≥ 97% coverage for new code
  6. The implementation is consistent with ADR-046 (Reference/Command System) and ADR-044 (TUI Architecture)
  7. The PR is reviewed, approved, and merged into the feat/tui-reference-system-at-mode branch targeting main

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Branch**: `feat/tui-reference-system-at-mode` - **Commit Message**: `feat(tui): implement TUI @-mode reference system for agent and resource references` - **Milestone**: v3.7.0 --- ## Background and Context The v3.7.0 milestone (M8: TUI Implementation) explicitly includes a "Reference and command input system (@, /, ! modes)" as part of its scope, governed by ADR-046 (Reference/Command System). The `@`-mode reference system is the primary mechanism by which users can bind messages to specific actors, attach project resources, and include files in context — all from within the TUI prompt input. Currently, the TUI prompt input accepts free-form text only. There is no mechanism to reference agents, resources, or files inline. Without `@`-mode, users cannot direct messages to specific actors or attach contextual resources to a prompt without leaving the TUI. This creates a significant usability gap for multi-agent workflows and context-aware interactions. The `@`-mode reference system must be triggered by typing `@` in the prompt input, display a real-time filtered autocomplete overlay, and resolve selected references when the prompt is submitted. Three reference types are required: `@agent` (binds the message to a specific actor), `@resource` (adds a project resource to the message context), and `@file` (adds a specific file to the message context). References are inserted as `@namespace/name` tokens in the prompt text. --- ## Expected Behavior - Typing `@` in the TUI prompt input triggers an autocomplete overlay listing all available references - The overlay groups references by type: agents, resources, and files - Typing additional characters after `@` filters the list in real-time (prefix match) - Arrow keys (`↑`/`↓`) navigate the filtered list; `Enter` selects the highlighted item - `Escape` dismisses the overlay without inserting a reference - The selected reference is inserted as `@namespace/name` at the cursor position in the prompt - Multiple `@` references can be included in a single prompt - On prompt submission, `@agent` references bind the message to the specified actor - On prompt submission, `@resource` references add the named resource to the message context - On prompt submission, `@file` references add the specified file to the message context - If a referenced agent, resource, or file does not exist, a clear inline error is shown before submission - The autocomplete overlay is styled with the Dracula theme and does not obscure the prompt input --- ## Acceptance Criteria - [ ] Typing `@` in the prompt input opens the reference autocomplete overlay - [ ] The overlay lists all available `@agent`, `@resource`, and `@file` references - [ ] Typing after `@` filters the list in real-time using prefix matching - [ ] Arrow keys navigate the list; `Enter` selects and inserts `@namespace/name` into the prompt - [ ] `Escape` dismisses the overlay without modifying the prompt - [ ] Multiple `@` references can coexist in a single prompt string - [ ] On submission, `@agent` references correctly bind the message to the specified actor - [ ] On submission, `@resource` references add the named resource to the message context - [ ] On submission, `@file` references add the specified file to the message context - [ ] Invalid references (non-existent agent/resource/file) produce a clear inline error before submission - [ ] The overlay is styled with the Dracula theme and does not obscure the prompt input - [ ] Unit tests cover: overlay trigger, real-time filtering, keyboard navigation, reference insertion, resolution logic, and error handling - [ ] Integration tests verify end-to-end reference resolution on prompt submission - [ ] Test coverage ≥ 97% for all new code paths --- ## Subtasks - [ ] Define `ReferenceType` enum and `ResolvedReference` dataclass in `src/cleveragents/tui/references/` - [ ] Implement `ReferenceRegistry` that aggregates available agents, resources, and files - [ ] Implement `ReferenceAutocompleteOverlay` Textual widget with real-time filtering and keyboard navigation - [ ] Integrate overlay trigger into `PromptInput` widget: detect `@` keypress and open overlay - [ ] Implement reference token insertion logic (`@namespace/name`) at cursor position - [ ] Implement multi-reference coexistence: parse and track all `@` tokens in the prompt string - [ ] Implement reference resolution pipeline in the prompt submission handler: - [ ] `@agent` → bind message to actor - [ ] `@resource` → attach resource to message context - [ ] `@file` → attach file to message context - [ ] Implement inline validation: check all `@` tokens against the registry before submission - [ ] Apply Dracula theme styling to the autocomplete overlay - [ ] Write unit tests for `ReferenceRegistry`, `ReferenceAutocompleteOverlay`, and resolution pipeline - [ ] Write integration tests for end-to-end `@`-mode reference flow - [ ] Update TUI documentation / ADR-046 implementation notes --- ## Definition of Done This issue is closed when: 1. Typing `@` in the TUI prompt input opens a styled autocomplete overlay listing all available agents, resources, and files 2. Real-time filtering, keyboard navigation, and reference insertion all work correctly 3. All three reference types (`@agent`, `@resource`, `@file`) are resolved correctly on prompt submission 4. Invalid references produce a clear inline error and block submission 5. All unit and integration tests pass with ≥ 97% coverage for new code 6. The implementation is consistent with ADR-046 (Reference/Command System) and ADR-044 (TUI Architecture) 7. The PR is reviewed, approved, and merged into the `feat/tui-reference-system-at-mode` branch targeting `main` --- **Automated by CleverAgents Bot** Agent: new-issue-creator
HAL9000 added this to the v3.7.0 milestone 2026-04-14 15:11:16 +00:00
Author
Owner

Triage: Verified [AUTO-OWNR-1]

Valid feature: The TUI @-mode reference system is explicitly listed in the v3.7.0 milestone scope: "Reference and command input system (@, /, ! modes)" per ADR-046. This issue provides a comprehensive specification for the ReferenceRegistry, ReferenceAutocompleteOverlay, reference token insertion, multi-reference support, and resolution pipeline for @agent, @resource, and @file references.

Assigning to v3.7.0 (TUI Implementation) as this is explicitly in the milestone scope. Priority High — core TUI deliverable.

MoSCoW: Must Have — the @-mode reference system is explicitly required by the v3.7.0 milestone scope and ADR-046.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

✅ **Triage: Verified** [AUTO-OWNR-1] Valid feature: The TUI @-mode reference system is explicitly listed in the v3.7.0 milestone scope: "Reference and command input system (@, /, ! modes)" per ADR-046. This issue provides a comprehensive specification for the `ReferenceRegistry`, `ReferenceAutocompleteOverlay`, reference token insertion, multi-reference support, and resolution pipeline for `@agent`, `@resource`, and `@file` references. Assigning to **v3.7.0** (TUI Implementation) as this is explicitly in the milestone scope. Priority **High** — core TUI deliverable. MoSCoW: **Must Have** — the @-mode reference system is explicitly required by the v3.7.0 milestone scope and ADR-046. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#9337
No description provided.