@kybernesis/dispatch 0.1.0 → 0.2.1

package/dist/channel.d.ts

@@ -26,14 +26,26 @@ export declare function peerSubject(peer: PeerRef): string;
 export interface DispatchChannelOptions {
     /**
      * The deployments allowed to call this agent AND assert a forwarded
-     * end-user principal. Must be non-empty — an agent with no peers should
-     * simply not author a dispatch channel. There is deliberately no predicate
-     * form: enumerating concrete peers is the whole point.
+     * end-user principal. There is deliberately no predicate form: enumerating
+     * concrete peers is the whole point. Optional only when `governed` is set;
+     * an agent with neither should simply not author a dispatch channel.
      */
-    trustedPeers: readonly PeerRef[];
+    trustedPeers?: readonly PeerRef[];
+    /**
+     * GOVERNED mode: verify A2A session tokens minted by the Kybernesis control
+     * plane for granted caller→callee edges (requires @kybernesis/enterprise
+     * ≥0.2.0 installed). `agent` is THIS agent's registered name; a verified
+     * a2a caller may call and assert forwarded principals — no peer enumeration
+     * needed, and revoking the edge in the admin locks it out within the token
+     * TTL (default 300 s). Composes with `trustedPeers` (union).
+     */
+    governed?: {
+        issuer: string;
+        agent: string;
+    };
     /**
      * Extra `AuthFn`s appended to the walk (e.g. your web app's auth for a
-     * browser frontend). The Vercel OIDC verifier for peers always runs first.
+     * browser frontend). The peer verifiers always run first.
      */
     extraAuth?: Parameters<typeof eveChannel>[0] extends {
         auth?: infer A;

package/dist/channel.js

@@ -35,18 +35,35 @@ export function peerSubject(peer) {
  *   via `placeholderAuth()` unless you pass real auth in `extraAuth`.
  */
 export function dispatchChannel(options) {
-    const peers = options.trustedPeers;
-    if (!Array.isArray(peers) || peers.length === 0) {
-        throw new Error("dispatchChannel: trustedPeers must name at least one peer deployment — an agent with no peers should not author a dispatch channel.");
+    const peers = options.trustedPeers ?? [];
+    const governed = options.governed;
+    if (peers.length === 0 && !governed) {
+        throw new Error("dispatchChannel: name at least one trustedPeers entry or set governed — an agent with no peers should not author a dispatch channel.");
     }
     const subjects = peers.map(peerSubject);
     const subjectSet = new Set(subjects);
     const extra = (options.extraAuth ?? []);
+    let governedAuth;
+    const governedAuthFn = async (request) => {
+        if (governedAuth === undefined) {
+            try {
+                const mod = (await import("@kybernesis/enterprise"));
+                governedAuth = mod.kybernesisAuth({ issuer: governed.issuer, agent: governed.agent });
+            }
+            catch {
+                console.error("[dispatch] governed mode requires @kybernesis/enterprise >=0.2.0 — install it or remove `governed`.");
+                governedAuth = null;
+            }
+        }
+        return governedAuth ? governedAuth(request) : null;
+    };
     return eveChannel({
         auth: [
             // Verifies which deployment is calling: this project's own tokens are
             // always accepted; other projects only when enumerated as peers.
-            vercelOidc({ subjects }),
+            ...(peers.length > 0 ? [vercelOidc({ subjects })] : []),
+            // Governed callers present a control-plane A2A session token instead.
+            ...(governed ? [governedAuthFn] : []),
             // Open on localhost for `eve dev` and the REPL; ignored in production.
             localDev(),
             ...extra,
@@ -54,8 +71,12 @@ export function dispatchChannel(options) {
             // caller passed real auth above.
             placeholderAuth(),
         ],
-        // Only enumerated peers may assert a forwarded end-user principal.
-        trustedForwarders: (forwarder) => typeof forwarder.subject === "string" &&
-            subjectSet.has(forwarder.subject),
+        // Enumerated peers OR a verified a2a agent principal (whose edge grant was
+        // checked at mint, ≤TTL ago) may assert a forwarded end-user principal.
+        trustedForwarders: (forwarder) => (typeof forwarder.subject === "string" && subjectSet.has(forwarder.subject)) ||
+            (Boolean(governed) &&
+                forwarder.principalType === "agent" &&
+                forwarder.authenticator === "kybernesis" &&
+                forwarder.attributes?.kind === "a2a"),
     });
 }

package/dist/governed.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Governed mode: edges resolved from the Kybernesis control plane instead of
+ * hand-enumerated peers. The caller authenticates to the control plane with its
+ * agent credential (KYBERNESIS_AGENT_CREDENTIAL env), receives a short-TTL A2A
+ * session token for a GRANTED caller→callee edge plus the callee's deployment
+ * URL — so the registry doubles as discovery, and revoking the edge in the
+ * admin takes effect at the next mint (≤ the token TTL, default 300 s).
+ */
+export interface GovernedOptions {
+    /** Control-plane issuer URL (e.g. https://agent.kybernesis.ai). */
+    issuer: string;
+}
+interface MintedSession {
+    token: string;
+    callee: {
+        name: string;
+        deploymentUrl: string | null;
+    };
+    expiresAt: number;
+}
+/**
+ * Per-edge mint cache. url() and auth() both need the mint result and are
+ * invoked independently by eve — a shared in-flight promise keeps them to one
+ * control-plane call per TTL window.
+ */
+export declare function createA2ASessionSource(issuer: string, callee: string): () => Promise<MintedSession>;
+export {};

package/dist/governed.js

@@ -0,0 +1,50 @@
+/**
+ * Governed mode: edges resolved from the Kybernesis control plane instead of
+ * hand-enumerated peers. The caller authenticates to the control plane with its
+ * agent credential (KYBERNESIS_AGENT_CREDENTIAL env), receives a short-TTL A2A
+ * session token for a GRANTED caller→callee edge plus the callee's deployment
+ * URL — so the registry doubles as discovery, and revoking the edge in the
+ * admin takes effect at the next mint (≤ the token TTL, default 300 s).
+ */
+/** Re-mint 30 s before expiry so an in-flight dispatch never carries a stale token. */
+const EXPIRY_BUFFER_SEC = 30;
+/**
+ * Per-edge mint cache. url() and auth() both need the mint result and are
+ * invoked independently by eve — a shared in-flight promise keeps them to one
+ * control-plane call per TTL window.
+ */
+export function createA2ASessionSource(issuer, callee) {
+    let cached = null;
+    let inflight = null;
+    const mint = async () => {
+        const credential = process.env.KYBERNESIS_AGENT_CREDENTIAL;
+        if (!credential) {
+            throw new Error("governed remotePeer: KYBERNESIS_AGENT_CREDENTIAL is not set — mint it in the control plane (agent panel) and add it to this deployment's env.");
+        }
+        const res = await fetch(`${issuer.replace(/\/$/, "")}/api/agent/session`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${credential}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({ callee }),
+        });
+        if (!res.ok) {
+            const body = (await res.json().catch(() => ({})));
+            throw new Error(`governed remotePeer: A2A mint for callee "${callee}" failed (${res.status} ${body.error ?? "unknown"}) — check the edge grant and both agents' status in the control plane.`);
+        }
+        return (await res.json());
+    };
+    return async () => {
+        const nowSec = Math.floor(Date.now() / 1000);
+        if (cached && cached.expiresAt - EXPIRY_BUFFER_SEC > nowSec)
+            return cached;
+        if (!inflight) {
+            inflight = mint().finally(() => {
+                inflight = null;
+            });
+        }
+        cached = await inflight;
+        return cached;
+    };
+}

package/dist/index.d.ts

@@ -22,4 +22,5 @@
  * app's service identity. Upgrade both ends of an edge together.
  */
 export { remotePeer, type RemotePeerOptions } from "./remote-peer.js";
+export { type GovernedOptions } from "./governed.js";
 export { dispatchChannel, peerSubject, type DispatchChannelOptions, type PeerRef, } from "./channel.js";

package/dist/remote-peer.d.ts

@@ -1,18 +1,30 @@
 import { defineRemoteAgent } from "eve";
+import { type GovernedOptions } from "./governed.js";
 /** Options for {@link remotePeer}. */
 export interface RemotePeerOptions {
     /**
      * Environment variable holding the peer deployment's URL (e.g.
      * `"GTM_AGENT_URL"`). Read at runtime on every dispatch, so repointing the
-     * edge is an env change, not a rebuild.
+     * edge is an env change, not a rebuild. Required in ungoverned mode; in
+     * governed mode it becomes an OVERRIDE on top of registry discovery.
      */
-    envVar: string;
+    envVar?: string;
     /**
      * Fallback URL when the env var is unset. Optional — without it, a missing
      * env var fails the dispatch loudly, which is usually what you want in a
      * fresh environment.
      */
     fallbackUrl?: string;
+    /**
+     * GOVERNED mode: the callee's registered name in the control plane. The edge
+     * must be granted (caller→callee) in the admin; outbound auth becomes a
+     * short-TTL A2A session token minted from `governed.issuer` using this
+     * deployment's `KYBERNESIS_AGENT_CREDENTIAL`, and the callee's URL is
+     * resolved from the registry (env var still wins as an override).
+     */
+    callee?: string;
+    /** Control-plane settings for governed mode. Requires `callee`. */
+    governed?: GovernedOptions;
     /**
      * The routing hint. The calling agent's model reads this to decide when to
      * delegate here — write it like the specialist's job description, with the
@@ -22,9 +34,9 @@ export interface RemotePeerOptions {
     description: string;
     /**
      * Forward the verified end-user principal across the hop (default `true`).
-     * The receiver must name this deployment in its `dispatchChannel`
-     * `trustedPeers` for the assertion to be accepted — otherwise the dispatch
-     * fails with a 403 rather than silently downgrading.
+     * The receiver must trust this deployment (trustedPeers, or the verified
+     * a2a caller principal in governed mode) for the assertion to be accepted —
+     * otherwise the dispatch fails with a 403 rather than silently downgrading.
      *
      * Set `false` only when the peer should treat calls as coming from this
      * app itself (service identity) rather than from the human behind it.
@@ -44,17 +56,26 @@ export interface RemotePeerOptions {
  * subagent, with eve's durable dispatch underneath: the calling turn parks
  * without holding compute until the peer posts its terminal callback.
  *
+ * Ungoverned (hand-wired):
  * ```ts title="agent/subagents/gtm.ts"
  * import { remotePeer } from "@kybernesis/dispatch";
- *
  * export default remotePeer({
  *   envVar: "GTM_AGENT_URL",
- *   description:
- *     "The company's GTM operator: posting cadence, open plays, outreach targets, content drafting.",
+ *   description: "The company's GTM operator: cadence, plays, targets, drafting.",
  * });
  * ```
+ * Outbound auth is Vercel OIDC — the peer verifies which deployment is calling.
  *
- * Outbound auth is always Vercel OIDC — the peer verifies which deployment is
- * calling before any principal assertion is considered.
+ * Governed (control-plane edges):
+ * ```ts title="agent/subagents/gtm.ts"
+ * export default remotePeer({
+ *   callee: "eve-gtm",
+ *   governed: { issuer: "https://agent.kybernesis.ai" },
+ *   description: "The company's GTM operator: cadence, plays, targets, drafting.",
+ * });
+ * ```
+ * Outbound auth is a 5-minute A2A token minted per granted edge; the callee's
+ * URL comes from the registry. Revoke the edge in the admin → the next mint
+ * refuses → dispatches 403 within the token TTL.
  */
 export declare function remotePeer(options: RemotePeerOptions): import("eve").RemoteAgentDefinition;

package/dist/remote-peer.js

@@ -1,5 +1,6 @@
 import { defineRemoteAgent } from "eve";
 import { vercelOidc } from "eve/agents/auth";
+import { createA2ASessionSource } from "./governed.js";
 /**
  * Declares a separately deployed eve agent as a callable peer of this agent.
  *
@@ -8,31 +9,70 @@ import { vercelOidc } from "eve/agents/auth";
  * subagent, with eve's durable dispatch underneath: the calling turn parks
  * without holding compute until the peer posts its terminal callback.
  *
+ * Ungoverned (hand-wired):
  * ```ts title="agent/subagents/gtm.ts"
  * import { remotePeer } from "@kybernesis/dispatch";
- *
  * export default remotePeer({
  *   envVar: "GTM_AGENT_URL",
- *   description:
- *     "The company's GTM operator: posting cadence, open plays, outreach targets, content drafting.",
+ *   description: "The company's GTM operator: cadence, plays, targets, drafting.",
  * });
  * ```
+ * Outbound auth is Vercel OIDC — the peer verifies which deployment is calling.
  *
- * Outbound auth is always Vercel OIDC — the peer verifies which deployment is
- * calling before any principal assertion is considered.
+ * Governed (control-plane edges):
+ * ```ts title="agent/subagents/gtm.ts"
+ * export default remotePeer({
+ *   callee: "eve-gtm",
+ *   governed: { issuer: "https://agent.kybernesis.ai" },
+ *   description: "The company's GTM operator: cadence, plays, targets, drafting.",
+ * });
+ * ```
+ * Outbound auth is a 5-minute A2A token minted per granted edge; the callee's
+ * URL comes from the registry. Revoke the edge in the admin → the next mint
+ * refuses → dispatches 403 within the token TTL.
  */
 export function remotePeer(options) {
-    const { envVar, fallbackUrl, description, outputSchema } = options;
-    return defineRemoteAgent({
-        url: () => {
-            const url = process.env[envVar] ?? fallbackUrl;
-            if (!url) {
-                throw new Error(`remotePeer: ${envVar} is not set and no fallbackUrl was provided — set the peer deployment URL in the environment.`);
+    const { envVar, fallbackUrl, description, outputSchema, callee, governed } = options;
+    if (governed && !callee) {
+        throw new Error("remotePeer: governed mode requires `callee` (the peer's registered control-plane name).");
+    }
+    const session = governed && callee ? createA2ASessionSource(governed.issuer, callee) : null;
+    // eve resolves this at agent-graph build (boot), not per dispatch — so URL
+    // resolution must DEGRADE, never throw for a merely-missing credential:
+    // a misconfigured edge should fail when dispatched, not prevent the whole
+    // agent (and its evals) from booting.
+    const url = async () => {
+        const override = envVar ? process.env[envVar] : undefined;
+        if (override)
+            return override;
+        if (session && process.env.KYBERNESIS_AGENT_CREDENTIAL) {
+            try {
+                const s = await session();
+                if (s.callee.deploymentUrl)
+                    return s.callee.deploymentUrl;
             }
-            return url;
-        },
+            catch {
+                // Mint failed (control plane down, edge revoked): fall through to the
+                // static fallback so boot survives; the dispatch itself will fail
+                // loudly in auth() with the precise mint error.
+            }
+        }
+        if (fallbackUrl)
+            return fallbackUrl;
+        throw new Error(`remotePeer: no URL for this edge — ${session
+            ? "registry discovery unavailable (no credential or no registered deploymentUrl) and no envVar/fallbackUrl override is set."
+            : `${envVar ?? "envVar"} is not set and no fallbackUrl was provided.`}`);
+    };
+    const auth = session
+        ? async () => {
+            const s = await session();
+            return { headers: { authorization: `Bearer ${s.token}` } };
+        }
+        : vercelOidc();
+    return defineRemoteAgent({
+        url,
         description,
-        auth: vercelOidc(),
+        auth,
         forwardPrincipal: options.forwardPrincipal ?? true,
         ...(outputSchema !== undefined ? { outputSchema } : {}),
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/dispatch",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Agent-to-agent dispatch for eve agents: declared remote-peer edges with principal forwarding on by default, and a receiver channel that makes trusting the wrong caller hard to express.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,7 +35,8 @@
     "typescript": "7.0.2"
   },
   "peerDependencies": {
-    "eve": ">=0.30.0 <0.31.0"
+    "eve": ">=0.30.0 <0.31.0",
+    "@kybernesis/enterprise": ">=0.2.0"
   },
   "engines": {
     "node": ">=20"
@@ -47,5 +48,10 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "peerDependenciesMeta": {
+    "@kybernesis/enterprise": {
+      "optional": true
+    }
   }
 }