@axhub/genie 0.2.1 → 0.2.3

package/server/routes/agent.js

@@ -1,33 +1,12 @@
 import express from 'express';
-import { spawn } from 'child_process';
-import path from 'path';
-import os from 'os';
-import { promises as fs } from 'fs';
-import crypto from 'crypto';
-import { userDb, apiKeysDb, githubTokensDb } from '../database/db.js';
-import { addProjectManually } from '../projects.js';
-import { queryClaudeSDK } from '../claude-sdk.js';
-import { queryCodex } from '../openai-codex.js';
-import { queryGemini } from '../gemini-cli.js';
-import { queryOpencode } from '../opencode-cli.js';
+
 import { SessionEventMirrorWriter } from '../session-core/runtimeWriter.js';
-import { ABORTABLE_AGENT_PROVIDERS, abortAgentSessionWithWriter, isAbortableAgentProvider } from '../session-core/abortSession.js';
-import {
-  buildAgentCallbackPayload,
-  createAgentCallbackEventId,
-  createEmptyTokenSummary,
-  normalizeAgentCallbackConfig,
-  scheduleAgentCallbackDelivery,
-  shouldDeliverAgentCallback
-} from '../utils/agentCallback.js';
-import { Octokit } from '@octokit/rest';
-import { CODEX_MODELS, GEMINI_MODELS, OPENCODE_MODELS } from '../../shared/modelConstants.js';
-import { IS_PLATFORM } from '../constants/config.js';
-import { validateExternalApiKey as validateExternalAgentApiKey } from '../external-agent/auth.js';
+import { abortAgentSessionWithWriter } from '../session-core/abortSession.js';
+import { validateExternalApiKey } from '../external-agent/auth.js';
 import {
-  NoopWriter as ExternalNoopWriter,
-  ResponseCollector as ExternalResponseCollector,
-  SSEStreamWriter as ExternalSSEStreamWriter,
+  NoopWriter,
+  ResponseCollector,
+  SSEStreamWriter,
   normalizeExternalAgentAbortRequest,
   normalizeExternalAgentRunRequest,
   runExternalAgentRequest
@@ -35,1061 +14,7 @@ import {
 
 const router = express.Router();
 
-function buildSessionNavigation(sessionId) {
-  const normalizedSessionId = typeof sessionId === 'string' && sessionId.trim() ? sessionId.trim() : null;
-  const sessionPath = normalizedSessionId ? `/session/${normalizedSessionId}` : null;
-  const frontendPort = process.env.VITE_PORT || '5173';
-  const configuredFrontendUrl = typeof process.env.FRONTEND_URL === 'string'
-    ? process.env.FRONTEND_URL.trim().replace(/\/+$/, '')
-    : '';
-  const frontendBaseUrl = configuredFrontendUrl || `http://localhost:${frontendPort}`;
-  const sessionUrl = normalizedSessionId ? `${frontendBaseUrl}${sessionPath}` : null;
-
-  return {
-    sessionPath,
-    sessionUrl
-  };
-}
-
-/**
- * Middleware to authenticate agent API requests.
- *
- * Supports three authentication modes:
- * 1. Platform mode (IS_PLATFORM=true): For managed/hosted deployments where
- *    authentication is handled by an external proxy. Requests are trusted and
- *    the default user context is used.
- *
- * 2. Optional API key mode (default): For local MVP integration, API key is optional.
- *    If provided, it is validated against the local database.
- *
- * 3. Required API key mode: Set AGENT_API_KEY_REQUIRED=true to force API key auth.
- */
-const validateExternalApiKey = (req, res, next) => {
-  const requireApiKey = process.env.AGENT_API_KEY_REQUIRED === 'true';
-
-  // Platform mode: Authentication is handled externally (e.g., by a proxy layer).
-  // Trust the request and use the default user context.
-  if (IS_PLATFORM) {
-    try {
-      const user = userDb.getFirstUser();
-      if (!user) {
-        return res.status(500).json({ error: 'Platform mode: No user found in database' });
-      }
-      req.user = user;
-      return next();
-    } catch (error) {
-      console.error('Platform mode error:', error);
-      return res.status(500).json({ error: 'Platform mode: Failed to fetch user' });
-    }
-  }
-
-  // Self-hosted mode: Validate API key from header or query parameter
-  const apiKey = req.headers['x-api-key'] || req.query.apiKey;
-
-  if (!apiKey) {
-    if (requireApiKey) {
-      return res.status(401).json({ error: 'API key required' });
-    }
-
-    try {
-      const user = userDb.getFirstUser();
-      if (user) {
-        req.user = user;
-      }
-    } catch (error) {
-      console.warn('Optional API key mode: failed to fetch default user:', error.message);
-    }
-
-    return next();
-  }
-
-  const user = apiKeysDb.validateApiKey(apiKey);
-
-  if (!user) {
-    return res.status(401).json({ error: 'Invalid or inactive API key' });
-  }
-
-  req.user = user;
-  next();
-};
-
-/**
- * Get the remote URL of a git repository
- * @param {string} repoPath - Path to the git repository
- * @returns {Promise<string>} - Remote URL of the repository
- */
-async function getGitRemoteUrl(repoPath) {
-  return new Promise((resolve, reject) => {
-    const gitProcess = spawn('git', ['config', '--get', 'remote.origin.url'], {
-      cwd: repoPath,
-      stdio: ['pipe', 'pipe', 'pipe']
-    });
-
-    let stdout = '';
-    let stderr = '';
-
-    gitProcess.stdout.on('data', (data) => {
-      stdout += data.toString();
-    });
-
-    gitProcess.stderr.on('data', (data) => {
-      stderr += data.toString();
-    });
-
-    gitProcess.on('close', (code) => {
-      if (code === 0) {
-        resolve(stdout.trim());
-      } else {
-        reject(new Error(`Failed to get git remote: ${stderr}`));
-      }
-    });
-
-    gitProcess.on('error', (error) => {
-      reject(new Error(`Failed to execute git: ${error.message}`));
-    });
-  });
-}
-
-/**
- * Normalize GitHub URLs for comparison
- * @param {string} url - GitHub URL
- * @returns {string} - Normalized URL
- */
-function normalizeGitHubUrl(url) {
-  // Remove .git suffix
-  let normalized = url.replace(/\.git$/, '');
-  // Convert SSH to HTTPS format for comparison
-  normalized = normalized.replace(/^git@github\.com:/, 'https://github.com/');
-  // Remove trailing slash
-  normalized = normalized.replace(/\/$/, '');
-  return normalized.toLowerCase();
-}
-
-/**
- * Parse GitHub URL to extract owner and repo
- * @param {string} url - GitHub URL (HTTPS or SSH)
- * @returns {{owner: string, repo: string}} - Parsed owner and repo
- */
-function parseGitHubUrl(url) {
-  // Handle HTTPS URLs: https://github.com/owner/repo or https://github.com/owner/repo.git
-  // Handle SSH URLs: git@github.com:owner/repo or git@github.com:owner/repo.git
-  const match = url.match(/github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?$/);
-  if (!match) {
-    throw new Error('Invalid GitHub URL format');
-  }
-  return {
-    owner: match[1],
-    repo: match[2].replace(/\.git$/, '')
-  };
-}
-
-/**
- * Auto-generate a branch name from a message
- * @param {string} message - The agent message
- * @returns {string} - Generated branch name
- */
-function autogenerateBranchName(message) {
-  // Convert to lowercase, replace spaces/special chars with hyphens
-  let branchName = message
-    .toLowerCase()
-    .replace(/[^a-z0-9\s-]/g, '') // Remove special characters
-    .replace(/\s+/g, '-') // Replace spaces with hyphens
-    .replace(/-+/g, '-') // Replace multiple hyphens with single
-    .replace(/^-|-$/g, ''); // Remove leading/trailing hyphens
-
-  // Ensure non-empty fallback
-  if (!branchName) {
-    branchName = 'task';
-  }
-
-  // Generate timestamp suffix (last 6 chars of base36 timestamp)
-  const timestamp = Date.now().toString(36).slice(-6);
-  const suffix = `-${timestamp}`;
-
-  // Limit length to ensure total length including suffix fits within 50 characters
-  const maxBaseLength = 50 - suffix.length;
-  if (branchName.length > maxBaseLength) {
-    branchName = branchName.substring(0, maxBaseLength);
-  }
-
-  // Remove any trailing hyphen after truncation and ensure no leading hyphen
-  branchName = branchName.replace(/-$/, '').replace(/^-+/, '');
-
-  // If still empty or starts with hyphen after cleanup, use fallback
-  if (!branchName || branchName.startsWith('-')) {
-    branchName = 'task';
-  }
-
-  // Combine base name with timestamp suffix
-  branchName = `${branchName}${suffix}`;
-
-  // Final validation: ensure it matches safe pattern
-  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(branchName)) {
-    // Fallback to deterministic safe name
-    return `branch-${timestamp}`;
-  }
-
-  return branchName;
-}
-
-/**
- * Validate a Git branch name
- * @param {string} branchName - Branch name to validate
- * @returns {{valid: boolean, error?: string}} - Validation result
- */
-function validateBranchName(branchName) {
-  if (!branchName || branchName.trim() === '') {
-    return { valid: false, error: 'Branch name cannot be empty' };
-  }
-
-  // Git branch name rules
-  const invalidPatterns = [
-    { pattern: /^\./, message: 'Branch name cannot start with a dot' },
-    { pattern: /\.$/, message: 'Branch name cannot end with a dot' },
-    { pattern: /\.\./, message: 'Branch name cannot contain consecutive dots (..)' },
-    { pattern: /\s/, message: 'Branch name cannot contain spaces' },
-    { pattern: /[~^:?*\[\\]/, message: 'Branch name cannot contain special characters: ~ ^ : ? * [ \\' },
-    { pattern: /@{/, message: 'Branch name cannot contain @{' },
-    { pattern: /\/$/, message: 'Branch name cannot end with a slash' },
-    { pattern: /^\//, message: 'Branch name cannot start with a slash' },
-    { pattern: /\/\//, message: 'Branch name cannot contain consecutive slashes' },
-    { pattern: /\.lock$/, message: 'Branch name cannot end with .lock' }
-  ];
-
-  for (const { pattern, message } of invalidPatterns) {
-    if (pattern.test(branchName)) {
-      return { valid: false, error: message };
-    }
-  }
-
-  // Check for ASCII control characters
-  if (/[\x00-\x1F\x7F]/.test(branchName)) {
-    return { valid: false, error: 'Branch name cannot contain control characters' };
-  }
-
-  return { valid: true };
-}
-
-/**
- * Get recent commit messages from a repository
- * @param {string} projectPath - Path to the git repository
- * @param {number} limit - Number of commits to retrieve (default: 5)
- * @returns {Promise<string[]>} - Array of commit messages
- */
-async function getCommitMessages(projectPath, limit = 5) {
-  return new Promise((resolve, reject) => {
-    const gitProcess = spawn('git', ['log', `-${limit}`, '--pretty=format:%s'], {
-      cwd: projectPath,
-      stdio: ['pipe', 'pipe', 'pipe']
-    });
-
-    let stdout = '';
-    let stderr = '';
-
-    gitProcess.stdout.on('data', (data) => {
-      stdout += data.toString();
-    });
-
-    gitProcess.stderr.on('data', (data) => {
-      stderr += data.toString();
-    });
-
-    gitProcess.on('close', (code) => {
-      if (code === 0) {
-        const messages = stdout.trim().split('\n').filter(msg => msg.length > 0);
-        resolve(messages);
-      } else {
-        reject(new Error(`Failed to get commit messages: ${stderr}`));
-      }
-    });
-
-    gitProcess.on('error', (error) => {
-      reject(new Error(`Failed to execute git: ${error.message}`));
-    });
-  });
-}
-
-/**
- * Create a new branch on GitHub using the API
- * @param {Octokit} octokit - Octokit instance
- * @param {string} owner - Repository owner
- * @param {string} repo - Repository name
- * @param {string} branchName - Name of the new branch
- * @param {string} baseBranch - Base branch to branch from (default: 'main')
- * @returns {Promise<void>}
- */
-async function createGitHubBranch(octokit, owner, repo, branchName, baseBranch = 'main') {
-  try {
-    // Get the SHA of the base branch
-    const { data: ref } = await octokit.git.getRef({
-      owner,
-      repo,
-      ref: `heads/${baseBranch}`
-    });
-
-    const baseSha = ref.object.sha;
-
-    // Create the new branch
-    await octokit.git.createRef({
-      owner,
-      repo,
-      ref: `refs/heads/${branchName}`,
-      sha: baseSha
-    });
-
-    console.log(`✅ Created branch '${branchName}' on GitHub`);
-  } catch (error) {
-    if (error.status === 422 && error.message.includes('Reference already exists')) {
-      console.log(`ℹ️ Branch '${branchName}' already exists on GitHub`);
-    } else {
-      throw error;
-    }
-  }
-}
-
-/**
- * Create a pull request on GitHub
- * @param {Octokit} octokit - Octokit instance
- * @param {string} owner - Repository owner
- * @param {string} repo - Repository name
- * @param {string} branchName - Head branch name
- * @param {string} title - PR title
- * @param {string} body - PR body/description
- * @param {string} baseBranch - Base branch (default: 'main')
- * @returns {Promise<{number: number, url: string}>} - PR number and URL
- */
-async function createGitHubPR(octokit, owner, repo, branchName, title, body, baseBranch = 'main') {
-  const { data: pr } = await octokit.pulls.create({
-    owner,
-    repo,
-    title,
-    head: branchName,
-    base: baseBranch,
-    body
-  });
-
-  console.log(`✅ Created pull request #${pr.number}: ${pr.html_url}`);
-
-  return {
-    number: pr.number,
-    url: pr.html_url
-  };
-}
-
-/**
- * Clone a GitHub repository to a directory
- * @param {string} githubUrl - GitHub repository URL
- * @param {string} githubToken - Optional GitHub token for private repos
- * @param {string} projectPath - Path for cloning the repository
- * @returns {Promise<string>} - Path to the cloned repository
- */
-async function cloneGitHubRepo(githubUrl, githubToken = null, projectPath) {
-  return new Promise(async (resolve, reject) => {
-    try {
-      // Validate GitHub URL
-      if (!githubUrl || !githubUrl.includes('github.com')) {
-        throw new Error('Invalid GitHub URL');
-      }
-
-      const cloneDir = path.resolve(projectPath);
-
-      // Check if directory already exists
-      try {
-        await fs.access(cloneDir);
-        // Directory exists - check if it's a git repo with the same URL
-        try {
-          const existingUrl = await getGitRemoteUrl(cloneDir);
-          const normalizedExisting = normalizeGitHubUrl(existingUrl);
-          const normalizedRequested = normalizeGitHubUrl(githubUrl);
-
-          if (normalizedExisting === normalizedRequested) {
-            console.log('✅ Repository already exists at path with correct URL');
-            return resolve(cloneDir);
-          } else {
-            throw new Error(`Directory ${cloneDir} already exists with a different repository (${existingUrl}). Expected: ${githubUrl}`);
-          }
-        } catch (gitError) {
-          throw new Error(`Directory ${cloneDir} already exists but is not a valid git repository or git command failed`);
-        }
-      } catch (accessError) {
-        // Directory doesn't exist - proceed with clone
-      }
-
-      // Ensure parent directory exists
-      await fs.mkdir(path.dirname(cloneDir), { recursive: true });
-
-      // Prepare the git clone URL with authentication if token is provided
-      let cloneUrl = githubUrl;
-      if (githubToken) {
-        // Convert HTTPS URL to authenticated URL
-        // Example: https://github.com/user/repo -> https://token@github.com/user/repo
-        cloneUrl = githubUrl.replace('https://github.com', `https://${githubToken}@github.com`);
-      }
-
-      console.log('🔄 Cloning repository:', githubUrl);
-      console.log('📁 Destination:', cloneDir);
-
-      // Execute git clone
-      const gitProcess = spawn('git', ['clone', '--depth', '1', cloneUrl, cloneDir], {
-        stdio: ['pipe', 'pipe', 'pipe']
-      });
-
-      let stdout = '';
-      let stderr = '';
-
-      gitProcess.stdout.on('data', (data) => {
-        stdout += data.toString();
-      });
-
-      gitProcess.stderr.on('data', (data) => {
-        stderr += data.toString();
-        console.log('Git stderr:', data.toString());
-      });
-
-      gitProcess.on('close', (code) => {
-        if (code === 0) {
-          console.log('✅ Repository cloned successfully');
-          resolve(cloneDir);
-        } else {
-          console.error('❌ Git clone failed:', stderr);
-          reject(new Error(`Git clone failed: ${stderr}`));
-        }
-      });
-
-      gitProcess.on('error', (error) => {
-        reject(new Error(`Failed to execute git: ${error.message}`));
-      });
-    } catch (error) {
-      reject(error);
-    }
-  });
-}
-
-/**
- * Clean up a temporary project directory and its Claude session
- * @param {string} projectPath - Path to the project directory
- * @param {string} sessionId - Session ID to clean up
- */
-async function cleanupProject(projectPath, sessionId = null) {
-  try {
-    // Only clean up projects in the external-projects directory
-    if (!projectPath.includes('.claude/external-projects')) {
-      console.warn('⚠️ Refusing to clean up non-external project:', projectPath);
-      return;
-    }
-
-    console.log('🧹 Cleaning up project:', projectPath);
-    await fs.rm(projectPath, { recursive: true, force: true });
-    console.log('✅ Project cleaned up');
-
-    // Also clean up the Claude session directory if sessionId provided
-    if (sessionId) {
-      try {
-        const sessionPath = path.join(os.homedir(), '.claude', 'sessions', sessionId);
-        console.log('🧹 Cleaning up session directory:', sessionPath);
-        await fs.rm(sessionPath, { recursive: true, force: true });
-        console.log('✅ Session directory cleaned up');
-      } catch (error) {
-        console.error('⚠️ Failed to clean up session directory:', error.message);
-      }
-    }
-  } catch (error) {
-    console.error('❌ Failed to clean up project:', error);
-  }
-}
-
-/**
- * SSE Stream Writer - Adapts SDK/CLI output to Server-Sent Events
- */
-class SSEStreamWriter {
-  constructor(res) {
-    this.res = res;
-    this.sessionId = null;
-    this.isSSEStreamWriter = true;  // Marker for transport detection
-  }
-
-  send(data) {
-    if (this.res.writableEnded) {
-      return;
-    }
-
-    // Format as SSE - providers send raw objects, we stringify
-    this.res.write(`data: ${JSON.stringify(data)}\n\n`);
-  }
-
-  end() {
-    if (!this.res.writableEnded) {
-      this.res.write('data: {"type":"done"}\n\n');
-      this.res.end();
-    }
-  }
-
-  setSessionId(sessionId) {
-    this.sessionId = sessionId;
-  }
-
-  getSessionId() {
-    return this.sessionId;
-  }
-}
-
-/**
- * Non-streaming response collector
- */
-class ResponseCollector {
-  constructor() {
-    this.messages = [];
-    this.sessionId = null;
-  }
-
-  send(data) {
-    // Store ALL messages for now - we'll filter when returning
-    this.messages.push(data);
-
-    // Extract sessionId if present
-    if (typeof data === 'string') {
-      try {
-        const parsed = JSON.parse(data);
-        if (parsed.sessionId) {
-          this.sessionId = parsed.sessionId;
-        }
-      } catch (e) {
-        // Not JSON, ignore
-      }
-    } else if (data && data.sessionId) {
-      this.sessionId = data.sessionId;
-    }
-  }
-
-  end() {
-    // Do nothing - we'll collect all messages
-  }
-
-  setSessionId(sessionId) {
-    this.sessionId = sessionId;
-  }
-
-  getSessionId() {
-    return this.sessionId;
-  }
-
-  getMessages() {
-    return this.messages;
-  }
-
-  /**
-   * Get filtered assistant messages only
-   */
-  getAssistantMessages() {
-    const assistantMessages = [];
-
-    for (const msg of this.messages) {
-      // Skip initial status message
-      if (msg && msg.type === 'status') {
-        continue;
-      }
-
-      // Handle JSON strings
-      if (typeof msg === 'string') {
-        try {
-          const parsed = JSON.parse(msg);
-          // Only include claude-response messages with assistant type
-          if (parsed.type === 'claude-response' && parsed.data && parsed.data.type === 'assistant') {
-            assistantMessages.push(parsed.data);
-          }
-        } catch (e) {
-          // Not JSON, skip
-        }
-      }
-    }
-
-    return assistantMessages;
-  }
-
-  /**
-   * Calculate total tokens from all messages
-   */
-  getTotalTokens() {
-    let totalInput = 0;
-    let totalOutput = 0;
-    let totalCacheRead = 0;
-    let totalCacheCreation = 0;
-
-    for (const msg of this.messages) {
-      let data = msg;
-
-      // Parse if string
-      if (typeof msg === 'string') {
-        try {
-          data = JSON.parse(msg);
-        } catch (e) {
-          continue;
-        }
-      }
-
-      // Extract usage from claude-response messages
-      if (data && data.type === 'claude-response' && data.data) {
-        const msgData = data.data;
-        if (msgData.message && msgData.message.usage) {
-          const usage = msgData.message.usage;
-          totalInput += usage.input_tokens || 0;
-          totalOutput += usage.output_tokens || 0;
-          totalCacheRead += usage.cache_read_input_tokens || 0;
-          totalCacheCreation += usage.cache_creation_input_tokens || 0;
-        }
-      }
-    }
-
-    return {
-      inputTokens: totalInput,
-      outputTokens: totalOutput,
-      cacheReadTokens: totalCacheRead,
-      cacheCreationTokens: totalCacheCreation,
-      totalTokens: totalInput + totalOutput + totalCacheRead + totalCacheCreation
-    };
-  }
-}
-
-class AgentSessionAbortedError extends Error {
-  constructor(message = 'Session aborted') {
-    super(message);
-    this.name = 'AgentSessionAbortedError';
-  }
-}
-
-function extractTerminalErrorMessage(payload) {
-  if (!payload || typeof payload !== 'object') {
-    return null;
-  }
-
-  if (typeof payload.error === 'string' && payload.error.trim()) {
-    return payload.error.trim();
-  }
-
-  if (payload.error && typeof payload.error.message === 'string' && payload.error.message.trim()) {
-    return payload.error.message.trim();
-  }
-
-  const nestedData = payload.data;
-  if (nestedData && typeof nestedData === 'object') {
-    if (typeof nestedData.error === 'string' && nestedData.error.trim()) {
-      return nestedData.error.trim();
-    }
-
-    if (nestedData.error && typeof nestedData.error.message === 'string' && nestedData.error.message.trim()) {
-      return nestedData.error.message.trim();
-    }
-
-    if (typeof nestedData.message === 'string' && nestedData.message.trim()) {
-      return nestedData.message.trim();
-    }
-  }
-
-  return null;
-}
-
-class CallbackCaptureWriter {
-  constructor() {
-    this.sessionId = null;
-    this.assistantMessages = [];
-    this.tokenSummary = createEmptyTokenSummary();
-    this.terminalState = null;
-    this.terminalErrorMessage = null;
-  }
-
-  send(payload) {
-    if (!payload || typeof payload !== 'object') {
-      return;
-    }
-
-    if (typeof payload.sessionId === 'string' && payload.sessionId.trim()) {
-      this.sessionId = payload.sessionId.trim();
-    }
-
-    if (payload.type === 'session-created' && typeof payload.sessionId === 'string' && payload.sessionId.trim()) {
-      this.sessionId = payload.sessionId.trim();
-    }
-
-    if (payload.type === 'token-budget' && payload.data && typeof payload.data === 'object') {
-      this.tokenSummary = {
-        inputTokens: Number(payload.data.inputTokens) || 0,
-        outputTokens: Number(payload.data.outputTokens) || 0,
-        cacheReadTokens: Number(payload.data.cacheReadTokens) || 0,
-        cacheCreationTokens: Number(payload.data.cacheCreationTokens) || 0,
-        totalTokens: Number(payload.data.totalTokens) || 0
-      };
-    }
-
-    if (payload.type === 'claude-response' && payload.data?.type === 'assistant') {
-      this.assistantMessages.push(payload.data);
-    }
-
-    if (
-      payload.type === 'codex-response' &&
-      payload.data?.type === 'item_done' &&
-      payload.data?.itemType === 'agent_message' &&
-      typeof payload.data?.content === 'string' &&
-      payload.data.content.trim()
-    ) {
-      this.assistantMessages.push({
-        type: 'assistant',
-        message: {
-          role: 'assistant',
-          content: payload.data.content
-        }
-      });
-    }
-
-    if (payload.type === 'session-aborted') {
-      this.terminalState = 'aborted';
-      this.terminalErrorMessage = 'Session aborted';
-      return;
-    }
-
-    if (payload.type === 'claude-complete' || payload.type === 'codex-complete') {
-      this.terminalState = 'completed';
-      this.terminalErrorMessage = null;
-      return;
-    }
-
-    if (
-      payload.type === 'claude-error' ||
-      payload.type === 'codex-error' ||
-      payload.type === 'error' ||
-      (payload.type === 'codex-response' && payload.data?.type === 'turn_failed')
-    ) {
-      this.terminalState = 'errored';
-      this.terminalErrorMessage = extractTerminalErrorMessage(payload) || this.terminalErrorMessage || 'Agent session failed';
-    }
-  }
-
-  end() {}
-
-  setSessionId(sessionId) {
-    if (typeof sessionId === 'string' && sessionId.trim()) {
-      this.sessionId = sessionId.trim();
-    }
-  }
-
-  getSessionId() {
-    return this.sessionId;
-  }
-
-  getAssistantMessages() {
-    return this.assistantMessages;
-  }
-
-  getTotalTokens() {
-    return this.tokenSummary;
-  }
-
-  getTerminalState() {
-    return this.terminalState;
-  }
-
-  getTerminalErrorMessage() {
-    return this.terminalErrorMessage;
-  }
-}
-
-class TeeWriter {
-  constructor(primaryWriter, secondaryWriter) {
-    this.primaryWriter = primaryWriter;
-    this.secondaryWriter = secondaryWriter;
-    this.isSSEStreamWriter = !!primaryWriter?.isSSEStreamWriter;
-    this.isWebSocketWriter = !!primaryWriter?.isWebSocketWriter;
-  }
-
-  send(payload) {
-    this.primaryWriter?.send?.(payload);
-    this.secondaryWriter?.send?.(payload);
-  }
-
-  end() {
-    this.primaryWriter?.end?.();
-    this.secondaryWriter?.end?.();
-  }
-
-  setSessionId(sessionId) {
-    this.primaryWriter?.setSessionId?.(sessionId);
-    this.secondaryWriter?.setSessionId?.(sessionId);
-  }
-
-  getSessionId() {
-    return this.primaryWriter?.getSessionId?.() || this.secondaryWriter?.getSessionId?.() || null;
-  }
-}
-
-class NoopWriter {
-  send() {}
-
-  end() {}
-}
-
-// ===============================
-// External API Endpoint
-// ===============================
-
-/**
- * POST /api/agent
- *
- * Trigger an AI agent (Claude, Codex, Gemini, or OpenCode) to work on a project.
- * Supports automatic GitHub branch and pull request creation after successful completion.
- *
- * ================================================================================================
- * REQUEST BODY PARAMETERS
- * ================================================================================================
- *
- * @param {string} githubUrl - (Optional) GitHub repository URL to clone.
- *                             Supported formats:
- *                             - HTTPS: https://github.com/owner/repo
- *                             - HTTPS with .git: https://github.com/owner/repo.git
- *                             - SSH: git@github.com:owner/repo
- *                             - SSH with .git: git@github.com:owner/repo.git
- *
- * @param {string} projectPath - (Optional) Path to existing project OR destination for cloning.
- *                               Behavior depends on usage:
- *                               - If used alone: Must point to existing project directory
- *                               - If used with githubUrl: Target location for cloning
- *                               - If omitted with githubUrl: Auto-generates temporary path in ~/.claude/external-projects/
- *                               - If omitted without githubUrl: Falls back to service default working directory, then process cwd
- *
- * @param {string} message - (Required) Task description for the AI agent. Used as:
- *                          - Instructions for the agent
- *                          - Source for auto-generated branch names (if createBranch=true and no branchName)
- *                          - Fallback for PR title if no commits are made
- *
- * @param {string} sessionId - (Optional) Existing session ID to resume.
- *                            If provided, the request continues that session instead of creating a new one.
- *
- * @param {string} provider - (Optional) AI provider to use. Options: 'claude' | 'codex' | 'gemini' | 'opencode'
- *                           Default: 'claude'
- *
- * @param {boolean} stream - (Optional) Enable Server-Sent Events (SSE) streaming for real-time updates.
- *                          Default: true
- *                          - true: Returns text/event-stream with incremental updates
- *                          - false: Returns complete JSON response after completion
- *
- * @param {string} model - (Optional) Model identifier for providers.
- *
- *                        Claude models: 'sonnet' (default), 'opus', 'haiku', 'opusplan', 'sonnet[1m]'
- *                         *                                       'gemini-3-pro', 'composer-1', 'auto', 'gpt-5.1', 'gpt-5.1-high',
- *                                       'gpt-5.1-codex', 'gpt-5.1-codex-high', 'gpt-5.1-codex-max',
- *                                       'gpt-5.1-codex-max-high', 'opus-4.1', 'grok', and thinking variants
- *                        Codex models: 'gpt-5.2' (default), 'gpt-5.1-codex-max', 'o3', 'o4-mini'
- *                        Gemini models: 'gemini-2.5-pro' (default), 'gemini-2.5-flash', 'gemini-2.5-flash-lite'
- *
- * @param {boolean} cleanup - (Optional) Auto-cleanup project directory after completion.
- *                           Default: true
- *                           Behavior:
- *                           - Only applies when cloning via githubUrl (not for existing projectPath)
- *                           - Deletes cloned repository after 5 seconds
- *                           - Also deletes associated Claude session directory
- *                           - Remote branch and PR remain on GitHub if created
- *
- * @param {string} githubToken - (Optional) GitHub Personal Access Token for authentication.
- *                              Overrides stored token from user settings.
- *                              Required for:
- *                              - Private repositories
- *                              - Branch/PR creation features
- *                              Token must have 'repo' scope for full functionality.
- *
- * @param {string} branchName - (Optional) Custom name for the Git branch.
- *                             If provided, createBranch is automatically set to true.
- *                             Validation rules (errors returned if violated):
- *                             - Cannot be empty or whitespace only
- *                             - Cannot start or end with dot (.)
- *                             - Cannot contain consecutive dots (..)
- *                             - Cannot contain spaces
- *                             - Cannot contain special characters: ~ ^ : ? * [ \
- *                             - Cannot contain @{
- *                             - Cannot start or end with forward slash (/)
- *                             - Cannot contain consecutive slashes (//)
- *                             - Cannot end with .lock
- *                             - Cannot contain ASCII control characters
- *                             Examples: 'feature/user-auth', 'bugfix/login-error', 'refactor/db-optimization'
- *
- * @param {boolean} createBranch - (Optional) Create a new Git branch after successful agent completion.
- *                                Default: false (or true if branchName is provided)
- *                                Behavior:
- *                                - Creates branch locally and pushes to remote
- *                                - If branch exists locally: Checks out existing branch (no error)
- *                                - If branch exists on remote: Uses existing branch (no error)
- *                                - Branch name: Custom (if branchName provided) or auto-generated from message
- *                                - Requires either githubUrl OR projectPath with GitHub remote
- *
- * @param {boolean} createPR - (Optional) Create a GitHub Pull Request after successful completion.
- *                            Default: false
- *                            Behavior:
- *                            - PR title: First commit message (or fallback to message parameter)
- *                            - PR description: Auto-generated from all commit messages
- *                            - Base branch: Always 'main' (currently hardcoded)
- *                            - If PR already exists: GitHub returns error with details
- *                            - Requires either githubUrl OR projectPath with GitHub remote
- *
- * @param {object} callback - (Optional) Terminal webhook configuration for external systems.
- *                           Behavior:
- *                           - Sent once when the run ends as completed, errored, or aborted
- *                           - Delivery is asynchronous and never blocks the main API response
- *                           - Not supported with openOnly=true
- *                           Fields:
- *                           - url: Required HTTP/HTTPS target URL
- *                           - events: Optional subset of ["completed", "errored", "aborted"]
- *                           - secret: Optional shared secret for HMAC signing
- *
- * ================================================================================================
- * PATH HANDLING BEHAVIOR
- * ================================================================================================
- *
- * Scenario 1: Only githubUrl provided
- *   Input:  { githubUrl: "https://github.com/owner/repo" }
- *   Action: Clones to auto-generated temporary path: ~/.claude/external-projects/<hash>/
- *   Cleanup: Yes (if cleanup=true)
- *
- * Scenario 2: Only projectPath provided
- *   Input:  { projectPath: "/home/user/my-project" }
- *   Action: Uses existing project at specified path
- *   Validation: Path must exist and be accessible
- *   Cleanup: No (never cleanup existing projects)
- *
- * Scenario 3: Both githubUrl and projectPath provided
- *   Input:  { githubUrl: "https://github.com/owner/repo", projectPath: "/custom/path" }
- *   Action: Clones githubUrl to projectPath location
- *   Validation:
- *     - If projectPath exists with git repo:
- *       - Compares remote URL with githubUrl
- *       - If URLs match: Reuses existing repo
- *       - If URLs differ: Returns error
- *   Cleanup: Yes (if cleanup=true)
- *
- * ================================================================================================
- * GITHUB BRANCH/PR CREATION REQUIREMENTS
- * ================================================================================================
- *
- * For createBranch or createPR to work, one of the following must be true:
- *
- * Option A: githubUrl provided
- *   - Repository URL directly specified
- *   - Works with both cloning and existing paths
- *
- * Option B: projectPath with GitHub remote
- *   - Project must be a Git repository
- *   - Must have 'origin' remote configured
- *   - Remote URL must point to github.com
- *   - System auto-detects GitHub URL via: git remote get-url origin
- *
- * Additional Requirements:
- *   - Valid GitHub token (from settings or githubToken parameter)
- *   - Token must have 'repo' scope for private repos
- *   - Project must have commits (for PR creation)
- *
- * ================================================================================================
- * VALIDATION & ERROR HANDLING
- * ================================================================================================
- *
- * Input Validations (400 Bad Request):
- *   - message must be non-empty string
- *   - provider must be 'claude', 'codex', 'gemini', or 'opencode'
- *   - createBranch/createPR requires a resolvable working directory or githubUrl
- *   - branchName must pass Git naming rules (if provided)
- *   - callback must be an object when provided
- *   - callback.url must be a valid HTTP/HTTPS URL
- *   - callback.events can only include completed/errored/aborted
- *   - callback is not supported when openOnly=true
- *
- * Runtime Validations (500 Internal Server Error or specific error in response):
- *   - projectPath must exist (if used alone)
- *   - GitHub URL format must be valid
- *   - Git remote URL must include github.com (for projectPath + branch/PR)
- *   - GitHub token must be available (for private repos and branch/PR)
- *   - Directory conflicts handled (existing path with different repo)
- *
- * Branch Name Validation Errors (returned in response, not HTTP error):
- *   Invalid names return: { branch: { error: "Invalid branch name: <reason>" } }
- *   Examples:
- *   - "my branch" → "Branch name cannot contain spaces"
- *   - ".feature" → "Branch name cannot start with a dot"
- *   - "feature.lock" → "Branch name cannot end with .lock"
- *
- * ================================================================================================
- * RESPONSE FORMATS
- * ================================================================================================
- *
- * Streaming Response (stream=true):
- *   Content-Type: text/event-stream
- *   Events:
- *     - { type: "status", message: "...", projectPath: "..." }
- *     - { type: "claude-response", data: {...} }
- *     - { type: "github-branch", branch: { name: "...", url: "..." } }
- *     - { type: "github-pr", pullRequest: { number: 42, url: "..." } }
- *     - { type: "github-error", error: "..." }
- *     - { type: "done" }
- *
- * Non-Streaming Response (stream=false):
- *   Content-Type: application/json
- *   {
- *     success: true,
- *     sessionId: "session-123",
- *     messages: [...],        // Assistant messages only (filtered)
- *     tokens: {
- *       inputTokens: 150,
- *       outputTokens: 50,
- *       cacheReadTokens: 0,
- *       cacheCreationTokens: 0,
- *       totalTokens: 200
- *     },
- *     projectPath: "/path/to/project",
- *     branch: {               // Only if createBranch=true
- *       name: "feature/xyz",
- *       url: "https://github.com/owner/repo/tree/feature/xyz"
- *     } | { error: "..." },
- *     pullRequest: {          // Only if createPR=true
- *       number: 42,
- *       url: "https://github.com/owner/repo/pull/42"
- *     } | { error: "..." }
- *   }
- *
- * Error Response:
- *   HTTP Status: 400, 401, 500
- *   Content-Type: application/json
- *   { success: false, error: "Error description" }
- *
- * Callback Delivery:
- *   Content-Type: application/json
- *   Headers:
- *     - X-Agent-Event
- *     - X-Agent-Event-Id
- *     - X-Agent-Delivery-Attempt
- *     - X-Agent-Signature (only when callback.secret is provided)
- *
- * ================================================================================================
- * EXAMPLES
- * ================================================================================================
- *
- * Example 1: Clone and process with auto-cleanup
- *   POST /api/agent
- *   { "githubUrl": "https://github.com/user/repo", "message": "Fix bug" }
- *
- * Example 2: Use existing project with custom branch and PR
- *   POST /api/agent
- *   {
- *     "projectPath": "/home/user/project",
- *     "message": "Add feature",
- *     "branchName": "feature/new-feature",
- *     "createPR": true
- *   }
- *
- * Example 3: Clone to specific path with auto-generated branch
- *   POST /api/agent
- *   {
- *     "githubUrl": "https://github.com/user/repo",
- *     "projectPath": "/tmp/work",
- *     "message": "Refactor code",
- *     "createBranch": true,
- *     "cleanup": false
- *   }
- */
-router.post('/', validateExternalAgentApiKey, async (req, res) => {
+router.post('/', validateExternalApiKey, async (req, res) => {
   let normalized = null;
   try {
     normalized = normalizeExternalAgentRunRequest(req.body);
@@ -1100,16 +25,15 @@ router.post('/', validateExternalAgentApiKey, async (req, res) => {
   }
 
   try {
-    let transportWriter = null;
+    const transportWriter = normalized.stream
+      ? new SSEStreamWriter(res)
+      : new ResponseCollector();
 
     if (normalized.stream) {
       res.setHeader('Content-Type', 'text/event-stream');
       res.setHeader('Cache-Control', 'no-cache');
       res.setHeader('Connection', 'keep-alive');
       res.setHeader('X-Accel-Buffering', 'no');
-      transportWriter = new ExternalSSEStreamWriter(res);
-    } else {
-      transportWriter = new ExternalResponseCollector();
     }
 
     const response = await runExternalAgentRequest({
@@ -1123,7 +47,7 @@ router.post('/', validateExternalAgentApiKey, async (req, res) => {
       return res.json(response);
     }
   } catch (error) {
-    console.error('❌ External session error:', error);
+    console.error('External session error:', error);
 
     if (normalized?.stream) {
       if (!res.headersSent) {
@@ -1133,7 +57,7 @@ router.post('/', validateExternalAgentApiKey, async (req, res) => {
         res.setHeader('X-Accel-Buffering', 'no');
       }
 
-      const writer = new ExternalSSEStreamWriter(res);
+      const writer = new SSEStreamWriter(res);
       writer.send({
         type: 'error',
         error: error.message,
@@ -1150,52 +74,7 @@ router.post('/', validateExternalAgentApiKey, async (req, res) => {
   }
 });
 
-/**
- * POST /api/agent/abort
- *
- * Interrupt an active AI agent session.
- *
- * ================================================================================================
- * REQUEST BODY PARAMETERS
- * ================================================================================================
- *
- * @param {string} sessionId - (Required) Session ID to interrupt.
- * @param {string} provider - (Optional) AI provider for the active session.
- *                           Options: 'claude' | 'codex' | 'gemini' | 'opencode'
- *                           Default: 'claude'
- *
- * ================================================================================================
- * VALIDATION & ERROR HANDLING
- * ================================================================================================
- *
- * Input Validations (400 Bad Request):
- *   - sessionId must be a non-empty string
- *   - provider must be 'claude', 'codex', 'gemini', or 'opencode' when provided
- *
- * Success Response (200 OK):
- *   {
- *     success: true,
- *     aborted: true,
- *     sessionId: "session-123",
- *     provider: "claude",
- *     message: "Session aborted"
- *   }
- *
- * Not Found Response (200 OK):
- *   {
- *     success: false,
- *     aborted: false,
- *     sessionId: "session-123",
- *     provider: "claude",
- *     error: "Active session not found"
- *   }
- *
- * Error Response:
- *   HTTP Status: 400, 401, 500
- *   Content-Type: application/json
- *   { success: false, error: "Error description" }
- */
-router.post('/abort', validateExternalAgentApiKey, async (req, res) => {
+router.post('/abort', validateExternalApiKey, async (req, res) => {
   let normalized = null;
   try {
     normalized = normalizeExternalAgentAbortRequest(req.body);
@@ -1207,7 +86,7 @@ router.post('/abort', validateExternalAgentApiKey, async (req, res) => {
   }
 
   try {
-    const writer = new SessionEventMirrorWriter(new ExternalNoopWriter(), normalized.provider);
+    const writer = new SessionEventMirrorWriter(new NoopWriter(), normalized.provider);
     const { success } = await abortAgentSessionWithWriter({
       provider: normalized.provider,
       sessionId: normalized.sessionId,
@@ -1232,7 +111,7 @@ router.post('/abort', validateExternalAgentApiKey, async (req, res) => {
       message: 'Session aborted'
     });
   } catch (error) {
-    console.error('❌ External abort session error:', error);
+    console.error('External abort session error:', error);
     return res.status(500).json({
       success: false,
       error: error.message