Orchestrata Ultimate / Specs / 022-tui-interface

022-tui-interface: Terminal User Interface (TUI)

The Terminal User Interface (TUI) provides a rich, interactive terminal-based interface for human users to interact with the Orchestrata multi-agent orchestration system. It replaces the basic REPL in pipeline_cli.py with a modern Textual-based application featuring panels, real-time updates, keyboard navigation, and structured layout.

At a glance

Item	Value
Spec directory	`specs/022-tui-interface/`
Status line in the spec	Design Phase
Requirement IDs defined	39
With a `@traces` citation in `src/`	0 (0.0%)
With a `@traces` citation in `tests/`	0 (0.0%)
Tracked files	4
RTM page	022-tui-interface

Reading this spec

The Terminal User Interface (TUI) is an interactive, terminal-based interface through which people work with the Orchestrata multi-agent system. It replaces the basic input and print loop in pipeline_cli.py with a Textual application that has panels, real-time updates, keyboard navigation and a structured layout. The current REPL gives no visual structure, no view of agent activity or message flow, no real-time updates and no way to follow several threads at once.

The scope is ten user stories: interactive intent submission, thread management, a real-time chat view, an agent status dashboard, response input and the approval workflow (priority 1), a system status panel, a command palette and session management (priority 2), and packet flow visualization (priority 3). The functional requirements cover application launch, layout, thread management, message display, input handling and real-time updates. Requirement IDs use the REQ-022- prefix.

The design decisions are the Textual framework, CSS-based styling with live reload, a widget-based architecture with panels for different concerns, an async-first design for real-time agent updates, and keyboard-driven navigation with optional vim-style bindings. The spec includes a glossary defining terms such as panel, widget, reactive, header, footer and thread.

No tracing module is listed for this spec in the code table. The per-requirement view is on the RTM page.

The spec's status line reads Design Phase. It tracks 4 files and defines 39 requirement IDs. The full text follows below.

No src/ symbol cites any of the 39 requirements, so measured trace coverage is 0.0%. In tests/, 0 requirements are cited by a test-side @traces.

Coverage gaps: 39 requirements have no citing symbol. The largest untraced groups are REQ-022-US-003 (5), REQ-022-US-001 (4), REQ-022-US-002 (4). Untraced means no @traces names the ID; the behaviour may still exist in code that was never annotated.

Requirements

Checkbox is the state recorded in the requirements checklist; Traced by is the count of src/ symbols whose @traces names the ID.

ID	Done	Requirement	Traced by
`REQ-022-US-001-001`	no	Text input widget at bottom of screen for entering intent	none
`REQ-022-US-001-002`	no	Submit with Enter key, clear input after submission	none
`REQ-022-US-001-003`	no	Show thread_id returned from system	none
`REQ-022-US-001-004`	no	Auto-create new thread in thread list panel	none
`REQ-022-US-002-001`	no	Left panel shows list of all threads with status indicators	none
`REQ-022-US-002-002`	no	Click or keyboard navigation selects active thread	none
`REQ-022-US-002-003`	no	Visual highlight on selected thread	none
`REQ-022-US-002-004`	no	Thread shows: thread_id (truncated), last message preview, work status	none
`REQ-022-US-003-001`	no	Center panel displays message history for selected thread	none
`REQ-022-US-003-002`	no	Messages styled by sender (human vs. Volk vs. system)	none
`REQ-022-US-003-003`	no	Timestamps shown on messages	none
`REQ-022-US-003-004`	no	Auto-scroll to newest message	none
`REQ-022-US-003-005`	no	Support for multi-line messages and code blocks	none
`REQ-022-US-004-001`	no	Panel or header section shows all registered Volks	none
`REQ-022-US-004-002`	no	Each Volk shows: alias, role, status indicator (color-coded)	none
`REQ-022-US-004-003`	no	Status updates in real-time as agents work	none
`REQ-022-US-004-004`	no	Click on Volk shows their recent activity	none
`REQ-022-US-005-001`	no	Input area remains available after submitting intent	none
`REQ-022-US-005-002`	no	Enter key submits response to current thread	none
`REQ-022-US-005-003`	no	Up arrow recalls previous response for editing	none
`REQ-022-US-005-004`	no	Clear visual indicator of which thread receiving the response	none
`REQ-022-US-006-001`	no	Status panel shows: Kernel, Postman, Redis, Neo4j, Prolog	none
`REQ-022-US-006-002`	no	Each service shows: connected/disconnected, latency if available	none
`REQ-022-US-006-003`	no	Color-coded indicators (green=healthy, amber=degraded, red=down)	none
`REQ-022-US-007-001`	no	Ctrl+P opens command palette overlay	none
`REQ-022-US-007-002`	no	Type to filter available commands	none
`REQ-022-US-007-003`	no	Enter executes selected command	none
`REQ-022-US-007-004`	no	Commands: submit, respond, approve, reject, status, quit	none
`REQ-022-US-008-001`	no	When Volk completes work, show in chat with "Awaiting Approval" status	none
`REQ-022-US-008-002`	no	Keyboard shortcut (Ctrl+A) to approve	none
`REQ-022-US-008-003`	no	Keyboard shortcut (Ctrl+R) to reject with feedback prompt	none
`REQ-022-US-008-004`	no	Approval/rejection sends CXP packet with work_status update	none
`REQ-022-US-009-001`	no	Toggle panel showing packet flow log	none
`REQ-022-US-009-002`	no	Each entry shows: timestamp, from_agent, to_agent, subject	none
`REQ-022-US-009-003`	no	Real-time updates as packets are routed	none
`REQ-022-US-009-004`	no	Click on packet shows full payload	none
`REQ-022-US-010-001`	no	Show current session: number, duration, fact count	none
`REQ-022-US-010-002`	no	Commands to end session, archive to Neo4j	none
`REQ-022-US-010-003`	no	Visual indicator when session is active vs. none	none

Code that traces this spec

No src/ symbol cites a requirement of this spec.

Checklists

`checklists/requirements.md`

The requirement list above comes from this file; 0 of 39 checkbox items are ticked.

Other tracked files

specs/022-tui-interface/compliance-audit.md
specs/022-tui-interface/diagram.md

Full spec text

Verbatim from specs/022-tui-interface/spec.md; headings are pushed down two levels.

SPEC-022: Terminal User Interface (TUI)

Metadata

Spec ID: 022-tui-interface
Title: Terminal User Interface for Orchestrata
Author: Mohamed
Status: Design Phase
Created: 2026-04-03
Last Updated: 2026-04-03
Priority: P1
Version: 1.0.0

Overview

What

Why

The current pipeline_cli.py REPL is a basic input()/print() loop with no visual structure
Users cannot see agent activity, message flow, or system status at a glance
No support for real-time updates as agents work on tasks
Limited to single-line text input with no rich interaction patterns
No ability to view multiple threads or conversations simultaneously

How

Textual framework for Python (textual.textualize.io)
CSS-based styling with live-reload support
Widget-based architecture with panels for different concerns
Async-first design to handle real-time agent updates
Keyboard-driven navigation (vim-style bindings optional)

Terminology and Glossary

Term	Definition
TUI	Terminal User Interface — a text-based user interface in the terminal window, as opposed to CLI (command-line) or GUI (graphical).
Textual	A Python framework for building TUIs with widgets, CSS styling, and reactive updates.
Panel	A distinct visual area in the TUI that displays specific content (e.g., thread list, chat view, status).
Widget	A reusable UI component in Textual (Button, Input, ListView, etc.).
Reactive	A pattern where UI automatically updates when underlying data changes.
Header	Top bar showing system title, connection status, and global actions.
Footer	Bottom bar showing keyboard shortcuts and context-sensitive actions.
Thread	A unique identifier (thread_id) tracking a conversation or task across multiple CXP packets and Volk interactions.
Volk	An AI agent within the Orchestrata system, identified by alias (e.g., U:Ox, U:Cd).
CXP Packet	Cross-agent eXchange Protocol message — the structured 11-field packet format used for all communication.
Session	A bounded work period tracked in context.json, containing facts, achievements, and deferred work items.
Intent	A natural language request submitted by a human user, parsed and routed to the appropriate Volk.
Message Bubble	A styled block displaying a single message in the chat view, with sender, timestamp, and content.
Status Indicator	Visual element showing agent state: active (green), idle (gray), error (red), working (amber).
Work Status	CXP state machine field tracking task progress: pending → in_progress → review → resolved/rejected.
Command Palette	A quick-access overlay (Ctrl+P) for executing commands without navigating menus.

User Scenarios & Stories

US-001: Interactive Intent Submission (P1)

As a user I want to type my intent in a dedicated input area So that I can submit tasks to the orchestration system

Acceptance Criteria:

[ ] Text input widget at bottom of screen for entering intent
[ ] Submit with Enter key, clear input after submission
[ ] Show thread_id returned from system
[ ] Auto-create new thread in thread list panel

US-002: Thread Management (P1)

As a user I want to see all active threads and switch between them So that I can work on multiple tasks simultaneously

Acceptance Criteria:

[ ] Left panel shows list of all threads with status indicators
[ ] Click or keyboard navigation selects active thread
[ ] Visual highlight on selected thread
[ ] Thread shows: thread_id (truncated), last message preview, work status

US-003: Real-Time Chat View (P1)

As a user I want to see a scrolling chat history with each Volk So that I can follow the conversation and respond appropriately

Acceptance Criteria:

[ ] Center panel displays message history for selected thread
[ ] Messages styled by sender (human vs. Volk vs. system)
[ ] Timestamps shown on messages
[ ] Auto-scroll to newest message
[ ] Support for multi-line messages and code blocks

US-004: Agent Status Dashboard (P1)

As a user I want to see all Volks and their current status at a glance So that I know which agents are working

Acceptance Criteria:

[ ] Panel or header section shows all registered Volks
[ ] Each Volk shows: alias, role, status indicator (color-coded)
[ ] Status updates in real-time as agents work
[ ] Click on Volk shows their recent activity

US-005: Response Input (P1)

As a user I want to type responses to Volk questions So that I can participate in the requirement gathering loop

Acceptance Criteria:

[ ] Input area remains available after submitting intent
[ ] Enter key submits response to current thread
[ ] Up arrow recalls previous response for editing
[ ] Clear visual indicator of which thread receiving the response

US-006: System Status Panel (P2)

As a system operator I want to see the health of all services So that I can monitor system connectivity

Acceptance Criteria:

[ ] Status panel shows: Kernel, Postman, Redis, Neo4j, Prolog
[ ] Each service shows: connected/disconnected, latency if available
[ ] Color-coded indicators (green=healthy, amber=degraded, red=down)

US-007: Command Palette (P2)

As a power user I want to execute commands quickly without menus So that I can be more productive

Acceptance Criteria:

[ ] Ctrl+P opens command palette overlay
[ ] Type to filter available commands
[ ] Enter executes selected command
[ ] Commands: submit, respond, approve, reject, status, quit

US-008: Approval Workflow (P1)

As a human supervisor I want to review and approve agent outputs So that Article I (Human Authority) is enforced

Acceptance Criteria:

[ ] When Volk completes work, show in chat with "Awaiting Approval" status
[ ] Keyboard shortcut (Ctrl+A) to approve
[ ] Keyboard shortcut (Ctrl+R) to reject with feedback prompt
[ ] Approval/rejection sends CXP packet with work_status update

US-009: Packet Flow Visualization (P3)

As a developer I want to see CXP packets moving between agents So that I can debug the orchestration

Acceptance Criteria:

[ ] Toggle panel showing packet flow log
[ ] Each entry shows: timestamp, from_agent, to_agent, subject
[ ] Real-time updates as packets are routed
[ ] Click on packet shows full payload

US-010: Session Management (P2)

As a user I want to see and manage session state So that I can track work across sessions

Acceptance Criteria:

[ ] Show current session: number, duration, fact count
[ ] Commands to end session, archive to Neo4j
[ ] Visual indicator when session is active vs. none

Standardized Acceptance Criteria

SAC-US1: TUI Launch

#	Criterion	Verification
SAC-US1-01	`orchestrata tui` launches the Textual application	Process starts, TUI renders
SAC-US1-02	TUI displays Header with system title "Orchestrata"	Visual inspection
SAC-US1-03	TUI displays Footer with keyboard shortcuts	Visual inspection
SAC-US1-04	TUI connects to Kernel within 5 seconds	Timing measurement
SAC-US1-05	TUI handles missing services gracefully (show disconnected status)	Service shutdown test

SAC-US2: Thread Management

#	Criterion	Verification
SAC-US2-01	Thread list panel shows on left side	Visual layout check
SAC-US2-02	New intent creates new thread in list	Submit intent, verify list
SAC-US2-03	Clicking thread selects it and shows messages	Mouse interaction test
SAC-US2-04	Arrow keys navigate thread list	Keyboard test
SAC-US2-05	Selected thread has visual highlight	Visual inspection

SAC-US3: Message Display

#	Criterion	Verification
SAC-US3-01	Messages display in center panel	Visual layout check
SAC-US3-02	Human messages styled differently from Volk messages	Submit and receive, compare styles
SAC-US3-03	Messages auto-scroll to bottom	Send multiple messages
SAC-US3-04	Timestamps visible on messages	Visual inspection
SAC-US3-05	Code blocks render with monospace font	Send message with `code`

SAC-US4: Input Handling

#	Criterion	Verification
SAC-US4-01	Input widget at bottom of screen	Visual layout check
SAC-US4-02	Enter key submits input	Type and press Enter
SAC-US4-03	Input clears after submission	Visual inspection after submit
SAC-US4-04	Multi-line input with Shift+Enter	Hold Shift, press Enter

SAC-US5: Agent Status

#	Criterion	Verification
SAC-US5-01	All registered Volks visible	Start system, check display
SAC-US5-02	Status indicators color-coded (green/gray/red)	Visual inspection
SAC-US5-03	Status updates as agents work	Submit intent, watch status
SAC-US5-04	Click on Volk shows recent messages	Mouse interaction test

SAC-US6: Approval Workflow

#	Criterion	Verification
SAC-US6-01	Work completion shows "Awaiting Approval"	Submit full task, wait for completion
SAC-US6-02	Ctrl+A approves current work	Keyboard test
SAC-US6-03	Ctrl+R prompts for rejection reason	Keyboard test, verify prompt
SAC-US6-04	Approval sends CXP with work_status=resolved	Network inspection or log

SAC-US7: Command Palette

#	Criterion	Verification
SAC-US7-01	Ctrl+P opens command palette	Keyboard test
SAC-US7-02	Type filters available commands	Keyboard test
SAC-US7-03	Enter executes selected command	Keyboard test
SAC-US7-04	Escape closes palette	Keyboard test

Data Models

DM-001: TUI State

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "TUIState",
  "description": "Main application state for the TUI",
  "type": "object",
  "properties": {
    "connected": { "type": "boolean" },
    "kernel_status": { "type": "string", "enum": ["connected", "disconnected", "error"] },
    "postman_status": { "type": "string", "enum": ["connected", "disconnected", "error"] },
    "redis_status": { "type": "string", "enum": ["connected", "disconnected", "error"] },
    "neo4j_status": { "type": "string", "enum": ["connected", "disconnected", "error"] },
    "session": {
      "type": "object",
      "properties": {
        "session_number": { "type": "integer" },
        "status": { "type": "string" },
        "started_at": { "type": "string" },
        "fact_count": { "type": "integer" }
      }
    },
    "volks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "alias": { "type": "string" },
          "role": { "type": "string" },
          "status": { "type": "string", "enum": ["active", "idle", "error", "working"] }
        }
      }
    }
  }
}

DM-002: Thread

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Thread",
  "description": "A conversation thread in the TUI",
  "type": "object",
  "required": ["thread_id", "status", "messages"],
  "properties": {
    "thread_id": { "type": "string", "format": "uuid" },
    "status": { "type": "string", "enum": ["pending", "in_progress", "review", "resolved", "rejected"] },
    "created_at": { "type": "string", "format": "date-time" },
    "updated_at": { "type": "string", "format": "date-time" },
    "active_agent": { "type": "string" },
    "messages": {
      "type": "array",
      "items": { "$ref": "#/definitions/Message" }
    }
  },
  "definitions": {
    "Message": {
      "type": "object",
      "required": ["message_id", "from", "timestamp", "content"],
      "properties": {
        "message_id": { "type": "string", "format": "uuid" },
        "from": { "type": "string" },
        "to": { "type": "string" },
        "timestamp": { "type": "string", "format": "date-time" },
        "content": { "type": "string" },
        "subject": { "type": "string" }
      }
    }
  }
}

DM-003: Command Palette Command

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "TUCommand",
  "description": "A command available in the command palette",
  "type": "object",
  "required": ["id", "label", "shortcut", "action"],
  "properties": {
    "id": { "type": "string" },
    "label": { "type": "string" },
    "shortcut": { "type": "string" },
    "action": { "type": "string" },
    "category": { "type": "string" }
  }
}

Error Conditions and Edge Cases

Code	Condition	Trigger	Severity	Recovery
ERR-001	Kernel not running	Launch TUI without running `orchestrata start`	Warning	Show disconnected status, allow retry
ERR-002	Redis connection lost	Redis server stops	Warning	Show disconnected, queue operations locally
ERR-003	Neo4j connection lost	Neo4j server stops	Warning	Show disconnected, disable knowledge queries
ERR-004	Invalid thread_id	User navigates to non-existent thread	Error	Show error message, return to thread list
ERR-005	Governance blocks action	User tries to approve but Prolog denies	Error	Show governance rejection reason
ERR-006	Session expired	Session ends while TUI running	Info	Prompt to start new session
ERR-007	CXP packet timeout	Agent takes too long to respond	Warning	Show timeout indicator, allow retry
ERR-008	Invalid intent format	User submits blank intent	Error	Show validation error, clear input
ERR-009	Prolog engine failure	SWI-Prolog crashes	Critical	Show error, offer to restart
ERR-010	Postman connection lost	Postman service stops	Warning	Show disconnected, queue messages
ERR-011	Invalid response input	User submits blank response	Error	Show validation error, retain input
ERR-012	Thread limit exceeded	User creates more than 50 threads	Error	Prompt to close old threads

Performance Benchmarks

ID	Operation	Target	Measurement Method
TUI-PR-001	TUI launch to ready	≤ 3 seconds	Time from command to interactive
TUI-PR-002	Thread switch	≤ 100ms	Time from click to message display
TUI-PR-003	Message send/receive	≤ 200ms round-trip	Time from Enter to message in chat
TUI-PR-004	Status panel update	≤ 50ms	Time from event to UI update
TUI-PR-005	Command palette open	≤ 100ms	Time from Ctrl+P to overlay
TUI-PR-006	Memory footprint	≤ 200MB RSS	Resident set size during use
TUI-PR-007	Handle 1000+ messages	No degradation	Load test with large thread

Testability Guidelines

ID	Scope	Test Type	Description
TUI-TC001	US1	Integration	Submit intent via TUI, verify thread created
TUI-TC002	US2	Integration	Create multiple threads, navigate between them
TUI-TC003	US3	Integration	Receive messages from Volk, verify display
TUI-TC004	US4	Unit	Verify status indicators reflect actual agent state
TUI-TC005	US5	Integration	Type response, submit, verify delivery
TUI-TC006	US6	Integration	Approve work via shortcut, verify CXP packet
TUI-TC007	US7	Unit	Test command palette filtering and execution
TUI-TC008	US1	Unit	TUI handles missing Kernel gracefully
TUI-TC009	US3	Unit	Verify code block rendering
TUI-TC010	US6	Integration	Reject work, verify feedback prompt appears

Functional Requirements

FR-001: Application Launch

System SHALL provide orchestrata tui command to launch the TUI
System SHALL display Header with "Orchestrata" title
System SHALL display Footer with keyboard shortcuts
System SHALL connect to running Kernel automatically

FR-002: Layout Structure

System SHALL display a three-panel layout: threads | chat | status
System SHALL support responsive resizing
System SHALL use CSS for all styling (no hardcoded colors)

FR-003: Thread Management

System SHALL create new thread when intent submitted
System SHALL display all threads in left panel
System SHALL highlight selected thread
System SHALL support keyboard and mouse navigation

FR-004: Message Display

System SHALL display messages in center panel
System SHALL style messages by sender type (human/Volk/system)
System SHALL auto-scroll to newest message
System SHALL support code block rendering

FR-005: Input Handling

System SHALL provide text input at bottom of screen
System SHALL submit on Enter key
System SHALL clear input after submission
System SHALL support multi-line input (Shift+Enter)

FR-006: Real-Time Updates

System SHALL update agent status in real-time
System SHALL receive new messages without polling
System SHALL show packet flow when enabled

FR-007: Command Palette

System SHALL open command palette on Ctrl+P
System SHALL filter commands by typing
System SHALL execute command on Enter

FR-008: Approval Workflow

System SHALL show "Awaiting Approval" when work complete
System SHALL approve on Ctrl+A
System SHALL reject on Ctrl+R with prompt

FR-009: Session Integration

System SHALL display current session info
System SHALL support session end via command

Non-Functional Requirements

NFR-001: Performance

TUI SHALL launch within 3 seconds
Thread switching SHALL feel instant (<100ms)
Message updates SHALL appear within 200ms of receipt

NFR-002: Accessibility

TUI SHALL work in terminals supporting 256 colors
TUI SHALL degrade gracefully in monochrome terminals
All interactive elements SHALL be keyboard-accessible

NFR-003: Reliability

TUI SHALL handle connection loss gracefully
TUI SHALL auto-reconnect to services when available
TUI SHALL not crash on malformed CXP packets

NFR-004: Usability

All features SHALL be discoverable via keyboard shortcuts shown in Footer
Error messages SHALL be actionable with recovery suggestions
TUI SHALL work in terminals as small as 80x24

NFR-005: Maintainability

TUI code SHALL be organized into logical modules
Widgets SHALL be reusable components
CSS SHALL be in separate .tcss file for live-reload

Technical Design

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Orchestrata TUI                           │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │  Thread      │  │    Chat      │  │   Status     │   │
│  │  List       │  │    View      │  │   Panel      │   │
│  │  Panel      │  │    Panel     │  │              │   │
│  └──────────────┘  └──────────────┘  └──────────────┘   │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Input Area                              │   │
│  └─────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────┤
│  Header                                    Footer         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    PipelineKernel                            │
│              (orchestrata.kernel.pipeline)                   │
├─────────────────────────────────────────────────────────────┤
│  submit_intent(text) → thread_id                            │
│  respond(thread_id, text) → CXPPacket                       │
│  approve(thread_id) → bool                                   │
│  reject(thread_id, reason) → bool                           │
│  get_status() → SystemStatus                                │
└─────────────────────────────────────────────────────────────┘

Components

Component	File	Responsibility
TUIApp	`tui_app.py`	Main application class, layout composition
ThreadListPanel	`panels/thread_list.py`	Left panel with thread navigation
ChatPanel	`panels/chat.py`	Center panel with message display
StatusPanel	`panels/status.py`	Right panel with service/agent status
InputArea	`widgets/input_area.py`	Bottom input with submit handling
CommandPalette	`widgets/command_palette.py`	Ctrl+P overlay for commands

CSS Styling

File: tui.tcss
Layout: Grid-based with three columns
Colors: Dark theme by default, light theme available
Typography: Monospace for messages, proportional for UI

Key Bindings

Shortcut	Action
Enter	Submit intent/response
Shift+Enter	New line in input
Up/Down	Navigate threads
Ctrl+P	Open command palette
Ctrl+A	Approve current work
Ctrl+R	Reject current work
Ctrl+Q	Quit TUI
Ctrl+L	Clear current thread
Tab	Cycle focus between panels

Examples and Sample Data

Example 1: TUI Launch

┌─────────────────────────────────────────────────────────────────────────────┐
│  Orchestrata v0.2.1                                    [●] Connected        │
├─────────────┬───────────────────────────────────────────┬───────────────────┤
│ Threads     │ Chat                                      │ Status            │
├─────────────┼───────────────────────────────────────────┼───────────────────┤
│ > a1b2c3d4e5 │ [10:30:45] Human:                        │ Kernel   ● Online │
│   Pending   │ Create a REST API for user               │ Postman  ● Online │
│             │ management with CRUD endpoints            │ Redis    ● Online │
│ d4e5f6g7h8  │                                           │ Neo4j    ● Online │
│   In Review │ [10:30:46] U:Cx:                         │                  │
│             │ QUESTIONS:                                │ Volks:            │
│             │ 1. [D6] What deployment platform?        │ U:Ox    ● active │
│             │ 2. [D5] Any specific testing             │ U:Cx    ● working │
│             │    requirements?                         │ U:Cd    ● idle    │
│             │                                           │ U:Qa    ● idle    │
├─────────────┴───────────────────────────────────────────┴───────────────────┤
│ > What deployment platform? (Incus, Docker, bare metal)                    │
│                                                                             │
│  Enter to submit │ Tab: switch panel │ Ctrl+P: commands │ Ctrl+Q: quit    │
└─────────────────────────────────────────────────────────────────────────────┘

Example 2: Command Palette

┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│                        ┌─────────────────────────┐                          │
│                        │ > submit                │                          │
│                        │   submit - Submit intent                          │
│                        │   status    - Show system status                  │
│                        │   approve   - Approve current work                │
│                        │   reject    - Reject with reason                  │
│                        │   clear     - Clear thread                         │
│                        │   quit      - Exit TUI                            │
│                        └─────────────────────────┘                          │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Example 3: Approval Required

┌─────────────────────────────────────────────────────────────────────────────┐
│  Orchestrata v0.2.1                                    [●] Connected        │
├─────────────┬───────────────────────────────────────────┬───────────────────┤
│ Threads     │ Chat                                      │ Status            │
├─────────────┼───────────────────────────────────────────┼───────────────────┤
│ > a1b2c3d4e5 │ [10:45:12] Human:                        │ Kernel   ● Online │
│   Awaiting  │ Create a REST API for user               │ Postman  ● Online │
│   Approval  │ management with CRUD endpoints            │ Redis    ● Online │
│             │                                           │ Neo4j    ● Online │
│             │ [10:47:30] U:Cx: Working on implementation │                  │
│             │                                           │ Volks:            │
│             │ [10:48:33] U:Cd:                         │ U:Ox    ● active │
│             │ Implementation ready!                     │ U:Cx    ● idle   │
│             │ Files created: 12                        │ U:Cd    ● working │
│             │   - app.py                               │ U:Qa    ● working │
│             │   - models.py                            │                  │
│             │   - routes.py                            │                  │
│             │   - (additional files)                                  │                  │
│             │                                           │                  │
│             │ ════════════════════════════════════════ │                  │
│             │ ⚠ AWAITING APPROVAL                     │                  │
│             │ ════════════════════════════════════════ │                  │
│             │                                           │                  │
├─────────────┴───────────────────────────────────────────┴───────────────────┤
│ >                                                            Ctrl+A: Approve│
│                                                                             │
│  Enter to submit │ Tab: switch panel │ Ctrl+A: approve │ Ctrl+R: reject   │
└─────────────────────────────────────────────────────────────────────────────┘

Security

SEC-001: Input Validation

System SHALL validate all user input before processing
System SHALL sanitize text to prevent terminal escape sequences
System SHALL reject control characters except Tab, Enter, and Ctrl+[A-Z]
System SHALL enforce maximum message length (10,000 characters)

SEC-002: Authorization

System SHALL check user permissions before allowing approval actions
System SHALL verify session authenticity on each operation
System SHALL enforce role-based access (human supervisor vs. observer)
System SHALL log all approval/rejection actions with user identity

SEC-003: Secure Communication

System SHALL use encrypted connections (TLS) for all external services
System SHALL validate CXP packet signatures before processing
System SHALL prevent injection attacks through message content
System SHALL rate-limit user actions (max 10 commands/second)

SEC-004: Audit Logging

System SHALL log all user actions with timestamps
System SHALL log all approval decisions with reasoning
System SHALL log security-relevant events (auth failures, etc.)
System SHALL prevent log tampering through append-only storage

SEC-005: Data Protection

System SHALL not store session passwords in TUI
System SHALL use secure memory handling for sensitive data
System SHALL automatically expire cached credentials
System SHALL support keychain integration where available

Interface Definitions

ID-001: TUI to Kernel

class TUIKernelInterface:
    """Interface between TUI and PipelineKernel."""
    
    async def submit_intent(self, text: str) -> str:
        """Submit intent, return thread_id."""
        pass
    
    async def respond(self, thread_id: str, text: str) -> CXPPacket:
        """Respond to thread, return response packet."""
        pass
    
    async def approve(self, thread_id: str) -> bool:
        """Approve work on thread."""
        pass
    
    async def reject(self, thread_id: str, reason: str) -> bool:
        """Reject work on thread with reason."""
        pass
    
    async def get_status(self) -> SystemStatus:
        """Get system status."""
        pass
    
    async def subscribe_to_messages(self, callback: Callable) -> None:
        """Subscribe to incoming messages."""
        pass
    
    async def subscribe_to_status(self, callback: Callable) -> None:
        """Subscribe to status changes."""
        pass

Dependencies

Runtime Dependencies

Dependency	Version	Purpose
Python	≥3.14	Runtime
Textual	≥0.90.0	TUI framework
Rich	≥13.0	Terminal formatting
Click	≥8.1	CLI entry point

Orchestrata Package Dependencies

Package	Purpose
orchestrata-kernel	PipelineKernel access
orchestrata-postman	CXP packet handling
orchestrata-session	Session state
orchestrata-cxp	Packet definitions

Governance

GOV-001: Human Authority Principle

System SHALL require human approval before any automated action
System SHALL display clear approval prompts for work completion
System SHALL provide detailed context for approval decisions
System SHALL enforce governance rules via Prolog validation

GOV-002: Audit Trail

System SHALL maintain complete audit trail of all decisions
System SHALL record who approved/rejected work and when
System SHALL store audit logs in Neo4j for persistence
System SHALL provide query interface for audit history

GOV-003: Compliance Enforcement

System SHALL enforce organizational policies via Prolog rules
System SHALL block actions that violate governance constraints
System SHALL log all governance rejections with policy reference
System SHALL provide admin interface for policy management

GOV-004: Separation of Duties

System SHALL require different users for different actions
System SHALL prevent self-approval of work
System SHALL log all delegation and authorization changes
System SHALL enforce minimum review requirements for critical actions

GOV-005: Transparency

System SHALL display all governance checks and their results
System SHALL provide clear explanation for any blocked actions
System SHALL maintain human-readable decision records
System SHALL support independent review of automated decisions

Integration Points

INT-001: PipelineKernel Integration

Interface: orchestrata.kernel.pipeline.PipelineKernel
Methods: submit_intent(), respond(), approve(), reject(), get_status()
Protocol: Async Python calls, CXPPacket return types
Error Handling: Connection timeouts, service unavailable responses

INT-002: CXP Postman Integration

Interface: orchestrata.postman.CXPPostman
Methods: send_packet(), subscribe_to_packets()
Protocol: Async event streams, callback registration
Error Handling: Packet delivery failures, malformed packet detection

INT-003: Session Management Integration

Interface: orchestrata.session.SessionManager
Methods: get_current_session(), archive_session(), end_session()
Protocol: JSON state files, file system operations
Error Handling: Missing session files, concurrent access conflicts

INT-004: Redis Cache Integration

Interface: Redis client library
Methods: get(), set(), publish(), subscribe()
Protocol: Redis Pub/Sub for real-time updates
Error Handling: Connection loss, message queue overflow

INT-005: Neo4j Knowledge Graph Integration

Interface: Neo4j driver
Methods: run_query(), write_transaction()
Protocol: Cypher queries, transaction boundaries
Error Handling: Query failures, constraint violations

INT-006: Prolog Governance Integration

Interface: SWI-Prolog engine via subprocess
Methods: query(), assert_fact(), retract_fact()
Protocol: Prolog query strings, JSON result parsing
Error Handling: Syntax errors, timeout conditions

INT-007: Terminal Environment Integration

Interface: Operating system terminal APIs
Methods: set_title(), get_size(), set_cursor()
Protocol: ANSI escape codes, ioctl system calls
Error Handling: Unsupported features, terminal resizing

Definition of Done

ID	Criterion	Verification Method
DoD-001	TUI launches with `orchestrata tui` command	Command execution test
DoD-002	Three-panel layout renders correctly	Visual inspection
DoD-003	Can submit intent and see thread created	Integration test
DoD-004	Can navigate between threads	Manual test
DoD-005	Can respond to agent questions	Integration test
DoD-006	Agent status updates in real-time	Observation during work
DoD-007	Command palette functions (Ctrl+P)	Keyboard test
DoD-008	Approval workflow works (Ctrl+A/R)	Integration test
DoD-009	Error handling for disconnected services	Manual test
DoD-010	All keyboard shortcuts documented in Footer	Visual inspection

Success Criteria

TUI launches and connects to running Orchestrata system
Users can submit intents and receive thread tracking
Real-time message display works correctly
Agent status visible and updating
Command palette provides quick access to actions
Approval workflow enforces human-in-the-loop
Works in standard terminal sizes (80x24 minimum)

Open Items

#	Item	Owner
1	Define exact CSS color scheme	U:Ux
2	Add vim-style keybindings (j/k navigation)	Q2 2026
3	Implement light theme toggle	Q2 2026
4	Add message search functionality	Q3 2026
5	Support terminal resize handling	Q3 2026

Observability

Logging Requirements

Component Logging
- Log all major operations with appropriate log levels
- Include correlation IDs for request tracing
- Log performance metrics for critical operations
- Log errors with full context for debugging

Metrics Requirements

Performance Metrics
- Operation duration histograms
- Request/error rate counters
- Resource utilization gauges
- Business metrics relevant to domain

Tracing Requirements

Distributed Tracing
- Trace propagation across component boundaries
- Span attributes for domain-specific context
- Trace sampling based on operational needs

Alerting Requirements

Critical Alerts
- Error rate spikes
- Performance degradation
- Resource exhaustion
- Business metric anomalies

Dashboard Requirements

Operational Dashboard
- Real-time system health
- Performance trends
- Error analysis
- Resource monitoring

Revision History

Date	Version	Author	Changes
2026-04-03	1.0	Mohamed	Initial specification