@chengchenccc/oh-my-agent 0.1.1-rc.1

package/dist/core/tools/web-ports-std.js

@@ -0,0 +1,145 @@
+import { assertSafeUrl, FETCH_TIMEOUT_MS, MAX_REDIRECTS, UrlGuardError } from "./url-guard.js";
+/** Max bytes read from a fetched page (fetch port is heavier than the
+ *  url-guard default: real pages, not snippets). */
+const FETCH_CAP_BYTES = 512_000;
+function decodeEntities(value) {
+    return value
+        .replace(/<[^>]*>/g, " ")
+        .replace(/&#x([0-9a-f]+);/gi, (_, code) => String.fromCharCode(Number.parseInt(code, 16)))
+        .replace(/&#(\d+);/g, (_, code) => String.fromCharCode(Number(code)))
+        .replace(/&nbsp;/gi, " ")
+        .replace(/&amp;/gi, "&")
+        .replace(/&lt;/gi, "<")
+        .replace(/&gt;/gi, ">")
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;|&apos;/gi, "'")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** Naive HTML → readable text: drop script/style/head, strip tags. */
+function htmlToText(html) {
+    return decodeEntities(html
+        .replace(/<(script|style|noscript|svg|head)\b[\s\S]*?<\/\1>/gi, " ")
+        .replace(/<\/(p|div|li|h[1-6]|tr|section|article)>/gi, "\n"));
+}
+/** Std fetch port: global fetch, manual redirect walk (each hop re-validated
+ *  against the url guard), timeout + size caps, HTML→text. */
+export function createStdWebFetchPort() {
+    return {
+        async fetch(url, signal) {
+            let current = assertSafeUrl(url).toString();
+            for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+                const resp = await fetch(current, {
+                    redirect: "manual",
+                    signal: signal ?? AbortSignal.timeout(FETCH_TIMEOUT_MS),
+                    headers: { "user-agent": "oma/0.1 (+web_fetch)" },
+                });
+                if ([301, 302, 303, 307, 308].includes(resp.status)) {
+                    const location = resp.headers.get("location");
+                    if (!location)
+                        throw new Error(`redirect without location from ${current}`);
+                    current = assertSafeUrl(new URL(location, current).toString()).toString();
+                    continue;
+                }
+                if (!resp.ok)
+                    throw new Error(`HTTP ${resp.status} from ${current}`);
+                const reader = resp.body?.getReader();
+                if (!reader) {
+                    const text = await resp.text();
+                    return { text: htmlToText(text).slice(0, FETCH_CAP_BYTES), title: titleOf(text) };
+                }
+                const chunks = [];
+                let bytes = 0;
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    bytes += value.byteLength;
+                    chunks.push(value);
+                    if (bytes > FETCH_CAP_BYTES)
+                        break;
+                }
+                const html = new TextDecoder().decode(concat(chunks));
+                return { text: htmlToText(html), title: titleOf(html) };
+            }
+            throw new UrlGuardError(`too many redirects (>${MAX_REDIRECTS})`);
+        },
+    };
+}
+function titleOf(html) {
+    const m = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html);
+    return m?.[1] !== undefined ? decodeEntities(m[1]).slice(0, 200) : undefined;
+}
+function concat(chunks) {
+    const total = chunks.reduce((n, c) => n + c.byteLength, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const c of chunks) {
+        out.set(c, offset);
+        offset += c.byteLength;
+    }
+    return out;
+}
+/** DuckDuckGo no-JS HTML frontend as a zero-config search port (same source
+ *  omp uses). DDG routes outbound links through /l/?uddg=<encoded> — those
+ *  are unwrapped back to the target URL. */
+const DDG_HTML_URL = "https://html.duckduckgo.com/html/";
+function unwrapDdgHref(href) {
+    const wrap = /[?&]uddg=([^&]+)/.exec(href.replace(/&amp;/gi, "&"));
+    if (wrap?.[1] !== undefined) {
+        try {
+            return decodeURIComponent(wrap[1]);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (href.startsWith("//"))
+        return `https:${href}`;
+    if (href.startsWith("http://") || href.startsWith("https://"))
+        return href;
+    return undefined;
+}
+function parseDdgResults(html) {
+    const results = [];
+    const blockRe = /<div\b[^>]*\bclass="[^"]*\bresult\b[^"]*"[^>]*>([\s\S]*?)(?=<div\b[^>]*\bclass="[^"]*\bresult\b|<div\b[^>]*\bclass="[^"]*\bnav-link\b|$)/g;
+    const titleRe = /<a\b[^>]*\bclass="[^"]*\bresult__a\b[^"]*"[^>]*\bhref="([^"]+)"[^>]*>([\s\S]*?)<\/a>/;
+    const snippetRe = /<(?:a|div|span)\b[^>]*\bclass="[^"]*\bresult__snippet\b[^"]*"[^>]*>([\s\S]*?)<\/(?:a|div|span)>/;
+    for (const match of html.matchAll(blockRe)) {
+        const block = match[1] ?? "";
+        const title = titleRe.exec(block);
+        if (!title)
+            continue;
+        const url = unwrapDdgHref(title[1] ?? "");
+        const titleText = decodeEntities(title[2] ?? "");
+        if (!url || !titleText)
+            continue;
+        const snippet = snippetRe.exec(block);
+        results.push({
+            title: titleText,
+            url,
+            snippet: snippet ? decodeEntities(snippet[1] ?? "") : "",
+        });
+    }
+    return results;
+}
+export function createDdgWebSearchPort() {
+    return {
+        async search(query, limit = 5, signal) {
+            const resp = await fetch(DDG_HTML_URL, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/x-www-form-urlencoded",
+                    "user-agent": "oma/0.1 (+web_search)",
+                },
+                body: new URLSearchParams({ q: query }).toString(),
+                signal: signal ?? AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            });
+            const html = await resp.text();
+            if (html.includes("anomaly-modal") || html.includes("anomaly.js")) {
+                throw new Error("duckduckgo bot challenge — retry or use a different query");
+            }
+            return parseDdgResults(html).slice(0, limit);
+        },
+    };
+}

package/dist/core/tools/web-ports.d.ts

@@ -0,0 +1,56 @@
+/** Port for web search. Implementations inject search providers. */
+export interface WebSearchPort {
+    search(query: string, limit?: number, signal?: AbortSignal): Promise<ReadonlyArray<{
+        title: string;
+        url: string;
+        snippet: string;
+    }>>;
+}
+/** Port for web fetch. Implementations inject HTTP fetch behavior and own
+ *  redirect validation, response limits, and timeouts. */
+export interface WebFetchPort {
+    fetch(url: string, signal?: AbortSignal): Promise<{
+        text: string;
+        title?: string;
+    }>;
+}
+/** Create a web_search tool backed by the given port. */
+export declare function createWebSearchTool(port: WebSearchPort): {
+    name: string;
+    description: string;
+    inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly query: {
+                readonly type: "string";
+                readonly description: "Search query";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "Max results";
+                readonly default: 5;
+            };
+        };
+        readonly required: readonly ["query"];
+    };
+    execute(args: Readonly<Record<string, unknown>>, signal?: AbortSignal): Promise<Readonly<Record<string, unknown>>>;
+};
+/** Create a web_fetch tool backed by the given port. URL safety (protocol,
+ *  private-host) is enforced here; redirects/limits/timeouts belong to the
+ *  injected port implementation. */
+export declare function createWebFetchTool(port: WebFetchPort): {
+    name: string;
+    description: string;
+    inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly url: {
+                readonly type: "string";
+                readonly description: "URL to fetch";
+            };
+        };
+        readonly required: readonly ["url"];
+    };
+    execute(args: Readonly<Record<string, unknown>>, signal?: AbortSignal): Promise<Readonly<Record<string, unknown>>>;
+};
+//# sourceMappingURL=web-ports.d.ts.map

package/dist/core/tools/web-ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-ports.d.ts","sourceRoot":"","sources":["../../../src/core/tools/web-ports.ts"],"names":[],"mappings":"AAEA,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,MAAM,CACJ,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;CAC5E;AAED;0DAC0D;AAC1D,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrF;AAED,yDAAyD;AACzD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa;;;;;;;;;;;;;;;;;;kBAY/B,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,WAAW,WAAW;EAgB9E;AAED;;oCAEoC;AACpC,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY;;;;;;;;;;;;;kBAS7B,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,WAAW,WAAW;EAsB9E"}

package/dist/core/tools/web-ports.js

@@ -0,0 +1,62 @@
+import { assertSafeUrl } from "./url-guard.js";
+/** Create a web_search tool backed by the given port. */
+export function createWebSearchTool(port) {
+    return {
+        name: "web_search",
+        description: "Search the web for information.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search query" },
+                limit: { type: "number", description: "Max results", default: 5 },
+            },
+            required: ["query"],
+        },
+        async execute(args, signal) {
+            try {
+                const results = await port.search(args.query, args.limit ?? 5, signal);
+                return { results };
+            }
+            catch (err) {
+                return {
+                    error: `web_search failed: ${err instanceof Error ? err.message : String(err)}`,
+                    isError: true,
+                };
+            }
+        },
+    };
+}
+/** Create a web_fetch tool backed by the given port. URL safety (protocol,
+ *  private-host) is enforced here; redirects/limits/timeouts belong to the
+ *  injected port implementation. */
+export function createWebFetchTool(port) {
+    return {
+        name: "web_fetch",
+        description: "Fetch and read the contents of a web page.",
+        inputSchema: {
+            type: "object",
+            properties: { url: { type: "string", description: "URL to fetch" } },
+            required: ["url"],
+        },
+        async execute(args, signal) {
+            const rawUrl = args.url;
+            try {
+                assertSafeUrl(rawUrl);
+                const result = await port.fetch(rawUrl, signal);
+                return { text: result.text, title: result.title };
+            }
+            catch (err) {
+                if (err instanceof Error && err.name === "UrlGuardError") {
+                    return {
+                        error: err.message,
+                        isError: true,
+                    };
+                }
+                return {
+                    error: `web_fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/dist/core/tools/workspace-sandbox.d.ts

@@ -0,0 +1,20 @@
+/** Workspace sandbox enforces that all file access stays within an allowed root. */
+export declare class WorkspaceSandbox {
+    readonly root: string;
+    constructor(root: string);
+    /** Validate an existing path is within the sandbox. */
+    validate(target: string): string;
+    /** Validate a new path for creation. Walks up to the nearest existing
+     *  parent and checks its realpath is within root. This catches cases
+     *  where an intermediate directory is a symlink pointing outside. */
+    validateNew(target: string): string;
+    /** Check a command's cwd is within the sandbox. */
+    validateCwd(cwd: string): string;
+    private resolve;
+}
+export declare class WorkspaceEscapeError extends Error {
+    readonly path: string;
+    readonly root: string;
+    constructor(path: string, root: string);
+}
+//# sourceMappingURL=workspace-sandbox.d.ts.map

package/dist/core/tools/workspace-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-sandbox.d.ts","sourceRoot":"","sources":["../../../src/core/tools/workspace-sandbox.ts"],"names":[],"mappings":"AAGA,oFAAoF;AACpF,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM;IAIxB,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAehC;;yEAEqE;IACrE,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAuBnC,mDAAmD;IACnD,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAShC,OAAO,CAAC,OAAO;CAKhB;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAMvC"}

package/dist/core/tools/workspace-sandbox.js

@@ -0,0 +1,84 @@
+import { existsSync, realpathSync } from "node:fs";
+import { isAbsolute, normalize, resolve } from "node:path";
+/** Workspace sandbox enforces that all file access stays within an allowed root. */
+export class WorkspaceSandbox {
+    root;
+    constructor(root) {
+        this.root = realpathSync(root);
+    }
+    /** Validate an existing path is within the sandbox. */
+    validate(target) {
+        const resolved = this.resolve(target);
+        if (!resolved.startsWith(`${this.root}/`) && resolved !== this.root) {
+            throw new WorkspaceEscapeError(target, this.root);
+        }
+        // Check realpath for existing files to catch symlink escapes
+        if (existsSync(resolved)) {
+            const real = realpathSafe(resolved);
+            if (real && !real.startsWith(`${this.root}/`) && real !== this.root) {
+                throw new WorkspaceEscapeError(target, this.root);
+            }
+        }
+        return resolved;
+    }
+    /** Validate a new path for creation. Walks up to the nearest existing
+     *  parent and checks its realpath is within root. This catches cases
+     *  where an intermediate directory is a symlink pointing outside. */
+    validateNew(target) {
+        const resolved = this.resolve(target);
+        if (!resolved.startsWith(`${this.root}/`) && resolved !== this.root) {
+            throw new WorkspaceEscapeError(target, this.root);
+        }
+        // Walk up to find nearest existing parent
+        let checkPath = resolved;
+        const tried = [];
+        while (checkPath !== this.root && checkPath !== "/") {
+            if (existsSync(checkPath))
+                break;
+            tried.push(checkPath);
+            const idx = checkPath.lastIndexOf("/");
+            if (idx <= 0)
+                break;
+            checkPath = checkPath.slice(0, idx);
+        }
+        // Check realpath of the nearest existing ancestor
+        const real = realpathSafe(checkPath);
+        if (!real || (!real.startsWith(`${this.root}/`) && real !== this.root)) {
+            throw new WorkspaceEscapeError(target, this.root);
+        }
+        return resolved;
+    }
+    /** Check a command's cwd is within the sandbox. */
+    validateCwd(cwd) {
+        const resolved = this.resolve(cwd);
+        const real = realpathSafe(resolved);
+        if (!real || (!real.startsWith(`${this.root}/`) && real !== this.root)) {
+            throw new WorkspaceEscapeError(cwd, this.root);
+        }
+        return real;
+    }
+    resolve(target) {
+        const normalized = normalize(target);
+        if (isAbsolute(normalized))
+            return resolve(normalized);
+        return resolve(this.root, normalized);
+    }
+}
+export class WorkspaceEscapeError extends Error {
+    path;
+    root;
+    constructor(path, root) {
+        super(`Path "${path}" escapes workspace root "${root}"`);
+        this.name = "WorkspaceEscapeError";
+        this.path = path;
+        this.root = root;
+    }
+}
+function realpathSafe(p) {
+    try {
+        return existsSync(p) ? realpathSync(p) : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/workflow/subagent-registry.d.ts

@@ -0,0 +1,40 @@
+/** 3.4 subagent role registry.
+ *
+ *  A named subagent is either a builtin (`explore` / `worker`) or a
+ *  workspace definition at `<workspaceRoot>/.oma/agents/<name>.md`:
+ *
+ *    ---
+ *    name: reviewer
+ *    description: Reviews diffs for correctness
+ *    tools: [read, grep]
+ *    model: anthropic/claude-sonnet
+ *    ---
+ *    <body becomes the system prompt>
+ *
+ *  Frontmatter is parsed by hand (line regexes, no YAML dependency) — same
+ *  precedent as the oma tools skills parseFrontmatter.
+ */
+export interface SubagentRegistryEntry {
+    readonly name: string;
+    readonly description: string;
+    /** The role body — the executor appends the generic subagent tail. */
+    readonly systemPrompt: string;
+    /** Tool name allowlist; undefined = every executor file tool. */
+    readonly tools?: readonly string[];
+    /** Optional model override (must resolve in the runtime catalog). */
+    readonly modelId?: string;
+}
+/** Validate a subagent/script name: a plain label, never a path segment.
+ *  Model-supplied names must not escape `.oma/agents` / `.oma/workflow`. */
+export declare function isValidWorkflowName(name: string): boolean;
+/** Parse `.oma/agents/*.md` — YAML-subset frontmatter with the four fields
+ *  name / description / tools / model; unknown keys are ignored. */
+export declare function parseAgentDefinition(md: string): SubagentRegistryEntry | null;
+export declare function builtinAgentNames(): string[];
+/** Resolve a role: builtin first, then the workspace definition. Returns
+ *  null when unknown or the name is unsafe. `allowWorkspace` is false for
+ *  read_only workspaces (no `.oma/agents` files). */
+export declare function resolveAgent(name: string, readAgentDefinition: (name: string) => Promise<string | null>, opts?: {
+    allowWorkspace?: boolean;
+}): Promise<SubagentRegistryEntry | null>;
+//# sourceMappingURL=subagent-registry.d.ts.map

package/dist/core/workflow/subagent-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-registry.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/subagent-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;4EAC4E;AAC5E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AA0DD;oEACoE;AACpE,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CAmB7E;AAED,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C;AAED;;qDAEqD;AACrD,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,mBAAmB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,EAC7D,IAAI,GAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAWvC"}

package/dist/core/workflow/subagent-registry.js

@@ -0,0 +1,118 @@
+/** 3.4 subagent role registry.
+ *
+ *  A named subagent is either a builtin (`explore` / `worker`) or a
+ *  workspace definition at `<workspaceRoot>/.oma/agents/<name>.md`:
+ *
+ *    ---
+ *    name: reviewer
+ *    description: Reviews diffs for correctness
+ *    tools: [read, grep]
+ *    model: anthropic/claude-sonnet
+ *    ---
+ *    <body becomes the system prompt>
+ *
+ *  Frontmatter is parsed by hand (line regexes, no YAML dependency) — same
+ *  precedent as the oma tools skills parseFrontmatter.
+ */
+/** Validate a subagent/script name: a plain label, never a path segment.
+ *  Model-supplied names must not escape `.oma/agents` / `.oma/workflow`. */
+export function isValidWorkflowName(name) {
+    return /^[a-z0-9-]{1,64}$/i.test(name);
+}
+/** Builtin roles, usable with no workspace files — the claude Task-family
+ *  trio (explore / plan / task), with prompt structure following oh-my-pi's
+ *  builtin agent definitions (scout/task): a terse role line plus
+ *  <directives>/<critical> sections. `explore` and `plan` are strictly
+ *  read-only; `task` gets the full executor tool set (tools undefined). */
+const BUILTIN_AGENTS = {
+    explore: {
+        name: "explore",
+        description: "MUST be used for exploratory codebase research and broad pattern searches; read-only",
+        systemPrompt: `You are a read-only exploration subagent: investigate the workspace and return structured findings the caller can act on without re-reading everything.
+
+<directives>
+- You MUST use grep/glob for broad pattern searches as much as possible; then read only the needed ranges. NEVER read full files unless they are tiny.
+- If a search returns nothing, try at least one alternate pattern before concluding the target is absent.
+- Note the types/interfaces/key functions you touch and how files connect.
+</directives>
+
+<critical>
+You MUST operate as read-only. You NEVER write, edit, or modify files, nor execute state-changing commands. You MUST keep going until the investigation is complete.
+</critical>`,
+        tools: ["read", "grep", "glob", "tree", "read_image"],
+    },
+    plan: {
+        name: "plan",
+        description: "MUST be used for read-only implementation planning; explore the codebase and produce an execution plan",
+        systemPrompt: `You are a planning subagent: explore the codebase read-only and produce a concrete implementation plan the caller can execute.
+
+<directives>
+- You MUST use read/grep/glob/tree/read_image to understand the relevant code before proposing changes.
+- Identify the files to touch, the order of changes, and any risks/dependencies. Prefer specific paths over vague areas.
+- Keep the plan actionable: steps a worker agent can follow without re-investigating.
+</directives>
+
+<critical>
+You MUST operate as read-only. You NEVER write, edit, or modify files, nor execute state-changing commands. You MUST keep going until the plan is complete.
+</critical>`,
+        tools: ["read", "grep", "glob", "tree", "read_image"],
+    },
+    task: {
+        name: "task",
+        description: "General-purpose task worker with the full file tool set",
+        systemPrompt: `You are a general-purpose task subagent: a delegated task executor with full file tools.
+
+<directives>
+- MUST hyperfocus the assigned task; NEVER deviate.
+- MUST finish only the assigned work and return the minimum useful result; do not repeat filesystem writes.
+- MUST be concise; no filler, no repetition, no tool transcripts. Your result is notes for the caller.
+- Prefer narrow lookups (grep/glob), then read only needed ranges.
+- Prefer editing existing files over creating new ones; NEVER create documentation files (*.md) unless the task explicitly requests one.
+- Persist durable results as files and report what you changed.
+</directives>`,
+    },
+};
+/** Parse `.oma/agents/*.md` — YAML-subset frontmatter with the four fields
+ *  name / description / tools / model; unknown keys are ignored. */
+export function parseAgentDefinition(md) {
+    const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(md);
+    const frontmatter = match?.[1] ?? "";
+    const body = (match?.[2] ?? md).trim();
+    const field = (key) => new RegExp(`^${key}:\\s*(.+)$`, "m").exec(frontmatter)?.[1]?.trim();
+    const name = field("name");
+    if (!name)
+        return null; // a definition without a name is not loadable
+    const tools = field("tools")
+        ?.replace(/[[\]'"\s]/g, "")
+        .split(",")
+        .filter(Boolean);
+    return {
+        name,
+        description: field("description") ?? "",
+        systemPrompt: body,
+        ...(tools && tools.length > 0 ? { tools } : {}),
+        ...(field("model") ? { modelId: field("model") } : {}),
+    };
+}
+export function builtinAgentNames() {
+    return Object.keys(BUILTIN_AGENTS);
+}
+/** Resolve a role: builtin first, then the workspace definition. Returns
+ *  null when unknown or the name is unsafe. `allowWorkspace` is false for
+ *  read_only workspaces (no `.oma/agents` files). */
+export async function resolveAgent(name, readAgentDefinition, opts = {}) {
+    const builtin = BUILTIN_AGENTS[name];
+    if (builtin)
+        return builtin;
+    if (!isValidWorkflowName(name))
+        return null;
+    if (opts.allowWorkspace === false)
+        return null;
+    const md = await readAgentDefinition(name);
+    if (md === null)
+        return null;
+    const parsed = parseAgentDefinition(md);
+    // The file name is the identity; a mismatched frontmatter name is a
+    // hygiene hint, not an authorization boundary.
+    return parsed ? { ...parsed, name: parsed.name || name } : null;
+}

package/dist/core/workflow/workflow-evaluator.d.ts

@@ -0,0 +1,23 @@
+export interface WorkflowPrimitives {
+    readonly agent: (prompt: string, opts?: {
+        schema?: Readonly<Record<string, unknown>>;
+        label?: string;
+    }) => Promise<unknown>;
+    readonly pipeline: (items: readonly unknown[], fn: (item: unknown) => Promise<unknown>, opts?: {
+        concurrency?: number;
+    }) => Promise<readonly unknown[]>;
+}
+export interface EvaluateResult {
+    readonly value: unknown;
+}
+/** Sandboxed script evaluation: ONLY agent/pipeline/args are injected.
+ *  require/process/fs/fetch do not exist inside the script. The vm timeout
+ *  covers synchronous infinite loops; the caller races the returned promise
+ *  against the script budget for async stalls. */
+export declare function evaluateWorkflowScript(input: {
+    readonly script: string;
+    readonly args?: unknown;
+    readonly primitives: WorkflowPrimitives;
+    readonly timeoutMs?: number;
+}): Promise<EvaluateResult>;
+//# sourceMappingURL=workflow-evaluator.d.ts.map

package/dist/core/workflow/workflow-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-evaluator.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/workflow-evaluator.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,CACd,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAClE,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,CACjB,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,EACvC,IAAI,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,KAC5B,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;kDAGkD;AAClD,wBAAsB,sBAAsB,CAAC,KAAK,EAAE;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,GAAG,OAAO,CAAC,cAAc,CAAC,CAkB1B"}

package/dist/core/workflow/workflow-evaluator.js

@@ -0,0 +1,21 @@
+import vm from "node:vm";
+/** Sandboxed script evaluation: ONLY agent/pipeline/args are injected.
+ *  require/process/fs/fetch do not exist inside the script. The vm timeout
+ *  covers synchronous infinite loops; the caller races the returned promise
+ *  against the script budget for async stalls. */
+export async function evaluateWorkflowScript(input) {
+    const timeoutMs = input.timeoutMs ?? 60_000;
+    const { agent, pipeline } = input.primitives;
+    // codeGeneration off kills the constructor.constructor escape: no dynamic
+    // code can be minted from the sandbox (the model's bash tool is already
+    // workspace-scoped; this closes the vm's host-Function bridge).
+    const context = vm.createContext({ agent, pipeline, args: input.args }, { name: "workflow-script", codeGeneration: { strings: false, wasm: false } });
+    const wrapped = `(async () => { ${input.script} })()`;
+    const promise = vm.runInContext(wrapped, context, { timeout: timeoutMs });
+    const timer = new Promise((_, reject) => {
+        const id = setTimeout(() => reject(new Error("workflow script timed out")), timeoutMs);
+        void promise.finally(() => clearTimeout(id)).catch(() => { });
+    });
+    const value = await Promise.race([promise, timer]);
+    return { value };
+}