Remote register: fetch authoritative score/level from API (0.13.2)

Previously remoteRegister() returned a synthetic `{ level: 0 }` as
a placeholder — the comment said "authoritative values arrive after
first enforce()", but callers that cached the level (e.g. the
Mastra processor's agentLevel field) then sent that 0 on every
subsequent enforce. Rules gating on `agent_level >= N` fired
incorrectly for higher-level agents until the process restarted.

Fix: POST to /api/v1/agents on register() and use the API's real
compositeScore / governanceLevel in the returned receipt. The API
already deduplicates by id/name, so calling this against a
pre-existing agent returns the authoritative record — no need for
a separate lookup.

Falls back to the old synthetic receipt when the API is unreachable
or returns non-200, so register() still never throws for the
caller. The next enforce() carries authoritative data either way.

Author: scotty595

packages/governance/package.json

@@ -1,6 +1,6 @@
 {
   "name": "governance-sdk",
-  "version": "0.13.1",
+  "version": "0.13.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/remote-enforce.test.ts

@@ -265,28 +265,47 @@ describe("remote enforce", () => {
 
 // ─── Remote register ────────────────────────────────────────────
 
-describe("remote register (local no-op)", () => {
+describe("remote register (POST /api/v1/agents)", () => {
   const config = { serverUrl: "https://api.example.com", apiKey: "test-key" };
 
-  test("returns synthetic result using agent name as ID", async () => {
+  test("POSTs to /api/v1/agents and returns authoritative score + level", async () => {
+    setupFetchMock(201, {
+      id: "agent-abc",
+      name: "my-agent",
+      compositeScore: 72,
+      governanceLevel: 3,
+      status: "approved",
+    });
     const remote = createRemoteEnforcer(config);
     const result = await remote.register({
       name: "my-agent",
       framework: "mastra",
       owner: "team-a",
     });
 
-    assert.equal(result.id, "my-agent");
-    assert.equal(result.status, "registered");
+    assert.equal(mockFetch.mock.calls.length, 1);
+    const url = mockFetch.mock.calls[0].arguments[0];
+    assert.equal(url, "https://api.example.com/api/v1/agents");
+    assert.equal(result.id, "agent-abc");
+    assert.equal(result.score, 72);
+    assert.equal(result.level, 3);
+    assert.equal(result.status, "approved");
     assert.equal(result.assessment.agentName, "my-agent");
   });
 
-  test("does not call fetch — registration is handled by enforce endpoint", async () => {
-    setupFetchMock(200, {});
+  test("falls back to synthetic receipt when cloud is unreachable", async () => {
+    setupFetchMock(500, {});
     const remote = createRemoteEnforcer(config);
-    await remote.register({ name: "a", framework: "mastra", owner: "t" });
+    const result = await remote.register({
+      name: "my-agent",
+      framework: "mastra",
+      owner: "team-a",
+    });
 
-    assert.equal(mockFetch.mock.calls.length, 0);
+    // Non-200 — we fall through so register never throws on the caller.
+    assert.equal(result.id, "my-agent");
+    assert.equal(result.status, "registered");
+    assert.equal(result.level, 0);
   });
 });
 
@@ -320,8 +339,14 @@ describe("createGovernance remote integration", () => {
     assert.equal(mockFetch.mock.calls.length, 1);
   });
 
-  test("register returns synthetic result when serverUrl is set (no fetch)", async () => {
-    setupFetchMock(200, {});
+  test("register POSTs to /api/v1/agents when serverUrl is set", async () => {
+    setupFetchMock(201, {
+      id: "agent-xyz",
+      name: "test",
+      compositeScore: 55,
+      governanceLevel: 2,
+      status: "approved",
+    });
 
     const gov = createGovernance({
       serverUrl: "https://api.example.com",
@@ -334,10 +359,15 @@ describe("createGovernance remote integration", () => {
       owner: "team",
     });
 
-    // Register is a local no-op — API auto-registers on enforce
-    assert.equal(result.id, "test");
-    assert.equal(result.status, "registered");
-    assert.equal(mockFetch.mock.calls.length, 0);
+    // Register now fetches authoritative score/level from the API rather
+    // than returning a synthetic level: 0 placeholder.
+    assert.equal(result.id, "agent-xyz");
+    assert.equal(result.level, 2);
+    assert.equal(mockFetch.mock.calls.length, 1);
+    assert.equal(
+      mockFetch.mock.calls[0].arguments[0],
+      "https://api.example.com/api/v1/agents",
+    );
   });
 
   test("local methods still work when serverUrl is set", async () => {

packages/governance/src/remote-enforce.ts

@@ -178,15 +178,88 @@ export function createRemoteEnforcer(config: RemoteConfig) {
   }
 
   /**
-   * In cloud mode, this returns a SYNTHETIC confirmation. There is no
-   * dedicated remote register endpoint — the API auto-registers agents
-   * on the first `enforce()` call. The returned `score` / `level` are
-   * placeholder zeros; authoritative values arrive after first enforce.
+   * Register (or look up) an agent against the cloud API.
    *
-   * If you need a registration receipt before any enforcement happens,
-   * use local mode (no `serverUrl`) or call the cloud REST API directly.
+   * POSTs to `/api/v1/agents` with the registration payload. The API
+   * auto-dedupes by id/name, so calling this on a pre-existing agent
+   * is idempotent — it returns the existing record's authoritative
+   * score + level. This fixes the previous placeholder behaviour where
+   * remoteRegister returned `level: 0` unconditionally, which caused
+   * agent_level-conditioned rules to fire incorrectly for higher-level
+   * agents on every enforce().
+   *
+   * If the cloud call fails for any reason (network, auth, 5xx), we
+   * still return a synthetic "registered" receipt so the caller isn't
+   * blocked on a non-essential register step. The next enforce() will
+   * carry authoritative data regardless.
    */
   async function remoteRegister(input: AgentRegistration): Promise<RemoteRegisterResult> {
+    try {
+      const response = await fetch(`${baseUrl}/api/v1/agents`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          id: input.id,
+          name: input.name,
+          framework: input.framework,
+          owner: input.owner,
+          description: input.description,
+          tools: input.tools,
+          channels: input.channels,
+          hasAuth: input.hasAuth,
+          hasGuardrails: input.hasGuardrails,
+          hasObservability: input.hasObservability,
+          hasAuditLog: input.hasAuditLog,
+        }),
+        signal: AbortSignal.timeout(timeout),
+      });
+      if (response.ok) {
+        const data = await response.json() as {
+          id?: string;
+          name?: string;
+          compositeScore?: number;
+          governanceLevel?: number;
+          status?: string;
+        };
+        const id = data.id ?? input.name;
+        const score = typeof data.compositeScore === "number" ? data.compositeScore : 0;
+        // Clamp to the valid GovernanceLevel range (0-4). The API is the
+        // source of truth here, but we validate defensively.
+        const rawLevel = typeof data.governanceLevel === "number" ? data.governanceLevel : 0;
+        const level = (rawLevel >= 0 && rawLevel <= 4
+          ? Math.round(rawLevel)
+          : 0) as 0 | 1 | 2 | 3 | 4;
+        const status: "registered" | "assessed" | "approved" | "flagged" | "deprecated" | "quarantined" =
+          data.status === "assessed" || data.status === "approved" ||
+          data.status === "flagged" || data.status === "deprecated" ||
+          data.status === "quarantined"
+            ? data.status
+            : "registered";
+        return {
+          id,
+          score,
+          level,
+          status,
+          assessment: {
+            agentId: id,
+            agentName: data.name ?? input.name,
+            compositeScore: score,
+            level: { level, label: "live", autonomy: "governed", minScore: 0, maxScore: 100 },
+            status,
+            dimensions: [],
+            recommendations: [],
+            assessedAt: new Date().toISOString(),
+          },
+        };
+      }
+      // 409 / 4xx — fall through to the synthetic receipt. The next
+      // enforce() is still authoritative.
+    } catch {
+      // Network/timeout — same fall-through.
+    }
     return {
       id: input.name,
       score: 0,