@liangjie559567/ultrapower 5.5.20 → 5.5.21

package/dist/mcp/job-management.js

@@ -0,0 +1,825 @@
+/**
+ * Job Management - MCP tool handlers for background job lifecycle
+ *
+ * Provides four tools for managing background Codex/Gemini jobs:
+ * - wait_for_job: Poll-wait until a background job completes (or times out)
+ * - check_job_status: Non-blocking status check for a background job
+ * - kill_job: Send a signal to a running background job
+ * - list_jobs: List background jobs filtered by status
+ *
+ * All handlers are provider-scoped: each server hardcodes its provider and
+ * passes it as the first argument. Schemas omit provider since it's implicit.
+ */
+import { readJobStatus, readCompletedResponse, listActiveJobs, writeJobStatus, getPromptsDir, getJobWorkingDir, } from './prompt-persistence.js';
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { isSpawnedPid as isCodexSpawnedPid } from './codex-core.js';
+import { isSpawnedPid as isGeminiSpawnedPid } from './gemini-core.js';
+import { isJobDbInitialized, getJob, getActiveJobs as getActiveJobsFromDb, getJobsByStatus, updateJobStatus } from './job-state-db.js';
+import { createWorkerAdapter } from '../workers/factory.js';
+/** Signals allowed for kill_job. SIGKILL excluded - too dangerous for process groups. */
+const ALLOWED_SIGNALS = new Set(['SIGTERM', 'SIGINT']);
+/** Worker adapter instance (lazy initialized) */
+let adapterInstance = null;
+/**
+ * Get or create worker adapter instance
+ * Uses environment variable WORKER_BACKEND to control backend selection
+ */
+async function getAdapter(cwd) {
+    if (adapterInstance)
+        return adapterInstance;
+    const backend = process.env.WORKER_BACKEND || 'auto';
+    const workingDir = cwd || process.cwd();
+    if (backend === 'sqlite' || backend === 'json' || backend === 'auto') {
+        adapterInstance = await createWorkerAdapter(backend, workingDir);
+        // Auto-cleanup expired worker heartbeats on initialization
+        if (adapterInstance) {
+            const cleanupDays = parseInt(process.env.WORKER_CLEANUP_DAYS || '7', 10);
+            const maxAgeMs = cleanupDays * 24 * 60 * 60 * 1000;
+            adapterInstance.cleanup(maxAgeMs).catch(err => {
+                console.error('[MCP] Worker cleanup failed:', err);
+            });
+        }
+    }
+    return adapterInstance;
+}
+/**
+ * Convert JobStatus to WorkerState
+ */
+function jobStatusToWorkerState(job) {
+    return {
+        workerId: `${job.provider}:${job.jobId}`,
+        workerType: 'mcp',
+        name: job.jobId,
+        status: job.status,
+        pid: job.pid,
+        spawnedAt: job.spawnedAt,
+        lastHeartbeatAt: job.completedAt,
+        completedAt: job.completedAt,
+        provider: job.provider,
+        model: job.model,
+        agentRole: job.agentRole,
+        promptFile: job.promptFile,
+        responseFile: job.responseFile,
+        error: job.error,
+        metadata: {
+            slug: job.slug,
+            usedFallback: job.usedFallback,
+            fallbackModel: job.fallbackModel,
+            killedByUser: job.killedByUser,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Escape a string for safe inclusion in a RegExp
+ */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Standard MCP text result wrapper */
+function textResult(text, isError = false) {
+    return {
+        content: [{ type: 'text', text }],
+        ...(isError && { isError: true }),
+    };
+}
+/**
+ * Find the status file for a job by provider and jobId.
+ * Scans .omc/prompts/ for files matching the naming convention.
+ *
+ * Handles 0/1/many matches:
+ * - 0 matches: returns undefined
+ * - 1 match: returns { statusPath, slug }
+ * - Many matches: prefers non-terminal (active) status, then newest spawnedAt
+ */
+export function findJobStatusFile(provider, jobId, workingDirectory) {
+    // Validate jobId format: must be 16-char hex (from generatePromptId)
+    if (!/^[0-9a-f]{16}$/i.test(jobId)) {
+        return undefined;
+    }
+    const promptsDir = getPromptsDir(workingDirectory);
+    if (!existsSync(promptsDir))
+        return undefined;
+    try {
+        const files = readdirSync(promptsDir);
+        const escapedProvider = escapeRegex(provider);
+        const escapedJobId = escapeRegex(jobId);
+        const pattern = new RegExp(`^${escapedProvider}-status-(.+)-${escapedJobId}\\.json$`);
+        const matches = [];
+        for (const f of files) {
+            const m = f.match(pattern);
+            if (m) {
+                matches.push({
+                    file: f,
+                    slug: m[1],
+                    statusPath: join(promptsDir, f),
+                });
+            }
+        }
+        if (matches.length === 0)
+            return undefined;
+        if (matches.length === 1) {
+            return { statusPath: matches[0].statusPath, slug: matches[0].slug };
+        }
+        // Multiple matches: prefer non-terminal (active) status, then newest spawnedAt
+        let best;
+        for (const match of matches) {
+            try {
+                const content = readFileSync(match.statusPath, 'utf-8');
+                const status = JSON.parse(content);
+                const isActive = status.status === 'spawned' || status.status === 'running';
+                const spawnedAt = new Date(status.spawnedAt).getTime();
+                if (!best ||
+                    (isActive && !best.isActive) ||
+                    (isActive === best.isActive && spawnedAt > best.spawnedAt)) {
+                    best = { statusPath: match.statusPath, slug: match.slug, isActive, spawnedAt };
+                }
+            }
+            catch {
+                // Skip malformed files
+            }
+        }
+        if (best) {
+            return { statusPath: best.statusPath, slug: best.slug };
+        }
+        // Fallback to first match if all were malformed
+        return { statusPath: matches[0].statusPath, slug: matches[0].slug };
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// Tool Handlers
+// ---------------------------------------------------------------------------
+/**
+ * wait_for_job - block (poll) until a background job reaches a terminal state.
+ * Uses exponential backoff: 500ms base, 1.5x factor, 2000ms cap.
+ *
+ * WARNING: This function blocks the MCP request handler for the duration of the poll.
+ * For non-blocking checks, use handleCheckJobStatus instead.
+ */
+export async function handleWaitForJob(provider, jobId, timeoutMs = 3600000) {
+    if (!jobId || typeof jobId !== 'string') {
+        return textResult('job_id is required.', true);
+    }
+    const effectiveTimeout = Math.max(1000, Math.min(timeoutMs, 60_000));
+    const deadline = Date.now() + effectiveTimeout;
+    let pollDelay = 500;
+    let notFoundCount = 0;
+    while (Date.now() < deadline) {
+        // Try WorkerStateAdapter first
+        const adapter = await getAdapter();
+        if (adapter) {
+            const worker = await adapter.get(`${provider}:${jobId}`);
+            if (worker) {
+                if (worker.status === 'completed' || worker.status === 'failed' || worker.status === 'timeout') {
+                    if (worker.status === 'completed') {
+                        const slug = worker.metadata?.slug || '';
+                        const completed = readCompletedResponse(provider, slug, jobId);
+                        const responseSnippet = completed
+                            ? completed.response.substring(0, 500) + (completed.response.length > 500 ? '...' : '')
+                            : '(response file not found)';
+                        return textResult([
+                            `**Job ${jobId} completed.**`,
+                            `**Provider:** ${worker.provider}`,
+                            `**Model:** ${worker.model}`,
+                            `**Agent Role:** ${worker.agentRole}`,
+                            `**Response File:** ${worker.responseFile}`,
+                            worker.metadata?.usedFallback ? `**Fallback Model:** ${worker.metadata.fallbackModel}` : null,
+                            ``,
+                            `**Response preview:**`,
+                            responseSnippet,
+                        ].filter(Boolean).join('\n'));
+                    }
+                    return textResult([
+                        `**Job ${jobId} ${worker.status}.**`,
+                        `**Provider:** ${worker.provider}`,
+                        `**Model:** ${worker.model}`,
+                        `**Agent Role:** ${worker.agentRole}`,
+                        worker.error ? `**Error:** ${worker.error}` : null,
+                    ].filter(Boolean).join('\n'), true);
+                }
+                await new Promise(resolve => setTimeout(resolve, pollDelay));
+                pollDelay = Math.min(pollDelay * 1.5, 2000);
+                continue;
+            }
+        }
+        // Fallback to SQLite if adapter unavailable
+        if (isJobDbInitialized()) {
+            const status = getJob(provider, jobId);
+            if (status) {
+                if (status.status === 'completed' || status.status === 'failed' || status.status === 'timeout') {
+                    if (status.status === 'completed') {
+                        const completed = readCompletedResponse(status.provider, status.slug, status.jobId);
+                        const responseSnippet = completed
+                            ? completed.response.substring(0, 500) + (completed.response.length > 500 ? '...' : '')
+                            : '(response file not found)';
+                        return textResult([
+                            `**Job ${jobId} completed.**`,
+                            `**Provider:** ${status.provider}`,
+                            `**Model:** ${status.model}`,
+                            `**Agent Role:** ${status.agentRole}`,
+                            `**Response File:** ${status.responseFile}`,
+                            status.usedFallback ? `**Fallback Model:** ${status.fallbackModel}` : null,
+                            ``,
+                            `**Response preview:**`,
+                            responseSnippet,
+                        ].filter(Boolean).join('\n'));
+                    }
+                    return textResult([
+                        `**Job ${jobId} ${status.status}.**`,
+                        `**Provider:** ${status.provider}`,
+                        `**Model:** ${status.model}`,
+                        `**Agent Role:** ${status.agentRole}`,
+                        status.error ? `**Error:** ${status.error}` : null,
+                    ].filter(Boolean).join('\n'), true);
+                }
+                await new Promise(resolve => setTimeout(resolve, pollDelay));
+                pollDelay = Math.min(pollDelay * 1.5, 2000);
+                continue;
+            }
+        }
+        const jobDir = getJobWorkingDir(provider, jobId);
+        const found = findJobStatusFile(provider, jobId, jobDir);
+        if (!found) {
+            // Job may not be written yet (async SQLite init race) — retry with backoff
+            notFoundCount++;
+            if (notFoundCount >= 10) {
+                return textResult(`No job found with ID: ${jobId}`, true);
+            }
+            await new Promise(resolve => setTimeout(resolve, pollDelay));
+            pollDelay = Math.min(pollDelay * 1.5, 2000);
+            continue;
+        }
+        const status = readJobStatus(provider, found.slug, jobId);
+        if (!status) {
+            return textResult(`No job found with ID: ${jobId}`, true);
+        }
+        if (status.status === 'completed' || status.status === 'failed' || status.status === 'timeout') {
+            // Terminal state reached
+            if (status.status === 'completed') {
+                const completed = readCompletedResponse(status.provider, status.slug, status.jobId);
+                const responseSnippet = completed
+                    ? completed.response.substring(0, 500) + (completed.response.length > 500 ? '...' : '')
+                    : '(response file not found)';
+                return textResult([
+                    `**Job ${jobId} completed.**`,
+                    `**Provider:** ${status.provider}`,
+                    `**Model:** ${status.model}`,
+                    `**Agent Role:** ${status.agentRole}`,
+                    `**Response File:** ${status.responseFile}`,
+                    status.usedFallback ? `**Fallback Model:** ${status.fallbackModel}` : null,
+                    ``,
+                    `**Response preview:**`,
+                    responseSnippet,
+                ].filter(Boolean).join('\n'));
+            }
+            // failed or timeout
+            return textResult([
+                `**Job ${jobId} ${status.status}.**`,
+                `**Provider:** ${status.provider}`,
+                `**Model:** ${status.model}`,
+                `**Agent Role:** ${status.agentRole}`,
+                status.error ? `**Error:** ${status.error}` : null,
+            ].filter(Boolean).join('\n'), true);
+        }
+        // Still running - wait with exponential backoff and poll again
+        await new Promise(resolve => setTimeout(resolve, pollDelay));
+        pollDelay = Math.min(pollDelay * 1.5, 2000);
+    }
+    // Timed out waiting
+    return textResult(`Timed out waiting for job ${jobId} after ${timeoutMs}ms. The job is still running; use check_job_status to poll later.`, true);
+}
+/**
+ * check_job_status - non-blocking status check
+ */
+export async function handleCheckJobStatus(provider, jobId) {
+    if (!jobId || typeof jobId !== 'string') {
+        return textResult('job_id is required.', true);
+    }
+    // Try WorkerStateAdapter first
+    const adapter = await getAdapter();
+    if (adapter) {
+        const worker = await adapter.get(`${provider}:${jobId}`);
+        if (worker) {
+            const lines = [
+                `**Job ID:** ${jobId}`,
+                `**Provider:** ${worker.provider}`,
+                `**Status:** ${worker.status}`,
+                `**Model:** ${worker.model}`,
+                `**Agent Role:** ${worker.agentRole}`,
+                `**Spawned At:** ${worker.spawnedAt}`,
+                worker.completedAt ? `**Completed At:** ${worker.completedAt}` : null,
+                worker.pid ? `**PID:** ${worker.pid}` : null,
+                `**Prompt File:** ${worker.promptFile}`,
+                `**Response File:** ${worker.responseFile}`,
+                worker.error ? `**Error:** ${worker.error}` : null,
+                worker.metadata?.usedFallback ? `**Fallback Model:** ${worker.metadata.fallbackModel}` : null,
+                worker.metadata?.killedByUser ? `**Killed By User:** yes` : null,
+            ];
+            return textResult(lines.filter(Boolean).join('\n'));
+        }
+    }
+    // Fallback to SQLite
+    if (isJobDbInitialized()) {
+        const status = getJob(provider, jobId);
+        if (status) {
+            const lines = [
+                `**Job ID:** ${status.jobId}`,
+                `**Provider:** ${status.provider}`,
+                `**Status:** ${status.status}`,
+                `**Model:** ${status.model}`,
+                `**Agent Role:** ${status.agentRole}`,
+                `**Spawned At:** ${status.spawnedAt}`,
+                status.completedAt ? `**Completed At:** ${status.completedAt}` : null,
+                status.pid ? `**PID:** ${status.pid}` : null,
+                `**Prompt File:** ${status.promptFile}`,
+                `**Response File:** ${status.responseFile}`,
+                status.error ? `**Error:** ${status.error}` : null,
+                status.usedFallback ? `**Fallback Model:** ${status.fallbackModel}` : null,
+                status.killedByUser ? `**Killed By User:** yes` : null,
+            ];
+            return textResult(lines.filter(Boolean).join('\n'));
+        }
+    }
+    const jobDir = getJobWorkingDir(provider, jobId);
+    const found = findJobStatusFile(provider, jobId, jobDir);
+    if (!found) {
+        return textResult(`No job found with ID: ${jobId}`, true);
+    }
+    const status = readJobStatus(provider, found.slug, jobId);
+    if (!status) {
+        return textResult(`No job found with ID: ${jobId}`, true);
+    }
+    const lines = [
+        `**Job ID:** ${status.jobId}`,
+        `**Provider:** ${status.provider}`,
+        `**Status:** ${status.status}`,
+        `**Model:** ${status.model}`,
+        `**Agent Role:** ${status.agentRole}`,
+        `**Spawned At:** ${status.spawnedAt}`,
+        status.completedAt ? `**Completed At:** ${status.completedAt}` : null,
+        status.pid ? `**PID:** ${status.pid}` : null,
+        `**Prompt File:** ${status.promptFile}`,
+        `**Response File:** ${status.responseFile}`,
+        status.error ? `**Error:** ${status.error}` : null,
+        status.usedFallback ? `**Fallback Model:** ${status.fallbackModel}` : null,
+        status.killedByUser ? `**Killed By User:** yes` : null,
+    ];
+    return textResult(lines.filter(Boolean).join('\n'));
+}
+/**
+ * kill_job - send a signal to a running background job
+ */
+export async function handleKillJob(provider, jobId, signal = 'SIGTERM') {
+    if (!jobId || typeof jobId !== 'string') {
+        return textResult('job_id is required.', true);
+    }
+    if (!ALLOWED_SIGNALS.has(signal)) {
+        return textResult(`Invalid signal: ${signal}. Allowed signals: ${[...ALLOWED_SIGNALS].join(', ')}`, true);
+    }
+    // Try WorkerStateAdapter first
+    const adapter = await getAdapter();
+    if (adapter) {
+        const worker = await adapter.get(`${provider}:${jobId}`);
+        if (worker) {
+            if (worker.status !== 'spawned' && worker.status !== 'running') {
+                return textResult(`Job ${jobId} is already in terminal state: ${worker.status}. Cannot kill.`, true);
+            }
+            if (!worker.pid || !Number.isInteger(worker.pid) || worker.pid <= 0 || worker.pid > 4194304) {
+                return textResult(`Job ${jobId} has no valid PID recorded. Cannot send signal.`, true);
+            }
+            const isOurPid = provider === 'codex' ? isCodexSpawnedPid(worker.pid) : isGeminiSpawnedPid(worker.pid);
+            if (!isOurPid) {
+                return textResult(`Job ${jobId} PID ${worker.pid} was not spawned by this process. Refusing to send signal for safety.`, true);
+            }
+            try {
+                if (process.platform !== 'win32') {
+                    process.kill(-worker.pid, signal);
+                }
+                else {
+                    process.kill(worker.pid, signal);
+                }
+                await adapter.upsert({
+                    ...worker,
+                    status: 'failed',
+                    completedAt: new Date().toISOString(),
+                    error: `Killed by user (signal: ${signal})`,
+                    metadata: { ...worker.metadata, killedByUser: true },
+                });
+                return textResult(`Sent ${signal} to job ${jobId} (PID ${worker.pid}). Job marked as failed.`);
+            }
+            catch (err) {
+                if (err.code === 'ESRCH') {
+                    await adapter.upsert({
+                        ...worker,
+                        status: 'failed',
+                        completedAt: new Date().toISOString(),
+                        error: `Killed by user (process already exited, signal: ${signal})`,
+                        metadata: { ...worker.metadata, killedByUser: true },
+                    });
+                    return textResult(`Process ${worker.pid} already exited. Job marked as failed.`);
+                }
+                return textResult(`Failed to kill process ${worker.pid}: ${err.message}`, true);
+            }
+        }
+    }
+    const jobDir = getJobWorkingDir(provider, jobId);
+    const found = findJobStatusFile(provider, jobId, jobDir);
+    if (!found) {
+        // SQLite fallback
+        if (isJobDbInitialized()) {
+            const dbJob = getJob(provider, jobId);
+            if (dbJob) {
+                if (dbJob.status !== 'spawned' && dbJob.status !== 'running') {
+                    return textResult(`Job ${jobId} is already in terminal state: ${dbJob.status}. Cannot kill.`, true);
+                }
+                if (!dbJob.pid || !Number.isInteger(dbJob.pid) || dbJob.pid <= 0 || dbJob.pid > 4194304) {
+                    return textResult(`Job ${jobId} has no valid PID recorded. Cannot send signal.`, true);
+                }
+                const isOurPid = provider === 'codex' ? isCodexSpawnedPid(dbJob.pid) : isGeminiSpawnedPid(dbJob.pid);
+                if (!isOurPid) {
+                    return textResult(`Job ${jobId} PID ${dbJob.pid} was not spawned by this process. Refusing to send signal for safety.`, true);
+                }
+                // Send signal first, THEN update status based on outcome
+                try {
+                    if (process.platform !== 'win32') {
+                        process.kill(-dbJob.pid, signal);
+                    }
+                    else {
+                        process.kill(dbJob.pid, signal);
+                    }
+                    // Signal sent successfully - mark as killed in DB
+                    updateJobStatus(provider, jobId, {
+                        status: 'failed',
+                        killedByUser: true,
+                        completedAt: new Date().toISOString(),
+                        error: `Killed by user (signal: ${signal})`,
+                    });
+                    return textResult(`Sent ${signal} to job ${jobId} (PID ${dbJob.pid}). Job marked as failed.`);
+                }
+                catch (err) {
+                    if (err.code === 'ESRCH') {
+                        // Process already exited - mark as failed
+                        updateJobStatus(provider, jobId, {
+                            status: 'failed',
+                            killedByUser: true,
+                            completedAt: new Date().toISOString(),
+                            error: `Killed by user (process already exited, signal: ${signal})`,
+                        });
+                        return textResult(`Process ${dbJob.pid} already exited. Job marked as failed.`);
+                    }
+                    // Other kill errors - do NOT update status to avoid inconsistent state
+                    return textResult(`Failed to kill process ${dbJob.pid}: ${err.message}`, true);
+                }
+            }
+        }
+        return textResult(`No job found with ID: ${jobId}`, true);
+    }
+    const status = readJobStatus(provider, found.slug, jobId);
+    if (!status) {
+        return textResult(`No job found with ID: ${jobId}`, true);
+    }
+    if (status.status !== 'spawned' && status.status !== 'running') {
+        return textResult(`Job ${jobId} is already in terminal state: ${status.status}. Cannot kill.`, true);
+    }
+    if (!status.pid) {
+        return textResult(`Job ${jobId} has no PID recorded. Cannot send signal.`, true);
+    }
+    // Validate PID is a reasonable positive integer
+    if (!Number.isInteger(status.pid) || status.pid <= 0 || status.pid > 4194304) {
+        return textResult(`Job ${jobId} has invalid PID: ${status.pid}. Refusing to send signal.`, true);
+    }
+    // Verify this PID was spawned by us
+    const isOurPid = provider === 'codex'
+        ? isCodexSpawnedPid(status.pid)
+        : isGeminiSpawnedPid(status.pid);
+    if (!isOurPid) {
+        return textResult(`Job ${jobId} PID ${status.pid} was not spawned by this process. Refusing to send signal for safety.`, true);
+    }
+    const updated = {
+        ...status,
+        killedByUser: true,
+    };
+    try {
+        // On POSIX, background jobs are spawned detached as process-group leaders.
+        // Kill the whole process group so child processes also terminate.
+        if (process.platform !== 'win32') {
+            process.kill(-status.pid, signal);
+        }
+        else {
+            process.kill(status.pid, signal);
+        }
+        // Update status to failed
+        writeJobStatus({
+            ...updated,
+            status: 'failed',
+            killedByUser: true,
+            completedAt: new Date().toISOString(),
+            error: `Killed by user (signal: ${signal})`,
+        });
+        // Retry loop: background handler may overwrite our 'failed' status
+        for (let attempt = 0; attempt < 3; attempt++) {
+            await new Promise(resolve => setTimeout(resolve, 50));
+            const recheckStatus = readJobStatus(provider, found.slug, jobId);
+            if (!recheckStatus || recheckStatus.status === 'failed') {
+                break; // Our write stuck, or status is already what we want
+            }
+            // Background handler overwrote - write again
+            writeJobStatus({
+                ...recheckStatus,
+                status: 'failed',
+                killedByUser: true,
+                completedAt: new Date().toISOString(),
+                error: `Killed by user (signal: ${signal})`,
+            });
+        }
+        return textResult(`Sent ${signal} to job ${jobId} (PID ${status.pid}). Job marked as failed.`);
+    }
+    catch (err) {
+        const currentStatus = readJobStatus(provider, found.slug, jobId);
+        const isESRCH = err.code === 'ESRCH';
+        let message;
+        if (isESRCH) {
+            if (currentStatus?.status === 'completed') {
+                message = `Process ${status.pid} already exited. Job ${jobId} completed successfully.`;
+            }
+            else {
+                message = `Process ${status.pid} already exited.`;
+                // Only mark as failed if not already completed
+                writeJobStatus({
+                    ...(currentStatus || updated),
+                    status: 'failed',
+                    killedByUser: true,
+                    completedAt: new Date().toISOString(),
+                    error: `Killed by user (process already exited, signal: ${signal})`,
+                });
+            }
+        }
+        else {
+            message = `Failed to kill process ${status.pid}: ${err.message}`;
+        }
+        return textResult(message, !isESRCH || currentStatus?.status !== 'completed');
+    }
+}
+/**
+ * list_jobs - list background jobs with status filter and limit.
+ * Provider is hardcoded per-server (passed as first arg).
+ */
+export async function handleListJobs(provider, statusFilter = 'active', limit = 50) {
+    // Try WorkerStateAdapter first
+    const adapter = await getAdapter();
+    if (adapter) {
+        let statusArray = [];
+        if (statusFilter === 'active') {
+            statusArray = ['spawned', 'running'];
+        }
+        else if (statusFilter === 'completed') {
+            statusArray = ['completed'];
+        }
+        else if (statusFilter === 'failed') {
+            statusArray = ['failed', 'timeout'];
+        }
+        else {
+            statusArray = ['spawned', 'running', 'completed', 'failed', 'timeout'];
+        }
+        const workers = await adapter.list({ workerType: 'mcp', provider, status: statusArray });
+        if (workers.length === 0) {
+            const filterDesc = statusFilter !== 'all' ? ` with status=${statusFilter}` : '';
+            return textResult(`No ${provider} jobs found${filterDesc}.`);
+        }
+        const limited = workers.slice(0, limit);
+        const lines = limited.map((worker) => {
+            const parts = [
+                `- **${worker.name}** [${worker.status}] ${worker.provider}/${worker.model} (${worker.agentRole})`,
+                `  Spawned: ${worker.spawnedAt}`,
+            ];
+            if (worker.completedAt)
+                parts.push(`  Completed: ${worker.completedAt}`);
+            if (worker.error)
+                parts.push(`  Error: ${worker.error}`);
+            if (worker.pid)
+                parts.push(`  PID: ${worker.pid}`);
+            return parts.join('\n');
+        });
+        return textResult(`**${limited.length} ${provider} job(s) found:**\n\n${lines.join('\n\n')}`);
+    }
+    // Fallback to original implementation
+    if (statusFilter === 'active') {
+        // Try SQLite first
+        if (isJobDbInitialized()) {
+            const activeJobs = getActiveJobsFromDb(provider);
+            if (activeJobs.length === 0) {
+                return textResult(`No active ${provider} jobs found.`);
+            }
+            const limited = activeJobs.slice(0, limit);
+            const lines = limited.map((job) => {
+                const parts = [
+                    `- **${job.jobId}** [${job.status}] ${job.provider}/${job.model} (${job.agentRole})`,
+                    `  Spawned: ${job.spawnedAt}`,
+                ];
+                if (job.pid)
+                    parts.push(`  PID: ${job.pid}`);
+                return parts.join('\n');
+            });
+            return textResult(`**${limited.length} active ${provider} job(s):**\n\n${lines.join('\n\n')}`);
+        }
+        const activeJobs = listActiveJobs(provider);
+        if (activeJobs.length === 0) {
+            return textResult(`No active ${provider} jobs found.`);
+        }
+        // Sort by spawnedAt descending (newest first), apply limit
+        activeJobs.sort((a, b) => new Date(b.spawnedAt).getTime() - new Date(a.spawnedAt).getTime());
+        const limited = activeJobs.slice(0, limit);
+        const lines = limited.map((job) => {
+            const parts = [
+                `- **${job.jobId}** [${job.status}] ${job.provider}/${job.model} (${job.agentRole})`,
+                `  Spawned: ${job.spawnedAt}`,
+            ];
+            if (job.pid)
+                parts.push(`  PID: ${job.pid}`);
+            return parts.join('\n');
+        });
+        return textResult(`**${limited.length} active ${provider} job(s):**\n\n${lines.join('\n\n')}`);
+    }
+    // Try SQLite first for non-active filters
+    if (isJobDbInitialized()) {
+        let dbJobs = [];
+        if (statusFilter === 'completed') {
+            dbJobs = getJobsByStatus(provider, 'completed');
+        }
+        else if (statusFilter === 'failed') {
+            dbJobs = [
+                ...getJobsByStatus(provider, 'failed'),
+                ...getJobsByStatus(provider, 'timeout'),
+            ];
+        }
+        else if (statusFilter === 'all') {
+            dbJobs = [
+                ...getActiveJobsFromDb(provider),
+                ...getJobsByStatus(provider, 'completed'),
+                ...getJobsByStatus(provider, 'failed'),
+                ...getJobsByStatus(provider, 'timeout'),
+            ];
+        }
+        const seen = new Set();
+        const uniqueJobs = [];
+        for (const job of dbJobs) {
+            if (!seen.has(job.jobId)) {
+                seen.add(job.jobId);
+                uniqueJobs.push(job);
+            }
+        }
+        if (uniqueJobs.length > 0) {
+            uniqueJobs.sort((a, b) => new Date(b.spawnedAt).getTime() - new Date(a.spawnedAt).getTime());
+            const limited = uniqueJobs.slice(0, limit);
+            const lines = limited.map((job) => {
+                const parts = [
+                    `- **${job.jobId}** [${job.status}] ${job.provider}/${job.model} (${job.agentRole})`,
+                    `  Spawned: ${job.spawnedAt}`,
+                ];
+                if (job.completedAt)
+                    parts.push(`  Completed: ${job.completedAt}`);
+                if (job.error)
+                    parts.push(`  Error: ${job.error}`);
+                if (job.pid)
+                    parts.push(`  PID: ${job.pid}`);
+                return parts.join('\n');
+            });
+            return textResult(`**${limited.length} ${provider} job(s) found:**\n\n${lines.join('\n\n')}`);
+        }
+    }
+    // For 'all', 'completed', 'failed': scan all status files for this provider
+    const promptsDir = getPromptsDir();
+    if (!existsSync(promptsDir)) {
+        return textResult(`No ${provider} jobs found.`);
+    }
+    try {
+        const files = readdirSync(promptsDir);
+        const statusFiles = files.filter((f) => f.startsWith(`${provider}-status-`) && f.endsWith('.json'));
+        const jobs = [];
+        for (const file of statusFiles) {
+            try {
+                const content = readFileSync(join(promptsDir, file), 'utf-8');
+                const job = JSON.parse(content);
+                // Apply status filter
+                if (statusFilter === 'completed' && job.status !== 'completed')
+                    continue;
+                if (statusFilter === 'failed' && job.status !== 'failed' && job.status !== 'timeout')
+                    continue;
+                // 'all' has no filter
+                jobs.push(job);
+            }
+            catch {
+                // Skip malformed files
+            }
+        }
+        if (jobs.length === 0) {
+            const filterDesc = statusFilter !== 'all' ? ` with status=${statusFilter}` : '';
+            return textResult(`No ${provider} jobs found${filterDesc}.`);
+        }
+        // Sort by spawnedAt descending (newest first), apply limit
+        jobs.sort((a, b) => new Date(b.spawnedAt).getTime() - new Date(a.spawnedAt).getTime());
+        const limited = jobs.slice(0, limit);
+        const lines = limited.map((job) => {
+            const parts = [
+                `- **${job.jobId}** [${job.status}] ${job.provider}/${job.model} (${job.agentRole})`,
+                `  Spawned: ${job.spawnedAt}`,
+            ];
+            if (job.completedAt)
+                parts.push(`  Completed: ${job.completedAt}`);
+            if (job.error)
+                parts.push(`  Error: ${job.error}`);
+            if (job.pid)
+                parts.push(`  PID: ${job.pid}`);
+            return parts.join('\n');
+        });
+        return textResult(`**${limited.length} ${provider} job(s) found:**\n\n${lines.join('\n\n')}`);
+    }
+    catch (err) {
+        return textResult(`Error listing jobs: ${err.message}`, true);
+    }
+}
+// ---------------------------------------------------------------------------
+// Tool Schema Definitions (for both SDK and standalone servers)
+// ---------------------------------------------------------------------------
+// TODO: _provider parameter reserved for future per-provider schema customization
+export function getJobManagementToolSchemas(_provider) {
+    return [
+        {
+            name: 'wait_for_job',
+            description: 'Block (poll) until a background job reaches a terminal state (completed, failed, or timeout). Uses exponential backoff. Returns the response preview on success. WARNING: This tool blocks the MCP server for the duration of the poll. Prefer check_job_status for non-blocking status checks.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    job_id: {
+                        type: 'string',
+                        description: 'The job ID returned when the background job was dispatched.',
+                    },
+                    timeout_ms: {
+                        type: 'number',
+                        description: 'Maximum time to wait in milliseconds (default: 3600000, max: 60000).',
+                    },
+                },
+                required: ['job_id'],
+            },
+        },
+        {
+            name: 'check_job_status',
+            description: 'Non-blocking status check for a background job. Returns current status, metadata, and error information if available.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    job_id: {
+                        type: 'string',
+                        description: 'The job ID returned when the background job was dispatched.',
+                    },
+                },
+                required: ['job_id'],
+            },
+        },
+        {
+            name: 'kill_job',
+            description: 'Send a signal to a running background job. Marks the job as failed. Only works on jobs in spawned or running state.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    job_id: {
+                        type: 'string',
+                        description: 'The job ID of the running job to kill.',
+                    },
+                    signal: {
+                        type: 'string',
+                        enum: ['SIGTERM', 'SIGINT'],
+                        description: 'The signal to send (default: SIGTERM). Only SIGTERM and SIGINT are allowed.',
+                    },
+                },
+                required: ['job_id'],
+            },
+        },
+        {
+            name: 'list_jobs',
+            description: 'List background jobs for this provider. Filter by status and limit results. Results sorted newest first.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    status_filter: {
+                        type: 'string',
+                        enum: ['active', 'completed', 'failed', 'all'],
+                        description: 'Filter jobs by status (default: active).',
+                    },
+                    limit: {
+                        type: 'number',
+                        description: 'Maximum number of jobs to return (default: 50).',
+                    },
+                },
+                required: [],
+            },
+        },
+    ];
+}
+//# sourceMappingURL=job-management.js.map