Versatly · G9Pedro · Mar 6, 2026 · Mar 6, 2026
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
@@ -4,6 +4,7 @@ import { Command } from 'commander';
 import * as workgraph from '@versatly/workgraph-kernel';
 import { startWorkgraphServer, waitForShutdown } from '@versatly/workgraph-control-api';
 import { registerAutonomyCommands } from './cli/commands/autonomy.js';
+import { registerCapabilityCommands } from './cli/commands/capability.js';
 import { registerConversationCommands } from './cli/commands/conversation.js';
 import { registerDispatchCommands } from './cli/commands/dispatch.js';
 import { registerMcpCommands } from './cli/commands/mcp.js';
@@ -2224,6 +2225,7 @@ registerConversationCommands(program, DEFAULT_ACTOR);
 registerSafetyCommands(program, DEFAULT_ACTOR);
 registerPortabilityCommands(program);
 registerFederationCommands(program, threadCmd, DEFAULT_ACTOR);
+registerCapabilityCommands(program, DEFAULT_ACTOR);
 
 // ============================================================================
 // onboarding

diff --git a/packages/cli/src/cli/commands/capability.ts b/packages/cli/src/cli/commands/capability.ts
@@ -0,0 +1,168 @@
+import { Command } from 'commander';
+import * as workgraph from '@versatly/workgraph-kernel';
+import {
+  addWorkspaceOption,
+  csv,
+  resolveWorkspacePath,
+  runCommand,
+} from '../core.js';
+
+export function registerCapabilityCommands(program: Command, defaultActor: string): void {
+  const capabilityCmd = program
+    .command('capability')
+    .description('Inspect agent capability registry and thread requirement matching');
+
+  addWorkspaceOption(
+    capabilityCmd
+      .command('list')
+      .description('List known capabilities and owning agents')
+      .option('--agent <name>', 'Filter to one agent')
+      .option('--json', 'Emit structured JSON output'),
+  ).action((opts) =>
+    runCommand(
+      opts,
+      () => {
+        const workspacePath = resolveWorkspacePath(opts);
+        const registry = workgraph.capability.buildAgentCapabilityRegistry(workspacePath);
+        const agentFilter = normalizeToken(opts.agent);
+        const agents = agentFilter
+          ? registry.agents.filter((entry) => entry.agentName === agentFilter)
+          : registry.agents;
+        const capabilities = agentFilter
+          ? registry.capabilities.filter((entry) => entry.agents.includes(agentFilter))
+          : registry.capabilities;
+        return {
+          generatedAt: registry.generatedAt,
+          agents,
+          capabilities,
+          agentCount: agents.length,
+          capabilityCount: capabilities.length,
+        };
+      },
+      (result) => {
+        if (result.agents.length === 0) return ['No agent capabilities found.'];
+        return [
+          `Agents: ${result.agentCount}`,
+          `Capabilities: ${result.capabilityCount}`,
+          ...result.agents.map((entry) =>
+            `${entry.agentName} caps=${entry.capabilities.length} skills=${entry.skills.length} adapters=${entry.adapters.length}`),
+        ];
+      },
+    ),
+  );
+
+  addWorkspaceOption(
+    capabilityCmd
+      .command('search <query>')
+      .description('Search capabilities by token or agent identifier')
+      .option('--agent <name>', 'Filter search results by one agent')
+      .option('--json', 'Emit structured JSON output'),
+  ).action((query, opts) =>
+    runCommand(
+      opts,
+      () => {
+        const workspacePath = resolveWorkspacePath(opts);
+        const agentFilter = normalizeToken(opts.agent);
+        const results = workgraph.capability.searchCapabilityRegistry(workspacePath, query)
+          .filter((entry) => !agentFilter || entry.agents.includes(agentFilter));
+        return {
+          query: String(query),
+          agent: agentFilter || undefined,
+          results,
+          count: results.length,
+        };
+      },
+      (result) => {
+        if (result.results.length === 0) return [`No capabilities matched "${result.query}".`];
+        return [
+          ...result.results.map((entry) => `${entry.capability} <- ${entry.agents.join(', ')}`),
+          `${result.count} capability match(es)`,
+        ];
+      },
+    ),
+  );
+
+  addWorkspaceOption(
+    capabilityCmd
+      .command('match <threadRef>')
+      .description('Match one thread against an agent capability profile')
+      .option('-a, --agent <name>', 'Agent identity', defaultActor)
+      .option('--capabilities <items>', 'Comma-separated extra capabilities')
+      .option('--skills <items>', 'Comma-separated extra skills')
+      .option('--adapters <items>', 'Comma-separated extra adapters')
+      .option('--json', 'Emit structured JSON output'),
+  ).action((threadRef, opts) =>
+    runCommand(
+      opts,
+      () => {
+        const workspacePath = resolveWorkspacePath(opts);
+        const normalizedAgent = normalizeToken(opts.agent ?? defaultActor);
+        if (!normalizedAgent) {
+          throw new Error('Agent name is required. Provide --agent.');
+        }
+        const threadInstance = workgraph.capability.resolveThreadInstance(workspacePath, threadRef);
+        if (!threadInstance || threadInstance.type !== 'thread') {
+          throw new Error(`Thread not found: ${threadRef}`);
+        }
+
+        const resolved = workgraph.capability.resolveAgentCapabilityProfile(workspacePath, normalizedAgent);
+        const mergedCapabilities = dedupeStrings([
+          ...resolved.capabilities,
+          ...(csv(opts.capabilities) ?? []).map((item) => normalizeToken(item)),
+        ]);
+        const mergedSkills = dedupeStrings([
+          ...resolved.skills,
+          ...(csv(opts.skills) ?? []).map((item) => normalizeToken(item)),
+        ]);
+        const mergedAdapters = dedupeStrings([
+          ...resolved.adapters,
+          ...(csv(opts.adapters) ?? []).map((item) => normalizeToken(item)),
+        ]);
+        const profile = {
+          ...resolved,
+          capabilities: mergedCapabilities,
+          skills: mergedSkills,
+          adapters: mergedAdapters,
+        };
+        const match = workgraph.capability.matchThreadToCapabilityProfile(threadInstance, profile);
+
+        return {
+          thread: match.thread,
+          profile,
+          requirements: match.requirements,
+          missing: match.missing,
+          matched: match.matched,
+        };
+      },
+      (result) => {
+        const requirementSummary = [
+          `capabilities=${result.requirements.capabilities.join(', ') || 'none'}`,
+          `skills=${result.requirements.skills.join(', ') || 'none'}`,
+          `adapters=${result.requirements.adapters.join(', ') || 'none'}`,
+        ].join(' ');
+        const missingSummary = [
+          `capabilities=${result.missing.capabilities.join(', ') || 'none'}`,
+          `skills=${result.missing.skills.join(', ') || 'none'}`,
+          `adapters=${result.missing.adapters.join(', ') || 'none'}`,
+        ].join(' ');
+        return [
+          `Thread: ${result.thread.path}`,
+          `Agent: ${result.profile.agentName}`,
+          `Matched: ${result.matched}`,
+          `Requirements: ${requirementSummary}`,
+          `Missing: ${missingSummary}`,
+        ];
+      },
+    ),
+  );
+}
+
+function normalizeToken(value: unknown): string {
+  return String(value ?? '')
+    .trim()
+    .toLowerCase();
+}
+
+function dedupeStrings(values: string[]): string[] {
+  return [...new Set(values.filter(Boolean))];
+}
diff --git a/packages/kernel/package.json b/packages/kernel/package.json
@@ -11,5 +11,8 @@
   "dependencies": {
     "gray-matter": "^4.0.3",
     "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@versatly/workgraph-mcp-server": "workspace:*"
   }
 }
diff --git a/packages/kernel/src/agent-self-assembly.ts b/packages/kernel/src/agent-self-assembly.ts
@@ -12,6 +12,7 @@
 
 import * as auth from './auth.js';
 import * as agent from './agent.js';
+import * as capability from './capability.js';
 import * as conversation from './conversation.js';
 import * as dispatch from './dispatch.js';
 import * as orientation from './orientation.js';
@@ -20,12 +21,6 @@ import * as store from './store.js';
 import * as thread from './thread.js';
 import type { PrimitiveInstance, WorkgraphBrief, WorkgraphStatusSnapshot } from './types.js';
 
-const REQUIREMENT_TAG_PREFIXES = {
-  capability: 'requires:capability:',
-  skill: 'requires:skill:',
-  adapter: 'requires:adapter:',
-} as const;
-
 export interface AgentCapabilityAdvertisement {
   capabilities?: string[];
   skills?: string[];
@@ -156,24 +151,7 @@ export function matchThreadToAgent(
   threadInstance: PrimitiveInstance,
   capabilityProfile: AgentCapabilityProfile,
 ): ThreadCapabilityMatch {
-  const requirements = readThreadCapabilityRequirements(threadInstance);
-  const missingCapabilities = requirements.capabilities
-    .filter((requiredCapability) => !capabilitySatisfied(capabilityProfile.capabilities, requiredCapability));
-  const missingSkills = requirements.skills
-    .filter((requiredSkill) => !capabilityProfile.skills.includes(requiredSkill));
-  const missingAdapters = requirements.adapters
-    .filter((requiredAdapter) => !capabilityProfile.adapters.includes(requiredAdapter));
-
-  return {
-    thread: threadInstance,
-    requirements,
-    missing: {
-      capabilities: missingCapabilities,
-      skills: missingSkills,
-      adapters: missingAdapters,
-    },
-    matched: missingCapabilities.length === 0 && missingSkills.length === 0 && missingAdapters.length === 0,
-  };
+  return capability.matchThreadToCapabilityProfile(threadInstance, capabilityProfile);
 }
 
 function maybeBootstrapRegister(
@@ -383,53 +361,6 @@ function findPlanStepForExecution(
   });
 }
 
-function readThreadCapabilityRequirements(threadInstance: PrimitiveInstance): ThreadCapabilityRequirements {
-  const capabilityRequirements = dedupeStrings([
-    ...asStringList(threadInstance.fields.required_capabilities),
-    ...asStringList(threadInstance.fields.requiredCapabilities),
-    ...extractTagRequirements(threadInstance.fields.tags, REQUIREMENT_TAG_PREFIXES.capability),
-  ]);
-  const skillRequirements = dedupeStrings([
-    ...asStringList(threadInstance.fields.required_skills),
-    ...asStringList(threadInstance.fields.requiredSkills),
-    ...extractTagRequirements(threadInstance.fields.tags, REQUIREMENT_TAG_PREFIXES.skill),
-  ]);
-  const adapterRequirements = dedupeStrings([
-    ...asStringList(threadInstance.fields.required_adapters),
-    ...asStringList(threadInstance.fields.requiredAdapters),
-    ...extractTagRequirements(threadInstance.fields.tags, REQUIREMENT_TAG_PREFIXES.adapter),
-  ]);
-
-  return {
-    capabilities: capabilityRequirements,
-    skills: skillRequirements,
-    adapters: adapterRequirements,
-  };
-}
-
-function extractTagRequirements(value: unknown, prefix: string): string[] {
-  return asStringList(value)
-    .filter((tag) => tag.startsWith(prefix))
-    .map((tag) => tag.slice(prefix.length))
-    .filter(Boolean);
-}
-
-function capabilitySatisfied(grantedCapabilities: string[], requiredCapability: string): boolean {
-  const normalizedRequired = normalizeToken(requiredCapability);
-  if (!normalizedRequired) return true;
-  for (const grantedCapability of grantedCapabilities) {
-    if (grantedCapability === '*') return true;
-    if (grantedCapability === normalizedRequired) return true;
-    if (
-      grantedCapability.endsWith(':*') &&
-      normalizedRequired.startsWith(`${grantedCapability.slice(0, -2)}:`)
-    ) {
-      return true;
-    }
-  }
-  return false;
-}
-
 function withCredentialContext<T>(credentialToken: string | undefined, fn: () => T): T {
   const token = readOptionalString(credentialToken);
   if (!token) return fn();