@axhub/genie 0.1.8 → 0.2.0

package/server/external-agent/service.js

@@ -0,0 +1,1052 @@
+import { spawn } from 'child_process';
+import path from 'path';
+import os from 'os';
+import { promises as fs } from 'fs';
+import crypto from 'crypto';
+import { Octokit } from '@octokit/rest';
+
+import { 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 {
+  buildAgentCallbackPayload,
+  createAgentCallbackEventId,
+  createEmptyTokenSummary,
+  normalizeAgentCallbackConfig,
+  scheduleAgentCallbackDelivery,
+  shouldDeliverAgentCallback
+} from '../utils/agentCallback.js';
+import { normalizeExternalImages } from '../utils/agentImages.js';
+import { resolveWorkingDirectory } from '../utils/defaultWorkingDirectory.js';
+import { CODEX_MODELS, GEMINI_MODELS, OPENCODE_MODELS } from '../../shared/modelConstants.js';
+
+export const SUPPORTED_EXTERNAL_AGENT_PROVIDERS = ['claude', 'codex', 'gemini', 'opencode'];
+
+function createRequestError(message, statusCode = 400) {
+  const error = new Error(message);
+  error.statusCode = statusCode;
+  return error;
+}
+
+function parseBoolean(value, fallback) {
+  if (value === undefined) {
+    return fallback;
+  }
+  return value === true || value === 'true';
+}
+
+export 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
+  };
+}
+
+export function normalizeExternalAgentRunRequest(body = {}) {
+  const { githubUrl, projectPath, message, model, githubToken, branchName, sessionId, openOnly } = body;
+  const provider = typeof body.provider === 'string' ? body.provider.trim() : 'claude';
+  const stream = parseBoolean(body.stream, true);
+  const requestedCleanup = parseBoolean(body.cleanup, true);
+  const createBranch = branchName ? true : parseBoolean(body.createBranch, false);
+  const createPR = parseBoolean(body.createPR, false);
+  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);
+  const cleanup = isOpenOnly ? false : requestedCleanup;
+  const images = normalizeExternalImages(body.images);
+  const resolvedProjectPath = githubUrl ? projectPath : resolveWorkingDirectory({ projectPath });
+
+  let callbackConfig = null;
+  try {
+    callbackConfig = normalizeAgentCallbackConfig(body.callback);
+  } catch (error) {
+    throw createRequestError(error.message, 400);
+  }
+
+  if (!SUPPORTED_EXTERNAL_AGENT_PROVIDERS.includes(provider)) {
+    throw createRequestError('provider must be "claude", "codex", "gemini", or "opencode"', 400);
+  }
+
+  if (sessionId !== undefined && (typeof sessionId !== 'string' || !sessionId.trim())) {
+    throw createRequestError('sessionId must be a non-empty string when provided', 400);
+  }
+
+  if (isOpenOnly && !normalizedSessionId) {
+    throw createRequestError('sessionId is required when message is empty or openOnly=true', 400);
+  }
+
+  if (!isOpenOnly && !normalizedMessage) {
+    throw createRequestError('message is required unless openOnly=true', 400);
+  }
+
+  if (isOpenOnly && githubUrl) {
+    throw createRequestError('githubUrl is not supported when openOnly=true', 400);
+  }
+
+  if (isOpenOnly && (createBranch || createPR)) {
+    throw createRequestError('createBranch and createPR are not supported when openOnly=true', 400);
+  }
+
+  if (isOpenOnly && callbackConfig) {
+    throw createRequestError('callback is not supported when openOnly=true', 400);
+  }
+
+  if (isOpenOnly && images.length > 0) {
+    throw createRequestError('images is not supported when openOnly=true', 400);
+  }
+
+  if (images.length > 0 && provider !== 'claude' && provider !== 'codex') {
+    throw createRequestError(`images is not supported for provider "${provider}"`, 400);
+  }
+
+  return {
+    githubUrl,
+    projectPath: resolvedProjectPath,
+    message,
+    normalizedMessage,
+    provider,
+    model,
+    githubToken,
+    branchName,
+    sessionId,
+    normalizedSessionId,
+    openOnly,
+    requestedOpenOnly,
+    isOpenOnly,
+    createBranch,
+    createPR,
+    stream,
+    requestedCleanup,
+    cleanup,
+    callbackConfig,
+    images
+  };
+}
+
+export function normalizeExternalAgentAbortRequest(body = {}) {
+  const normalizedSessionId = typeof body.sessionId === 'string' ? body.sessionId.trim() : '';
+  const provider = typeof body.provider === 'string' && body.provider.trim()
+    ? body.provider.trim().toLowerCase()
+    : 'claude';
+
+  if (!normalizedSessionId) {
+    throw createRequestError('sessionId is required', 400);
+  }
+
+  if (!SUPPORTED_EXTERNAL_AGENT_PROVIDERS.includes(provider)) {
+    throw createRequestError(`provider must be one of: ${SUPPORTED_EXTERNAL_AGENT_PROVIDERS.join(', ')}`, 400);
+  }
+
+  return {
+    sessionId: normalizedSessionId,
+    provider
+  };
+}
+
+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}`));
+    });
+  });
+}
+
+function normalizeGitHubUrl(url) {
+  let normalized = url.replace(/\.git$/, '');
+  normalized = normalized.replace(/^git@github\.com:/, 'https://github.com/');
+  normalized = normalized.replace(/\/$/, '');
+  return normalized.toLowerCase();
+}
+
+function parseGitHubUrl(url) {
+  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$/, '')
+  };
+}
+
+function autogenerateBranchName(message) {
+  let branchName = message
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+
+  if (!branchName) {
+    branchName = 'task';
+  }
+
+  const timestamp = Date.now().toString(36).slice(-6);
+  const suffix = `-${timestamp}`;
+  const maxBaseLength = 50 - suffix.length;
+
+  if (branchName.length > maxBaseLength) {
+    branchName = branchName.substring(0, maxBaseLength);
+  }
+
+  branchName = branchName.replace(/-$/, '').replace(/^-+/, '');
+
+  if (!branchName || branchName.startsWith('-')) {
+    branchName = 'task';
+  }
+
+  branchName = `${branchName}${suffix}`;
+
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(branchName)) {
+    return `branch-${timestamp}`;
+  }
+
+  return branchName;
+}
+
+function validateBranchName(branchName) {
+  if (!branchName || branchName.trim() === '') {
+    return { valid: false, error: 'Branch name cannot be empty' };
+  }
+
+  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 };
+    }
+  }
+
+  if (/[\x00-\x1F\x7F]/.test(branchName)) {
+    return { valid: false, error: 'Branch name cannot contain control characters' };
+  }
+
+  return { valid: true };
+}
+
+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) {
+        resolve(stdout.trim().split('\n').filter((msg) => msg.length > 0));
+      } else {
+        reject(new Error(`Failed to get commit messages: ${stderr}`));
+      }
+    });
+
+    gitProcess.on('error', (error) => {
+      reject(new Error(`Failed to execute git: ${error.message}`));
+    });
+  });
+}
+
+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
+  });
+
+  return {
+    number: pr.number,
+    url: pr.html_url
+  };
+}
+
+async function cloneGitHubRepo(githubUrl, githubToken = null, projectPath) {
+  return new Promise(async (resolve, reject) => {
+    try {
+      if (!githubUrl || !githubUrl.includes('github.com')) {
+        throw new Error('Invalid GitHub URL');
+      }
+
+      const cloneDir = path.resolve(projectPath);
+      let directoryExists = false;
+      try {
+        await fs.access(cloneDir);
+        directoryExists = true;
+      } catch {
+        directoryExists = false;
+      }
+
+      if (directoryExists) {
+        try {
+          const existingUrl = await getGitRemoteUrl(cloneDir);
+          const normalizedExisting = normalizeGitHubUrl(existingUrl);
+          const normalizedRequested = normalizeGitHubUrl(githubUrl);
+
+          if (normalizedExisting === normalizedRequested) {
+            return resolve(cloneDir);
+          }
+
+          throw new Error(`Directory ${cloneDir} already exists with a different repository (${existingUrl}). Expected: ${githubUrl}`);
+        } catch (error) {
+          if (error.message && error.message.includes('different repository')) {
+            throw error;
+          }
+          throw new Error(`Directory ${cloneDir} already exists but is not a valid git repository or git command failed`);
+        }
+      }
+
+      await fs.mkdir(path.dirname(cloneDir), { recursive: true });
+
+      let cloneUrl = githubUrl;
+      if (githubToken) {
+        cloneUrl = githubUrl.replace('https://github.com', `https://${githubToken}@github.com`);
+      }
+
+      const gitProcess = spawn('git', ['clone', '--depth', '1', cloneUrl, cloneDir], {
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+
+      let stderr = '';
+
+      gitProcess.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+
+      gitProcess.on('close', (code) => {
+        if (code === 0) {
+          resolve(cloneDir);
+        } else {
+          reject(new Error(`Git clone failed: ${stderr}`));
+        }
+      });
+
+      gitProcess.on('error', (error) => {
+        reject(new Error(`Failed to execute git: ${error.message}`));
+      });
+    } catch (error) {
+      reject(error);
+    }
+  });
+}
+
+async function cleanupProject(projectPath, sessionId = null) {
+  try {
+    if (!projectPath.includes('.claude/external-projects')) {
+      console.warn('Refusing to clean up non-external project:', projectPath);
+      return;
+    }
+
+    await fs.rm(projectPath, { recursive: true, force: true });
+
+    if (sessionId) {
+      try {
+        const sessionPath = path.join(os.homedir(), '.claude', 'sessions', sessionId);
+        await fs.rm(sessionPath, { recursive: true, force: true });
+      } catch (error) {
+        console.error('Failed to clean up session directory:', error.message);
+      }
+    }
+  } catch (error) {
+    console.error('Failed to clean up project:', error);
+  }
+}
+
+export class SSEStreamWriter {
+  constructor(res) {
+    this.res = res;
+    this.sessionId = null;
+    this.isSSEStreamWriter = true;
+  }
+
+  send(data) {
+    if (!this.res.writableEnded) {
+      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;
+  }
+}
+
+export class ResponseCollector {
+  constructor() {
+    this.messages = [];
+    this.sessionId = null;
+  }
+
+  send(data) {
+    this.messages.push(data);
+    if (data && typeof data === 'object' && data.sessionId) {
+      this.sessionId = data.sessionId;
+    }
+  }
+
+  end() {}
+
+  setSessionId(sessionId) {
+    this.sessionId = sessionId;
+  }
+
+  getSessionId() {
+    return this.sessionId;
+  }
+}
+
+export 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;
+}
+
+export 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;
+  }
+}
+
+export 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;
+  }
+}
+
+export class NoopWriter {
+  send() {}
+
+  end() {}
+}
+
+async function runProviderSession({ provider, message, images, finalProjectPath, sessionId, model, writer }) {
+  if (provider === 'claude') {
+    await queryClaudeSDK(message, {
+      projectPath: finalProjectPath,
+      cwd: finalProjectPath,
+      sessionId,
+      model,
+      permissionMode: 'bypassPermissions',
+      images
+    }, writer);
+    return;
+  }
+
+  if (provider === 'codex') {
+    await queryCodex(message, {
+      projectPath: finalProjectPath,
+      cwd: finalProjectPath,
+      sessionId,
+      model: model || CODEX_MODELS.DEFAULT,
+      permissionMode: 'bypassPermissions',
+      images
+    }, writer);
+    return;
+  }
+
+  if (provider === 'gemini') {
+    await queryGemini(message, {
+      projectPath: finalProjectPath,
+      cwd: finalProjectPath,
+      sessionId,
+      resume: !!sessionId,
+      model: model || GEMINI_MODELS.DEFAULT,
+      permissionMode: 'bypassPermissions'
+    }, writer);
+    return;
+  }
+
+  if (provider === 'opencode') {
+    await queryOpencode(message, {
+      projectPath: finalProjectPath,
+      cwd: finalProjectPath,
+      sessionId,
+      resume: !!sessionId,
+      model: model || OPENCODE_MODELS.DEFAULT,
+      permissionMode: 'bypassPermissions'
+    }, writer);
+  }
+}
+
+async function maybeCreateBranchAndPR({
+  user,
+  githubToken,
+  githubUrl,
+  finalProjectPath,
+  branchName,
+  message,
+  createBranch,
+  createPR,
+  transportWriter
+}) {
+  let branchInfo = null;
+  let prInfo = null;
+
+  if (!createBranch && !createPR) {
+    return { branchInfo, prInfo };
+  }
+
+  try {
+    const tokenToUse = githubToken || githubTokensDb.getActiveGithubToken(user?.id);
+    if (!tokenToUse) {
+      throw new Error('GitHub token required for branch/PR creation. Please configure a GitHub token in settings.');
+    }
+
+    const octokit = new Octokit({ auth: tokenToUse });
+    let repoUrl = githubUrl;
+
+    if (!repoUrl) {
+      repoUrl = await getGitRemoteUrl(finalProjectPath);
+      if (!repoUrl.includes('github.com')) {
+        throw new Error('Project does not have a GitHub remote configured');
+      }
+    }
+
+    const { owner, repo } = parseGitHubUrl(repoUrl);
+    const finalBranchName = branchName || autogenerateBranchName(message);
+
+    if (branchName) {
+      const validation = validateBranchName(finalBranchName);
+      if (!validation.valid) {
+        throw new Error(`Invalid branch name: ${validation.error}`);
+      }
+    }
+
+    if (createBranch) {
+      await new Promise((resolve, reject) => {
+        const checkoutProcess = spawn('git', ['checkout', '-b', finalBranchName], {
+          cwd: finalProjectPath,
+          stdio: 'pipe'
+        });
+
+        let stderr = '';
+        checkoutProcess.stderr.on('data', (data) => {
+          stderr += data.toString();
+        });
+
+        checkoutProcess.on('close', (code) => {
+          if (code === 0) {
+            resolve();
+            return;
+          }
+
+          if (stderr.includes('already exists')) {
+            const checkoutExisting = spawn('git', ['checkout', finalBranchName], {
+              cwd: finalProjectPath,
+              stdio: 'pipe'
+            });
+            checkoutExisting.on('close', (checkoutCode) => {
+              if (checkoutCode === 0) {
+                resolve();
+              } else {
+                reject(new Error(`Failed to checkout existing branch: ${stderr}`));
+              }
+            });
+            return;
+          }
+
+          reject(new Error(`Failed to create branch: ${stderr}`));
+        });
+      });
+
+      await new Promise((resolve, reject) => {
+        const pushProcess = spawn('git', ['push', '-u', 'origin', finalBranchName], {
+          cwd: finalProjectPath,
+          stdio: 'pipe'
+        });
+
+        let stderr = '';
+        pushProcess.stderr.on('data', (data) => {
+          stderr += data.toString();
+        });
+
+        pushProcess.on('close', (code) => {
+          if (code === 0 || stderr.includes('already exists') || stderr.includes('up-to-date')) {
+            resolve();
+          } else {
+            reject(new Error(`Failed to push branch: ${stderr}`));
+          }
+        });
+      });
+
+      branchInfo = {
+        name: finalBranchName,
+        url: `https://github.com/${owner}/${repo}/tree/${finalBranchName}`
+      };
+    }
+
+    if (createPR) {
+      const commitMessages = await getCommitMessages(finalProjectPath, 5);
+      const prTitle = commitMessages.length > 0 ? commitMessages[0] : message;
+      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.*';
+
+      prInfo = await createGitHubPR(octokit, owner, repo, finalBranchName, prTitle, prBody, 'main');
+    }
+
+    if (branchInfo) {
+      transportWriter?.send?.({
+        type: 'github-branch',
+        branch: branchInfo
+      });
+    }
+
+    if (prInfo) {
+      transportWriter?.send?.({
+        type: 'github-pr',
+        pullRequest: prInfo
+      });
+    }
+  } catch (error) {
+    transportWriter?.send?.({
+      type: 'github-error',
+      error: error.message
+    });
+
+    branchInfo = { error: error.message };
+    prInfo = { error: error.message };
+  }
+
+  return { branchInfo, prInfo };
+}
+
+export async function runExternalAgentRequest({
+  user,
+  request,
+  transportWriter,
+  endTransportOnFinish = false
+}) {
+  const normalized = request?.normalizedMessage !== undefined
+    ? request
+    : normalizeExternalAgentRunRequest(request);
+  const startedAt = new Date().toISOString();
+
+  if (normalized.isOpenOnly) {
+    const response = {
+      success: true,
+      openOnly: true,
+      sessionId: normalized.normalizedSessionId,
+      ...buildSessionNavigation(normalized.normalizedSessionId),
+      isResumed: true,
+      message: 'Session link generated. No model call triggered.'
+    };
+
+    transportWriter?.send?.({
+      type: 'open-only',
+      ...response
+    });
+
+    if (endTransportOnFinish) {
+      transportWriter?.end?.();
+    }
+
+    return response;
+  }
+
+  let finalProjectPath = null;
+  let branchInfo = null;
+  let prInfo = null;
+  const callbackCaptureWriter = new CallbackCaptureWriter();
+  const writer = new TeeWriter(transportWriter, callbackCaptureWriter);
+  let callbackSessionId = normalized.normalizedSessionId;
+  let callbackResult = null;
+
+  try {
+    if (normalized.githubUrl) {
+      const tokenToUse = normalized.githubToken || githubTokensDb.getActiveGithubToken(user?.id);
+      let targetPath = normalized.projectPath;
+      if (!targetPath) {
+        const repoHash = crypto.createHash('md5').update(normalized.githubUrl + Date.now()).digest('hex');
+        targetPath = path.join(os.homedir(), '.claude', 'external-projects', repoHash);
+      }
+
+      finalProjectPath = await cloneGitHubRepo(normalized.githubUrl.trim(), tokenToUse, targetPath);
+    } else {
+      finalProjectPath = resolveWorkingDirectory({ projectPath: normalized.projectPath });
+      try {
+        await fs.access(finalProjectPath);
+      } catch {
+        throw new Error(`Project path does not exist: ${finalProjectPath}`);
+      }
+    }
+
+    try {
+      await addProjectManually(finalProjectPath);
+    } catch (error) {
+      if (!(error.message && error.message.includes('Project already configured'))) {
+        throw error;
+      }
+    }
+
+    const statusMessage = normalized.normalizedSessionId
+      ? (normalized.githubUrl ? 'Repository cloned and session resumed' : 'Session resumed')
+      : (normalized.githubUrl ? 'Repository cloned and session started' : 'Session started');
+
+    transportWriter?.send?.({
+      type: 'status',
+      message: statusMessage,
+      projectPath: finalProjectPath
+    });
+
+    await runProviderSession({
+      provider: normalized.provider,
+      message: normalized.normalizedMessage,
+      images: normalized.images,
+      finalProjectPath,
+      sessionId: normalized.normalizedSessionId,
+      model: normalized.model,
+      writer
+    });
+
+    callbackSessionId = writer.getSessionId() || callbackCaptureWriter.getSessionId() || normalized.normalizedSessionId;
+    const terminalState = callbackCaptureWriter.getTerminalState();
+
+    if (terminalState === 'errored') {
+      throw new Error(callbackCaptureWriter.getTerminalErrorMessage() || `${normalized.provider} session failed`);
+    }
+
+    if (terminalState !== 'completed') {
+      throw new AgentSessionAbortedError();
+    }
+
+    ({ branchInfo, prInfo } = await maybeCreateBranchAndPR({
+      user,
+      githubToken: normalized.githubToken,
+      githubUrl: normalized.githubUrl,
+      finalProjectPath,
+      branchName: normalized.branchName,
+      message: normalized.message,
+      createBranch: normalized.createBranch,
+      createPR: normalized.createPR,
+      transportWriter
+    }));
+
+    callbackSessionId = writer.getSessionId() || callbackCaptureWriter.getSessionId() || normalized.normalizedSessionId;
+    const navigation = buildSessionNavigation(callbackSessionId);
+    const response = {
+      success: true,
+      sessionId: callbackSessionId,
+      ...navigation,
+      isResumed: !!normalized.normalizedSessionId,
+      messages: callbackCaptureWriter.getAssistantMessages(),
+      tokens: callbackCaptureWriter.getTotalTokens(),
+      projectPath: finalProjectPath
+    };
+
+    if (branchInfo) {
+      response.branch = branchInfo;
+    }
+    if (prInfo) {
+      response.pullRequest = prInfo;
+    }
+
+    callbackResult = {
+      sessionPath: navigation.sessionPath,
+      sessionUrl: navigation.sessionUrl,
+      messages: response.messages,
+      tokens: response.tokens,
+      branch: branchInfo,
+      pullRequest: prInfo
+    };
+
+    if (normalized.callbackConfig && shouldDeliverAgentCallback(normalized.callbackConfig, 'completed')) {
+      const payload = buildAgentCallbackPayload({
+        event: 'completed',
+        eventId: createAgentCallbackEventId(),
+        sessionId: callbackSessionId,
+        provider: normalized.provider,
+        projectPath: finalProjectPath,
+        isResumed: !!normalized.normalizedSessionId,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        result: callbackResult
+      });
+
+      void scheduleAgentCallbackDelivery({
+        callback: normalized.callbackConfig,
+        payload
+      });
+    }
+
+    if (normalized.cleanup && normalized.githubUrl) {
+      const sessionIdForCleanup = writer.getSessionId();
+      setTimeout(() => {
+        cleanupProject(finalProjectPath, sessionIdForCleanup);
+      }, 5000);
+    }
+
+    if (endTransportOnFinish) {
+      transportWriter?.end?.();
+    }
+
+    return response;
+  } catch (error) {
+    callbackSessionId = writer.getSessionId() || callbackCaptureWriter.getSessionId() || normalized.normalizedSessionId;
+    callbackResult = {
+      ...buildSessionNavigation(callbackSessionId),
+      messages: callbackCaptureWriter.getAssistantMessages(),
+      tokens: callbackCaptureWriter.getTotalTokens(),
+      branch: branchInfo,
+      pullRequest: prInfo
+    };
+
+    if (finalProjectPath && normalized.cleanup && normalized.githubUrl) {
+      const sessionIdForCleanup = writer.getSessionId();
+      await cleanupProject(finalProjectPath, sessionIdForCleanup);
+    }
+
+    const terminalEvent = error instanceof AgentSessionAbortedError ? 'aborted' : 'errored';
+    if (normalized.callbackConfig && shouldDeliverAgentCallback(normalized.callbackConfig, terminalEvent)) {
+      const callbackError = terminalEvent === 'aborted'
+        ? { message: 'Session aborted' }
+        : { message: error.message };
+
+      const payload = buildAgentCallbackPayload({
+        event: terminalEvent,
+        eventId: createAgentCallbackEventId(),
+        sessionId: callbackSessionId,
+        provider: normalized.provider,
+        projectPath: finalProjectPath,
+        isResumed: !!normalized.normalizedSessionId,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        result: callbackResult,
+        error: callbackError
+      });
+
+      void scheduleAgentCallbackDelivery({
+        callback: normalized.callbackConfig,
+        payload
+      });
+    }
+
+    throw error;
+  }
+}