RFC Background Bash Tasks Implementation Plan

[xierenyuan]

Background Bash Tasks Implementation Plan

Goal: Enable bash tool to run commands in background and retrieve their output asynchronously through a new bash_output tool.

Architecture: Create a BackgroundTaskManager in src/utils to manage background process lifecycle, output buffering, and cleanup. Extend bash tool with background parameter, add bash_output tool for retrieval. Manager is session-scoped and auto-cleans on session end.

Tech Stack: Node.js child_process, existing shellExecute utility from src/utils/shell-execution.ts, reuse executeCommand and validateCommand from src/tools/bash.ts, zod for validation

Key Design Decision: The BackgroundTaskManager reuses the command execution logic from src/tools/bash.ts to ensure consistency:

• validateCommand() - For command validation before execution
• shellExecute() - For actual command execution with proper shell handling
• This ensures background tasks follow the same security rules and execution behavior as foreground bash commands

---

Task 0: Export bash.ts Functions for Reuse

Files:

• Modify: src/tools/bash.ts

Step 1: Export executeCommand function

Change async function executeCommand to export async function executeCommand in src/tools/bash.ts

Step 2: Export validateCommand function

Change function validateCommand to export function validateCommand in src/tools/bash.ts

Step 3: Verify exports

Run: npm run typecheck
Expected: No errors

Status: ✅ COMPLETED - Functions have been exported from src/tools/bash.ts

---

Task 1: Create BackgroundTaskManager Core

Files:

• Create: src/utils/backgroundTasks.ts
• Test: src/utils/backgroundTasks.test.ts

Step 1: Write failing test for manager initialization

import { describe, expect, it } from 'vitest';
import { BackgroundTaskManager } from './backgroundTasks';

describe('BackgroundTaskManager', () => {
  it('should initialize with empty task map', () => {
    const manager = new BackgroundTaskManager('test-session');
    expect(manager.getTaskCount()).toBe(0);
  });
});

Step 2: Run test to verify it fails

Run: npm test src/utils/backgroundTasks.test.ts
Expected: FAIL with "Cannot find module './backgroundTasks'"

Step 3: Create minimal BackgroundTaskManager class

In src/utils/backgroundTasks.ts:

import type { ChildProcess } from 'node:child_process';

export interface BackgroundTask {
  id: string;
  command: string;
  process: ChildProcess;
  stdout: string[];
  stderr: string[];
  status: 'running' | 'completed' | 'failed';
  exitCode: number | null;
  startTime: Date;
  endTime: Date | null;
  lastReadPosition: {
    stdout: number;
    stderr: number;
  };
}

export class BackgroundTaskManager {
  private tasks: Map<string, BackgroundTask> = new Map();
  private sessionId: string;

  constructor(sessionId: string) {
    this.sessionId = sessionId;
  }

  getTaskCount(): number {
    return this.tasks.size;
  }
}

Step 4: Run test to verify it passes

Run: npm test src/utils/backgroundTasks.test.ts
Expected: PASS

---

Task 2: Implement Task Starting

Files:

• Modify: src/utils/backgroundTasks.ts
• Modify: src/utils/backgroundTasks.test.ts

Step 1: Write failing test for startTask

Add to src/utils/backgroundTasks.test.ts:

import { vi } from 'vitest';

it('should start a background task and return task ID', async () => {
  const manager = new BackgroundTaskManager('test-session');
  const taskId = await manager.startTask('echo "test"', '/tmp', 30000);
  
  expect(taskId).toBeTruthy();
  expect(typeof taskId).toBe('string');
  expect(manager.getTaskCount()).toBe(1);
});

Step 2: Run test to verify it fails

Run: npm test src/utils/backgroundTasks.test.ts
Expected: FAIL with "manager.startTask is not a function"

Step 3: Implement startTask method

Add to src/utils/backgroundTasks.ts:

import { randomUUID } from 'node:crypto';
import { spawn } from 'node:child_process';
import os from 'node:os';
import createDebug from 'debug';
import { executeCommand, validateCommand } from '../tools/bash';
import { shellExecute } from './shell-execution';

const debug = createDebug('neovate:background-tasks');

export class BackgroundTaskManager {
  // ... existing code ...

  async startTask(
    command: string,
    cwd: string,
    timeout: number,
  ): Promise<string> {
    const taskId = randomUUID();
    
    // Reuse command validation from bash tool
    const validationError = validateCommand(command);
    if (validationError) {
      throw new Error(validationError);
    }

    const isWindows = os.platform() === 'win32';
    const shell = isWindows ? 'cmd.exe' : '/bin/sh';
    const shellArgs = isWindows ? ['/c', command] : ['-c', command];

    // Use shellExecute from bash tool for consistent command execution
    const { result: resultPromise, process } = shellExecute(
      command,
      cwd,
      timeout,
    );

    const task: BackgroundTask = {
      id: taskId,
      command,
      process,
      stdout: [],
      stderr: [],
      status: 'running',
      exitCode: null,
      startTime: new Date(),
      endTime: null,
      lastReadPosition: { stdout: 0, stderr: 0 },
    };

    this.setupProcessHandlers(task, resultPromise);
    this.tasks.set(taskId, task);

    debug('Started task %s: %s', taskId, command);
    return taskId;
  }

  private setupProcessHandlers(task: BackgroundTask, resultPromise: Promise<any>): void {
    // Setup stdout capture
    task.process.stdout?.on('data', (chunk: Buffer) => {
      const lines = chunk.toString().split('\n');
      task.stdout.push(...lines.filter(Boolean));
    });

    // Setup stderr capture
    task.process.stderr?.on('data', (chunk: Buffer) => {
      const lines = chunk.toString().split('\n');
      task.stderr.push(...lines.filter(Boolean));
    });

    // Wait for result and update task status
    resultPromise.then((result) => {
      task.exitCode = result.exitCode ?? null;
      task.endTime = new Date();
      task.status = result.exitCode === 0 ? 'completed' : 'failed';
      debug('Task %s exited with code %s', task.id, result.exitCode);
    }).catch((error) => {
      task.status = 'failed';
      task.endTime = new Date();
      task.stderr.push(`Process error: ${error.message}`);
      debug('Task %s error: %s', task.id, error.message);
    });
  }
}

Note: The implementation now reuses validateCommand and shellExecute from src/tools/bash.ts to ensure consistent command validation and execution behavior with the bash tool.

Step 4: Run test to verify it passes

Run: npm test src/utils/backgroundTasks.test.ts
Expected: PASS

Step 5: Add integration test with real process

Add to src/utils/backgroundTasks.test.ts:

import { setTimeout } from 'node:timers/promises';

it('should capture stdout from background process', async () => {
  const manager = new BackgroundTaskManager('test-session');
  const taskId = await manager.startTask(
    'echo "line1" && echo "line2"',
    process.cwd(),
    5000,
  );

  // Wait for process to complete
  await setTimeout(500);

  const task = manager.getTask(taskId);
  expect(task?.stdout).toContain('line1');
  expect(task?.stdout).toContain('line2');
});

Step 6: Add getTask helper method

Add to src/utils/backgroundTasks.ts:

getTask(taskId: string): BackgroundTask | undefined {
  return this.tasks.get(taskId);
}

Step 7: Run integration test

Run: npm test src/utils/backgroundTasks.test.ts
Expected: PASS

---

Task 3: Implement Output Retrieval

Files:

• Modify: src/utils/backgroundTasks.ts
• Modify: src/utils/backgroundTasks.test.ts

Step 1: Write failing test for getTaskOutput (full mode)

Add to src/utils/backgroundTasks.test.ts:

it('should retrieve full task output', async () => {
  const manager = new BackgroundTaskManager('test-session');
  const taskId = await manager.startTask('echo "test output"', process.cwd(), 5000);
  
  await setTimeout(500);
  
  const output = manager.getTaskOutput(taskId, false, 'both');
  expect(output.stdout).toContain('test output');
  expect(output.combined).toContain('test output');
});

Step 2: Run test to verify it fails

Run: npm test src/utils/backgroundTasks.test.ts
Expected: FAIL with "manager.getTaskOutput is not a function"

Step 3: Implement getTaskOutput method

Add to src/utils/backgroundTasks.ts:

export interface TaskOutput {
  stdout: string;
  stderr: string;
  combined: string;
}

export class BackgroundTaskManager {
  // ... existing code ...

  getTaskOutput(
    taskId: string,
    incremental: boolean,
    stream: 'stdout' | 'stderr' | 'both' = 'both',
  ): TaskOutput {
    const task = this.tasks.get(taskId);
    if (!task) {
      throw new Error(`Task ${taskId} not found`);
    }

    const startStdout = incremental ? task.lastReadPosition.stdout : 0;
    const startStderr = incremental ? task.lastReadPosition.stderr : 0;

    const stdoutLines =
      stream === 'stderr' ? [] : task.stdout.slice(startStdout);
    const stderrLines =
      stream === 'stdout' ? [] : task.stderr.slice(startStderr);

    // Update read positions if incremental
    if (incremental) {
      task.lastReadPosition.stdout = task.stdout.length;
      task.lastReadPosition.stderr = task.stderr.length;
    }

    const stdout = stdoutLines.join('\n');
    const stderr = stderrLines.join('\n');
    const combined = [stdout, stderr].filter(Boolean).join('\n');

    return { stdout, stderr, combined };
  }
}

Step 4: Run test to verify it passes

Run: npm test src/utils/backgroundTasks.test.ts
Expected: PASS

Step 5: Write test for incremental output

Add to src/utils/backgroundTasks.test.ts:

it('should retrieve incremental output only', async () => {
  const manager = new BackgroundTaskManager('test-session');
  const taskId = await manager.startTask(
    'echo "first" && sleep 0.2 && echo "second"',
    process.cwd(),
    5000,
  );

  await setTimeout(100);
  const output1 = manager.getTaskOutput(taskId, true, 'both');
  expect(output1.stdout).toContain('first');

  await setTimeout(300);
  const output2 = manager.getTaskOutput(taskId, true, 'both');
  expect(output2.stdout).toContain('second');
  expect(output2.stdout).not.toContain('first');
});

Step 6: Run test to verify incremental works

Run: npm test src/utils/backgroundTasks.test.ts
Expected: PASS

---

Task 4: Implement Task Status and Cleanup

Files:

• Modify: src/utils/backgroundTasks.ts
• Modify: src/utils/backgroundTasks.test.ts

Step 1: Write failing test for getTaskStatus

Add to src/utils/backgroundTasks.test.ts:

it('should return task status', async () => {
  const manager = new BackgroundTaskManager('test-session');
  const taskId = await manager.startTask('echo "test"', process.cwd(), 5000);
  
  const status1 = manager.getTaskStatus(taskId);
  expect(status1.status).toBe('running');
  
  await setTimeout(500);
  
  const status2 = manager.getTaskStatus(taskId);
  expect(status2.status).toBe('completed');
  expect(status2.exitCode).toBe(0);
});

Step 2: Run test to verify it fails

Run: npm test src/utils/backgroundTasks.test.ts
Expected: FAIL with "manager.getTaskStatus is not a function"

Step 3: Implement getTaskStatus

Add to src/utils/backgroundTasks.ts:

export interface TaskStatus {
  id: string;
  command: string;
  status: 'running' | 'completed' | 'failed';
  exitCode: number | null;
  startTime: Date;
  endTime: Date | null;
  duration: number | null;
}

export class BackgroundTaskManager {
  // ... existing code ...

  getTaskStatus(taskId: string): TaskStatus {
    const task = this.tasks.get(taskId);
    if (!task) {
      throw new Error(`Task ${taskId} not found`);
    }

    const duration = task.endTime
      ? task.endTime.getTime() - task.startTime.getTime()
      : null;

    return {
      id: task.id,
      command: task.command,
      status: task.status,
      exitCode: task.exitCode,
      startTime: task.startTime,
      endTime: task.endTime,
      duration,
    };
  }
}

Step 4: Run test to verify it passes

Run: npm test src/utils/backgroundTasks.test.ts
Expected: PASS

Step 5: Write failing test for cleanup

Add to src/utils/backgroundTasks.test.ts:

it('should cleanup all tasks', async () => {
  const manager = new BackgroundTaskManager('test-session');
  await manager.startTask('sleep 10', process.cwd(), 60000);
  await manager.startTask('sleep 10', process.cwd(), 60000);
  
  expect(manager.getTaskCount()).toBe(2);
  
  manager.cleanup();
  
  expect(manager.getTaskCount()).toBe(0);
});

Step 6: Run test to verify it fails

Run: npm test src/utils/backgroundTasks.test.ts
Expected: FAIL with "manager.cleanup is not a function"

Step 7: Implement cleanup method

Add to src/utils/backgroundTasks.ts:

export class BackgroundTaskManager {
  // ... existing code ...

  cleanup(): void {
    debug('Cleaning up %d tasks for session %s', this.tasks.size, this.sessionId);
    
    for (const [taskId, task] of this.tasks.entries()) {
      if (task.status === 'running') {
        try {
          task.process.kill('SIGTERM');
          debug('Killed task %s', taskId);
        } catch (error) {
          debug('Failed to kill task %s: %s', taskId, error);
        }
      }
    }

    this.tasks.clear();
  }

  getAllTasks(): TaskStatus[] {
    return Array.from(this.tasks.values()).map((task) =>
      this.getTaskStatus(task.id),
    );
  }
}

Step 8: Run test to verify it passes

Run: npm test src/utils/backgroundTasks.test.ts
Expected: PASS

Step 9: Commit

Run: git add src/utils/backgroundTasks.ts src/utils/backgroundTasks.test.ts
Run: git commit -m "feat: implement task status and cleanup"

---

Task 5: Integrate Manager into Context

Files:

• Modify: src/context.ts
• Read for reference: src/session.ts

Step 1: Add BackgroundTaskManager to Context interface

In src/context.ts, find the Context type and add:

import type { BackgroundTaskManager } from './utils/backgroundTasks';

export type Context = {
  // ... existing properties ...
  backgroundTaskManager?: BackgroundTaskManager;
};

Step 2: Initialize manager in session creation

In src/session.ts, find where Context is created and add:

import { BackgroundTaskManager } from './utils/backgroundTasks';

// In the function that creates context (likely createSession or similar)
const backgroundTaskManager = new BackgroundTaskManager(sessionId);

const context: Context = {
  // ... existing properties ...
  backgroundTaskManager,
};

Step 3: Add cleanup hook in session end

In src/session.ts, find where session cleanup happens and add:

// In cleanup/exit handler
if (context.backgroundTaskManager) {
  context.backgroundTaskManager.cleanup();
}

Step 4: Run typecheck

Run: npm run typecheck
Expected: No errors

---

Task 6: Extend bash Tool with Background Support

Files:

• Modify: src/tools/bash.ts

Step 1: Add background parameter to schema

In src/tools/bash.ts, modify the parameters object:

parameters: z.object({
  command: z.string().describe('The command to execute'),
  timeout: z
    .number()
    .optional()
    .nullable()
    .describe(`Optional timeout in milliseconds (max ${MAX_TIMEOUT})`),
  background: z
    .boolean()
    .optional()
    .default(false)
    .describe('Run command in background and return task ID'),
}),

Step 2: Update createBashTool to accept context

Modify function signature:

export function createBashTool(opts: { cwd: string; context?: Context }) {
  return createTool({
    // ... existing config ...

Step 3: Add background execution logic

In the execute function, before the existing logic:

execute: async ({ command, timeout = DEFAULT_TIMEOUT, background = false }) => {
  try {
    if (!command) {
      return {
        llmContent: 'Error: Command cannot be empty.',
        isError: true,
      };
    }

    // Background task handling
    if (background) {
      const manager = opts.context?.backgroundTaskManager;
      if (!manager) {
        return {
          llmContent:
            'Error: Background tasks are not supported in this session.',
          isError: true,
        };
      }

      const validationError = validateCommand(command);
      if (validationError) {
        return {
          isError: true,
          llmContent: validationError,
        };
      }

      const taskId = await manager.startTask(
        command,
        timeout || DEFAULT_TIMEOUT,
        opts.cwd,
      );

      return {
        llmContent: [
          `Background task started successfully`,
          `Task ID: ${taskId}`,
          `Command: ${command}`,
          `Use bash_output tool with task_id="${taskId}" to retrieve output`,
        ].join('\n'),
        returnDisplay: `Task ${taskId} started`,
      };
    }

    // Existing synchronous execution logic
    return await executeCommand(
      command,
      timeout || DEFAULT_TIMEOUT,
      opts.cwd,
    );
  } catch (e) {
    // ... existing error handling ...
  }
},

Step 4: Update tool description

Add to the description string:

description:
  `Run shell commands in the terminal, ensuring proper handling and security measures.

Before using this tool, please follow these steps:
- Verify that the command is not one of the banned commands: ${BANNED_COMMANDS.join(', ')}.
- Always quote file paths that contain spaces with double quotes (e.g., cd "path with spaces/file.txt")
- Capture the output of the command.

Notes:
- The command argument is required.
- Set background=true to run command in background and get a task ID for later output retrieval.
- You can specify an optional timeout in milliseconds (up to ${MAX_TIMEOUT}ms / 10 minutes). If not specified, commands will timeout after 30 minutes.
// ... rest of existing description ...
`.trim(),

Step 5: Run typecheck

Run: npm run typecheck
Expected: No errors

---

Task 7: Create bash_output Tool

Files:

• Modify: src/tools/bash.ts
• Modify: src/constants.ts

Step 1: Add BASH_OUTPUT to tool names

In src/constants.ts, find TOOL_NAMES and add:

export const TOOL_NAMES = {
  // ... existing tools ...
  BASH_OUTPUT: 'bash_output',
} as const;

Step 2: Create bash_output tool function

Add to end of src/tools/bash.ts:

export function createBashOutputTool(opts: { context?: Context }) {
  return createTool({
    name: TOOL_NAMES.BASH_OUTPUT,
    description: `Retrieve output from a background bash task.

Usage:
- Provide the task_id returned from a background bash command
- Set incremental=true to only get new output since last read (default: false)
- Set stream to control which output to retrieve: 'stdout', 'stderr', or 'both' (default: 'both')

The tool returns:
- Current task status (running/completed/failed)
- Exit code (if task completed)
- Output from the specified stream(s)

Example:
- Get all output: bash_output(task_id="abc-123")
- Get new output only: bash_output(task_id="abc-123", incremental=true)
- Get only stderr: bash_output(task_id="abc-123", stream="stderr")
`.trim(),
    parameters: z.object({
      task_id: z.string().describe('Background task ID to retrieve output from'),
      incremental: z
        .boolean()
        .optional()
        .default(false)
        .describe('Only return new output since last read'),
      stream: z
        .enum(['stdout', 'stderr', 'both'])
        .optional()
        .default('both')
        .describe('Which output stream to retrieve'),
    }),
    getDescription: ({ params }) => {
      const taskId = params.task_id as string;
      const incremental = params.incremental as boolean;
      return `Get ${incremental ? 'new' : 'all'} output from task ${taskId}`;
    },
    execute: async ({ task_id, incremental = false, stream = 'both' }) => {
      const manager = opts.context?.backgroundTaskManager;
      if (!manager) {
        return {
          llmContent: 'Error: Background tasks are not supported in this session.',
          isError: true,
        };
      }

      try {
        const status = manager.getTaskStatus(task_id);
        const output = manager.getTaskOutput(task_id, incremental, stream);

        const llmContent = [
          `Task ID: ${task_id}`,
          `Command: ${status.command}`,
          `Status: ${status.status}`,
          `Exit Code: ${status.exitCode ?? '(still running)'}`,
          `Duration: ${status.duration ? `${status.duration}ms` : '(in progress)'}`,
          `Stdout: ${output.stdout || '(empty)'}`,
          `Stderr: ${output.stderr || '(empty)'}`,
        ].join('\n');

        const displayMessage = output.combined
          ? truncateOutput(output.combined)
          : `Task ${status.status}, no output`;

        return {
          llmContent,
          returnDisplay: displayMessage,
        };
      } catch (error) {
        return {
          llmContent:
            error instanceof Error
              ? `Error retrieving task output: ${error.message}`
              : 'Error retrieving task output',
          isError: true,
        };
      }
    },
    approval: {
      category: 'read',
      needsApproval: async () => false, // Reading output doesn't need approval
    },
  });
}

Step 3: Run typecheck

Run: npm run typecheck
Expected: No errors

---

Task 8: Register Tools in Context

Files:

• Read: src/tool.ts (to understand tool registration)
• Modify: File where tools are registered (likely src/index.ts or src/context.ts)

Step 1: Find tool registration location

Run: rg "createBashTool" src --type ts
Expected: Find where bash tool is created and registered

Step 2: Update bash tool creation to pass context

In the file found above, modify:

// Old:
const bashTool = createBashTool({ cwd });

// New:
const bashTool = createBashTool({ cwd, context });

Step 3: Add bash_output tool registration

In the same location:

import { createBashTool, createBashOutputTool } from './tools/bash';

// Add after bash tool
const bashOutputTool = createBashOutputTool({ context });

Step 4: Add to tools array/map

Find where tools are collected and add:

// If it's an array:
const tools = [
  // ... existing tools ...
  bashTool,
  bashOutputTool,
];

// If it's a map:
tools.set(TOOL_NAMES.BASH_OUTPUT, bashOutputTool);

Step 5: Run typecheck

Run: npm run typecheck
Expected: No errors

---

Task 9: Add Memory Management and Limits

Files:

• Modify: src/utils/backgroundTasks.ts
• Modify: src/utils/backgroundTasks.test.ts

Step 1: Add constants for limits

At top of src/utils/backgroundTasks.ts:

const MAX_OUTPUT_LINES = 10000; // ~10MB at 1KB per line
const MAX_CONCURRENT_TASKS = 10;

Step 2: Write test for task limit

Add to src/utils/backgroundTasks.test.ts:

it('should enforce max concurrent tasks limit', async () => {
  const manager = new BackgroundTaskManager('test-session');
  
  // Start max allowed tasks
  for (let i = 0; i < 10; i++) {
    await manager.startTask('sleep 5', process.cwd(), 60000);
  }
  
  // Next task should fail
  await expect(
    manager.startTask('sleep 5', process.cwd(), 60000)
  ).rejects.toThrow('Maximum concurrent tasks reached');
});

Step 3: Implement task limit check

In src/utils/backgroundTasks.ts, modify startTask:

async startTask(
  command: string,
  cwd: string,
  timeout: number,
): Promise<string> {
  // Check concurrent task limit
  const runningTasks = Array.from(this.tasks.values()).filter(
    (t) => t.status === 'running',
  ).length;
  
  if (runningTasks >= MAX_CONCURRENT_TASKS) {
    throw new Error(
      `Maximum concurrent tasks reached (${MAX_CONCURRENT_TASKS}). ` +
      `Wait for existing tasks to complete or use cleanup.`,
    );
  }

  // ... rest of existing code ...
}

Step 4: Add output line truncation

Modify setupProcessHandlers stdout/stderr handlers:

private setupProcessHandlers(task: BackgroundTask, timeout: number): void {
  // Setup stdout capture with limit
  task.process.stdout?.on('data', (chunk: Buffer) => {
    const lines = chunk.toString().split('\n').filter(Boolean);
    task.stdout.push(...lines);
    
    // Truncate if exceeds limit
    if (task.stdout.length > MAX_OUTPUT_LINES) {
      const excess = task.stdout.length - MAX_OUTPUT_LINES;
      task.stdout.splice(0, excess);
      // Add truncation notice once
      if (!task.stdout[0]?.startsWith('[Output truncated]')) {
        task.stdout.unshift(
          `[Output truncated: removed ${excess} oldest lines]`,
        );
      }
    }
  });

  // Setup stderr capture with limit (same logic)
  task.process.stderr?.on('data', (chunk: Buffer) => {
    const lines = chunk.toString().split('\n').filter(Boolean);
    task.stderr.push(...lines);
    
    if (task.stderr.length > MAX_OUTPUT_LINES) {
      const excess = task.stderr.length - MAX_OUTPUT_LINES;
      task.stderr.splice(0, excess);
      if (!task.stderr[0]?.startsWith('[Output truncated]')) {
        task.stderr.unshift(
          `[Output truncated: removed ${excess} oldest lines]`,
        );
      }
    }
  });

  // ... rest of existing code ...
}

Step 5: Run tests

Run: npm test src/utils/backgroundTasks.test.ts
Expected: PASS

---

Task 11: Manual Testing

Step 1: Build the project

Run: npm run build
Expected: Build succeeds without errors

Step 2: Start interactive session

Run: ./dist/cli.mjs or npm start
Expected: CLI starts successfully

Step 3: Test background task

In CLI, test with LLM:

> Start a background task that echoes numbers 1-5 with 1 second delays

Expected: LLM uses bash with background=true, returns task ID

Step 4: Test output retrieval

> Check the output of task <task-id>

Expected: LLM uses bash_output, shows current output

Step 5: Test incremental mode

Wait a few seconds, then:

> Check for new output from task <task-id>

Expected: LLM uses bash_output with incremental=true, shows only new lines

Step 6: Test task completion

Wait for task to complete:

> Check status of task <task-id>

Expected: Shows status=completed, exit code 0

Step 7: Test error handling

> Start a background task that will fail

Expected: Task starts, can retrieve error output

Step 8: Test cleanup

Exit CLI and restart, verify old tasks are gone.

---

Task 12: Run Full Test Suite and CI

Step 1: Run all tests

Run: npm test
Expected: All tests pass

Step 2: Run typecheck

Run: npm run typecheck
Expected: No type errors

Step 3: Run formatting check

Run: npm run biome:format
Expected: All files properly formatted

Step 4: Fix any formatting issues

Run: npm run biome:format -- --write

Step 5: Run full CI pipeline

Run: npm run ci
Expected: All checks pass

Completion Checklist

• Export executeCommand and validateCommand from bash.ts for reuse
• BackgroundTaskManager created with tests
• Task starting and output capture working (using shellExecute)
• Incremental and full output retrieval working
• Task status and cleanup implemented
• Manager integrated into Context and Session
• bash tool extended with background parameter
• bash_output tool created and registered
• Memory limits and task limits enforced
• Documentation updated
• Manual testing completed
• All tests passing
• CI pipeline passing