Copilot Tui Harness

Copilot SDK TUI Harness Development Skill

Expert skill for developing the Copilot SDK TUI Harness—a terminal user interface that wraps the GitHub Copilot SDK with an event-driven, plugin-based architecture.

Project Identity

Name: Copilot SDK TUI Harness (copilot-anvil)
Stack: TypeScript + OpenTUI/React + @github/copilot-sdk
Runtime: Bun 1.0+
Architecture: Event-driven with strict UI ↔ SDK decoupling

Core Principles

1. Strict Layer Separation

UI Layer (OpenTUI/React)
    ↕ HarnessEvent / UIAction
Harness (Orchestrator)
    ↕ Internal callbacks
CopilotSessionAdapter
    ↕
@github/copilot-sdk

CRITICAL: The UI layer never imports @github/copilot-sdk directly. All SDK interaction flows through the adapter and harness layers.

2. Event-Driven Communication

• Harness → UI: HarnessEvent types (run.started, assistant.delta, log, etc.)
• UI → Harness: UIAction types (submit.prompt, cancel)
• No direct function calls between layers—everything flows through events

3. Plugin-Ready Architecture

The system is designed for extensibility via plugins that can register:

• Tools (callable by the assistant)
• Commands (user-invokable actions)
• Panes (UI components)
• State slices (additional state management)

Architecture Deep Dive

Directory Structure

src/
├── index.tsx                    # Entry point, bootstraps app
├── copilot/
│   └── CopilotSessionAdapter.ts # ONLY place that imports SDK
├── harness/
│   ├── Harness.ts              # Orchestrator, state manager
│   ├── events.ts               # Event type definitions
│   └── plugins.ts              # Plugin system interfaces
├── ui/
│   ├── App.tsx                 # Main OpenTUI app component
│   ├── theme.ts                # Theme configuration
│   ├── syntaxTheme.ts          # Syntax highlighting theme
│   └── panes/
│       ├── ChatPane.tsx        # Conversation transcript
│       ├── InputBar.tsx        # Prompt input with image support
│       ├── Sidebar.tsx         # Sidebar container
│       ├── TasksPane.tsx       # Task tracking display
│       ├── ContextPane.tsx     # Context information
│       ├── SubagentsPane.tsx   # Subagent monitoring
│       ├── FilesModifiedPane.tsx # Git modified files
│       ├── PlanPane.tsx        # Plan viewer
│       ├── LogsPane.tsx        # System logs
│       ├── StartScreen.tsx     # Welcome screen
│       ├── ModelSelector.tsx   # Model selection modal
│       ├── SessionSwitcher.tsx # Session management
│       ├── SkillsPane.tsx      # Skills browser
│       ├── QuestionModal.tsx   # Interactive questions
│       ├── ConfirmModal.tsx    # Confirmation dialogs
│       ├── CommandModal.tsx    # Ephemeral run display
│       └── DebugOverlay.tsx    # Debug overlay
├── commands/                   # Slash command system
│   └── CommandLoader.ts        # Command registry
└── utils/                      # Shared utilities
    ├── git.ts                  # Git operations
    ├── gitDiff.ts              # Diff utilities
    └── stderrCapture.ts        # Error capture

Key Files and Responsibilities

src/copilot/CopilotSessionAdapter.ts

Purpose: Wraps Copilot SDK, translates SDK events to HarnessEvents

Responsibilities:

• Initialize CopilotClient
• Create/manage CopilotSession (with streaming: true)
• Subscribe to SDK events and emit corresponding HarnessEvents
• Handle prompt submission via session.sendAndWait()
• Must NOT contain UI code or import UI components

Key Pattern:

// SDK event → Harness event translation
session.on('assistant.message_delta', (event) => {
  this.emit({
    type: 'assistant.delta',
    runId: this.currentRunId,
    text: event.content
  });
});

src/harness/Harness.ts

Purpose: Central orchestrator and state manager

Responsibilities:

• Maintain UI transcript (for display only—SDK has true memory)
• Own event bus and lifecycle state
• Handle UIAction dispatch from UI
• Support plugin registration and management
• Coordinate between adapter and UI

Key Patterns:

• State is immutable; updates create new state objects
• Events are emitted synchronously to all listeners
• Plugins hook into lifecycle via onEvent()

src/harness/events.ts

Purpose: Define all event and action types

Core HarnessEvent Types:

UIAction Types:

src/harness/plugins.ts

Purpose: Define plugin system interfaces

Plugin Interface:

interface HarnessPlugin {
  name: string;
  register(ctx: PluginContext): void;
  onEvent?(event: HarnessEvent): void;
}

interface PluginContext {
  tools: ToolRegistry;
  commands: CommandRegistry;
  panes: PaneRegistry;
  state: StateRegistry;
  emit(event: HarnessEvent): void;
}

Key Concept: Plugins receive a context object during registration and can subscribe to all harness events.

src/ui/App.tsx

Purpose: Main OpenTUI application component

Responsibilities:

• Layout definition (chat + logs + input)
• Subscribe to harness events and update local state
• Dispatch UIActions in response to user input
• Render keybind hints and status bar

Key Patterns:

• Use React hooks (useState, useEffect) for local UI state
• Never directly manipulate harness state
• All harness communication via events/actions

src/ui/panes/ChatPane.tsx

Purpose: Display conversation transcript with streaming support

Responsibilities:

• Render user and assistant messages
• Show streaming draft during active run
• Display tool calls inline in transcript
• Handle scrolling and layout
• Support syntax highlighting for code blocks

Key Pattern: Separate committed messages from streaming buffer:

{transcript.map(item => 
  item.kind === "message" ? <Message {...item} /> : <ToolCall {...item} />
)}
{streamingBuffer && <StreamingMessage text={streamingBuffer} />}

src/ui/panes/InputBar.tsx

Purpose: Handle prompt input with image attachment support

Responsibilities:

• Provide text input field
• Dispatch submit.prompt action on Enter
• Disable input during active run
• Handle image attachment (Ctrl+I)
• Show input hints

src/ui/panes/Sidebar.tsx

Purpose: Container for sidebar panels

Responsibilities:

• Layout sidebar panes vertically
• Manage space allocation between panes
• Show/hide panes based on content

src/ui/panes/TasksPane.tsx

Purpose: Display active tasks

Responsibilities:

• Show running, completed, and failed tasks
• Display task timing and status
• Update in real-time via events

src/ui/panes/ContextPane.tsx

Purpose: Display current context information

Responsibilities:

• Show git information (branch, repo, commit)
• Display active tools
• Show token usage and quota

src/ui/panes/SubagentsPane.tsx

Purpose: Monitor subagent execution

Responsibilities:

• Display active and completed subagents
• Show subagent status and timing
• Track subagent failures

src/ui/panes/FilesModifiedPane.tsx

Purpose: Show git modified files

Responsibilities:

• List unstaged and staged changes
• Display file change types (modified, added, deleted)
• Update periodically from git status

src/ui/panes/PlanPane.tsx

Purpose: Display execution plan

Responsibilities:

• Show current plan content
• Support markdown rendering
• Track plan updates

src/ui/panes/ModelSelector.tsx

Purpose: Model selection modal

Responsibilities:

• Display available models
• Allow model switching
• Show current model
• Handle keyboard navigation

src/ui/panes/SessionSwitcher.tsx

Purpose: Session management modal

Responsibilities:

• List all sessions
• Allow session switching
• Support creating new sessions
• Show session metadata

src/ui/panes/SkillsPane.tsx

Purpose: Skills browser

Responsibilities:

• List available skills
• Show skill descriptions
• Allow skill invocation
• Display skill metadata

src/ui/panes/QuestionModal.tsx

Purpose: Interactive user questions

Responsibilities:

• Display agent questions
• Show choices (if provided)
• Support freeform input
• Handle keyboard navigation

src/ui/panes/CommandModal.tsx

Purpose: Ephemeral run display

Responsibilities:

• Show ephemeral run output
• Display status and progress
• Allow closing modal

src/ui/panes/StartScreen.tsx

Purpose: Welcome screen

Responsibilities:

• Show before first interaction
• Display keybind hints
• Provide getting started info

Event Flow Patterns

Typical Prompt Submission Flow

1. User types in InputBar, presses Enter
2. InputBar dispatches UIAction({ type: "submit.prompt", text })
3. Harness.dispatch() receives action
4. Harness emits HarnessEvent({ type: "run.started", runId, createdAt })
5. Harness calls CopilotSessionAdapter.sendPrompt(text)
6. Adapter calls session.sendAndWait({ prompt: text })
7. SDK streams response tokens
8. For each token:
   a. Adapter receives SDK event
   b. Adapter emits HarnessEvent({ type: "assistant.delta", runId, text })
   c. Harness updates streaming buffer
   d. UI re-renders with updated buffer
9. SDK completes
10. Adapter emits HarnessEvent({ type: "assistant.message", runId, message })
11. Harness commits buffer to transcript
12. Harness emits HarnessEvent({ type: "run.finished", runId, createdAt })
13. UI shows completed message, re-enables input

Cancellation Flow

1. User presses Ctrl+C during run
2. UI dispatches UIAction({ type: "cancel" })
3. Harness.dispatch() receives action
4. Harness tells adapter to cancel
5. Adapter stops processing deltas (best-effort)
6. Adapter emits HarnessEvent({ type: "run.cancelled", runId, createdAt })
7. Harness clears streaming buffer, resets to idle
8. UI re-enables input

Development Guidelines

When Adding a New Feature

1. Define Events First

• Add new event types to src/harness/events.ts
• Define clear contracts (what data, when emitted)

2. Implement in Layers

• If SDK-related: extend CopilotSessionAdapter
• If state/logic: extend Harness
• If UI: add/modify components in src/ui/

3. Maintain Separation

• Never import SDK in UI
• Keep adapter simple—just translation
• Put logic in harness, not adapter or UI

When Adding a Plugin

1. Define the plugin object:

const myPlugin: HarnessPlugin = {
  name: "my-feature",
  register(ctx) {
    // Register tools, commands, etc.
    ctx.tools.register("myTool", async (args) => {
      return { result: "..." };
    });
  },
  onEvent(event) {
    // React to lifecycle events
    if (event.type === "run.started") {
      console.log("Run started!");
    }
  }
};

2. Register with harness:

harness.use(myPlugin);

3. Test integration:

• Verify tools are callable by assistant
• Ensure events are received
• Check for conflicts with existing plugins

When Adding a New Pane

1. Create component: src/ui/panes/NewPane.tsx

2. Design state needs:

• What events does it subscribe to?
• What actions does it dispatch?
• What data does it display?

3. Add to layout: Update src/ui/App.tsx

• Import the pane
• Add to the appropriate section (main area, sidebar, or modal)
• Connect to harness state

4. Handle keyboard shortcuts (if needed):

• Add keybind in App.tsx
• Update state to show/hide pane

5. (Future) Register via plugin: Use ctx.panes.register()

Existing panes for reference:

• Main area: ChatPane, InputBar
• Sidebar: TasksPane, ContextPane, SubagentsPane, FilesModifiedPane, PlanPane
• Modals: ModelSelector, SessionSwitcher, SkillsPane, QuestionModal, ConfirmModal, CommandModal
• Overlays: StartScreen, DebugOverlay

When Modifying SDK Integration

ONLY edit src/copilot/CopilotSessionAdapter.ts

Common tasks:

• Change session options (model, streaming, etc.)
• Add new SDK event subscriptions
• Adjust prompt formatting
• Handle new SDK capabilities

Never:

• Import SDK elsewhere
• Put business logic in adapter
• Directly manipulate UI from adapter

Common Patterns

Pattern: Buffered Streaming

// In Harness
private streamingBuffer = "";

onDelta(event: AssistantDeltaEvent) {
  this.streamingBuffer += event.text;
  this.notifyUI();
}

onComplete(event: AssistantMessageEvent) {
  this.transcript.push({
    role: "assistant",
    content: this.streamingBuffer,
    createdAt: new Date()
  });
  this.streamingBuffer = "";
  this.notifyUI();
}

Pattern: Idempotent Event Handling

// In Plugin
onEvent(event: HarnessEvent) {
  if (event.type === "run.started") {
    // Always safe to call, even if called multiple times
    this.resetState();
  }
}

Pattern: Async Tool Registration

// In Plugin
register(ctx: PluginContext) {
  ctx.tools.register("fetchData", async (args) => {
    const data = await fetch(args.url);
    return await data.json();
  });
}

Testing Strategies

Manual Testing

bun run dev

Test cases:

1. Send a prompt, verify streaming display
2. Send multiple prompts, verify session continuity
3. Press Ctrl+C during streaming, verify cancellation
4. Trigger error (bad auth), verify error handling
5. Check logs pane shows lifecycle events

Integration Testing

• Mock CopilotSessionAdapter
• Emit events manually
• Verify harness state updates
• Verify UI renders correctly

Unit Testing

• Test event type definitions
• Test plugin registration logic
• Test utility functions

Debugging

Enable verbose logging

// In Harness or Adapter
this.emit({
  type: "log",
  level: "info",
  message: "Debug: streaming delta",
  data: { text, runId }
});

Check event flow

Add logging to:

1. Harness.dispatch() — see incoming actions
2. Adapter event handlers — see SDK events
3. UI useEffect hooks — see state updates

Inspect state

Use OpenTUI devtools or add temporary UI to display:

• Current harness state
• Active run ID
• Streaming buffer content
• Plugin registry contents

Performance Considerations

Streaming Updates

• Debounce UI updates if delta rate is very high
• Use React memoization for message list
• Limit log pane to last N entries

Event Listeners

• Remove listeners on component unmount
• Use weak references if holding onto event listeners long-term

Plugin Load Time

• Keep register() fast—defer heavy init to first use
• Don't block on network calls during registration

Common Pitfalls

❌ Importing SDK in UI

// WRONG - never do this
import { CopilotClient } from "@github/copilot-sdk";

Fix: Use harness events and actions instead

❌ Putting Logic in Adapter

// WRONG - adapter should not have business logic
adapter.sendPrompt = (text) => {
  if (text.includes("secret")) {
    // Don't do this here!
    throw new Error("Forbidden");
  }
  session.sendAndWait({ prompt: text });
}

Fix: Put validation in harness or plugin

❌ Mutating Harness State from UI

// WRONG - never mutate harness state directly
harness.state.transcript.push(newMessage);

Fix: Dispatch an action, let harness update its own state

❌ Blocking Event Handlers

// WRONG - don't block the event loop
onEvent(event) {
  if (event.type === "run.started") {
    // This blocks!
    const result = syncExpensiveOperation();
  }
}

Fix: Use async/await or defer work to next tick

Scripts and Commands

Dependencies

Production

• @github/copilot-sdk — Core SDK for agent runtime
• @opentui/core — Terminal UI framework (core)
• @opentui/react — React reconciler for OpenTUI
• react — React library
• diff — Diff utility (future use)

Development

• typescript — TypeScript compiler
• @types/node — Node.js type definitions
• @types/react — React type definitions
• @types/diff — Diff type definitions

Configuration Files

• package.json — Project manifest, scripts, dependencies
• tsconfig.json — TypeScript compiler options
• bun.lock — Bun lockfile

Resources

• Full requirements: docs/REQUIREMENTS.md
• Agent docs: AGENTS.md
• Main README: README.md

Quick Reference: File → Responsibility

Troubleshooting

"Copilot not authenticated"

npm install -g @github/copilot-cli
copilot auth login

Streaming not working

• Check streaming: true in session options
• Verify adapter subscribes to assistant.message_delta
• Check harness emits assistant.delta events

Cancellation not working

• SDK may not support true abort
• Current approach: ignore subsequent deltas, reset state
• Session remains valid for next prompt

Plugin not receiving events

• Verify plugin registered: harness.use(plugin)
• Check onEvent method exists and has correct signature
• Add logging to verify events are being emitted

UI not updating

• Check component subscribes to harness events
• Verify state changes trigger re-render
• Use React DevTools to inspect component state

Future Enhancements (Planned)

Architecture supports these additions:

1. Tasks: ✅ Implemented — Task tracking and status display
2. Memory: Memory provider interface, context injection
3. Git & Diffs: ✅ Partially implemented — Diff viewing, modified files; approval gating pending
4. GitHub PR: PR tools, PR resources, PR pane
5. File Browser: File selection pane, context injection
6. Sessions: ✅ Implemented — Multi-session support with persistence
7. Skills: ✅ Implemented — Skills browser and invocation
8. Image Support: ✅ Implemented — Image attachment for vision models
9. Plans: ✅ Implemented — Plan tracking and display
10. Subagents: ✅ Implemented — Subagent monitoring and status

Summary

This skill provides comprehensive knowledge for working on the Copilot SDK TUI Harness project. Key takeaways:

1. Strict separation: UI never imports SDK
2. Event-driven: All communication via events/actions
3. Plugin-ready: Extensibility built into core
4. Three layers: UI → Harness → Adapter → SDK
5. TypeScript + OpenTUI: Strongly typed, terminal-first

When developing, always consider: Which layer does this belong in? What events does it produce/consume? How does it fit into the plugin system?