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

## 0.1.1 (Unreleased)

- Allow discovery and hooks without Python only for a verified absent or empty Hermes install; preserve failed installed guards and propagate pre-tool callback failures. Thanks @SebTardif.
- Keep concurrent turns waiting for their current session start, consume its context once, and recover later turns after a failed start without deleting a newer pending start. Thanks @SebTardif.
- Read folded and literal YAML descriptions for generated commands, agents, and output styles, preserving header comments, indentation, blank lines, and clip/strip/keep chomping across LF and CRLF; retain copied skill bodies, metadata, assets, and regeneration rollback. Thanks @SebTardif.
- Isolate imported hook command expansion failures while retaining a blocking decision for PreToolUse, UserPromptSubmit, and Stop, preserving prior results and later hooks; observers warn and continue. Thanks @SebTardif.
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ Installing an already installed name requires `--force`; a rejected duplicate le
| Prompt and terminal commands | User-invoked skills or top-level CLI commands when the source format supports them. Hermes MCP command tools accept optional `args`: omitted arguments, `{}`, or an empty `args` string pass `""`; explicit text is preserved. |
| Compatible hooks | Matching lifecycle, prompt, tool, compaction, and subagent hooks. Discovery permits 50 unique hook files and eight nested directories. Command-hook stdin is capped at 1 MiB; oversized decision events fail closed. String commands use a login shell; `args` or a `command` array spawn without a shell. |
| Compatible middleware | Matching prompt-build and tool-result middleware |
| Hermes availability | An absent or empty install needs no Python for discovery or hooks; installed or unknown providers still require it, and failed pre-tool guards prevent execution |
| Session-start context | Turn preparation waits for an in-flight session start. A failed start warns once instead of poisoning later turns; successful start context is consumed once. Concurrent prepares cannot bypass a pending start or remove a newer one. |
| Hook command expansion | An unresolved variable blocks PreToolUse, UserPromptSubmit, and Stop decisions while preserving earlier results and running later hooks. Observer expansion failures warn and continue. Execution-error handling is unchanged. |
| Stop hook decisions | On upgrade, installed Claude Code and Codex Stop hooks with `continue: false` finish the turn rather than request revision. This takes precedence over a block on the same hook only; a separate blocking hook still requests revision in either order. Pre-tool and prompt blocking is unchanged. |
Expand Down
12 changes: 12 additions & 0 deletions docs/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,18 @@ start context is consumed once per session and cleared at session end.

The selected Python environment must import each installed plugin and its dependencies. Plugins that import client internals also require the source client's Python package.

Discovery, hooks, and middleware can return empty results without Python only
after checking that the install directory is absent or empty. This check is not
cached and does not trust a generated registry. Unreadable paths, dangling
symlinks, and nonempty or incomplete installations do not establish absence.
Unexpanded user-home paths stay on the Python path; missing paths with `.` or
`..` components are not normalized into an absence claim.
Explicit tool, command, CLI command, and skill requests still require Python.

Installed guard failures remain failures: startup, import, registration, protocol,
timeout, and `pre_tool_call` or `tool_request` callback errors prevent the host
tool call. Other callback failures retain their warning-and-continue behavior.

```bash
export OPENCLAW_BABELFISH_HERMES_PLUGIN_DIR=/path/to/plugins
export OPENCLAW_BABELFISH_HERMES_PYTHON=/path/to/python3
Expand Down
4 changes: 4 additions & 0 deletions python/hermes_openclaw_bridge.py
Original file line number Diff line number Diff line change
Expand Up @@ -696,6 +696,8 @@ def _hook(payload: dict[str, Any]) -> dict[str, Any]:
try:
result = _invoke_event_callback(hook.callback, kwargs)
except Exception as exc:
if hook_name == "pre_tool_call":
raise
print(f"Hook '{hook.name}' callback failed: {exc}", file=sys.stderr)
continue
if result is not None:
Expand Down Expand Up @@ -737,6 +739,8 @@ def _middleware(payload: dict[str, Any]) -> dict[str, Any]:
try:
result = _invoke_event_callback(middleware.callback, callback_kwargs)
except Exception as exc:
if kind == "tool_request":
raise
print(f"Middleware '{middleware.kind}' callback failed: {exc}", file=sys.stderr)
continue
if result is not None:
Expand Down
119 changes: 119 additions & 0 deletions src/hermes-python.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import {
callHermesCommand,
callHermesTool,
invokeHermesHook,
invokeHermesMiddleware,
listHermesPlugins,
readHermesSkill,
releaseHermesBridge,
Expand Down Expand Up @@ -50,6 +51,102 @@ async function writeRoutingFixture(
}

describe("Hermes Python bridge", () => {
it.each(["empty", "missing", "nested-missing"])("skips Python only for a verified %s installation", async (kind) => {
const root = await fs.mkdtemp(path.join(os.tmpdir(), "babelfish-absence-"));
const installDir = kind === "empty" ? root : path.join(root, kind === "missing" ? "missing" : "missing/nested");
const config = { rootDir: root, installDir, python: path.join(root, "no-python"), timeoutMs: 1000, env: {} };
try {
await expect(listHermesPlugins(config)).resolves.toEqual({ installDir, plugins: [] });
await expect(invokeHermesHook(config, { hook: "pre_tool_call", kwargs: {} }))
.resolves.toEqual({ hook: "pre_tool_call", invoked: [], results: [] });
await expect(invokeHermesMiddleware(config, { kind: "tool_request", kwargs: {} }))
.resolves.toEqual({ middleware: "tool_request", invoked: [], results: [] });
for (const invoke of [
() => callHermesTool(config, { tool: "missing", args: {} }),
() => callHermesCommand(config, { command: "missing", args: "" }),
() => callHermesCliCommand(config, { command: "missing", args: [] }),
() => readHermesSkill(config, { skill: "missing" }),
]) await expect(invoke()).rejects.toThrow();
} finally {
await fs.rm(root, { recursive: true, force: true });
}
});

it("does not cache absence or infer it from incomplete files or a stale registry", async () => {
const root = await fs.mkdtemp(path.join(os.tmpdir(), "babelfish-unknown-"));
const config = { rootDir: root, installDir: root, python: path.join(root, "no-python"), timeoutMs: 1000, env: {} };
try {
await expect(listHermesPlugins(config)).resolves.toMatchObject({ plugins: [] });
await fs.writeFile(path.join(root, "plugin.yaml"), "name: incomplete\n");
await fs.writeFile(path.join(root, "babelfish.generated.json"), '{"plugins":[]}');
await expect(listHermesPlugins(config)).rejects.toThrow();
await expect(invokeHermesHook(config, { hook: "pre_tool_call", kwargs: {} })).rejects.toThrow();
await expect(invokeHermesMiddleware(config, { kind: "tool_request", kwargs: {} })).rejects.toThrow();
} finally {
await fs.rm(root, { recursive: true, force: true });
}
});

it("rejects unreadable installation discovery", async () => {
const error = Object.assign(new Error("denied"), { code: "EACCES" });
const read = vi.spyOn(fs, "readdir").mockRejectedValue(error);
try {
await expect(invokeHermesHook(
{ installDir: "unreadable", rootDir: ".", python: "python3", timeoutMs: 1000, env: {} },
{ hook: "pre_tool_call", kwargs: {} },
)).rejects.toThrow("denied");
} finally {
read.mockRestore();
}
});

it.each(["~", "~/guard", "~fixture/guard"])("leaves %s expansion to Python", async (installDir) => {
const read = vi.spyOn(fs, "readdir");
const config = { rootDir: ".", installDir, python: path.join(os.tmpdir(), "babelfish-no-such-python"), timeoutMs: 1000, env: {} };
try {
await expect(listHermesPlugins(config)).rejects.toThrow();
await expect(invokeHermesHook(config, { hook: "pre_tool_call", kwargs: {} })).rejects.toThrow();
await expect(invokeHermesMiddleware(config, { kind: "tool_request", kwargs: {} })).rejects.toThrow();
expect(read).not.toHaveBeenCalled();
} finally {
read.mockRestore();
}
});

it.skipIf(process.platform === "win32")("does not mistake dangling symlinks for absent installations", async () => {
const root = await fs.mkdtemp(path.join(os.tmpdir(), "babelfish-dangling-"));
const link = path.join(root, "link");
try {
await fs.symlink(path.join(root, "missing"), link);
for (const installDir of [link, path.join(link, "nested")]) {
await expect(listHermesPlugins({ rootDir: root, installDir, python: "python3", timeoutMs: 1000, env: {} }))
.rejects.toThrow();
}
} finally {
await fs.rm(root, { recursive: true, force: true });
}
});

it.skipIf(process.platform === "win32")("does not normalize away a missing component before an installed guard", async () => {
const root = await fs.mkdtemp(path.join(os.tmpdir(), "babelfish-path-identity-"));
try {
await copyFixture(path.join(root, "hermes"));
await fs.symlink(path.join(root, "absent-target"), path.join(root, "dangling"));
for (const prefix of ["missing", "dangling"]) {
const config = {
rootDir: root, installDir: `${root}/${prefix}/../hermes`,
python: "python3", timeoutMs: 1000, env: {},
};
await expect(listHermesPlugins(config)).rejects.toThrow();
await expect(invokeHermesHook(config, { hook: "pre_tool_call", kwargs: { tool_name: "blocked" } }))
.rejects.toThrow();
await expect(invokeHermesMiddleware(config, { kind: "tool_request", kwargs: {} })).rejects.toThrow();
}
} finally {
await fs.rm(root, { recursive: true, force: true });
}
});

it("lists and calls a Hermes register(ctx) tool", async () => {
const installDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-babelfish-"));
await copyFixture(installDir);
Expand Down Expand Up @@ -179,6 +276,28 @@ describe("Hermes Python bridge", () => {
).resolves.toMatchObject({ result: { state: "unset" } });
});

it("keeps discovery in the request lane before a concurrent tool call", async () => {
const installDir = await fs.mkdtemp(path.join(os.tmpdir(), "babelfish-discovery-order-"));
await copyFixture(installDir);
const config = { rootDir: installDir, installDir, python: "python3", timeoutMs: 10000, env: {} };
const context = { sessionId: "discovery-order" };
const readdir = fs.readdir.bind(fs);
const read = vi.spyOn(fs, "readdir").mockImplementationOnce(async () => {
await new Promise((resolve) => setTimeout(resolve, 50));
return readdir(installDir);
});
try {
const start = invokeHermesHook(config, { hook: "on_session_start", kwargs: { value: "ordered" }, context });
const call = callHermesTool(config, { plugin: "simple", tool: "simple_state", args: {}, context });
await expect(call).resolves.toMatchObject({ result: { state: "ordered" } });
await start;
} finally {
read.mockRestore();
releaseHermesBridge(config, context);
await fs.rm(installDir, { recursive: true, force: true });
}
});

it("does not block independent sessions behind one adapter lane", async () => {
const installDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-babelfish-"));
const pluginDir = path.join(installDir, "concurrent");
Expand Down
57 changes: 54 additions & 3 deletions src/hermes-python.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
import fs from "node:fs/promises";
import path from "node:path";
import { createInterface } from "node:readline";
import { fileURLToPath } from "node:url";
import type { HermesBridgeConfig } from "./config.js";
Expand Down Expand Up @@ -184,9 +186,22 @@ class BridgeProcess {
this.stop(new Error("Babelfish adapter reset"));
}

private execute<T>(request: BridgeRequest, options: { signal?: AbortSignal }): Promise<T> {
private async execute<T>(request: BridgeRequest, options: { signal?: AbortSignal }): Promise<T> {
if (options.signal?.aborted) {
return Promise.reject(new Error("Babelfish adapter call cancelled"));
throw new Error("Babelfish adapter call cancelled");
}
// Discovery stays in the request lane so asynchronous filesystem checks
// cannot let a turn or tool call overtake session initialization.
if (request.op === "list" || request.op === "hook" || request.op === "middleware") {
const empty = await isEmptyInstallation(request.installDir);
if (options.signal?.aborted) throw new Error("Babelfish adapter call cancelled");
if (empty) {
return (request.op === "list"
? { installDir: request.installDir, plugins: [] }
: request.op === "hook"
? { hook: request.hook, invoked: [], results: [] }
: { middleware: request.kind, invoked: [], results: [] }) as T;
}
}
const child = this.ensureChild();
const requestId = this.nextRequestId++;
Expand Down Expand Up @@ -250,7 +265,13 @@ class BridgeProcess {
private handleLine(line: string): void {
let response: BridgeResponse;
try {
response = JSON.parse(line) as BridgeResponse;
const parsed: unknown = JSON.parse(line);
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)
|| !("requestId" in parsed) || !Number.isSafeInteger(parsed.requestId)
|| ("error" in parsed ? typeof parsed.error !== "string" : !("result" in parsed))) {
throw new Error("invalid response envelope");
}
response = parsed as BridgeResponse;
} catch (error) {
this.stop(new Error(`Babelfish adapter returned invalid JSON: ${(error as Error).message}`));
return;
Expand Down Expand Up @@ -347,6 +368,36 @@ function runHelper<T>(
return bridge.request<T>(request, options);
}

async function isEmptyInstallation(installDir: string): Promise<boolean> {
// Python owns expanduser semantics, including named users and config.env HOME.
if (installDir.startsWith("~")) return false;
try {
return (await fs.readdir(installDir)).length === 0;
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
if (installDir.split(/[\\/]/).some((part) => part === "." || part === "..")) throw error;
// ENOENT also describes dangling symlinks. Verify the existing ancestor
// before treating a missing installation as absence of providers.
const resolvedInstallDir = path.resolve(installDir);
let candidate = resolvedInstallDir;
for (;;) {
let entry;
try {
entry = await fs.lstat(candidate);
} catch (ancestorError) {
if ((ancestorError as NodeJS.ErrnoException).code !== "ENOENT") throw ancestorError;
const parent = path.dirname(candidate);
if (parent === candidate) throw ancestorError;
candidate = parent;
continue;
}
const resolved = entry.isSymbolicLink() ? await fs.stat(candidate) : entry;
if (!resolved.isDirectory()) throw new Error("Hermes install ancestor is not a directory");
return candidate !== resolvedInstallDir;
}
}
}

export function listHermesPlugins(config: HermesBridgeConfig): Promise<HermesListResult> {
return runHelper(config, { op: "list", installDir: config.installDir }, { isolated: true });
}
Expand Down
30 changes: 30 additions & 0 deletions src/index.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,36 @@ async function copyFixture(target: string): Promise<void> {
}

describe("native OpenClaw hook entry", () => {
it("keeps imported guards active when Hermes is empty and Python is missing", async () => {
const root = await fs.mkdtemp(path.join(os.tmpdir(), "babelfish-no-hermes-"));
const plugin = path.join(root, "codex", "guard");
vi.stubEnv("OPENCLAW_BABELFISH_ROOT", root);
vi.stubEnv("OPENCLAW_BABELFISH_HERMES_PLUGIN_DIR", path.join(root, "hermes"));
vi.stubEnv("OPENCLAW_BABELFISH_HERMES_PYTHON", path.join(root, "missing-python"));
try {
await fs.mkdir(path.join(plugin, ".codex-plugin"), { recursive: true });
await fs.writeFile(path.join(plugin, "guard.mjs"),
'process.stdin.resume();process.stdin.on("end",()=>console.log(JSON.stringify({decision:"block",reason:"imported guard"})));');
await fs.writeFile(path.join(plugin, ".codex-plugin", "plugin.json"), JSON.stringify({
hooks: { PreToolUse: [{ hooks: [{ type: "command", command: [process.execPath, "guard.mjs"] }] }] },
}));
vi.resetModules();
const entry = (await import("./index.js")).default;
const hooks = new Map<string, (event: unknown, ctx: unknown) => unknown>();
entry.register({
on: (name, handler) => { hooks.set(name, handler); },
registerTool: () => undefined, registerCommand: () => undefined,
registerCli: () => undefined, registerAgentToolResultMiddleware: () => undefined,
logger: { warn: () => undefined },
});
await expect(hooks.get("before_tool_call")!({ toolName: "fixture", params: {} }, { sessionId: "guard" }))
.resolves.toEqual({ block: true, blockReason: "imported guard" });
} finally {
vi.unstubAllEnvs();
await fs.rm(root, { recursive: true, force: true });
}
});

it("consumes session-start context once and clears it on session end after reset", async () => {
const root = await fs.mkdtemp(path.join(os.tmpdir(), "babelfish-start-context-"));
const plugin = path.join(root, "codex", "start");
Expand Down
Loading
Loading