@arnilo/prism-coding-agent 0.0.3

package/dist/path-utils.js

@@ -0,0 +1,117 @@
+/**
+ * Path resolution helpers.
+ *
+ * Behavioral port of pi's core/tools/path-utils for @arnilo/prism-coding-agent.
+ * stdlib only (node:fs, node:os, node:path, node:url). pi's version delegates
+ * homedir/tilde expansion to an internal utils/paths.js; that logic is inlined
+ * here as normalizePath/resolvePath so the package stays self-contained.
+ */
+import { accessSync, constants as fsConstants } from "node:fs";
+import { access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve as nodeResolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+const NARROW_NO_BREAK_SPACE = "\u202F";
+function normalizePath(input, options = {}) {
+    let normalized = options.trim ? input.trim() : input;
+    if (options.normalizeUnicodeSpaces) {
+        normalized = normalized.replace(UNICODE_SPACES, " ");
+    }
+    if (options.stripAtPrefix && normalized.startsWith("@")) {
+        normalized = normalized.slice(1);
+    }
+    if (options.expandTilde ?? true) {
+        const home = options.homeDir ?? homedir();
+        if (normalized === "~")
+            return home;
+        if (normalized.startsWith("~/") || (process.platform === "win32" && normalized.startsWith("~\\"))) {
+            return join(home, normalized.slice(2));
+        }
+    }
+    if (/^file:\/\//.test(normalized)) {
+        return fileURLToPath(normalized);
+    }
+    return normalized;
+}
+function resolvePath(input, baseDir = process.cwd(), options = {}) {
+    const normalized = normalizePath(input, options);
+    const normalizedBaseDir = normalizePath(baseDir);
+    return isAbsolute(normalized) ? nodeResolve(normalized) : nodeResolve(normalizedBaseDir, normalized);
+}
+export async function pathExists(filePath) {
+    try {
+        await access(filePath, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function expandPath(filePath) {
+    return normalizePath(filePath, { normalizeUnicodeSpaces: true, stripAtPrefix: true });
+}
+/**
+ * Resolve a path relative to the given cwd. Handles ~ expansion and absolute paths.
+ */
+export function resolveToCwd(filePath, cwd) {
+    return resolvePath(filePath, cwd, { normalizeUnicodeSpaces: true, stripAtPrefix: true });
+}
+// macOS screenshot / NFD / curly-quote fallbacks for read paths.
+function tryMacOSScreenshotPath(filePath) {
+    return filePath.replace(/ (AM|PM)\./gi, `${NARROW_NO_BREAK_SPACE}$1.`);
+}
+function tryNFDVariant(filePath) {
+    // macOS stores filenames in NFD (decomposed) form; try converting user input to NFD.
+    return filePath.normalize("NFD");
+}
+function tryCurlyQuoteVariant(filePath) {
+    // macOS uses U+2019 in screenshot names; users typically type a straight apostrophe.
+    return filePath.replace(/'/g, "\u2019");
+}
+function fileExists(filePath) {
+    try {
+        accessSync(filePath, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveReadPath(filePath, cwd) {
+    const resolved = resolveToCwd(filePath, cwd);
+    if (fileExists(resolved))
+        return resolved;
+    const amPmVariant = tryMacOSScreenshotPath(resolved);
+    if (amPmVariant !== resolved && fileExists(amPmVariant))
+        return amPmVariant;
+    const nfdVariant = tryNFDVariant(resolved);
+    if (nfdVariant !== resolved && fileExists(nfdVariant))
+        return nfdVariant;
+    const curlyVariant = tryCurlyQuoteVariant(resolved);
+    if (curlyVariant !== resolved && fileExists(curlyVariant))
+        return curlyVariant;
+    const nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);
+    if (nfdCurlyVariant !== resolved && fileExists(nfdCurlyVariant))
+        return nfdCurlyVariant;
+    return resolved;
+}
+export async function resolveReadPathAsync(filePath, cwd) {
+    const resolved = resolveToCwd(filePath, cwd);
+    if ((await pathExists(resolved)))
+        return resolved;
+    const amPmVariant = tryMacOSScreenshotPath(resolved);
+    if (amPmVariant !== resolved && (await pathExists(amPmVariant)))
+        return amPmVariant;
+    const nfdVariant = tryNFDVariant(resolved);
+    if (nfdVariant !== resolved && (await pathExists(nfdVariant)))
+        return nfdVariant;
+    const curlyVariant = tryCurlyQuoteVariant(resolved);
+    if (curlyVariant !== resolved && (await pathExists(curlyVariant)))
+        return curlyVariant;
+    const nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);
+    if (nfdCurlyVariant !== resolved && (await pathExists(nfdCurlyVariant)))
+        return nfdCurlyVariant;
+    return resolved;
+}
+//# sourceMappingURL=path-utils.js.map

package/dist/read.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Read tool: read a file from the host filesystem.
+ *
+ * Behavioral port of pi's core/tools/read for @arnilo/prism-coding-agent, adapted to Prism's
+ * `ToolDefinition` contract. Faithfully ports pi's text path (offset/limit → `truncateHead` →
+ * continuation notices) and image path (magic-byte MIME → `ImageContent` with base64). Drops pi's
+ * TUI (`renderCall`/`renderResult`, theme/syntax-highlight, compact classifications, key hints) and
+ * the model-aware non-vision note (Prism's `ToolExecutionContext` has no model field).
+ *
+ * Deviations from pi (documented):
+ *  - **`autoResizeImages` is a documented no-op** (deferred). pi resizes images to ≤2000×2000 via a
+ *    photon/WASM + `worker_threads` helper (`utils/image-process.js`); pulling that in adds native
+ *    build weight for a display-size concern hosts can own. The tool returns the raw image bytes as
+ *    base64 `ImageContent`. `ponytail:` ceiling noted inline; upgrade path = port image processing
+ *    when a host needs context-size capping.
+ *  - Abort + all read failures return a Prism `error` result (pi throws/rejects). Prism's
+ *    `dispatchToolCall` would catch a throw anyway, but returning a clean error result is predictable
+ *    for direct-`execute` callers and matches the package's `shell` tool.
+ *  - Truncation footers say "Use the shell tool" (pi: "Use bash") since the package's shell tool is
+ *    named `shell`.
+ */
+import { Buffer } from "node:buffer";
+import type { ToolDefinition } from "@arnilo/prism";
+import { type TruncationResult } from "./truncate.js";
+/** Detect a supported image MIME type from a buffer's leading bytes. Returns null for non-images. */
+export declare function detectSupportedImageMimeType(buffer: Buffer): string | null;
+/** Sniff the leading bytes of a file and return its image MIME type (null if not a supported image). */
+export declare function detectSupportedImageMimeTypeFromFile(filePath: string): Promise<string | null>;
+/**
+ * Pluggable operations for the read tool. Override to delegate file reading to remote systems
+ * (e.g. SSH) while keeping the tool's truncation/offset/limit behavior.
+ */
+export interface ReadOperations {
+    /** Read file contents as a Buffer. */
+    readFile: (absolutePath: string) => Promise<Buffer>;
+    /** Check the file is readable (throw if not). */
+    access: (absolutePath: string) => Promise<void>;
+    /** Detect image MIME type from the file; return null/undefined for non-images. */
+    detectImageMimeType?: (absolutePath: string) => Promise<string | null | undefined>;
+}
+export interface ReadToolOptions {
+    /**
+     * Whether to auto-resize images (pi resizes to ≤2000×2000). **Not yet implemented** — the tool
+     * returns raw image bytes. Kept as a placeholder so hosts can opt in once resizing is ported.
+     */
+    autoResizeImages?: boolean;
+    /** Custom operations backend (default: local filesystem). */
+    operations?: ReadOperations;
+    /** Max lines kept from the head (default 2000). */
+    maxLines?: number;
+    /** Max bytes kept from the head (default 50KB). */
+    maxBytes?: number;
+}
+export declare function createReadTool(cwd: string, options?: ReadToolOptions): ToolDefinition;
+/** Re-exported for hosts building custom read tools or analyzing truncation metadata. */
+export type { TruncationResult };

package/dist/read.js

@@ -0,0 +1,264 @@
+/**
+ * Read tool: read a file from the host filesystem.
+ *
+ * Behavioral port of pi's core/tools/read for @arnilo/prism-coding-agent, adapted to Prism's
+ * `ToolDefinition` contract. Faithfully ports pi's text path (offset/limit → `truncateHead` →
+ * continuation notices) and image path (magic-byte MIME → `ImageContent` with base64). Drops pi's
+ * TUI (`renderCall`/`renderResult`, theme/syntax-highlight, compact classifications, key hints) and
+ * the model-aware non-vision note (Prism's `ToolExecutionContext` has no model field).
+ *
+ * Deviations from pi (documented):
+ *  - **`autoResizeImages` is a documented no-op** (deferred). pi resizes images to ≤2000×2000 via a
+ *    photon/WASM + `worker_threads` helper (`utils/image-process.js`); pulling that in adds native
+ *    build weight for a display-size concern hosts can own. The tool returns the raw image bytes as
+ *    base64 `ImageContent`. `ponytail:` ceiling noted inline; upgrade path = port image processing
+ *    when a host needs context-size capping.
+ *  - Abort + all read failures return a Prism `error` result (pi throws/rejects). Prism's
+ *    `dispatchToolCall` would catch a throw anyway, but returning a clean error result is predictable
+ *    for direct-`execute` callers and matches the package's `shell` tool.
+ *  - Truncation footers say "Use the shell tool" (pi: "Use bash") since the package's shell tool is
+ *    named `shell`.
+ */
+import { Buffer } from "node:buffer";
+import { constants } from "node:fs";
+import { access as fsAccess, open, readFile as fsReadFile } from "node:fs/promises";
+import { resolveReadPathAsync } from "./path-utils.js";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead, } from "./truncate.js";
+// --- magic-byte image MIME detection (faithful port of pi utils/mime.js, pure JS, no deps) ---
+const IMAGE_TYPE_SNIFF_BYTES = 4100;
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+/** Detect a supported image MIME type from a buffer's leading bytes. Returns null for non-images. */
+export function detectSupportedImageMimeType(buffer) {
+    if (startsWith(buffer, [0xff, 0xd8, 0xff])) {
+        // SOI marker; 0xff 0xd8 0xff 0xf7 is a JFIF-extension frame, not a standalone JPEG image.
+        return buffer[3] === 0xf7 ? null : "image/jpeg";
+    }
+    if (startsWith(buffer, PNG_SIGNATURE)) {
+        return isPng(buffer) && !isAnimatedPng(buffer) ? "image/png" : null;
+    }
+    if (startsWithAscii(buffer, 0, "GIF")) {
+        return "image/gif";
+    }
+    if (startsWithAscii(buffer, 0, "RIFF") && startsWithAscii(buffer, 8, "WEBP")) {
+        return "image/webp";
+    }
+    if (startsWithAscii(buffer, 0, "BM") && isBmp(buffer)) {
+        return "image/bmp";
+    }
+    return null;
+}
+/** Sniff the leading bytes of a file and return its image MIME type (null if not a supported image). */
+export async function detectSupportedImageMimeTypeFromFile(filePath) {
+    const fileHandle = await open(filePath, "r");
+    try {
+        const buffer = Buffer.alloc(IMAGE_TYPE_SNIFF_BYTES);
+        const { bytesRead } = await fileHandle.read(buffer, 0, IMAGE_TYPE_SNIFF_BYTES, 0);
+        return detectSupportedImageMimeType(buffer.subarray(0, bytesRead));
+    }
+    finally {
+        await fileHandle.close();
+    }
+}
+function isPng(buffer) {
+    // First chunk after the 8-byte signature must be a 13-byte IHDR.
+    return (buffer.length >= 16 &&
+        readUint32BE(buffer, PNG_SIGNATURE.length) === 13 &&
+        startsWithAscii(buffer, 12, "IHDR"));
+}
+function isAnimatedPng(buffer) {
+    // Walk PNG chunks; an acTL chunk before the first IDAT marks an animated (APNG) image.
+    let offset = PNG_SIGNATURE.length;
+    while (offset + 8 <= buffer.length) {
+        const chunkLength = readUint32BE(buffer, offset);
+        const chunkTypeOffset = offset + 4;
+        if (startsWithAscii(buffer, chunkTypeOffset, "acTL"))
+            return true;
+        if (startsWithAscii(buffer, chunkTypeOffset, "IDAT"))
+            return false;
+        const nextOffset = offset + 8 + chunkLength + 4;
+        if (nextOffset <= offset || nextOffset > buffer.length)
+            return false;
+        offset = nextOffset;
+    }
+    return false;
+}
+function isBmp(buffer) {
+    if (buffer.length < 26)
+        return false;
+    const declaredFileSize = readUint32LE(buffer, 2);
+    const pixelDataOffset = readUint32LE(buffer, 10);
+    const dibHeaderSize = readUint32LE(buffer, 14);
+    if (declaredFileSize !== 0 && declaredFileSize < 26)
+        return false;
+    if (pixelDataOffset < 14 + dibHeaderSize)
+        return false;
+    if (declaredFileSize !== 0 && pixelDataOffset >= declaredFileSize)
+        return false;
+    let colorPlanes;
+    let bitsPerPixel;
+    if (dibHeaderSize === 12) {
+        colorPlanes = readUint16LE(buffer, 22);
+        bitsPerPixel = readUint16LE(buffer, 24);
+    }
+    else if (dibHeaderSize >= 40 && dibHeaderSize <= 124) {
+        if (buffer.length < 30)
+            return false;
+        colorPlanes = readUint16LE(buffer, 26);
+        bitsPerPixel = readUint16LE(buffer, 28);
+    }
+    else {
+        return false;
+    }
+    return colorPlanes === 1 && [1, 4, 8, 16, 24, 32].includes(bitsPerPixel);
+}
+function readUint16LE(buffer, offset) {
+    return (buffer[offset] ?? 0) + ((buffer[offset + 1] ?? 0) << 8);
+}
+function readUint32BE(buffer, offset) {
+    return ((buffer[offset] ?? 0) * 0x1000000 +
+        ((buffer[offset + 1] ?? 0) << 16) +
+        ((buffer[offset + 2] ?? 0) << 8) +
+        (buffer[offset + 3] ?? 0));
+}
+function readUint32LE(buffer, offset) {
+    return ((buffer[offset] ?? 0) +
+        ((buffer[offset + 1] ?? 0) << 8) +
+        ((buffer[offset + 2] ?? 0) << 16) +
+        (buffer[offset + 3] ?? 0) * 0x1000000);
+}
+function startsWith(buffer, bytes) {
+    if (buffer.length < bytes.length)
+        return false;
+    return bytes.every((byte, index) => buffer[index] === byte);
+}
+function startsWithAscii(buffer, offset, text) {
+    if (buffer.length < offset + text.length)
+        return false;
+    for (let index = 0; index < text.length; index++) {
+        if (buffer[offset + index] !== text.charCodeAt(index))
+            return false;
+    }
+    return true;
+}
+const defaultReadOperations = {
+    readFile: (path) => fsReadFile(path),
+    access: (path) => fsAccess(path, constants.R_OK),
+    detectImageMimeType: detectSupportedImageMimeTypeFromFile,
+};
+function errorResult(toolCallId, message) {
+    return {
+        toolCallId,
+        name: "read",
+        content: [{ type: "text", text: message }],
+        error: { message },
+    };
+}
+export function createReadTool(cwd, options) {
+    const ops = options?.operations ?? defaultReadOperations;
+    const maxLines = options?.maxLines ?? DEFAULT_MAX_LINES;
+    const maxBytes = options?.maxBytes ?? DEFAULT_MAX_BYTES;
+    return {
+        name: "read",
+        description: `Read the contents of a file. Supports text files and images (jpg, png, gif, webp, bmp); images are returned as image content. For text files, output is truncated to ${maxLines} lines or ${maxBytes / 1024}KB (whichever is hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete.`,
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Path to the file to read (relative or absolute)" },
+                offset: { type: "number", description: "Line number to start reading from (1-indexed)" },
+                limit: { type: "number", description: "Maximum number of lines to read" },
+            },
+            required: ["path"],
+            additionalProperties: false,
+        },
+        async execute(args, context) {
+            const toolCallId = context.toolCallId;
+            if (context.signal?.aborted) {
+                return errorResult(toolCallId, "Operation aborted");
+            }
+            const path = typeof args.path === "string" ? args.path : "";
+            const offset = typeof args.offset === "number" ? args.offset : undefined;
+            const limit = typeof args.limit === "number" ? args.limit : undefined;
+            if (path.length === 0) {
+                return errorResult(toolCallId, "path is required and must be a non-empty string.");
+            }
+            try {
+                const absolutePath = await resolveReadPathAsync(path, cwd);
+                await ops.access(absolutePath);
+                const mimeType = ops.detectImageMimeType ? await ops.detectImageMimeType(absolutePath) : undefined;
+                if (mimeType) {
+                    const buffer = await ops.readFile(absolutePath);
+                    // ponytail: auto-resize deferred — raw bytes returned; port image processing (resize to
+                    // ≤2000×2000) when a host needs context-size capping. Until then large images bloat context.
+                    return {
+                        toolCallId,
+                        name: "read",
+                        content: [
+                            { type: "text", text: `Read image file [${mimeType}]` },
+                            { type: "image", data: buffer.toString("base64"), mimeType },
+                        ],
+                        metadata: { image: { mimeType, resized: false } },
+                    };
+                }
+                // Text path: faithful port of pi's offset/limit → truncateHead → continuation logic.
+                const buffer = await ops.readFile(absolutePath);
+                const textContent = buffer.toString("utf-8");
+                const allLines = textContent.split("\n");
+                const totalFileLines = allLines.length;
+                // 1-indexed offset → 0-indexed array access.
+                const startLine = offset ? Math.max(0, offset - 1) : 0;
+                const startLineDisplay = startLine + 1;
+                if (startLine >= allLines.length) {
+                    throw new Error(`Offset ${offset} is beyond end of file (${allLines.length} lines total)`);
+                }
+                let selectedContent;
+                let userLimitedLines;
+                if (limit !== undefined) {
+                    const endLine = Math.min(startLine + limit, allLines.length);
+                    selectedContent = allLines.slice(startLine, endLine).join("\n");
+                    userLimitedLines = endLine - startLine;
+                }
+                else {
+                    selectedContent = allLines.slice(startLine).join("\n");
+                }
+                const truncation = truncateHead(selectedContent, { maxLines, maxBytes });
+                let outputText;
+                if (truncation.firstLineExceedsLimit) {
+                    // First line alone exceeds the byte limit — point at a shell fallback.
+                    const firstLineSize = formatSize(Buffer.byteLength(allLines[startLine], "utf-8"));
+                    outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(maxBytes)} limit. Use the shell tool: sed -n '${startLineDisplay}p' ${path} | head -c ${maxBytes}]`;
+                }
+                else if (truncation.truncated) {
+                    const endLineDisplay = startLineDisplay + truncation.outputLines - 1;
+                    const nextOffset = endLineDisplay + 1;
+                    outputText = truncation.content;
+                    if (truncation.truncatedBy === "lines") {
+                        outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue.]`;
+                    }
+                    else {
+                        outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines} (${formatSize(maxBytes)} limit). Use offset=${nextOffset} to continue.]`;
+                    }
+                }
+                else if (userLimitedLines !== undefined && startLine + userLimitedLines < allLines.length) {
+                    // User limit stopped early but the file has more content.
+                    const remaining = allLines.length - (startLine + userLimitedLines);
+                    const nextOffset = startLine + userLimitedLines + 1;
+                    outputText = `${truncation.content}\n\n[${remaining} more lines in file. Use offset=${nextOffset} to continue.]`;
+                }
+                else {
+                    outputText = truncation.content;
+                }
+                return {
+                    toolCallId,
+                    name: "read",
+                    content: [{ type: "text", text: outputText }],
+                    metadata: { truncation },
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return errorResult(toolCallId, message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=read.js.map

package/dist/shell.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Shell tool: execute a command in the host shell.
+ *
+ * Behavioral port of pi's core/tools/bash for @arnilo/prism-coding-agent, adapted to
+ * Prism's `ToolDefinition` contract. Drops pi's TUI (live `onUpdate` streaming,
+ * `renderCall`/`renderResult`) and process-shutdown child tracking; re-ports spawn/
+ * kill/waitForChildProcess directly over stdlib so the package stays self-contained.
+ *
+ * Deviations from pi (documented):
+ *  - Tool named `"shell"` (pi: `"bash"`).
+ *  - `timeout` param is in **seconds** (matches pi).
+ *  - Shell resolution honors `process.env.SHELL` → `/bin/bash` → `sh` (pi forces `/bin/bash`);
+ *    overridable via `options.shellPath`. Rationale: a host integrating the tool usually wants its
+ *    login shell respected; `shellPath` still lets a host force bash for fully predictable POSIX.
+ *  - Non-zero exit is **not** a tool error: returned as a normal `ToolResult` with `exitCode` in
+ *    `metadata` and a status footer in `content` (pi throws). timeout/abort *are* error results
+ *    (the command did not complete). Rationale: `ToolResult.error` should mean the tool call failed,
+ *    not that the command returned non-zero.
+ *  - Drops detached-child PID tracking (`killTrackedDetachedChildren`): the host owns process
+ *    lifecycle; the tool kills the tree only on timeout/abort. Drops the stdin command transport
+ *    (argv `-c` only). Default spawn env is `process.env` (no pi CLI binDir PATH injection).
+ */
+import { type ChildProcess } from "node:child_process";
+import type { ToolDefinition } from "@arnilo/prism";
+export interface ShellConfig {
+    shell: string;
+    args: string[];
+}
+export interface BashSpawnContext {
+    command: string;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}
+export type BashSpawnHook = (context: BashSpawnContext) => BashSpawnContext;
+export interface BashExecOptions {
+    onData: (data: Buffer) => void;
+    signal?: AbortSignal;
+    timeout?: number;
+    env?: NodeJS.ProcessEnv;
+}
+export interface BashOperations {
+    /** Execute a command and stream combined output. Resolves to the exit code (null if killed). */
+    exec: (command: string, cwd: string, options: BashExecOptions) => Promise<{
+        exitCode: number | null;
+    }>;
+}
+export interface ShellToolOptions {
+    /** Custom operations backend (default: local shell). Override to delegate to remote shells. */
+    operations?: BashOperations;
+    /** Command prefix prepended to every command (e.g. shell setup commands). */
+    commandPrefix?: string;
+    /** Explicit shell binary path; overrides SHELL/defaults. */
+    shellPath?: string;
+    /** Hook to adjust command, cwd, or env before execution. */
+    spawnHook?: BashSpawnHook;
+    /** Max lines kept in the tail snapshot (default 2000). */
+    maxLines?: number;
+    /** Max bytes kept in the tail snapshot (default 50KB). */
+    maxBytes?: number;
+    /** Temp-file prefix for spilled full output (default "prism-shell"). */
+    tempFilePrefix?: string;
+}
+/** Resolve the shell binary + args. shellPath → SHELL env → /bin/bash → sh. */
+export declare function getShellConfig(customShellPath?: string): ShellConfig;
+/** Kill a process and all its descendants (cross-platform). */
+export declare function killProcessTree(pid: number): void;
+/**
+ * Wait for a child to terminate without hanging on inherited stdio handles held by detached descendants.
+ *
+ * A short-lived child can `exit` while a detached descendant keeps its stdout/stderr pipe open. After
+ * `exit` we wait for the pipes to fall idle: the grace timer is re-armed on every chunk, so an actively
+ * writing descendant keeps us reading, while a quiet inherited handle releases us after the grace elapses.
+ */
+export declare function waitForChildProcess(child: ChildProcess): Promise<number | null>;
+/** Default local-shell operations: spawn the command in a shell, stream combined stdout+stderr. */
+export declare function createLocalBashOperations(options?: {
+    shellPath?: string;
+}): BashOperations;
+export declare function createShellTool(cwd: string, options?: ShellToolOptions): ToolDefinition;