@axhub/genie 0.1.8 → 0.2.0

package/server/routes/agent.js

@@ -7,13 +7,31 @@ import crypto from 'crypto';
 import { userDb, apiKeysDb, githubTokensDb } from '../database/db.js';
 import { addProjectManually } from '../projects.js';
 import { queryClaudeSDK } from '../claude-sdk.js';
-import { spawnCursor } from '../cursor-cli.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 {
+  NoopWriter as ExternalNoopWriter,
+  ResponseCollector as ExternalResponseCollector,
+  SSEStreamWriter as ExternalSSEStreamWriter,
+  normalizeExternalAgentAbortRequest,
+  normalizeExternalAgentRunRequest,
+  runExternalAgentRequest
+} from '../external-agent/service.js';
 
 const router = express.Router();
 
@@ -632,6 +650,182 @@ class ResponseCollector {
   }
 }
 
+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
 // ===============================
@@ -639,25 +833,26 @@ class ResponseCollector {
 /**
  * POST /api/agent
  *
- * Trigger an AI agent (Claude, Cursor, Codex, or Gemini) to work on a project.
+ * 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 - (Conditionally Required) GitHub repository URL to clone.
+ * @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 - (Conditionally Required) Path to existing project OR destination for cloning.
+ * @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
@@ -667,7 +862,7 @@ class ResponseCollector {
  * @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' | 'cursor' | 'codex' | 'gemini'
+ * @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.
@@ -678,8 +873,7 @@ class ResponseCollector {
  * @param {string} model - (Optional) Model identifier for providers.
  *
  *                        Claude models: 'sonnet' (default), 'opus', 'haiku', 'opusplan', 'sonnet[1m]'
- *                        Cursor models: 'gpt-5' (default), 'gpt-5.2', 'gpt-5.2-high', 'sonnet-4.5', 'opus-4.5',
- *                                       'gemini-3-pro', 'composer-1', 'auto', 'gpt-5.1', 'gpt-5.1-high',
+ *                         *                                       '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'
@@ -733,6 +927,16 @@ class ResponseCollector {
  *                            - 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
  * ================================================================================================
@@ -784,11 +988,14 @@ class ResponseCollector {
  * ================================================================================================
  *
  * Input Validations (400 Bad Request):
- *   - Either githubUrl OR projectPath must be provided (not neither)
  *   - message must be non-empty string
- *   - provider must be 'claude', 'cursor', 'codex', or 'gemini'
- *   - createBranch/createPR requires githubUrl OR projectPath (not neither)
+ *   - 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)
@@ -847,6 +1054,14 @@ class ResponseCollector {
  *   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
  * ================================================================================================
@@ -874,481 +1089,154 @@ class ResponseCollector {
  *     "cleanup": false
  *   }
  */
-router.post('/', validateExternalApiKey, async (req, res) => {
-  const { githubUrl, projectPath, message, provider = 'claude', model, githubToken, branchName, sessionId, openOnly } = req.body;
-
-  // Parse stream and cleanup as booleans (handle string "true"/"false" from curl)
-  const stream = req.body.stream === undefined ? true : (req.body.stream === true || req.body.stream === 'true');
-  const requestedCleanup = req.body.cleanup === undefined ? true : (req.body.cleanup === true || req.body.cleanup === 'true');
-
-  // If branchName is provided, automatically enable createBranch
-  const createBranch = branchName ? true : (req.body.createBranch === true || req.body.createBranch === 'true');
-  const createPR = req.body.createPR === true || req.body.createPR === 'true';
-  const normalizedSessionId = typeof sessionId === 'string' && sessionId.trim() ? sessionId.trim() : null;
-  const normalizedMessage = typeof message === 'string' ? message.trim() : '';
-  const requestedOpenOnly = openOnly === true || openOnly === 'true';
-  const isOpenOnly = requestedOpenOnly || (!normalizedMessage && !!normalizedSessionId);
-  // Keep openOnly requests backward-compatible with existing docs/examples:
-  // cleanup is irrelevant when we only generate session navigation.
-  const cleanup = isOpenOnly ? false : requestedCleanup;
-
-  // Validate inputs
-  if (!['claude', 'cursor', 'codex', 'gemini', 'opencode'].includes(provider)) {
-    return res.status(400).json({ error: 'provider must be "claude", "cursor", "codex", "gemini", or "opencode"' });
-  }
-
-  if (sessionId !== undefined && (typeof sessionId !== 'string' || !sessionId.trim())) {
-    return res.status(400).json({ error: 'sessionId must be a non-empty string when provided' });
-  }
-
-  if (isOpenOnly && !normalizedSessionId) {
-    return res.status(400).json({ error: 'sessionId is required when message is empty or openOnly=true' });
-  }
-
-  if (!isOpenOnly && !normalizedMessage) {
-    return res.status(400).json({ error: 'message is required unless openOnly=true' });
-  }
-
-  if (!isOpenOnly && !githubUrl && !projectPath) {
-    return res.status(400).json({ error: 'Either githubUrl or projectPath is required' });
-  }
-
-  if (isOpenOnly && githubUrl) {
-    return res.status(400).json({ error: 'githubUrl is not supported when openOnly=true' });
-  }
-
-  if (isOpenOnly && (createBranch || createPR)) {
-    return res.status(400).json({ error: 'createBranch and createPR are not supported when openOnly=true' });
-  }
-
-  // Validate GitHub branch/PR creation requirements
-  // Allow branch/PR creation with projectPath as long as it has a GitHub remote
-  if ((createBranch || createPR) && !githubUrl && !projectPath) {
-    return res.status(400).json({ error: 'createBranch and createPR require either githubUrl or projectPath with a GitHub remote' });
+router.post('/', validateExternalAgentApiKey, async (req, res) => {
+  let normalized = null;
+  try {
+    normalized = normalizeExternalAgentRunRequest(req.body);
+  } catch (error) {
+    return res.status(error.statusCode || 400).json({
+      error: error.message
+    });
   }
 
-  if (isOpenOnly) {
-    const { sessionPath, sessionUrl } = buildSessionNavigation(normalizedSessionId);
-    const response = {
-      success: true,
-      openOnly: true,
-      sessionId: normalizedSessionId,
-      sessionPath,
-      sessionUrl,
-      isResumed: true,
-      message: 'Session link generated. No model call triggered.'
-    };
+  try {
+    let transportWriter = null;
 
-    if (stream) {
+    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');
-
-      const writer = new SSEStreamWriter(res);
-      writer.send({
-        type: 'open-only',
-        ...response
-      });
-      writer.end();
-      return;
+      transportWriter = new ExternalSSEStreamWriter(res);
+    } else {
+      transportWriter = new ExternalResponseCollector();
     }
 
-    return res.json(response);
-  }
-
-  let finalProjectPath = null;
-  let writer = null;
-
-  try {
-    // Determine the final project path
-    if (githubUrl) {
-      // Clone repository (to projectPath if provided, otherwise generate path)
-      const tokenToUse = githubToken || githubTokensDb.getActiveGithubToken(req.user.id);
-
-      let targetPath;
-      if (projectPath) {
-        targetPath = projectPath;
-      } else {
-        // Generate a unique path for cloning
-        const repoHash = crypto.createHash('md5').update(githubUrl + Date.now()).digest('hex');
-        targetPath = path.join(os.homedir(), '.claude', 'external-projects', repoHash);
-      }
-
-      finalProjectPath = await cloneGitHubRepo(githubUrl.trim(), tokenToUse, targetPath);
-    } else {
-      // Use existing project path
-      finalProjectPath = path.resolve(projectPath);
+    const response = await runExternalAgentRequest({
+      user: req.user,
+      request: normalized,
+      transportWriter,
+      endTransportOnFinish: normalized.stream
+    });
 
-      // Verify the path exists
-      try {
-        await fs.access(finalProjectPath);
-      } catch (error) {
-        throw new Error(`Project path does not exist: ${finalProjectPath}`);
-      }
+    if (!normalized.stream) {
+      return res.json(response);
     }
+  } catch (error) {
+    console.error('❌ External session error:', error);
 
-    // Register the project (or use existing registration)
-    let project;
-    try {
-      project = await addProjectManually(finalProjectPath);
-      console.log('📦 Project registered:', project);
-    } catch (error) {
-      // If project already exists, that's fine - continue with the existing registration
-      if (error.message && error.message.includes('Project already configured')) {
-        console.log('📦 Using existing project registration for:', finalProjectPath);
-        project = { path: finalProjectPath };
-      } else {
-        throw error;
+    if (normalized?.stream) {
+      if (!res.headersSent) {
+        res.setHeader('Content-Type', 'text/event-stream');
+        res.setHeader('Cache-Control', 'no-cache');
+        res.setHeader('Connection', 'keep-alive');
+        res.setHeader('X-Accel-Buffering', 'no');
       }
-    }
-
-    // Set up writer based on streaming mode
-    const statusMessage = normalizedSessionId
-      ? (githubUrl ? 'Repository cloned and session resumed' : 'Session resumed')
-      : (githubUrl ? 'Repository cloned and session started' : 'Session started');
 
-    if (stream) {
-      // Set up SSE headers for streaming
-      res.setHeader('Content-Type', 'text/event-stream');
-      res.setHeader('Cache-Control', 'no-cache');
-      res.setHeader('Connection', 'keep-alive');
-      res.setHeader('X-Accel-Buffering', 'no'); // Disable nginx buffering
-
-      writer = new SSEStreamWriter(res);
-
-      // Send initial status
+      const writer = new ExternalSSEStreamWriter(res);
       writer.send({
-        type: 'status',
-        message: statusMessage,
-        projectPath: finalProjectPath
+        type: 'error',
+        error: error.message,
+        message: `Failed: ${error.message}`
       });
-    } else {
-      // Non-streaming mode: collect messages
-      writer = new ResponseCollector();
-
-      // Collect initial status message
-      writer.send({
-        type: 'status',
-        message: statusMessage,
-        projectPath: finalProjectPath
-      });
-    }
-
-    // Start the appropriate session
-    if (provider === 'claude') {
-      console.log('🤖 Starting Claude SDK session');
-
-      await queryClaudeSDK(normalizedMessage, {
-        projectPath: finalProjectPath,
-        cwd: finalProjectPath,
-        sessionId: normalizedSessionId,
-        model: model,
-        permissionMode: 'bypassPermissions' // Bypass all permissions for API calls
-      }, writer);
-
-    } else if (provider === 'cursor') {
-      console.log('🖱️ Starting Cursor CLI session');
-
-      await spawnCursor(normalizedMessage, {
-        projectPath: finalProjectPath,
-        cwd: finalProjectPath,
-        sessionId: normalizedSessionId,
-        resume: !!normalizedSessionId,
-        model: model || undefined,
-        skipPermissions: true // Bypass permissions for Cursor
-      }, writer);
-    } else if (provider === 'codex') {
-      console.log('🤖 Starting Codex SDK session');
-
-      await queryCodex(normalizedMessage, {
-        projectPath: finalProjectPath,
-        cwd: finalProjectPath,
-        sessionId: normalizedSessionId,
-        model: model || CODEX_MODELS.DEFAULT,
-        permissionMode: 'bypassPermissions'
-      }, writer);
-    } else if (provider === 'gemini') {
-      console.log('💎 Starting Gemini CLI session');
-
-      await queryGemini(normalizedMessage, {
-        projectPath: finalProjectPath,
-        cwd: finalProjectPath,
-        sessionId: normalizedSessionId,
-        resume: !!normalizedSessionId,
-        model: model || GEMINI_MODELS.DEFAULT,
-        permissionMode: 'bypassPermissions'
-      }, writer);
-    } else if (provider === 'opencode') {
-      console.log('🧠 Starting OpenCode CLI session');
-
-      await queryOpencode(normalizedMessage, {
-        projectPath: finalProjectPath,
-        cwd: finalProjectPath,
-        sessionId: normalizedSessionId,
-        resume: !!normalizedSessionId,
-        model: model || OPENCODE_MODELS.DEFAULT,
-        permissionMode: 'bypassPermissions'
-      }, writer);
-    }
-
-    // Handle GitHub branch and PR creation after successful agent completion
-    let branchInfo = null;
-    let prInfo = null;
-
-    if (createBranch || createPR) {
-      try {
-        console.log('🔄 Starting GitHub branch/PR creation workflow...');
-
-        // Get GitHub token
-        const tokenToUse = githubToken || githubTokensDb.getActiveGithubToken(req.user.id);
-
-        if (!tokenToUse) {
-          throw new Error('GitHub token required for branch/PR creation. Please configure a GitHub token in settings.');
-        }
-
-        // Initialize Octokit
-        const octokit = new Octokit({ auth: tokenToUse });
-
-        // Get GitHub URL - either from parameter or from git remote
-        let repoUrl = githubUrl;
-        if (!repoUrl) {
-          console.log('🔍 Getting GitHub URL from git remote...');
-          try {
-            repoUrl = await getGitRemoteUrl(finalProjectPath);
-            if (!repoUrl.includes('github.com')) {
-              throw new Error('Project does not have a GitHub remote configured');
-            }
-            console.log(`✅ Found GitHub remote: ${repoUrl}`);
-          } catch (error) {
-            throw new Error(`Failed to get GitHub remote URL: ${error.message}`);
-          }
-        }
-
-        // Parse GitHub URL to get owner and repo
-        const { owner, repo } = parseGitHubUrl(repoUrl);
-        console.log(`📦 Repository: ${owner}/${repo}`);
-
-        // Use provided branch name or auto-generate from message
-        const finalBranchName = branchName || autogenerateBranchName(message);
-        if (branchName) {
-          console.log(`🌿 Using provided branch name: ${finalBranchName}`);
-
-          // Validate custom branch name
-          const validation = validateBranchName(finalBranchName);
-          if (!validation.valid) {
-            throw new Error(`Invalid branch name: ${validation.error}`);
-          }
-        } else {
-          console.log(`🌿 Auto-generated branch name: ${finalBranchName}`);
-        }
-
-        if (createBranch) {
-          // Create and checkout the new branch locally
-          console.log('🔄 Creating local branch...');
-          const checkoutProcess = spawn('git', ['checkout', '-b', finalBranchName], {
-            cwd: finalProjectPath,
-            stdio: 'pipe'
-          });
-
-          await new Promise((resolve, reject) => {
-            let stderr = '';
-            checkoutProcess.stderr.on('data', (data) => { stderr += data.toString(); });
-            checkoutProcess.on('close', (code) => {
-              if (code === 0) {
-                console.log(`✅ Created and checked out local branch '${finalBranchName}'`);
-                resolve();
-              } else {
-                // Branch might already exist locally, try to checkout
-                if (stderr.includes('already exists')) {
-                  console.log(`ℹ️ Branch '${finalBranchName}' already exists locally, checking out...`);
-                  const checkoutExisting = spawn('git', ['checkout', finalBranchName], {
-                    cwd: finalProjectPath,
-                    stdio: 'pipe'
-                  });
-                  checkoutExisting.on('close', (checkoutCode) => {
-                    if (checkoutCode === 0) {
-                      console.log(`✅ Checked out existing branch '${finalBranchName}'`);
-                      resolve();
-                    } else {
-                      reject(new Error(`Failed to checkout existing branch: ${stderr}`));
-                    }
-                  });
-                } else {
-                  reject(new Error(`Failed to create branch: ${stderr}`));
-                }
-              }
-            });
-          });
-
-          // Push the branch to remote
-          console.log('🔄 Pushing branch to remote...');
-          const pushProcess = spawn('git', ['push', '-u', 'origin', finalBranchName], {
-            cwd: finalProjectPath,
-            stdio: 'pipe'
-          });
-
-          await new Promise((resolve, reject) => {
-            let stderr = '';
-            let stdout = '';
-            pushProcess.stdout.on('data', (data) => { stdout += data.toString(); });
-            pushProcess.stderr.on('data', (data) => { stderr += data.toString(); });
-            pushProcess.on('close', (code) => {
-              if (code === 0) {
-                console.log(`✅ Pushed branch '${finalBranchName}' to remote`);
-                resolve();
-              } else {
-                // Check if branch exists on remote but has different commits
-                if (stderr.includes('already exists') || stderr.includes('up-to-date')) {
-                  console.log(`ℹ️ Branch '${finalBranchName}' already exists on remote, using existing branch`);
-                  resolve();
-                } else {
-                  reject(new Error(`Failed to push branch: ${stderr}`));
-                }
-              }
-            });
-          });
-
-          branchInfo = {
-            name: finalBranchName,
-            url: `https://github.com/${owner}/${repo}/tree/${finalBranchName}`
-          };
-        }
-
-        if (createPR) {
-          // Get commit messages to generate PR description
-          console.log('🔄 Generating PR title and description...');
-          const commitMessages = await getCommitMessages(finalProjectPath, 5);
-
-          // Use the first commit message as the PR title, or fallback to the agent message
-          const prTitle = commitMessages.length > 0 ? commitMessages[0] : message;
-
-          // Generate PR body from commit messages
-          let prBody = '## Changes\n\n';
-          if (commitMessages.length > 0) {
-            prBody += commitMessages.map(msg => `- ${msg}`).join('\n');
-          } else {
-            prBody += `Agent task: ${message}`;
-          }
-          prBody += '\n\n---\n*This pull request was automatically created by Axhub Genie Agent.*';
-
-          console.log(`📝 PR Title: ${prTitle}`);
-
-          // Create the pull request
-          console.log('🔄 Creating pull request...');
-          prInfo = await createGitHubPR(octokit, owner, repo, finalBranchName, prTitle, prBody, 'main');
-        }
-
-        // Send branch/PR info in response
-        if (stream) {
-          if (branchInfo) {
-            writer.send({
-              type: 'github-branch',
-              branch: branchInfo
-            });
-          }
-          if (prInfo) {
-            writer.send({
-              type: 'github-pr',
-              pullRequest: prInfo
-            });
-          }
-        }
-
-      } catch (error) {
-        console.error('❌ GitHub branch/PR creation error:', error);
-
-        // Send error but don't fail the entire request
-        if (stream) {
-          writer.send({
-            type: 'github-error',
-            error: error.message
-          });
-        }
-        // Store error info for non-streaming response
-        if (!stream) {
-          branchInfo = { error: error.message };
-          prInfo = { error: error.message };
-        }
-      }
-    }
-
-    // Handle response based on streaming mode
-    if (stream) {
-      // Streaming mode: end the SSE stream
       writer.end();
-    } else {
-      // Non-streaming mode: send filtered messages and token summary as JSON
-      const assistantMessages = writer.getAssistantMessages();
-      const tokenSummary = writer.getTotalTokens();
-      const resolvedSessionId = writer.getSessionId() || normalizedSessionId;
-      const { sessionPath, sessionUrl } = buildSessionNavigation(resolvedSessionId);
-
-      const response = {
-        success: true,
-        sessionId: resolvedSessionId,
-        sessionPath,
-        sessionUrl,
-        isResumed: !!normalizedSessionId,
-        messages: assistantMessages,
-        tokens: tokenSummary,
-        projectPath: finalProjectPath
-      };
-
-      // Add branch/PR info if created
-      if (branchInfo) {
-        response.branch = branchInfo;
-      }
-      if (prInfo) {
-        response.pullRequest = prInfo;
-      }
-
-      res.json(response);
+      return;
     }
 
-    // Clean up if requested
-    if (cleanup && githubUrl) {
-      // Only cleanup if we cloned a repo (not for existing project paths)
-      const sessionIdForCleanup = writer.getSessionId();
-      setTimeout(() => {
-        cleanupProject(finalProjectPath, sessionIdForCleanup);
-      }, 5000);
-    }
+    return res.status(error.statusCode || 500).json({
+      success: false,
+      error: error.message
+    });
+  }
+});
 
+/**
+ * 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) => {
+  let normalized = null;
+  try {
+    normalized = normalizeExternalAgentAbortRequest(req.body);
   } catch (error) {
-    console.error('❌ External session error:', error);
-
-    // Clean up on error
-    if (finalProjectPath && cleanup && githubUrl) {
-      const sessionIdForCleanup = writer ? writer.getSessionId() : null;
-      cleanupProject(finalProjectPath, sessionIdForCleanup);
-    }
+    return res.status(error.statusCode || 400).json({
+      success: false,
+      error: error.message
+    });
+  }
 
-    if (stream) {
-      // For streaming, send error event and stop
-      if (!writer) {
-        // Set up SSE headers if not already done
-        res.setHeader('Content-Type', 'text/event-stream');
-        res.setHeader('Cache-Control', 'no-cache');
-        res.setHeader('Connection', 'keep-alive');
-        res.setHeader('X-Accel-Buffering', 'no');
-        writer = new SSEStreamWriter(res);
-      }
+  try {
+    const writer = new SessionEventMirrorWriter(new ExternalNoopWriter(), normalized.provider);
+    const { success } = await abortAgentSessionWithWriter({
+      provider: normalized.provider,
+      sessionId: normalized.sessionId,
+      writer
+    });
 
-      if (!res.writableEnded) {
-        writer.send({
-          type: 'error',
-          error: error.message,
-          message: `Failed: ${error.message}`
-        });
-        writer.end();
-      }
-    } else if (!res.headersSent) {
-      res.status(500).json({
+    if (!success) {
+      return res.json({
         success: false,
-        error: error.message
+        aborted: false,
+        sessionId: normalized.sessionId,
+        provider: normalized.provider,
+        error: 'Active session not found'
       });
     }
+
+    return res.json({
+      success: true,
+      aborted: true,
+      sessionId: normalized.sessionId,
+      provider: normalized.provider,
+      message: 'Session aborted'
+    });
+  } catch (error) {
+    console.error('❌ External abort session error:', error);
+    return res.status(500).json({
+      success: false,
+      error: error.message
+    });
   }
 });