@felan-ai/ext-background-bash 0.3.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Felan contributors
+Copyright (c) 2026 Milko Slavov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,12 @@
+@felan-ai/ext-background-bash
+
+Includes code adapted from packages/pi-background-bash in
+https://github.com/mslavov/pi-extensions at source commit
+7e72e509fe45a5a87c4c2e176cb711de994a8c1d.
+
+Copyright (c) 2026 Milko Slavov
+Licensed under the MIT License included in this package.
+
+This package uses TypeBox 1.1.38 from
+https://github.com/sinclairzx81/typebox, licensed under the MIT License.
+Copyright (c) 2017-2026 Haydn Paterson.

package/README.md

@@ -0,0 +1,52 @@
+# @felan-ai/ext-background-bash
+
+Detached project-local Bash execution for Felan sessions. The extension augments
+`bash` with `background: true` and adds tools to list, wait for, and stop processes.
+Output and process metadata live under
+`<runtime-storage>/background-bash/<workspace-key>/jobs`. Local Felan maps
+`<runtime-storage>` to `$FELAN_AGENT_DIR` (`~/.felan` by default), while cloud
+adapters map it to their durable state root.
+
+The implementation routes filesystem and process operations through the active
+`AgentRuntime`. Background launch uses a detached POSIX shell runner. Host,
+Docker, and Daytona runtimes need `nohup`, `ps`, and either `setsid` or shell job
+control so each process receives an isolated process group. `runtime.storage.root`
+must be durable and visible in the same filesystem namespace as `runtime.shell`.
+
+The extension activates for selected models outside the OpenAI provider family.
+Providers `openai` and `openai-codex` are reserved for a separate background Bash
+extension. Keeping this policy here gives cloud and local consumers identical
+behavior without duplicating model filters in their composition roots.
+
+## Tools and controls
+
+- `bash({ command, background: true })` starts a detached process.
+- `list_background_bash` lists workspace processes and statuses.
+- `read_background_bash` reads trailing process output.
+- `wait_background_bash` waits for terminal status without returning log output.
+- `stop_background_bash` sends `SIGTERM` or `SIGKILL`.
+- `/background-bash` and `Ctrl+Shift+J` open the interactive process/log overlay in the TUI.
+
+The footer status shows the number of running processes. Foreground `bash` continues
+to use the active `AgentRuntime`. Processes started by the active session deliver a
+completion message automatically. The message steers an active run at its next
+model-call boundary or triggers a turn when the agent is idle. A terminal result
+returned directly by `list_background_bash`, `read_background_bash`,
+`wait_background_bash`, or `stop_background_bash` suppresses the duplicate
+completion message.
+
+## Development
+
+Source: `packages/ext-background-bash` in <https://github.com/felan-ai/felan>.
+
+```sh
+corepack enable
+pnpm install --frozen-lockfile
+pnpm --filter @felan-ai/ext-background-bash build
+pnpm --filter @felan-ai/ext-background-bash test
+```
+
+## Attribution
+
+This package adapts the MIT-licensed `pi-background-bash` implementation. See
+[NOTICE](NOTICE) for source details.

package/dist/command-normalizer.d.ts

@@ -0,0 +1,7 @@
+export interface NormalizedBackgroundCommand {
+    command: string;
+    originalCommand?: string;
+    rtkRewriteRemoved: boolean;
+}
+export declare function normalizeBackgroundCommand(command: string): NormalizedBackgroundCommand;
+//# sourceMappingURL=command-normalizer.d.ts.map

package/dist/command-normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-normalizer.d.ts","sourceRoot":"","sources":["../src/command-normalizer.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,2BAA2B,CAkBvF"}

package/dist/command-normalizer.js

@@ -0,0 +1,23 @@
+const SHELL_VALUE_PATTERN = String.raw `(?:"(?:\\.|[^"])*"|'(?:'\\''|[^'])*'|[^\s;]+)`;
+const RTK_DB_EXPORT_PATTERN = new RegExp(String.raw `^\s*export\s+RTK_DB_PATH=${SHELL_VALUE_PATTERN}\s*;\s*([\s\S]+)$`, 'u');
+const LEADING_ENV_ASSIGNMENTS_BEFORE_RTK_PATTERN = new RegExp(String.raw `^((?:[A-Za-z_][A-Za-z0-9_]*=${SHELL_VALUE_PATTERN}\s+)*)rtk\s+([\s\S]+)$`, 'u');
+export function normalizeBackgroundCommand(command) {
+    const exportMatch = command.match(RTK_DB_EXPORT_PATTERN);
+    if (!exportMatch)
+        return { command, rtkRewriteRemoved: false };
+    const afterExport = exportMatch[1] ?? '';
+    const rtkMatch = afterExport.match(LEADING_ENV_ASSIGNMENTS_BEFORE_RTK_PATTERN);
+    if (!rtkMatch)
+        return { command, rtkRewriteRemoved: false };
+    const envPrefix = rtkMatch[1] ?? '';
+    const rawCommand = rtkMatch[2] ?? '';
+    const normalized = `${envPrefix}${rawCommand}`.trim();
+    if (!normalized)
+        return { command, rtkRewriteRemoved: false };
+    return {
+        command: normalized,
+        originalCommand: command,
+        rtkRewriteRemoved: true,
+    };
+}
+//# sourceMappingURL=command-normalizer.js.map

package/dist/command-normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-normalizer.js","sourceRoot":"","sources":["../src/command-normalizer.ts"],"names":[],"mappings":"AAAA,MAAM,mBAAmB,GAAG,MAAM,CAAC,GAAG,CAAA,+CAA+C,CAAC;AACtF,MAAM,qBAAqB,GAAG,IAAI,MAAM,CACtC,MAAM,CAAC,GAAG,CAAA,4BAA4B,mBAAmB,mBAAmB,EAC5E,GAAG,CACJ,CAAC;AACF,MAAM,0CAA0C,GAAG,IAAI,MAAM,CAC3D,MAAM,CAAC,GAAG,CAAA,+BAA+B,mBAAmB,wBAAwB,EACpF,GAAG,CACJ,CAAC;AAQF,MAAM,UAAU,0BAA0B,CAAC,OAAe;IACxD,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACzD,IAAI,CAAC,WAAW;QAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC;IAE/D,MAAM,WAAW,GAAG,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACzC,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC/E,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC;IAE5D,MAAM,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACpC,MAAM,UAAU,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACrC,MAAM,UAAU,GAAG,GAAG,SAAS,GAAG,UAAU,EAAE,CAAC,IAAI,EAAE,CAAC;IACtD,IAAI,CAAC,UAAU;QAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC;IAE9D,OAAO;QACL,OAAO,EAAE,UAAU;QACnB,eAAe,EAAE,OAAO;QACxB,iBAAiB,EAAE,IAAI;KACxB,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { type Api, type FelanExtension, type Model } from '@felan-ai/agent-core';
+interface BackgroundBashDetails {
+    background: true;
+    id: string;
+    pid?: number;
+    status: string;
+    logPath: string;
+    infoPath: string;
+    jobDir: string;
+    command: string;
+    originalCommand?: string;
+    rtkRewriteRemoved?: boolean;
+    cwd: string;
+    startedAt: number;
+}
+export declare function supportsBackgroundBashModel(model: Model<Api> | undefined): boolean;
+declare const backgroundBashExtension: FelanExtension;
+export type { BackgroundBashDetails };
+export { BackgroundBashManager } from './process-manager.js';
+export type { BackgroundBashInfo, BackgroundBashJob, BackgroundBashMeta, BackgroundBashStatus, BackgroundBashStatusFile, BackgroundBashStatusFilter, } from './job-store.js';
+export default backgroundBashExtension;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,GAAG,EAER,KAAK,cAAc,EACnB,KAAK,KAAK,EACX,MAAM,sBAAsB,CAAC;AA8D9B,UAAU,qBAAqB;IAC7B,UAAU,EAAE,IAAI,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB;AAOD,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,SAAS,GAAG,OAAO,CAElF;AAED,QAAA,MAAM,uBAAuB,EAAE,cAqZ9B,CAAC;AAiFF,YAAY,EAAE,qBAAqB,EAAE,CAAC;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,gBAAgB,CAAC;AACxB,eAAe,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,515 @@
+import { StringEnum, createRuntimeCodingTools, } 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 { BackgroundBashOverlay } from './ui/background-bash-overlay.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_MESSAGE_TYPE = 'felan-background-bash-completion';
+const COMPLETION_POLL_MS = 500;
+const BACKGROUND_TOOL_NAMES = [
+    'list_background_bash',
+    'read_background_bash',
+    'wait_background_bash',
+    'stop_background_bash',
+];
+const BashParams = Type.Object({
+    command: Type.String({ description: 'Bash command to execute' }),
+    timeout: Type.Optional(Type.Number({ description: 'Timeout in seconds for foreground commands' })),
+    background: Type.Optional(Type.Boolean({
+        description: 'Start a detached background Bash process and return immediately',
+    })),
+}, { 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)' }),
+    lines: Type.Optional(Type.Integer({
+        minimum: 1,
+        maximum: 1_000,
+        description: 'Number of trailing log lines to return. Default: 80.',
+    })),
+}, { additionalProperties: false });
+const WaitBackgroundBashParams = Type.Object({
+    id: Type.String({ description: 'Background Bash process id returned by bash(background: true)' }),
+    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)' }),
+    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) => {
+    const manager = new BackgroundBashManager(pi.runtime);
+    const foregroundBash = createRuntimeCodingTools(pi.runtime)
+        .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;
+    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;
+            const count = running.length;
+            const label = count === 1 ? '1 process' : `${count} processes`;
+            const icon = count > 0
+                ? target.ui.theme.fg('accent', '●')
+                : target.ui.theme.fg('dim', '○');
+            const text = count > 0
+                ? target.ui.theme.fg('accent', label)
+                : target.ui.theme.fg('dim', label);
+            target.ui.setStatus('background-bash', `${icon} ${text}`);
+        }
+        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;
+        clearInterval(completionPollTimer);
+        completionPollTimer = undefined;
+    };
+    const deliverCompletion = (job) => {
+        pi.sendMessage({
+            customType: 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);
+            }
+        }
+        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();
+        return removed;
+    };
+    const resumeCompletionPolling = () => {
+        completionPollingEnabled = true;
+        ensureCompletionPolling();
+    };
+    const pauseCompletionPolling = () => {
+        completionPollingEnabled = false;
+        completionPollGeneration += 1;
+        completionPollRunningGeneration = undefined;
+        clearCompletionPollTimer();
+    };
+    const clearCompletionWatches = () => {
+        pauseCompletionPolling();
+        watchedJobIds.clear();
+    };
+    const openOverlay = async (ctx) => {
+        if (!supportsBackgroundBashModel(ctx.model)) {
+            if (ctx.mode === 'tui')
+                ctx.ui.notify('Background Bash is unavailable for this model.', 'info');
+            return;
+        }
+        const target = createStatusTarget(ctx);
+        if (!target)
+            return;
+        await target.ui.custom((tui, theme, _keybindings, done) => new BackgroundBashOverlay(manager, theme, () => done(undefined), () => tui.requestRender()), {
+            overlay: true,
+            overlayOptions: {
+                width: '85%',
+                minWidth: 72,
+                maxHeight: '90%',
+                margin: 2,
+            },
+        });
+        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 by any Felan session in the same workspace.',
+            ],
+            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 workspace, including processes started by other Felan sessions.',
+            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) {
+                    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)
+                        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) => openOverlay(ctx),
+        });
+        pi.registerShortcut(Key.ctrlShift('j'), {
+            description: 'View Background Bash processes and logs',
+            handler: openOverlay,
+        });
+    };
+    const activateRegisteredTools = () => {
+        if (!helperToolsRegistered || !backgroundBashActive)
+            return;
+        pi.setActiveTools([...new Set([...pi.getActiveTools(), 'bash', ...BACKGROUND_TOOL_NAMES])]);
+    };
+    const enableExtension = (ctx) => {
+        if (!supportsBackgroundBashModel(ctx.model)) {
+            stopStatusPolling();
+            pauseCompletionPolling();
+            return;
+        }
+        registerBackgroundBash();
+        registerHelperTools();
+        activateRegisteredTools();
+        resumeCompletionPolling();
+        if (ctx.mode === 'tui') {
+            registerControls();
+            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', (_event, ctx) => enableExtension(ctx));
+    pi.on('model_select', (event, ctx) => {
+        if (supportsBackgroundBashModel(event.model))
+            enableExtension(ctx);
+        else
+            disableExtension();
+    });
+    pi.on('session_shutdown', () => {
+        stopStatusPolling();
+        clearCompletionWatches();
+    });
+};
+function formatDate(ms) {
+    return ms ? new Date(ms).toISOString() : '-';
+}
+function formatDuration(job) {
+    const end = job.status.completedAt ?? Date.now();
+    const seconds = Math.max(0, Math.round((end - job.meta.startedAt) / 1_000));
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    return `${minutes}m${seconds % 60}s`;
+}
+function oneLine(value, max = 90) {
+    const compact = value.replace(/\s+/gu, ' ').trim();
+    return compact.length > max ? `${compact.slice(0, max - 1)}…` : compact;
+}
+function formatJobDetails(job) {
+    return [
+        `ID: ${job.meta.id}`,
+        `Status: ${job.status.status}`,
+        `PID: ${job.status.pid ?? job.meta.pid ?? '-'}`,
+        `Exit code: ${job.status.exitCode ?? '-'}`,
+        `Signal: ${job.status.signal ?? '-'}`,
+        `Error: ${job.status.error ?? '-'}`,
+        `Started: ${formatDate(job.meta.startedAt)}`,
+        `Completed: ${formatDate(job.status.completedAt)}`,
+        `Duration: ${formatDuration(job)}`,
+        `Log: ${job.meta.logPath}`,
+        `Info: ${job.meta.infoPath}`,
+        `Process dir: ${job.meta.jobDir}`,
+        `Command: ${job.meta.command}`,
+    ].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.`;
+}
+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.`;
+}
+function completionDetails(job) {
+    return {
+        id: job.meta.id,
+        status: job.status.status,
+        command: job.meta.command,
+        cwd: job.meta.cwd,
+        logPath: job.meta.logPath,
+        infoPath: job.meta.infoPath,
+        startedAt: job.meta.startedAt,
+        ...(job.status.completedAt === undefined ? {} : { completedAt: job.status.completedAt }),
+        ...(job.status.exitCode === undefined ? {} : { exitCode: job.status.exitCode }),
+        ...(job.status.signal === undefined ? {} : { signal: job.status.signal }),
+        ...(job.status.error === undefined ? {} : { error: job.status.error }),
+    };
+}
+function formatJobList(jobs) {
+    if (jobs.length === 0)
+        return 'No Background Bash 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 ?? '-';
+        return [
+            `${job.meta.id}  ${job.status.status}  pid=${pid}  exit=${exit}  started=${formatDate(job.meta.startedAt)}  duration=${formatDuration(job)}`,
+            `  log: ${job.meta.logPath}`,
+            `  command: ${oneLine(job.meta.command)}`,
+        ].join('\n');
+    }).join('\n\n');
+}
+function formatWaitResult(job, timedOut) {
+    const heading = timedOut
+        ? 'Background Bash process is still running.'
+        : 'Background Bash process finished.';
+    return `${heading}\n\n${formatJobDetails(job)}\n\nUse read_background_bash with id "${job.meta.id}" to inspect output.`;
+}
+export { BackgroundBashManager } from './process-manager.js';
+export default backgroundBashExtension;
+//# sourceMappingURL=index.js.map