Let me get the rest of the tui-renderer file:

Now I have a complete picture. Let me do a deep analysis.

## Deep Analysis: `main.ts` and `tui-renderer.ts`

### Overview of the Problem

The code has evolved organically around three distinct run modes:
1. **Interactive mode** (TUI) - full terminal UI experience
2. **Print/JSON mode** (single-shot) - run once and exit, output text or JSON events
3. **RPC mode** - headless, JSON-in/JSON-out, meant for embedding in other apps

The problem is that these modes share a lot of conceptual logic but it's implemented differently in each, leading to:

### Code Duplication Issues

#### 1. **Agent Event Handling**
- `tui-renderer.ts` has `handleEvent()` that subscribes to agent events, saves messages via `sessionManager.saveMessage()`, and handles session initialization
- `runSingleShotMode()` in `main.ts` has its own subscription loop for JSON output
- `runRpcMode()` in `main.ts` has yet another subscription loop doing the same session saving plus JSON output

All three have nearly identical patterns:
```typescript
agent.subscribe((event) => {
// output/render event
if (event.type === "message_end") {
sessionManager.saveMessage(event.message);
// maybe init session
}
});
```

#### 2. **Auto-compaction Logic**
- `tui-renderer.ts` has `checkAutoCompaction()` called after assistant messages
- `runRpcMode()` has duplicate `checkAutoCompaction()` implementation
- `runSingleShotMode()` doesn't do it (maybe intentional?)

#### 3. **Bash Command Execution**
- `tui-renderer.ts` has `executeBashCommand()` with streaming callbacks, temp file handling
- `main.ts` has `executeRpcBashCommand()` which is nearly identical but without streaming

#### 4. **Slash Command Expansion**
- `runInteractiveMode()` calls `expandSlashCommand()` before `agent.prompt()`
- `runSingleShotMode()` calls `expandSlashCommand()` before `agent.prompt()`
- No slash command handling in RPC mode (intentional, but inconsistent)

### Architecture Issues

#### 1. **TuiRenderer is a God Class**
At ~2400 lines, `TuiRenderer` does too much:
- TUI lifecycle management (init, render, event loop)
- Agent event handling and session management
- All slash command implementations (/export, /copy, /session, /changelog, /branch, /login, /logout, /queue, /theme, /clear, /compact, /autocompact, /debug, /resume)
- Bash command execution (!command)
- Model/thinking/theme selection UI
- Message queuing display
- Hotkey handling (Ctrl+C, Ctrl+P, Ctrl+O, Ctrl+T, Shift+Tab, Esc)

#### 2. **Naming**
- `TuiRenderer` doesn't just render, it's the entire interactive mode coordinator
- Should be something like `InteractiveMode` or `TuiController`

#### 3. **Mode-specific code scattered in main.ts**
- `runInteractiveMode()`, `runSingleShotMode()`, `runRpcMode()` are all in `main.ts`
- Model resolution, system prompt building, session loading also in `main.ts`

---

## Refactoring Plan

### Phase 1: Extract Shared Logic into a Core Module

Create `packages/coding-agent/src/core/agent-session.ts`:

```typescript
/**
* Handles agent lifecycle, session persistence, and event routing.
* Shared between all modes.
*/
export class AgentSession {
constructor(
public agent: Agent,
public sessionManager: SessionManager,
public settingsManager: SettingsManager,
) {}

/** Subscribe to agent events, handle session persistence, emit to callback */
subscribe(onEvent: (event: AgentEvent) => void): () => void;

/** Check and perform auto-compaction if enabled */
checkAutoCompaction(): Promise<void>;

/** Execute manual compaction */
compact(customInstructions?: string, signal?: AbortSignal): Promise<CompactionEntry>;

/** Reset agent and session (for /clear) */
reset(): Promise<void>;

/** Branch session from entry index */
branch(entryIndex: number): void;

/** Switch to different session file */
switchSession(sessionPath: string): Promise<void>;
}
```

This consolidates:
- Session saving on `message_end`
- Session initialization check
- Auto-compaction logic
- Manual compaction (currently duplicated between `handleCompactCommand` and RPC)

### Phase 2: Extract Bash Execution into Shared Module

Create `packages/coding-agent/src/core/bash-executor.ts`:

```typescript
export interface BashExecutionResult {
output: string;
exitCode: number | null;
cancelled: boolean;
truncationResult?: TruncationResult;
fullOutputPath?: string;
}

/**
* Execute a bash command with optional streaming and cancellation.
*/
export function executeBash(
command: string,
options?: {
onChunk?: (chunk: string) => void;
signal?: AbortSignal;
}
): Promise<BashExecutionResult>;
```

This replaces:
- `TuiRenderer.executeBashCommand()`
- `executeRpcBashCommand()` in `main.ts`

### Phase 3: Create Mode-Specific Modules

Rename and split:

```
src/modes/
interactive-mode.ts (renamed from tui-renderer.ts)
print-mode.ts (extracted from runSingleShotMode)
rpc-mode.ts (extracted from runRpcMode)
index.ts (exports)
```

Each mode would:
- Take an `AgentSession` instance
- Implement mode-specific I/O
- Use shared `executeBash()` if needed

#### `print-mode.ts` (simple)
```typescript
export async function runPrintMode(
session: AgentSession,
mode: "text" | "json",
messages: string[],
initialMessage?: string,
initialAttachments?: Attachment[],
): Promise<void>;
```

#### `rpc-mode.ts`
```typescript
export async function runRpcMode(session: AgentSession): Promise<never>;
```

#### `interactive-mode.ts` (the big one)

Split `TuiRenderer` into:

1. **InteractiveMode** - orchestrator class
- Owns `TUI`, `AgentSession`
- Main event loop
- Hotkey routing

2. **CommandHandler** - slash command implementations
- Extract all `/` command handlers into a separate class
- Each command is a method: `handleExport()`, `handleCopy()`, etc.

3. **SelectorManager** - modal selector management
- Handles showing/hiding model, thinking, theme, session, branch selectors
- Currently this is a mess of `showXSelector()` / `hideXSelector()` methods

### Phase 4: Simplify main.ts

After extraction, `main.ts` becomes:

```typescript
export async function main(args: string[]) {
const parsed = parseArgs(args);

if (parsed.help) { printHelp(); return; }
if (parsed.export) { handleExport(parsed); return; }

// Shared setup
const { agent, sessionManager, settingsManager } = await setupAgent(parsed);
const session = new AgentSession(agent, sessionManager, settingsManager);

// Route to mode
if (parsed.mode === "rpc") {
await runRpcMode(session);
} else if (parsed.print || parsed.mode) {
await runPrintMode(session, parsed.mode || "text", parsed.messages, ...);
} else {
await runInteractiveMode(session, { version, scopedModels, fdPath, ... });
}
}
```

### Phase 5: Extract Setup Logic

Create `packages/coding-agent/src/core/setup.ts`:

```typescript
export interface SetupResult {
agent: Agent;
sessionManager: SessionManager;
settingsManager: SettingsManager;
initialMessages: Message[];
modelFallbackMessage: string | null;
}

export async function setupAgent(options: SetupOptions): Promise<SetupResult>;
```

This extracts from `main.ts`:
- Model resolution (CLI args → scope → session → settings → fallback)
- System prompt building
- Session loading (for --continue/--resume)
- Thinking level resolution

---

## Summary of Changes

| Current | Proposed |
|---------|----------|
| `main.ts` (1100+ lines) | `main.ts` (~200 lines) + `core/setup.ts` |
| `tui/tui-renderer.ts` (2400 lines) | `modes/interactive-mode.ts` + `interactive/command-handler.ts` + `interactive/selector-manager.ts` |
| `runSingleShotMode()` in main.ts | `modes/print-mode.ts` |
| `runRpcMode()` in main.ts | `modes/rpc-mode.ts` |
| Duplicated bash execution | `core/bash-executor.ts` |
| Duplicated session/compaction logic | `core/agent-session.ts` |

### Benefits

1. **Clear separation of concerns**: Each mode has its own file
2. **No more duplication**: Session management, bash execution, compaction in one place
3. **Testability**: `AgentSession`, `CommandHandler` can be unit tested independently
4. **Maintainability**: Adding a new mode means adding one file, not touching everything
5. **Naming clarity**: `InteractiveMode` instead of `TuiRenderer`

### Risks

1. **Large refactor**: This is a significant change touching core code paths
2. **TUI coupling**: Some slash commands deeply interact with TUI state (selectors, rendering). May need to keep some coupling.
3. **Testing**: Need to manually test all three modes after refactoring

---

What's your take? Want me to proceed with any specific phase, or adjust the plan?

Good thinking. Let me expand AgentSession to be a comprehensive, TUI-agnostic abstraction that all modes can use.

## Expanded AgentSession Design

```typescript
// src/core/agent-session.ts

import type { Agent, AgentEvent, AgentState, ThinkingLevel } from "@mariozechner/pi-agent-core";
import type { Model, Message } from "@mariozechner/pi-ai";

export interface AgentSessionConfig {
agent: Agent;
sessionManager: SessionManager;
settingsManager: SettingsManager;
scopedModels?: Array<{ model: Model<any>; thinkingLevel: ThinkingLevel }>;
}

export interface BashResult {
output: string;
exitCode: number | null;
cancelled: boolean;
truncated: boolean;
fullOutputPath?: string;
}

export interface CompactionResult {
tokensBefore: number;
tokensAfter: number;
summary: string;
}

export interface ModelCycleResult {
model: Model<any>;
thinkingLevel: ThinkingLevel;
isScoped: boolean; // true if cycling within --models scope
}

export interface PromptOptions {
expandSlashCommands?: boolean; // default true
attachments?: Attachment[];
}

/**
* Core agent session management - shared between all modes.
* Handles agent lifecycle, persistence, model/thinking management.
* TUI-agnostic: returns data, doesn't render anything.
*/
export class AgentSession {
readonly agent: Agent;
readonly sessionManager: SessionManager;
readonly settingsManager: SettingsManager;

private scopedModels: Array<{ model: Model<any>; thinkingLevel: ThinkingLevel }>;
private fileCommands: FileSlashCommand[];
private eventListeners: Array<(event: AgentEvent) => void> = [];
private bashAbortController: AbortController | null = null;
private compactionAbortController: AbortController | null = null;

constructor(config: AgentSessionConfig);

// ─────────────────────────────────────────────────────────────
// State Access
// ─────────────────────────────────────────────────────────────

get state(): AgentState;
get model(): Model<any> | null;
get thinkingLevel(): ThinkingLevel;
get isStreaming(): boolean;
get messages(): Message[];
get sessionFile(): string;
get sessionId(): string;

// ─────────────────────────────────────────────────────────────
// Event Subscription
// ─────────────────────────────────────────────────────────────

/**
* Subscribe to agent events. Handles session persistence internally.
* Returns unsubscribe function.
*/
subscribe(listener: (event: AgentEvent) => void): () => void;

// ─────────────────────────────────────────────────────────────
// Prompting
// ─────────────────────────────────────────────────────────────

/**
* Send a prompt to the agent. Expands slash commands by default.
* Validates model and API key before sending.
* Throws if no model or API key.
*/
prompt(text: string, options?: PromptOptions): Promise<void>;

/**
* Queue a message (when agent is streaming).
*/
queueMessage(text: string): Promise<void>;

/**
* Clear queued messages, return them for restoration.
*/
clearQueue(): string[];

/**
* Abort current operation and wait for idle.
*/
abort(): Promise<void>;

/**
* Reset agent and session (start fresh).
*/
reset(): Promise<void>;

// ─────────────────────────────────────────────────────────────
// Model Management
// ─────────────────────────────────────────────────────────────

/**
* Set model directly. Validates API key.
* Saves to session and settings.
* Throws if no API key available.
*/
setModel(model: Model<any>): Promise<void>;

/**
* Cycle to next model (uses scoped models if available).
* Returns the new model info, or null if only one model available.
*/
cycleModel(): Promise<ModelCycleResult | null>;

/**
* Get all available models (with valid API keys).
*/
getAvailableModels(): Promise<Model<any>[]>;

// ─────────────────────────────────────────────────────────────
// Thinking Level Management
// ─────────────────────────────────────────────────────────────

/**
* Set thinking level. Silently uses "off" if model doesn't support it.
* Saves to session and settings.
*/
setThinkingLevel(level: ThinkingLevel): void;

/**
* Cycle to next thinking level.
* Returns new level, or null if model doesn't support thinking.
*/
cycleThinkingLevel(): ThinkingLevel | null;

/**
* Check if current model supports thinking.
*/
supportsThinking(): boolean;

// ─────────────────────────────────────────────────────────────
// Compaction
// ─────────────────────────────────────────────────────────────

/**
* Manually compact the session context.
* Aborts current agent operation first.
*/
compact(customInstructions?: string): Promise<CompactionResult>;

/**
* Cancel in-progress compaction.
*/
abortCompaction(): void;

/**
* Check if auto-compaction should run, and run it if so.
* Called internally after assistant messages.
* Returns result if compaction occurred, null otherwise.
*/
checkAutoCompaction(): Promise<CompactionResult | null>;

/**
* Toggle auto-compaction setting.
*/
setAutoCompactionEnabled(enabled: boolean): void;

get autoCompactionEnabled(): boolean;

// ─────────────────────────────────────────────────────────────
// Bash Execution (for ! commands)
// ─────────────────────────────────────────────────────────────

/**
* Execute a bash command. Adds result to agent context.
* @param onChunk - Optional streaming callback for output
*/
executeBash(command: string, onChunk?: (chunk: string) => void): Promise<BashResult>;

/**
* Cancel running bash command.
*/
abortBash(): void;

/**
* Check if bash command is running.
*/
get isBashRunning(): boolean;

// ─────────────────────────────────────────────────────────────
// Session Management
// ─────────────────────────────────────────────────────────────

/**
* Switch to a different session file.
* Aborts current operation, loads messages, restores model/thinking.
*/
switchSession(sessionPath: string): Promise<void>;

/**
* Create a branch from a specific entry index.
* Returns the text of the selected user message (for editor pre-fill).
*/
branch(entryIndex: number): string;

/**
* Get all user messages from session (for branch selector).
* Returns entries with index and text.
*/
getUserMessagesForBranching(): Array<{ entryIndex: number; text: string }>;

/**
* Get session stats for /session command.
*/
getSessionStats(): SessionStats;

/**
* Export session to HTML.
*/
exportToHtml(outputPath?: string): string;

// ─────────────────────────────────────────────────────────────
// Clipboard
// ─────────────────────────────────────────────────────────────

/**
* Get last assistant message text for /copy.
* Returns null if no assistant message exists.
*/
getLastAssistantText(): string | null;
}

export interface SessionStats {
sessionFile: string;
sessionId: string;
userMessages: number;
assistantMessages: number;
toolCalls: number;
toolResults: number;
totalMessages: number;
tokens: {
input: number;
output: number;
cacheRead: number;
cacheWrite: number;
total: number;
};
cost: number;
}
```

## How Modes Would Use It

### Print Mode (simplest)

```typescript
// src/modes/print-mode.ts

export async function runPrintMode(
session: AgentSession,
mode: "text" | "json",
messages: string[],
initialMessage?: string,
initialAttachments?: Attachment[],
): Promise<void> {

if (mode === "json") {
// Just pipe events to stdout
session.subscribe((event) => {
console.log(JSON.stringify(event));
});
}

// Send messages
if (initialMessage) {
await session.prompt(initialMessage, { attachments: initialAttachments });
}
for (const message of messages) {
await session.prompt(message);
}

// In text mode, output final response
if (mode === "text") {
const lastText = session.getLastAssistantText();
if (lastText) {
console.log(lastText);
}
}
}
```

### RPC Mode

```typescript
// src/modes/rpc-mode.ts

export async function runRpcMode(session: AgentSession): Promise<never> {
// Pipe all events to stdout as JSON
session.subscribe((event) => {
console.log(JSON.stringify(event));
});

// Listen for JSON input
const rl = readline.createInterface({ input: process.stdin });

rl.on("line", async (line: string) => {
try {
const input = JSON.parse(line);

switch (input.type) {
case "prompt":
await session.prompt(input.message, { attachments: input.attachments });
break;

case "abort":
await session.abort();
break;

case "compact":
const result = await session.compact(input.customInstructions);
console.log(JSON.stringify({ type: "compaction", ...result }));
break;

case "bash":
const bashResult = await session.executeBash(input.command);
console.log(JSON.stringify({ type: "bash_end", ...bashResult }));
break;

case "setModel":
// Could add model switching via RPC
break;

case "setThinking":
session.setThinkingLevel(input.level);
break;
}
} catch (error: any) {
console.log(JSON.stringify({ type: "error", error: error.message }));
}
});

return new Promise(() => {}); // Never resolves
}
```

### Interactive Mode (most complex, but cleaner)

```typescript
// src/modes/interactive-mode.ts

export class InteractiveMode {
private session: AgentSession;
private tui: TUI;
private components: TuiComponents; // Chat container, editor, footer, etc.

constructor(session: AgentSession, options: InteractiveModeOptions) {
this.session = session;
this.tui = new TUI(new ProcessTerminal());
this.components = this.createComponents();

// Subscribe to session events for rendering
session.subscribe((event) => this.handleEvent(event));
}

async run(): Promise<void> {
await this.init();

while (true) {
const input = await this.getEditorInput();
await this.handleInput(input);
}
}

private async handleInput(text: string): Promise<void> {
// Slash commands
if (text === "/thinking") {
this.showThinkingSelector();
return;
}
if (text === "/model") {
this.showModelSelector();
return;
}
if (text === "/compact") {
await this.handleCompact();
return;
}
if (text === "/copy") {
this.handleCopy();
return;
}
// ... other commands

// Bash command
if (text.startsWith("!")) {
await this.handleBash(text.slice(1));
return;
}

// Regular prompt
try {
await this.session.prompt(text);
} catch (error) {
this.showError(error.message);
}
}

// ─── Slash Command Handlers ───

private async handleCompact(): Promise<void> {
this.showLoader("Compacting...");
try {
const result = await this.session.compact();
this.rebuildChat();
this.addCompactionComponent(result);
} catch (error) {
this.showError(`Compaction failed: ${error.message}`);
} finally {
this.hideLoader();
}
}

private handleCopy(): void {
const text = this.session.getLastAssistantText();
if (!text) {
this.showError("No assistant message to copy");
return;
}
copyToClipboard(text);
this.showMessage("Copied to clipboard");
}

private async handleBash(command: string): Promise<void> {
const component = new BashExecutionComponent(command);
this.components.chat.addChild(component);

const result = await this.session.executeBash(command, (chunk) => {
component.appendOutput(chunk);
this.tui.requestRender();
});

component.setComplete(result);
this.tui.requestRender();
}

// ─── Hotkey Handlers ───

private handleEscape(): void {
if (this.session.isStreaming) {
// Restore queued messages to editor
const queued = this.session.clearQueue();
const current = this.components.editor.getText();
this.components.editor.setText([...queued, current].filter(Boolean).join("\n\n"));
this.session.abort();
} else if (this.session.isBashRunning) {
this.session.abortBash();
}
}

private handleShiftTab(): void {
const newLevel = this.session.cycleThinkingLevel();
if (newLevel === null) {
this.showMessage("Model doesn't support thinking");
} else {
this.showMessage(`Thinking: ${newLevel}`);
this.updateEditorBorder();
}
}

private async handleCtrlP(): Promise<void> {
const result = await this.session.cycleModel();
if (result === null) {
this.showMessage("Only one model available");
} else {
const thinkingStr = result.thinkingLevel !== "off" ? ` (thinking: ${result.thinkingLevel})` : "";
this.showMessage(`Switched to ${result.model.name || result.model.id}${thinkingStr}`);
this.updateEditorBorder();
}
}

// ─── Event Handling (just rendering) ───

private handleEvent(event: AgentEvent): void {
// Pure rendering logic - no session management
switch (event.type) {
case "agent_start":
this.showLoader("Working...");
break;
case "message_start":
if (event.message.role === "user") {
this.addUserMessage(event.message);
} else {
this.startStreamingAssistant();
}
break;
case "message_update":
this.updateStreamingAssistant(event.message);
break;
case "message_end":
this.finalizeMessage(event.message);
break;
case "agent_end":
this.hideLoader();
break;
}
this.tui.requestRender();
}
}
```

## What This Achieves

### 1. **Single Source of Truth**
All agent/session logic lives in `AgentSession`:
- No more duplicate `checkAutoCompaction()`
- No more duplicate bash execution
- No more duplicate session saving
- Model/thinking changes always go through one path

### 2. **Clear Separation**
- `AgentSession` = state management, persistence, business logic
- Modes = I/O and presentation

### 3. **Testable**
```typescript
// Can unit test AgentSession without any TUI
const session = new AgentSession({ agent, sessionManager, settingsManager });
await session.setThinkingLevel("high");
expect(session.thinkingLevel).toBe("high");
expect(settingsManager.getDefaultThinkingLevel()).toBe("high");
```

### 4. **Extensible**
Adding a new mode (e.g., LSP server mode, web socket mode) just means:
1. Create `AgentSession`
2. Subscribe to events
3. Implement your I/O layer

### 5. **Reduced main.ts**
Model resolution, thinking restoration, session loading can all be helper functions or part of an `AgentSession.create()` factory:

```typescript
// main.ts
const session = await AgentSession.create({
args: parsed,
settingsManager,
sessionManager,
});

if (mode === "rpc") await runRpcMode(session);
else if (mode === "print") await runPrintMode(session, ...);
else await runInteractiveMode(session, ...);
```

---

## File Structure After Refactor

```
src/
core/
agent-session.ts # The big shared abstraction
bash-executor.ts # Low-level bash execution (used by AgentSession)
setup.ts # Factory/initialization helpers
modes/
interactive/
interactive-mode.ts # Main class
components.ts # TUI component wiring
selectors.ts # Model/thinking/theme selector management
print-mode.ts
rpc-mode.ts
main.ts # Just arg parsing and mode routing (~200 lines)
```

Does this expanded design address your concerns? Should I start implementing `AgentSession`?

Done. On branch `refactor` now. Ready to start implementing `AgentSession`. Want me to begin?

Yes, that's a major benefit. Here's what becomes testable:

### 1. `AgentSession` Unit Tests

```typescript
// No TUI, no terminal, just pure logic
describe("AgentSession", () => {
let mockAgent: MockAgent;
let mockSessionManager: MockSessionManager;
let mockSettingsManager: MockSettingsManager;
let session: AgentSession;

beforeEach(() => {
mockAgent = createMockAgent();
mockSessionManager = createMockSessionManager();
mockSettingsManager = createMockSettingsManager();
session = new AgentSession({
agent: mockAgent,
sessionManager: mockSessionManager,
settingsManager: mockSettingsManager
});
});

describe("thinking level", () => {
it("cycles through levels", () => {
mockAgent.state.model = { reasoning: true };

expect(session.cycleThinkingLevel()).toBe("minimal");
expect(session.cycleThinkingLevel()).toBe("low");
expect(session.cycleThinkingLevel()).toBe("medium");
// ...
});

it("returns null when model doesn't support thinking", () => {
mockAgent.state.model = { reasoning: false };
expect(session.cycleThinkingLevel()).toBeNull();
});

it("persists to session and settings", () => {
session.setThinkingLevel("high");
expect(mockSessionManager.saveThinkingLevelChange).toHaveBeenCalledWith("high");
expect(mockSettingsManager.setDefaultThinkingLevel).toHaveBeenCalledWith("high");
});
});

describe("compaction", () => {
it("auto-compacts when threshold exceeded", async () => {
mockSettingsManager.getCompactionSettings.mockReturnValue({ enabled: true, threshold: 0.8 });
// Setup agent state with high token usage...

const result = await session.checkAutoCompaction();
expect(result).not.toBeNull();
expect(mockSessionManager.saveCompaction).toHaveBeenCalled();
});
});

describe("model cycling", () => {
it("cycles through scoped models with thinking levels", async () => {
const scopedModels = [
{ model: modelA, thinkingLevel: "high" },
{ model: modelB, thinkingLevel: "off" },
];
session = new AgentSession({ ..., scopedModels });

const result = await session.cycleModel();
expect(result.model).toBe(modelB);
expect(result.thinkingLevel).toBe("off");
});
});

describe("bash execution", () => {
it("adds result to agent context", async () => {
const result = await session.executeBash("echo hello");
expect(mockAgent.appendMessage).toHaveBeenCalledWith(
expect.objectContaining({ role: "bashExecution", command: "echo hello" })
);
});

it("can be aborted", async () => {
const promise = session.executeBash("sleep 10");
session.abortBash();
const result = await promise;
expect(result.cancelled).toBe(true);
});
});
});
```

### 2. Integration Tests (with real Agent, mocked API)

```typescript
describe("AgentSession integration", () => {
it("full prompt flow persists correctly", async () => {
const agent = new Agent({ /* real config with mocked transport */ });
const sessionManager = new SessionManager(false, tempSessionFile);
const session = new AgentSession({ agent, sessionManager, ... });

await session.prompt("Hello");

// Verify session file has correct entries
const entries = sessionManager.loadEntries();
expect(entries).toContainEqual(expect.objectContaining({
type: "message",
message: expect.objectContaining({ role: "user" })
}));
});
});
```

### 3. Mode Tests (with mocked AgentSession)

```typescript
describe("RPC mode", () => {
it("handles prompt command", async () => {
const mockSession = createMockAgentSession();
const stdin = new MockReadable();
const stdout = new MockWritable();

runRpcMode(mockSession, { stdin, stdout });

stdin.push(JSON.stringify({ type: "prompt", message: "hello" }));

expect(mockSession.prompt).toHaveBeenCalledWith("hello", expect.anything());
});
});
```

### What's Still Hard to Test

- The actual `Agent` class from `pi-agent-core` (that's its own package, would need its own test strategy with API mocking)
- TUI rendering (visual testing is always tricky)

### What This Unlocks

| Before | After |
|--------|-------|
| Can't test thinking cycling without TUI | Unit test `session.cycleThinkingLevel()` |
| Can't test compaction logic in isolation | Unit test `session.compact()` and `checkAutoCompaction()` |
| Can't test session persistence without running full app | Unit test that `prompt()` calls `sessionManager.saveMessage()` |
| Can't test model cycling without TUI | Unit test `session.cycleModel()` |
| RPC mode untestable | Mock `AgentSession`, test JSON handling |

So yes, `AgentSession` becomes the testable core that all modes share. Want me to start implementing it?

Done. Created `packages/coding-agent/docs/refactor.md` with:

1. **Goals and motivation** for the refactoring
2. **Architecture overview** (current vs target state)
3. **Full AgentSession API** design
4. **20 work packages** in optimal order, each with:
- Files to create/modify
- What to extract from where (with line numbers)
- Implementation details/code snippets
- Verification steps
- Checkboxes for tracking
5. **E2E testing checklist** at the end
6. **Resume instructions** at the top

A new session can:
1. Read the refactor.md file
2. Run `git diff` to see in-progress work
3. Find the first unchecked work package
4. Read the referenced files before making changes
5. Continue implementing

Want me to start on WP1 (bash-executor.ts)?

Good catch. Let me check what types we're dealing with:

You're right. The agent stores `AppMessage[]` which includes both standard `Message` types and custom types like `BashExecutionMessage`. Let me update the refactor.md:

Fixed. `AgentSession.messages` now returns `AppMessage[]` which is the union type that includes standard messages plus custom types like `BashExecutionMessage`.

The declaration merging in `messages.ts` extends `CustomMessages` in pi-agent-core, so `AppMessage` automatically includes `BashExecutionMessage`.

Ready to start implementing WP1?

Good catch. Looking at the API, I have methods for setting things (`setModel()`, `setThinkingLevel()`, `setAutoCompactionEnabled()`), but I'm missing queue mode. Let me also make the API clearer:

Now let me add the queue mode implementation to the relevant work package. Let me find WP6 and add queue mode there or create a small addition:

Updated. The API now clearly shows:

**Read-only getters:**
- `state`, `model`, `thinkingLevel`, `isStreaming`, `messages`, `queueMode`, `autoCompactionEnabled`, `isBashRunning`

**Setters (as methods, with side effects):**
- `setModel()` - validates API key, saves to session + settings
- `setThinkingLevel()` - saves to session + settings
- `setQueueMode()` - saves to settings
- `setAutoCompactionEnabled()` - saves to settings

**Cycle methods (get + set combined):**
- `cycleModel()` - cycles and persists, returns result
- `cycleThinkingLevel()` - cycles and persists, returns new level

The pattern is: getters are cheap reads, setters are methods because they have side effects (persistence, validation).

Ready to start WP1?

Let's start with WP1: Create bash-executor.ts.

First, let me read the existing implementations to extract: