@axhub/genie 0.1.7 → 0.1.9

package/server/routes/agent.js

@@ -7,10 +7,19 @@ 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';
@@ -21,7 +30,11 @@ 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 sessionUrl = normalizedSessionId ? `http://localhost:${frontendPort}${sessionPath}` : null;
+  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,
@@ -628,6 +641,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
 // ===============================
@@ -635,7 +824,7 @@ 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.
  *
  * ================================================================================================
@@ -663,7 +852,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.
@@ -674,8 +863,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'
@@ -729,6 +917,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
  * ================================================================================================
@@ -782,9 +980,13 @@ 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'
+ *   - provider must be 'claude', 'codex', 'gemini', or 'opencode'
  *   - createBranch/createPR requires githubUrl OR projectPath (not neither)
  *   - 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)
@@ -843,6 +1045,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
  * ================================================================================================
@@ -872,6 +1082,7 @@ class ResponseCollector {
  */
 router.post('/', validateExternalApiKey, async (req, res) => {
   const { githubUrl, projectPath, message, provider = 'claude', model, githubToken, branchName, sessionId, openOnly } = req.body;
+  const startedAt = new Date().toISOString();
 
   // 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');
@@ -887,10 +1098,17 @@ router.post('/', validateExternalApiKey, async (req, res) => {
   // Keep openOnly requests backward-compatible with existing docs/examples:
   // cleanup is irrelevant when we only generate session navigation.
   const cleanup = isOpenOnly ? false : requestedCleanup;
+  let callbackConfig = null;
+
+  try {
+    callbackConfig = normalizeAgentCallbackConfig(req.body.callback);
+  } catch (error) {
+    return res.status(400).json({ error: error.message });
+  }
 
   // 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 (!['claude', 'codex', 'gemini', 'opencode'].includes(provider)) {
+    return res.status(400).json({ error: 'provider must be "claude", "codex", "gemini", or "opencode"' });
   }
 
   if (sessionId !== undefined && (typeof sessionId !== 'string' || !sessionId.trim())) {
@@ -917,6 +1135,10 @@ router.post('/', validateExternalApiKey, async (req, res) => {
     return res.status(400).json({ error: 'createBranch and createPR are not supported when openOnly=true' });
   }
 
+  if (isOpenOnly && callbackConfig) {
+    return res.status(400).json({ error: 'callback is 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) {
@@ -955,6 +1177,10 @@ router.post('/', validateExternalApiKey, async (req, res) => {
 
   let finalProjectPath = null;
   let writer = null;
+  let transportWriter = null;
+  let callbackCaptureWriter = new CallbackCaptureWriter();
+  let callbackResult = null;
+  let callbackSessionId = normalizedSessionId;
 
   try {
     // Determine the final project path
@@ -1011,26 +1237,28 @@ router.post('/', validateExternalApiKey, async (req, res) => {
       res.setHeader('Connection', 'keep-alive');
       res.setHeader('X-Accel-Buffering', 'no'); // Disable nginx buffering
 
-      writer = new SSEStreamWriter(res);
+      transportWriter = new SSEStreamWriter(res);
 
       // Send initial status
-      writer.send({
+      transportWriter.send({
         type: 'status',
         message: statusMessage,
         projectPath: finalProjectPath
       });
     } else {
       // Non-streaming mode: collect messages
-      writer = new ResponseCollector();
+      transportWriter = new ResponseCollector();
 
       // Collect initial status message
-      writer.send({
+      transportWriter.send({
         type: 'status',
         message: statusMessage,
         projectPath: finalProjectPath
       });
     }
 
+    writer = new TeeWriter(transportWriter, callbackCaptureWriter);
+
     // Start the appropriate session
     if (provider === 'claude') {
       console.log('🤖 Starting Claude SDK session');
@@ -1042,18 +1270,6 @@ router.post('/', validateExternalApiKey, async (req, res) => {
         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');
 
@@ -1088,6 +1304,17 @@ router.post('/', validateExternalApiKey, async (req, res) => {
       }, writer);
     }
 
+    callbackSessionId = writer.getSessionId() || callbackCaptureWriter.getSessionId() || normalizedSessionId;
+
+    const terminalState = callbackCaptureWriter.getTerminalState();
+    if (terminalState === 'errored') {
+      throw new Error(callbackCaptureWriter.getTerminalErrorMessage() || `${provider} session failed`);
+    }
+
+    if (terminalState !== 'completed') {
+      throw new AgentSessionAbortedError();
+    }
+
     // Handle GitHub branch and PR creation after successful agent completion
     let branchInfo = null;
     let prInfo = null;
@@ -1270,15 +1497,26 @@ router.post('/', validateExternalApiKey, async (req, res) => {
     }
 
     // Handle response based on streaming mode
+    callbackSessionId = writer.getSessionId() || callbackCaptureWriter.getSessionId() || normalizedSessionId;
+    const { sessionPath, sessionUrl } = buildSessionNavigation(callbackSessionId);
+
     if (stream) {
+      callbackResult = {
+        sessionPath,
+        sessionUrl,
+        messages: callbackCaptureWriter.getAssistantMessages(),
+        tokens: callbackCaptureWriter.getTotalTokens(),
+        branch: branchInfo,
+        pullRequest: prInfo
+      };
+
       // 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 assistantMessages = transportWriter.getAssistantMessages();
+      const tokenSummary = transportWriter.getTotalTokens();
+      const resolvedSessionId = transportWriter.getSessionId() || callbackSessionId;
 
       const response = {
         success: true,
@@ -1299,9 +1537,37 @@ router.post('/', validateExternalApiKey, async (req, res) => {
         response.pullRequest = prInfo;
       }
 
+      callbackResult = {
+        sessionPath,
+        sessionUrl,
+        messages: assistantMessages,
+        tokens: tokenSummary,
+        branch: branchInfo,
+        pullRequest: prInfo
+      };
+
       res.json(response);
     }
 
+    if (callbackConfig && shouldDeliverAgentCallback(callbackConfig, 'completed')) {
+      const payload = buildAgentCallbackPayload({
+        event: 'completed',
+        eventId: createAgentCallbackEventId(),
+        sessionId: callbackSessionId,
+        provider,
+        projectPath: finalProjectPath,
+        isResumed: !!normalizedSessionId,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        result: callbackResult
+      });
+
+      void scheduleAgentCallbackDelivery({
+        callback: callbackConfig,
+        payload
+      });
+    }
+
     // Clean up if requested
     if (cleanup && githubUrl) {
       // Only cleanup if we cloned a repo (not for existing project paths)
@@ -1313,6 +1579,15 @@ router.post('/', validateExternalApiKey, async (req, res) => {
 
   } catch (error) {
     console.error('❌ External session error:', error);
+    const terminalEvent = error instanceof AgentSessionAbortedError ? 'aborted' : 'errored';
+    callbackSessionId = (writer && writer.getSessionId()) || callbackCaptureWriter.getSessionId() || normalizedSessionId;
+    const { sessionPath, sessionUrl } = buildSessionNavigation(callbackSessionId);
+    callbackResult = {
+      sessionPath,
+      sessionUrl,
+      messages: callbackCaptureWriter.getAssistantMessages(),
+      tokens: callbackCaptureWriter.getTotalTokens()
+    };
 
     // Clean up on error
     if (finalProjectPath && cleanup && githubUrl) {
@@ -1328,7 +1603,8 @@ router.post('/', validateExternalApiKey, async (req, res) => {
         res.setHeader('Cache-Control', 'no-cache');
         res.setHeader('Connection', 'keep-alive');
         res.setHeader('X-Accel-Buffering', 'no');
-        writer = new SSEStreamWriter(res);
+        transportWriter = new SSEStreamWriter(res);
+        writer = new TeeWriter(transportWriter, callbackCaptureWriter);
       }
 
       if (!res.writableEnded) {
@@ -1345,6 +1621,129 @@ router.post('/', validateExternalApiKey, async (req, res) => {
         error: error.message
       });
     }
+
+    if (callbackConfig && shouldDeliverAgentCallback(callbackConfig, terminalEvent)) {
+      const callbackError = terminalEvent === 'aborted'
+        ? { message: 'Session aborted' }
+        : { message: error.message };
+
+      const payload = buildAgentCallbackPayload({
+        event: terminalEvent,
+        eventId: createAgentCallbackEventId(),
+        sessionId: callbackSessionId,
+        provider,
+        projectPath: finalProjectPath,
+        isResumed: !!normalizedSessionId,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        result: callbackResult,
+        error: callbackError
+      });
+
+      void scheduleAgentCallbackDelivery({
+        callback: callbackConfig,
+        payload
+      });
+    }
+  }
+});
+
+/**
+ * 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', validateExternalApiKey, async (req, res) => {
+  const normalizedSessionId = typeof req.body.sessionId === 'string' ? req.body.sessionId.trim() : '';
+  const provider = typeof req.body.provider === 'string' && req.body.provider.trim()
+    ? req.body.provider.trim().toLowerCase()
+    : 'claude';
+
+  if (!normalizedSessionId) {
+    return res.status(400).json({
+      success: false,
+      error: 'sessionId is required'
+    });
+  }
+
+  if (!isAbortableAgentProvider(provider)) {
+    return res.status(400).json({
+      success: false,
+      error: `provider must be one of: ${ABORTABLE_AGENT_PROVIDERS.join(', ')}`
+    });
+  }
+
+  try {
+    const writer = new SessionEventMirrorWriter(new NoopWriter(), provider);
+    const { success } = await abortAgentSessionWithWriter({
+      provider,
+      sessionId: normalizedSessionId,
+      writer
+    });
+
+    if (!success) {
+      return res.json({
+        success: false,
+        aborted: false,
+        sessionId: normalizedSessionId,
+        provider,
+        error: 'Active session not found'
+      });
+    }
+
+    return res.json({
+      success: true,
+      aborted: true,
+      sessionId: normalizedSessionId,
+      provider,
+      message: 'Session aborted'
+    });
+  } catch (error) {
+    console.error('❌ External abort session error:', error);
+    return res.status(500).json({
+      success: false,
+      error: error.message
+    });
   }
 });