@astralyn/pi 0.84.10 → 0.84.12

package/dist/extensions/background/index.js

@@ -10,206 +10,24 @@
  * kill stops a single task; list enumerates known tasks. /bg opens the
  * interactive task manager. Running counts surface in the footer via
  * ctx.ui.setStatus.
+ *
+ * This file is wiring only: the actions live in actions.ts, the notification
+ * in notify.ts, the transcript rows in render.ts, and the menu in manager.ts.
  */
-import { Type } from "typebox";
 import { getAgentDir } from "../../config.js";
 import { SettingsManager } from "../../core/settings-manager.js";
-import { createLocalBashOperations, MAX_TIMEOUT_SECONDS, resolveSpawnContext, } from "../../core/tools/bash.js";
-import { DEFAULT_MAX_BYTES, formatSize } from "../../core/tools/truncate.js";
-import { sanitizeBinaryOutput } from "../../utils/shell.js";
+import { createLocalBashOperations } from "../../core/tools/bash.js";
+import { describeTaskLine, runCreate, runKill, runList, runRead, runWait } from "./actions.js";
+import { BG_NOTIFICATION_TYPE } from "./constants.js";
 import { BackgroundTasksMenu } from "./manager.js";
-import { BackgroundTaskRegistry, BG_WAIT_DEFAULT_MS, BG_WAIT_MAX_MS, BG_WAIT_MIN_MS, firstCommandLine, formatDuration, readOutputSince, readOutputSlice, } from "./registry.js";
-import { commandLabel, renderBackgroundNotification, renderBgCall, renderBgResult, } from "./render.js";
-export const BG_NOTIFICATION_TYPE = "background-task";
-const BG_LOGS_DEFAULT_BYTES = 8 * 1024;
-const BG_LOGS_MIN_BYTES = 256;
-const BG_LIST_FINISHED_SHOWN = 5;
-/** Bounded output delta returned by a successful wait. */
-const BG_WAIT_DELTA_BYTES = 32 * 1024;
-/** Tail peek included in a wait timeout result so progress stays visible. */
-const BG_WAIT_PEEK_BYTES = 2 * 1024;
-const bgSchema = Type.Object({
-    action: Type.Union([Type.Literal("create"), Type.Literal("read"), Type.Literal("wait"), Type.Literal("kill"), Type.Literal("list")], { description: "Which background-task operation to perform" }),
-    // — create —
-    command: Type.Optional(Type.String({ description: "Bash command to run in the background (create). Do not append '&'" })),
-    description: Type.Optional(Type.String({
-        description: "Short label for the task, shown in /bg and notifications, e.g. 'dev server' (create)",
-    })),
-    timeout: Type.Optional(Type.Number({
-        description: "Kill the task after this many seconds; on expiry it is reported as timeout (create)",
-    })),
-    // — read / wait / kill —
-    taskId: Type.Optional(Type.String({ description: "Task id; a unique prefix is accepted, e.g. 'bg-3f' or '3f' (read/wait/kill)" })),
-    // — read —
-    mode: Type.Optional(Type.Union([Type.Literal("tail"), Type.Literal("head")], {
-        description: "Read from the end (default) or the start of the output (read)",
-    })),
-    bytes: Type.Optional(Type.Number({
-        description: `Max bytes to return (read, default ${formatSize(BG_LOGS_DEFAULT_BYTES)}, max ${formatSize(DEFAULT_MAX_BYTES)})`,
-    })),
-    // — wait —
-    waitMs: Type.Optional(Type.Number({
-        description: `Max time to wait in ms, default ${BG_WAIT_DEFAULT_MS}, max ${BG_WAIT_MAX_MS} (wait)`,
-    })),
-    sinceBytes: Type.Optional(Type.Number({
-        description: "Only return output written after this byte offset — take it from a previous read/wait result (wait)",
-    })),
-});
-export function escapeXml(text) {
-    return text
-        .replaceAll("&", "&")
-        .replaceAll("<", "&lt;")
-        .replaceAll(">", "&gt;")
-        .replaceAll('"', "&quot;")
-        .replaceAll("'", "&apos;");
-}
-/**
- * Strip characters XML 1.0 forbids: C0 controls (except \t \n \r), lone
- * surrogates (U+D800–U+DFFF), and the non-characters U+FFFE/U+FFFF.
- * sanitizeBinaryOutput does not remove the latter two classes, so this filter
- * is the authority for every text field in the notification XML.
- */
-export function filterXmlCharacters(text) {
-    let result = "";
-    for (const char of text) {
-        const code = char.codePointAt(0) ?? 0;
-        if (code === 0x09 ||
-            code === 0x0a ||
-            code === 0x0d ||
-            (code >= 0x20 && code <= 0xd7ff) ||
-            (code >= 0xe000 && code <= 0xfffd) ||
-            code >= 0x10000) {
-            result += char;
-        }
-    }
-    return result;
-}
-/**
- * filterXmlCharacters keeps \t \n \r and every other XML-legal codepoint, so
- * every field built with this is valid XML 1.0 after escaping.
- */
-const xmlText = (text) => escapeXml(filterXmlCharacters(text));
-/** The `<output-tail>` element, shared by the completion and stall notifications. */
-function renderOutputTail(notification) {
-    if (notification.tailError) {
-        return [`<output-tail unavailable="${xmlText(notification.tailError)}"/>`];
-    }
-    const attrs = [
-        `bytes="${notification.tailBytes}"`,
-        `totalBytes="${notification.totalBytes}"`,
-        notification.tailTruncated ? 'truncated="true"' : "",
-        notification.tailStartsMidLine ? 'startsMidLine="true"' : "",
-    ]
-        .filter(Boolean)
-        .join(" ");
-    const tail = notification.tailText.length > 0 ? xmlText(notification.tailText) : "(no output)";
-    return [`<output-tail ${attrs}>`, tail.trimEnd(), "</output-tail>"];
-}
-export function buildNotificationContent(notification) {
-    const task = notification.task;
-    const runtime = formatDuration((task.endedAt ?? task.startedAt) - task.startedAt);
-    const exitCode = task.exitCode === undefined || task.exitCode === null ? "" : ` exitCode="${task.exitCode}"`;
-    const lines = [
-        `<background-task id="${task.id}" status="${task.status}"${exitCode} runtime="${runtime}">`,
-        `<command>${xmlText(task.command)}</command>`,
-    ];
-    if (task.description) {
-        lines.push(`<description>${xmlText(task.description)}</description>`);
-    }
-    lines.push(`<output-file>${xmlText(task.outputPath)}</output-file>`);
-    if (task.error) {
-        lines.push(`<error>${xmlText(task.error)}</error>`);
-    }
-    lines.push(...renderOutputTail(notification));
-    lines.push("</background-task>");
-    return lines.join("\n");
-}
-export function formatStatusline(counts) {
-    if (counts.total === 0)
-        return undefined;
-    // Stalled tasks are running tasks: report them separately so the counts add up.
-    const waiting = counts.stalled ?? 0;
-    const running = counts.running - waiting;
-    const ended = counts.total - counts.running;
-    const parts = [];
-    if (running > 0)
-        parts.push(`${running} running`);
-    if (waiting > 0)
-        parts.push(`${waiting} waiting for input`);
-    if (ended > 0)
-        parts.push(`${ended} done`);
-    return `bg ${parts.join(" · ")}`;
-}
-export function buildStallContent(notification) {
-    const task = notification.task;
-    // A stalled task is by definition still running, so it has no endedAt.
-    const runtime = formatDuration(Date.now() - task.startedAt);
-    const lines = [
-        `<background-task id="${task.id}" status="running" waiting-for-input="true" runtime="${runtime}">`,
-        `<command>${xmlText(task.command)}</command>`,
-    ];
-    if (task.description) {
-        lines.push(`<description>${xmlText(task.description)}</description>`);
-    }
-    lines.push(`<output-file>${xmlText(task.outputPath)}</output-file>`);
-    lines.push(...renderOutputTail(notification));
-    lines.push("<advice>The command appears blocked waiting for interactive input. Kill it (bg action kill) and " +
-        "re-run with piped input (e.g. echo y | command) or a non-interactive flag if one exists (e.g. --yes). " +
-        "The task keeps running until then.</advice>");
-    lines.push("</background-task>");
-    return lines.join("\n");
-}
-function toStallDetails(notification) {
-    const task = notification.task;
-    return {
-        taskId: task.id,
-        command: task.command,
-        description: task.description,
-        status: "running",
-        stalled: true,
-        exitCode: undefined,
-        runtimeMs: Date.now() - task.startedAt,
-        outputPath: task.outputPath,
-        totalBytes: notification.totalBytes,
-        tailText: notification.tailText,
-        tailTruncated: notification.tailTruncated,
-        tailError: notification.tailError,
-    };
-}
-function describeResolveFailure(input, result) {
-    if (result.reason === "ambiguous") {
-        const lines = result.candidates.map((task) => `  ${task.id} (${task.status})  ${commandLabel(taskLabel(task), 60)}`);
-        return `Task id "${input}" is ambiguous. Candidates:\n${lines.join("\n")}`;
-    }
-    return `No background task matches "${input}". Check the id returned by bg (action create), or run action list.`;
-}
-/** One row of a bounded task listing: the model-facing list and /bg summaries. */
-function describeTaskLine(task, now) {
-    const duration = formatDuration((task.endedAt ?? now) - task.startedAt);
-    const exit = task.exitCode !== undefined && task.exitCode !== null ? ` exit ${task.exitCode}` : "";
-    return `  ${task.id}  ${task.status}${exit}  ${duration}  ${commandLabel(taskLabel(task), 60)}`;
-}
-/** Label for listings: the model-provided description over the first command line. */
-function taskLabel(task) {
-    return task.description ? `${task.description} — ${firstCommandLine(task.command)}` : firstCommandLine(task.command);
-}
-function toNotificationDetails(notification) {
-    const task = notification.task;
-    return {
-        taskId: task.id,
-        command: task.command,
-        description: task.description,
-        status: task.status,
-        exitCode: task.exitCode,
-        runtimeMs: (task.endedAt ?? task.startedAt) - task.startedAt,
-        outputPath: task.outputPath,
-        totalBytes: notification.totalBytes,
-        tailText: notification.tailText,
-        tailTruncated: notification.tailTruncated,
-        error: task.error,
-        tailError: notification.tailError,
-    };
-}
+import { buildNotificationContent, toNotificationDetails } from "./notify.js";
+import { readOutputSlice } from "./output-file.js";
+import { BackgroundTaskRegistry } from "./registry.js";
+import { renderBackgroundNotification, renderBgCall, renderBgResult, } from "./render.js";
+import { BG_PROMPT_GUIDELINES, BG_PROMPT_SNIPPET, BG_TOOL_DESCRIPTION, bgSchema } from "./schema.js";
+import { formatStatusline } from "./task-view.js";
+/** Tasks shown by the non-TUI `/bg` fallback summary. */
+const BG_COMMAND_SUMMARY_SHOWN = 10;
 /**
  * Wrap operations so every executed command carries the prefix, mirroring the
  * built-in bash tool. The prefix never reaches task labels or notifications:
@@ -222,41 +40,16 @@ export function prependCommandPrefix(operations, prefix) {
         exec: (command, cwd, options) => operations.exec(`${prefix}\n${command}`, cwd, options),
     };
 }
-/** Shell configuration for one bg session: the session's settings win, disk settings are the fallback. */
-export function resolveSessionShell(ctx, readDiskSettings) {
-    return ctx.getShellSettings?.() ?? readDiskSettings?.() ?? {};
+/** Hosts without getShellSettings (older SDK hosts): read what the session was configured with. */
+function readDiskShellSettings(ctx) {
+    const settings = SettingsManager.create(ctx.cwd, getAgentDir(), { projectTrusted: ctx.isProjectTrusted() });
+    return { shellPath: settings.getShellPath(), commandPrefix: settings.getShellCommandPrefix() };
 }
 /** Local shell operations honoring the session's shell settings (shellPath, commandPrefix). */
 function createSessionBashOperations(ctx) {
-    const shell = resolveSessionShell(ctx, () => {
-        // Hosts without getShellSettings (older SDK hosts): fall back to reading
-        // settings from disk, matching what the session was configured with.
-        const settings = SettingsManager.create(ctx.cwd, getAgentDir(), {
-            projectTrusted: ctx.isProjectTrusted(),
-        });
-        return { shellPath: settings.getShellPath(), commandPrefix: settings.getShellCommandPrefix() };
-    });
+    const shell = ctx.getShellSettings?.() ?? readDiskShellSettings(ctx);
     return prependCommandPrefix(createLocalBashOperations({ shellPath: shell.shellPath }), shell.commandPrefix);
 }
-/** Validate per-action required fields; every message names the next step. */
-function validateAction(input) {
-    switch (input.action) {
-        case "create":
-            if (!input.command || input.command.trim().length === 0) {
-                throw new Error("action 'create' requires 'command' — pass the bash command to run in the background.");
-            }
-            break;
-        case "read":
-        case "wait":
-        case "kill":
-            if (!input.taskId || input.taskId.trim().length === 0) {
-                throw new Error(`action '${input.action}' requires 'taskId' — use the id returned by action create, or action list to find it.`);
-            }
-            break;
-        case "list":
-            break;
-    }
-}
 /** Factory with injectable seams for tests; the default export uses production wiring. */
 export function createBackgroundExtension(overrides) {
     return (pi) => {
@@ -267,12 +60,6 @@ export function createBackgroundExtension(overrides) {
                 throw new Error("Background tasks are not available yet (no active session).");
             return registry;
         };
-        const resolveTaskOrThrow = (taskId) => {
-            const resolved = requireRegistry().resolveTask(taskId);
-            if (!resolved.ok)
-                throw new Error(describeResolveFailure(taskId, resolved));
-            return resolved.task;
-        };
         /** Read-only live peek for the pending wait renderer; never throws. */
         const waitLiveProbe = (taskId) => {
             if (!registry)
@@ -285,10 +72,6 @@ export function createBackgroundExtension(overrides) {
                 return;
             sessionCtx?.ui.setStatus("background", formatStatusline(registry.counts()));
         };
-        /** Both background messages reach the model the same way; that choice lives here only. */
-        const notify = (content, details) => {
-            pi.sendMessage({ customType: BG_NOTIFICATION_TYPE, content, display: true, details }, { deliverAs: "followUp", triggerTurn: true });
-        };
         pi.on("session_start", (_event, ctx) => {
             sessionCtx = ctx;
             // Defensive: a leftover registry (session_shutdown not seen) must not leak processes.
@@ -299,11 +82,13 @@ export function createBackgroundExtension(overrides) {
                 outputDir: overrides?.outputDir,
                 maxOutputBytes: overrides?.maxOutputBytes,
                 stall: overrides?.stall,
-                onNotify: (notification) => notify(buildNotificationContent(notification), toNotificationDetails(notification)),
-                // Informational one-shot signal: not a terminal state, so it bypasses
-                // the claim protocol (a waiting model needs to know it is blocked on
-                // input, not merely slow).
-                onStall: (notification) => notify(buildStallContent(notification), toStallDetails(notification)),
+                // Completion and stall reach the model the same way; that choice lives here only.
+                onNotify: (notification) => pi.sendMessage({
+                    customType: BG_NOTIFICATION_TYPE,
+                    content: buildNotificationContent(notification),
+                    display: true,
+                    details: toNotificationDetails(notification),
+                }, { deliverAs: "followUp", triggerTurn: true }),
                 onChange: updateStatus,
             });
             updateStatus();
@@ -315,283 +100,26 @@ export function createBackgroundExtension(overrides) {
             registry = undefined;
             await active?.shutdown();
         });
-        const runCreate = async (params, ctx) => {
-            if (params.timeout !== undefined && (!Number.isFinite(params.timeout) || params.timeout <= 0)) {
-                throw new Error("Invalid timeout: must be a positive number of seconds.");
-            }
-            if (params.timeout !== undefined && params.timeout > MAX_TIMEOUT_SECONDS) {
-                throw new Error(`Invalid timeout: maximum is ${MAX_TIMEOUT_SECONDS} seconds`);
-            }
-            // Same PI_* session variables as the built-in bash tool, snapshotted at start.
-            const spawnContext = resolveSpawnContext(params.command, ctx.cwd, undefined, true, ctx);
-            // Deliberately ignore the turn signal: aborting the current turn must
-            // not kill the background task (that is what action kill is for).
-            const task = requireRegistry().startTask({
-                command: params.command,
-                cwd: ctx.cwd,
-                description: params.description,
-                timeoutSeconds: params.timeout,
-                env: spawnContext.env,
-            });
-            const label = task.description ? ` (${task.description})` : "";
-            const text = [
-                `Started background task ${task.id}${label}.`,
-                `Output file: ${task.outputPath}`,
-                "",
-                "A <background-task> notification with the result and output tail arrives automatically when the task " +
-                    "ends — do NOT poll (no sleep loops, no repeated reads). Use action read for an early peek, " +
-                    "action wait when the next step depends on the result, action kill to stop it.",
-            ].join("\n");
-            return {
-                content: [{ type: "text", text }],
-                details: {
-                    action: "create",
-                    taskId: task.id,
-                    outputPath: task.outputPath,
-                    command: params.command,
-                    description: params.description,
-                },
-            };
-        };
-        const runRead = async (params) => {
-            const task = resolveTaskOrThrow(params.taskId);
-            const mode = params.mode ?? "tail";
-            const maxBytes = Math.min(DEFAULT_MAX_BYTES, Math.max(BG_LOGS_MIN_BYTES, Math.floor(params.bytes ?? BG_LOGS_DEFAULT_BYTES)));
-            let slice;
-            try {
-                slice = await readOutputSlice(task.outputPath, { mode, maxBytes });
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                throw new Error(`Could not read output for ${task.id} (${task.status}): ${message}\nOutput file: ${task.outputPath}`);
-            }
-            const text = sanitizeBinaryOutput(slice.text);
-            const running = task.status === "running" ? ["still running"] : [];
-            const noticeParts = slice.truncated
-                ? [
-                    `${mode} ${formatSize(slice.sliceBytes)} of ${formatSize(slice.totalBytes)}`,
-                    `task ${task.id} ${task.status}`,
-                    ...running,
-                    ...(slice.startsMidLine ? ["first line may be partial"] : []),
-                    `full output: ${task.outputPath}`,
-                ]
-                : [
-                    `task ${task.id} ${task.status}`,
-                    ...running,
-                    `${formatSize(slice.totalBytes)} total`,
-                    `output: ${task.outputPath}`,
-                ];
-            const body = text.length > 0 ? text : "(no output yet)";
-            return {
-                content: [{ type: "text", text: `[${noticeParts.join(" · ")}]\n${body}` }],
-                details: {
-                    action: "read",
-                    taskId: task.id,
-                    mode,
-                    sliceBytes: slice.sliceBytes,
-                    totalBytes: slice.totalBytes,
-                    outputPath: task.outputPath,
-                },
-            };
-        };
-        const runWait = async (params, signal) => {
-            const task = resolveTaskOrThrow(params.taskId);
-            const waitMs = Math.min(BG_WAIT_MAX_MS, Math.max(BG_WAIT_MIN_MS, Math.floor(params.waitMs ?? BG_WAIT_DEFAULT_MS)));
-            const startedWait = Date.now();
-            const result = await requireRegistry().waitForResult(task.id, waitMs, signal);
-            const waitedMs = Date.now() - startedWait;
-            const finalTask = result.task;
-            const exitSuffix = finalTask.exitCode !== undefined && finalTask.exitCode !== null ? ` · exit ${finalTask.exitCode}` : "";
-            const ran = formatDuration((finalTask.endedAt ?? Date.now()) - finalTask.startedAt);
-            if (result.outcome === "timeout") {
-                // Still running: keep progress visible with a bounded tail peek.
-                let peekText = "";
-                let peekNote = "";
-                let totalBytes = finalTask.outputBytes;
-                try {
-                    const peek = await readOutputSlice(finalTask.outputPath, { mode: "tail", maxBytes: BG_WAIT_PEEK_BYTES });
-                    peekText = sanitizeBinaryOutput(peek.text);
-                    totalBytes = peek.totalBytes;
-                    peekNote = peek.truncated ? ` (last ${formatSize(peek.sliceBytes)})` : "";
-                }
-                catch {
-                    peekNote = " (output unavailable)";
-                }
-                const lines = [
-                    `[${finalTask.id} still running · waited ${formatDuration(waitedMs)} · ${formatSize(totalBytes)} total]`,
-                ];
-                const trimmed = peekText.trimEnd();
-                if (trimmed.length > 0)
-                    lines.push(`Last output${peekNote}:\n${trimmed}`);
-                lines.push("The task keeps running. Wait again (action wait), peek with action read, or stop it with action kill; " +
-                    "the <background-task> notification still arrives when it ends. Do not sleep-poll.");
-                return {
-                    content: [{ type: "text", text: lines.join("\n\n") }],
-                    details: {
-                        action: "wait",
-                        taskId: finalTask.id,
-                        timedOut: true,
-                        status: finalTask.status,
-                        exitCode: finalTask.exitCode,
-                        waitedMs,
-                        deltaBytes: 0,
-                        totalBytes,
-                        deltaTruncated: false,
-                        outputPath: finalTask.outputPath,
-                    },
-                };
-            }
-            // Terminal: deliver the bounded delta since the requested offset.
-            // The followUp notification was suppressed by the claim protocol —
-            // this result is the single delivery of the completion.
-            const since = params.sinceBytes !== undefined ? Math.max(0, Math.floor(params.sinceBytes)) : undefined;
-            let delta;
-            let offsetNote;
-            try {
-                delta = await readOutputSince(finalTask.outputPath, since ?? 0, BG_WAIT_DELTA_BYTES);
-                if (since !== undefined && since > delta.totalBytes) {
-                    // A stale offset past EOF (the output was truncated at the cap, or
-                    // the model is reusing an id from an earlier read): fall back to
-                    // the tail and say so. Never an error — the offset is not a bug.
-                    delta = await readOutputSince(finalTask.outputPath, 0, BG_WAIT_DELTA_BYTES);
-                    offsetNote = finalTask.outputTruncated
-                        ? "the given offset is past EOF — output was truncated at the limit; showing the tail"
-                        : "the given offset is past EOF; showing the tail";
-                }
-            }
-            catch (error) {
-                // Deliver the terminal status even when the output file cannot be read.
-                const message = error instanceof Error ? error.message : String(error);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `[${finalTask.id} ${finalTask.status}${exitSuffix} · ran ${ran} · waited ${formatDuration(waitedMs)}]\nerror reading output: ${message}`,
-                        },
-                    ],
-                    details: {
-                        action: "wait",
-                        taskId: finalTask.id,
-                        timedOut: false,
-                        status: finalTask.status,
-                        exitCode: finalTask.exitCode,
-                        waitedMs,
-                        deltaBytes: 0,
-                        totalBytes: finalTask.outputBytes,
-                        deltaTruncated: false,
-                        outputPath: finalTask.outputPath,
-                    },
-                };
-            }
-            const lines = [
-                `[${finalTask.id} ${finalTask.status}${exitSuffix} · ran ${ran} · waited ${formatDuration(waitedMs)} · +${formatSize(delta.sliceBytes)} new output · total ${formatSize(delta.totalBytes)}]`,
-            ];
-            if (offsetNote)
-                lines.push(`[${offsetNote}]`);
-            if (finalTask.error)
-                lines.push(`error: ${finalTask.error}`);
-            if (delta.truncated) {
-                lines.push(`[showing ${formatSize(delta.sliceBytes)} of ${formatSize(delta.totalBytes)}; full output: ${finalTask.outputPath}]`);
-            }
-            const body = sanitizeBinaryOutput(delta.text).trimEnd();
-            lines.push(body.length > 0 ? body : "(no new output)");
-            return {
-                content: [{ type: "text", text: lines.join("\n") }],
-                details: {
-                    action: "wait",
-                    taskId: finalTask.id,
-                    timedOut: false,
-                    status: finalTask.status,
-                    exitCode: finalTask.exitCode,
-                    waitedMs,
-                    deltaBytes: delta.sliceBytes,
-                    totalBytes: delta.totalBytes,
-                    deltaTruncated: delta.truncated,
-                    outputPath: finalTask.outputPath,
-                },
-            };
-        };
-        const runKill = (params) => {
-            const task = resolveTaskOrThrow(params.taskId);
-            const result = requireRegistry().killTask(task.id);
-            if (!result.killed) {
-                const exit = task.exitCode !== undefined && task.exitCode !== null ? `, exit ${task.exitCode}` : "";
-                throw new Error(`Task ${task.id} is not running (status: ${task.status}${exit}).`);
-            }
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Killed task ${task.id}. If you are waiting on it (action wait) the killed status is delivered there; otherwise a completion notification follows once the process tree is reaped.`,
-                    },
-                ],
-                details: { action: "kill", taskId: task.id, command: task.command },
-            };
-        };
-        const runList = () => {
-            const tasks = requireRegistry().listTasks();
-            if (tasks.length === 0) {
-                return {
-                    content: [{ type: "text", text: "No background tasks this session. Start one with action create." }],
-                    details: { action: "list", running: 0, finished: 0, shown: 0, hidden: 0 },
-                };
-            }
-            const now = Date.now();
-            const running = tasks.filter((task) => task.status === "running");
-            const finished = tasks.filter((task) => task.status !== "running");
-            const shownFinished = finished.slice(0, BG_LIST_FINISHED_SHOWN);
-            const hidden = finished.length - shownFinished.length;
-            const lines = [`${running.length} running · ${finished.length} finished`];
-            for (const task of [...running, ...shownFinished]) {
-                lines.push(describeTaskLine(task, now));
-            }
-            if (hidden > 0) {
-                lines.push(`(+${hidden} more finished, not shown — action read shows any task's output)`);
-            }
-            return {
-                content: [{ type: "text", text: lines.join("\n") }],
-                details: {
-                    action: "list",
-                    running: running.length,
-                    finished: finished.length,
-                    shown: running.length + shownFinished.length,
-                    hidden,
-                },
-            };
-        };
         pi.registerTool({
             name: "bg",
             label: "bg",
-            description: "Run and manage background bash tasks.\n\n" +
-                "create: start a command in the background and return immediately with a task id and an " +
-                "output file path. A <background-task> notification with status, exit code, and output tail " +
-                "arrives automatically when it ends. Do NOT append '&' to the command; bg already runs it " +
-                "detached.\n\n" +
-                "read: bounded slice of a task's output; works while the task runs. The " +
-                "output file is a plain file — the read tool also works on it for line-based paging.\n\n" +
-                "wait: block until a task finishes and return its status plus output written since a given " +
-                "offset. On timeout the task is still running and you may wait again.\n\n" +
-                "kill: stop a running task (whole process tree).\n\n" +
-                "list: currently known tasks with status.",
-            promptSnippet: "Manage background shell tasks (create, read, wait, kill, list)",
-            promptGuidelines: [
-                "Use `bg` action create for long-running commands (dev servers, watch builds, slow tests) instead of regular bash; the completion notification arrives on its own, so continue independent work or end the turn.",
-                "Never wait on a `bg` task with sleep loops or repeated reads; use `bg` action wait when the next step depends on its result.",
-            ],
+            description: BG_TOOL_DESCRIPTION,
+            promptSnippet: BG_PROMPT_SNIPPET,
+            promptGuidelines: BG_PROMPT_GUIDELINES,
             parameters: bgSchema,
             async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-                validateAction(params);
+                const active = requireRegistry();
                 switch (params.action) {
                     case "create":
-                        return runCreate(params, ctx);
+                        return runCreate(active, params, ctx);
                     case "read":
-                        return runRead(params);
+                        return runRead(active, params);
                     case "wait":
-                        return runWait(params, signal);
+                        return runWait(active, params, signal);
                     case "kill":
-                        return runKill(params);
+                        return runKill(active, params);
                     case "list":
-                        return runList();
+                        return runList(active);
                 }
             },
             renderCall(args, theme, context) {
@@ -612,10 +140,11 @@ export function createBackgroundExtension(overrides) {
                 }
                 if (ctx.mode !== "tui") {
                     // RPC/print: ctx.ui.custom is unavailable — show a bounded summary.
+                    const now = Date.now();
                     const lines = active
                         .listTasks()
-                        .slice(0, 10)
-                        .map((task) => describeTaskLine(task, Date.now()));
+                        .slice(0, BG_COMMAND_SUMMARY_SHOWN)
+                        .map((task) => describeTaskLine(task, now));
                     ctx.ui.notify(`Background tasks:\n${lines.join("\n")}\nUse the bg tool (action kill) to stop a task.`, "info");
                     return;
                 }