@developerz.ai/ai-claude-compat 0.0.3 → 0.0.4

package/README.md

@@ -29,24 +29,56 @@ can't read or write outside the root you give it.
 import {
   readFileTool, writeFileTool,   // Read (offset/limit window) + Write
   editFileTool, multiEditTool,   // exact-string Edit + batched MultiEdit
-  bashTool,                       // streaming shell, scoped to cwd
+  bashTool, multiBashTool,        // one shell command / an ordered sequence, scoped to cwd
   globTool, grepTool,             // file glob + content search
 } from '@developerz.ai/ai-claude-compat';
 
 const cwd = process.cwd();
 const tools = {
-  read:  readFileTool({ cwd }),
-  write: writeFileTool({ cwd }),
-  edit:  editFileTool({ cwd }),
-  bash:  bashTool({ cwd }),
-  grep:  grepTool({ cwd }),
-  glob:  globTool({ cwd }),
+  read:      readFileTool({ cwd }),
+  write:     writeFileTool({ cwd }),
+  edit:      editFileTool({ cwd }),
+  bash:      bashTool({ cwd }),
+  multiBash: multiBashTool({ cwd }),
+  grep:      grepTool({ cwd }),
+  glob:      globTool({ cwd }),
 };
 ```
 
 Pass `tools` straight into a `generateText` / `streamText` call or an
 `Agent`/`ToolLoopAgent`.
 
+## Background processes
+
+`bashTool`/`multiBashTool` block until the command exits, so they can't hold a
+dev server open. `backgroundProcessTools` does: it spawns `bash -c …` without
+awaiting, returns a process id immediately, and lets the agent tail output, kill
+one process, or kill them all on teardown. **The caller owns lifecycle** — keep
+the returned `manager` and call `killAll()` when the run ends, or processes leak.
+
+```ts
+import { backgroundProcessTools } from '@developerz.ai/ai-claude-compat';
+
+const { manager, backgroundBash, bashOutput, killBash, listBackground } =
+  backgroundProcessTools({ cwd });
+
+const agentTools = { ...tools, backgroundBash, bashOutput, killBash, listBackground };
+// agent: backgroundBash("npm run dev") -> { id }
+//        bashOutput(id) -> new stdout/stderr since last poll, running, exitCode
+//        killBash(id)
+try {
+  await agent.generate({ prompt: 'start the dev server and check it serves /health' });
+} finally {
+  manager.killAll(); // teardown — nothing else guarantees the server is stopped
+}
+```
+
+`bashOutput` is **incremental** (like Claude Code's BashOutput): each call returns
+only the bytes produced since the last call. Buffers are capped (256 KiB/stream by
+default); past the cap the oldest bytes are dropped and `truncated` is set.
+Browser/CDP automation is intentionally **out of scope** — drive a browser with a
+dedicated MCP server (e.g. Playwright MCP), not from this library.
+
 ## Subagents (subagent-as-tool)
 
 `createSubagent` wraps the boilerplate of a `ToolLoopAgent` (model + tools +
@@ -99,7 +131,9 @@ for (const dir of claudeDirs(process.cwd())) {
 | --- | --- |
 | `readFileTool`, `writeFileTool` | Read (offset/limit window) + Write, cwd-scoped |
 | `editFileTool`, `multiEditTool`, `applyEdit` | Exact-string Edit, batched MultiEdit, pure edit helper |
-| `bashTool` | Streaming shell tool, scoped to cwd |
+| `bashTool` | Run one shell command, cwd as initial dir; returns stdout/stderr/exitCode |
+| `multiBashTool` | Run an ordered sequence of commands; stops at the first non-zero exit |
+| `backgroundProcessTools`, `ProcessManager` | Non-blocking background commands (dev servers): start / tail output / kill / killAll |
 | `globTool`, `grepTool`, `globToRegExp` | File glob + content search |
 | `composeSystemPrompt`, `createSubagent` | System-prompt composer + subagent-as-tool factory |
 | `envBlock` | Render the `<env>` system-context block from `EnvInfo` |
@@ -116,6 +150,30 @@ ESM only. Runs unchanged on **Node ≥ 20, Bun, and Deno ≥ 1.40**. Peer dep: `
 (AI SDK v6). No Anthropic SDK — "Claude-compat" refers to the *conventions*, not
 the provider.
 
+## Platform: Linux only
+
+The shell tools (`bashTool`, `multiBashTool`) target **Linux**. They spawn
+`bash -c …`, so they need a POSIX `bash` on `PATH` — they are **not** supported
+on native Windows (use WSL) and are only best-effort on macOS. The pure
+filesystem/edit/search tools are platform-neutral, but the package as a whole is
+developed and tested on Linux; treat anything else as unsupported.
+
+### Shell environment (rbenv / nvm / asdf, `~/.bashrc`)
+
+Commands run via a **non-login, non-interactive** `bash -c` with `BASH_ENV`
+scrubbed. That is deliberate: a login/interactive shell would source
+`/etc/profile` and `~/.bashrc`, which often `cd` away and would defeat the
+cwd lock. The consequence:
+
+- **PATH-based tools work** — `rbenv`/`asdf` shims, and any binary already on the
+  `PATH` of the process that launched the agent, are inherited (the child gets
+  `process.env`). If you can run `ruby`/`node` from the shell you start the agent
+  in, the agent can too.
+- **Shell-function tools do not** — `nvm`, and anything that exists only as a
+  function defined in `~/.bashrc`, is **not** loaded. Source it yourself inside
+  the command (`source ~/.nvm/nvm.sh && nvm use && …`) or put the resolved
+  binary on `PATH` before launching.
+
 ## License
 
 MIT · part of [`developerz-ai/ai-task-master`](https://github.com/developerz-ai/ai-task-master)

package/dist/background-process.d.ts

@@ -0,0 +1,62 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { type Tool } from 'ai';
+export type SpawnFn = typeof nodeSpawn;
+export type BackgroundProcessInit = {
+    cwd: string;
+    maxBufferBytes?: number;
+    spawn?: SpawnFn;
+};
+export type ProcessStatus = {
+    id: string;
+    command: string;
+    running: boolean;
+    exitCode: number | null;
+    pid: number | null;
+};
+export type ProcessOutput = {
+    id: string;
+    stdout: string;
+    stderr: string;
+    running: boolean;
+    exitCode: number | null;
+    truncated: boolean;
+};
+export declare class ProcessManager {
+    private readonly cwd;
+    private readonly cap;
+    private readonly spawn;
+    private readonly procs;
+    private counter;
+    constructor(init: BackgroundProcessInit);
+    start(command: string): ProcessStatus;
+    output(id: string): ProcessOutput | null;
+    kill(id: string, signal?: NodeJS.Signals): boolean;
+    killAll(signal?: NodeJS.Signals): void;
+    list(): ProcessStatus[];
+    private statusOf;
+}
+export type BackgroundBashInput = {
+    command: string;
+};
+export type BackgroundBashOutput = ProcessStatus;
+export type BashOutputInput = {
+    id: string;
+};
+export type KillBashInput = {
+    id: string;
+};
+export type KillBashOutput = {
+    id: string;
+    killed: boolean;
+};
+export type ListBackgroundOutput = {
+    processes: ProcessStatus[];
+};
+export type BackgroundProcessTools = {
+    manager: ProcessManager;
+    backgroundBash: Tool<BackgroundBashInput, BackgroundBashOutput>;
+    bashOutput: Tool<BashOutputInput, ProcessOutput>;
+    killBash: Tool<KillBashInput, KillBashOutput>;
+    listBackground: Tool<Record<string, never>, ListBackgroundOutput>;
+};
+export declare function backgroundProcessTools(init: BackgroundProcessInit): BackgroundProcessTools;

package/dist/background-process.js

@@ -0,0 +1,146 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { tool } from 'ai';
+import { z } from 'zod';
+const DEFAULT_MAX_BUFFER_BYTES = 256 * 1024;
+class CappedStream {
+    cap;
+    retained = '';
+    produced = 0;
+    returned = 0;
+    constructor(cap) {
+        this.cap = cap;
+    }
+    append(chunk) {
+        this.produced += chunk.length;
+        this.retained += chunk;
+        if (this.retained.length > this.cap) {
+            this.retained = this.retained.slice(this.retained.length - this.cap);
+        }
+    }
+    read() {
+        const retainedStart = this.produced - this.retained.length;
+        const from = Math.max(this.returned, retainedStart);
+        const chunk = this.retained.slice(from - retainedStart);
+        const truncated = retainedStart > this.returned;
+        this.returned = this.produced;
+        return { chunk, truncated };
+    }
+}
+export class ProcessManager {
+    cwd;
+    cap;
+    spawn;
+    procs = new Map();
+    counter = 0;
+    constructor(init) {
+        this.cwd = init.cwd;
+        this.cap = init.maxBufferBytes ?? DEFAULT_MAX_BUFFER_BYTES;
+        this.spawn = init.spawn ?? nodeSpawn;
+    }
+    start(command) {
+        const id = `bg-${++this.counter}`;
+        const proc = this.spawn('bash', ['-c', command], {
+            cwd: this.cwd,
+            env: { ...process.env, BASH_ENV: '' },
+        });
+        const entry = {
+            command,
+            proc,
+            stdout: new CappedStream(this.cap),
+            stderr: new CappedStream(this.cap),
+            running: true,
+            exitCode: null,
+        };
+        proc.stdout?.on('data', (d) => entry.stdout.append(d.toString()));
+        proc.stderr?.on('data', (d) => entry.stderr.append(d.toString()));
+        proc.on('error', (err) => {
+            entry.stderr.append(err.message);
+            entry.running = false;
+            if (entry.exitCode === null)
+                entry.exitCode = 1;
+        });
+        proc.on('exit', (code, signal) => {
+            entry.running = false;
+            entry.exitCode = code ?? (signal ? 1 : 0);
+        });
+        this.procs.set(id, entry);
+        return this.statusOf(id, entry);
+    }
+    output(id) {
+        const entry = this.procs.get(id);
+        if (!entry)
+            return null;
+        const out = entry.stdout.read();
+        const err = entry.stderr.read();
+        return {
+            id,
+            stdout: out.chunk,
+            stderr: err.chunk,
+            running: entry.running,
+            exitCode: entry.exitCode,
+            truncated: out.truncated || err.truncated,
+        };
+    }
+    kill(id, signal = 'SIGTERM') {
+        const entry = this.procs.get(id);
+        if (!entry)
+            return false;
+        if (entry.running)
+            entry.proc.kill(signal);
+        return true;
+    }
+    killAll(signal = 'SIGTERM') {
+        for (const entry of this.procs.values()) {
+            if (entry.running)
+                entry.proc.kill(signal);
+        }
+    }
+    list() {
+        return [...this.procs.entries()].map(([id, entry]) => this.statusOf(id, entry));
+    }
+    statusOf(id, entry) {
+        return {
+            id,
+            command: entry.command,
+            running: entry.running,
+            exitCode: entry.exitCode,
+            pid: entry.proc.pid ?? null,
+        };
+    }
+}
+const backgroundBashInputSchema = z.object({ command: z.string().min(1) });
+const idInputSchema = z.object({ id: z.string().min(1) });
+export function backgroundProcessTools(init) {
+    const manager = new ProcessManager(init);
+    const backgroundBash = tool({
+        description: 'Start a long-running shell command in the background (e.g. a dev server) and return immediately with a process id. Does NOT wait for it to exit. Poll its output with bashOutput(id) and stop it with killBash(id). For a command that finishes quickly, use the blocking bash tool instead.',
+        inputSchema: backgroundBashInputSchema,
+        execute: async (input) => manager.start(input.command),
+    });
+    const bashOutput = tool({
+        description: 'Read new stdout/stderr produced since the last bashOutput call for a background process id, plus whether it is still running and its exit code once finished.',
+        inputSchema: idInputSchema,
+        execute: async (input) => manager.output(input.id) ?? {
+            id: input.id,
+            stdout: '',
+            stderr: `no background process with id ${input.id}`,
+            running: false,
+            exitCode: 1,
+            truncated: false,
+        },
+    });
+    const killBash = tool({
+        description: 'Stop a background process by id (sends SIGTERM). Idempotent.',
+        inputSchema: idInputSchema,
+        execute: async (input) => ({
+            id: input.id,
+            killed: manager.kill(input.id),
+        }),
+    });
+    const listBackground = tool({
+        description: 'List all background processes started this session with their running state.',
+        inputSchema: z.object({}),
+        execute: async () => ({ processes: manager.list() }),
+    });
+    return { manager, backgroundBash, bashOutput, killBash, listBackground };
+}

package/dist/bash-tool.d.ts

@@ -5,16 +5,29 @@ declare const bashInputSchema: z.ZodObject<{
     command: z.ZodString;
     timeoutMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
+declare const multiBashInputSchema: z.ZodObject<{
+    commands: z.ZodArray<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 export type BashInput = z.infer<typeof bashInputSchema>;
 export type BashOutput = {
     stdout: string;
     stderr: string;
     exitCode: number;
 };
+export type MultiBashInput = z.infer<typeof multiBashInputSchema>;
+export type MultiBashOutput = {
+    results: Array<{
+        command: string;
+    } & BashOutput>;
+    exitCode: number;
+    failedAt: number | null;
+};
 export type BashToolInit = {
     cwd: string;
     defaultTimeoutMs?: number;
     exec?: typeof execa;
 };
 export declare function bashTool(init: BashToolInit): Tool<BashInput, BashOutput>;
+export declare function multiBashTool(init: BashToolInit): Tool<MultiBashInput, MultiBashOutput>;
 export {};

package/dist/bash-tool.js

@@ -5,42 +5,67 @@ const bashInputSchema = z.object({
     command: z.string().min(1),
     timeoutMs: z.number().int().positive().optional(),
 });
+const multiBashInputSchema = z.object({
+    commands: z.array(z.string().min(1)).min(1),
+    timeoutMs: z.number().int().positive().optional(),
+});
 const DEFAULT_BASH_TIMEOUT_MS = 60_000;
 const MAX_BASH_TIMEOUT_MS = 600_000;
+async function runBash(exec, cwd, command, timeout) {
+    try {
+        const r = await exec('bash', ['-c', command], {
+            cwd,
+            timeout,
+            env: { ...process.env, BASH_ENV: '' },
+        });
+        return {
+            stdout: typeof r.stdout === 'string' ? r.stdout : '',
+            stderr: typeof r.stderr === 'string' ? r.stderr : '',
+            exitCode: r.exitCode ?? 0,
+        };
+    }
+    catch (err) {
+        if (err instanceof ExecaError) {
+            return {
+                stdout: typeof err.stdout === 'string' ? err.stdout : '',
+                stderr: typeof err.stderr === 'string' ? err.stderr : err.message,
+                exitCode: err.exitCode ?? 1,
+            };
+        }
+        return {
+            stdout: '',
+            stderr: err instanceof Error ? err.message : String(err),
+            exitCode: 1,
+        };
+    }
+}
 export function bashTool(init) {
     const exec = init.exec ?? execa;
     const defaultTimeout = init.defaultTimeoutMs ?? DEFAULT_BASH_TIMEOUT_MS;
     return tool({
         description: 'Run a shell command inside the current worktree. Returns stdout, stderr, and exit code. The command runs via `bash -c` with its initial cwd set to the worktree.',
         inputSchema: bashInputSchema,
+        execute: (input) => runBash(exec, init.cwd, input.command, Math.min(input.timeoutMs ?? defaultTimeout, MAX_BASH_TIMEOUT_MS)),
+    });
+}
+export function multiBashTool(init) {
+    const exec = init.exec ?? execa;
+    const defaultTimeout = init.defaultTimeoutMs ?? DEFAULT_BASH_TIMEOUT_MS;
+    return tool({
+        description: 'Run a sequence of shell commands inside the current worktree, one after another. Stops at the first command that exits non-zero — the remaining commands are not run. Each command runs in its own `bash -c` with cwd reset to the worktree, so chain `cd x && …` within a single command if you need a directory change to persist. Returns one result per command that ran, the overall exit code, and the index of the failing command (failedAt) if any.',
+        inputSchema: multiBashInputSchema,
         execute: async (input) => {
             const timeout = Math.min(input.timeoutMs ?? defaultTimeout, MAX_BASH_TIMEOUT_MS);
-            try {
-                const r = await exec('bash', ['-c', input.command], {
-                    cwd: init.cwd,
-                    timeout,
-                    env: { ...process.env, BASH_ENV: '' },
-                });
-                return {
-                    stdout: typeof r.stdout === 'string' ? r.stdout : '',
-                    stderr: typeof r.stderr === 'string' ? r.stderr : '',
-                    exitCode: r.exitCode ?? 0,
-                };
-            }
-            catch (err) {
-                if (err instanceof ExecaError) {
-                    return {
-                        stdout: typeof err.stdout === 'string' ? err.stdout : '',
-                        stderr: typeof err.stderr === 'string' ? err.stderr : err.message,
-                        exitCode: err.exitCode ?? 1,
-                    };
+            const results = [];
+            for (let i = 0; i < input.commands.length; i++) {
+                const command = input.commands[i] ?? '';
+                const out = await runBash(exec, init.cwd, command, timeout);
+                results.push({ command, ...out });
+                if (out.exitCode !== 0) {
+                    return { results, exitCode: out.exitCode, failedAt: i };
                 }
-                return {
-                    stdout: '',
-                    stderr: err instanceof Error ? err.message : String(err),
-                    exitCode: 1,
-                };
             }
+            return { results, exitCode: 0, failedAt: null };
         },
     });
 }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { type AgentDefinition, claudeDirs, loadAgents } from './agents-loader.ts';
-export { type BashInput, type BashOutput, type BashToolInit, bashTool } from './bash-tool.ts';
+export { type BackgroundBashInput, type BackgroundBashOutput, type BackgroundProcessInit, type BackgroundProcessTools, type BashOutputInput, backgroundProcessTools, type KillBashInput, type KillBashOutput, type ListBackgroundOutput, ProcessManager, type ProcessOutput, type ProcessStatus, type SpawnFn, } from './background-process.ts';
+export { type BashInput, type BashOutput, type BashToolInit, bashTool, type MultiBashInput, type MultiBashOutput, multiBashTool, } from './bash-tool.ts';
 export { applyEdit, type EditFileInput, type EditFileOutput, type EditSpec, editFileTool, type MultiEditInput, type MultiEditOutput, multiEditTool, } from './edit-tools.ts';
 export { type EnvInfo, envBlock } from './env-block.ts';
 export { asString, asStringArray, type Frontmatter, type FrontmatterValue, parseFrontmatter, } from './frontmatter.ts';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { claudeDirs, loadAgents } from "./agents-loader.js";
-export { bashTool } from "./bash-tool.js";
+export { backgroundProcessTools, ProcessManager, } from "./background-process.js";
+export { bashTool, multiBashTool, } from "./bash-tool.js";
 export { applyEdit, editFileTool, multiEditTool, } from "./edit-tools.js";
 export { envBlock } from "./env-block.js";
 export { asString, asStringArray, parseFrontmatter, } from "./frontmatter.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@developerz.ai/ai-claude-compat",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Claude-Code-style agent primitives for the Vercel AI SDK: FS/bash tools, an <env> system-context block, a subagent-as-tool factory, and .claude/ skills/agents loading.",
   "license": "MIT",
   "type": "module",