Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
- Refresh the MCP SDK, development dependencies, npm 11 tooling, and pinned CodeQL actions while retaining Node.js 22.19 support.
- Bound imported command-hook stdout and stderr so noisy hooks cannot exhaust
OpenClaw memory before their timeout.
- Preserve literal arguments in exec-form command hooks while retaining Windows process-tree supervision. Thanks @SebTardif.
- Add a Docker constrained-memory matrix covering build, tests, packaging,
three-app plugin lifecycle, generated tools, and MCP stdio down to 256 MiB.

Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,15 +41,15 @@ Babelfish preserves source names when they are unique and qualifies collisions w
| Agent and MCP tools | Native tools that retain the source JSON schema |
| Skills and support files | Native OpenClaw skills with referenced files intact |
| Prompt and terminal commands | User-invoked skills or top-level CLI commands when the source format supports them |
| Compatible hooks | Matching lifecycle, prompt, tool, compaction, and subagent hooks |
| Compatible hooks | Matching lifecycle, prompt, tool, compaction, and subagent hooks. String commands use a login shell; `args` or a `command` array spawn without a shell. |
| Compatible middleware | Matching prompt-build and tool-result middleware |
| Unsupported behavior | Recorded during generation and reported at Gateway startup |

Support differs by source app and surface. See the [compatibility reference](docs/compatibility.md) for the full matrix, source-specific behavior, configuration, and example plugins.

## Trust and lifecycle

Installing a plugin executes code from its repository while Babelfish inspects MCP tools and later runs imported hooks or tools. Review the source before installing it.
Installing a plugin executes code from its repository while Babelfish inspects MCP tools and later runs imported hooks or tools. Review the source before installing it. String hook commands are full shell execution. Hooks that declare `args` or a `command` array spawn the listed executable directly.

Babelfish does not expose install or uninstall as agent tools. The read-only `babelfish_plugins_list` agent tool reports installed plugins and detected surfaces. Restart OpenClaw after installing, updating, or removing an imported plugin because OpenClaw loads plugin metadata and tool contracts at process startup.

Expand Down
51 changes: 45 additions & 6 deletions assets/windows-job.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,11 @@ param(
[ValidateSet("command", "monitor")]
[string]$Mode,

[Parameter(Mandatory = $true)]
[string]$CommandBase64
[Parameter(Mandatory = $true, ParameterSetName = "Command")]
[string]$CommandBase64,

[Parameter(Mandatory = $true, ParameterSetName = "Argv")]
[string]$ArgvBase64
)

$ErrorActionPreference = "Stop"
Expand Down Expand Up @@ -427,7 +430,37 @@ public static class BabelfishJob {
}
}

private static string QuoteArgument(string argument) {
var quoted = new StringBuilder("\"");
int backslashes = 0;
foreach (char character in argument) {
if (character == '\\') {
backslashes++;
continue;
}
quoted.Append('\\', character == '"' ? backslashes * 2 + 1 : backslashes);
quoted.Append(character);
backslashes = 0;
}
quoted.Append('\\', backslashes * 2);
return quoted.Append('"').ToString();
}

public static int RunArgv(string executable, string[] arguments, string mode) {
var commandLine = new StringBuilder(QuoteArgument(executable));
foreach (string argument in arguments) {
commandLine.Append(' ').Append(QuoteArgument(argument));
}
return RunProcess(executable, commandLine, mode);
}

public static int Run(string command, string mode, string commandShell) {
return RunProcess(commandShell, new StringBuilder(
"\"" + commandShell + "\" /d /s /c \"" + command + "\""
), mode);
}

private static int RunProcess(string executable, StringBuilder commandLine, string mode) {
IntPtr job = CreateKillOnCloseJob();
IntPtr childStdin;
IntPtr parentStdin;
Expand All @@ -439,13 +472,10 @@ public static class BabelfishJob {
CreateChildOutputPipe(out parentStdout, out childStdout);
CreateChildOutputPipe(out parentStderr, out childStderr);

var commandLine = new StringBuilder(
"\"" + commandShell + "\" /d /s /c \"" + command + "\""
);
PROCESS_INFORMATION child;
try {
child = CreateProcessInJob(
commandShell,
executable,
commandLine,
job,
childStdin,
Expand Down Expand Up @@ -510,6 +540,15 @@ public static class BabelfishJob {
}
"@

if ($PSCmdlet.ParameterSetName -eq "Argv") {
$argvJson = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($ArgvBase64))
# Windows PowerShell returns the JSON array as one pipeline object.
[string[]]$commandArgv = ConvertFrom-Json -InputObject $argvJson
$executable = (Get-Command -Name $commandArgv[0] -CommandType Application -ErrorAction Stop | Select-Object -First 1).Source
[string[]]$arguments = @($commandArgv | Select-Object -Skip 1)
exit [BabelfishJob]::RunArgv($executable, $arguments, $Mode)
}

$command = [Text.Encoding]::UTF8.GetString(
[Convert]::FromBase64String($CommandBase64)
)
Expand Down
3 changes: 2 additions & 1 deletion docs/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ Babelfish translates plugin behavior from Claude Code, Codex, and Hermes Agent i
| User prompt commands | Full | N/A | Partial | Hermes commands become native slash commands; Claude commands become user-only skills |
| Terminal CLI commands | Full | N/A | N/A | Registered as top-level `openclaw <command>` commands |
| Command-hook process output | N/A | 1 MiB per stream | 1 MiB per stream | Codex and Claude Code command hooks are terminated and reported as failed if stdout or stderr exceeds the limit |
| Command-hook invocation | N/A | String shell or exec `args` | String shell or exec `args` | String `command` runs via `/bin/sh -lc` (Windows uses `cmd.exe`). `args` or a `command` array spawn the executable without shell parsing. Both forms retain Windows Job supervision and process-tree cleanup. Plugin install is trusted code execution. |
| Plugin-defined agents | N/A | N/A | Partial | Imported as user-only skills; model and tool isolation are not preserved |
| Pre-tool command hooks | Full | Full | Full | Blocks and argument rewrites map to OpenClaw's pre-tool hook |
| Permission command hooks | N/A | No | No | OpenClaw has no equivalent approval-boundary event |
Expand All @@ -42,7 +43,7 @@ Babelfish translates plugin behavior from Claude Code, Codex, and Hermes Agent i

Babelfish reads `.claude-plugin/plugin.json`, declared or conventional skill, command, agent, output-style, hook, and MCP paths. Existing `SKILL.md` directories are copied intact. Markdown commands, agents, and output styles are converted to user-invoked OpenClaw skills.

Command hooks run with `${CLAUDE_PLUGIN_ROOT}` set to the installed plugin directory. `command` handlers are supported. Single-turn `prompt` handlers use the active OpenClaw agent and model when `plugins.entries.babelfish.llm` allows both agent and model overrides. Without those trust flags they are reported but not executed. Multi-turn `agent` handlers are unsupported.
Command hooks run with `${CLAUDE_PLUGIN_ROOT}` set to the installed plugin directory. String `command` handlers run through a login shell. When `args` is set (Claude Code exec form), or when `command` is a string array, Babelfish spawns the executable directly without a shell. Single-turn `prompt` handlers use the active OpenClaw agent and model when `plugins.entries.babelfish.llm` allows both agent and model overrides. Without those trust flags they are reported but not executed. Multi-turn `agent` handlers are unsupported.

## Codex

Expand Down
46 changes: 46 additions & 0 deletions src/bundle-plugins.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,52 @@ describe("bundle plugins", () => {
expect(plugin.hooks).toMatchObject([{ event: "SessionStart", command: "node hook.mjs" }]);
});

it("discovers exec-form command hooks from args and command arrays", async () => {
const root = await fixture("claude-code");
await fs.writeFile(
path.join(root, "hooks", "hooks.json"),
JSON.stringify({
hooks: {
SessionStart: [{ hooks: [{ type: "command", command: "node", args: ["hook.mjs"] }] }],
SessionEnd: [{ hooks: [{ type: "command", command: ["node", "hook.mjs", "done"] }] }],
},
}),
);
const plugin = await inspectBundlePlugin("claude-code", root);
expect(plugin.hooks).toEqual(expect.arrayContaining([
expect.objectContaining({ event: "SessionStart", command: "node", args: ["hook.mjs"] }),
expect.objectContaining({ event: "SessionEnd", command: "node", args: ["hook.mjs", "done"] }),
]));
});

it("executes argv command hooks without a shell", async () => {
const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), "babelfish-root-"));
const pluginRoot = path.join(rootDir, "codex", "fixture");
await fs.mkdir(path.join(pluginRoot, ".codex-plugin"), { recursive: true });
await fs.writeFile(
path.join(pluginRoot, "argv-hook.mjs"),
"process.stdin.resume(); process.stdin.on('end', () => console.log(JSON.stringify({hookSpecificOutput:{hookEventName:'SessionStart',additionalContext:process.argv.slice(2).join('\\0')}})));",
);
await fs.writeFile(
path.join(pluginRoot, ".codex-plugin", "plugin.json"),
JSON.stringify({
hooks: {
SessionStart: [{ hooks: [{
type: "command",
command: "node",
args: ["${PLUGIN_ROOT}/argv-hook.mjs", "$(echo INJECTED)"],
}] }],
},
}),
);
const results = await invokeBundleHooks(
{ rootDir, installDir: path.join(rootDir, "hermes"), python: "python3", timeoutMs: fixtureTimeoutMs, env: {} },
"SessionStart",
{},
);
expect(results.map(hookAdditionalContext)).toEqual(["$(echo INJECTED)"]);
}, 30_000);

it("executes compatible command hooks", async () => {
const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), "babelfish-root-"));
const plugin = await fixture("codex");
Expand Down
44 changes: 39 additions & 5 deletions src/bundle-plugins.ts
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ export type BundleHook = {
matcher?: string;
type: "command" | "prompt";
command?: string;
args?: string[];
prompt?: string;
timeoutMs: number;
};
Expand Down Expand Up @@ -240,18 +241,43 @@ function inlineServers(value: unknown): BundleServer[] {
return servers;
}

function commandArgv(value: unknown): string[] | undefined {
if (!Array.isArray(value)) {
return undefined;
}
return value.filter((entry): entry is string => typeof entry === "string");
}

function commandHook(app: BundlePlugin["app"], entry: JsonObject): BundleHook | undefined {
const timeout = typeof entry.timeout === "number" ? entry.timeout : 60;
if (entry.type === "command" && typeof entry.command === "string" && entry.command.trim()) {
return { event: "", type: "command", command: entry.command, timeoutMs: Math.max(1000, timeout * 1000) };
const timeoutMs = Math.max(1000, timeout * 1000);
if (entry.type === "command") {
const argvCommand = commandArgv(entry.command);
if (argvCommand) {
const file = argvCommand[0]?.trim();
if (!file) {
return undefined;
}
return { event: "", type: "command", command: argvCommand[0], args: argvCommand.slice(1), timeoutMs };
}
if (typeof entry.command === "string" && entry.command.trim()) {
const args = commandArgv(entry.args);
return {
event: "",
type: "command",
command: entry.command,
...(args ? { args } : {}),
timeoutMs,
};
}
}
if (
app === "claude-code"
&& entry.type === "prompt"
&& typeof entry.prompt === "string"
&& entry.prompt.trim()
) {
return { event: "", type: "prompt", prompt: entry.prompt, timeoutMs: Math.max(1000, timeout * 1000) };
return { event: "", type: "prompt", prompt: entry.prompt, timeoutMs };
}
return undefined;
}
Expand Down Expand Up @@ -720,7 +746,7 @@ export async function invokeBundleHooks(
}
continue;
}
const command = expandRoot(hook.command!, plugin.path);
const command = expandHookCommand(hook, plugin.path);
let output: Awaited<ReturnType<typeof runHookCommand>>;
try {
output = await runHookCommand(command, plugin.path, currentPayload, hook.timeoutMs);
Expand Down Expand Up @@ -787,8 +813,16 @@ export function hookUpdatedInput(result: JsonObject): JsonObject | undefined {
return object(specific?.updatedInput) ?? object(specific?.updatedMCPToolInput);
}

function expandHookCommand(hook: BundleHook, pluginRoot: string): string | string[] {
const command = hook.command ?? "";
if (hook.args) {
return [expandRoot(command, pluginRoot), ...hook.args.map((arg) => expandRoot(arg, pluginRoot))];
}
return expandRoot(command, pluginRoot);
}

function runHookCommand(
command: string,
command: string | readonly string[],
cwd: string,
payload: JsonObject,
timeoutMs: number,
Expand Down
77 changes: 77 additions & 0 deletions src/shell-command.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,83 @@ describe("spawnShellCommand", () => {
);
});

it("spawns argv commands without a POSIX login shell", () => {
const child = {} as ChildProcess;
const spawn = vi.fn(() => child);

expect(
spawnShellCommand(["node", "hook.mjs", "safe; echo pwned"], { cwd: "/tmp" }, "linux", spawn),
).toBe(child);
expect(spawn).toHaveBeenCalledWith(
"node",
["hook.mjs", "safe; echo pwned"],
{ cwd: "/tmp" },
);
expect(spawn.mock.calls[0]?.[1]).not.toContain("-lc");
});

it("keeps Windows argv commands inside the Job supervisor", () => {
const child = {} as ChildProcess;
const spawn = vi.fn(() => child);

expect(
spawnShellCommand(["node", "hook.mjs"], { cwd: "C:\\work" }, "win32", spawn),
).toBe(child);
const [executable, args, options] = spawn.mock.calls[0]!;
expect(executable).toMatch(/powershell\.exe$/);
expect(args).toContain("-ArgvBase64");
expect(JSON.parse(Buffer.from(args.at(-1)!, "base64").toString("utf8")))
.toEqual(["node", "hook.mjs"]);
expect(options).toEqual({ cwd: "C:\\work", detached: false, windowsHide: true });
});

it("rejects an empty argv command", () => {
const spawn = vi.fn();
expect(() => spawnShellCommand([], { cwd: "/tmp" }, "linux", spawn)).toThrow(/empty/i);
expect(spawn).not.toHaveBeenCalled();
});

it("preserves literal argv through the platform launcher", async () => {
const args = ["", "two words", "a\"b", "back\\slash\\", "trail space\\", "$(echo changed)", "%PATH%", "x & y", "日本語"];
const child = spawnShellCommand(
[process.execPath, "-e", "process.stdout.write(JSON.stringify(process.argv.slice(1)))", ...args],
{ detached: true, stdio: ["ignore", "pipe", "pipe"] },
);
const stdout: Buffer[] = [];
const stderr: Buffer[] = [];
child.stdout!.on("data", (chunk: Buffer) => stdout.push(chunk));
child.stderr!.on("data", (chunk: Buffer) => stderr.push(chunk));
const [code] = await once(child, "close");
expect(Buffer.concat(stderr).toString("utf8")).toBe("");
expect(code).toBe(0);
expect(JSON.parse(Buffer.concat(stdout).toString("utf8"))).toEqual(args);
}, 15_000);

it("terminates argv command descendants with their supervisor", async () => {
const child = spawnShellCommand([
process.execPath, "-e",
"const {spawn}=require('node:child_process'); const worker=spawn(process.execPath,['-e','setInterval(()=>{},1000)'],{stdio:'ignore'}); console.log(worker.pid); setInterval(()=>{},1000);",
], { detached: true, stdio: ["ignore", "pipe", "pipe"] });
let workerPid: number | undefined;
const closed = once(child, "close");
try {
let stdout = "";
child.stdout!.on("data", (chunk: Buffer) => { stdout += chunk.toString(); });
await vi.waitFor(() => expect(stdout).toMatch(/^\d+\s/), { timeout: 10_000 });
workerPid = Number(stdout.trim());
terminateShellProcessTree(child);
await closed;
await vi.waitFor(() => {
expect(() => process.kill(workerPid!, 0)).toThrow();
}, { timeout: 5_000 });
} finally {
terminateShellProcessTree(child, process.platform, "SIGKILL");
if (workerPid) {
try { process.kill(workerPid, "SIGKILL"); } catch { /* Already exited. */ }
}
}
}, 20_000);

it("delegates Windows command parsing to the native shell", () => {
const child = new EventEmitter() as ChildProcess;
const spawn = vi.fn(() => child);
Expand Down
18 changes: 14 additions & 4 deletions src/shell-command.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ function windowsPowerShellPath(systemRoot = process.env.SystemRoot): string {
}

function spawnWindowsJobCommand(
command: string,
command: string | readonly string[],
mode: "command" | "monitor",
options: Omit<SpawnOptions, "shell">,
spawnProcess: SpawnProcess,
Expand All @@ -43,19 +43,29 @@ function spawnWindowsJobCommand(
windowsJobScript,
"-Mode",
mode,
"-CommandBase64",
Buffer.from(command, "utf8").toString("base64"),
typeof command === "string" ? "-CommandBase64" : "-ArgvBase64",
Buffer.from(typeof command === "string" ? command : JSON.stringify(command), "utf8").toString("base64"),
],
{ ...options, detached: false, windowsHide: true },
);
}

export function spawnShellCommand(
command: string,
command: string | readonly string[],
options: Omit<SpawnOptions, "shell">,
platform: NodeJS.Platform = process.platform,
spawnProcess: SpawnProcess = spawn,
): ChildProcess {
if (typeof command !== "string") {
const [file, ...args] = command;
if (!file) {
throw new Error("Command argv is empty");
}
if (platform === "win32") {
return spawnWindowsJobCommand(command, "command", options, spawnProcess);
}
return spawnProcess(file, args, options);
}
if (platform === "win32") {
return spawnWindowsJobCommand(command, "command", options, spawnProcess);
}
Expand Down