@felan-ai/ext-background-bash 0.5.0 → 0.6.0

package/dist/index.js

@@ -1,34 +1,39 @@
-import { StringEnum, createRuntimeCodingTools, } from '@felan-ai/agent-core';
+import { StringEnum, associateExtensionConfig, configField, createRuntimeCodingTools, defineExtensionConfig, } from '@felan-ai/agent-core';
 import { Key, Text } from '@earendil-works/pi-tui';
 import { Type } from 'typebox';
 import { normalizeBackgroundCommand } from './command-normalizer.js';
 import { isTerminalStatus, } from './job-store.js';
 import { BackgroundBashManager } from './process-manager.js';
+import { BackgroundBashCoordinator } from './coordinator.js';
 import { inspectBackgroundBashRuntime } from './runtime-support.js';
 import { BackgroundBashView } from './ui/background-bash-view.js';
 import { BACKGROUND_BASH_COMPLETION_MESSAGE_TYPE, registerBackgroundBashCompletionRenderer, } from './ui/completion-message.js';
 const STATUS_VALUES = ['running', 'completed', 'failed', 'killed', 'unknown', 'all'];
 const SIGNAL_VALUES = ['SIGTERM', 'SIGKILL'];
-const OPENAI_PROVIDER_IDS = new Set(['openai', 'openai-codex']);
 const COMPLETION_POLL_MS = 500;
 const BACKGROUND_TOOL_NAMES = [
     'list_background_bash',
     'read_background_bash',
     'wait_background_bash',
     'stop_background_bash',
+    'write_background_bash',
 ];
+export function supportsBackgroundBashModel(model) {
+    return model !== undefined;
+}
 const BashParams = Type.Object({
     command: Type.String({ description: 'Bash command to execute' }),
-    timeout: Type.Optional(Type.Number({ description: 'Timeout in seconds for foreground commands' })),
+    timeout: Type.Optional(Type.Number({ minimum: 0, description: 'Seconds to wait before promoting the same process to the background. Defaults to 120; 0 backgrounds immediately.' })),
     background: Type.Optional(Type.Boolean({
-        description: 'Start a detached background Bash process and return immediately',
+        description: 'Start a background process and return immediately',
     })),
+    tty: Type.Optional(Type.Boolean({ description: 'Start with a PTY so write_background_bash can send stdin and control bytes' })),
 }, { additionalProperties: false });
 const ListBackgroundBashParams = Type.Object({
     status: Type.Optional(StringEnum(STATUS_VALUES, { description: 'Filter processes by status' })),
 }, { additionalProperties: false });
 const ReadBackgroundBashParams = Type.Object({
-    id: Type.String({ description: 'Background Bash process id returned by bash(background: true)' }),
+    id: Type.String({ description: 'Background process id returned by bash' }),
     lines: Type.Optional(Type.Integer({
         minimum: 1,
         maximum: 1_000,
@@ -36,427 +41,502 @@ const ReadBackgroundBashParams = Type.Object({
     })),
 }, { additionalProperties: false });
 const WaitBackgroundBashParams = Type.Object({
-    id: Type.String({ description: 'Background Bash process id returned by bash(background: true)' }),
+    id: Type.String({ description: 'Background process id returned by bash' }),
     timeout: Type.Optional(Type.Number({ description: 'Maximum seconds to wait before returning current status' })),
 }, { additionalProperties: false });
 const StopBackgroundBashParams = Type.Object({
-    id: Type.String({ description: 'Background Bash process id returned by bash(background: true)' }),
+    id: Type.String({ description: 'Background process id returned by bash' }),
     signal: Type.Optional(StringEnum(SIGNAL_VALUES, { description: 'Signal to send. Default: SIGTERM.' })),
 }, { additionalProperties: false });
-export function supportsBackgroundBashModel(model) {
-    return model !== undefined && !OPENAI_PROVIDER_IDS.has(model.provider);
-}
-const backgroundBashExtension = (pi) => {
-    registerBackgroundBashCompletionRenderer(pi);
-    const manager = new BackgroundBashManager(pi.runtime);
-    const foregroundBash = createRuntimeCodingTools(pi.runtime, { shellFlavor: 'posix' })
-        .find((tool) => tool.name === 'bash');
-    let helperToolsRegistered = false;
-    let backgroundBashActive = false;
-    let controlsRegistered = false;
-    let statusTarget;
-    let statusPollTimer;
-    let statusUpdateRunning = false;
-    let statusGeneration = 0;
-    let completionPollingEnabled = false;
-    let completionPollTimer;
-    let completionPollGeneration = 0;
-    let completionPollRunningGeneration;
-    let runtimeAvailable;
-    let runtimeCheck;
-    const watchedJobIds = new Set();
-    const createStatusTarget = (ctx) => {
-        if (ctx.mode !== 'tui')
-            return undefined;
-        return { ui: ctx.ui, generation: statusGeneration };
-    };
-    const updateStatus = async (target) => {
-        if (!target || target.generation !== statusGeneration || statusUpdateRunning)
-            return;
-        statusUpdateRunning = true;
-        try {
-            const running = await manager.list('running');
-            if (target.generation !== statusGeneration)
-                return;
-            if (running.length === 0) {
-                target.ui.setStatus('background-bash', undefined);
+const WriteBackgroundBashParams = Type.Object({
+    id: Type.String({ description: 'Background process id returned by bash' }),
+    chars: Type.String({ description: 'Exact text or control bytes to write to a PTY process' }),
+}, { additionalProperties: false });
+export const BACKGROUND_BASH_CONFIG = defineExtensionConfig({
+    id: 'backgroundBash',
+    title: 'Background processes',
+    fields: {
+        foregroundTimeoutSeconds: configField.number({
+            default: 120,
+            description: 'Seconds before a foreground Bash command is promoted to the background',
+            validate: (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0
+                ? undefined
+                : 'must be a finite non-negative number',
+        }),
+    },
+});
+export function createBackgroundBashExtension(coordinator, ownsCoordinator = coordinator === undefined) {
+    const extension = (pi) => {
+        const config = {
+            foregroundTimeoutSeconds: Number(pi.config?.foregroundTimeoutSeconds ?? 120),
+        };
+        registerBackgroundBashCompletionRenderer(pi);
+        const manager = new BackgroundBashManager(pi.runtime, coordinator);
+        const foregroundBash = createRuntimeCodingTools(pi.runtime, { shellFlavor: 'posix' })
+            .find((tool) => tool.name === 'bash');
+        let helperToolsRegistered = false;
+        let backgroundBashActive = false;
+        let controlsRegistered = false;
+        let statusTarget;
+        let statusPollTimer;
+        let statusUpdateRunning = false;
+        let statusGeneration = 0;
+        let completionPollingEnabled = false;
+        let completionPollTimer;
+        let completionPollGeneration = 0;
+        let completionPollRunningGeneration;
+        let runtimeAvailable;
+        let runtimeCheck;
+        const watchedJobIds = new Set();
+        const createStatusTarget = (ctx) => {
+            if (ctx.mode !== 'tui')
+                return undefined;
+            return { ui: ctx.ui, generation: statusGeneration };
+        };
+        const updateStatus = async (target) => {
+            if (!target || target.generation !== statusGeneration || statusUpdateRunning)
                 return;
+            statusUpdateRunning = true;
+            try {
+                const running = await manager.list('running');
+                if (target.generation !== statusGeneration)
+                    return;
+                if (running.length === 0) {
+                    target.ui.setStatus('background-bash', undefined);
+                    return;
+                }
+                const label = running.length === 1 ? '1 process' : `${running.length} processes`;
+                const icon = target.ui.theme.fg('accent', '●');
+                const text = target.ui.theme.fg('accent', label);
+                target.ui.setStatus('background-bash', `${icon} ${text}`);
             }
-            const label = running.length === 1 ? '1 process' : `${running.length} processes`;
-            const icon = target.ui.theme.fg('accent', '●');
-            const text = target.ui.theme.fg('accent', label);
-            target.ui.setStatus('background-bash', `${icon} ${text}`);
-        }
-        catch {
-            if (target.generation !== statusGeneration)
+            catch {
+                if (target.generation !== statusGeneration)
+                    return;
+                target.ui.setStatus('background-bash', target.ui.theme.fg('warning', 'bash ?'));
+            }
+            finally {
+                statusUpdateRunning = false;
+            }
+        };
+        const startStatusPolling = (ctx) => {
+            statusGeneration += 1;
+            if (statusPollTimer)
+                clearInterval(statusPollTimer);
+            const target = createStatusTarget(ctx);
+            statusTarget = target;
+            void updateStatus(target);
+            statusPollTimer = target ? setInterval(() => void updateStatus(target), 5_000) : undefined;
+        };
+        const stopStatusPolling = () => {
+            statusGeneration += 1;
+            if (statusPollTimer) {
+                clearInterval(statusPollTimer);
+                statusPollTimer = undefined;
+            }
+            statusTarget?.ui.setStatus('background-bash', undefined);
+            statusTarget = undefined;
+        };
+        const clearCompletionPollTimer = () => {
+            if (!completionPollTimer)
                 return;
-            target.ui.setStatus('background-bash', target.ui.theme.fg('warning', 'bash ?'));
-        }
-        finally {
-            statusUpdateRunning = false;
-        }
-    };
-    const startStatusPolling = (ctx) => {
-        statusGeneration += 1;
-        if (statusPollTimer)
-            clearInterval(statusPollTimer);
-        const target = createStatusTarget(ctx);
-        statusTarget = target;
-        void updateStatus(target);
-        statusPollTimer = target ? setInterval(() => void updateStatus(target), 5_000) : undefined;
-    };
-    const stopStatusPolling = () => {
-        statusGeneration += 1;
-        if (statusPollTimer) {
-            clearInterval(statusPollTimer);
-            statusPollTimer = undefined;
-        }
-        statusTarget?.ui.setStatus('background-bash', undefined);
-        statusTarget = undefined;
-    };
-    const clearCompletionPollTimer = () => {
-        if (!completionPollTimer)
-            return;
-        clearInterval(completionPollTimer);
-        completionPollTimer = undefined;
-    };
-    const deliverCompletion = (job) => {
-        pi.sendMessage({
-            customType: BACKGROUND_BASH_COMPLETION_MESSAGE_TYPE,
-            content: formatCompletionNotice(job),
-            display: true,
-            details: { job: completionDetails(job) },
-        }, {
-            triggerTurn: true,
-            deliverAs: 'steer',
-        });
-    };
-    const pollCompletions = async (generation) => {
-        if (generation !== completionPollGeneration
-            || completionPollRunningGeneration === generation)
-            return;
-        completionPollRunningGeneration = generation;
-        try {
-            for (const id of [...watchedJobIds]) {
-                let job;
-                try {
-                    job = await manager.get(id);
-                }
-                catch {
-                    continue;
+            clearInterval(completionPollTimer);
+            completionPollTimer = undefined;
+        };
+        const deliverCompletion = (job) => {
+            pi.sendMessage({
+                customType: BACKGROUND_BASH_COMPLETION_MESSAGE_TYPE,
+                content: formatCompletionNotice(job),
+                display: true,
+                details: { job: completionDetails(job) },
+            }, {
+                triggerTurn: true,
+                deliverAs: 'steer',
+            });
+        };
+        const pollCompletions = async (generation) => {
+            if (generation !== completionPollGeneration
+                || completionPollRunningGeneration === generation)
+                return;
+            completionPollRunningGeneration = generation;
+            try {
+                for (const id of [...watchedJobIds]) {
+                    let job;
+                    try {
+                        job = await manager.get(id);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (generation !== completionPollGeneration
+                        || !completionPollingEnabled
+                        || !watchedJobIds.has(id))
+                        return;
+                    if (!isTerminalStatus(job.status.status))
+                        continue;
+                    watchedJobIds.delete(id);
+                    deliverCompletion(job);
+                    void updateStatus(statusTarget);
                 }
-                if (generation !== completionPollGeneration
-                    || !completionPollingEnabled
-                    || !watchedJobIds.has(id))
-                    return;
-                if (!isTerminalStatus(job.status.status))
-                    continue;
-                watchedJobIds.delete(id);
-                deliverCompletion(job);
-                void updateStatus(statusTarget);
             }
-        }
-        finally {
-            if (completionPollRunningGeneration === generation) {
-                completionPollRunningGeneration = undefined;
+            finally {
+                if (completionPollRunningGeneration === generation) {
+                    completionPollRunningGeneration = undefined;
+                }
+                if (watchedJobIds.size === 0)
+                    clearCompletionPollTimer();
             }
+        };
+        const ensureCompletionPolling = () => {
+            if (!completionPollingEnabled || watchedJobIds.size === 0 || completionPollTimer)
+                return;
+            const generation = completionPollGeneration;
+            completionPollTimer = setInterval(() => void pollCompletions(generation), COMPLETION_POLL_MS);
+            completionPollTimer.unref?.();
+            void pollCompletions(generation);
+        };
+        const watchCompletion = (id) => {
+            watchedJobIds.add(id);
+            ensureCompletionPolling();
+        };
+        const suppressCompletion = (id) => {
+            const removed = watchedJobIds.delete(id);
             if (watchedJobIds.size === 0)
                 clearCompletionPollTimer();
-        }
-    };
-    const ensureCompletionPolling = () => {
-        if (!completionPollingEnabled || watchedJobIds.size === 0 || completionPollTimer)
-            return;
-        const generation = completionPollGeneration;
-        completionPollTimer = setInterval(() => void pollCompletions(generation), COMPLETION_POLL_MS);
-        completionPollTimer.unref?.();
-        void pollCompletions(generation);
-    };
-    const watchCompletion = (id) => {
-        watchedJobIds.add(id);
-        ensureCompletionPolling();
-    };
-    const suppressCompletion = (id) => {
-        const removed = watchedJobIds.delete(id);
-        if (watchedJobIds.size === 0)
+            return removed;
+        };
+        const resumeCompletionPolling = () => {
+            completionPollingEnabled = true;
+            ensureCompletionPolling();
+        };
+        const pauseCompletionPolling = () => {
+            completionPollingEnabled = false;
+            completionPollGeneration += 1;
+            completionPollRunningGeneration = undefined;
             clearCompletionPollTimer();
-        return removed;
-    };
-    const resumeCompletionPolling = () => {
-        completionPollingEnabled = true;
-        ensureCompletionPolling();
-    };
-    const pauseCompletionPolling = () => {
-        completionPollingEnabled = false;
-        completionPollGeneration += 1;
-        completionPollRunningGeneration = undefined;
-        clearCompletionPollTimer();
-    };
-    const clearCompletionWatches = () => {
-        pauseCompletionPolling();
-        watchedJobIds.clear();
-    };
-    const openProcessView = async (ctx) => {
-        if (!supportsBackgroundBashModel(ctx.model)) {
-            if (ctx.mode === 'tui')
-                ctx.ui.notify('Background Bash is unavailable for this model.', 'info');
-            return;
-        }
-        if (!backgroundBashActive) {
-            if (ctx.mode === 'tui')
-                ctx.ui.notify('Background Bash is unavailable in this runtime.', 'info');
-            return;
-        }
-        const target = createStatusTarget(ctx);
-        if (!target)
-            return;
-        await target.ui.custom((tui, theme, _keybindings, done) => new BackgroundBashView(manager, theme, () => done(undefined), () => tui.requestRender()));
-        await updateStatus(target);
-    };
-    const assertSupportedModel = (ctx) => {
-        if (!supportsBackgroundBashModel(ctx.model)) {
-            throw new Error('Background Bash is unavailable for this model.');
-        }
-    };
-    const registerBackgroundBash = () => {
-        if (backgroundBashActive)
-            return;
-        pi.registerTool({
-            name: 'bash',
-            label: 'bash',
-            description: 'Execute a Bash command in the current working directory. Set background: true for long-running commands and inspect output with read_background_bash.',
-            promptSnippet: 'Execute Bash commands, optionally as detached processes with background: true',
-            promptGuidelines: [
-                'Use bash with background: true for long-running commands such as dev servers, watchers, and scripts the agent should not block on.',
-                'Background Bash completion messages arrive automatically; continue useful work instead of polling when the current task does not need to block.',
-                'After starting Background Bash, inspect output with read_background_bash; do not use wait_background_bash just to read output.',
-                'Use wait_background_bash only when you need to wait for the process to finish or check whether it has finished.',
-                'Use list_background_bash to discover detached Bash processes started in this root session and workspace, including its subagents.',
-            ],
-            parameters: BashParams,
-            async execute(toolCallId, params, signal, onUpdate, ctx) {
-                if (!params.background) {
-                    return foregroundBash.execute(toolCallId, {
-                        command: params.command,
-                        ...(params.timeout === undefined ? {} : { timeout: params.timeout }),
-                    }, signal, onUpdate, ctx);
-                }
-                assertSupportedModel(ctx);
-                const normalized = normalizeBackgroundCommand(params.command);
-                const target = createStatusTarget(ctx);
-                const job = await manager.start(normalized.command);
-                watchCompletion(job.meta.id);
-                await updateStatus(target);
-                const notice = normalized.rtkRewriteRemoved
-                    ? '\n\nRTK rewrite was removed for this background process so output streams directly to the log file.'
-                    : '';
-                const details = {
-                    background: true,
-                    id: job.meta.id,
-                    status: job.status.status,
-                    logPath: job.meta.logPath,
-                    infoPath: job.meta.infoPath,
-                    jobDir: job.meta.jobDir,
-                    command: job.meta.command,
-                    cwd: job.meta.cwd,
-                    startedAt: job.meta.startedAt,
-                    ...(job.status.pid ?? job.meta.pid) === undefined
-                        ? {}
-                        : { pid: job.status.pid ?? job.meta.pid },
-                    ...(normalized.originalCommand === undefined
-                        ? {}
-                        : { originalCommand: normalized.originalCommand }),
-                    ...(normalized.rtkRewriteRemoved ? { rtkRewriteRemoved: true } : {}),
-                };
-                return {
-                    content: [{ type: 'text', text: `${formatStarted(job)}${notice}` }],
-                    details,
-                };
-            },
-            renderCall(args, theme) {
-                const suffix = args.background ? theme.fg('muted', ' (background)') : '';
-                return new Text(theme.fg('toolTitle', theme.bold(`$ ${args.command}`)) + suffix, 0, 0);
-            },
-        });
-        backgroundBashActive = true;
-    };
-    const registerHelperTools = () => {
-        if (helperToolsRegistered)
-            return;
-        helperToolsRegistered = true;
-        pi.registerTool({
-            name: 'list_background_bash',
-            label: 'List Background Bash',
-            description: 'List detached Bash processes started in this root session and workspace, including processes started by its subagents.',
-            promptSnippet: 'List workspace Background Bash processes and their status',
-            parameters: ListBackgroundBashParams,
-            async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-                assertSupportedModel(ctx);
-                const target = createStatusTarget(ctx);
-                const jobs = await manager.list((params.status ?? 'all'));
-                for (const job of jobs) {
+        };
+        const clearCompletionWatches = () => {
+            pauseCompletionPolling();
+            watchedJobIds.clear();
+        };
+        const openProcessView = async (ctx) => {
+            if (!backgroundBashActive) {
+                if (ctx.mode === 'tui')
+                    ctx.ui.notify('Background processes are unavailable in this runtime.', 'info');
+                return;
+            }
+            const target = createStatusTarget(ctx);
+            if (!target)
+                return;
+            await target.ui.custom((tui, theme, _keybindings, done) => new BackgroundBashView(manager, theme, () => done(undefined), () => tui.requestRender()));
+            await updateStatus(target);
+        };
+        const registerBackgroundBash = () => {
+            if (backgroundBashActive)
+                return;
+            pi.registerTool({
+                name: 'bash',
+                label: 'bash',
+                description: 'Execute a Bash command in the current working directory. Set background: true for long-running commands and inspect output with read_background_bash.',
+                promptSnippet: 'Execute Bash commands, optionally as background processes with background: true',
+                promptGuidelines: [
+                    'Use bash with background: true for long-running commands such as dev servers, watchers, and scripts the agent should not block on.',
+                    'Use tty: true when a command needs interactive stdin or control bytes; write_background_bash sends exact input to it.',
+                    'Foreground commands are promoted to the background after their timeout without restarting; timeout: 0 promotes immediately.',
+                    'Background process completion messages arrive automatically; continue useful work instead of polling when the current task does not need to block.',
+                    'After starting a background process, inspect output with read_background_bash; do not use wait_background_bash just to read output.',
+                    'Use wait_background_bash only when you need to wait for the process to finish or check whether it has finished.',
+                    'Use list_background_bash to discover processes started in this root session and workspace, including its subagents.',
+                ],
+                parameters: BashParams,
+                async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+                    if (signal?.aborted)
+                        throw new Error('Command cancelled');
+                    const timeoutSeconds = params.timeout ?? config.foregroundTimeoutSeconds;
+                    const interactive = params.tty === true;
+                    const normalized = interactive
+                        ? { command: params.command, rtkRewriteRemoved: false }
+                        : normalizeBackgroundCommand(params.command);
+                    const target = createStatusTarget(ctx);
+                    const started = interactive
+                        ? await manager.startInteractive(normalized.command)
+                        : { job: await manager.start(normalized.command) };
+                    const job = started.job;
+                    if (signal?.aborted) {
+                        if (interactive)
+                            await manager.stopInteractive(job.meta.id).catch(() => { });
+                        else
+                            await manager.stop(job.meta.id).catch(() => { });
+                        throw new Error('Command cancelled');
+                    }
+                    if (!params.background && timeoutSeconds > 0) {
+                        try {
+                            if (interactive) {
+                                const deadline = Date.now() + timeoutSeconds * 1_000;
+                                let result = await manager.readInteractive(job.meta.id, Math.max(0, deadline - Date.now()), signal);
+                                if (signal?.aborted)
+                                    throw new Error('Command cancelled');
+                                while (result.running && Date.now() < deadline) {
+                                    result = await manager.readInteractive(job.meta.id, Math.max(0, deadline - Date.now()), signal);
+                                    if (signal?.aborted)
+                                        throw new Error('Command cancelled');
+                                }
+                                if (!result.running) {
+                                    const completed = await manager.get(job.meta.id);
+                                    return {
+                                        content: [{ type: 'text', text: formatForegroundOutput(completed, result.output) }],
+                                        details: { background: false, id: job.meta.id, status: completed.status.status, output: result.output },
+                                    };
+                                }
+                            }
+                            else {
+                                const result = await manager.wait(job.meta.id, timeoutSeconds, signal);
+                                if (!result.timedOut) {
+                                    const output = await manager.tail(job.meta.id);
+                                    return {
+                                        content: [{ type: 'text', text: formatForegroundOutput(result.job, output) }],
+                                        details: { background: false, id: job.meta.id, status: result.job.status.status, output },
+                                    };
+                                }
+                            }
+                        }
+                        catch (error) {
+                            if (signal?.aborted) {
+                                if (interactive)
+                                    await manager.stopInteractive(job.meta.id, 'SIGTERM').catch(() => { });
+                                else
+                                    await manager.stop(job.meta.id, 'SIGTERM').catch(() => { });
+                                throw new Error('Command cancelled', { cause: error });
+                            }
+                            throw error;
+                        }
+                    }
+                    if (!params.background)
+                        await manager.markPromoted(job.meta.id, interactive ? 'pty' : 'detached');
+                    watchCompletion(job.meta.id);
+                    await updateStatus(target);
+                    const notice = normalized.rtkRewriteRemoved
+                        ? '\n\nRTK rewrite was removed for this background process so output streams directly to the log file.'
+                        : '';
+                    const details = {
+                        background: true,
+                        id: job.meta.id,
+                        status: job.status.status,
+                        logPath: job.meta.logPath,
+                        infoPath: job.meta.infoPath,
+                        jobDir: job.meta.jobDir,
+                        command: job.meta.command,
+                        cwd: job.meta.cwd,
+                        startedAt: job.meta.startedAt,
+                        ...(job.status.pid ?? job.meta.pid) === undefined
+                            ? {}
+                            : { pid: job.status.pid ?? job.meta.pid },
+                        ...(normalized.originalCommand === undefined
+                            ? {}
+                            : { originalCommand: normalized.originalCommand }),
+                        ...(normalized.rtkRewriteRemoved ? { rtkRewriteRemoved: true } : {}),
+                        ...(interactive ? { tty: true } : {}),
+                    };
+                    return {
+                        content: [{ type: 'text', text: `${formatStarted(job)}${notice}` }],
+                        details,
+                    };
+                },
+                renderCall(args, theme) {
+                    const suffix = args.background || args.tty ? theme.fg('muted', args.tty ? ' (pty)' : ' (background)') : '';
+                    return new Text(theme.fg('toolTitle', theme.bold(`$ ${args.command}`)) + suffix, 0, 0);
+                },
+            });
+            backgroundBashActive = true;
+        };
+        const registerHelperTools = () => {
+            if (helperToolsRegistered)
+                return;
+            helperToolsRegistered = true;
+            pi.registerTool({
+                name: 'list_background_bash',
+                label: 'List background processes',
+                description: 'List processes started in this root session and workspace, including processes started by its subagents.',
+                promptSnippet: 'List workspace background processes and their status',
+                parameters: ListBackgroundBashParams,
+                async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+                    const target = createStatusTarget(ctx);
+                    const jobs = await manager.list((params.status ?? 'all'));
+                    for (const job of jobs) {
+                        if (isTerminalStatus(job.status.status))
+                            suppressCompletion(job.meta.id);
+                    }
+                    await updateStatus(target);
+                    return {
+                        content: [{ type: 'text', text: formatJobList(jobs) }],
+                        details: { jobs: jobs.map((job) => ({ meta: job.meta, status: job.status })) },
+                    };
+                },
+            });
+            pi.registerTool({
+                name: 'read_background_bash',
+                label: 'Read background process',
+                description: 'Read the trailing output of a background process by id.',
+                promptSnippet: 'Read output from a background process by id',
+                parameters: ReadBackgroundBashParams,
+                async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+                    const output = await manager.tail(params.id, params.lines ?? 80);
+                    const job = await manager.get(params.id);
                     if (isTerminalStatus(job.status.status))
                         suppressCompletion(job.meta.id);
-                }
-                await updateStatus(target);
-                return {
-                    content: [{ type: 'text', text: formatJobList(jobs) }],
-                    details: { jobs: jobs.map((job) => ({ meta: job.meta, status: job.status })) },
-                };
-            },
-        });
-        pi.registerTool({
-            name: 'read_background_bash',
-            label: 'Read Background Bash',
-            description: 'Read the trailing output of a detached Bash process by id.',
-            promptSnippet: 'Read output from a Background Bash process by id',
-            parameters: ReadBackgroundBashParams,
-            async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-                assertSupportedModel(ctx);
-                const output = await manager.tail(params.id, params.lines ?? 80);
-                const job = await manager.get(params.id);
-                if (isTerminalStatus(job.status.status))
-                    suppressCompletion(job.meta.id);
-                return {
-                    content: [{ type: 'text', text: output }],
-                    details: { id: params.id, status: job.status.status, lines: params.lines ?? 80 },
-                };
-            },
-        });
-        pi.registerTool({
-            name: 'wait_background_bash',
-            label: 'Wait Background Bash',
-            description: 'Wait for a detached Bash process to finish, or return current status after a timeout. Use read_background_bash for output.',
-            promptSnippet: 'Wait for a Background Bash process and return its status',
-            parameters: WaitBackgroundBashParams,
-            async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-                assertSupportedModel(ctx);
-                const target = createStatusTarget(ctx);
-                const wasWatched = suppressCompletion(params.id);
-                let result;
-                try {
-                    result = await manager.wait(params.id, params.timeout, signal);
-                }
-                catch (error) {
-                    if (wasWatched)
+                    return {
+                        content: [{ type: 'text', text: output }],
+                        details: { id: params.id, status: job.status.status, lines: params.lines ?? 80 },
+                    };
+                },
+            });
+            pi.registerTool({
+                name: 'wait_background_bash',
+                label: 'Wait for background process',
+                description: 'Wait for a background process to finish, or return current status after a timeout. Use read_background_bash for output.',
+                promptSnippet: 'Wait for a background process and return its status',
+                parameters: WaitBackgroundBashParams,
+                async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+                    const target = createStatusTarget(ctx);
+                    const wasWatched = suppressCompletion(params.id);
+                    let result;
+                    try {
+                        result = await manager.wait(params.id, params.timeout, signal);
+                    }
+                    catch (error) {
+                        if (wasWatched)
+                            watchCompletion(params.id);
+                        throw error;
+                    }
+                    if (wasWatched && result.timedOut)
                         watchCompletion(params.id);
-                    throw error;
-                }
-                if (wasWatched && result.timedOut)
-                    watchCompletion(params.id);
-                await updateStatus(target);
-                return {
-                    content: [{ type: 'text', text: formatWaitResult(result.job, result.timedOut) }],
-                    details: { job: result.job, timedOut: result.timedOut },
-                };
-            },
-        });
-        pi.registerTool({
-            name: 'stop_background_bash',
-            label: 'Stop Background Bash',
-            description: 'Stop a running Background Bash process by id and mark it as killed.',
-            promptSnippet: 'Stop a running Background Bash process by id',
-            parameters: StopBackgroundBashParams,
-            async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-                assertSupportedModel(ctx);
-                const target = createStatusTarget(ctx);
-                const wasWatched = suppressCompletion(params.id);
-                let job;
-                try {
-                    job = await manager.stop(params.id, params.signal ?? 'SIGTERM');
-                }
-                catch (error) {
-                    if (wasWatched)
-                        watchCompletion(params.id);
-                    throw error;
-                }
-                await updateStatus(target);
-                return {
-                    content: [{ type: 'text', text: `Background Bash stop result.\n\n${formatJobDetails(job)}` }],
-                    details: { job },
-                };
-            },
-        });
-    };
-    const registerControls = () => {
-        if (controlsRegistered)
-            return;
-        controlsRegistered = true;
-        pi.registerCommand('background-bash', {
-            description: 'View Background Bash processes and logs',
-            handler: async (_args, ctx) => openProcessView(ctx),
-        });
-        pi.registerShortcut(Key.ctrlShift('j'), {
-            description: 'View Background Bash processes and logs',
-            handler: openProcessView,
+                    await updateStatus(target);
+                    return {
+                        content: [{ type: 'text', text: formatWaitResult(result.job, result.timedOut) }],
+                        details: { job: result.job, timedOut: result.timedOut },
+                    };
+                },
+            });
+            pi.registerTool({
+                name: 'stop_background_bash',
+                label: 'Stop background process',
+                description: 'Stop a running background process by id and mark it as killed.',
+                promptSnippet: 'Stop a running background process by id',
+                parameters: StopBackgroundBashParams,
+                async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+                    const target = createStatusTarget(ctx);
+                    const wasWatched = suppressCompletion(params.id);
+                    let job;
+                    try {
+                        job = await manager.stop(params.id, params.signal ?? 'SIGTERM');
+                    }
+                    catch (error) {
+                        if (wasWatched)
+                            watchCompletion(params.id);
+                        throw error;
+                    }
+                    await updateStatus(target);
+                    return {
+                        content: [{ type: 'text', text: `Background process stop result.\n\n${formatJobDetails(job)}` }],
+                        details: { job },
+                    };
+                },
+            });
+            pi.registerTool({
+                name: 'write_background_bash',
+                label: 'Write to background process',
+                description: 'Write exact text or control bytes to a running background process with a PTY.',
+                promptSnippet: 'Send stdin or control bytes to a background process with a PTY',
+                parameters: WriteBackgroundBashParams,
+                async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+                    const result = await manager.writeInteractive(params.id, params.chars);
+                    const job = await manager.get(params.id);
+                    if (!result.running)
+                        suppressCompletion(job.meta.id);
+                    await updateStatus(createStatusTarget(ctx));
+                    return {
+                        content: [{ type: 'text', text: result.output || '(no output)' }],
+                        details: { id: params.id, status: job.status.status, tty: true },
+                    };
+                },
+            });
+        };
+        const registerControls = () => {
+            if (controlsRegistered)
+                return;
+            controlsRegistered = true;
+            pi.registerCommand('processes', {
+                description: 'View processes and logs',
+                handler: async (_args, ctx) => openProcessView(ctx),
+            });
+            pi.registerShortcut(Key.ctrlShift('j'), {
+                description: 'View processes and logs',
+                handler: openProcessView,
+            });
+        };
+        const activateRegisteredTools = () => {
+            if (!helperToolsRegistered || !backgroundBashActive)
+                return;
+            pi.setActiveTools([...new Set([...pi.getActiveTools(), 'bash', ...BACKGROUND_TOOL_NAMES])]);
+        };
+        const ensureRuntimeAvailable = async () => {
+            if (runtimeAvailable !== undefined)
+                return runtimeAvailable;
+            runtimeCheck ??= inspectBackgroundBashRuntime(pi.runtime)
+                .then((status) => {
+                runtimeAvailable = status.available;
+                return status.available;
+            })
+                .finally(() => {
+                runtimeCheck = undefined;
+            });
+            return runtimeCheck;
+        };
+        const enableExtension = async (ctx) => {
+            if (!await ensureRuntimeAvailable()) {
+                disableExtension();
+                return;
+            }
+            registerBackgroundBash();
+            registerHelperTools();
+            activateRegisteredTools();
+            resumeCompletionPolling();
+            if (ctx.mode === 'tui')
+                startStatusPolling(ctx);
+        };
+        const disableExtension = () => {
+            stopStatusPolling();
+            pauseCompletionPolling();
+            if (!helperToolsRegistered || !backgroundBashActive)
+                return;
+            pi.registerTool({ ...foregroundBash });
+            backgroundBashActive = false;
+            const backgroundNames = new Set(BACKGROUND_TOOL_NAMES);
+            pi.setActiveTools([
+                ...new Set([
+                    ...pi.getActiveTools().filter((name) => !backgroundNames.has(name)),
+                    'bash',
+                ]),
+            ]);
+        };
+        pi.on('session_start', async (_event, ctx) => {
+            if (ctx.mode === 'tui')
+                registerControls();
+            await enableExtension(ctx);
         });
-    };
-    const activateRegisteredTools = () => {
-        if (!helperToolsRegistered || !backgroundBashActive)
-            return;
-        pi.setActiveTools([...new Set([...pi.getActiveTools(), 'bash', ...BACKGROUND_TOOL_NAMES])]);
-    };
-    const ensureRuntimeAvailable = async () => {
-        if (runtimeAvailable !== undefined)
-            return runtimeAvailable;
-        runtimeCheck ??= inspectBackgroundBashRuntime(pi.runtime)
-            .then((status) => {
-            runtimeAvailable = status.available;
-            return status.available;
-        })
-            .finally(() => {
-            runtimeCheck = undefined;
+        pi.on('model_select', async (_event, ctx) => {
+            await enableExtension(ctx);
         });
-        return runtimeCheck;
-    };
-    const enableExtension = async (ctx) => {
-        if (!supportsBackgroundBashModel(ctx.model)) {
+        pi.on('session_shutdown', (event) => {
             stopStatusPolling();
-            pauseCompletionPolling();
-            return;
-        }
-        if (!await ensureRuntimeAvailable()) {
-            disableExtension();
-            return;
-        }
-        registerBackgroundBash();
-        registerHelperTools();
-        activateRegisteredTools();
-        resumeCompletionPolling();
-        if (ctx.mode === 'tui')
-            startStatusPolling(ctx);
-    };
-    const disableExtension = () => {
-        stopStatusPolling();
-        pauseCompletionPolling();
-        if (!helperToolsRegistered || !backgroundBashActive)
-            return;
-        pi.registerTool({ ...foregroundBash });
-        backgroundBashActive = false;
-        const backgroundNames = new Set(BACKGROUND_TOOL_NAMES);
-        pi.setActiveTools([
-            ...new Set([
-                ...pi.getActiveTools().filter((name) => !backgroundNames.has(name)),
-                'bash',
-            ]),
-        ]);
+            clearCompletionWatches();
+            return ownsCoordinator && event.reason !== 'reload' ? manager.shutdownInteractive() : undefined;
+        });
     };
-    pi.on('session_start', async (_event, ctx) => {
-        if (ctx.mode === 'tui')
-            registerControls();
-        await enableExtension(ctx);
-    });
-    pi.on('model_select', async (event, ctx) => {
-        if (supportsBackgroundBashModel(event.model))
-            await enableExtension(ctx);
-        else
-            disableExtension();
-    });
-    pi.on('session_shutdown', () => {
-        stopStatusPolling();
-        clearCompletionWatches();
-    });
-};
+    associateExtensionConfig(extension, BACKGROUND_BASH_CONFIG);
+    return extension;
+}
+const backgroundBashExtension = createBackgroundBashExtension();
 export { inspectBackgroundBashRuntime } from './runtime-support.js';
 function formatDate(ms) {
     return ms ? new Date(ms).toISOString() : '-';
@@ -491,10 +571,10 @@ function formatJobDetails(job) {
     ].join('\n');
 }
 function formatStarted(job) {
-    return `Started Background Bash process.\n\n${formatJobDetails(job)}\n\nCompletion will be delivered automatically. Use list_background_bash to see processes, read_background_bash with id "${job.meta.id}" to inspect output, wait_background_bash when the current task must block, or stop_background_bash to stop it.`;
+    return `Started background process.\n\n${formatJobDetails(job)}\n\nCompletion will be delivered automatically. Use list_background_bash to see processes, read_background_bash with id "${job.meta.id}" to inspect output, wait_background_bash when the current task must block, or stop_background_bash to stop it.`;
 }
 function formatCompletionNotice(job) {
-    return `Background Bash process reached terminal status: ${job.status.status}.\n\n${formatJobDetails(job)}\n\nUse read_background_bash with id "${job.meta.id}" if its output is needed.`;
+    return `Background process reached terminal status: ${job.status.status}.\n\n${formatJobDetails(job)}\n\nUse read_background_bash with id "${job.meta.id}" if its output is needed.`;
 }
 function completionDetails(job) {
     return {
@@ -513,7 +593,7 @@ function completionDetails(job) {
 }
 function formatJobList(jobs) {
     if (jobs.length === 0)
-        return 'No Background Bash processes found for this workspace.';
+        return 'No background processes found for this workspace.';
     return jobs.map((job) => {
         const pid = String(job.status.pid ?? job.meta.pid ?? '-');
         const exit = job.status.exitCode ?? job.status.signal ?? '-';
@@ -526,10 +606,16 @@ function formatJobList(jobs) {
 }
 function formatWaitResult(job, timedOut) {
     const heading = timedOut
-        ? 'Background Bash process is still running.'
-        : 'Background Bash process finished.';
+        ? 'Background process is still running.'
+        : 'Background process finished.';
     return `${heading}\n\n${formatJobDetails(job)}\n\nUse read_background_bash with id "${job.meta.id}" to inspect output.`;
 }
+function formatForegroundOutput(job, output) {
+    const exit = job.status.exitCode ?? job.status.signal ?? '-';
+    return `Exit: ${exit}\n\n${output || '(no output)'}`;
+}
 export { BackgroundBashManager } from './process-manager.js';
+export { BackgroundBashCoordinator } from './coordinator.js';
 export default backgroundBashExtension;
+associateExtensionConfig(backgroundBashExtension, BACKGROUND_BASH_CONFIG);
 //# sourceMappingURL=index.js.map