Implement TUI circuit breaker and safe logging for interrupt handling

- Add circuit breaker to stop terminal updates on error (e.g. SIGINT)
- Refactor Logger to use file-based error logging instead of stderr
- Add comprehensive tests for logger stability and plugin fault tolerance

Author: fpr1m3

AGENTS.md

@@ -10,7 +10,7 @@ PAI is the core Personal AI Infrastructure agent implemented by this plugin. It
 ## Capabilities
 - **Context Management:** Automatically loads the `core/SKILL.md` file from the user's skills directory at the start of each session, injecting it as the core system prompt.
 - **Event Logging:** Logs all session events, tool calls, and message updates to the `.opencode/history/raw-outputs` directory for audit and debugging purposes.
-- **Session Status:** Updates the terminal tab title to reflect the current activity or thought process of the agent.
+- **Fault-Tolerant Status Updates:** Updates the terminal tab title to reflect activity. Includes a "circuit breaker" to automatically disable updates if interrupts (e.g., ESC key) are detected, preventing TUI corruption.
 - **Session Summarization:** Generates a summary of the session in `.opencode/history/sessions` when a session ends (if configured).
 
 ## Configuration
@@ -22,8 +22,8 @@ The agent's behavior contains some configurable elements via environment variabl
 | `USER_NAME` | Environment variable to override the user's name (default: "Engineer"). |
 
 ## Codebase Structure
-- `src/index.ts`: The plugin entry point. It defines the `PAIPlugin` export and sets up hooks for event listening (`event`, `chat.message`, `tool.execute.after`).
+- `src/index.ts`: The plugin entry point. Handles hooks and implements the TUI circuit breaker logic.
 - `src/lib/context-loader.ts`: Responsible for reading and processing the `core/SKILL.md` file, injecting environment variables.
-- `src/lib/logger.ts`: Implements a buffering JSONL logger. It captures events and tool outputs, writing them to `raw-outputs/{session-id}.jsonl`. It handles file creation and flushing.
-- `src/lib/notifier.ts`: A utility to send POST requests to a local voice server (defaulting to `localhost:8888`). It fails gracefully (silently ignores errors) if the server is not unreachable.
+- `src/lib/logger.ts`: Implements a buffering JSONL logger. Captures events safely, redirecting internal errors to `system-logs` to protect the TUI.
+- `src/lib/notifier.ts`: A utility to send POST requests to a local voice server (defaulting to `localhost:8888`).
 - `src/lib/paths.ts`: Contains helper functions for resolving paths (`getHistoryDir`, `getRawOutputsDir`, `getSkillsDir`) and handling environment variable expansion in paths.

README.md

@@ -33,7 +33,7 @@ Once installed and registered, the plugin will automatically:
 
 *   Load the `CORE/SKILL.md` file as core context at the start of each session.
 *   Log all events and tool calls to the `.opencode/history/raw-outputs` directory.
-*   Update the terminal tab title with the current session status.
+*   Update the terminal tab title with the current session status (failsafe mode included).
 *   Create a session summary in `.opencode/history/sessions` when a session ends.
 
 ---

src/index.ts

@@ -35,6 +35,7 @@ function shouldSkipEvent(event: Event, sessionId: string | null): boolean {
 export const PAIPlugin: Plugin = async ({ project, directory, $, client }) => {
   let logger: Logger | null = null;
   let currentSessionId: string | null = null;
+  let titleUpdatesDisabled: boolean = false;
 
   const hooks: Hooks = {
     event: async ({ event }: { event: Event }) => {
@@ -63,7 +64,7 @@ export const PAIPlugin: Plugin = async ({ project, directory, $, client }) => {
       if (event.type === 'message.part.updated') {
           const part = event.properties.part;
 
-          if (part.type === 'text') {
+          if (part.type === 'text' && !titleUpdatesDisabled) {
               const prompt = part.text;
               let tabTitle = 'Processing request...';
 
@@ -86,7 +87,10 @@ export const PAIPlugin: Plugin = async ({ project, directory, $, client }) => {
               try {
                 process.stderr.write(`\x1b]0;${titleWithEmoji}\x07`);
               } catch (e) {
-                  // ignore
+                  titleUpdatesDisabled = true;
+                  if (logger) {
+                    logger.logError('Terminal Title Update', e);
+                  }
               }
           }
       }

src/lib/logger.ts

@@ -135,6 +135,33 @@ export class Logger {
       this.writeEvent('ToolUse', payload, toolName, toolInput);
   }
 
+  public logError(context: string, error: any): void {
+    try {
+      const now = new Date();
+      const pstDate = new Date(now.toLocaleString('en-US', { timeZone: process.env.TIME_ZONE || 'America/Los_Angeles' }));
+      const year = pstDate.getFullYear();
+      const month = String(pstDate.getMonth() + 1).padStart(2, '0');
+      const day = String(pstDate.getDate()).padStart(2, '0');
+
+      const filename = `${year}-${month}-${day}_errors.log`;
+      const filePath = getHistoryFilePath('system-logs', filename);
+      const dir = dirname(filePath);
+
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+
+      const timestamp = this.getPSTTimestamp();
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const stack = error instanceof Error ? error.stack : '';
+      
+      const logEntry = `[${timestamp}] [${context}] ${errorMessage}\n${stack}\n-------------------\n`;
+      appendFileSync(filePath, logEntry, 'utf-8');
+    } catch (e) {
+      // Intentionally silent - TUI protection
+    }
+  }
+
   // Core write method
   private writeEvent(eventType: string, payload: any, toolName?: string, toolInput?: any): void {
       const sessionId = this.sessionId;
@@ -164,7 +191,7 @@ export class Logger {
         const jsonLine = JSON.stringify(hookEvent) + '\n';
         appendFileSync(eventsFile, jsonLine, 'utf-8');
       } catch (error) {
-        console.error('Event capture error:', error);
+        this.logError('EventCapture', error);
       }
   }
 

tests/logger.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect, mock, beforeEach, afterEach } from 'bun:test';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const TEMP_DIR = '/tmp/pai-test-' + Date.now();
+
+// Calculate absolute path to the module we want to mock
+const pathsModulePath = path.resolve(__dirname, '../src/lib/paths.ts');
+
+mock.module(pathsModulePath, () => {
+  return {
+    PAI_DIR: TEMP_DIR,
+    getHistoryFilePath: (subdir: string, filename: string) => path.join(TEMP_DIR, 'history', subdir, filename),
+    join: path.join,
+    dirname: path.dirname,
+    // Add other exports if needed
+    HOOKS_DIR: path.join(TEMP_DIR, 'hooks'),
+    SKILLS_DIR: path.join(TEMP_DIR, 'skills'),
+    AGENTS_DIR: path.join(TEMP_DIR, 'agents'),
+    HISTORY_DIR: path.join(TEMP_DIR, 'history'),
+    COMMANDS_DIR: path.join(TEMP_DIR, 'commands'),
+  };
+});
+
+describe('Logger Integration', () => {
+  let Logger: any;
+  let logger: any;
+
+  beforeEach(async () => {
+    // Clean up temp dir
+    if (fs.existsSync(TEMP_DIR)) {
+      fs.rmSync(TEMP_DIR, { recursive: true, force: true });
+    }
+    fs.mkdirSync(TEMP_DIR, { recursive: true });
+
+    // Dynamic import to get the Logger class
+    // We append a query string to force reload if possible? Bun doesn't support that for FS modules easily.
+    // But since we are mocking the dependency, if Logger is re-evaluated or if it uses the mocked module, it should work.
+    // Ideally we'd use a fresh Logger class.
+    
+    // We might need to use the absolute path for logger too to ensure we are importing the same thing
+    const loggerPath = path.resolve(__dirname, '../src/lib/logger.ts');
+    const module = await import(loggerPath);
+    Logger = module.Logger;
+    
+    logger = new Logger('test-session', '/tmp/project');
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(TEMP_DIR)) {
+      fs.rmSync(TEMP_DIR, { recursive: true, force: true });
+    }
+    mock.restore();
+  });
+
+  it('should log events to a file', async () => {
+    const event = {
+      type: 'test.event',
+      properties: { foo: 'bar' }
+    };
+
+    logger.logOpenCodeEvent(event);
+
+    const rawOutputsDir = path.join(TEMP_DIR, 'history', 'raw-outputs');
+    expect(fs.existsSync(rawOutputsDir)).toBe(true);
+    
+    const files = fs.readdirSync(rawOutputsDir);
+    expect(files.length).toBe(1);
+    expect(files[0].endsWith('.jsonl')).toBe(true);
+    
+    const content = fs.readFileSync(path.join(rawOutputsDir, files[0]), 'utf-8');
+    expect(content).toContain('test.event');
+    expect(content).toContain('"foo":"bar"');
+  });
+
+  it('should handle errors by logging to error file', async () => {
+    // 1. Setup
+    logger.logOpenCodeEvent({ type: 'init' });
+    const rawOutputsDir = path.join(TEMP_DIR, 'history', 'raw-outputs');
+    const files = fs.readdirSync(rawOutputsDir);
+    const eventsFile = path.join(rawOutputsDir, files[0]);
+    
+    // Delete file and replace with directory to force EISDIR
+    fs.unlinkSync(eventsFile);
+    fs.mkdirSync(eventsFile); 
+    
+    // 2. Trigger event logging
+    const event = {
+      type: 'test.event.fail',
+      properties: { foo: 'baz' }
+    };
+
+    expect(() => logger.logOpenCodeEvent(event)).not.toThrow();
+
+    // 3. Verify error log
+    const systemLogsDir = path.join(TEMP_DIR, 'history', 'system-logs');
+    expect(fs.existsSync(systemLogsDir)).toBe(true);
+    
+    const logFiles = fs.readdirSync(systemLogsDir);
+    expect(logFiles.length).toBeGreaterThan(0);
+    expect(logFiles[0].endsWith('_errors.log')).toBe(true);
+    
+    const errorContent = fs.readFileSync(path.join(systemLogsDir, logFiles[0]), 'utf-8');
+    expect(errorContent).toContain('EventCapture');
+    expect(errorContent).toContain('EISDIR');
+  });
+});

tests/plugin.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect, mock, beforeEach, afterEach } from 'bun:test';
+import { PAIPlugin } from '../src/index';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Use a temp dir to avoid polluting real history
+const TEMP_DIR = '/tmp/pai-test-plugin-' + Date.now();
+
+// Mock paths to redirect logs
+const pathsModulePath = path.resolve(__dirname, '../src/lib/paths.ts');
+mock.module(pathsModulePath, () => {
+  return {
+    PAI_DIR: TEMP_DIR,
+    getHistoryFilePath: (subdir: string, filename: string) => path.join(TEMP_DIR, 'history', subdir, filename),
+    join: path.join,
+    dirname: path.dirname,
+  };
+});
+
+describe('PAIPlugin Circuit Breaker', () => {
+  let originalStderrWrite: any;
+  let stderrWriteMock: any;
+
+  beforeEach(() => {
+    // Setup temp dir
+    if (fs.existsSync(TEMP_DIR)) {
+      fs.rmSync(TEMP_DIR, { recursive: true, force: true });
+    }
+    fs.mkdirSync(TEMP_DIR, { recursive: true });
+
+    originalStderrWrite = process.stderr.write;
+    stderrWriteMock = mock(() => {});
+    process.stderr.write = stderrWriteMock;
+  });
+
+  afterEach(() => {
+    process.stderr.write = originalStderrWrite;
+    if (fs.existsSync(TEMP_DIR)) {
+      fs.rmSync(TEMP_DIR, { recursive: true, force: true });
+    }
+    mock.restore();
+  });
+
+  it('should stop updating title after an error', async () => {
+    const plugin = await PAIPlugin({
+      project: { worktree: '/tmp' },
+      directory: '/tmp',
+      $: {},
+      client: {}
+    } as any);
+
+    const eventHook = plugin.event;
+    if (!eventHook) throw new Error('Event hook not found');
+
+    // 1. First call - succeeds
+    await eventHook({
+      event: {
+        type: 'message.part.updated',
+        properties: {
+          part: { type: 'text', text: 'hello world' }
+        }
+      } as any
+    });
+
+    expect(stderrWriteMock).toHaveBeenCalledTimes(1);
+
+    // 2. Second call - make it fail
+    stderrWriteMock.mockImplementationOnce(() => {
+      throw new Error('EPIPE');
+    });
+
+    await eventHook({
+      event: {
+        type: 'message.part.updated',
+        properties: {
+          part: { type: 'text', text: 'generating code' }
+        }
+      } as any
+    });
+
+    // Should have been called (and failed)
+    expect(stderrWriteMock).toHaveBeenCalledTimes(2);
+
+    // 3. Third call - should be skipped due to circuit breaker
+    stderrWriteMock.mockClear();
+    
+    await eventHook({
+      event: {
+        type: 'message.part.updated',
+        properties: {
+          part: { type: 'text', text: 'still generating' }
+        }
+      } as any
+    });
+
+    // Should NOT have been called
+    expect(stderrWriteMock).toHaveBeenCalledTimes(0);
+  });
+});