open-multi-agent-kit 0.90.3 → 0.90.5

package/examples/extensions/sandbox/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "omk-extension-sandbox",
-	"version": "0.90.3",
+	"version": "0.90.5",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "omk-extension-sandbox",
-			"version": "0.90.3",
+			"version": "0.90.5",
 			"dependencies": {
 				"@anthropic-ai/sandbox-runtime": "0.0.26"
 			}

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-sandbox",
 	"private": true,
-	"version": "0.90.3",
+	"version": "0.90.5",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/subagent/agent-capability-router.test.ts

@@ -0,0 +1,123 @@
+/**
+ * Deterministic unit tests for the agent → capability router.
+ *
+ * The router is fully deterministic (no LLM, no randomness, no I/O inside the
+ * router itself), so every assertion here is an exact expected value. The only
+ * I/O is the one-time module-scope catalog build, which scans the live skill
+ * tree under the agent directory.
+ */
+import { describe, expect, it } from "vitest";
+import { auditCapabilities, classifyAgent, deriveCapabilities } from "./agent-capability-router.ts";
+import { buildCapabilityCatalog } from "./capabilities.ts";
+
+// Built once at module scope from the live skill tree under the agent
+// directory. This is populated during local verification but empty in CI (the
+// agent skill catalog is not checked out on the runner), so the skill-catalog
+// -dependent assertions below are guarded with `skipIf(!hasSkillCatalog)`. The
+// MCP/hooks sets are a fixed OMK list and stay populated everywhere.
+const catalog = buildCapabilityCatalog({ agentDir: `${process.env.HOME ?? "/home/yu"}/.omk/agent` });
+const hasSkillCatalog = catalog.skills.size > 0;
+
+describe("classifyAgent", () => {
+	it("classifies by name token: seo-specialist → marketing-content", () => {
+		expect(classifyAgent("seo-specialist", "x")?.id).toBe("marketing-content");
+	});
+
+	it("classifies smart-contract-auditor → security", () => {
+		expect(classifyAgent("smart-contract-auditor", "x")?.id).toBe("security");
+	});
+
+	it("classifies react-developer → frontend-web", () => {
+		expect(classifyAgent("react-developer", "x")?.id).toBe("frontend-web");
+	});
+
+	it("guards the gin→engineer substring regression: ml-engineer is NOT backend-api", () => {
+		// "engineer" contains "gin"; a naive first-match classifier would route
+		// this to backend-api. Boundary-anchored voting must not.
+		expect(classifyAgent("ml-engineer", "AI/ML")?.id).not.toBe("backend-api");
+	});
+
+	it("guards the gis→strategist substring regression: account-strategist is NOT gis-spatial", () => {
+		// "strategist" contains "gis"; must not flip into the GIS domain.
+		expect(classifyAgent("account-strategist", "x")?.id).not.toBe("gis-spatial");
+	});
+
+	it("returns null when no domain matches", () => {
+		expect(classifyAgent("zzz-nonexistent-xyz", "nothing relevant here")).toBeNull();
+	});
+});
+
+describe("deriveCapabilities", () => {
+	it.skipIf(!hasSkillCatalog)(
+		"weights the name token: react-developer's first derived skill is react-patterns",
+		() => {
+			const { skills } = deriveCapabilities("react-developer", "React frontend", catalog);
+			expect(skills[0]).toBe("react-patterns");
+		},
+	);
+
+	it.skipIf(!hasSkillCatalog)("includes the literal domain skill for seo-specialist", () => {
+		const { skills } = deriveCapabilities("seo-specialist", "SEO", catalog);
+		expect(skills).toContain("seo");
+	});
+
+	it("returns empty skills for an unmatched domain", () => {
+		const { skills } = deriveCapabilities("zzz-unknown", "x", catalog);
+		expect(skills.length).toBe(0);
+	});
+
+	it.skipIf(!hasSkillCatalog)("only emits skills that exist in the live catalog", () => {
+		const { skills } = deriveCapabilities("react-developer", "React frontend", catalog);
+		expect(skills.length).toBeGreaterThan(0);
+		for (const skill of skills) {
+			expect(catalog.skills.has(skill)).toBe(true);
+		}
+	});
+
+	it("derived MCP is a subset of the catalog MCP set", () => {
+		const { mcp } = deriveCapabilities("devops-automator", "kubernetes", catalog);
+		expect(mcp.length).toBeGreaterThan(0);
+		for (const server of mcp) {
+			expect(catalog.mcp.has(server)).toBe(true);
+		}
+	});
+});
+
+describe("auditCapabilities", () => {
+	it("identical sets → jaccard 1.0 and verdict match", () => {
+		const caps = { skills: ["react-patterns"], mcp: [], hooks: [] };
+		const result = auditCapabilities(caps, caps, catalog);
+		expect(result.jaccard).toBe(1.0);
+		expect(result.verdict).toBe("match");
+	});
+
+	it("disjoint sets → jaccard 0 and verdict divergent", () => {
+		const declared = { skills: ["react-patterns"], mcp: [], hooks: [] };
+		const derived = { skills: ["seo"], mcp: [], hooks: [] };
+		const result = auditCapabilities(declared, derived, catalog);
+		expect(result.jaccard).toBe(0);
+		expect(result.verdict).toBe("divergent");
+	});
+
+	it("half overlap → jaccard within [0,1] and verdict drift or match", () => {
+		const declared = { skills: ["react-patterns", "seo"], mcp: [], hooks: [] };
+		const derived = { skills: ["react-patterns"], mcp: [], hooks: [] };
+		const result = auditCapabilities(declared, derived, catalog);
+		expect(result.jaccard).toBeGreaterThanOrEqual(0);
+		expect(result.jaccard).toBeLessThanOrEqual(1);
+		expect(["drift", "match"]).toContain(result.verdict);
+	});
+
+	it("surfaces declared-but-unknown skills in declaredUnknownSkills", () => {
+		const declared = { skills: ["fake-skill-xyz"], mcp: [], hooks: [] };
+		const derived = { skills: [], mcp: [], hooks: [] };
+		const result = auditCapabilities(declared, derived, catalog);
+		expect(result.declaredUnknownSkills).toContain("fake-skill-xyz");
+	});
+
+	it("both-empty skills → jaccard 1.0", () => {
+		const empty = { skills: [], mcp: [], hooks: [] };
+		const result = auditCapabilities(empty, empty, catalog);
+		expect(result.jaccard).toBe(1.0);
+	});
+});

package/examples/extensions/subagent/agent-capability-router.ts

@@ -0,0 +1,274 @@
+/**
+ * Deterministic agent → capability router.
+ *
+ * Classifies an agent (by name + description) into a {@link DomainProfile},
+ * derives a baseline capability set (skills / MCP / hooks) from the live
+ * {@link CapabilityCatalog}, and audits a declared capability set against the
+ * deterministic derivation (Jaccard overlap + drift verdict).
+ *
+ * Fully deterministic: same inputs always yield same outputs. No LLM calls,
+ * no randomness, no I/O. Depends only on {@link DOMAIN_PROFILES} and the
+ * passed-in catalog.
+ *
+ * Classification is **name-weighted vote scoring**: a domain's keywords are
+ * tested against the agent name and description; matches inside the name (the
+ * strongest identity signal) count triple. The domain with the highest score
+ * wins (ties resolved by array order, so specific domains should come first).
+ * This is robust to the substring false positives that plague first-match
+ * classification (e.g. `chem` matching "s**chem**a", `gis` matching
+ * "strate**gis**t"): a single accidental description hit cannot outvote a
+ * domain that matches the name.
+ *
+ * @module agent-capability-router
+ */
+
+import type { AgentCapabilities, CapabilityCatalog } from "./capabilities.ts";
+import { validateCapabilities } from "./capabilities.ts";
+import type { DomainProfile } from "./domain-profiles.ts";
+import { DOMAIN_PROFILES } from "./domain-profiles.ts";
+
+/** Maximum number of scored skills to grant. */
+const MAX_SKILLS = 6;
+/** Number of pool skills granted as a fallback when nothing scores above zero. */
+const FALLBACK_SKILLS = 4;
+/** Jaccard threshold (inclusive) for a "match" verdict. */
+const JACCARD_MATCH = 0.5;
+/** Jaccard threshold (inclusive) for a "drift" verdict. */
+const JACCARD_DRIFT = 0.15;
+/** Weight multiplier when a keyword or skill token matches an agent *name* token. */
+const NAME_WEIGHT = 3;
+
+/**
+ * Generic role-suffix tokens that carry no domain signal and must not be
+ * counted as matches (otherwise e.g. "react-developer" would tie
+ * "angular-developer" on the "developer" token). These are stripped before
+ * both classification voting and derive scoring.
+ */
+const GENERIC_ROLE_TOKENS: ReadonlySet<string> = new Set([
+	"agent",
+	"analyst",
+	"architect",
+	"auditor",
+	"builder",
+	"coach",
+	"consultant",
+	"coordinator",
+	"creator",
+	"designer",
+	"developer",
+	"director",
+	"editor",
+	"engineer",
+	"expert",
+	"guardian",
+	"lead",
+	"manager",
+	"master",
+	"mentor",
+	"navigator",
+	"officer",
+	"operator",
+	"planner",
+	"producer",
+	"reviewer",
+	"specialist",
+	"steward",
+	"strategist",
+	"tester",
+	"writer",
+	"engineers",
+	"specialists",
+	"managers",
+	"developers",
+]);
+
+/**
+ * Classify an agent by name + description against {@link DOMAIN_PROFILES} using
+ * name-weighted vote scoring. Returns the highest-scoring domain (ties resolve
+ * to the earliest in {@link DOMAIN_PROFILES}), or `null` when every domain
+ * scores zero — the explicit "No direct OMK skill match" sentinel.
+ */
+export function classifyAgent(name: string, description: string): DomainProfile | null {
+	const nameLower = name.toLowerCase();
+	const text = `${name} ${description}`.toLowerCase();
+
+	let best: DomainProfile | null = null;
+	let bestScore = 0;
+	for (const domain of DOMAIN_PROFILES) {
+		let score = 0;
+		for (const re of domain.keywords) {
+			// Boundary-anchored match: a keyword only counts when it lands on a
+			// word edge, so bare short keywords ("gin", "gis", "chem") cannot fire
+			// inside unrelated words ("engineer", "strategist", "schema").
+			if (!keywordHits(re, text)) continue;
+			// A keyword that also matches the agent name is a strong identity
+			// signal (the name is the most reliable classifier); otherwise it
+			// is a weaker description-only hit.
+			score += keywordHits(re, nameLower) ? NAME_WEIGHT : 1;
+		}
+		if (score > bestScore) {
+			bestScore = score;
+			best = domain;
+		}
+	}
+	return best;
+}
+
+/** Split lowercased text into identity tokens: non-word boundaries, length >= 2. */
+function tokenize(lowerText: string): string[] {
+	const tokens: string[] = [];
+	for (const raw of lowerText.split(/[^a-z0-9+#]+/)) {
+		if (raw.length >= 2) tokens.push(raw);
+	}
+	return tokens;
+}
+
+/** Identity tokens with generic role suffixes removed. */
+function identityTokens(lowerText: string): string[] {
+	return tokenize(lowerText).filter((t) => !GENERIC_ROLE_TOKENS.has(t));
+}
+
+/**
+ * Boundary-anchored keyword test. A keyword must start at a left word edge
+ * (start-of-text or a non-`[a-z0-9]` neighbor). A **right** boundary is added
+ * only for short, all-alphabetic keywords (length <= 4, e.g. "gin", "gis",
+ * "chem", "seo"): those are the ones that cause substring false positives
+ * ("gin" -> "engineer", "gis" -> "strategist", "chem" -> "schema"). Longer and
+ * pattern keywords ("react", "3d-", "smart-?contract", "document-?generat")
+ * use prefix semantics (left edge only) so intentional prefix/partial matches
+ * still fire. Node >= 10 supports lookbehind.
+ */
+function keywordHits(re: RegExp, text: string): boolean {
+	const src = re.source;
+	const shortBare = src.length <= 4 && /^[a-z]+$/i.test(src);
+	const right = shortBare ? "(?![a-z0-9])" : "";
+	return new RegExp(`(?<![a-z0-9])${src}${right}`, "i").test(text);
+}
+
+/**
+ * Score a candidate skill against the agent's name and description tokens.
+ * The skill's **first** `-`-split token is the technology word (e.g. "react"
+ * in "react-patterns") and is weighted heaviest; a match in the agent name is
+ * worth {@link NAME_WEIGHT}x a description match. Generic tokens are skipped.
+ */
+function skillMatchScore(
+	skill: string,
+	nameTokens: ReadonlySet<string>,
+	descTokens: ReadonlySet<string>,
+	nameLower: string,
+	descLower: string,
+): number {
+	const parts = skill.split("-");
+	let score = 0;
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i];
+		if (part.length === 0 || GENERIC_ROLE_TOKENS.has(part)) continue;
+		const isTech = i === 0; // first token = the technology word
+		const nameHit = nameTokens.has(part);
+		const descHit = descTokens.has(part);
+		if (nameHit) score += (isTech ? 5 : 2) * NAME_WEIGHT;
+		else if (descHit) score += isTech ? 5 : 2;
+	}
+	// Full skill string appearing verbatim in name or description is a strong signal.
+	if (nameLower.includes(skill)) score += 3 * NAME_WEIGHT;
+	else if (descLower.includes(skill)) score += 3;
+	return score;
+}
+
+/** Dedupe a list preserving first-seen order. */
+function dedupe(items: readonly string[]): string[] {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const item of items) {
+		if (seen.has(item)) continue;
+		seen.add(item);
+		out.push(item);
+	}
+	return out;
+}
+
+/**
+ * Deterministically derive a baseline capability set for an agent. When no
+ * domain matches, all three lists are empty. Otherwise skills are picked from
+ * the domain's pool by name/description relevance (top {@link MAX_SKILLS} with
+ * a positive score, falling back to the first {@link FALLBACK_SKILLS} pool
+ * entries when nothing scores above zero), and MCP/hooks are the domain
+ * defaults intersected with the live catalog.
+ */
+export function deriveCapabilities(name: string, description: string, catalog: CapabilityCatalog): AgentCapabilities {
+	const domain = classifyAgent(name, description);
+	if (domain === null) return { skills: [], mcp: [], hooks: [] };
+
+	const nameLower = name.toLowerCase();
+	const descLower = description.toLowerCase();
+	const nameTokens = new Set(identityTokens(nameLower));
+	const descTokens = new Set(identityTokens(`${nameLower} ${descLower}`));
+
+	const candidates = domain.skillPool.filter((s) => catalog.skills.has(s));
+	const scored = candidates.map((skill) => ({
+		skill,
+		score: skillMatchScore(skill, nameTokens, descTokens, nameLower, descLower),
+	}));
+	const positive = scored.filter((x) => x.score > 0);
+
+	let selected: string[];
+	if (positive.length > 0) {
+		positive.sort((a, b) => {
+			if (a.score !== b.score) return b.score - a.score;
+			if (a.skill < b.skill) return -1;
+			if (a.skill > b.skill) return 1;
+			return 0;
+		});
+		selected = positive.slice(0, MAX_SKILLS).map((x) => x.skill);
+	} else {
+		selected = candidates.slice(0, FALLBACK_SKILLS);
+	}
+
+	const mcp = domain.defaultMcp.filter((m) => catalog.mcp.has(m));
+	const hooks = domain.defaultHooks.filter((h) => catalog.hooks.has(h));
+
+	return { skills: dedupe(selected), mcp, hooks };
+}
+
+/** Result of comparing a declared capability set against the deterministic derivation. */
+export interface CapabilityAudit {
+	/** Jaccard overlap of declared vs derived skill sets, 0..1 (1.0 when both empty). */
+	readonly jaccard: number;
+	/** Skills declared but not in the live catalog (from {@link validateCapabilities}). */
+	readonly declaredUnknownSkills: readonly string[];
+	readonly skillsOnlyInDeclared: readonly string[];
+	readonly skillsOnlyInDerived: readonly string[];
+	/** "match" (jaccard >= 0.5), "drift" (0.15 <= jaccard < 0.5), "divergent" (jaccard < 0.15). */
+	readonly verdict: "match" | "drift" | "divergent";
+}
+
+/**
+ * Compare a declared (e.g. LLM-assigned or embedded) capability set against the
+ * deterministic derivation. The Jaccard coefficient is over the two skill lists
+ * treated as sets; both-empty is defined as 1.0.
+ */
+export function auditCapabilities(
+	declared: AgentCapabilities,
+	derived: AgentCapabilities,
+	catalog: CapabilityCatalog,
+): CapabilityAudit {
+	const declaredSet = new Set(declared.skills);
+	const derivedSet = new Set(derived.skills);
+
+	let intersection = 0;
+	for (const s of declaredSet) if (derivedSet.has(s)) intersection++;
+	const unionSize = new Set([...declaredSet, ...derivedSet]).size;
+	const jaccard = unionSize === 0 ? 1.0 : intersection / unionSize;
+
+	const declaredUnknownSkills = validateCapabilities(declared, catalog).unknownSkills;
+
+	const skillsOnlyInDeclared: string[] = [];
+	for (const s of declaredSet) if (!derivedSet.has(s)) skillsOnlyInDeclared.push(s);
+	const skillsOnlyInDerived: string[] = [];
+	for (const s of derivedSet) if (!declaredSet.has(s)) skillsOnlyInDerived.push(s);
+
+	const verdict: "match" | "drift" | "divergent" =
+		jaccard >= JACCARD_MATCH ? "match" : jaccard >= JACCARD_DRIFT ? "drift" : "divergent";
+
+	return { jaccard, declaredUnknownSkills, skillsOnlyInDeclared, skillsOnlyInDerived, verdict };
+}

package/examples/extensions/subagent/agents/planner.md

@@ -9,6 +9,9 @@ You are a planning specialist. You receive context (from a scout) and requiremen
 
 You must NOT make any changes. Only read, analyze, and plan.
 
+Assigned capabilities (see ~/.omk/agent/SUBAGENTS.md for the full routing reference):
+- Skills: ulw-plan (explore-first planning, decision-complete plans), packages (if the codebase spans multiple packages), deep-interview (only if requirements are still fuzzy after reading the scout's context). Load only what the task needs; do not bulk-load the catalog.
+
 Input format you'll receive:
 - Context/findings from a scout agent
 - Original query or requirements

package/examples/extensions/subagent/agents/reviewer.md

@@ -10,6 +10,9 @@ You are a senior code reviewer. Analyze code for quality, security, and maintain
 Bash is for read-only commands only: `git diff`, `git log`, `git show`. Do NOT modify files or run builds.
 Assume tool permissions are not perfectly enforceable; keep all bash usage strictly read-only.
 
+Assigned capabilities (see ~/.omk/agent/SUBAGENTS.md for the full routing reference):
+- Skills: review-work (structured multi-angle review pass), security-review (when the diff touches auth, secrets, or user input). Load only what the task needs.
+
 Strategy:
 1. Run `git diff` to see recent changes (if applicable)
 2. Read the modified files

package/examples/extensions/subagent/agents/scout.md

@@ -9,6 +9,9 @@ You are a scout. Quickly investigate a codebase and return structured findings t
 
 Your output will be passed to an agent who has NOT seen the files you explored.
 
+Assigned capabilities (see ~/.omk/agent/SUBAGENTS.md for the full routing reference):
+- Skills: understand-anything (if a knowledge-graph/dependency question, not just a file lookup), ast-grep (structural search when grep-by-text isn't precise enough), headroom (if findings would otherwise be too large to hand off compactly). Load only what the task needs.
+
 Thoroughness (infer from task, default medium):
 - Quick: Targeted lookups, key files only
 - Medium: Follow imports, read critical sections

package/examples/extensions/subagent/agents/worker.md

@@ -8,6 +8,8 @@ You are a worker agent with full capabilities. You operate in an isolated contex
 
 Work autonomously to complete the assigned task. Use all available tools as needed.
 
+Assigned capabilities (see ~/.omk/agent/SUBAGENTS.md for the full routing reference): no fixed skill set — you have the full catalog. Self-route: classify the task, pick the most specific matching skill, load only that one, and never browse the catalog speculatively. For general coding work the most common picks are programming, debugging, git-master, ast-grep, and lsp; for anything else, match by the skill's own description.
+
 Output format when finished:
 
 ## Completed

package/examples/extensions/subagent/agents.ts

@@ -5,6 +5,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAgentDir, parseFrontmatter } from "open-multi-agent-kit";
+import { type AgentCapabilities, parseCapabilities } from "./capabilities.ts";
 
 export type AgentScope = "user" | "project" | "both";
 
@@ -13,6 +14,11 @@ export interface AgentConfig {
 	description: string;
 	tools?: string[];
 	model?: string;
+	/** Optional capabilities declared in frontmatter (canonical source). */
+	capabilities?: AgentCapabilities;
+	/** When true, the dispatcher restricts the spawned subprocess to the declared
+	 * skills via `--no-skills` + `--skill <path>`. Default off (guidance only). */
+	enforceCapabilities?: boolean;
 	systemPrompt: string;
 	source: "user" | "project";
 	filePath: string;
@@ -60,11 +66,19 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 			.map((t: string) => t.trim())
 			.filter(Boolean);
 
+		const capabilities = parseCapabilities(frontmatter);
+		const enforceCapabilities =
+			typeof frontmatter.enforceCapabilities === "string"
+				? frontmatter.enforceCapabilities.trim().toLowerCase() === "true"
+				: undefined;
+
 		agents.push({
 			name: frontmatter.name,
 			description: frontmatter.description,
 			tools: tools && tools.length > 0 ? tools : undefined,
 			model: frontmatter.model,
+			capabilities,
+			enforceCapabilities,
 			systemPrompt: body,
 			source,
 			filePath,