maestro-agent-sdk 0.1.4 → 0.1.6

package/dist/tools/builtin/glob.js

@@ -0,0 +1,235 @@
+import { readdirSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, sep } from "node:path";
+/**
+ * `Glob` builtin — claude-SDK parity file-pattern matcher.
+ *
+ * Mirrors the upstream `Glob` tool's name + schema so the model's pretrained
+ * instinct calls our handler with the right shape. Returns absolute paths
+ * sorted by mtime descending (recently-modified first) — that ordering is
+ * what makes the tool actually useful: when a developer types `**\/*.tsx`
+ * what they usually want is "what did I touch in this codebase recently?",
+ * not an arbitrary readdir order.
+ *
+ * Pattern syntax (a sane subset of shell glob, no minimatch dep):
+ *   - `*`     — zero or more chars within one path segment (no `/`)
+ *   - `**`    — zero or more chars including `/` (cross-segment)
+ *   - `**\/`  — zero or more path segments + separator
+ *   - `?`     — exactly one char within one segment (no `/`)
+ *   - Other characters match literally; regex metacharacters are escaped.
+ *
+ * Implementation: compile the pattern to a regex once, then walk the
+ * directory tree and test the relative path of each file. Deliberately
+ * does NOT skip dotfiles or build directories — the user's pattern is
+ * authoritative, and silently filtering would surprise them when
+ * `**\/*.ts` doesn't list files in `.next/` even though they're there.
+ *
+ * Bounds:
+ *   - 10,000-file ceiling so a pathological pattern (`**\/*`) in a giant
+ *     monorepo can't pin the loop. Past the cap we stop walking and
+ *     surface a `truncated: true` flag.
+ *   - 30s walk timeout via the wall-clock check on each readdir iteration.
+ */
+/** Hard cap on results so a pathological pattern doesn't blow out context. */
+const MAX_RESULTS = 10_000;
+/** Hard cap on wall time spent walking — prevents the loop pinning on a
+ *  pathological filesystem. */
+const WALK_TIMEOUT_MS = 30_000;
+export const globTool = {
+    // Pure read of the filesystem — safe to run in parallel with anything
+    // that doesn't write the same tree.
+    parallelSafe: true,
+    schema: {
+        name: "Glob",
+        description: "Fast file pattern matching. Supports `*` (within-segment wildcard), " +
+            "`**` (cross-segment wildcard), `?` (one char). Returns absolute paths " +
+            "sorted by modification time descending — recently-touched files first. " +
+            "Does NOT skip dotfiles or build dirs; the model's pattern is authoritative. " +
+            "Caps results at 10,000 entries (truncates with a note when exceeded).",
+        input_schema: {
+            type: "object",
+            properties: {
+                pattern: {
+                    type: "string",
+                    description: "Glob pattern. Examples: `**/*.ts`, `src/**/*.tsx`, `README.md`, " +
+                        "`config/*.json`. Matched against paths relative to `path`.",
+                },
+                path: {
+                    type: "string",
+                    description: "Optional absolute directory to search in. Defaults to the SDK's process cwd. " +
+                        "Relative paths are rejected.",
+                },
+            },
+            required: ["pattern"],
+        },
+    },
+    async execute(input) {
+        const pattern = typeof input.pattern === "string" ? input.pattern : "";
+        if (!pattern) {
+            return JSON.stringify({ error: "Glob: missing 'pattern' argument" });
+        }
+        const rawPath = typeof input.path === "string" ? input.path : undefined;
+        let root;
+        if (rawPath !== undefined) {
+            if (!isAbsolute(rawPath)) {
+                return JSON.stringify({
+                    error: `Glob: 'path' must be absolute, got '${rawPath}'`,
+                });
+            }
+            root = rawPath;
+        }
+        else {
+            root = process.cwd();
+        }
+        let rootStat;
+        try {
+            rootStat = statSync(root);
+        }
+        catch (e) {
+            return JSON.stringify({
+                error: `Glob: cannot stat root '${root}': ${e instanceof Error ? e.message : String(e)}`,
+            });
+        }
+        if (!rootStat.isDirectory()) {
+            return JSON.stringify({
+                error: `Glob: 'path' must point to a directory, got '${root}'`,
+            });
+        }
+        let regex;
+        try {
+            regex = compileGlob(pattern);
+        }
+        catch (e) {
+            return JSON.stringify({
+                error: `Glob: failed to compile pattern '${pattern}': ${e instanceof Error ? e.message : String(e)}`,
+            });
+        }
+        const matches = [];
+        const startedAt = Date.now();
+        let truncated = false;
+        let timedOut = false;
+        function shouldStop() {
+            if (matches.length >= MAX_RESULTS) {
+                truncated = true;
+                return true;
+            }
+            if (Date.now() - startedAt > WALK_TIMEOUT_MS) {
+                timedOut = true;
+                return true;
+            }
+            return false;
+        }
+        function walk(dir) {
+            if (shouldStop())
+                return;
+            let names;
+            try {
+                // `readdirSync` without `withFileTypes` returns a string[], which we
+                // narrow with statSync per entry — avoids the Dirent generic variance
+                // (Node's @types declare both `Dirent<NonSharedBuffer>` and
+                // `Dirent<string>` overloads, and TS can't always pick the right one).
+                names = readdirSync(dir);
+            }
+            catch {
+                // Unreadable directory (perm denied, vanished) — skip silently.
+                return;
+            }
+            for (const name of names) {
+                if (shouldStop())
+                    return;
+                const abs = join(dir, name);
+                let stat;
+                try {
+                    stat = statSync(abs);
+                }
+                catch {
+                    continue;
+                }
+                if (stat.isDirectory()) {
+                    walk(abs);
+                    continue;
+                }
+                if (!stat.isFile())
+                    continue;
+                // Match against the path relative to root, with forward slashes for
+                // cross-platform pattern stability.
+                const rel = relative(root, abs).split(sep).join("/");
+                if (!regex.test(rel))
+                    continue;
+                matches.push({ abs, mtime: stat.mtimeMs });
+            }
+        }
+        walk(root);
+        matches.sort((a, b) => b.mtime - a.mtime);
+        const paths = matches.map((m) => m.abs);
+        if (paths.length === 0) {
+            return JSON.stringify({
+                ok: true,
+                count: 0,
+                paths: [],
+                note: timedOut ? "Walk timed out after 30s with no matches." : "No matches.",
+            });
+        }
+        const payload = {
+            ok: true,
+            count: paths.length,
+            paths,
+        };
+        if (truncated)
+            payload.truncated = true;
+        if (timedOut)
+            payload.timedOut = true;
+        return JSON.stringify(payload);
+    },
+};
+/**
+ * Compile a shell-style glob to a regex that matches the entire relative
+ * path (anchored at both ends).
+ *
+ * Handled tokens:
+ *   `**\/`  → `(?:.*\/)?` — zero or more path segments (greedy across `/`)
+ *   `**`    → `.*`        — anything including `/`
+ *   `*`     → `[^/]*`     — anything except `/` within one segment
+ *   `?`     → `[^/]`      — single char within one segment
+ *
+ * Other regex metacharacters are escaped so literals like `.` in `foo.ts`
+ * don't accidentally turn into "any char".
+ */
+export function compileGlob(pattern) {
+    let s = "";
+    let i = 0;
+    while (i < pattern.length) {
+        const c = pattern[i];
+        if (c === "*") {
+            // Detect "**" (and the "**/" prefix variant).
+            if (pattern[i + 1] === "*") {
+                if (pattern[i + 2] === "/") {
+                    s += "(?:.*\\/)?";
+                    i += 3;
+                }
+                else {
+                    s += ".*";
+                    i += 2;
+                }
+            }
+            else {
+                s += "[^/]*";
+                i += 1;
+            }
+        }
+        else if (c === "?") {
+            s += "[^/]";
+            i += 1;
+        }
+        else if (REGEX_META.includes(c)) {
+            s += `\\${c}`;
+            i += 1;
+        }
+        else {
+            s += c;
+            i += 1;
+        }
+    }
+    return new RegExp(`^${s}$`);
+}
+const REGEX_META = ".+^$()[]{}|\\";
+//# sourceMappingURL=glob.js.map

package/dist/tools/builtin/glob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.js","sourceRoot":"","sources":["../../../src/tools/builtin/glob.ts"],"names":[],"mappings":"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"}

package/dist/tools/builtin/grep.d.ts

@@ -0,0 +1,3 @@
+import type { ToolHandler } from "../../tools/registry.js";
+export declare const grepTool: ToolHandler;
+//# sourceMappingURL=grep.d.ts.map

package/dist/tools/builtin/grep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grep.d.ts","sourceRoot":"","sources":["../../../src/tools/builtin/grep.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAoDpD,eAAO,MAAM,QAAQ,EAAE,WAiPtB,CAAC"}

package/dist/tools/builtin/grep.js

@@ -0,0 +1,272 @@
+import { spawnSync } from "node:child_process";
+import { isAbsolute } from "node:path";
+import { logger } from "../../platform/logger.js";
+/**
+ * `Grep` builtin — ripgrep wrapper, claude-SDK parity.
+ *
+ * Mirrors the upstream `Grep` tool's name + schema so the model's
+ * pretrained instinct calls our handler with the right arguments
+ * (full regex syntax, `glob` / `type` filters, context flags). We shell
+ * out to `rg` rather than re-implementing the matcher in JS — ripgrep
+ * is ubiquitous on developer machines, dramatically faster on large
+ * trees, and shipping our own regex engine would be a months-long
+ * project for worse performance.
+ *
+ * If `rg` is not on PATH the tool returns a structured error so the
+ * model knows to fall back to bash (or so the host operator can
+ * install ripgrep). We deliberately do NOT vendor or bundle ripgrep —
+ * keeping the SDK dep-free is a load-bearing decision (no native
+ * binaries, no install scripts, no platform-specific tarballs).
+ *
+ * Output modes:
+ *   - `files_with_matches` (default): one absolute path per line.
+ *     Use this when the model wants to know which files contain the
+ *     pattern without paying for the full content payload.
+ *   - `content`: file:line:match (with `-n` line numbers by default).
+ *     Use this when the model needs to read the matched lines + context.
+ *   - `count`: one `file:count` line per file. Use for survey questions
+ *     ("how many places does X appear?").
+ *
+ * Bounds: a `head_limit` parameter (default 250) caps the output line
+ * count so a runaway match doesn't blow out the model's context. Set to
+ * 0 to disable the cap (use sparingly — Claude's response context is
+ * precious).
+ */
+/** Default cap on output lines. The model can override via `head_limit`. */
+const DEFAULT_HEAD_LIMIT = 250;
+/** Wall-clock cap on a single ripgrep invocation. */
+const RG_TIMEOUT_MS = 30_000;
+/** Hard cap on stdout bytes — defensive against pathological matches that
+ *  blow past head_limit because they're all on one line. */
+const RG_MAX_OUTPUT = 1_000_000;
+const VALID_OUTPUT_MODES = new Set([
+    "content",
+    "files_with_matches",
+    "count",
+]);
+export const grepTool = {
+    // Pure read of the filesystem via an external process — multiple Greps
+    // in parallel are fine.
+    parallelSafe: true,
+    schema: {
+        name: "Grep",
+        description: "Search file contents using ripgrep. Returns matches in one of three " +
+            "output modes (files_with_matches, content, count). Supports the same " +
+            "pattern syntax as `rg` (PCRE2-style regex) and the usual filters " +
+            "(`glob` for filename pattern, `type` for ripgrep file-type aliases " +
+            "like `ts` / `py` / `rust`). Context flags `-A` / `-B` / `-C` only " +
+            "apply in `content` mode. Requires ripgrep on PATH.",
+        input_schema: {
+            type: "object",
+            properties: {
+                pattern: {
+                    type: "string",
+                    description: "Regular expression to search for. ripgrep syntax — `.` is any char, " +
+                        "`\\.` is a literal dot, character classes / lookarounds / etc. work.",
+                },
+                path: {
+                    type: "string",
+                    description: "Optional absolute file or directory to search in. Defaults to the " +
+                        "SDK's process cwd. Relative paths are rejected.",
+                },
+                output_mode: {
+                    type: "string",
+                    enum: ["content", "files_with_matches", "count"],
+                    description: "Output shape. Defaults to `files_with_matches`. `content` returns " +
+                        "matching lines (with `file:line:match` prefix); `count` returns " +
+                        "`file:N`; `files_with_matches` returns one path per line.",
+                },
+                glob: {
+                    type: "string",
+                    description: "Filter files by glob pattern (e.g. `*.ts`, `**/*.{js,tsx}`). " +
+                        "Maps to `rg --glob`.",
+                },
+                type: {
+                    type: "string",
+                    description: "Filter by ripgrep's built-in file-type alias (`ts`, `py`, `rust`, " +
+                        "`go`, etc.). More efficient than `glob` for standard languages.",
+                },
+                "-i": {
+                    type: "boolean",
+                    description: "Case-insensitive search (ripgrep `-i`).",
+                },
+                "-n": {
+                    type: "boolean",
+                    description: "Show line numbers in `content` mode. Defaults to true; pass false " +
+                        "to suppress. Ignored in other modes.",
+                },
+                "-A": {
+                    type: "number",
+                    description: "Lines of trailing context per match. `content` mode only.",
+                },
+                "-B": {
+                    type: "number",
+                    description: "Lines of leading context per match. `content` mode only.",
+                },
+                "-C": {
+                    type: "number",
+                    description: "Lines of context (both sides) per match. `content` mode only. " +
+                        "Overrides `-A` / `-B` if both supplied.",
+                },
+                "-o": {
+                    type: "boolean",
+                    description: "Print only the matched portion of each line (ripgrep `-o`). " +
+                        "`content` mode only.",
+                },
+                multiline: {
+                    type: "boolean",
+                    description: "Enable multi-line matching (`-U --multiline-dotall`). `.` will " +
+                        "match newlines and patterns can span lines.",
+                },
+                head_limit: {
+                    type: "number",
+                    description: "Cap output to the first N lines. Defaults to 250. Pass 0 to disable.",
+                },
+                offset: {
+                    type: "number",
+                    description: "Skip the first N output lines before applying head_limit. " +
+                        "Defaults to 0. Use to paginate large result sets.",
+                },
+            },
+            required: ["pattern"],
+        },
+    },
+    async execute(input) {
+        const pattern = typeof input.pattern === "string" ? input.pattern : "";
+        if (!pattern) {
+            return JSON.stringify({ error: "Grep: missing 'pattern' argument" });
+        }
+        const rawPath = typeof input.path === "string" ? input.path : undefined;
+        if (rawPath !== undefined && !isAbsolute(rawPath)) {
+            return JSON.stringify({
+                error: `Grep: 'path' must be absolute, got '${rawPath}'`,
+            });
+        }
+        const target = rawPath ?? process.cwd();
+        const outputMode = VALID_OUTPUT_MODES.has(input.output_mode)
+            ? input.output_mode
+            : "files_with_matches";
+        const args = [];
+        // Mode-specific args.
+        if (outputMode === "files_with_matches") {
+            args.push("-l");
+        }
+        else if (outputMode === "count") {
+            args.push("-c");
+        }
+        else {
+            // content mode — show line numbers unless explicitly disabled.
+            const showLineNumbers = input["-n"] !== false;
+            if (showLineNumbers)
+                args.push("-n");
+            if (input["-o"] === true)
+                args.push("-o");
+            // Context flags only apply in content mode; -C wins over -A/-B if both given.
+            const ctxC = typeof input["-C"] === "number" ? input["-C"] : null;
+            const ctxA = typeof input["-A"] === "number" ? input["-A"] : null;
+            const ctxB = typeof input["-B"] === "number" ? input["-B"] : null;
+            if (ctxC !== null && ctxC > 0) {
+                args.push("-C", String(ctxC));
+            }
+            else {
+                if (ctxA !== null && ctxA > 0)
+                    args.push("-A", String(ctxA));
+                if (ctxB !== null && ctxB > 0)
+                    args.push("-B", String(ctxB));
+            }
+        }
+        if (input["-i"] === true)
+            args.push("-i");
+        if (input.multiline === true)
+            args.push("-U", "--multiline-dotall");
+        if (typeof input.glob === "string" && input.glob)
+            args.push("--glob", input.glob);
+        if (typeof input.type === "string" && input.type)
+            args.push("--type", input.type);
+        // Pattern + target last so the positional args don't get shuffled.
+        args.push("--", pattern, target);
+        const spawnOpts = {
+            encoding: "utf-8",
+            timeout: RG_TIMEOUT_MS,
+            maxBuffer: RG_MAX_OUTPUT,
+        };
+        const result = spawnSync("rg", args, spawnOpts);
+        if (result.error) {
+            const err = result.error;
+            if (err.code === "ENOENT") {
+                return JSON.stringify({
+                    error: "Grep: ripgrep (`rg`) is not on PATH. Install it via Homebrew (`brew install ripgrep`), " +
+                        "your package manager, or https://github.com/BurntSushi/ripgrep, or fall back to " +
+                        "the bash tool with `grep`/`find`.",
+                });
+            }
+            if (err.code === "ETIMEDOUT" || err.code === "ECHILD") {
+                return JSON.stringify({
+                    error: `Grep: timeout after ${RG_TIMEOUT_MS}ms — narrow the search with --glob/--type or pass a more specific path.`,
+                });
+            }
+            return JSON.stringify({
+                error: `Grep: spawn failed: ${err.message}`,
+            });
+        }
+        // ripgrep exits 0 = matches found, 1 = no matches, 2 = error.
+        if (result.status === 2) {
+            return JSON.stringify({
+                error: `Grep: ripgrep exited with status 2: ${truncate(String(result.stderr ?? ""), 1000)}`,
+            });
+        }
+        let stdout = typeof result.stdout === "string" ? result.stdout : "";
+        // Head-limit / offset slicing — applied AFTER ripgrep returns the full
+        // result so we don't lose deterministic ordering by piping through
+        // external `head`.
+        const headLimit = typeof input.head_limit === "number" && Number.isFinite(input.head_limit)
+            ? Math.max(0, Math.floor(input.head_limit))
+            : DEFAULT_HEAD_LIMIT;
+        const offset = typeof input.offset === "number" && Number.isFinite(input.offset)
+            ? Math.max(0, Math.floor(input.offset))
+            : 0;
+        const allLines = stdout.split("\n");
+        // Trailing empty line is artifact of the final \n — drop it for counting.
+        if (allLines.length > 0 && allLines[allLines.length - 1] === "")
+            allLines.pop();
+        let truncated = false;
+        let sliced = allLines;
+        if (offset > 0)
+            sliced = sliced.slice(offset);
+        if (headLimit > 0 && sliced.length > headLimit) {
+            sliced = sliced.slice(0, headLimit);
+            truncated = true;
+        }
+        if (sliced.length === 0) {
+            if (result.status === 1) {
+                return "(no matches)";
+            }
+            if (allLines.length > 0 && offset >= allLines.length) {
+                return JSON.stringify({
+                    ok: true,
+                    count: 0,
+                    totalLines: allLines.length,
+                    note: `offset ${offset} is past the end of the result set (${allLines.length} lines)`,
+                });
+            }
+            return "(no matches)";
+        }
+        if (!truncated && offset === 0) {
+            // Plain text — model parses naturally.
+            return sliced.join("\n");
+        }
+        // Annotated payload when we sliced. JSON shape so the model sees the
+        // truncation context explicitly.
+        const note = [];
+        if (offset > 0)
+            note.push(`offset=${offset}`);
+        if (truncated)
+            note.push(`truncated to ${headLimit} of ${allLines.length - offset} matching lines`);
+        logger.debug({ offset, headLimit, total: allLines.length, returned: sliced.length }, "Grep: applied head-limit/offset slicing");
+        return [`# ${note.join(", ")}`, ...sliced].join("\n");
+    },
+};
+function truncate(s, n) {
+    return s.length > n ? `${s.slice(0, n)}…` : s;
+}
+//# sourceMappingURL=grep.js.map

package/dist/tools/builtin/grep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grep.js","sourceRoot":"","sources":["../../../src/tools/builtin/grep.ts"],"names":[],"mappings":"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"}

package/dist/tools/builtin/skill_write.d.ts

@@ -0,0 +1,53 @@
+import type { ToolHandler } from "../../tools/registry.js";
+/**
+ * `skill_write` builtin — agent-autonomous skill authoring.
+ *
+ * Mirrors the clawgram skill-creation convention (`meta/skills/skill-creation-
+ * guide.md` in the host repo):
+ *
+ *   - File layout is `<skillsDir>/<name>/skill.md` (folder per skill, lowercase
+ *     filename). Folder layout is enforced — progressive-disclosure assets
+ *     (`scripts/`, `templates/`, `references/`) sit alongside the manifest
+ *     and the agent ships them in the same call via the `files` map.
+ *   - Content is plain markdown with a `# Title` heading and a
+ *     `> **Description**: <trigger keywords>` blockquote near the top. No
+ *     YAML frontmatter is required (the v0.1.5 loader extracts the
+ *     description from the blockquote when frontmatter is absent).
+ *   - Canonical identifier (`name`) is the folder, kebab-case English.
+ *
+ * The model produces the full markdown body and passes it as `content`,
+ * along with an optional `files` map for adjacent assets (scripts,
+ * templates, references). The tool enforces:
+ *
+ *   - kebab-case name validation
+ *   - non-empty manifest content
+ *   - relative-path safety for `files` (no leading `/`, no `..` escapes)
+ *   - no collisions with the manifest path (`skill.md` is reserved)
+ *
+ * All writes happen under `<skillsDir>/<name>/` so the agent can never
+ * escape its keyed profile. Writes are best-effort transactional: the tool
+ * validates EVERY `files` entry before touching disk, then writes manifest
+ * + files in order. A partial-failure midway (disk full, permission
+ * change) leaves whatever was written so far in place — the caller can
+ * inspect `path` / `files` in the error response and re-try with
+ * `overwrite: true`.
+ *
+ * After a successful write the in-memory skills cache is invalidated so
+ * the next turn's catalog reload picks up the new skill immediately. The
+ * skill is NOT live in the current turn's catalog — adding it mid-turn
+ * would change the system-prompt index hash and bust the prompt cache,
+ * costing more than it gains.
+ *
+ * Factory captures the resolved skillsDir for this session so the agent
+ * always lands writes inside its own keyed profile (`.skills/<key>/`) and
+ * never escapes to another profile's directory.
+ */
+export interface SkillWriteToolOptions {
+    /** Absolute path of the resolved skills directory for this session. New
+     *  skills land at `<skillsDir>/<name>/skill.md`. Comes from
+     *  `resolveSkillsDir(opts)` in the provider, so it already reflects the
+     *  `(cwd, skillKey)` routing. */
+    skillsDir: string;
+}
+export declare function createSkillWriteTool(opts: SkillWriteToolOptions): ToolHandler;
+//# sourceMappingURL=skill_write.d.ts.map

package/dist/tools/builtin/skill_write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill_write.d.ts","sourceRoot":"","sources":["../../../src/tools/builtin/skill_write.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,MAAM,WAAW,qBAAqB;IACpC;;;qCAGiC;IACjC,SAAS,EAAE,MAAM,CAAC;CACnB;AAuBD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,qBAAqB,GAAG,WAAW,CA8N7E"}