@thegitai/cli 1.0.0-beta.15 → 1.0.0-beta.17

package/dist/bin/ai.js

@@ -16,6 +16,8 @@ import { formatSessionExitNotice } from '../src/session-exit.js';
 import { formatUsageText } from '../src/usage.js';
 import { formatVersionLine } from '../src/version.js';
 import { parseArgs } from '../src/cli-args.js';
+import { getJobBufferedOutput, killBackgroundJob, killAllBackgroundJobs, listBackgroundJobs, setBackgroundJobSession, } from '../src/background-jobs.js';
+import { collectBackgroundJobUiKillMutations, collectBackgroundJobUiOutputMutations, } from '../src/tool-executor.js';
 const DEFAULT_SERVER_URL = 'https://thegit.ai';
 const { auth, chat, models, sessions } = ServerApi;
 function printUsage() {
@@ -126,6 +128,15 @@ function modelLabel(serverModels, modelId) {
     return (serverModels.models.find((model) => model.id === modelId)?.label ??
         'Unknown model');
 }
+function formatJobElapsedMs(ms) {
+    const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+    if (totalSeconds < 60)
+        return `${totalSeconds}s`;
+    const minutes = Math.floor(totalSeconds / 60);
+    if (minutes < 60)
+        return `${minutes}m${String(totalSeconds % 60).padStart(2, '0')}s`;
+    return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, '0')}m`;
+}
 function makeConfirmCommand(session) {
     return async (command) => {
         console.log(chalk.bold(`\nCommand approval needed:\n${command}\n`));
@@ -237,6 +248,68 @@ async function mainInteractive({ authConfig, projectIndex, serverModels, serverS
             console.log(chalk.dim('Conversation cleared.\n'));
             continue;
         }
+        if (trimmed === '/jobs' || trimmed.startsWith('/jobs ')) {
+            const jobsArgs = trimmed.slice('/jobs'.length).trim();
+            const killMatch = jobsArgs.match(/^kill\s+(\S+)$/);
+            if (killMatch) {
+                const jobId = killMatch[1];
+                const killed = await killBackgroundJob(jobId);
+                await collectBackgroundJobUiKillMutations({
+                    session,
+                    projectIndex,
+                    jobId,
+                    result: killed,
+                });
+                if (!killed.ok) {
+                    console.log(chalk.red(killed.error ?? 'Background job kill failed.'));
+                }
+                else if (killed.alreadyFinished) {
+                    console.log(chalk.dim(`${jobId} had already finished.`));
+                }
+                continue;
+            }
+            const outputMatch = jobsArgs.match(/^output\s+(\S+)$/);
+            if (outputMatch) {
+                const jobId = outputMatch[1];
+                await collectBackgroundJobUiOutputMutations({
+                    session,
+                    projectIndex,
+                    jobId,
+                });
+                const job = listBackgroundJobs().find((candidate) => candidate.id === jobId);
+                const buffered = getJobBufferedOutput(jobId);
+                if (!job || !buffered) {
+                    console.log(chalk.red(`Unknown background job id: ${jobId}`));
+                    continue;
+                }
+                if (buffered.droppedChars > 0) {
+                    console.log(chalk.dim(`... (${buffered.droppedChars} chars of older output dropped) ...`));
+                }
+                console.log(buffered.output || chalk.dim('(no output captured)'));
+                continue;
+            }
+            if (jobsArgs) {
+                console.log(chalk.dim('Usage: /jobs — list · /jobs output <id> — full output · /jobs kill <id> — kill'));
+                continue;
+            }
+            const jobsList = listBackgroundJobs();
+            if (!jobsList.length) {
+                console.log(chalk.dim('No background jobs in this session.'));
+                continue;
+            }
+            for (const job of jobsList) {
+                const elapsed = formatJobElapsedMs((job.endedAt ?? Date.now()) - job.startedAt);
+                const stateText = job.status === 'running'
+                    ? `running · ${elapsed}`
+                    : job.status === 'killed'
+                        ? `killed · ran ${elapsed}`
+                        : job.status === 'error'
+                            ? 'failed to start'
+                            : `exited (code ${job.exitCode ?? 1}) · ran ${elapsed}`;
+                console.log(`${job.id} · ${stateText}\n    $ ${job.command}`);
+            }
+            continue;
+        }
         if (trimmed === '/resume') {
             const snapshot = await promptForResumeSession(session.rootDir, serverModels);
             if (!snapshot) {
@@ -244,6 +317,7 @@ async function mainInteractive({ authConfig, projectIndex, serverModels, serverS
                 continue;
             }
             applySessionSnapshot(session, snapshot);
+            setBackgroundJobSession(session.sessionId);
             await saveSessionBoth({ session, serverSessionClient });
             console.log(chalk.dim(`Resumed session${session.sessionName ? ` "${session.sessionName}"` : ''} (${session.sessionId})\n`));
             continue;
@@ -412,17 +486,24 @@ export async function main() {
     }
     printStartupBanner(rootDir, modelLabel(serverModels, session.modelId), session.autoYes);
     printSessionStartup(session);
-    await mainInteractive({
-        authConfig,
-        projectIndex,
-        serverModels,
-        serverSessionClient,
-        session,
-        usageText: async () => formatUsageText(await auth.fetchWhoamiResponse({ config: authConfig })),
-        initialPrompt,
-    });
-    await saveSessionBoth({ session, serverSessionClient });
-    printSessionExit(session);
+    setBackgroundJobSession(session.sessionId);
+    try {
+        await mainInteractive({
+            authConfig,
+            projectIndex,
+            serverModels,
+            serverSessionClient,
+            session,
+            usageText: async () => formatUsageText(await auth.fetchWhoamiResponse({ config: authConfig })),
+            initialPrompt,
+        });
+        await saveSessionBoth({ session, serverSessionClient });
+        printSessionExit(session);
+    }
+    finally {
+        killAllBackgroundJobs({ sessionId: session.sessionId, remove: true });
+        setBackgroundJobSession(null);
+    }
 }
 main().catch((error) => {
     console.error(chalk.red(`\n✖ Error: ${error.message}\n`));

package/dist/src/agent-mode.js

@@ -12,6 +12,7 @@ const PLAN_MODE_TOOL_NAMES = new Set([
     'read_document',
     'analyze_image',
     'run_command',
+    'shell_job_output',
 ]);
 const PLAN_MODE_RUN_COMMAND_NAMES = new Set([
     'pwd',
@@ -117,6 +118,11 @@ export function buildAgentModeToolBlockedResult(mode, call) {
     }
     if (call.name !== 'run_command')
         return null;
+    if (call.args?.background === true ||
+        call.args?.run_in_background === true ||
+        call.args?.runInBackground === true) {
+        return buildPlanModeToolBlockedResult(call.name, PLAN_MODE_RUN_COMMAND_ACTION);
+    }
     const command = String(call.args?.command ?? call.args?.cmd ?? '');
     const reason = planModeRunCommandBlockReason(command);
     return reason ? buildPlanModeToolBlockedResult(call.name, reason) : null;

package/dist/src/api/chat.js

@@ -1,3 +1,4 @@
+import { drainBackgroundJobNotifications } from '../background-jobs.js';
 import { createPromptCheckpoint, sanitizeSessionSafetyForServer, } from '../session-safety.js';
 import { applySessionSnapshot, snapshotFromSession, } from '../session-store.js';
 import { executeLocalToolCall } from '../tool-executor.js';
@@ -65,7 +66,9 @@ function snapshotForServer(session) {
     return snapshot;
 }
 function imageAttachmentsForServer(attachments) {
-    return (attachments ?? []).map(({ filePath: _filePath, ...attachment }) => attachment);
+    return (attachments ?? []).map(({ filePath, ...attachment }) => attachment.source === 'file' && filePath
+        ? { ...attachment, filePath }
+        : attachment);
 }
 function userHistoryText(entry) {
     return (entry.parts ?? [])
@@ -146,6 +149,35 @@ function publicStatusMessage(data) {
         return `Running ${toolName} locally...`;
     return null;
 }
+function normalizeShellJobToolCall(call) {
+    if (call.name !== 'shell_job_output' && call.name !== 'shell_job_kill') {
+        return call;
+    }
+    const args = call.args && typeof call.args === 'object' && !Array.isArray(call.args)
+        ? { ...call.args }
+        : {};
+    let changed = false;
+    if (args.job_id === undefined) {
+        const alias = args.jobId ?? args.id;
+        if (alias !== undefined) {
+            args.job_id = alias;
+            delete args.jobId;
+            delete args.id;
+            changed = true;
+        }
+    }
+    if (call.name === 'shell_job_output' && args.wait_ms === undefined) {
+        const alias = args.waitMs ?? args.wait ?? args.wait_millis;
+        if (alias !== undefined) {
+            args.wait_ms = alias;
+            delete args.waitMs;
+            delete args.wait;
+            delete args.wait_millis;
+            changed = true;
+        }
+    }
+    return changed ? { ...call, args } : call;
+}
 async function postToolResult({ config, turnId, event, result, session, fetchImpl, traceId, }) {
     const payload = {
         toolCallId: event.call.id,
@@ -186,8 +218,9 @@ async function executeAndPostToolResult({ config, projectIndex, session, event,
         }
     }
     try {
-        const rawResult = await executeLocalToolCall({ projectIndex }, session, event.call);
-        preserveCancelledTurnToolResult(session, input, event, rawResult);
+        const call = normalizeShellJobToolCall(event.call);
+        const rawResult = await executeLocalToolCall({ projectIndex }, session, call);
+        preserveCancelledTurnToolResult(session, input, { ...event, call }, rawResult);
         if (signal?.aborted) {
             throw new TurnCancelledError();
         }
@@ -293,14 +326,18 @@ export async function sendServerUserMessage({ config, projectIndex, session, inp
     const requestImageAttachments = autoAttach.attachments.length > 0
         ? [...imageAttachments, ...autoAttach.attachments]
         : imageAttachments;
-    const requestInput = autoAttach.attachments.length > 0 ? autoAttach.sanitizedInput : input;
+    const requestInputBase = autoAttach.attachments.length > 0 ? autoAttach.sanitizedInput : input;
+    const backgroundJobUpdate = drainBackgroundJobNotifications({
+        sessionId: session.sessionId,
+    });
     for (const err of autoAttach.errors) {
         session.onStatus(`Image: ${err}`);
     }
     const request = {
         modelId: session.modelId,
         session: snapshotForServer(session),
-        input: requestInput,
+        input: requestInputBase,
+        backgroundJobUpdate: backgroundJobUpdate || undefined,
         clientEnvironment: collectClientEnvironment({ env: session.env }),
         imageAttachments: imageAttachmentsForServer(requestImageAttachments),
         maxToolSteps: session.maxToolSteps,
@@ -309,7 +346,7 @@ export async function sendServerUserMessage({ config, projectIndex, session, inp
     };
     const trace = createTraceContext();
     const preTurnHistoryLength = session.history.length;
-    const preserveOnAbort = () => preserveCancelledTurnInput(session, requestInput);
+    const preserveOnAbort = () => preserveCancelledTurnInput(session, requestInputBase);
     if (signal?.aborted) {
         preserveOnAbort();
     }
@@ -336,7 +373,7 @@ export async function sendServerUserMessage({ config, projectIndex, session, inp
             config,
             projectIndex,
             session,
-            input: requestInput,
+            input: requestInputBase,
             fetchImpl,
             signal,
             traceId: trace.traceId,
@@ -351,13 +388,13 @@ export async function sendServerUserMessage({ config, projectIndex, session, inp
     }
     catch (error) {
         if (isTurnCancelledError(error)) {
-            preserveCancelledTurnInput(session, requestInput);
+            preserveCancelledTurnInput(session, requestInputBase);
             throw error instanceof TurnCancelledError
                 ? error
                 : new TurnCancelledError();
         }
         session.history.length = preTurnHistoryLength;
-        preserveFailedTurnInput(session, requestInput, error instanceof ChatTurnFailedError ? error.category : 'unknown_error');
+        preserveFailedTurnInput(session, requestInputBase, error instanceof ChatTurnFailedError ? error.category : 'unknown_error');
         throw error;
     }
     finally {

package/dist/src/background-jobs.js

@@ -0,0 +1,410 @@
+import chalk from './colors.js';
+import { spawn } from 'child_process';
+import { buildCommandEnv, commandUsesSudo, sanitizeCommandText, terminateChild, } from './executor.js';
+import { isTuiMode } from './runtime-mode.js';
+import { redactConnectionStringCredentials } from './secret-preview.js';
+const MAX_RUNNING_JOBS = 8;
+const MAX_FINISHED_JOBS = 20;
+const MAX_JOB_BUFFER_CHARS = 200 * 1024;
+export const DEFAULT_STARTUP_WAIT_MS = 5000;
+export const MAX_JOB_WAIT_MS = 30_000;
+const KILL_ESCALATION_MS = 2000;
+const jobs = new Map();
+let jobCounter = 0;
+let activeSessionId = null;
+let updateHook = null;
+let exitCleanupRegistered = false;
+let pendingModelNotifications = [];
+export function setBackgroundJobUpdateHook(hook) {
+    updateHook = hook;
+}
+function normalizeSessionId(sessionId) {
+    return String(sessionId ?? activeSessionId ?? 'default').trim() || 'default';
+}
+function sessionFilter(sessionId) {
+    const value = String(sessionId ?? activeSessionId ?? '').trim();
+    return value || null;
+}
+function belongsToSession(record, sessionId) {
+    const filter = sessionFilter(sessionId);
+    return !filter || record.sessionId === filter;
+}
+export function setBackgroundJobSession(sessionId) {
+    const next = String(sessionId ?? '').trim() || null;
+    if (activeSessionId && activeSessionId !== next) {
+        killAllBackgroundJobs({ sessionId: activeSessionId, remove: true });
+        pendingModelNotifications = pendingModelNotifications.filter((snapshot) => snapshot.sessionId === next);
+    }
+    activeSessionId = next;
+}
+function snapshotOf(record) {
+    return {
+        id: record.id,
+        sessionId: record.sessionId,
+        command: record.command,
+        status: record.status,
+        pid: record.child.pid ?? null,
+        exitCode: record.exitCode,
+        signal: record.signal,
+        startedAt: record.startedAt,
+        endedAt: record.endedAt,
+    };
+}
+function notifyUpdate(record) {
+    if (!belongsToSession(record))
+        return;
+    try {
+        updateHook?.(snapshotOf(record));
+    }
+    catch { }
+}
+function logJobStatus(record) {
+    if (isTuiMode())
+        return;
+    if (record.status === 'running') {
+        console.log(chalk.cyan(`\n  ⚙ Background job ${record.id} started: ${record.command}`));
+        return;
+    }
+    if (record.status === 'killed') {
+        console.log(chalk.dim(`\n  ■ Background job ${record.id} killed.`));
+        return;
+    }
+    if (record.status === 'error') {
+        console.log(chalk.red(`\n  ✖ Background job ${record.id} failed to run.`));
+        return;
+    }
+    const color = record.exitCode === 0 ? chalk.green : chalk.red;
+    console.log(color(`\n  ${record.exitCode === 0 ? '✓' : '✖'} Background job ${record.id} exited with code ${record.exitCode ?? 1}`));
+}
+function appendJobOutput(record, chunk) {
+    if (!chunk)
+        return;
+    if (record.firstOutputLine == null) {
+        record.firstOutputFragment = `${record.firstOutputFragment}${chunk}`.slice(0, 8000);
+        const firstLine = record.firstOutputFragment
+            .split(/\r?\n/)
+            .find((line) => line.trim().length > 0);
+        if (firstLine) {
+            record.firstOutputLine = firstLine;
+        }
+    }
+    record.totalCaptured += chunk.length;
+    record.buffer += chunk;
+    if (record.buffer.length > MAX_JOB_BUFFER_CHARS) {
+        record.buffer = record.buffer.slice(record.buffer.length - MAX_JOB_BUFFER_CHARS);
+    }
+    const waiters = record.outputWaiters;
+    record.outputWaiters = [];
+    for (const waiter of waiters)
+        waiter();
+}
+function settleJob(record, status, exitCode, signal) {
+    if (record.status !== 'running')
+        return;
+    record.status = status;
+    record.exitCode = exitCode;
+    record.signal = signal;
+    record.endedAt = Date.now();
+    const waiters = [...record.exitWaiters, ...record.outputWaiters];
+    record.exitWaiters = [];
+    record.outputWaiters = [];
+    for (const waiter of waiters)
+        waiter();
+    if (jobs.has(record.id) && belongsToSession(record)) {
+        pendingModelNotifications.push(snapshotOf(record));
+    }
+    logJobStatus(record);
+    if (status === 'killed' || record.removeOnSettle) {
+        jobs.delete(record.id);
+    }
+    else {
+        pruneFinishedJobs();
+    }
+    notifyUpdate(record);
+}
+function pruneFinishedJobs() {
+    const finished = [...jobs.values()].filter((record) => record.status !== 'running');
+    if (finished.length <= MAX_FINISHED_JOBS)
+        return;
+    finished.sort((a, b) => (a.endedAt ?? 0) - (b.endedAt ?? 0));
+    for (const record of finished.slice(0, finished.length - MAX_FINISHED_JOBS)) {
+        jobs.delete(record.id);
+    }
+}
+function registerExitCleanup() {
+    if (exitCleanupRegistered)
+        return;
+    exitCleanupRegistered = true;
+    process.on('exit', () => {
+        for (const record of jobs.values()) {
+            if (record.status !== 'running')
+                continue;
+            terminateChild(record.child, 'SIGKILL');
+        }
+    });
+}
+function sanitizeJobText(record, raw) {
+    return redactConnectionStringCredentials(sanitizeCommandText(record.command, raw, record.cwd));
+}
+function readNewOutput(record) {
+    const dropped = record.totalCaptured - record.buffer.length;
+    const droppedUnread = Math.max(dropped - record.readOffset, 0);
+    const start = Math.max(record.readOffset - dropped, 0);
+    const raw = record.buffer.slice(start);
+    record.readOffset = record.totalCaptured;
+    return {
+        newOutput: sanitizeJobText(record, raw),
+        droppedChars: droppedUnread,
+    };
+}
+function waitForJobEvent(record, waitMs, kind) {
+    if (record.status !== 'running' || waitMs <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const waiters = kind === 'exit' ? record.exitWaiters : record.outputWaiters;
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const index = waiters.indexOf(finish);
+            if (index !== -1)
+                waiters.splice(index, 1);
+            resolve();
+        };
+        const timer = setTimeout(finish, Math.min(waitMs, MAX_JOB_WAIT_MS));
+        timer.unref?.();
+        waiters.push(finish);
+    });
+}
+export async function startBackgroundJob(command, cwd, { startupWaitMs, sessionId, } = {}) {
+    if (commandUsesSudo(command)) {
+        return {
+            ok: false,
+            error: 'sudo commands cannot run as background jobs because the password prompt is interactive. Run it in the foreground instead.',
+        };
+    }
+    const running = [...jobs.values()].filter((record) => record.status === 'running' && belongsToSession(record, sessionId));
+    if (running.length >= MAX_RUNNING_JOBS) {
+        return {
+            ok: false,
+            error: `Too many background jobs are already running (${running.length}). Kill one with shell_job_kill first.`,
+        };
+    }
+    registerExitCleanup();
+    const id = `bg_${++jobCounter}`;
+    const child = spawn(command, {
+        cwd,
+        shell: true,
+        detached: process.platform !== 'win32',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: buildCommandEnv(cwd),
+    });
+    child.stdin?.end();
+    const record = {
+        id,
+        sessionId: normalizeSessionId(sessionId),
+        command,
+        cwd,
+        child,
+        status: 'running',
+        exitCode: null,
+        signal: null,
+        startedAt: Date.now(),
+        endedAt: null,
+        buffer: '',
+        totalCaptured: 0,
+        readOffset: 0,
+        firstOutputLine: null,
+        firstOutputFragment: '',
+        killRequested: false,
+        removeOnSettle: false,
+        exitWaiters: [],
+        outputWaiters: [],
+    };
+    jobs.set(id, record);
+    child.stdout?.on('data', (chunk) => {
+        appendJobOutput(record, chunk.toString('utf-8'));
+    });
+    child.stderr?.on('data', (chunk) => {
+        appendJobOutput(record, chunk.toString('utf-8'));
+    });
+    child.on('error', (error) => {
+        appendJobOutput(record, error.message ? `${error.message}\n` : '');
+        terminateChild(child, 'SIGKILL');
+        settleJob(record, 'error', 1, null);
+    });
+    child.on('close', (code, signal) => {
+        settleJob(record, record.killRequested ? 'killed' : 'exited', code ?? (signal ? 1 : 0), signal);
+    });
+    logJobStatus(record);
+    notifyUpdate(record);
+    const waitMs = Math.min(Math.max(startupWaitMs ?? DEFAULT_STARTUP_WAIT_MS, 0), MAX_JOB_WAIT_MS);
+    await waitForJobEvent(record, waitMs, 'exit');
+    const { newOutput, droppedChars } = readNewOutput(record);
+    return {
+        ok: true,
+        snapshot: snapshotOf(record),
+        startupOutput: newOutput,
+        droppedChars,
+    };
+}
+export function getBackgroundJob(id, { sessionId } = {}) {
+    const record = jobs.get(String(id ?? '').trim());
+    return record && belongsToSession(record, sessionId) ? snapshotOf(record) : null;
+}
+export function listBackgroundJobs({ sessionId, } = {}) {
+    return [...jobs.values()]
+        .filter((record) => belongsToSession(record, sessionId))
+        .sort((a, b) => a.startedAt - b.startedAt)
+        .map(snapshotOf);
+}
+export function getJobOutputTail(id, maxLines) {
+    const record = jobs.get(String(id ?? '').trim());
+    if (!record || !belongsToSession(record) || maxLines <= 0)
+        return [];
+    const lines = sanitizeJobText(record, record.buffer)
+        .split('\n')
+        .filter((line) => line.trim().length > 0);
+    return lines.slice(-maxLines);
+}
+export function getJobOutputPreview(id, maxTailLines) {
+    const record = jobs.get(String(id ?? '').trim());
+    if (!record || !belongsToSession(record))
+        return null;
+    const firstLine = record.firstOutputLine
+        ? sanitizeJobText(record, record.firstOutputLine).trim()
+        : '';
+    return {
+        firstLine,
+        tailLines: getJobOutputTail(id, maxTailLines),
+    };
+}
+export function getJobBufferedOutput(id) {
+    const record = jobs.get(String(id ?? '').trim());
+    if (!record || !belongsToSession(record))
+        return null;
+    return {
+        output: sanitizeJobText(record, record.buffer),
+        droppedChars: Math.max(record.totalCaptured - record.buffer.length, 0),
+    };
+}
+export async function readBackgroundJobOutput(id, { waitMs, sessionId } = {}) {
+    const record = jobs.get(String(id ?? '').trim());
+    if (!record || !belongsToSession(record, sessionId)) {
+        return { ok: false, error: unknownJobError(id) };
+    }
+    if (waitMs && waitMs > 0 && record.status === 'running') {
+        const hasUnread = record.totalCaptured > record.readOffset;
+        if (!hasUnread)
+            await waitForJobEvent(record, waitMs, 'output');
+    }
+    const { newOutput, droppedChars } = readNewOutput(record);
+    return { ok: true, snapshot: snapshotOf(record), newOutput, droppedChars };
+}
+export async function killBackgroundJob(id, { waitMs = 5000, sessionId, } = {}) {
+    const record = jobs.get(String(id ?? '').trim());
+    if (!record || !belongsToSession(record, sessionId)) {
+        return { ok: false, error: unknownJobError(id) };
+    }
+    if (record.status !== 'running') {
+        const { newOutput, droppedChars } = readNewOutput(record);
+        const snapshot = snapshotOf(record);
+        if (record.status === 'killed') {
+            jobs.delete(record.id);
+        }
+        return {
+            ok: true,
+            alreadyFinished: true,
+            snapshot,
+            finalOutput: newOutput,
+            droppedChars,
+        };
+    }
+    record.killRequested = true;
+    terminateChild(record.child, 'SIGTERM');
+    const killTimer = setTimeout(() => {
+        if (record.status === 'running') {
+            terminateChild(record.child, 'SIGKILL');
+        }
+    }, KILL_ESCALATION_MS);
+    killTimer.unref?.();
+    await waitForJobEvent(record, Math.max(waitMs, KILL_ESCALATION_MS + 1000), 'exit');
+    clearTimeout(killTimer);
+    const { newOutput, droppedChars } = readNewOutput(record);
+    return {
+        ok: true,
+        snapshot: snapshotOf(record),
+        finalOutput: newOutput,
+        droppedChars,
+    };
+}
+export function killAllBackgroundJobs({ sessionId, remove = false, } = {}) {
+    for (const record of jobs.values()) {
+        if (!belongsToSession(record, sessionId))
+            continue;
+        if (record.status !== 'running')
+            continue;
+        record.killRequested = true;
+        record.removeOnSettle = record.removeOnSettle || remove;
+        terminateChild(record.child, 'SIGTERM');
+        const killTimer = setTimeout(() => {
+            if (record.status === 'running') {
+                terminateChild(record.child, 'SIGKILL');
+            }
+        }, KILL_ESCALATION_MS);
+        killTimer.unref?.();
+    }
+}
+export function hasRunningBackgroundJobs({ sessionId, } = {}) {
+    for (const record of jobs.values()) {
+        if (!belongsToSession(record, sessionId))
+            continue;
+        if (record.status === 'running')
+            return true;
+    }
+    return false;
+}
+function formatRunTime(snapshot) {
+    const ms = (snapshot.endedAt ?? Date.now()) - snapshot.startedAt;
+    const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+    if (totalSeconds < 60)
+        return `${totalSeconds}s`;
+    const minutes = Math.floor(totalSeconds / 60);
+    if (minutes < 60)
+        return `${minutes}m${String(totalSeconds % 60).padStart(2, '0')}s`;
+    return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, '0')}m`;
+}
+export function drainBackgroundJobNotifications({ sessionId } = {}) {
+    if (pendingModelNotifications.length === 0)
+        return null;
+    const filter = sessionFilter(sessionId);
+    const pending = filter
+        ? pendingModelNotifications.filter((snapshot) => snapshot.sessionId === filter)
+        : pendingModelNotifications;
+    pendingModelNotifications = filter
+        ? pendingModelNotifications.filter((snapshot) => snapshot.sessionId !== filter)
+        : [];
+    if (pending.length === 0)
+        return null;
+    const lines = pending.map((snapshot) => {
+        const ran = formatRunTime(snapshot);
+        if (snapshot.status === 'error') {
+            return `Background job ${snapshot.id} (${snapshot.command}) failed to start.`;
+        }
+        if (snapshot.status === 'killed') {
+            return `Background job ${snapshot.id} (${snapshot.command}) was killed after ${ran}.`;
+        }
+        return `Background job ${snapshot.id} (${snapshot.command}) exited with code ${snapshot.exitCode ?? 1} after ${ran}.`;
+    });
+    const hasReadableFinalOutput = pending.some((snapshot) => snapshot.status !== 'killed');
+    return `${lines.join(' ')}${hasReadableFinalOutput ? ' Use shell_job_output to read any final output.' : ''}`;
+}
+function unknownJobError(id) {
+    const known = listBackgroundJobs().map((job) => job.id);
+    const hint = known.length
+        ? ` Known jobs: ${known.join(', ')}.`
+        : ' No background jobs have been started this session.';
+    return `Unknown background job id: ${String(id ?? '').trim() || '(empty)'}.${hint}`;
+}