wave-agent-sdk 1.2.0 → 1.3.0

package/dist/utils/runtimeDeps.js

@@ -0,0 +1,426 @@
+/**
+ * Runtime dependencies the CLI installs on demand.
+ *
+ * ## Why this exists
+ *
+ * Two dependencies live here: `sharp` (the image codec behind outbound image
+ * resizing, ~19MB unpacked) and `@vscode/ripgrep` (the search binary behind the
+ * Grep tool, ~5MB with its platform package). Both are too big to ship in every
+ * host bundle and useless to users who never send an image or run a search. Two
+ * of the three ways of getting the CLI can simply use npm:
+ *
+ * | how the CLI was installed | where the dependencies come from | what this does |
+ * | --- | --- | --- |
+ * | `npm i -g wave-code`, project install | plain npm dependencies (npm picks the matching platform package; sharp's libvips arrives through the platform package's own optionalDependencies) | step 1 short-circuits, nothing is downloaded |
+ * | desktop / VS Code / JetBrains (the host copies the CLI into `~/.wave/cli/<end>/`) | nothing ships them — the copy is three files (entry, package.json, bundle) | downloads into the shared `~/.wave/cli/node_modules` |
+ * | in-repo dev (`pnpm run wave`) | the repo's node_modules | step 1 short-circuits |
+ *
+ * It is deliberately CLI-side rather than per-host: the platform key is computed
+ * by the *same* runtime that later loads the module (a JVM-side arch guess
+ * cannot be), and one implementation covers the TUI, stdio (all three hosts),
+ * remote and daemon paths. ripgrep used to be the counter-example — each of the
+ * three hosts downloaded it before spawning the CLI, and the remote path shelled
+ * out to `npm install --prefix` — so the table replaced four implementations.
+ *
+ * ## Layout
+ *
+ * ```
+ * ~/.wave/cli/node_modules/          <- shared by all three hosts, survives CLI upgrades
+ *   sharp/  semver/  detect-libc/  @img/colour/
+ *   @img/sharp-<key>/                key = linux-x64 | linuxmusl-x64 | darwin-arm64 | win32-x64
+ *   @img/sharp-libvips-<key>/        must stay a sibling of the above: its .node has
+ *                                    rpath `$ORIGIN/../../sharp-libvips-<key>/lib`
+ *   @vscode/ripgrep/                 the wrapper (ESM, no dependencies of its own)
+ *   @vscode/ripgrep-<platform>-<arch>/  holds bin/rg, published with the exec bit
+ *   .wave-runtime-deps.json          <- marker, written last: present means this
+ *                                       batch completed
+ * ```
+ *
+ * Node resolves the modules from `~/.wave/cli/<end>/dist/bundle/wave.mjs` by
+ * walking up, which lands on this `node_modules`.
+ *
+ * ## Why detect-libc decides the platform key
+ *
+ * `linux-x64` and `linuxmusl-x64` are different downloads, and a wrong guess
+ * means a `.node` that refuses to dlopen. The key is therefore computed *by*
+ * `detect-libc` (the very module sharp consults, `dist/libvips.cjs`:
+ * `` `${process.platform}${isNonGlibcLinuxSync() ? familySync() : ""}-${process.arch}` ``)
+ * rather than by a copy of that logic. A future sharp that renames or drops a
+ * dependency is followed automatically; only a *renamed* dependency needs a
+ * code change here.
+ *
+ * A row can opt out of the libc family (`libcAwarePlatformKey: false`):
+ * `@vscode/ripgrep` publishes only `@vscode/ripgrep-linux-x64`, so a musl key
+ * would match nothing.
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { maxSatisfying } from "semver";
+import { logWarn, logger } from "./globalLogger.js";
+import { getImageProcessor, resetImageProcessor, resolveSharp, } from "./imageProcessor.js";
+import { extractNpmTarball } from "./npmTarball.js";
+import { getRgPath, resetRipgrep, resolveRipgrep } from "./ripgrep.js";
+/** npm registry mirror for China users (same choice as the ripgrep download). */
+export const RUNTIME_DEPS_REGISTRY = "https://registry.npmmirror.com";
+const MARKER_FILE = ".wave-runtime-deps.json";
+const sharpDependency = {
+    name: "sharp",
+    sharedPackages(entry) {
+        const requests = [
+            { name: "sharp", range: entry.version },
+        ];
+        // The plain JS deps come from sharp's own ranges, so a sharp upgrade that
+        // adds or drops one is followed without a code change.
+        for (const [name, range] of Object.entries(entry.dependencies ?? {})) {
+            requests.push({ name, range });
+        }
+        return requests;
+    },
+    platformPackages(entry, platformKey) {
+        // Platform builds are pinned exactly in sharp's optionalDependencies —
+        // including the libvips version, which no other field carries.
+        const optional = entry.optionalDependencies ?? {};
+        return ["@img/sharp", "@img/sharp-libvips"].map((prefix) => {
+            const name = `${prefix}-${platformKey}`;
+            const range = optional[name];
+            if (!range) {
+                throw new Error(`sharp 不支持当前平台（${platformKey}）：缺 ${name}`);
+            }
+            return { name, range };
+        });
+    },
+    isAvailable: () => getImageProcessor() !== undefined,
+    loadsFrom: (requireBase) => resolveSharp(requireFnFor(requireBase)) !== undefined,
+    onInstalled: () => resetImageProcessor(),
+};
+/**
+ * ripgrep row. The wrapper declares no dependencies of its own — only the
+ * platform packages in `optionalDependencies` — and keys them by
+ * `<platform>-<arch>` with no libc family.
+ */
+const ripgrepDependency = {
+    name: "@vscode/ripgrep",
+    sharedPackages(entry) {
+        return [{ name: "@vscode/ripgrep", range: entry.version }];
+    },
+    platformPackages(entry, platformKey) {
+        const name = `@vscode/ripgrep-${platformKey}`;
+        const range = entry.optionalDependencies?.[name];
+        if (!range) {
+            throw new Error(`ripgrep 不支持当前平台（${platformKey}）：缺 ${name}`);
+        }
+        return [{ name, range }];
+    },
+    libcAwarePlatformKey: false,
+    isAvailable: () => getRgPath() !== undefined,
+    loadsFrom: (requireBase) => resolveRipgrep(requireFnFor(requireBase)) !== undefined,
+    onInstalled: () => resetRipgrep(),
+};
+const RUNTIME_DEPENDENCIES = [
+    sharpDependency,
+    ripgrepDependency,
+];
+/** `<home>/.wave/cli` — where hosts copy the CLI into and share downloads. */
+function defaultCliHome() {
+    return path.join(os.homedir(), ".wave", "cli");
+}
+/**
+ * Whether this code runs from a CLI copy under the shared cli home.
+ *
+ * An npm-installed CLI (bundle under `<prefix>/lib/node_modules/wave-code/...`)
+ * must not self-install: Node would never look in `~/.wave/cli/node_modules`
+ * from there, and writing into a global npm prefix may lack permissions and
+ * gets pruned by the next `npm install`. Such a setup either already has the
+ * dependencies (the normal case) or degrades with an actionable warning.
+ */
+export function isManagedCliInstall(moduleUrl, cliHome = defaultCliHome()) {
+    let file;
+    try {
+        file = fileURLToPath(moduleUrl);
+    }
+    catch {
+        return false;
+    }
+    const relative = path.relative(cliHome, file);
+    return (relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative));
+}
+/** Nearest `package.json` upwards from [from] that declares [dependency]. */
+function findEntryPackageJson(from, dependency) {
+    let dir = path.dirname(from);
+    for (;;) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf-8"));
+            const range = parsed.dependencies?.[dependency];
+            if (range)
+                return { range };
+        }
+        catch {
+            // Unreadable or absent — keep walking towards the filesystem root.
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+async function downloadBuffer(url, fetchImpl) {
+    const res = await fetchImpl(url, { redirect: "follow" });
+    if (!res.ok) {
+        throw new Error(`下载失败（HTTP ${res.status}）：${url}`);
+    }
+    return Buffer.from(await res.arrayBuffer());
+}
+/** sha512/base64 check against the registry's `dist.integrity`. */
+export function verifyIntegrity(buffer, integrity) {
+    for (const part of integrity.split(/\s+/)) {
+        const separator = part.indexOf("-");
+        if (separator === -1)
+            continue;
+        const algorithm = part.slice(0, separator);
+        if (algorithm !== "sha512")
+            continue;
+        const actual = createHash("sha512").update(buffer).digest("base64");
+        if (actual !== part.slice(separator + 1)) {
+            throw new Error("下载内容 sha512 校验失败");
+        }
+        return;
+    }
+    throw new Error(`不支持的完整性摘要：${integrity}`);
+}
+/** Registry metadata for the highest version of [name] matching [range]. */
+async function resolveVersion(name, range, fetchImpl) {
+    const res = await fetchImpl(`${RUNTIME_DEPS_REGISTRY}/${name}`, {
+        redirect: "follow",
+    });
+    if (!res.ok) {
+        throw new Error(`获取 ${name} 元数据失败（HTTP ${res.status}）`);
+    }
+    const metadata = (await res.json());
+    const versions = metadata.versions ?? {};
+    const best = maxSatisfying(Object.keys(versions), range);
+    if (!best) {
+        throw new Error(`没有满足 ${range} 的 ${name} 版本`);
+    }
+    return { version: best, ...versions[best] };
+}
+/**
+ * A `require` rooted at [requireBase] — the cli home when the packages are
+ * already on disk, the temp dir mid-install. Used both to ask `detect-libc`
+ * which build to fetch and to verify an install afterwards.
+ */
+function requireFnFor(requireBase) {
+    return createRequire(path.join(requireBase, "index.js"));
+}
+/**
+ * Platform key of the native build. With [libcFamily] (the default) the key
+ * carries the libc family — `linuxmusl-x64` vs `linux-x64` — decided by
+ * `detect-libc`, resolved from `[requireBase]/node_modules` and falling back to
+ * Node's own report when it cannot be loaded. Dependencies that publish a single
+ * Linux build pass `false`.
+ */
+function runtimePlatformKey(requireBase, libcFamily = true) {
+    if (!libcFamily)
+        return `${process.platform}-${process.arch}`;
+    if (requireBase) {
+        try {
+            const detect = requireFnFor(requireBase)("detect-libc");
+            const family = detect.isNonGlibcLinuxSync?.()
+                ? (detect.familySync?.() ?? "")
+                : "";
+            return `${process.platform}${family}-${process.arch}`;
+        }
+        catch {
+            // Fall through to the report-based fallback.
+        }
+    }
+    let family = "";
+    if (process.platform === "linux") {
+        const report = process.report?.getReport();
+        if (!report?.header?.glibcVersionRuntime)
+            family = "musl";
+    }
+    return `${process.platform}${family}-${process.arch}`;
+}
+/** Write the tarball's entries under [dest], creating parent directories. */
+function writeEntries(dest, entries) {
+    for (const entry of entries) {
+        const target = path.join(dest, entry.path);
+        fs.mkdirSync(entry.kind === "directory" ? target : path.dirname(target), {
+            recursive: true,
+        });
+        if (entry.kind !== "file")
+            continue;
+        fs.writeFileSync(target, entry.data);
+        // npm publishes executables (the ripgrep binary) as 0755; without the exec
+        // bit every spawn fails with EACCES. Only the exec bit is worth restoring —
+        // the rest is umask's business. A no-op on Windows, where there is no mode.
+        if (entry.mode & 0o111)
+            fs.chmodSync(target, entry.mode & 0o777);
+    }
+}
+/** Fetch one package and unpack it into `modulesDir/<name>`. */
+async function fetchPackage(request, modulesDir, fetchImpl, known) {
+    const meta = known ?? (await resolveVersion(request.name, request.range, fetchImpl));
+    const tarball = meta.dist?.tarball;
+    if (!tarball) {
+        throw new Error(`${request.name}@${meta.version} 缺少下载地址`);
+    }
+    const buffer = await downloadBuffer(tarball, fetchImpl);
+    if (meta.dist?.integrity)
+        verifyIntegrity(buffer, meta.dist.integrity);
+    writeEntries(path.join(modulesDir, request.name), extractNpmTarball(buffer));
+}
+/**
+ * Install one dependency: download into a temp `node_modules` beside the real
+ * one, then move each package into place. A crash mid-way leaves the marker
+ * absent, so the next launch redoes the batch — packages already moved are
+ * skipped.
+ *
+ * Returns the platform key the batch was built for.
+ */
+async function installDependency(dependency, entry, cliHome, fetchImpl) {
+    const installDir = path.join(cliHome, "node_modules");
+    fs.mkdirSync(installDir, { recursive: true });
+    const tempDir = path.join(cliHome, `.wave-runtime-tmp-${process.pid}-${Math.random().toString(36).slice(2)}`);
+    const tempModules = path.join(tempDir, "node_modules");
+    fs.mkdirSync(tempModules, { recursive: true });
+    try {
+        const shared = dependency.sharedPackages(entry);
+        // detect-libc has to land first: it decides which native build to fetch.
+        for (const request of shared) {
+            await fetchPackage(request, tempModules, fetchImpl, 
+            // The entry package's metadata is already in hand — no second round trip.
+            request.name === dependency.name ? entry : undefined);
+        }
+        const platformKey = runtimePlatformKey(tempDir, dependency.libcAwarePlatformKey ?? true);
+        const platform = dependency.platformPackages(entry, platformKey);
+        for (const request of platform) {
+            await fetchPackage(request, tempModules, fetchImpl);
+        }
+        for (const { name } of [...shared, ...platform]) {
+            const target = path.join(installDir, name);
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            // Already there: either a previous run or a process racing us.
+            if (fs.existsSync(target))
+                continue;
+            try {
+                fs.renameSync(path.join(tempModules, name), target);
+            }
+            catch (error) {
+                const code = error.code;
+                const raced = code === "EEXIST" || code === "ENOTEMPTY" || code === "EPERM";
+                if (!raced)
+                    throw error;
+            }
+        }
+        return platformKey;
+    }
+    finally {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+}
+function readMarker(installDir) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(installDir, MARKER_FILE), "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+let inFlight;
+let settled;
+/**
+ * Make sure the runtime dependencies are installed. Never throws: the long-lived
+ * CLI entry points await it before serving, so a first pasted image (or a first
+ * search) cannot race a download — the same reason the hosts used to block on
+ * ripgrep before spawning the CLI. A failed install is reported once and only
+ * degrades images and grep.
+ *
+ * The outcome is memoised for the process lifetime, failures included — one
+ * attempt per launch, so a broken network does not retry on every image.
+ */
+export function ensureRuntimeDeps(options) {
+    if (settled)
+        return Promise.resolve(settled);
+    if (!inFlight) {
+        inFlight = runInstall(options).then((result) => {
+            settled = result;
+            return result;
+        }, (error) => {
+            settled = {
+                available: false,
+                reason: error instanceof Error ? error.message : String(error),
+            };
+            return settled;
+        });
+    }
+    return inFlight;
+}
+async function runInstall(options) {
+    const fetchImpl = options?.fetchImpl ?? fetch;
+    const moduleUrl = options?.moduleUrl ?? import.meta.url;
+    const cliHome = options?.cliHome ?? defaultCliHome();
+    if (RUNTIME_DEPENDENCIES.every((dependency) => dependency.isAvailable())) {
+        return { available: true };
+    }
+    if (!isManagedCliInstall(moduleUrl, cliHome)) {
+        const reason = "当前 wave CLI 不是 ~/.wave/cli 下的副本，无法自动安装运行时依赖" +
+            "（sharp / ripgrep）；请重装 wave-code（不要使用 --omit=optional）";
+        logWarn(`[Wave] ${reason}`);
+        return { available: false, reason };
+    }
+    const installDir = path.join(cliHome, "node_modules");
+    // One dependency failing must not skip the others: they degrade independently
+    // (a broken image codec has nothing to do with grep).
+    const failures = [];
+    for (const dependency of RUNTIME_DEPENDENCIES) {
+        if (dependency.isAvailable())
+            continue;
+        try {
+            const entry = findEntryPackageJson(fileURLToPath(moduleUrl), dependency.name);
+            if (!entry) {
+                fail(failures, `找不到声明 ${dependency.name} 依赖范围的 package.json`);
+                continue;
+            }
+            // A batch that completed but still will not load is a platform problem
+            // (wrong libc, unsupported CPU). Downloading ~19MB again on every launch
+            // would not fix it, so report instead.
+            if (readMarker(installDir)[dependency.name] === entry.range) {
+                fail(failures, `${dependency.name} 已安装但无法加载（平台 ${runtimePlatformKey(cliHome, dependency.libcAwarePlatformKey ?? true)}）`);
+                continue;
+            }
+            const meta = await resolveVersion(dependency.name, entry.range, fetchImpl);
+            const platformKey = await installDependency(dependency, meta, cliHome, fetchImpl);
+            // Verify through the cli home itself: the only require base that proves
+            // the layout works for the bundle that will load it.
+            if (!dependency.loadsFrom(cliHome)) {
+                fs.rmSync(path.join(installDir, MARKER_FILE), { force: true });
+                fail(failures, `${dependency.name} 安装后仍无法加载（平台 ${platformKey}）`);
+                continue;
+            }
+            dependency.onInstalled();
+            fs.writeFileSync(path.join(installDir, MARKER_FILE), `${JSON.stringify({ ...readMarker(installDir), [dependency.name]: entry.range }, null, 2)}\n`);
+            logger.info(`[Wave] 已安装 ${dependency.name} ${meta.version}（平台 ${platformKey}）到 ${installDir}`);
+        }
+        catch (error) {
+            fail(failures, `安装 ${dependency.name} 失败：${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (failures.length > 0)
+        return { available: false, reason: failures.join("；") };
+    return { available: true };
+}
+/** Log and record one dependency's failure, without aborting the batch. */
+function fail(failures, reason) {
+    logWarn(`[Wave] ${reason}`);
+    failures.push(reason);
+}
+/** Forget the memoised outcome, and the settled result (tests). */
+export function __resetRuntimeDepsForTesting() {
+    inFlight = undefined;
+    settled = undefined;
+}

package/dist/utils/skillParser.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "fs";
 import { dirname } from "path";
+import { parseFrontmatterYaml, splitFrontmatter } from "./frontmatterYaml.js";
 /**
  * Parse a SKILL.md file and validate its contents
  */
@@ -22,13 +23,12 @@ export function parseSkillFile(filePath, options = {}) {
         const content = readFileSync(filePath, "utf-8");
         result.content = content;
         // Parse YAML frontmatter
-        const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-        if (!frontmatterMatch) {
+        const { yaml } = splitFrontmatter(content);
+        if (yaml === null) {
             result.validationErrors.push("Missing YAML frontmatter");
             return result;
         }
-        const yamlContent = frontmatterMatch[1];
-        result.frontmatter = parseYamlFrontmatter(yamlContent);
+        result.frontmatter = parseYamlFrontmatter(yaml);
         if (!result.frontmatter.name || !result.frontmatter.description) {
             result.validationErrors.push("Missing required fields: name and description");
             return result;
@@ -88,56 +88,26 @@ export function parseSkillFile(filePath, options = {}) {
     }
 }
 /**
- * Simple YAML frontmatter parser for skill files
+ * Simple YAML frontmatter parser for skill files.
+ *
+ * The value parsing lives in `frontmatterYaml.ts` so skills, subagents, custom
+ * slash commands, memory rules and memory files all read frontmatter the same
+ * way (block scalars included — see spec `ecosystem/agent-skills` 场景 2).
+ * Here we only narrow the result to the fields a skill declares.
  */
 function parseYamlFrontmatter(yamlContent) {
-    const frontmatter = { name: "", description: "" };
-    try {
-        const lines = yamlContent.split("\n");
-        let currentKey = null;
-        for (const line of lines) {
-            const trimmed = line.trim();
-            if (!trimmed || trimmed.startsWith("#"))
-                continue;
-            // Check for list item
-            if (trimmed.startsWith("-") && currentKey) {
-                const value = trimmed
-                    .substring(1)
-                    .trim()
-                    .replace(/^["']|["']$/g, "");
-                if (value) {
-                    const existing = frontmatter[currentKey];
-                    if (Array.isArray(existing)) {
-                        existing.push(value);
-                    }
-                    else {
-                        frontmatter[currentKey] = [value];
-                    }
-                }
-                continue;
-            }
-            const colonIndex = trimmed.indexOf(":");
-            if (colonIndex === -1)
-                continue;
-            const key = trimmed.substring(0, colonIndex).trim();
-            const value = trimmed
-                .substring(colonIndex + 1)
-                .trim()
-                .replace(/^["']|["']$/g, "");
-            currentKey = key;
-            if (key && value) {
-                frontmatter[key] = value;
-            }
-            else if (key) {
-                // Key with no value on the same line, might be a list
-                frontmatter[key] = [];
-            }
-        }
-    }
-    catch {
-        // Return empty frontmatter on parse error - validation will catch missing fields
-    }
-    return frontmatter;
+    const parsed = parseFrontmatterYaml(yamlContent);
+    const asString = (key) => {
+        const value = parsed[key];
+        return typeof value === "string" ? value : undefined;
+    };
+    return {
+        ...parsed,
+        // Required fields must be strings: a bare `name:` / `description:` key
+        // parses to a list, which validation reports as missing.
+        name: asString("name") ?? "",
+        description: asString("description") ?? "",
+    };
 }
 /**
  * Validate skill metadata according to requirements

package/dist/utils/subagentParser.js

@@ -2,64 +2,60 @@ import { readFileSync, readdirSync, statSync } from "fs";
 import { homedir } from "os";
 import { join, extname, basename } from "path";
 import { logger } from "./globalLogger.js";
+import { parseFrontmatterYaml, splitFrontmatter, } from "./frontmatterYaml.js";
 import { getBuiltinSubagentsDir } from "./configPaths.js";
 /**
- * Parse YAML frontmatter from markdown file content
+ * Parse YAML frontmatter from markdown file content.
+ *
+ * Value parsing is shared with skills, custom slash commands and memory files —
+ * see `frontmatterYaml.ts` (spec `multi-agent/subagent` 场景 6).
  */
 function parseFrontmatter(content) {
-    const frontmatterRegex = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n([\s\S]*)$/;
-    const match = content.match(frontmatterRegex);
-    if (!match) {
+    const { yaml, body } = splitFrontmatter(content);
+    if (yaml === null) {
         return { frontmatter: {}, body: content.trim() };
     }
-    const [, yamlContent, body] = match;
-    const frontmatter = parseYamlFrontmatter(yamlContent);
-    return { frontmatter, body: body.trim() };
+    return {
+        frontmatter: toSubagentFrontmatter(parseFrontmatterYaml(yaml)),
+        body: body.trim(),
+    };
 }
 /**
- * Simple YAML frontmatter parser for subagent files
+ * Narrow a parsed frontmatter block to the fields a subagent declares. Values
+ * of an unexpected shape (e.g. a bare `description:` key, which parses to a
+ * list) are dropped so `validateConfiguration` reports the field as missing.
  */
-function parseYamlFrontmatter(yamlContent) {
+function toSubagentFrontmatter(parsed) {
     const frontmatter = {};
-    try {
-        const lines = yamlContent.split("\n");
-        for (const line of lines) {
-            const trimmed = line.trim();
-            if (!trimmed || trimmed.startsWith("#"))
-                continue;
-            const colonIndex = trimmed.indexOf(":");
-            if (colonIndex === -1)
-                continue;
-            const key = trimmed.substring(0, colonIndex).trim();
-            const value = trimmed
-                .substring(colonIndex + 1)
-                .trim()
-                .replace(/^["']|["']$/g, "");
-            if (key && value) {
-                // Handle array values for tools
-                if (key === "tools" && value) {
-                    let arrayValue = value;
-                    if (arrayValue.startsWith("[") && arrayValue.endsWith("]")) {
-                        arrayValue = arrayValue.slice(1, -1);
-                    }
-                    frontmatter[key] = arrayValue
-                        .split(",")
-                        .map((s) => s.trim())
-                        .filter(Boolean);
-                }
-                else {
-                    if (key === "name" || key === "description" || key === "model") {
-                        frontmatter[key] = value;
-                    }
-                }
-            }
+    for (const key of ["name", "description", "model"]) {
+        const value = parsed[key];
+        if (typeof value === "string" && value) {
+            frontmatter[key] = value;
         }
     }
-    catch {
-        // Return empty frontmatter on parse error - validation will catch missing fields
+    const tools = normalizeTools(parsed.tools);
+    if (tools) {
+        frontmatter.tools = tools;
     }
     return frontmatter;
 }
+/**
+ * Normalize the frontmatter `tools` field: a comma-separated string
+ * (`Read, Bash`), a bracketed list (`[Read, Bash]`) or a block list.
+ */
+function normalizeTools(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => item.trim()).filter(Boolean);
+    }
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const list = value.startsWith("[") && value.endsWith("]") ? value.slice(1, -1) : value;
+    return list
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
 /**
  * Validate subagent configuration
  */