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)

- 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.
- Let a Stop hook with `continue: false` finish the turn. `decision: "block"` still asks OpenClaw to revise, and `continue: false` outranks a block on the same hook. Thanks @SebTardif.
- Pass an empty string when an MCP command tool is called without `args`, matching `babelfish_task_start`. Thanks @SebTardif.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ Installing an already installed name requires `--force`; a rejected duplicate le
| Source contribution | OpenClaw behavior |
| --- | --- |
| Agent and MCP tools | Native tools that retain the source JSON schema. MCP inspection follows at most 50 tool pages within one request-timeout budget and rejects repeated cursors. |
| Skills and support files | Native OpenClaw skills with referenced files intact; Markdown frontmatter supports LF and Windows CRLF line endings. In-root directory names such as `..skills` are supported. |
| Skills and support files | Native OpenClaw skills with referenced files intact; Markdown frontmatter supports LF and Windows CRLF. Generated command, agent, and output-style descriptions support literal and folded YAML blocks, header comments, one-digit indentation indicators, and clip/strip/keep chomping. Copied skill bodies and assets remain intact. In-root directory names such as `..skills` are supported. |
| 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 |
Expand Down
8 changes: 8 additions & 0 deletions docs/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,14 @@ Pre-tool and prompt hooks continue to treat `continue: false` as blocking.

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.

Generated descriptions read literal (`|`) and folded (`>`) YAML block scalars,
including header comments, single-digit indentation indicators, and `-`/`+`
chomping indicators in either order. Folding retains breaks around more-indented
content and repeated blank lines. Clip retains one final line break, strip
removes trailing breaks, and keep retains them, including before the Markdown
closing delimiter. LF and CRLF headers work without altering copied skill body
bytes or support files. This is a scalar reader, not general YAML parsing.

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
25 changes: 24 additions & 1 deletion src/bundle-plugins.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -455,7 +455,7 @@ process.exitCode = ${code};
await fs.mkdir(path.join(root, "output-styles"));
await fs.writeFile(
path.join(root, "output-styles", "brief.md"),
["---", "name: Brief", "description: Keep replies short", "keep-coding-instructions: true", "---", "Answer in three sentences."].join(eol),
["---", "name: Brief", "description: Keep replies short", "keep-coding-instructions:", " true", "---", "Answer in three sentences."].join(eol),
);
const plugin = await inspectBundlePlugin("claude-code", root);
expect(plugin.outputStyles).toEqual([{
Expand All @@ -466,6 +466,29 @@ process.exitCode = ${code};
}]);
});

it("reads a folded output-style description", async () => {
const root = await fixture("claude-code");
await fs.mkdir(path.join(root, "output-styles"));
await fs.writeFile(path.join(root, "output-styles", "brief.md"), [
"---",
"name: Brief",
"description: >",
" Keep replies short",
" and specific.",
"keep-coding-instructions: true",
"---",
"Answer in three sentences.",
"",
].join("\n"));
const plugin = await inspectBundlePlugin("claude-code", root);
expect(plugin.outputStyles).toEqual([{
name: "Brief",
description: "Keep replies short and specific.\n",
instructions: "Answer in three sentences.",
keepCodingInstructions: true,
}]);
});

it("discovers always-on Claude monitors and reports deferred triggers", async () => {
const root = await fixture("claude-code");
await fs.mkdir(path.join(root, "monitors"));
Expand Down
5 changes: 2 additions & 3 deletions src/bundle-plugins.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import type { BabelfishConfig, SupportedApp } from "./config.js";
import { appInstallDir } from "./config.js";
import { splitFrontmatter } from "./markdown.js";
import { readFrontmatterScalar, splitFrontmatter } from "./markdown.js";
import {
spawnShellCommand,
terminateShellProcessTree,
Expand Down Expand Up @@ -141,8 +141,7 @@ async function readOutputStyles(root: string, candidates: string[]): Promise<Bun
const source = await fs.readFile(path.join(directory, entry.name), "utf8");
const parsed = splitFrontmatter(source);
const frontmatter = parsed?.frontmatter ?? "";
const field = (name: string) => frontmatter.match(new RegExp(`^${name}:\\s*(.+)$`, "m"))?.[1]
?.trim().replace(/^['"]|['"]$/g, "");
const field = (name: string) => readFrontmatterScalar(frontmatter, name)?.value;
styles.push({
name: field("name") ?? path.basename(entry.name, path.extname(entry.name)),
description: field("description") ?? "Imported output style",
Expand Down
92 changes: 90 additions & 2 deletions src/markdown.test.ts
Original file line number Diff line number Diff line change
@@ -1,9 +1,17 @@
import { splitFrontmatter } from "./markdown.js";
import { readFrontmatterScalar, splitFrontmatter } from "./markdown.js";

it("preserves next-line scalar metadata without consuming a following key", () => {
expect(readFrontmatterScalar("keep-coding-instructions:\n true\nnext: kept\n", "keep-coding-instructions"))
.toEqual({ value: "true", consumed: [0, 1] });
expect(readFrontmatterScalar("description:\n\n 'next-line description'\nnext: kept\n", "description"))
.toEqual({ value: "next-line description", consumed: [0, 1, 2] });
expect(readFrontmatterScalar("description:\nnext: kept\n", "description")).toBeUndefined();
});

describe("splitFrontmatter", () => {
it("retains body bytes while normalizing frontmatter line endings", () => {
expect(splitFrontmatter("---\r\nname: demo\r\ndescription: Demo\r\n---\r\nBody.\r\n"))
.toEqual({ frontmatter: "name: demo\ndescription: Demo", body: "Body.\r\n" });
.toEqual({ frontmatter: "name: demo\ndescription: Demo\n", body: "Body.\r\n" });
});

it.each(["---\n---", "---\r\n---\r\n"])("accepts an empty header %j", (source) => {
Expand All @@ -16,3 +24,83 @@ describe("splitFrontmatter", () => {
},
);
});

describe("readFrontmatterScalar", () => {
it("keeps a one-line description", () => {
expect(readFrontmatterScalar('description: "Keep replies short"', "description")).toEqual({
value: "Keep replies short",
consumed: [0],
});
});

it("joins a folded description and leaves the next key", () => {
const frontmatter = [
"description: >",
" Keep replies short",
" and specific.",
"keep-coding-instructions: true",
].join("\n");
expect(readFrontmatterScalar(frontmatter, "description")).toEqual({
value: "Keep replies short and specific.\n",
consumed: [0, 1, 2],
});
expect(readFrontmatterScalar(frontmatter, "keep-coding-instructions")?.value).toBe("true");
});

it("keeps line breaks in a literal description", () => {
const frontmatter = [
"description: |",
" Commit the selected files",
" after reviewing the diff.",
"argument-hint: '[files]'",
].join("\n");
expect(readFrontmatterScalar(frontmatter, "description")).toEqual({
value: "Commit the selected files\nafter reviewing the diff.\n",
consumed: [0, 1, 2],
});
});

// YAML 1.2.2 sections 8.1.1.1, 8.1.1.2 and 8.1.3.
it.each([
["| # header", " alpha\n beta\n", "alpha\nbeta\n"],
[">- # header", " alpha\n beta\n", "alpha beta"],
["|2+", " alpha\n\n", "alpha\n\n"],
["|+2", " alpha\n\n", "alpha\n\n"],
[">", " alpha\n indented\n omega\n", "alpha\n indented\nomega\n"],
[">", " alpha\n\n\n omega\n", "alpha\n\nomega\n"],
[">", " alpha\n\n indented\n\n omega\n", "alpha\n\n indented\n\nomega\n"],
["|-", " alpha\n\n", "alpha"],
["|", " alpha\n\n", "alpha\n"],
["|+", " alpha\n\n", "alpha\n\n"],
[">-", "\n", ""],
[">", "\n", ""],
["|+", "\n", "\n"],
["|", " \n", ""],
["|+", " \n", "\n"],
["|", " alpha", "alpha"],
])("reads %s with content %j", (header, content, expected) => {
expect(readFrontmatterScalar(`description: ${header}\n${content}`, "description")?.value).toBe(expected);
});

it.each(["|12", ">0", "|+-", ">2-3"])("rejects invalid block header %s", (header) => {
expect(() => readFrontmatterScalar(`description: ${header}\n text\n`, "description")).toThrow(/Invalid block scalar header/);
});

it.each(["\n", "\r\n"])("preserves the closing-delimiter break and body bytes with %j", (eol) => {
for (const [indicator, expected] of [["|-", "alpha"], ["|", "alpha\n"], ["|+", "alpha\n\n"]]) {
const body = ` Body.${eol}${eol}`;
const source = ["---", `description: ${indicator} # comment`, " alpha", "", "---", body].join(eol);
const parsed = splitFrontmatter(source)!;
expect(parsed.body).toBe(body);
expect(readFrontmatterScalar(parsed.frontmatter, "description")?.value).toBe(expected);
}
});

it("keeps following metadata outside a block", () => {
const frontmatter = "description: >2- # comment\n alpha\n beta\nallowed-tools: Read\n";
expect(readFrontmatterScalar(frontmatter, "description")).toEqual({
value: "alpha beta", consumed: [0, 1, 2],
});
expect(readFrontmatterScalar(frontmatter, "allowed-tools")?.value).toBe("Read");
});
});
88 changes: 87 additions & 1 deletion src/markdown.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,94 @@
export function splitFrontmatter(source: string): { frontmatter: string; body: string } | undefined {
const match = /^---\r?\n(?:([\s\S]*?)\r?\n)?---(?:\r?\n|$)/.exec(source);
const match = /^---\r?\n(?:([\s\S]*?\r?\n))?---(?:\r?\n|$)/.exec(source);
if (!match) return undefined;
return {
frontmatter: (match[1] ?? "").replaceAll("\r\n", "\n"),
body: source.slice(match[0].length),
};
}

export function readFrontmatterScalar(
frontmatter: string,
name: string,
): { value: string; consumed: number[] } | undefined {
const normalized = frontmatter.replaceAll("\r\n", "\n");
const finalBreak = normalized.endsWith("\n");
const lines = normalized.split("\n");
if (finalBreak) lines.pop();
const key = new RegExp(`^${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}:\\s*(.*)$`);
for (let index = 0; index < lines.length; index += 1) {
const match = key.exec(lines[index] ?? "");
if (!match) continue;
const raw = (match[1] ?? "").trim();
const header = /^([|>])(?:([-+])([1-9])?|([1-9])([-+])?)?(?:[ \t]+#.*)?$/.exec(raw);
if (!header) {
if (/^[|>]/.test(raw)) throw new Error(`Invalid block scalar header for ${name}`);
if (!raw) {
let cursor = index + 1;
while (cursor < lines.length && !lines[cursor]?.trim()) cursor += 1;
const continuation = lines[cursor];
if (!continuation || !/^[ \t]+\S/.test(continuation)) return undefined;
return {
value: continuation.trim().replace(/^['"]|['"]$/g, ""),
consumed: Array.from({ length: cursor - index + 1 }, (_, offset) => index + offset),
};
}
return { value: raw.replace(/^['"]|['"]$/g, ""), consumed: [index] };
}
const indicator = header[3] ?? header[4];
const explicitIndent = indicator ? Number(indicator) : undefined;
const consumed = [index];
const content: string[] = [];
let contentIndent = explicitIndent;
if (contentIndent === undefined) {
const first = lines.slice(index + 1).find((line) => line.trim() !== "");
contentIndent = first?.match(/^ */)?.[0].length ?? 0;
}
let terminated = false;
let contentStarted = false;
for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
const line = lines[cursor] ?? "";
const indent = line.match(/^ */)?.[0].length ?? 0;
const blank = line.trim() === "";
if (!blank && (contentIndent === 0 || indent < contentIndent)) break;
if (blank && explicitIndent === undefined && !contentStarted && contentIndent > 0 && indent > contentIndent) {
throw new Error(`Invalid leading indentation for ${name}`);
}
const value = blank && (contentIndent === 0 || indent <= contentIndent) ? "" : line.slice(contentIndent);
content.push(value);
if (value !== "") contentStarted = true;
consumed.push(cursor);
terminated = cursor < lines.length - 1 || finalBreak;
}
return {
value: blockScalar(content, header[1] === ">", header[2] ?? header[5] ?? "", terminated),
consumed,
};
}
return undefined;
}

function blockScalar(lines: string[], folded: boolean, chomping: string, terminated: boolean): string {
let lastContent = lines.length - 1;
while (lastContent >= 0 && lines[lastContent] === "") lastContent -= 1;
const moreIndented = (line: string) => /^[ \t]/.test(line);
let text = "";
for (const [index, line] of lines.entries()) {
text += line;
if (index === lines.length - 1 && !terminated) break;
if (!folded || index >= lastContent || line === "") {
text += "\n";
} else {
const next = lines[index + 1] ?? "";
let nextContentIndex = index + 1;
while (nextContentIndex < lastContent && lines[nextContentIndex] === "") nextContentIndex += 1;
const nextContent = lines[nextContentIndex] ?? "";
// Breaks around more-indented content are never folded.
if (moreIndented(line) || moreIndented(nextContent)) text += "\n";
else if (next !== "") text += " ";
}
}
if (chomping === "+") return text;
const stripped = text.replace(/\n+$/, "");
return chomping === "-" || lastContent < 0 || !text.endsWith("\n") ? stripped : `${stripped}\n`;
}
Loading
Loading