@inbrowser/agent 0.1.0 → 0.2.0

package/dist/skill-catalog.js

@@ -0,0 +1,388 @@
+/**
+ * Static catalog of skill workflows.
+ *
+ * Phase five of the implementation plan splits the planner-executor work
+ * into three branches: this catalog, the router that classifies a user
+ * prompt against the catalog, and the executor that walks a chosen
+ * skill's prescribed step sequence. This module is the data + types
+ * gate — no runtime logic. The router reads `triggerHints` to score
+ * candidate matches; the executor reads `steps` to materialize a plan.
+ *
+ * Each entry's `name` matches a value in the `SkillName` enum from
+ * `eval/fixture.ts` (re-exported here for convenience). Step
+ * descriptions are imperative, short, and model-agnostic. Per-step
+ * `verifier?` references existing starter / custom specs where one
+ * fits naturally; not every step has one. Leaf "compile / deploy /
+ * verify" steps tend to have a spec; intermediate read / draft steps
+ * usually don't.
+ *
+ * The catalog is hand-authored and intentionally `const`. The
+ * companion test in `test/skill-catalog.test.ts` asserts shape
+ * invariants: every `name` is in `SKILL_NAMES`, every entry has at
+ * least three trigger hints, every entry has between four and nine
+ * steps, every step id is unique and kebab-case within its plan, and
+ * every `verifier?.name` matches a spec registered by
+ * `registerAllSpecs(createSpecRegistry())`.
+ */
+import { SPEC_FINAL_RULES_INCLUDES_LITERAL, SPEC_FINAL_RUNTIME_RUN_SUMMARY_OK, SPEC_GAME_RULES_SIMULATOR_ACCEPTS_POSITIVE_AND_REJECTS_CHEAT, SPEC_PYRIC_AGENTS_LINT_CLEAN_AND_RULE_REJECTS_CHEAT, SPEC_REPORT_MENTIONS_ALL_OF, SPEC_REPORT_MENTIONS_AT_LEAST_ONE_OF, SPEC_TRACE_CONTAINS_TOOL_CALL_BY_NAME, } from './eval/spec-helpers.js';
+// ---------------------------------------------------------------------------
+// The catalog. One entry per in-scope skill, in `SKILL_NAMES` order.
+// Step content is derived from each skill's `SKILL.md` playbook in the
+// downstream firebase-agent-sdk repo.
+// ---------------------------------------------------------------------------
+export const SKILL_CATALOG = [
+    {
+        name: 'firestore-rules-audit',
+        description: 'Audit Firestore security rules for vulnerabilities, semantic errors, and structural anti-patterns.',
+        triggerHints: ['firestore', 'audit', 'rules', 'security', 'vulnerability', 'review'],
+        steps: [
+            {
+                id: 'inspect-rules',
+                description: 'Fetch deployed Firestore rules, parse to AST, and run validator checks.',
+            },
+            {
+                id: 'triage-findings',
+                description: 'Group validator findings by severity: critical, high, medium, low.',
+            },
+            {
+                id: 'cross-reference',
+                description: 'Combine findings on the same path to surface compound vulnerabilities.',
+            },
+            {
+                id: 'apply-context',
+                description: 'Escalate or de-escalate findings based on path purpose and data sensitivity.',
+            },
+            {
+                id: 'compile-report',
+                description: 'Compile prioritized health report with score, findings, and remediation.',
+                verifier: {
+                    name: SPEC_REPORT_MENTIONS_AT_LEAST_ONE_OF,
+                    args: { tokens: ['critical', 'high', 'finding'] },
+                },
+            },
+        ],
+    },
+    {
+        name: 'firebase-project-audit',
+        description: 'Audit an unknown Firebase project for auth gaps, rule weaknesses, and structural issues across services.',
+        triggerHints: ['firebase', 'project', 'audit', 'inspect', 'health', 'unknown'],
+        steps: [
+            {
+                id: 'inspect-project',
+                description: 'Inspect auth, rules, and database structure in a single crawl.',
+            },
+            {
+                id: 'assess-auth',
+                description: 'Evaluate enabled providers and surface auth configuration gaps.',
+            },
+            {
+                id: 'assess-rules',
+                description: 'Walk the rule tree and flag open paths, broken expressions, and warnings.',
+            },
+            {
+                id: 'assess-structure',
+                description: 'Walk the data structure for deep nesting, god nodes, and array patterns.',
+            },
+            {
+                id: 'cross-reference-rules-data',
+                description: 'Compare rule paths against data paths to find unprotected data and orphan rules.',
+            },
+            {
+                id: 'compile-report',
+                description: 'Compile prioritized report with health score, findings, and recommended skills to load.',
+                verifier: {
+                    name: SPEC_REPORT_MENTIONS_AT_LEAST_ONE_OF,
+                    args: { tokens: ['health', 'finding', 'recommendation'] },
+                },
+            },
+        ],
+    },
+    {
+        name: 'rtdb-data-modeling',
+        description: 'Analyze and recommend Realtime Database structures with flat collections, fan-out writes, and index tables.',
+        triggerHints: [
+            'rtdb',
+            'realtime',
+            'data',
+            'model',
+            'modeling',
+            'denormalize',
+            'structure',
+            'schema',
+        ],
+        steps: [
+            {
+                id: 'crawl-structure',
+                description: 'Crawl database structure to inventory top-level keys, depth, and child counts.',
+            },
+            {
+                id: 'sample-data',
+                description: 'Read representative paths to compare stored shape against per-screen needs.',
+            },
+            {
+                id: 'check-god-nodes',
+                description: 'Identify unbounded lists and god nodes that grow without per-user scoping.',
+            },
+            {
+                id: 'evaluate-queries',
+                description: 'Map each app list to a single orderBy path and flag multi-field filter needs.',
+            },
+            {
+                id: 'propose-restructure',
+                description: 'Propose flat collections, index tables, and summary collections via fan-out writes.',
+            },
+            {
+                id: 'verify-restructure',
+                description: 'Validate the proposed shape with a multi-path write and a re-crawl of the structure.',
+                verifier: {
+                    name: SPEC_TRACE_CONTAINS_TOOL_CALL_BY_NAME,
+                    args: { tool: 'crawl_database_structure', minCount: 1 },
+                },
+            },
+        ],
+    },
+    {
+        name: 'firebase-security-rules',
+        description: 'Author, simulate, and deploy Realtime Database security rules with auth, validation, and immutability patterns.',
+        triggerHints: ['rtdb', 'realtime', 'rules', 'security', 'authz', 'access', 'validate'],
+        steps: [
+            {
+                id: 'inspect-current-rules',
+                description: 'Inspect deployed rules and read linter warnings on existing expressions.',
+            },
+            {
+                id: 'design-change',
+                description: 'Identify the rule changes required by the request or by prior audit findings.',
+            },
+            {
+                id: 'validate-expressions',
+                description: 'Build and validate each rule expression before assembling the ruleset IR.',
+            },
+            {
+                id: 'simulate-access',
+                description: 'Simulate positive, negative, cross-user, and validation scenarios against the draft rules.',
+            },
+            {
+                id: 'deploy-rules',
+                description: 'Deploy the full ruleset after every simulation passes.',
+                verifier: {
+                    name: SPEC_FINAL_RULES_INCLUDES_LITERAL,
+                    args: { literal: 'auth' },
+                },
+            },
+            {
+                id: 'verify-deployment',
+                description: 'Re-inspect the deployed rules to confirm they match the intended IR.',
+            },
+        ],
+    },
+    {
+        name: 'firebase-client-sdk',
+        description: 'Generate correct Firebase web client code for init, auth gating, listeners, fan-out writes, and queries.',
+        triggerHints: ['client', 'sdk', 'web', 'javascript', 'app', 'listener', 'init'],
+        steps: [
+            {
+                id: 'get-config',
+                description: 'Fetch the project client config for initializeApp.',
+            },
+            {
+                id: 'inspect-rules-for-auth',
+                description: 'Inspect deployed rules to determine the auth state the client must satisfy.',
+            },
+            {
+                id: 'check-indexes',
+                description: 'Verify indexOn declarations cover every planned orderByChild query.',
+            },
+            {
+                id: 'generate-init-and-auth',
+                description: 'Emit initialization, the auth gate, and the sign-in flow.',
+            },
+            {
+                id: 'generate-reads',
+                description: 'Emit entity listeners, fan-in patterns, or one-time reads as needed.',
+            },
+            {
+                id: 'generate-writes',
+                description: 'Emit set, update at path, and multi-location update writes per intent.',
+            },
+            {
+                id: 'add-cleanup-and-errors',
+                description: 'Add listener unsubscription and permission-denied error handling.',
+            },
+            {
+                id: 'verify-run',
+                description: 'Run the generated code once and confirm the run summary reports success.',
+                verifier: { name: SPEC_FINAL_RUNTIME_RUN_SUMMARY_OK },
+            },
+        ],
+    },
+    {
+        name: 'pyric-agents',
+        description: 'Author Firestore rules and seed data through the pyric MCP tools with lint gating and reversible commits.',
+        triggerHints: ['pyric', 'firestore', 'rules', 'seed', 'lint', 'mcp'],
+        steps: [
+            {
+                id: 'draft-rules',
+                description: 'Draft the Firestore rules source in conversation.',
+            },
+            {
+                id: 'lint-rules',
+                description: 'Lint the draft and iterate until errors are empty.',
+            },
+            {
+                id: 'write-rules',
+                description: 'Write the lint-clean rules through the gated write tool.',
+            },
+            {
+                id: 'draft-seed',
+                description: 'Compose seed data as collection-to-documents arrays.',
+            },
+            {
+                id: 'write-seed',
+                description: 'Write the shape-validated seed through the gated write tool.',
+                verifier: {
+                    name: SPEC_PYRIC_AGENTS_LINT_CLEAN_AND_RULE_REJECTS_CHEAT,
+                },
+            },
+            {
+                id: 'surface-audit-log',
+                description: 'Point the user at the emitted plan and commit event ids.',
+            },
+        ],
+    },
+    {
+        name: 'playground-prompts',
+        description: 'Generate well-shaped 30-50 word playground prompts with a bounded domain and a rule-enforced security boundary.',
+        triggerHints: ['playground', 'prompt', 'prompts', 'demo', 'test', 'scenario'],
+        steps: [
+            {
+                id: 'pick-dimension',
+                description: 'Pick the capability dimension to exercise (rules, transactions, queries, listeners).',
+            },
+            {
+                id: 'pick-domain',
+                description: 'Pick a bounded familiar domain with two collections and a relationship.',
+            },
+            {
+                id: 'specify-security-boundary',
+                description: 'Specify a security boundary tedious to enforce in client code alone.',
+            },
+            {
+                id: 'draft-prompt',
+                description: 'Draft a 30-50 word prompt that fills in actors, data model, and constraint.',
+            },
+            {
+                id: 'tag-capabilities',
+                description: 'Tag what the prompt exercises so the consumer can pick by capability.',
+                verifier: {
+                    name: SPEC_REPORT_MENTIONS_AT_LEAST_ONE_OF,
+                    args: { tokens: ['exercises', 'capability', 'rules', 'state', 'membership'] },
+                },
+            },
+        ],
+    },
+    {
+        name: 'rtdb-game-rules',
+        description: 'Design and deploy Realtime Database security rules for turn-based games with turn guards and win checks.',
+        triggerHints: ['rtdb', 'realtime', 'game', 'turn', 'multiplayer', 'rules'],
+        steps: [
+            {
+                id: 'identify-players',
+                description: 'Identify players, their marks, and how they map to authenticated UIDs.',
+            },
+            {
+                id: 'design-turn-flow',
+                description: 'Design the turn marker, alternation order, and turn-guard write rule.',
+            },
+            {
+                id: 'design-board-and-moves',
+                description: 'Design the board layout, move protocol, and per-cell validation.',
+            },
+            {
+                id: 'design-win-and-end',
+                description: 'Design win helpers, terminal states, and the winner validation rule.',
+            },
+            {
+                id: 'compose-ruleset',
+                description: 'Compose the full ruleset from turnGuard, flip, winCheckHelper, and helpers.',
+            },
+            {
+                id: 'simulate-and-deploy',
+                description: 'Simulate positive and cheating moves, then deploy the ruleset.',
+                verifier: {
+                    name: SPEC_GAME_RULES_SIMULATOR_ACCEPTS_POSITIVE_AND_REJECTS_CHEAT,
+                    args: { database: 'rtdb' },
+                },
+            },
+        ],
+    },
+    {
+        name: 'firestore-game-rules',
+        description: 'Design and deploy Firestore security rules for turn-based games with split-allow rules and dynamic field keys.',
+        triggerHints: ['firestore', 'game', 'turn', 'multiplayer', 'rules', 'split-allow'],
+        steps: [
+            {
+                id: 'design-board',
+                description: 'Design a flat board map with statically named cell fields.',
+            },
+            {
+                id: 'design-turns',
+                description: 'Design turn enforcement with resource.data and a turn-flip validation.',
+            },
+            {
+                id: 'design-move-validity',
+                description: 'Design placement or movement validity with dynamic field keys or a config document.',
+            },
+            {
+                id: 'design-win-detection',
+                description: 'Enumerate winning lines or piece-counter wins as static expressions.',
+            },
+            {
+                id: 'split-allow-rules',
+                description: 'Split the update rule into normal-move, winning-move, and draw branches to stay under the complexity ceiling.',
+            },
+            {
+                id: 'generate-and-deploy',
+                description: 'Generate the rules via code, deploy them, and verify under the test API.',
+                verifier: {
+                    name: SPEC_GAME_RULES_SIMULATOR_ACCEPTS_POSITIVE_AND_REJECTS_CHEAT,
+                    args: { database: 'firestore' },
+                },
+            },
+            {
+                id: 'iterate-on-complexity',
+                description: 'If valid moves are denied, re-split the rules and move expensive checks into separate allow branches.',
+                verifier: {
+                    name: SPEC_REPORT_MENTIONS_ALL_OF,
+                    args: { tokens: ['allow', 'update'] },
+                },
+            },
+        ],
+    },
+];
+// ---------------------------------------------------------------------------
+// Helpers. The router and executor will read the catalog through these to
+// keep their implementations narrow; the catalog itself is exported as a
+// value so callers can iterate without going through them.
+// ---------------------------------------------------------------------------
+const ENTRY_BY_NAME = new Map(SKILL_CATALOG.map((entry) => [entry.name, entry]));
+const NAMES = SKILL_CATALOG.map((entry) => entry.name);
+/**
+ * Look up a catalog entry by skill name. Returns `undefined` when the
+ * name is not in the catalog. The router will use this to materialize
+ * an entry after picking a winner; the executor will use it to
+ * unwrap a router decision into a plan.
+ */
+export function getSkillEntry(name) {
+    return ENTRY_BY_NAME.get(name);
+}
+/**
+ * List every skill name present in the catalog, in catalog order. The
+ * router uses this to iterate candidates when scoring a prompt; the
+ * test suite uses it to assert the catalog covers every value in
+ * `SKILL_NAMES`.
+ */
+export function listSkillNames() {
+    return NAMES;
+}
+//# sourceMappingURL=skill-catalog.js.map

package/dist/skill-catalog.js.map

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

package/dist/skill-router.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Keyword-based skill router.
+ *
+ * Phase five of the implementation plan splits the planner-executor
+ * work into three branches: the static `SkillCatalog`, this router
+ * that classifies a user prompt against the catalog, and the
+ * executor that walks a chosen skill's prescribed step sequence.
+ *
+ * The router is intentionally simple. It does not call a language
+ * model. It lowercases the prompt and counts how many of each
+ * catalog entry's `triggerHints` appear as substrings in the
+ * prompt. The entry with the highest hit count wins. Ties break
+ * in favor of entries whose literal `name` (e.g.
+ * `rtdb-game-rules`) appears in the prompt — either in the
+ * lowered text or in the prompt's kebab-case form (whitespace
+ * collapsed to dashes). After that, ties break by catalog order.
+ * When the score AND name-in-prompt signal both tie between the
+ * top entry and the runner-up, the router returns `match: null`
+ * rather than mis-route into a coin-flip pick.
+ *
+ * A v1 design point: confidence is the raw hit count. There is no
+ * normalization, no probability. The planner-executor decides
+ * whether a `RouterDecision.match` is good enough to act on. When
+ * no entry scores at or above `threshold` (default 1), the router
+ * returns `match: null` and the executor is expected to fall back
+ * to plain ReAct.
+ *
+ * Future work: an LLM-based router could layer on top of this
+ * keyword scoring (for example, only invoked when the keyword
+ * router returns null or returns a low-margin tie). That layering
+ * is explicitly deferred and is not in this branch.
+ */
+import type { SkillName } from './eval/fixture.js';
+import { type SkillCatalog } from './skill-catalog.js';
+/**
+ * A single scored entry in the router's ranking. `score` is the
+ * raw number of `triggerHints` that appeared as substrings of
+ * the lowercased prompt — no normalization or probability.
+ */
+export interface RouterMatch {
+    /** The skill the catalog entry identifies. */
+    skill: SkillName;
+    /** Number of trigger hints matched. Higher is better. */
+    score: number;
+}
+/**
+ * The router's verdict for one prompt. `match` is the top-scoring
+ * candidate when it cleared the threshold, otherwise `null`.
+ * `ranking` always reflects the full sorted scoring, useful for
+ * debugging accuracy and for callers that want to inspect runners-up.
+ */
+export interface RouterDecision {
+    /** The top-scoring match, or null when no entry scored >= threshold. */
+    match: RouterMatch | null;
+    /** All scored entries, descending. Useful for debugging accuracy. */
+    ranking: readonly RouterMatch[];
+}
+/**
+ * Optional overrides for `routeSkill`. `threshold` is the minimum
+ * `score` required to count as a real match (default 1, so a single
+ * trigger hit clears the bar). `catalog` lets tests inject a
+ * different catalog without touching the global.
+ */
+export interface RouterOptions {
+    /** Minimum score required to call it a match. Default 1. */
+    threshold?: number;
+    /** Optional override of the catalog. Defaults to SKILL_CATALOG. */
+    catalog?: SkillCatalog;
+}
+/**
+ * Route a user prompt to a catalog entry using keyword scoring.
+ *
+ * Algorithm:
+ *   1. Lowercase the prompt and compute its kebab-case form
+ *      (whitespace collapsed to dashes) for name matching.
+ *   2. For each entry, score = count of `triggerHints` whose
+ *      lowercased form appears as a substring of the prompt.
+ *   3. Build a ranking sorted by (score DESC, name-in-prompt DESC,
+ *      catalog order ASC). `name-in-prompt` is true when the
+ *      literal skill name (e.g. `rtdb-game-rules`) appears in
+ *      either the lowered prompt or its kebab-case form.
+ *   4. If the top entry's score is >= threshold (default 1),
+ *      return it as `match`; otherwise `match: null`.
+ *   5. Ambiguity guard: if the top entry ties on score with the
+ *      runner-up and the tie-break (name-in-prompt) does not
+ *      disambiguate, return `match: null` rather than committing
+ *      to the catalog-order winner. The brief's hard requirement
+ *      is that the router never returns a *wrong* skill — a
+ *      coin-flip pick is exactly that failure mode.
+ *
+ * The `ranking` returned always covers every catalog entry so
+ * callers can inspect runners-up regardless of the match decision.
+ */
+export declare function routeSkill(prompt: string, options?: RouterOptions): RouterDecision;
+//# sourceMappingURL=skill-router.d.ts.map

package/dist/skill-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-router.d.ts","sourceRoot":"","sources":["../src/skill-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEtE;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,KAAK,EAAE,SAAS,CAAC;IACjB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1B,qEAAqE;IACrE,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAmCD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,cAAc,CA6ClF"}

package/dist/skill-router.js

@@ -0,0 +1,130 @@
+/**
+ * Keyword-based skill router.
+ *
+ * Phase five of the implementation plan splits the planner-executor
+ * work into three branches: the static `SkillCatalog`, this router
+ * that classifies a user prompt against the catalog, and the
+ * executor that walks a chosen skill's prescribed step sequence.
+ *
+ * The router is intentionally simple. It does not call a language
+ * model. It lowercases the prompt and counts how many of each
+ * catalog entry's `triggerHints` appear as substrings in the
+ * prompt. The entry with the highest hit count wins. Ties break
+ * in favor of entries whose literal `name` (e.g.
+ * `rtdb-game-rules`) appears in the prompt — either in the
+ * lowered text or in the prompt's kebab-case form (whitespace
+ * collapsed to dashes). After that, ties break by catalog order.
+ * When the score AND name-in-prompt signal both tie between the
+ * top entry and the runner-up, the router returns `match: null`
+ * rather than mis-route into a coin-flip pick.
+ *
+ * A v1 design point: confidence is the raw hit count. There is no
+ * normalization, no probability. The planner-executor decides
+ * whether a `RouterDecision.match` is good enough to act on. When
+ * no entry scores at or above `threshold` (default 1), the router
+ * returns `match: null` and the executor is expected to fall back
+ * to plain ReAct.
+ *
+ * Future work: an LLM-based router could layer on top of this
+ * keyword scoring (for example, only invoked when the keyword
+ * router returns null or returns a low-margin tie). That layering
+ * is explicitly deferred and is not in this branch.
+ */
+import { SKILL_CATALOG } from './skill-catalog.js';
+/**
+ * Count how many of `hints` appear as substrings of `lowerPrompt`.
+ * Each hint is counted at most once, regardless of how many times
+ * it appears in the prompt — this matches the "number of hints
+ * that matched" framing in the brief, not "total occurrences."
+ */
+function scoreHints(lowerPrompt, hints) {
+    let score = 0;
+    for (const hint of hints) {
+        if (hint.length === 0)
+            continue;
+        if (lowerPrompt.includes(hint.toLowerCase())) {
+            score += 1;
+        }
+    }
+    return score;
+}
+/**
+ * The brief's tie-break: prefer entries whose `name` appears in
+ * the prompt as a substring of the lowercased prompt or its
+ * kebab-case form. The kebab-case form of the prompt is the
+ * lowercased text with all whitespace collapsed to single dashes,
+ * so a user typing "rtdb game rules" still picks up the literal
+ * `rtdb-game-rules` skill name.
+ */
+function nameInPrompt(lowerPrompt, kebabPrompt, name) {
+    return lowerPrompt.includes(name) || kebabPrompt.includes(name);
+}
+function toKebabPrompt(lowerPrompt) {
+    return lowerPrompt.replace(/\s+/g, '-');
+}
+/**
+ * Route a user prompt to a catalog entry using keyword scoring.
+ *
+ * Algorithm:
+ *   1. Lowercase the prompt and compute its kebab-case form
+ *      (whitespace collapsed to dashes) for name matching.
+ *   2. For each entry, score = count of `triggerHints` whose
+ *      lowercased form appears as a substring of the prompt.
+ *   3. Build a ranking sorted by (score DESC, name-in-prompt DESC,
+ *      catalog order ASC). `name-in-prompt` is true when the
+ *      literal skill name (e.g. `rtdb-game-rules`) appears in
+ *      either the lowered prompt or its kebab-case form.
+ *   4. If the top entry's score is >= threshold (default 1),
+ *      return it as `match`; otherwise `match: null`.
+ *   5. Ambiguity guard: if the top entry ties on score with the
+ *      runner-up and the tie-break (name-in-prompt) does not
+ *      disambiguate, return `match: null` rather than committing
+ *      to the catalog-order winner. The brief's hard requirement
+ *      is that the router never returns a *wrong* skill — a
+ *      coin-flip pick is exactly that failure mode.
+ *
+ * The `ranking` returned always covers every catalog entry so
+ * callers can inspect runners-up regardless of the match decision.
+ */
+export function routeSkill(prompt, options) {
+    const threshold = options?.threshold ?? 1;
+    const catalog = options?.catalog ?? SKILL_CATALOG;
+    const lowerPrompt = prompt.toLowerCase();
+    const kebabPrompt = toKebabPrompt(lowerPrompt);
+    // Snapshot each entry with its score, its catalog position, and
+    // the tie-break signal. We sort a copy so the input catalog is
+    // not mutated.
+    const scored = catalog.map((entry, index) => ({
+        skill: entry.name,
+        score: scoreHints(lowerPrompt, entry.triggerHints),
+        nameInPrompt: nameInPrompt(lowerPrompt, kebabPrompt, entry.name),
+        catalogIndex: index,
+    }));
+    scored.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        if (a.nameInPrompt !== b.nameInPrompt)
+            return a.nameInPrompt ? -1 : 1;
+        return a.catalogIndex - b.catalogIndex;
+    });
+    const ranking = scored.map((s) => ({ skill: s.skill, score: s.score }));
+    const top = scored[0];
+    let match = top !== undefined && top.score >= threshold ? { skill: top.skill, score: top.score } : null;
+    // Ambiguity guard. When the top and runner-up share a positive
+    // score and the name-in-prompt tie-break does not separate them,
+    // the keyword router does not have enough signal to commit.
+    // Returning null here hands the prompt off to the planner-executor's
+    // fallback (plain ReAct) rather than mis-routing — the brief's
+    // hard requirement is that the router never returns a *wrong*
+    // skill. Only applies when the top score is at least 1: callers
+    // who pass `threshold: 0` are explicitly asking for the
+    // catalog-order winner regardless of signal.
+    if (match !== null && top.score > 0 && scored.length > 1) {
+        const runnerUp = scored[1];
+        if (runnerUp.score === top.score && runnerUp.nameInPrompt === top.nameInPrompt) {
+            match = null;
+        }
+    }
+    return { match, ranking };
+}
+//# sourceMappingURL=skill-router.js.map

package/dist/skill-router.js.map

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

package/dist/strategy.d.ts

@@ -16,10 +16,29 @@
  * parallel-branch ensembling) sit alongside this one — same
  * `AgentStrategy` interface, different control flow.
  */
-import type { AgentStrategy } from './types/strategy.js';
+import type { AgentStrategy, ReflexionConfig } from './types/strategy.js';
 interface ReactLoopOptions {
     /** Cap on loop iterations to avoid runaway tool-call ping-pong. Default 24. */
     maxTurns?: number;
+    /**
+     * Opt-in: when `true`, tool calls produced in a single turn are partitioned
+     * by the handler's `parallelSafe` tag. Parallel-safe calls run concurrently
+     * with `Promise.all`; the remaining (mutation) calls run sequentially after
+     * the parallel group settles. Result yield order and `messages` order are
+     * preserved in the original input order, so the trace and next-turn prompt
+     * are byte-for-byte identical to a sequential run — the only observable
+     * difference is wall-clock.
+     *
+     * Defaults to `false` (current behavior: every call serialised).
+     */
+    parallelDispatch?: boolean;
+    /**
+     * Opt-in critique-and-retry pass after a candidate final-answer turn.
+     * See `ReflexionConfig` for the verdict shape and the retry/exhaust
+     * semantics. When absent or `enabled: false`, behavior is byte-for-byte
+     * identical to the pre-reflexion loop.
+     */
+    reflexion?: ReflexionConfig;
 }
 export declare function createReactLoopStrategy(options?: ReactLoopOptions): AgentStrategy;
 export {};