feat(register): caller-supplied agent id for identity binding

Adds an optional `id` field to AgentRegistration so callers can bind a
new dashboard record to a framework's canonical agent id (e.g. Lua's
`agent.agentId` from `lua.skill.yaml`) instead of letting register()
generate a UUID. Solves the "first runtime enforce() call creates a
duplicate agent" problem by making the dashboard record use the same
id the runtime will send.

Three coordinated pieces:

  - AgentRegistration.id (optional) — register() honors it when set,
    falls back to crypto.randomUUID() otherwise
  - GovernanceProcessorConfig.agentId (optional) — Mastra processor
    plugin passes it through to register() so framework integrations
    (lua-core etc.) can wire the canonical id from their config
  - ScannerPlugin.extractMetadata hook — scanner plugins surface
    framework-specific structured data (canonical ids, manifest fields)
    alongside the generic scan result via RepoScanResult.metadata.
    Convention key `externalId` is what consumers map to the
    register-time `id` field.

Bumps governance-sdk to 0.8.2.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: scotty595

examples/package.json

@@ -19,7 +19,7 @@
     "hosted:all": "tsx hosted/vercel-ai.ts && tsx hosted/anthropic.ts && tsx hosted/mastra.ts && tsx hosted/langchain.ts && tsx hosted/openai-agents.ts && tsx hosted/mcp.ts"
   },
   "dependencies": {
-    "governance-sdk": "^0.4.4",
+    "governance-sdk": "^0.8.2",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0"
   }

packages/governance-benchmark/package.json

@@ -64,7 +64,7 @@
   },
   "homepage": "https://heygovernance.ai",
   "peerDependencies": {
-    "governance-sdk": ">=0.4.0"
+    "governance-sdk": "^0.8.2"
   },
   "peerDependenciesMeta": {
     "governance-sdk": {

packages/governance/package.json

@@ -1,6 +1,6 @@
 {
   "name": "governance-sdk",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "AI Agent Governance for TypeScript — policy enforcement, scoring, compliance, and audit for AI agents",
   "type": "module",
   "main": "./dist/index.js",

packages/governance/src/index.ts

@@ -177,7 +177,10 @@ export function createGovernance(config: GovernanceConfig = {}): GovernanceInsta
       return remote.register(input);
     }
 
-    const id = crypto.randomUUID();
+    // Honor a caller-supplied id when present (e.g. binding to a Lua
+    // agent's canonical agentId from lua.skill.yaml so the dashboard
+    // record uses the same id the runtime will send to enforce()).
+    const id = input.id ?? crypto.randomUUID();
     const assessment = assessAgent(id, input);
 
     // Persist capability booleans in metadata so re-scoring can reconstruct them

packages/governance/src/plugins/mastra-processor-types.ts

@@ -209,6 +209,13 @@ export interface MastraProcessorInterface {
 // ─── Processor Configuration ──────────────────────────────────
 
 export interface GovernanceProcessorConfig {
+  /**
+   * Optional caller-supplied agent id. When set, the processor will
+   * register with this exact id so the runtime record matches a
+   * pre-existing dashboard-scanned record (e.g. Lua's `agent.agentId`
+   * from `lua.skill.yaml`). When omitted, the SDK generates a UUID.
+   */
+  agentId?: string;
   agentName: string;
   owner: string;
   framework?: AgentFramework;

packages/governance/src/plugins/mastra-processor.ts

@@ -85,6 +85,11 @@ export class GovernanceProcessor implements MastraProcessorInterface {
 
   private async doRegister(): Promise<void> {
     const registration: AgentRegistration = {
+      // Pass through the caller-supplied id when present so the runtime
+      // record binds to a pre-existing dashboard record (e.g. Lua's
+      // canonical agentId). Without this, the SDK would generate a new
+      // UUID on first register and create a duplicate row.
+      id: this.config.agentId,
       name: this.config.agentName,
       framework: this.config.framework ?? "mastra",
       owner: this.config.owner,

packages/governance/src/repo-patterns.ts

@@ -24,6 +24,18 @@ export interface RepoScanResult {
   channels: string[];
   dependencies: string[];
   scannedFiles: number;
+  /**
+   * Framework-specific metadata extracted by a scanner plugin (e.g. the
+   * Lua plugin pulling `agent.agentId` out of `lua.skill.yaml`). Always
+   * undefined for plain `scanRepoContents` calls; populated by
+   * `scanRepoContentsWithPlugins` when a plugin's `extractMetadata`
+   * returns a value.
+   *
+   * The most important convention key is `externalId` — when present,
+   * callers should use it as the agent's canonical id at registration
+   * time so the dashboard record matches the runtime's enforce calls.
+   */
+  metadata?: Record<string, unknown>;
 }
 
 interface PatternDef {
@@ -389,7 +401,29 @@ export async function scanRepoContentsWithPlugins(
     }
   }
 
-  return { ...base, tools: [...tools] };
+  // Collect framework-specific metadata from active plugins. Plugins are
+  // merged in registration order — later plugins overwrite earlier keys
+  // for the same field, but in practice only one plugin should claim a
+  // given repo (gated by detectFramework) so collisions are rare.
+  let metadata: Record<string, unknown> | undefined;
+  for (const plugin of activePlugins) {
+    if (!plugin.extractMetadata) continue;
+    let extracted: Record<string, unknown> | null;
+    try {
+      extracted = await plugin.extractMetadata(fileContents);
+    } catch {
+      extracted = null;
+    }
+    if (extracted) {
+      metadata = { ...(metadata ?? {}), ...extracted };
+    }
+  }
+
+  return {
+    ...base,
+    tools: [...tools],
+    ...(metadata ? { metadata } : {}),
+  };
 }
 
 /** Files worth scanning — skip node_modules, dist, tests, assets. */

packages/governance/src/scanner-plugins/types.ts

@@ -131,4 +131,23 @@ export interface ScannerPlugin {
    * that returns true wins. When omitted, the plugin is always applied.
    */
   detectFramework?(fileContents: Map<string, string>): boolean;
+
+  /**
+   * Optional: extract framework-specific metadata from the scanned
+   * files. Used to surface canonical identifiers, config values, or
+   * any other structured data the framework's manifest carries that
+   * the generic scanner can't see.
+   *
+   * The most important field by convention is `externalId` — when set,
+   * callers (e.g. governance-web's connect-repo route) use it as the
+   * agent's canonical id at registration time so the dashboard record
+   * matches whatever id the runtime will pass to `enforce()`. For Lua
+   * this is `agent.agentId` from `lua.skill.yaml`.
+   *
+   * Plugins may also surface other framework-known fields here. The
+   * scanner doesn't interpret them — it just merges into the result.
+   */
+  extractMetadata?(
+    fileContents: Map<string, string>,
+  ): Promise<Record<string, unknown> | null> | Record<string, unknown> | null;
 }

packages/governance/src/types.ts

@@ -73,6 +73,14 @@ export interface GovernanceAssessment {
 
 /** Agent registration input */
 export interface AgentRegistration {
+  /**
+   * Optional caller-supplied agent id. When omitted, register() generates
+   * a UUID. Provide this when binding to an existing canonical identity
+   * — e.g. a Lua agent's `agent.agentId` from `lua.skill.yaml` — so the
+   * dashboard-registered record matches the id the runtime will pass to
+   * `enforce()`. The id must be unique within the org's storage.
+   */
+  id?: string;
   name: string;
   framework: AgentFramework;
   description?: string;