@tangle-network/browser-agent-driver 0.24.0 → 0.24.2

package/dist/skills/domain-loader.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Domain-skill loader — reads `skills/domain/<host>/SKILL.md` files from
+ * the bad repo and exposes them as a `BadExtension`-compatible bundle so
+ * the existing `setExtensionRules` path at brain/index.ts:899 picks up the
+ * per-domain rules without a second injection site.
+ *
+ * Inspired by browser-use/browser-harness's `domain-skills/` layout.
+ * The differences that matter:
+ *
+ *   1. Every skill carries YAML frontmatter with `host` + optional
+ *      `aliases` so one file covers www.amazon.com + smile.amazon.com.
+ *   2. The body is plain markdown — no code, no enforcement. It lands
+ *      verbatim in the system prompt's USER RULES (domain match) section
+ *      that already exists at brain/index.ts:865-870.
+ *   3. Skills under `skills/domain/experimental/<host>/` are loaded into
+ *      the same registry but tagged so the promotion script can demote
+ *      those whose bench cases don't produce a measurable win.
+ *
+ * No YAML parser dep — we handle the tiny subset we support (flat
+ * key/value + single-line array aliases) with regex. If a skill needs
+ * more expressive metadata, grow the parser with a failing test first.
+ */
+import type { BadExtension } from '../extensions/types.js';
+/** Parsed frontmatter + body split, before we turn it into rules. */
+export interface ParsedDomainSkill {
+    /** Primary hostname the skill applies to (e.g. "amazon.com") */
+    host: string;
+    /** Extra hosts that share the same rules (e.g. ["smile.amazon.com"]) */
+    aliases: string[];
+    /** Optional human-readable label */
+    title?: string;
+    /** Markdown body verbatim (no processing — goes straight into the prompt) */
+    body: string;
+    /** Absolute path to the source file, for logging and promotion flows */
+    sourcePath: string;
+    /** Whether this skill lives under experimental/ */
+    experimental: boolean;
+}
+/** Cap on the body size we'll inject, to keep domain rules from blowing up
+ * the system prompt. Bodies longer than this are truncated with a marker
+ * and the loader warns. 4 KB is ~1000 tokens — comfortable headroom even
+ * across multiple domain matches. */
+export declare const MAX_DOMAIN_BODY_BYTES = 4096;
+/**
+ * Parse a single SKILL.md file. The caller has already read the raw text.
+ * Throws on missing `host` — that's not a recoverable schema hole, we
+ * want the loader to surface it.
+ */
+export declare function parseDomainSkill(raw: string, sourcePath: string, experimental?: boolean): ParsedDomainSkill;
+export interface LoadDomainSkillsOptions {
+    /** Root directory containing the domain skill tree. Defaults to the
+     * `skills/domain` dir shipped with the bad package. */
+    rootDir?: string;
+    /** Logger for load errors. Defaults to a stderr warning. */
+    onError?: (sourcePath: string, err: unknown) => void;
+}
+export interface LoadDomainSkillsResult {
+    skills: ParsedDomainSkill[];
+    /** Files that failed to parse. Never throws — a broken file should never
+     * bring down the run, but the operator needs to see which file it was. */
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+}
+/** Locate the packaged `skills/domain` directory. Works both when running
+ * from source (tsx/test) and from the built dist/ layout. */
+export declare function defaultDomainSkillsRoot(): string;
+/** Walk the domain tree and return parsed skills. Missing dir ⇒ empty list,
+ * not an error: shipping without any seeded skills is a valid state. */
+export declare function loadDomainSkills(options?: LoadDomainSkillsOptions): Promise<LoadDomainSkillsResult>;
+/** Collapse a list of parsed skills into a BadExtension so they flow through
+ * the existing resolveExtensions → setExtensionRules path. Aliases are only
+ * emitted as additional keys when they can't already be reached by the
+ * matcher's substring comparison — otherwise the same body would be
+ * concatenated onto itself at match time. */
+export declare function buildDomainSkillExtension(skills: ParsedDomainSkill[]): BadExtension;
+//# sourceMappingURL=domain-loader.d.ts.map

package/dist/skills/domain-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-loader.d.ts","sourceRoot":"","sources":["../../src/skills/domain-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAe,MAAM,wBAAwB,CAAA;AAEvE,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAA;IAClB,mDAAmD;IACnD,YAAY,EAAE,OAAO,CAAA;CACtB;AAED;;;qCAGqC;AACrC,eAAO,MAAM,qBAAqB,OAAO,CAAA;AAEzC;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,UAAQ,GAAG,iBAAiB,CAyBzG;AA8CD,MAAM,WAAW,uBAAuB;IACtC;2DACuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;CACrD;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,iBAAiB,EAAE,CAAA;IAC3B;8EAC0E;IAC1E,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC/C;AAED;6DAC6D;AAC7D,wBAAgB,uBAAuB,IAAI,MAAM,CAMhD;AAED;wEACwE;AACxE,wBAAsB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAuB7G;AAuBD;;;;6CAI6C;AAC7C,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,EAAE,GAAG,YAAY,CAenF"}

package/dist/skills/domain-loader.js

@@ -0,0 +1,201 @@
+/**
+ * Domain-skill loader — reads `skills/domain/<host>/SKILL.md` files from
+ * the bad repo and exposes them as a `BadExtension`-compatible bundle so
+ * the existing `setExtensionRules` path at brain/index.ts:899 picks up the
+ * per-domain rules without a second injection site.
+ *
+ * Inspired by browser-use/browser-harness's `domain-skills/` layout.
+ * The differences that matter:
+ *
+ *   1. Every skill carries YAML frontmatter with `host` + optional
+ *      `aliases` so one file covers www.amazon.com + smile.amazon.com.
+ *   2. The body is plain markdown — no code, no enforcement. It lands
+ *      verbatim in the system prompt's USER RULES (domain match) section
+ *      that already exists at brain/index.ts:865-870.
+ *   3. Skills under `skills/domain/experimental/<host>/` are loaded into
+ *      the same registry but tagged so the promotion script can demote
+ *      those whose bench cases don't produce a measurable win.
+ *
+ * No YAML parser dep — we handle the tiny subset we support (flat
+ * key/value + single-line array aliases) with regex. If a skill needs
+ * more expressive metadata, grow the parser with a failing test first.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Cap on the body size we'll inject, to keep domain rules from blowing up
+ * the system prompt. Bodies longer than this are truncated with a marker
+ * and the loader warns. 4 KB is ~1000 tokens — comfortable headroom even
+ * across multiple domain matches. */
+export const MAX_DOMAIN_BODY_BYTES = 4096;
+/**
+ * Parse a single SKILL.md file. The caller has already read the raw text.
+ * Throws on missing `host` — that's not a recoverable schema hole, we
+ * want the loader to surface it.
+ */
+export function parseDomainSkill(raw, sourcePath, experimental = false) {
+    const { frontmatter, body } = splitFrontmatter(raw);
+    const meta = parseFrontmatterBlock(frontmatter);
+    const host = typeof meta.host === 'string' ? meta.host.trim() : '';
+    if (!host) {
+        throw new Error(`${sourcePath}: frontmatter missing required "host" field`);
+    }
+    const aliases = Array.isArray(meta.aliases)
+        ? meta.aliases.map(String).map((s) => s.trim()).filter(Boolean)
+        : [];
+    const title = typeof meta.title === 'string' ? meta.title.trim() : undefined;
+    let trimmedBody = body.trim();
+    if (Buffer.byteLength(trimmedBody, 'utf-8') > MAX_DOMAIN_BODY_BYTES) {
+        trimmedBody = trimmedBody.slice(0, MAX_DOMAIN_BODY_BYTES).trimEnd() +
+            '\n\n[…truncated — domain skill body exceeded MAX_DOMAIN_BODY_BYTES]';
+    }
+    return {
+        host,
+        aliases,
+        title,
+        body: trimmedBody,
+        sourcePath,
+        experimental,
+    };
+}
+/** Split `---\nfrontmatter\n---\nbody` into its two parts. Files without
+ * frontmatter (missing opening `---\n`) are treated as body-only. The
+ * strict `---\n` match avoids misinterpreting a body that happens to
+ * start with a markdown horizontal rule. */
+function splitFrontmatter(raw) {
+    if (!raw.startsWith('---\n') && !raw.startsWith('---\r\n'))
+        return { frontmatter: '', body: raw };
+    const afterOpenDelimiter = raw.startsWith('---\r\n') ? 5 : 4;
+    // Closing delimiter must be on its own line (\n---\n or \n---\r\n or EOF).
+    const bodyStart = raw.indexOf('\n---\n', afterOpenDelimiter);
+    const altStart = raw.indexOf('\n---\r\n', afterOpenDelimiter);
+    const endIndex = altStart !== -1 && (bodyStart === -1 || altStart < bodyStart) ? altStart : bodyStart;
+    if (endIndex === -1)
+        return { frontmatter: '', body: raw };
+    const frontmatter = raw.slice(afterOpenDelimiter, endIndex).trim();
+    const bodyOffset = raw.indexOf('\n', endIndex + 4); // skip past the closing --- and its newline
+    const body = bodyOffset >= 0 ? raw.slice(bodyOffset + 1) : '';
+    return { frontmatter, body };
+}
+/** Tiny YAML subset: flat scalars + single-line [a, b] arrays. Quoted and
+ * unquoted strings both work; inline comments (`# …`) are ignored. */
+function parseFrontmatterBlock(block) {
+    const out = {};
+    if (!block)
+        return out;
+    for (const line of block.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const match = trimmed.match(/^([A-Za-z0-9_-]+)\s*:\s*(.*)$/);
+        if (!match)
+            continue;
+        const key = match[1];
+        let rawVal = match[2].replace(/\s+#.*$/, '').trim();
+        if (rawVal.startsWith('[') && rawVal.endsWith(']')) {
+            out[key] = rawVal.slice(1, -1)
+                .split(',')
+                .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+                .filter(Boolean);
+        }
+        else if ((rawVal.startsWith('"') && rawVal.endsWith('"')) || (rawVal.startsWith("'") && rawVal.endsWith("'"))) {
+            out[key] = rawVal.slice(1, -1);
+        }
+        else {
+            out[key] = rawVal;
+        }
+    }
+    return out;
+}
+/** Locate the packaged `skills/domain` directory. Works both when running
+ * from source (tsx/test) and from the built dist/ layout. */
+export function defaultDomainSkillsRoot() {
+    const here = fileURLToPath(import.meta.url);
+    // src layout:  src/skills/domain-loader.ts     → <repo>/skills/domain
+    // dist layout: dist/skills/domain-loader.js    → <repo>/skills/domain
+    const packageRoot = path.resolve(path.dirname(here), '..', '..');
+    return path.join(packageRoot, 'skills', 'domain');
+}
+/** Walk the domain tree and return parsed skills. Missing dir ⇒ empty list,
+ * not an error: shipping without any seeded skills is a valid state. */
+export async function loadDomainSkills(options = {}) {
+    const rootDir = options.rootDir ?? defaultDomainSkillsRoot();
+    const onError = options.onError ?? ((p, err) => {
+        // eslint-disable-next-line no-console
+        console.error(`[domain-skill] failed to load ${p}: ${err instanceof Error ? err.message : String(err)}`);
+    });
+    if (!fs.existsSync(rootDir))
+        return { skills: [], errors: [] };
+    const skills = [];
+    const errors = [];
+    for (const candidate of walkSkillMarkdown(rootDir)) {
+        try {
+            const raw = fs.readFileSync(candidate.path, 'utf-8');
+            const parsed = parseDomainSkill(raw, candidate.path, candidate.experimental);
+            skills.push(parsed);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            errors.push({ path: candidate.path, error: message });
+            onError(candidate.path, err);
+        }
+    }
+    return { skills, errors };
+}
+/** Enumerate <root>/<host>/SKILL.md and <root>/experimental/<host>/SKILL.md.
+ * Any other files or directory depths are ignored — the layout is strict on
+ * purpose so we don't accidentally pick up READMEs or notes. */
+function* walkSkillMarkdown(rootDir) {
+    const entries = fs.readdirSync(rootDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const entryPath = path.join(rootDir, entry.name);
+        if (entry.name === 'experimental') {
+            for (const inner of fs.readdirSync(entryPath, { withFileTypes: true })) {
+                if (!inner.isDirectory())
+                    continue;
+                const skillPath = path.join(entryPath, inner.name, 'SKILL.md');
+                if (fs.existsSync(skillPath))
+                    yield { path: skillPath, experimental: true };
+            }
+            continue;
+        }
+        const skillPath = path.join(entryPath, 'SKILL.md');
+        if (fs.existsSync(skillPath))
+            yield { path: skillPath, experimental: false };
+    }
+}
+/** Collapse a list of parsed skills into a BadExtension so they flow through
+ * the existing resolveExtensions → setExtensionRules path. Aliases are only
+ * emitted as additional keys when they can't already be reached by the
+ * matcher's substring comparison — otherwise the same body would be
+ * concatenated onto itself at match time. */
+export function buildDomainSkillExtension(skills) {
+    const addRulesForDomain = {};
+    for (const skill of skills) {
+        const body = skill.body;
+        addBody(addRulesForDomain, skill.host, body);
+        for (const alias of skill.aliases) {
+            // Skip aliases that already match via substring on the primary or any
+            // prior alias — registering them would double-emit the body when the
+            // brain matcher walks every registered key.
+            if (alias.includes(skill.host))
+                continue;
+            if (skill.aliases.some((other) => other !== alias && alias.includes(other)))
+                continue;
+            addBody(addRulesForDomain, alias, body);
+        }
+    }
+    return { addRulesForDomain };
+}
+function addBody(map, host, body) {
+    const existing = map[host];
+    if (existing && existing.extraRules) {
+        existing.extraRules = `${existing.extraRules}\n\n${body}`;
+    }
+    else {
+        map[host] = { extraRules: body };
+    }
+}
+//# sourceMappingURL=domain-loader.js.map

package/dist/skills/domain-loader.js.map

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

package/dist/skills/macro-loader.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Macro loader and executor. Reads `skills/macros/*.json` files and validates
+ * each into a typed MacroDefinition. A macro is a flat ordered list of
+ * existing primitive Actions with string-template interpolation over its
+ * declared params.
+ *
+ * This is the minimum viable mutable tool surface: the agent can add new
+ * capability by composing safe primitives into named workflows, without us
+ * eval-ing arbitrary code. Raw TS/JS handlers are a later generation's fight.
+ *
+ * Safety invariants (all enforced at load time, tested):
+ *   1. Step types are restricted to SAFE_MACRO_STEP_TYPES. No `macro` steps
+ *      (flat only). No `navigate` — macros are page-interaction primitives,
+ *      not navigation helpers (macros get triggered when the agent is
+ *      already somewhere).
+ *   2. Param substitution only applies to string fields. Objects and numbers
+ *      pass through as-is.
+ *   3. Unknown params in steps (e.g. `${oops}`) are a load-time error.
+ *   4. Duplicate macro names error at registration.
+ */
+import type { Action } from '../types.js';
+/**
+ * A step inside a macro is any safe primitive action. We use Action
+ * directly — the loader validates that `step.action` is in SAFE_MACRO_STEP_TYPES
+ * at load time. Strings in these actions can carry `${param}` placeholders
+ * that are substituted from the caller's args.
+ */
+export type MacroStep = Action;
+/** Primitive actions that are safe inside a macro. Explicitly whitelists —
+ * any new Action type needs to be added here deliberately. Note that
+ * `navigate` and `complete`/`abort` are intentionally absent: macros
+ * compose local interactions, not run-level control flow. */
+/** Maximum steps in a single macro. Bounds the total wall-time any one
+ * macro can consume (step count × per-action timeout) to keep the
+ * CLI's budget cap meaningful. Raising this requires a measured reason —
+ * a longer macro is usually a hint that the work should split into two.
+ */
+export declare const MAX_MACRO_STEPS = 8;
+export declare const SAFE_MACRO_STEP_TYPES: Set<"select" | "fill" | "type" | "click" | "scroll" | "navigate" | "wait" | "complete" | "press" | "hover" | "evaluate" | "runScript" | "extractWithIndex" | "verifyPreview" | "abort" | "clickSequence" | "clickAt" | "typeAt" | "clickLabel" | "typeLabel" | "macro">;
+export interface MacroParamSpec {
+    name: string;
+    description?: string;
+    /** Minimum required; if absent the macro can be invoked without this arg */
+    required?: boolean;
+}
+export interface MacroDefinition {
+    name: string;
+    description: string;
+    /** Declared parameters. Empty array if the macro takes no args. */
+    params: MacroParamSpec[];
+    /** Ordered, flat list of primitive actions */
+    steps: MacroStep[];
+    /** Where on disk this came from (for diagnostics) */
+    sourcePath: string;
+    /** If true, macro is in staging and is NOT exposed in the agent's prompt
+     *  until it passes eval-gated promotion. */
+    experimental?: boolean;
+}
+export interface MacroRegistry {
+    macros: Map<string, MacroDefinition>;
+    /** The same list rendered for the LLM's system prompt */
+    promptBlock: string;
+}
+/** Exported for tests + promotion script to share the same root resolution.
+ * BAD_MACROS_DIR overrides the packaged path — the promotion script uses this
+ * to point at a staging directory without mutating the canonical tree. */
+export declare function defaultMacrosRoot(): string;
+export interface LoadMacrosOptions {
+    rootDir?: string;
+    /** Include experimental/ subdir (for the promotion script only). */
+    includeExperimental?: boolean;
+    onError?: (p: string, err: unknown) => void;
+}
+export interface LoadMacrosResult {
+    macros: MacroDefinition[];
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+}
+export declare function loadMacros(options?: LoadMacrosOptions): Promise<LoadMacrosResult>;
+export declare function validateMacroDefinition(raw: unknown, sourcePath: string, experimental: boolean): MacroDefinition;
+/** Render the loaded macros into the system-prompt snippet. Called once at
+ * runner boot and cached in the brain. Returns empty string if no macros. */
+export declare function renderMacroPromptBlock(macros: MacroDefinition[]): string;
+/** Substitute `${param}` placeholders in string-typed fields of a step,
+ * using the provided args. Returns a new object — does not mutate input.
+ * Unknown placeholders are collected so the dispatcher can fail fast
+ * instead of silently typing a literal `${missing}` into a form. */
+export declare function interpolateStep(step: MacroStep, args: Record<string, string>): {
+    step: MacroStep;
+    unresolved: string[];
+};
+export declare function buildMacroRegistry(macros: MacroDefinition[]): MacroRegistry;
+//# sourceMappingURL=macro-loader.d.ts.map

package/dist/skills/macro-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"macro-loader.d.ts","sourceRoot":"","sources":["../../src/skills/macro-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAA;AAE9B;;;6DAG6D;AAC7D;;;;GAIG;AACH,eAAO,MAAM,eAAe,IAAI,CAAA;AAEhC,eAAO,MAAM,qBAAqB,yQAchC,CAAA;AAEF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,mEAAmE;IACnE,MAAM,EAAE,cAAc,EAAE,CAAA;IACxB,8CAA8C;IAC9C,KAAK,EAAE,SAAS,EAAE,CAAA;IAClB,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAA;IAClB;gDAC4C;IAC5C,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;IACpC,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;0EAE0E;AAC1E,wBAAgB,iBAAiB,IAAI,MAAM,CAQ1C;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;CAC5C;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,EAAE,CAAA;IACzB,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC/C;AAED,wBAAsB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA6B3F;AAmBD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,eAAe,CAgEhH;AAqBD;6EAC6E;AAC7E,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,CAaxE;AAED;;;oEAGoE;AACpE,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC3B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAc3C;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,aAAa,CAO3E"}

package/dist/skills/macro-loader.js

@@ -0,0 +1,237 @@
+/**
+ * Macro loader and executor. Reads `skills/macros/*.json` files and validates
+ * each into a typed MacroDefinition. A macro is a flat ordered list of
+ * existing primitive Actions with string-template interpolation over its
+ * declared params.
+ *
+ * This is the minimum viable mutable tool surface: the agent can add new
+ * capability by composing safe primitives into named workflows, without us
+ * eval-ing arbitrary code. Raw TS/JS handlers are a later generation's fight.
+ *
+ * Safety invariants (all enforced at load time, tested):
+ *   1. Step types are restricted to SAFE_MACRO_STEP_TYPES. No `macro` steps
+ *      (flat only). No `navigate` — macros are page-interaction primitives,
+ *      not navigation helpers (macros get triggered when the agent is
+ *      already somewhere).
+ *   2. Param substitution only applies to string fields. Objects and numbers
+ *      pass through as-is.
+ *   3. Unknown params in steps (e.g. `${oops}`) are a load-time error.
+ *   4. Duplicate macro names error at registration.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Primitive actions that are safe inside a macro. Explicitly whitelists —
+ * any new Action type needs to be added here deliberately. Note that
+ * `navigate` and `complete`/`abort` are intentionally absent: macros
+ * compose local interactions, not run-level control flow. */
+/** Maximum steps in a single macro. Bounds the total wall-time any one
+ * macro can consume (step count × per-action timeout) to keep the
+ * CLI's budget cap meaningful. Raising this requires a measured reason —
+ * a longer macro is usually a hint that the work should split into two.
+ */
+export const MAX_MACRO_STEPS = 8;
+export const SAFE_MACRO_STEP_TYPES = new Set([
+    'click',
+    'type',
+    'press',
+    'hover',
+    'select',
+    'scroll',
+    'wait',
+    'clickAt',
+    'typeAt',
+    'clickLabel',
+    'typeLabel',
+    'clickSequence',
+    'fill',
+]);
+/** Exported for tests + promotion script to share the same root resolution.
+ * BAD_MACROS_DIR overrides the packaged path — the promotion script uses this
+ * to point at a staging directory without mutating the canonical tree. */
+export function defaultMacrosRoot() {
+    const override = process.env.BAD_MACROS_DIR;
+    if (override && override.length > 0)
+        return path.resolve(override);
+    const here = fileURLToPath(import.meta.url);
+    // src/skills/macro-loader.ts → <repo>/skills/macros
+    // dist/skills/macro-loader.js → <repo>/skills/macros
+    const pkgRoot = path.resolve(path.dirname(here), '..', '..');
+    return path.join(pkgRoot, 'skills', 'macros');
+}
+export async function loadMacros(options = {}) {
+    const rootDir = options.rootDir ?? defaultMacrosRoot();
+    const onError = options.onError ?? ((p, err) => {
+        // eslint-disable-next-line no-console
+        console.error(`[macro] failed to load ${p}: ${err instanceof Error ? err.message : String(err)}`);
+    });
+    if (!fs.existsSync(rootDir))
+        return { macros: [], errors: [] };
+    const candidates = collectMacroFiles(rootDir, options.includeExperimental ?? false);
+    const macros = [];
+    const errors = [];
+    const seen = new Set();
+    for (const { file, experimental } of candidates) {
+        try {
+            const raw = fs.readFileSync(file, 'utf-8');
+            const parsed = JSON.parse(raw);
+            const macro = validateMacroDefinition(parsed, file, experimental);
+            if (seen.has(macro.name)) {
+                throw new Error(`Duplicate macro name "${macro.name}" (already loaded from a prior file)`);
+            }
+            seen.add(macro.name);
+            macros.push(macro);
+        }
+        catch (err) {
+            errors.push({ path: file, error: err instanceof Error ? err.message : String(err) });
+            onError(file, err);
+        }
+    }
+    return { macros, errors };
+}
+function collectMacroFiles(rootDir, includeExperimental) {
+    const result = [];
+    for (const entry of fs.readdirSync(rootDir, { withFileTypes: true })) {
+        const full = path.join(rootDir, entry.name);
+        if (entry.isFile() && entry.name.endsWith('.json')) {
+            result.push({ file: full, experimental: false });
+        }
+        else if (entry.isDirectory() && entry.name === 'experimental' && includeExperimental) {
+            for (const inner of fs.readdirSync(full, { withFileTypes: true })) {
+                if (inner.isFile() && inner.name.endsWith('.json')) {
+                    result.push({ file: path.join(full, inner.name), experimental: true });
+                }
+            }
+        }
+    }
+    return result;
+}
+export function validateMacroDefinition(raw, sourcePath, experimental) {
+    if (!raw || typeof raw !== 'object')
+        throw new Error('macro must be a JSON object');
+    const obj = raw;
+    const name = obj.name;
+    if (typeof name !== 'string' || !/^[a-z][a-z0-9-]*$/i.test(name)) {
+        throw new Error('macro.name must be a non-empty string matching /^[a-z][a-z0-9-]*$/i');
+    }
+    const description = obj.description;
+    if (typeof description !== 'string' || description.length === 0) {
+        throw new Error(`macro.description must be a non-empty string (for the agent's prompt)`);
+    }
+    const rawParams = Array.isArray(obj.params) ? obj.params : [];
+    const params = [];
+    const paramNames = new Set();
+    for (const p of rawParams) {
+        if (!p || typeof p !== 'object')
+            throw new Error('each macro param must be an object');
+        const pn = p.name;
+        if (typeof pn !== 'string' || !/^[a-z][a-z0-9_]*$/i.test(pn)) {
+            throw new Error(`macro param name must match /^[a-z][a-z0-9_]*$/i, got ${String(pn)}`);
+        }
+        if (paramNames.has(pn))
+            throw new Error(`duplicate macro param: ${pn}`);
+        paramNames.add(pn);
+        const spec = { name: pn };
+        if (typeof p.description === 'string') {
+            spec.description = p.description;
+        }
+        if (typeof p.required === 'boolean') {
+            spec.required = p.required;
+        }
+        params.push(spec);
+    }
+    const rawSteps = obj.steps;
+    if (!Array.isArray(rawSteps) || rawSteps.length === 0) {
+        throw new Error('macro.steps must be a non-empty array');
+    }
+    if (rawSteps.length > MAX_MACRO_STEPS) {
+        throw new Error(`macro.steps has ${rawSteps.length} entries, max ${MAX_MACRO_STEPS}. Split the macro.`);
+    }
+    const steps = [];
+    for (let i = 0; i < rawSteps.length; i++) {
+        const step = rawSteps[i];
+        if (!step || typeof step !== 'object' || Array.isArray(step)) {
+            throw new Error(`macro.steps[${i}] must be an object`);
+        }
+        const action = step.action;
+        if (typeof action !== 'string' || !SAFE_MACRO_STEP_TYPES.has(action)) {
+            throw new Error(`macro.steps[${i}].action "${String(action)}" is not in the safe-macro whitelist. ` +
+                `Allowed: ${[...SAFE_MACRO_STEP_TYPES].join(', ')}`);
+        }
+        validateStepTemplates(step, paramNames, i);
+        steps.push(step);
+    }
+    return {
+        name,
+        description,
+        params,
+        steps,
+        sourcePath,
+        ...(experimental ? { experimental: true } : {}),
+    };
+}
+/** Walk a step's string fields and ensure every `${foo}` matches a declared
+ * param. We don't support nested interpolation, math, or anything fancy —
+ * just a literal `${name}` token. */
+function validateStepTemplates(step, paramNames, index) {
+    const re = /\$\{([a-z][a-z0-9_]*)\}/gi;
+    for (const [key, value] of Object.entries(step)) {
+        if (typeof value !== 'string')
+            continue;
+        let match;
+        while ((match = re.exec(value)) !== null) {
+            const name = match[1];
+            if (!paramNames.has(name)) {
+                throw new Error(`macro.steps[${index}].${key} references undeclared param \${${name}} — add it to params[] or remove the template`);
+            }
+        }
+    }
+}
+/** Render the loaded macros into the system-prompt snippet. Called once at
+ * runner boot and cached in the brain. Returns empty string if no macros. */
+export function renderMacroPromptBlock(macros) {
+    const available = macros.filter((m) => !m.experimental);
+    if (available.length === 0)
+        return '';
+    const lines = [];
+    lines.push('');
+    lines.push('USER MACROS (invoke via {"action":"macro","name":"<name>","args":{...}}):');
+    for (const macro of available) {
+        const paramList = macro.params.length > 0
+            ? ` args: { ${macro.params.map((p) => `${p.name}${p.required === false ? '?' : ''}: string`).join(', ')} }`
+            : '';
+        lines.push(`- ${macro.name} — ${macro.description}${paramList}`);
+    }
+    return lines.join('\n');
+}
+/** Substitute `${param}` placeholders in string-typed fields of a step,
+ * using the provided args. Returns a new object — does not mutate input.
+ * Unknown placeholders are collected so the dispatcher can fail fast
+ * instead of silently typing a literal `${missing}` into a form. */
+export function interpolateStep(step, args) {
+    const unresolved = new Set();
+    const entries = Object.entries(step).map(([k, v]) => {
+        if (typeof v !== 'string')
+            return [k, v];
+        return [k, v.replace(/\$\{([a-z][a-z0-9_]*)\}/gi, (match, name) => {
+                if (Object.prototype.hasOwnProperty.call(args, name))
+                    return args[name];
+                unresolved.add(name);
+                return match;
+            })];
+    });
+    return {
+        step: Object.fromEntries(entries),
+        unresolved: [...unresolved],
+    };
+}
+export function buildMacroRegistry(macros) {
+    const map = new Map();
+    for (const macro of macros)
+        map.set(macro.name, macro);
+    return {
+        macros: map,
+        promptBlock: renderMacroPromptBlock(macros),
+    };
+}
+//# sourceMappingURL=macro-loader.js.map

package/dist/skills/macro-loader.js.map

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