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 @@ -4,6 +4,7 @@

- Refresh the MCP SDK to 1.31.0, Vitest to 5.0.2, Node typings, transitive dependencies, and pinned CodeQL actions to 4.38.2 while retaining Node.js 22.19 support; clear two dependency audit advisories.
- Time out plugin Git clones after 120 seconds, terminate stalled transport processes, and preserve existing installs on failure; override with `--clone-timeout-ms` or `OPENCLAW_BABELFISH_CLONE_TIMEOUT_MS`. Thanks @SebTardif.
- Cap background MCP tasks at eight isolated Hermes processes, holding slots until children exit while publishing task results promptly. Thanks @SebTardif.
- Accept in-root bundle directories whose names begin with two dots while retaining parent-traversal and symlink escape checks.
- Avoid leaving staging directories behind when a duplicate plugin install is rejected without `--force`.
- Preserve Markdown frontmatter in imported skills, commands, and output styles with Windows line endings or a closing delimiter at end of file.
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,9 +64,9 @@ Babelfish does not expose install or uninstall as agent tools. The read-only `ba
| `openclaw babelfish list [app]` | List installed plugins and detected surfaces |
| `openclaw babelfish install <app> <git-url> [--name <name>] [--force] [--clone-timeout-ms <ms>]` | Install a source plugin from Git. Clone waits 120 seconds by default; pass `--clone-timeout-ms` or set `OPENCLAW_BABELFISH_CLONE_TIMEOUT_MS` for a slower healthy remote |
| `openclaw babelfish uninstall <app> <name>` | Remove an imported plugin |
| `babelfish mcp` | Start the optional Hermes-only stdio MCP server |
| `babelfish mcp` | Start the optional Hermes-only stdio MCP server; background tasks allow eight isolated processes, including children still exiting after completion or stop |

The standalone MCP server is a compatibility fallback for MCP clients; native OpenClaw loading remains the recommended path. See [Manual MCP server](mcp/README.md) for setup and limitations.
The standalone MCP server is a compatibility fallback for MCP clients; native OpenClaw loading remains the recommended path. See [Manual MCP server](mcp/README.md) for setup and limitations. Task results become available when the helper returns; its concurrency slot remains occupied until the child exits.

## Development

Expand Down
2 changes: 1 addition & 1 deletion docs/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ Restart OpenClaw after installing or removing a plugin. OpenClaw plugin metadata

## Optional MCP compatibility mode

Use this mode only when an MCP client needs direct access to installed Hermes plugins without loading Babelfish as a native OpenClaw plugin. It starts a stdio MCP server that exposes available Hermes tools and commands, a read-only installed-plugin listing, and helpers for starting, checking, or stopping long-running Hermes calls.
Use this mode only when an MCP client needs direct access to installed Hermes plugins without loading Babelfish as a native OpenClaw plugin. It starts a stdio MCP server that exposes available Hermes tools and commands, a read-only installed-plugin listing, and helpers for starting, checking, or stopping long-running Hermes calls. `babelfish_task_start` rejects a new start when eight isolated children still occupy slots, including after status is completed, failed, or stopped but the process has not exited.

This mode covers Hermes plugins only. It does not provide Babelfish's native OpenClaw skills, hooks, middleware, or generated CLI commands.

Expand Down
5 changes: 5 additions & 0 deletions mcp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,8 @@ babelfish mcp

Configure an MCP client to launch that command over stdio. This directory is
not a Codex plugin bundle; native Codex app support is planned separately.

`babelfish_task_start` runs each call in an isolated Hermes process. At most
eight isolated children may occupy slots at once. `babelfish_task_status` can
show completed or failed as soon as the helper returns; the slot stays
occupied until that child exits.
57 changes: 53 additions & 4 deletions src/hermes-python.ts
Original file line number Diff line number Diff line change
Expand Up @@ -160,9 +160,14 @@ class BridgeProcess {
private nextRequestId = 1;
private pending = new Map<number, PendingRequest>();
private queue: Promise<void> = Promise.resolve();
private childExit: Promise<void> = Promise.resolve();

constructor(private readonly config: HermesBridgeConfig) {}

waitForExit(): Promise<void> {
return this.childExit;
}

request<T>(request: BridgeRequest, options: { signal?: AbortSignal }): Promise<T> {
const result = this.queue.then(
() => this.execute<T>(request, options),
Expand Down Expand Up @@ -207,15 +212,34 @@ class BridgeProcess {
env: { ...process.env, ...this.config.env },
stdio: ["pipe", "pipe", "pipe"],
});
let exitSettled = false;
let settleExit!: () => void;
this.childExit = new Promise<void>((resolve) => {
settleExit = () => {
if (exitSettled) {
return;
}
exitSettled = true;
resolve();
};
});
child.unref();
(child.stdin as unknown as UnrefHandle).unref();
(child.stdout as unknown as UnrefHandle).unref();
(child.stderr as unknown as UnrefHandle).unref();
this.child = child;
child.stdin.on("error", () => undefined);
child.stderr.pipe(process.stderr);
createInterface({ input: child.stdout }).on("line", (line) => this.handleLine(line));
child.on("error", (error) => this.stop(error));
child.on("error", (error) => {
if (child.pid === undefined) {
settleExit();
}
this.stop(error);
});
child.on("exit", () => settleExit());
child.on("close", (code) => {
settleExit();
if (this.child === child) {
this.stop(new Error(`Babelfish adapter exited with ${code}`));
}
Expand Down Expand Up @@ -280,13 +304,38 @@ function contextLane(context: HermesRuntimeContext): string | undefined {
return context.sessionKey ?? context.sessionId ?? context.agentId;
}

export type HermesHelperOptions = {
signal?: AbortSignal;
isolated?: boolean;
waitForExit?: boolean;
onOccupancy?: (occupancy: Promise<void>) => void;
};

function runHelper<T>(
config: HermesBridgeConfig,
request: BridgeRequest,
options: { signal?: AbortSignal; isolated?: boolean } = {},
options: HermesHelperOptions = {},
): Promise<T> {
if (options.isolated) {
const bridge = new BridgeProcess(config);
if (options.waitForExit) {
const result = bridge.request<T>(request, options);
const occupancy = result
.then(
() => undefined,
() => undefined,
)
.finally(async () => {
bridge.reset();
await bridge.waitForExit();
})
.then(
() => undefined,
() => undefined,
);
options.onOccupancy?.(occupancy);
return result;
}
return bridge.request<T>(request, options).finally(() => bridge.reset());
}
const key = `${bridgeKey(config)}:${requestLane(request)}`;
Expand Down Expand Up @@ -318,7 +367,7 @@ export function releaseHermesBridge(
export function callHermesTool(
config: HermesBridgeConfig,
params: { plugin?: string; tool: string; args: unknown; context?: HermesRuntimeContext },
options?: { signal?: AbortSignal; isolated?: boolean },
options?: HermesHelperOptions,
): Promise<HermesCallResult> {
return runHelper(config, {
op: "call",
Expand All @@ -333,7 +382,7 @@ export function callHermesTool(
export function callHermesCommand(
config: HermesBridgeConfig,
params: { plugin?: string; command: string; args: unknown; context?: HermesRuntimeContext },
options?: { signal?: AbortSignal; isolated?: boolean },
options?: HermesHelperOptions,
): Promise<HermesCommandResult> {
return runHelper(config, {
op: "command",
Expand Down
Loading
Loading