@claude-flow/plugin-agent-federation 1.0.4 → 1.0.6

package/dist/a2a/agent-card.d.ts

@@ -0,0 +1,130 @@
+/**
+ * A2A (Agent2Agent, Linux Foundation) Agent Card adapter — cards only.
+ *
+ * Maps ruflo's bespoke federation identity (`FederationManifest` /
+ * `FederationNode`) to and from a spec-compliant A2A Agent Card so ruflo
+ * nodes are discoverable by A2A peers and A2A peers appear in federation
+ * discovery. This is an ADAPTER over the existing federation schema, not a
+ * rewrite — A2A Tasks/messaging are deliberately out of scope.
+ *
+ * Spec: A2A Protocol 1.0.0 — https://a2a-protocol.org/latest/specification/
+ * (schema source of truth: specification/a2a.proto in a2aproject/A2A).
+ * Required AgentCard fields per spec §4.4.1: name, description,
+ * supportedInterfaces, version, capabilities, defaultInputModes,
+ * defaultOutputModes, skills.
+ */
+import { FederationNode } from '../domain/entities/federation-node.js';
+import type { FederationManifest } from '../domain/services/discovery-service.js';
+/** A2A protocol version this adapter targets. */
+export declare const A2A_PROTOCOL_VERSION = "1.0";
+/**
+ * Well-known URI for Agent Card discovery (A2A 1.0 §8.2 + IANA registration
+ * §14). NOTE: earlier drafts used `/.well-known/agent.json`; 0.3.0+ settled
+ * on `agent-card.json`.
+ */
+export declare const A2A_WELL_KNOWN_PATH = "/.well-known/agent-card.json";
+/**
+ * Open-form protocol binding string advertising ruflo's federation wire
+ * (Ed25519-signed envelopes over WebSocket/QUIC). Spec §4.4.6 explicitly
+ * allows non-core bindings: "This is an open form string, to be easily
+ * extended for other protocol bindings."
+ */
+export declare const RUFLO_FEDERATION_BINDING = "RUFLO-FEDERATION";
+/**
+ * Extension URI carrying the bespoke federation identity inside the card
+ * (spec §4.6 AgentExtension). Enables lossless round-trip in fromAgentCard.
+ */
+export declare const RUFLO_FEDERATION_EXTENSION_URI = "urn:ruflo:federation:manifest:v1";
+export interface A2AAgentInterface {
+    readonly url: string;
+    readonly protocolBinding: string;
+    readonly protocolVersion: string;
+    readonly tenant?: string;
+}
+export interface A2AAgentSkill {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly tags: readonly string[];
+    readonly examples?: readonly string[];
+    readonly inputModes?: readonly string[];
+    readonly outputModes?: readonly string[];
+}
+export interface A2AAgentExtension {
+    readonly uri: string;
+    readonly description?: string;
+    readonly required?: boolean;
+    readonly params?: Record<string, unknown>;
+}
+export interface A2AAgentCapabilities {
+    readonly streaming?: boolean;
+    readonly pushNotifications?: boolean;
+    readonly extensions?: readonly A2AAgentExtension[];
+    readonly extendedAgentCard?: boolean;
+}
+export interface A2AAgentProvider {
+    readonly url: string;
+    readonly organization: string;
+}
+export interface A2AAgentCard {
+    readonly name: string;
+    readonly description: string;
+    readonly supportedInterfaces: readonly A2AAgentInterface[];
+    readonly version: string;
+    readonly capabilities: A2AAgentCapabilities;
+    readonly defaultInputModes: readonly string[];
+    readonly defaultOutputModes: readonly string[];
+    readonly skills: readonly A2AAgentSkill[];
+    readonly provider?: A2AAgentProvider;
+    readonly documentationUrl?: string;
+    readonly iconUrl?: string;
+    readonly securitySchemes?: Record<string, unknown>;
+    readonly securityRequirements?: readonly Record<string, readonly string[]>[];
+    readonly signatures?: readonly {
+        protected: string;
+        signature: string;
+    }[];
+}
+export interface ToAgentCardOptions {
+    /** Human-readable agent name; defaults to `ruflo-federation/<nodeId>`. */
+    readonly name?: string;
+    /** Human-readable description override. */
+    readonly description?: string;
+    readonly provider?: A2AAgentProvider;
+    readonly documentationUrl?: string;
+    /**
+     * Extra spec-core interfaces to advertise ahead of the federation binding
+     * (e.g. a JSONRPC endpoint once A2A messaging lands). First entry is the
+     * preferred interface per spec.
+     */
+    readonly additionalInterfaces?: readonly A2AAgentInterface[];
+}
+/**
+ * Generate a spec-compliant A2A Agent Card from a ruflo federation manifest.
+ * Every agent type becomes an AgentSkill; the federation endpoint becomes a
+ * `RUFLO-FEDERATION` interface; the bespoke identity (nodeId, publicKey,
+ * complianceModes, manifest signature) rides in a spec §4.6 extension so
+ * `fromAgentCard` can restore it.
+ */
+export declare function toAgentCard(manifest: FederationManifest, options?: ToAgentCardOptions): A2AAgentCard;
+export interface AgentCardValidation {
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+}
+/**
+ * Structural validation against the A2A 1.0 AgentCard REQUIRED fields.
+ * Intentionally strict on required shape, lenient on unknown extra fields
+ * (forward compatibility with future spec minors).
+ */
+export declare function validateAgentCard(value: unknown): AgentCardValidation;
+/**
+ * Map a validated remote A2A Agent Card into the bespoke federation registry
+ * shape (a `FederationNode`) so A2A peers appear in federation discovery.
+ *
+ * Trust posture: A2A cards are self-describing metadata, NOT authenticated
+ * federation manifests — consumed peers always enter at
+ * `TrustLevel.UNTRUSTED` regardless of embedded identity claims. Trust is
+ * earned afterwards through the normal handshake + TrustEvaluator path.
+ */
+export declare function fromAgentCard(card: A2AAgentCard, sourceUrl?: string): FederationNode;
+//# sourceMappingURL=agent-card.d.ts.map

package/dist/a2a/consume.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A2A Agent Card consumption — fetch + validate a remote card and map it
+ * into the bespoke federation registry so A2A peers appear in federation
+ * discovery. Cards only (no A2A Tasks/messaging in this iteration).
+ */
+import type { DiscoveryService } from '../domain/services/discovery-service.js';
+import type { FederationNode } from '../domain/entities/federation-node.js';
+import { type A2AAgentCard } from './agent-card.js';
+export interface FetchAgentCardOptions {
+    /** Injectable fetch for tests / restricted environments. Default: globalThis.fetch. */
+    readonly fetchImpl?: typeof fetch;
+    readonly timeoutMs?: number;
+    /** Response size cap in bytes (defense against decompression floods). Default 256 KiB. */
+    readonly maxBytes?: number;
+}
+export interface FetchAgentCardResult {
+    readonly card: A2AAgentCard;
+    readonly sourceUrl: string;
+}
+/**
+ * Resolve the card URL: a bare base URL (`https://host[:port]` or a path-less
+ * URL) gets the A2A well-known path appended; anything already pointing at a
+ * JSON document is used as-is.
+ */
+export declare function resolveAgentCardUrl(baseOrCardUrl: string): string;
+/** Fetch and structurally validate a remote A2A Agent Card. */
+export declare function fetchAgentCard(baseOrCardUrl: string, options?: FetchAgentCardOptions): Promise<FetchAgentCardResult>;
+/**
+ * Fetch a remote Agent Card and register the peer in federation discovery.
+ * The peer enters at TrustLevel.UNTRUSTED (see fromAgentCard) — the card is
+ * self-asserted metadata, and trust is earned through the normal handshake.
+ */
+export declare function consumeAgentCard(discovery: DiscoveryService, baseOrCardUrl: string, options?: FetchAgentCardOptions): Promise<FederationNode>;
+//# sourceMappingURL=consume.d.ts.map

package/dist/a2a/planner-descriptor.d.ts

@@ -0,0 +1,40 @@
+import { type A2AAgentCard } from './agent-card.js';
+/**
+ * Host-owned planner semantics for a registered capability identifier.
+ * Remote registration metadata may select an identifier, but never supplies
+ * these planner-visible strings directly.
+ */
+export interface PlannerCapabilityDefinition {
+    readonly id: string;
+    readonly functionality: string;
+    readonly inputSpecification: string;
+    readonly outputSpecification: string;
+    readonly usageConstraints: readonly string[];
+}
+export interface PlannerDescriptorPolicy {
+    /** Resolve only identifiers the host has explicitly approved for planning. */
+    readonly resolveCapability: (canonicalSkillId: string) => PlannerCapabilityDefinition | undefined;
+    readonly maximumCapabilities?: number;
+}
+export interface PlannerSafeAgentDescriptor {
+    readonly schema: 'ruflo/planner-safe-agent-descriptor/v1';
+    readonly source: 'a2a-agent-card';
+    readonly capabilities: readonly PlannerCapabilityDefinition[];
+    readonly authority: 'none';
+}
+export interface PlannerDescriptorProjection {
+    readonly descriptor: PlannerSafeAgentDescriptor;
+    readonly rejectedSkillCount: number;
+    readonly duplicateSkillCount: number;
+}
+/**
+ * Project a third-party A2A Agent Card into planner-visible metadata.
+ *
+ * Security boundary: card descriptions, skill descriptions, examples, tags,
+ * provider text, documentation URLs, extension parameters, and all other
+ * remote prose are deliberately absent from the return type. Only a bounded
+ * canonical skill identifier may cross the registration boundary, and its
+ * planner semantics come from a host-controlled resolver.
+ */
+export declare function projectPlannerSafeAgentCard(card: A2AAgentCard, policy: PlannerDescriptorPolicy): PlannerDescriptorProjection;
+//# sourceMappingURL=planner-descriptor.d.ts.map

package/dist/a2a/well-known.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A2A well-known Agent Card endpoint (A2A 1.0 §8.2 discovery + §8.6 caching).
+ *
+ * Serves `GET /.well-known/agent-card.json` from a minimal `node:http`
+ * server. Security posture follows ADR-166 (mcp-bridge unauthenticated-RCE
+ * remediation): binds 127.0.0.1 by default and REFUSES a non-loopback bind
+ * unless the caller passes `allowNonLoopback: true` explicitly. The endpoint
+ * is read-only (GET/HEAD on one exact path), exposes only the public card,
+ * and is entirely opt-in — nothing here weakens the federation transport's
+ * existing bind or auth behavior.
+ */
+import { type A2AAgentCard } from './agent-card.js';
+export interface AgentCardServerOptions {
+    /** Card supplier — re-invoked per request so a late-published manifest is picked up. */
+    readonly getCard: () => A2AAgentCard | null;
+    readonly port: number;
+    /** Bind host. Default 127.0.0.1 (ADR-166 posture). */
+    readonly host?: string;
+    /** Serve path. Default A2A_WELL_KNOWN_PATH. */
+    readonly path?: string;
+    /**
+     * Explicit opt-in required to bind anything other than loopback. Without
+     * it a non-loopback host is rejected at start (fail-closed).
+     */
+    readonly allowNonLoopback?: boolean;
+    /** Cache-Control max-age seconds (spec §8.6.1). Default 300. */
+    readonly cacheMaxAgeSeconds?: number;
+}
+export interface AgentCardServerHandle {
+    readonly url: string;
+    readonly host: string;
+    readonly port: number;
+    close(): Promise<void>;
+}
+export declare function isLoopbackHost(host: string): boolean;
+/**
+ * Start the well-known Agent Card HTTP endpoint.
+ *
+ * Responses:
+ *   GET/HEAD <path>  → 200 application/json (+ Cache-Control, ETag per §8.6)
+ *                      or 503 when no card is available yet
+ *   other method     → 405
+ *   other path       → 404
+ */
+export declare function startAgentCardServer(options: AgentCardServerOptions): Promise<AgentCardServerHandle>;
+//# sourceMappingURL=well-known.d.ts.map

package/dist/application/claim-checker.d.ts

@@ -0,0 +1,27 @@
+import type { FederationClaimType, PolicyEngineDeps } from './policy-engine.js';
+export type FederationAuthorizationMode = 'legacy' | 'observe' | 'enforce';
+export interface FederationClaimCheckerConfig {
+    mode?: FederationAuthorizationMode;
+    grantedClaims?: readonly string[];
+    onObservation?: (claim: FederationClaimType, granted: boolean) => void;
+}
+export interface FederationClaimChecker {
+    mode: FederationAuthorizationMode;
+    grantedClaims: ReadonlySet<FederationClaimType>;
+    checkClaim: PolicyEngineDeps['checkClaim'];
+}
+/**
+ * Compatibility bridge for the legacy federation policy engine.
+ *
+ * This removes the anonymous `() => true` production stub and makes
+ * compatibility behavior explicit:
+ * - legacy: preserve pre-ADR-325 behavior;
+ * - observe: calculate and report missing grants without blocking;
+ * - enforce: default deny unless the exact claim is configured.
+ *
+ * ADR-324 policy adapters can supply the `grantedClaims` set after evaluating
+ * the request; ownership-changing federation messages remain disabled in the
+ * default message policy until the full ingress PEP is composed.
+ */
+export declare function createFederationClaimChecker(config?: FederationClaimCheckerConfig): FederationClaimChecker;
+//# sourceMappingURL=claim-checker.d.ts.map

package/dist/application/federation-breaker-service.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Federation circuit breaker service (ADR-097 Phase 2.b).
+ *
+ * Phase 2.a shipped the FederationNode state machine + canTransition table.
+ * This service is what drives transitions: it records per-peer send outcomes
+ * (success/failure + spend), evaluates thresholds against the configured
+ * policy, and calls suspend()/evict()/reactivate() on the entity.
+ *
+ * Architecture is two-layer to keep the policy testable in isolation:
+ *
+ *   1. **evaluatePolicy** (pure function) — given rolling samples for a peer
+ *      + the policy + now, returns a BreakerDecision describing what should
+ *      happen. No I/O, no clock, no entity mutation.
+ *   2. **FederationBreakerService** — owns the rolling-sample buffer,
+ *      wraps evaluatePolicy with the entity mutation step, and exposes
+ *      `recordOutcome` (called by the coordinator on each send completion)
+ *      + `tick` (called periodically to drive cooldown/auto-evict).
+ *
+ * The cost-tracker integration (Phase 3 upstream — emits federation_spend
+ * events when sends complete) is *not* wired here; this service holds its
+ * own in-memory rolling buffer. When Phase 3 upstream lands, the consumer
+ * can call `recordOutcome` from the bus subscriber and the buffer becomes
+ * a transparent cache. This keeps Phase 2 deliverable without a hard
+ * cost-tracker dependency.
+ *
+ * Security invariants:
+ *
+ *   1. Negative tokens/usd are clamped to 0 — a malicious receive-side
+ *      reporter cannot drive an "unsuspend" through credit inflation.
+ *   2. Sample buffer is bounded per-peer (DEFAULT_MAX_SAMPLES_PER_PEER) so
+ *      a high-throughput peer cannot exhaust memory.
+ *   3. Policy evaluation is order-independent for SUSPEND triggers —
+ *      cost OR failure-ratio fires the same SUSPEND. The reason field
+ *      records which one tripped.
+ *   4. evaluatePolicy is pure & deterministic given (samples, policy, now)
+ *      — no Date.now() calls inside, no random IDs, no hidden state.
+ *   5. Auto-eviction only runs from SUSPENDED state and only after the
+ *      grace age. Cannot skip SUSPENDED for an ACTIVE → EVICTED jump.
+ */
+import { FederationNode } from '../domain/entities/federation-node.js';
+import { SuspensionReason } from '../domain/value-objects/federation-node-state.js';
+/** A single send outcome recorded by the coordinator. */
+export interface SendOutcome {
+    readonly nodeId: string;
+    readonly success: boolean;
+    /** Tokens consumed by this leg. Negative values are treated as 0. */
+    readonly tokensUsed?: number;
+    /** USD spent on this leg. Negative values are treated as 0. */
+    readonly usdSpent?: number;
+    /** Caller-supplied timestamp (for testability). Defaults to recordOutcome's `now`. */
+    readonly at?: Date;
+}
+/** Configurable thresholds. All defaults come from ADR-097 Part 2. */
+export interface BreakerPolicy {
+    /** 24h spend cap per peer. Default $5.00. */
+    readonly costSuspensionUsd: number;
+    /** Window for the cost cap. Default 24h. */
+    readonly costWindowMs: number;
+    /** Failure ratio that trips the breaker. Default 0.5 (50%). */
+    readonly failureRatioThreshold: number;
+    /** Window for failure-ratio computation. Default 1h. */
+    readonly failureWindowMs: number;
+    /** Minimum samples in the failure window before evaluating (anti-noise). Default 10. */
+    readonly failureMinSamples: number;
+    /** Cooldown before SUSPENDED → reactivate-eligible. Default 30min. */
+    readonly cooldownMs: number;
+    /** Continuous suspension age before auto-evict. Default 24h. */
+    readonly autoEvictionAgeMs: number;
+}
+export declare const DEFAULT_BREAKER_POLICY: BreakerPolicy;
+/** Per-peer sample buffer cap. ~24h of 1-Hz traffic. */
+export declare const DEFAULT_MAX_SAMPLES_PER_PEER = 100000;
+/** A normalized, time-stamped outcome (negatives clamped, `at` resolved). */
+interface NormalizedSample {
+    readonly success: boolean;
+    readonly tokensUsed: number;
+    readonly usdSpent: number;
+    readonly at: Date;
+}
+/**
+ * What the breaker decided for a peer at evaluation time. The service then
+ * applies the action (calls node.suspend()/evict()/reactivate()) but the
+ * decision itself is a pure return so tests can assert it without checking
+ * mutated state.
+ */
+export type BreakerDecision = {
+    readonly action: 'NONE';
+    readonly nodeId: string;
+} | {
+    readonly action: 'SUSPEND';
+    readonly nodeId: string;
+    readonly reason: SuspensionReason;
+} | {
+    readonly action: 'EVICT';
+    readonly nodeId: string;
+    readonly reason: SuspensionReason;
+} | {
+    readonly action: 'REACTIVATE_ELIGIBLE';
+    readonly nodeId: string;
+};
+/**
+ * Pure policy evaluator. Returns the decision the breaker should apply.
+ * No I/O, no clock, no entity mutation — given the same inputs, returns the
+ * same output. The service layer is responsible for calling node.suspend()
+ * / evict() / reactivate() based on this.
+ *
+ * Decision rules:
+ *
+ *   For ACTIVE peers:
+ *     - 24h cost > policy.costSuspensionUsd → SUSPEND/COST_THRESHOLD_EXCEEDED
+ *     - 1h failure ratio > policy.failureRatioThreshold (≥ failureMinSamples
+ *       in window) → SUSPEND/FAILURE_RATIO_EXCEEDED
+ *     - else NONE
+ *
+ *   For SUSPENDED peers:
+ *     - suspended ≥ autoEvictionAgeMs → EVICT/GRACE_PERIOD_EXPIRED
+ *     - cooldown elapsed → REACTIVATE_ELIGIBLE (caller probes + reactivates)
+ *     - else NONE
+ *
+ *   For EVICTED peers: always NONE (terminal under breaker flow).
+ *
+ * Cost takes priority over failure-ratio when both trip, because cost is
+ * the more conservative signal (a malicious peer can manufacture failures
+ * by trickling errors but cannot manufacture spend without actually
+ * burning budget).
+ */
+export declare function evaluatePolicy(samples: readonly NormalizedSample[], node: FederationNode, policy: BreakerPolicy, now: Date): BreakerDecision;
+/**
+ * Stateful service: owns the per-peer sample buffer, applies decisions to
+ * entities, and exposes the breaker control surface to the coordinator.
+ *
+ * Construct once per federation coordinator. Inject the policy if you need
+ * non-default thresholds (Phase 4 doctor surface will let users tune them).
+ */
+/**
+ * ADR-111 Phase 3 — callback invoked after the breaker applies a successful
+ * state transition. Used by the coordinator to propagate suspends to the
+ * WG mesh layer (clearing AllowedIPs). Not invoked for `apply=false` dry runs
+ * or `NONE` / `REACTIVATE_ELIGIBLE` decisions. Errors thrown from the callback
+ * are swallowed at the breaker — the entity transition has already happened,
+ * and side-effect failures shouldn't unwind the breaker's internal state.
+ */
+export type BreakerTransitionListener = (node: FederationNode, decision: BreakerDecision) => void | Promise<void>;
+export declare class FederationBreakerService {
+    private readonly policy;
+    private readonly samples;
+    private readonly maxSamplesPerPeer;
+    private readonly onTransition?;
+    constructor(policy?: BreakerPolicy, maxSamplesPerPeer?: number, onTransition?: BreakerTransitionListener);
+    /** Read the active policy (handy for tests + doctor surface). */
+    getPolicy(): BreakerPolicy;
+    /**
+     * Record a send outcome for a peer. Called by the coordinator after each
+     * `routing.send` completion. Returns a BreakerDecision describing what,
+     * if anything, the breaker would do for this peer right now — but does
+     * NOT apply it (the caller asks `evaluate(node)` if they want the action
+     * to actually happen). This split lets the coordinator decide whether to
+     * apply on every outcome or batch via tick.
+     *
+     * Negative tokens/usd are clamped to 0. A peer cannot inflate its own
+     * remaining cost ceiling by reporting credits.
+     */
+    recordOutcome(outcome: SendOutcome, now?: Date): void;
+    /**
+     * Evaluate the breaker for one peer and apply the resulting transition
+     * to the entity. Returns the decision so callers can observe the outcome.
+     *
+     * `apply` defaults to true — set to false to get the dry-run decision
+     * without mutating the entity (useful for the doctor surface).
+     */
+    evaluate(node: FederationNode, now?: Date, apply?: boolean): BreakerDecision;
+    /**
+     * Periodic tick — evaluate all known peers. Intended to be called from a
+     * timer or after each batch of outcomes. Returns the decisions for
+     * observability.
+     */
+    tick(nodes: readonly FederationNode[], now?: Date): BreakerDecision[];
+    /** Drop a peer's sample buffer (e.g. after reactivate or evict). */
+    forget(nodeId: string): void;
+    /**
+     * Snapshot of per-peer aggregates for the doctor surface. Pure read —
+     * does not mutate the buffer.
+     */
+    snapshot(nodeId: string, now?: Date): {
+        readonly nodeId: string;
+        readonly sampleCount: number;
+        readonly cumUsdInWindow: number;
+        readonly failureRatioInWindow: number | null;
+    };
+}
+export {};
+//# sourceMappingURL=federation-breaker-service.d.ts.map