adding a queue system to the agent runner

apps/server/src/index.ts

@@ -48,6 +48,7 @@ import { createClaudeRoutes } from './routes/claude/index.js';
 import { ClaudeUsageService } from './services/claude-usage-service.js';
 import { createGitHubRoutes } from './routes/github/index.js';
 import { createContextRoutes } from './routes/context/index.js';
+import { createBacklogPlanRoutes } from './routes/backlog-plan/index.js';
 import { cleanupStaleValidations } from './routes/github/routes/validation-common.js';
 
 // Load environment variables
@@ -160,6 +161,7 @@ app.use('/api/settings', createSettingsRoutes(settingsService));
 app.use('/api/claude', createClaudeRoutes(claudeUsageService));
 app.use('/api/github', createGitHubRoutes(events, settingsService));
 app.use('/api/context', createContextRoutes(settingsService));
+app.use('/api/backlog-plan', createBacklogPlanRoutes(events, settingsService));
 
 // Create HTTP server
 const server = createServer(app);

apps/server/src/routes/agent/index.ts

@@ -12,6 +12,10 @@ import { createHistoryHandler } from './routes/history.js';
 import { createStopHandler } from './routes/stop.js';
 import { createClearHandler } from './routes/clear.js';
 import { createModelHandler } from './routes/model.js';
+import { createQueueAddHandler } from './routes/queue-add.js';
+import { createQueueListHandler } from './routes/queue-list.js';
+import { createQueueRemoveHandler } from './routes/queue-remove.js';
+import { createQueueClearHandler } from './routes/queue-clear.js';
 
 export function createAgentRoutes(agentService: AgentService, _events: EventEmitter): Router {
   const router = Router();
@@ -27,5 +31,15 @@ export function createAgentRoutes(agentService: AgentService, _events: EventEmit
   router.post('/clear', createClearHandler(agentService));
   router.post('/model', createModelHandler(agentService));
 
+  // Queue routes
+  router.post(
+    '/queue/add',
+    validatePathParams('imagePaths[]'),
+    createQueueAddHandler(agentService)
+  );
+  router.post('/queue/list', createQueueListHandler(agentService));
+  router.post('/queue/remove', createQueueRemoveHandler(agentService));
+  router.post('/queue/clear', createQueueClearHandler(agentService));
+
   return router;
 }

apps/server/src/routes/agent/routes/queue-add.ts

@@ -0,0 +1,34 @@
+/**
+ * POST /queue/add endpoint - Add a prompt to the queue
+ */
+
+import type { Request, Response } from 'express';
+import { AgentService } from '../../../services/agent-service.js';
+import { getErrorMessage, logError } from '../common.js';
+
+export function createQueueAddHandler(agentService: AgentService) {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { sessionId, message, imagePaths, model } = req.body as {
+        sessionId: string;
+        message: string;
+        imagePaths?: string[];
+        model?: string;
+      };
+
+      if (!sessionId || !message) {
+        res.status(400).json({
+          success: false,
+          error: 'sessionId and message are required',
+        });
+        return;
+      }
+
+      const result = await agentService.addToQueue(sessionId, { message, imagePaths, model });
+      res.json(result);
+    } catch (error) {
+      logError(error, 'Add to queue failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/agent/routes/queue-clear.ts

@@ -0,0 +1,29 @@
+/**
+ * POST /queue/clear endpoint - Clear all prompts from the queue
+ */
+
+import type { Request, Response } from 'express';
+import { AgentService } from '../../../services/agent-service.js';
+import { getErrorMessage, logError } from '../common.js';
+
+export function createQueueClearHandler(agentService: AgentService) {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { sessionId } = req.body as { sessionId: string };
+
+      if (!sessionId) {
+        res.status(400).json({
+          success: false,
+          error: 'sessionId is required',
+        });
+        return;
+      }
+
+      const result = await agentService.clearQueue(sessionId);
+      res.json(result);
+    } catch (error) {
+      logError(error, 'Clear queue failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/agent/routes/queue-list.ts

@@ -0,0 +1,29 @@
+/**
+ * POST /queue/list endpoint - List queued prompts
+ */
+
+import type { Request, Response } from 'express';
+import { AgentService } from '../../../services/agent-service.js';
+import { getErrorMessage, logError } from '../common.js';
+
+export function createQueueListHandler(agentService: AgentService) {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { sessionId } = req.body as { sessionId: string };
+
+      if (!sessionId) {
+        res.status(400).json({
+          success: false,
+          error: 'sessionId is required',
+        });
+        return;
+      }
+
+      const result = agentService.getQueue(sessionId);
+      res.json(result);
+    } catch (error) {
+      logError(error, 'List queue failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/agent/routes/queue-remove.ts

@@ -0,0 +1,32 @@
+/**
+ * POST /queue/remove endpoint - Remove a prompt from the queue
+ */
+
+import type { Request, Response } from 'express';
+import { AgentService } from '../../../services/agent-service.js';
+import { getErrorMessage, logError } from '../common.js';
+
+export function createQueueRemoveHandler(agentService: AgentService) {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { sessionId, promptId } = req.body as {
+        sessionId: string;
+        promptId: string;
+      };
+
+      if (!sessionId || !promptId) {
+        res.status(400).json({
+          success: false,
+          error: 'sessionId and promptId are required',
+        });
+        return;
+      }
+
+      const result = await agentService.removeFromQueue(sessionId, promptId);
+      res.json(result);
+    } catch (error) {
+      logError(error, 'Remove from queue failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/backlog-plan/common.ts

@@ -0,0 +1,39 @@
+/**
+ * Common utilities for backlog plan routes
+ */
+
+import { createLogger } from '@automaker/utils';
+
+const logger = createLogger('BacklogPlan');
+
+// State for tracking running generation
+let isRunning = false;
+let currentAbortController: AbortController | null = null;
+
+export function getBacklogPlanStatus(): { isRunning: boolean } {
+  return { isRunning };
+}
+
+export function setRunningState(running: boolean, abortController?: AbortController | null): void {
+  isRunning = running;
+  if (abortController !== undefined) {
+    currentAbortController = abortController;
+  }
+}
+
+export function getAbortController(): AbortController | null {
+  return currentAbortController;
+}
+
+export function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+export function logError(error: unknown, context: string): void {
+  logger.error(`[BacklogPlan] ${context}:`, getErrorMessage(error));
+}
+
+export { logger };

apps/server/src/routes/backlog-plan/generate-plan.ts

@@ -0,0 +1,217 @@
+/**
+ * Generate backlog plan using Claude AI
+ */
+
+import type { EventEmitter } from '../../lib/events.js';
+import type { Feature, BacklogPlanResult, BacklogChange, DependencyUpdate } from '@automaker/types';
+import { FeatureLoader } from '../../services/feature-loader.js';
+import { ProviderFactory } from '../../providers/provider-factory.js';
+import { logger, setRunningState, getErrorMessage } from './common.js';
+import type { SettingsService } from '../../services/settings-service.js';
+import { getAutoLoadClaudeMdSetting } from '../../lib/settings-helpers.js';
+
+const featureLoader = new FeatureLoader();
+
+/**
+ * Format features for the AI prompt
+ */
+function formatFeaturesForPrompt(features: Feature[]): string {
+  if (features.length === 0) {
+    return 'No features in backlog yet.';
+  }
+
+  return features
+    .map((f) => {
+      const deps = f.dependencies?.length ? `Dependencies: [${f.dependencies.join(', ')}]` : '';
+      const priority = f.priority !== undefined ? `Priority: ${f.priority}` : '';
+      return `- ID: ${f.id}
+  Title: ${f.title || 'Untitled'}
+  Description: ${f.description}
+  Category: ${f.category}
+  Status: ${f.status || 'backlog'}
+  ${priority}
+  ${deps}`.trim();
+    })
+    .join('\n\n');
+}
+
+/**
+ * Parse the AI response into a BacklogPlanResult
+ */
+function parsePlanResponse(response: string): BacklogPlanResult {
+  try {
+    // Try to extract JSON from the response
+    const jsonMatch = response.match(/```json\n?([\s\S]*?)\n?```/);
+    if (jsonMatch) {
+      return JSON.parse(jsonMatch[1]);
+    }
+
+    // Try to parse the whole response as JSON
+    return JSON.parse(response);
+  } catch {
+    // If parsing fails, return an empty result
+    logger.warn('[BacklogPlan] Failed to parse AI response as JSON');
+    return {
+      changes: [],
+      summary: 'Failed to parse AI response',
+      dependencyUpdates: [],
+    };
+  }
+}
+
+/**
+ * Generate a backlog modification plan based on user prompt
+ */
+export async function generateBacklogPlan(
+  projectPath: string,
+  prompt: string,
+  events: EventEmitter,
+  abortController: AbortController,
+  settingsService?: SettingsService,
+  model?: string
+): Promise<BacklogPlanResult> {
+  try {
+    // Load current features
+    const features = await featureLoader.getAll(projectPath);
+
+    events.emit('backlog-plan:event', {
+      type: 'backlog_plan_progress',
+      content: `Loaded ${features.length} features from backlog`,
+    });
+
+    // Build the system prompt
+    const systemPrompt = `You are an AI assistant helping to modify a software project's feature backlog.
+You will be given the current list of features and a user request to modify the backlog.
+
+IMPORTANT CONTEXT (automatically injected):
+- Remember to update the dependency graph if deleting existing features
+- Remember to define dependencies on new features hooked into relevant existing ones
+- Maintain dependency graph integrity (no orphaned dependencies)
+- When deleting a feature, identify which other features depend on it
+
+Your task is to analyze the request and produce a structured JSON plan with:
+1. Features to ADD (include title, description, category, and dependencies)
+2. Features to UPDATE (specify featureId and the updates)
+3. Features to DELETE (specify featureId)
+4. A summary of the changes
+5. Any dependency updates needed (removed dependencies due to deletions, new dependencies for new features)
+
+Respond with ONLY a JSON object in this exact format:
+\`\`\`json
+{
+  "changes": [
+    {
+      "type": "add",
+      "feature": {
+        "title": "Feature title",
+        "description": "Feature description",
+        "category": "Category name",
+        "dependencies": ["existing-feature-id"],
+        "priority": 1
+      },
+      "reason": "Why this feature should be added"
+    },
+    {
+      "type": "update",
+      "featureId": "existing-feature-id",
+      "feature": {
+        "title": "Updated title"
+      },
+      "reason": "Why this feature should be updated"
+    },
+    {
+      "type": "delete",
+      "featureId": "feature-id-to-delete",
+      "reason": "Why this feature should be deleted"
+    }
+  ],
+  "summary": "Brief overview of all proposed changes",
+  "dependencyUpdates": [
+    {
+      "featureId": "feature-that-depended-on-deleted",
+      "removedDependencies": ["deleted-feature-id"],
+      "addedDependencies": []
+    }
+  ]
+}
+\`\`\``;
+
+    // Build the user prompt
+    const userPrompt = `Current Features in Backlog:
+${formatFeaturesForPrompt(features)}
+
+---
+
+User Request: ${prompt}
+
+Please analyze the current backlog and the user's request, then provide a JSON plan for the modifications.`;
+
+    events.emit('backlog-plan:event', {
+      type: 'backlog_plan_progress',
+      content: 'Generating plan with AI...',
+    });
+
+    // Get the model to use
+    const effectiveModel = model || 'sonnet';
+    const provider = ProviderFactory.getProviderForModel(effectiveModel);
+
+    // Get autoLoadClaudeMd setting
+    const autoLoadClaudeMd = await getAutoLoadClaudeMdSetting(
+      projectPath,
+      settingsService,
+      '[BacklogPlan]'
+    );
+
+    // Execute the query
+    const stream = provider.executeQuery({
+      prompt: userPrompt,
+      model: effectiveModel,
+      cwd: projectPath,
+      systemPrompt,
+      maxTurns: 1,
+      allowedTools: [], // No tools needed for this
+      abortController,
+      settingSources: autoLoadClaudeMd ? ['user', 'project'] : undefined,
+    });
+
+    let responseText = '';
+
+    for await (const msg of stream) {
+      if (abortController.signal.aborted) {
+        throw new Error('Generation aborted');
+      }
+
+      if (msg.type === 'assistant') {
+        if (msg.message?.content) {
+          for (const block of msg.message.content) {
+            if (block.type === 'text') {
+              responseText += block.text;
+            }
+          }
+        }
+      }
+    }
+
+    // Parse the response
+    const result = parsePlanResponse(responseText);
+
+    events.emit('backlog-plan:event', {
+      type: 'backlog_plan_complete',
+      result,
+    });
+
+    return result;
+  } catch (error) {
+    const errorMessage = getErrorMessage(error);
+    logger.error('[BacklogPlan] Generation failed:', errorMessage);
+
+    events.emit('backlog-plan:event', {
+      type: 'backlog_plan_error',
+      error: errorMessage,
+    });
+
+    throw error;
+  } finally {
+    setRunningState(false, null);
+  }
+}

apps/server/src/routes/backlog-plan/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Backlog Plan routes - HTTP API for AI-assisted backlog modification
+ */
+
+import { Router } from 'express';
+import type { EventEmitter } from '../../lib/events.js';
+import { validatePathParams } from '../../middleware/validate-paths.js';
+import { createGenerateHandler } from './routes/generate.js';
+import { createStopHandler } from './routes/stop.js';
+import { createStatusHandler } from './routes/status.js';
+import { createApplyHandler } from './routes/apply.js';
+import type { SettingsService } from '../../services/settings-service.js';
+
+export function createBacklogPlanRoutes(
+  events: EventEmitter,
+  settingsService?: SettingsService
+): Router {
+  const router = Router();
+
+  router.post(
+    '/generate',
+    validatePathParams('projectPath'),
+    createGenerateHandler(events, settingsService)
+  );
+  router.post('/stop', createStopHandler());
+  router.get('/status', createStatusHandler());
+  router.post('/apply', validatePathParams('projectPath'), createApplyHandler());
+
+  return router;
+}

apps/server/src/routes/backlog-plan/routes/apply.ts

@@ -0,0 +1,147 @@
+/**
+ * POST /apply endpoint - Apply a backlog plan
+ */
+
+import type { Request, Response } from 'express';
+import type { BacklogPlanResult, BacklogChange, Feature } from '@automaker/types';
+import { FeatureLoader } from '../../../services/feature-loader.js';
+import { getErrorMessage, logError, logger } from '../common.js';
+
+const featureLoader = new FeatureLoader();
+
+export function createApplyHandler() {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { projectPath, plan } = req.body as {
+        projectPath: string;
+        plan: BacklogPlanResult;
+      };
+
+      if (!projectPath) {
+        res.status(400).json({ success: false, error: 'projectPath required' });
+        return;
+      }
+
+      if (!plan || !plan.changes) {
+        res.status(400).json({ success: false, error: 'plan with changes required' });
+        return;
+      }
+
+      const appliedChanges: string[] = [];
+
+      // Load current features for dependency validation
+      const allFeatures = await featureLoader.getAll(projectPath);
+      const featureMap = new Map(allFeatures.map((f) => [f.id, f]));
+
+      // Process changes in order: deletes first, then adds, then updates
+      // This ensures we can remove dependencies before they cause issues
+
+      // 1. First pass: Handle deletes
+      const deletions = plan.changes.filter((c) => c.type === 'delete');
+      for (const change of deletions) {
+        if (!change.featureId) continue;
+
+        try {
+          // Before deleting, update any features that depend on this one
+          for (const feature of allFeatures) {
+            if (feature.dependencies?.includes(change.featureId)) {
+              const newDeps = feature.dependencies.filter((d) => d !== change.featureId);
+              await featureLoader.update(projectPath, feature.id, { dependencies: newDeps });
+              logger.info(
+                `[BacklogPlan] Removed dependency ${change.featureId} from ${feature.id}`
+              );
+            }
+          }
+
+          // Now delete the feature
+          const deleted = await featureLoader.delete(projectPath, change.featureId);
+          if (deleted) {
+            appliedChanges.push(`deleted:${change.featureId}`);
+            featureMap.delete(change.featureId);
+            logger.info(`[BacklogPlan] Deleted feature ${change.featureId}`);
+          }
+        } catch (error) {
+          logger.error(
+            `[BacklogPlan] Failed to delete ${change.featureId}:`,
+            getErrorMessage(error)
+          );
+        }
+      }
+
+      // 2. Second pass: Handle adds
+      const additions = plan.changes.filter((c) => c.type === 'add');
+      for (const change of additions) {
+        if (!change.feature) continue;
+
+        try {
+          // Create the new feature
+          const newFeature = await featureLoader.create(projectPath, {
+            title: change.feature.title,
+            description: change.feature.description || '',
+            category: change.feature.category || 'Uncategorized',
+            dependencies: change.feature.dependencies,
+            priority: change.feature.priority,
+            status: 'backlog',
+          });
+
+          appliedChanges.push(`added:${newFeature.id}`);
+          featureMap.set(newFeature.id, newFeature);
+          logger.info(`[BacklogPlan] Created feature ${newFeature.id}: ${newFeature.title}`);
+        } catch (error) {
+          logger.error(`[BacklogPlan] Failed to add feature:`, getErrorMessage(error));
+        }
+      }
+
+      // 3. Third pass: Handle updates
+      const updates = plan.changes.filter((c) => c.type === 'update');
+      for (const change of updates) {
+        if (!change.featureId || !change.feature) continue;
+
+        try {
+          const updated = await featureLoader.update(projectPath, change.featureId, change.feature);
+          appliedChanges.push(`updated:${change.featureId}`);
+          featureMap.set(change.featureId, updated);
+          logger.info(`[BacklogPlan] Updated feature ${change.featureId}`);
+        } catch (error) {
+          logger.error(
+            `[BacklogPlan] Failed to update ${change.featureId}:`,
+            getErrorMessage(error)
+          );
+        }
+      }
+
+      // 4. Apply dependency updates from the plan
+      if (plan.dependencyUpdates) {
+        for (const depUpdate of plan.dependencyUpdates) {
+          try {
+            const feature = featureMap.get(depUpdate.featureId);
+            if (feature) {
+              const currentDeps = feature.dependencies || [];
+              const newDeps = currentDeps
+                .filter((d) => !depUpdate.removedDependencies.includes(d))
+                .concat(depUpdate.addedDependencies.filter((d) => !currentDeps.includes(d)));
+
+              await featureLoader.update(projectPath, depUpdate.featureId, {
+                dependencies: newDeps,
+              });
+              logger.info(`[BacklogPlan] Updated dependencies for ${depUpdate.featureId}`);
+            }
+          } catch (error) {
+            logger.error(
+              `[BacklogPlan] Failed to update dependencies for ${depUpdate.featureId}:`,
+              getErrorMessage(error)
+            );
+          }
+        }
+      }
+
+      res.json({
+        success: true,
+        appliedChanges,
+      });
+    } catch (error) {
+      logError(error, 'Apply backlog plan failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/backlog-plan/routes/generate.ts

@@ -0,0 +1,62 @@
+/**
+ * POST /generate endpoint - Generate a backlog plan
+ */
+
+import type { Request, Response } from 'express';
+import type { EventEmitter } from '../../../lib/events.js';
+import { getBacklogPlanStatus, setRunningState, getErrorMessage, logError } from '../common.js';
+import { generateBacklogPlan } from '../generate-plan.js';
+import type { SettingsService } from '../../../services/settings-service.js';
+
+export function createGenerateHandler(events: EventEmitter, settingsService?: SettingsService) {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { projectPath, prompt, model } = req.body as {
+        projectPath: string;
+        prompt: string;
+        model?: string;
+      };
+
+      if (!projectPath) {
+        res.status(400).json({ success: false, error: 'projectPath required' });
+        return;
+      }
+
+      if (!prompt) {
+        res.status(400).json({ success: false, error: 'prompt required' });
+        return;
+      }
+
+      const { isRunning } = getBacklogPlanStatus();
+      if (isRunning) {
+        res.json({
+          success: false,
+          error: 'Backlog plan generation is already running',
+        });
+        return;
+      }
+
+      setRunningState(true);
+      const abortController = new AbortController();
+      setRunningState(true, abortController);
+
+      // Start generation in background
+      generateBacklogPlan(projectPath, prompt, events, abortController, settingsService, model)
+        .catch((error) => {
+          logError(error, 'Generate backlog plan failed (background)');
+          events.emit('backlog-plan:event', {
+            type: 'backlog_plan_error',
+            error: getErrorMessage(error),
+          });
+        })
+        .finally(() => {
+          setRunningState(false, null);
+        });
+
+      res.json({ success: true });
+    } catch (error) {
+      logError(error, 'Generate backlog plan failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/backlog-plan/routes/status.ts

@@ -0,0 +1,18 @@
+/**
+ * GET /status endpoint - Get backlog plan generation status
+ */
+
+import type { Request, Response } from 'express';
+import { getBacklogPlanStatus, getErrorMessage, logError } from '../common.js';
+
+export function createStatusHandler() {
+  return async (_req: Request, res: Response): Promise<void> => {
+    try {
+      const status = getBacklogPlanStatus();
+      res.json({ success: true, ...status });
+    } catch (error) {
+      logError(error, 'Get backlog plan status failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/backlog-plan/routes/stop.ts

@@ -0,0 +1,22 @@
+/**
+ * POST /stop endpoint - Stop the current backlog plan generation
+ */
+
+import type { Request, Response } from 'express';
+import { getAbortController, setRunningState, getErrorMessage, logError } from '../common.js';
+
+export function createStopHandler() {
+  return async (_req: Request, res: Response): Promise<void> => {
+    try {
+      const abortController = getAbortController();
+      if (abortController) {
+        abortController.abort();
+        setRunningState(false, null);
+      }
+      res.json({ success: true });
+    } catch (error) {
+      logError(error, 'Stop backlog plan failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/services/agent-service.ts

@@ -32,6 +32,14 @@ interface Message {
   isError?: boolean;
 }
 
+interface QueuedPrompt {
+  id: string;
+  message: string;
+  imagePaths?: string[];
+  model?: string;
+  addedAt: string;
+}
+
 interface Session {
   messages: Message[];
   isRunning: boolean;
@@ -39,6 +47,7 @@ interface Session {
   workingDirectory: string;
   model?: string;
   sdkSessionId?: string; // Claude SDK session ID for conversation continuity
+  promptQueue: QueuedPrompt[]; // Queue of prompts to auto-run after current task
 }
 
 interface SessionMetadata {
@@ -94,12 +103,16 @@ export class AgentService {
       // Validate that the working directory is allowed using centralized validation
       validateWorkingDirectory(resolvedWorkingDirectory);
 
+      // Load persisted queue
+      const promptQueue = await this.loadQueueState(sessionId);
+
       this.sessions.set(sessionId, {
         messages,
         isRunning: false,
         abortController: null,
         workingDirectory: resolvedWorkingDirectory,
         sdkSessionId: sessionMetadata?.sdkSessionId, // Load persisted SDK session ID
+        promptQueue,
       });
     }
 
@@ -178,6 +191,11 @@ export class AgentService {
     session.isRunning = true;
     session.abortController = new AbortController();
 
+    // Emit started event so UI can show thinking indicator
+    this.emitAgentEvent(sessionId, {
+      type: 'started',
+    });
+
     // Emit user message event
     this.emitAgentEvent(sessionId, {
       type: 'message',
@@ -336,6 +354,9 @@ export class AgentService {
       session.isRunning = false;
       session.abortController = null;
 
+      // Process next item in queue after completion
+      setImmediate(() => this.processNextInQueue(sessionId));
+
       return {
         success: true,
         message: currentAssistantMessage,
@@ -574,6 +595,167 @@ export class AgentService {
     return true;
   }
 
+  // Queue management methods
+
+  /**
+   * Add a prompt to the queue for later execution
+   */
+  async addToQueue(
+    sessionId: string,
+    prompt: { message: string; imagePaths?: string[]; model?: string }
+  ): Promise<{ success: boolean; queuedPrompt?: QueuedPrompt; error?: string }> {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      return { success: false, error: 'Session not found' };
+    }
+
+    const queuedPrompt: QueuedPrompt = {
+      id: this.generateId(),
+      message: prompt.message,
+      imagePaths: prompt.imagePaths,
+      model: prompt.model,
+      addedAt: new Date().toISOString(),
+    };
+
+    session.promptQueue.push(queuedPrompt);
+    await this.saveQueueState(sessionId, session.promptQueue);
+
+    // Emit queue update event
+    this.emitAgentEvent(sessionId, {
+      type: 'queue_updated',
+      queue: session.promptQueue,
+    });
+
+    return { success: true, queuedPrompt };
+  }
+
+  /**
+   * Get the current queue for a session
+   */
+  getQueue(sessionId: string): { success: boolean; queue?: QueuedPrompt[]; error?: string } {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      return { success: false, error: 'Session not found' };
+    }
+    return { success: true, queue: session.promptQueue };
+  }
+
+  /**
+   * Remove a specific prompt from the queue
+   */
+  async removeFromQueue(
+    sessionId: string,
+    promptId: string
+  ): Promise<{ success: boolean; error?: string }> {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      return { success: false, error: 'Session not found' };
+    }
+
+    const index = session.promptQueue.findIndex((p) => p.id === promptId);
+    if (index === -1) {
+      return { success: false, error: 'Prompt not found in queue' };
+    }
+
+    session.promptQueue.splice(index, 1);
+    await this.saveQueueState(sessionId, session.promptQueue);
+
+    this.emitAgentEvent(sessionId, {
+      type: 'queue_updated',
+      queue: session.promptQueue,
+    });
+
+    return { success: true };
+  }
+
+  /**
+   * Clear all prompts from the queue
+   */
+  async clearQueue(sessionId: string): Promise<{ success: boolean; error?: string }> {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      return { success: false, error: 'Session not found' };
+    }
+
+    session.promptQueue = [];
+    await this.saveQueueState(sessionId, []);
+
+    this.emitAgentEvent(sessionId, {
+      type: 'queue_updated',
+      queue: [],
+    });
+
+    return { success: true };
+  }
+
+  /**
+   * Save queue state to disk for persistence
+   */
+  private async saveQueueState(sessionId: string, queue: QueuedPrompt[]): Promise<void> {
+    const queueFile = path.join(this.stateDir, `${sessionId}-queue.json`);
+    try {
+      await secureFs.writeFile(queueFile, JSON.stringify(queue, null, 2), 'utf-8');
+    } catch (error) {
+      console.error('[AgentService] Failed to save queue state:', error);
+    }
+  }
+
+  /**
+   * Load queue state from disk
+   */
+  private async loadQueueState(sessionId: string): Promise<QueuedPrompt[]> {
+    const queueFile = path.join(this.stateDir, `${sessionId}-queue.json`);
+    try {
+      const data = (await secureFs.readFile(queueFile, 'utf-8')) as string;
+      return JSON.parse(data);
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Process the next item in the queue (called after task completion)
+   */
+  private async processNextInQueue(sessionId: string): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session || session.promptQueue.length === 0) {
+      return;
+    }
+
+    // Don't process if already running
+    if (session.isRunning) {
+      return;
+    }
+
+    const nextPrompt = session.promptQueue.shift();
+    if (!nextPrompt) return;
+
+    await this.saveQueueState(sessionId, session.promptQueue);
+
+    this.emitAgentEvent(sessionId, {
+      type: 'queue_updated',
+      queue: session.promptQueue,
+    });
+
+    console.log(`[AgentService] Processing next queued prompt for session ${sessionId}`);
+
+    try {
+      await this.sendMessage({
+        sessionId,
+        message: nextPrompt.message,
+        imagePaths: nextPrompt.imagePaths,
+        model: nextPrompt.model,
+      });
+    } catch (error) {
+      console.error('[AgentService] Failed to process queued prompt:', error);
+      this.emitAgentEvent(sessionId, {
+        type: 'queue_error',
+        error: (error as Error).message,
+        promptId: nextPrompt.id,
+      });
+    }
+  }
+
   private emitAgentEvent(sessionId: string, data: Record<string, unknown>): void {
     this.events.emit('agent:stream', { sessionId, ...data });
   }