@claude-flow/plugin-agent-federation 1.0.0-alpha.10

package/dist/domain/value-objects/federation-budget.js

@@ -0,0 +1,165 @@
+/**
+ * Federation budget + hop counter (ADR-097 Phase 1).
+ *
+ * Carried in {@link FederationEnvelope} alongside the existing
+ * sourceNodeId/targetNodeId/payload. Sender supplies the original limits;
+ * each outbound hop increments hopCount and decrements remaining budget.
+ *
+ * Phase 1 enforces at the *send* side because there is no inbound
+ * dispatcher today (sendToNode is a stub — see researcher report).
+ * Phase 2 will move the decrement to receive once the inbound path lands.
+ *
+ * Security invariants pinned by the reviewer (audit_1776853149979 follow-up):
+ *
+ *   1. validateBudget rejects NaN, ±Infinity, negative numbers, and
+ *      non-integer hop counts. Returns a discriminated result so callers
+ *      cannot accidentally use a bad budget unchecked.
+ *   2. enforceBudget runs check-then-decrement in a single synchronous
+ *      function with no awaits inside — two concurrent send calls cannot
+ *      both pass the pre-check.
+ *   3. Errors return constant strings ("HOP_LIMIT_EXCEEDED" /
+ *      "BUDGET_EXCEEDED") with no remaining-budget echo so a caller can't
+ *      use the error response as an oracle for the threshold.
+ */
+/** Maximum hops a federation message may travel before the breaker opens. */
+export const DEFAULT_MAX_HOPS = 8;
+/** Hard ceiling on caller-supplied maxUsd to prevent absurd integer math. */
+const MAX_USD_CEILING = 1_000_000;
+/** Hard ceiling on caller-supplied maxTokens. 1B tokens is more than any real session. */
+const MAX_TOKENS_CEILING = 1_000_000_000;
+/** Hard ceiling on hop count. */
+const MAX_HOPS_CEILING = 64;
+/**
+ * Validate a raw budget object. Pure, no side effects. Caller obtains either
+ * a guaranteed-safe Budget or a structured error suitable for logging.
+ *
+ * Accepts undefined/null and returns a default unbounded budget (maxHops =
+ * DEFAULT_MAX_HOPS, tokens/usd = Infinity). This preserves backward
+ * compatibility for callers that don't pass a budget at all.
+ */
+export function validateBudget(raw, overrideMaxHops) {
+    // Default unbounded budget when caller passes nothing.
+    if (raw == null && overrideMaxHops == null) {
+        return {
+            ok: true,
+            budget: {
+                maxHops: DEFAULT_MAX_HOPS,
+                maxTokens: Number.POSITIVE_INFINITY,
+                maxUsd: Number.POSITIVE_INFINITY,
+            },
+        };
+    }
+    // Caller passed a bare maxHops without a budget object — accept it as a
+    // hop-only budget. Useful for "no remote delegation allowed" via
+    // maxHops: 0.
+    if (raw == null && overrideMaxHops != null) {
+        const hopCheck = checkHops(overrideMaxHops);
+        if (!hopCheck.ok)
+            return hopCheck;
+        return {
+            ok: true,
+            budget: {
+                maxHops: hopCheck.value,
+                maxTokens: Number.POSITIVE_INFINITY,
+                maxUsd: Number.POSITIVE_INFINITY,
+            },
+        };
+    }
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        return { ok: false, error: 'budget must be an object' };
+    }
+    const obj = raw;
+    const hopsRaw = overrideMaxHops ?? obj.maxHops;
+    const hopCheck = hopsRaw == null
+        ? { ok: true, value: DEFAULT_MAX_HOPS }
+        : checkHops(hopsRaw);
+    if (!hopCheck.ok)
+        return hopCheck;
+    const tokensCheck = obj.maxTokens == null
+        ? { ok: true, value: Number.POSITIVE_INFINITY }
+        : checkBound(obj.maxTokens, MAX_TOKENS_CEILING, 'maxTokens', true);
+    if (!tokensCheck.ok)
+        return tokensCheck;
+    const usdCheck = obj.maxUsd == null
+        ? { ok: true, value: Number.POSITIVE_INFINITY }
+        : checkBound(obj.maxUsd, MAX_USD_CEILING, 'maxUsd', false);
+    if (!usdCheck.ok)
+        return usdCheck;
+    return {
+        ok: true,
+        budget: {
+            maxHops: hopCheck.value,
+            maxTokens: tokensCheck.value,
+            maxUsd: usdCheck.value,
+        },
+    };
+}
+function checkHops(v) {
+    if (typeof v !== 'number' || !Number.isFinite(v) || !Number.isInteger(v)) {
+        return { ok: false, error: 'maxHops must be a finite integer' };
+    }
+    if (v < 0)
+        return { ok: false, error: 'maxHops must be >= 0' };
+    if (v > MAX_HOPS_CEILING) {
+        return { ok: false, error: `maxHops exceeds ceiling (${MAX_HOPS_CEILING})` };
+    }
+    return { ok: true, value: v };
+}
+function checkBound(v, ceiling, label, requireInteger) {
+    if (typeof v !== 'number' || !Number.isFinite(v)) {
+        return { ok: false, error: `${label} must be a finite number` };
+    }
+    if (requireInteger && !Number.isInteger(v)) {
+        return { ok: false, error: `${label} must be an integer` };
+    }
+    if (v < 0)
+        return { ok: false, error: `${label} must be >= 0` };
+    if (v > ceiling) {
+        return { ok: false, error: `${label} exceeds ceiling (${ceiling})` };
+    }
+    return { ok: true, value: v };
+}
+/**
+ * Atomic (single synchronous function, no internal awaits) hop check.
+ *
+ * Returns the hopCount value the OUTBOUND envelope should carry plus the
+ * remaining budget that downstream peers will see. Callers must use the
+ * returned values; mutating the input Budget is forbidden (it's readonly).
+ *
+ * Contract:
+ *   - hopCount represents how many hops the message has already taken.
+ *   - The next outbound hop increments it: nextHopCount = hopCount + 1.
+ *   - The check fires AFTER increment: nextHopCount must be <= maxHops.
+ *   - This means maxHops=0 refuses to forward at all, which matches the
+ *     ADR's "no remote delegation allowed" semantic.
+ *
+ * tokensSpent / usdSpent are caller-reported actuals from the immediately
+ * preceding leg (or 0 on the originator). The check fires on the
+ * *post-spend* totals so a leg that overshoots is caught before the next
+ * outbound dispatch.
+ */
+export function enforceBudget(budget, hopCount, spent = { tokens: 0, usd: 0 }) {
+    const nextHopCount = hopCount + 1;
+    if (nextHopCount > budget.maxHops) {
+        return { ok: false, reason: 'HOP_LIMIT_EXCEEDED' };
+    }
+    // Negative spend is a programming error; treat as 0 rather than refunding
+    // the budget (which would let a malicious caller inflate remaining).
+    const ts = Math.max(0, spent.tokens);
+    const us = Math.max(0, spent.usd);
+    const remainingTokens = budget.maxTokens - ts;
+    const remainingUsd = budget.maxUsd - us;
+    if (remainingTokens < 0 || remainingUsd < 0) {
+        return { ok: false, reason: 'BUDGET_EXCEEDED' };
+    }
+    return {
+        ok: true,
+        nextHopCount,
+        remaining: {
+            maxHops: budget.maxHops,
+            maxTokens: remainingTokens,
+            maxUsd: remainingUsd,
+        },
+    };
+}
+//# sourceMappingURL=federation-budget.js.map

package/dist/domain/value-objects/federation-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"federation-budget.js","sourceRoot":"","sources":["../../../src/domain/value-objects/federation-budget.ts"],"names":[],"mappings":"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"}

package/dist/domain/value-objects/federation-node-state.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Federation peer state machine (ADR-097 Phase 2).
+ *
+ * Phase 1 shipped the budget envelope + enforcer that travels with every
+ * outbound message. Phase 2 adds the per-peer breaker: when a peer crosses a
+ * cost or failure threshold, transition it to SUSPENDED so subsequent
+ * `federation_send` calls short-circuit. After a cooldown the peer can
+ * recover; if it stays bad the breaker escalates to EVICTED.
+ *
+ * This module is the *value object* layer — pure, no I/O. The breaker
+ * service (Phase 2.b, separate file) reads cost-tracker telemetry, evaluates
+ * thresholds, and calls `transition` on the FederationNode entity. Decoupling
+ * the state machine from the policy lets tests pin transitions without
+ * standing up the cost bus.
+ *
+ * Security invariants pinned by the spec:
+ *
+ *   1. EVICTED is terminal under normal flow. The only way out is an
+ *      explicit `reactivate` call (operator-initiated). This prevents a
+ *      misbehaving peer from auto-recovering through the cooldown.
+ *   2. canTransition is the single source of truth for legality. Any path
+ *      that mutates state MUST consult it; direct field writes are not
+ *      permitted (entity getter/setter shape enforces this).
+ *   3. Reasons are constant strings, no remaining-budget echo on failure
+ *      (matches Phase 1's anti-oracle posture).
+ *   4. Default cooldown is conservative (30 min) so a transient spike
+ *      cannot ping-pong a peer ACTIVE↔SUSPENDED at high frequency.
+ */
+/** Lifecycle state of a federation peer. */
+export declare enum FederationNodeState {
+    /** Default; healthy. `federation_send` accepts deliveries. */
+    ACTIVE = "ACTIVE",
+    /** Breaker tripped. Sends short-circuit with PEER_SUSPENDED. */
+    SUSPENDED = "SUSPENDED",
+    /** Removed from active rotation. Sends short-circuit with PEER_EVICTED. */
+    EVICTED = "EVICTED"
+}
+/** Reason a peer was suspended/evicted. Constant strings — no echo of caps. */
+export type SuspensionReason = 'COST_THRESHOLD_EXCEEDED' | 'FAILURE_RATIO_EXCEEDED' | 'MANUAL_SUSPEND' | 'GRACE_PERIOD_EXPIRED' | 'MANUAL_EVICT';
+/**
+ * Default cooldown a SUSPENDED peer must wait before being eligible for
+ * SUSPENDED → ACTIVE. 30 minutes matches the ADR-097 Part 2 spec and is
+ * intentionally well past the prompt-cache window so a recovery probe is
+ * cheap to amortize.
+ */
+export declare const DEFAULT_SUSPENSION_COOLDOWN_MS: number;
+/**
+ * Default age at which a continuously-SUSPENDED peer is auto-escalated to
+ * EVICTED. 24 hours per spec — long enough to ride out a cost-tracker
+ * outage without false eviction, short enough that a genuinely-broken peer
+ * doesn't linger forever.
+ */
+export declare const DEFAULT_AUTO_EVICTION_AGE_MS: number;
+/** A successful transition's reason payload (for the audit trail). */
+export interface TransitionReason {
+    readonly reason: SuspensionReason;
+    /** Optional opaque correlation key — task ID, breaker run ID, etc. */
+    readonly correlationId?: string;
+}
+/**
+ * Static legality table for state transitions. Returns true iff the
+ * `from -> to` edge is in the allowed set. Used by the entity to reject
+ * illegal mutations before applying them.
+ *
+ * Allowed edges:
+ *   ACTIVE    → SUSPENDED  (breaker trips)
+ *   SUSPENDED → ACTIVE     (cooldown + probe success)
+ *   SUSPENDED → EVICTED    (grace expired, or manual evict)
+ *   ACTIVE    → EVICTED    (manual evict only — skips suspend)
+ *   EVICTED   → ACTIVE     (manual reactivate only)
+ *
+ * Disallowed (anything else, including self-loops, is a no-op error).
+ */
+export declare function canTransition(from: FederationNodeState, to: FederationNodeState): boolean;
+/**
+ * Should a SUSPENDED peer be eligible for SUSPENDED → ACTIVE based purely
+ * on elapsed time? The breaker still has to confirm health via probe before
+ * it actually calls reactivate; this just answers "is the cooldown done?"
+ *
+ * Pure function of (suspendedAt, now, cooldownMs) so it's trivially
+ * deterministic in tests.
+ */
+export declare function isCooldownElapsed(suspendedAt: Date, now: Date, cooldownMs?: number): boolean;
+/**
+ * Should a SUSPENDED peer be auto-escalated to EVICTED based on the age of
+ * its suspension? Returns true once the peer has been continuously
+ * SUSPENDED past the configured limit (default 24h). The breaker calls
+ * this on each tick and, if true, issues the SUSPENDED → EVICTED
+ * transition with reason GRACE_PERIOD_EXPIRED.
+ */
+export declare function shouldAutoEvict(suspendedAt: Date, now: Date, ageLimitMs?: number): boolean;
+//# sourceMappingURL=federation-node-state.d.ts.map

package/dist/domain/value-objects/federation-node-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"federation-node-state.d.ts","sourceRoot":"","sources":["../../../src/domain/value-objects/federation-node-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,4CAA4C;AAC5C,oBAAY,mBAAmB;IAC7B,8DAA8D;IAC9D,MAAM,WAAW;IACjB,gEAAgE;IAChE,SAAS,cAAc;IACvB,2EAA2E;IAC3E,OAAO,YAAY;CACpB;AAED,+EAA+E;AAC/E,MAAM,MAAM,gBAAgB,GACxB,yBAAyB,GACzB,wBAAwB,GACxB,gBAAgB,GAChB,sBAAsB,GACtB,cAAc,CAAC;AAEnB;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,QAAiB,CAAC;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,QAAsB,CAAC;AAEhE,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,mBAAmB,EACzB,EAAE,EAAE,mBAAmB,GACtB,OAAO,CAUT;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,IAAI,EACjB,GAAG,EAAE,IAAI,EACT,UAAU,GAAE,MAAuC,GAClD,OAAO,CAET;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,IAAI,EACjB,GAAG,EAAE,IAAI,EACT,UAAU,GAAE,MAAqC,GAChD,OAAO,CAET"}

package/dist/domain/value-objects/federation-node-state.js

@@ -0,0 +1,100 @@
+/**
+ * Federation peer state machine (ADR-097 Phase 2).
+ *
+ * Phase 1 shipped the budget envelope + enforcer that travels with every
+ * outbound message. Phase 2 adds the per-peer breaker: when a peer crosses a
+ * cost or failure threshold, transition it to SUSPENDED so subsequent
+ * `federation_send` calls short-circuit. After a cooldown the peer can
+ * recover; if it stays bad the breaker escalates to EVICTED.
+ *
+ * This module is the *value object* layer — pure, no I/O. The breaker
+ * service (Phase 2.b, separate file) reads cost-tracker telemetry, evaluates
+ * thresholds, and calls `transition` on the FederationNode entity. Decoupling
+ * the state machine from the policy lets tests pin transitions without
+ * standing up the cost bus.
+ *
+ * Security invariants pinned by the spec:
+ *
+ *   1. EVICTED is terminal under normal flow. The only way out is an
+ *      explicit `reactivate` call (operator-initiated). This prevents a
+ *      misbehaving peer from auto-recovering through the cooldown.
+ *   2. canTransition is the single source of truth for legality. Any path
+ *      that mutates state MUST consult it; direct field writes are not
+ *      permitted (entity getter/setter shape enforces this).
+ *   3. Reasons are constant strings, no remaining-budget echo on failure
+ *      (matches Phase 1's anti-oracle posture).
+ *   4. Default cooldown is conservative (30 min) so a transient spike
+ *      cannot ping-pong a peer ACTIVE↔SUSPENDED at high frequency.
+ */
+/** Lifecycle state of a federation peer. */
+export var FederationNodeState;
+(function (FederationNodeState) {
+    /** Default; healthy. `federation_send` accepts deliveries. */
+    FederationNodeState["ACTIVE"] = "ACTIVE";
+    /** Breaker tripped. Sends short-circuit with PEER_SUSPENDED. */
+    FederationNodeState["SUSPENDED"] = "SUSPENDED";
+    /** Removed from active rotation. Sends short-circuit with PEER_EVICTED. */
+    FederationNodeState["EVICTED"] = "EVICTED";
+})(FederationNodeState || (FederationNodeState = {}));
+/**
+ * Default cooldown a SUSPENDED peer must wait before being eligible for
+ * SUSPENDED → ACTIVE. 30 minutes matches the ADR-097 Part 2 spec and is
+ * intentionally well past the prompt-cache window so a recovery probe is
+ * cheap to amortize.
+ */
+export const DEFAULT_SUSPENSION_COOLDOWN_MS = 30 * 60 * 1000;
+/**
+ * Default age at which a continuously-SUSPENDED peer is auto-escalated to
+ * EVICTED. 24 hours per spec — long enough to ride out a cost-tracker
+ * outage without false eviction, short enough that a genuinely-broken peer
+ * doesn't linger forever.
+ */
+export const DEFAULT_AUTO_EVICTION_AGE_MS = 24 * 60 * 60 * 1000;
+/**
+ * Static legality table for state transitions. Returns true iff the
+ * `from -> to` edge is in the allowed set. Used by the entity to reject
+ * illegal mutations before applying them.
+ *
+ * Allowed edges:
+ *   ACTIVE    → SUSPENDED  (breaker trips)
+ *   SUSPENDED → ACTIVE     (cooldown + probe success)
+ *   SUSPENDED → EVICTED    (grace expired, or manual evict)
+ *   ACTIVE    → EVICTED    (manual evict only — skips suspend)
+ *   EVICTED   → ACTIVE     (manual reactivate only)
+ *
+ * Disallowed (anything else, including self-loops, is a no-op error).
+ */
+export function canTransition(from, to) {
+    if (from === to)
+        return false;
+    if (from === FederationNodeState.ACTIVE) {
+        return to === FederationNodeState.SUSPENDED || to === FederationNodeState.EVICTED;
+    }
+    if (from === FederationNodeState.SUSPENDED) {
+        return to === FederationNodeState.ACTIVE || to === FederationNodeState.EVICTED;
+    }
+    // EVICTED is terminal except for explicit operator reactivate.
+    return to === FederationNodeState.ACTIVE;
+}
+/**
+ * Should a SUSPENDED peer be eligible for SUSPENDED → ACTIVE based purely
+ * on elapsed time? The breaker still has to confirm health via probe before
+ * it actually calls reactivate; this just answers "is the cooldown done?"
+ *
+ * Pure function of (suspendedAt, now, cooldownMs) so it's trivially
+ * deterministic in tests.
+ */
+export function isCooldownElapsed(suspendedAt, now, cooldownMs = DEFAULT_SUSPENSION_COOLDOWN_MS) {
+    return now.getTime() - suspendedAt.getTime() >= cooldownMs;
+}
+/**
+ * Should a SUSPENDED peer be auto-escalated to EVICTED based on the age of
+ * its suspension? Returns true once the peer has been continuously
+ * SUSPENDED past the configured limit (default 24h). The breaker calls
+ * this on each tick and, if true, issues the SUSPENDED → EVICTED
+ * transition with reason GRACE_PERIOD_EXPIRED.
+ */
+export function shouldAutoEvict(suspendedAt, now, ageLimitMs = DEFAULT_AUTO_EVICTION_AGE_MS) {
+    return now.getTime() - suspendedAt.getTime() >= ageLimitMs;
+}
+//# sourceMappingURL=federation-node-state.js.map

package/dist/domain/value-objects/federation-node-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"federation-node-state.js","sourceRoot":"","sources":["../../../src/domain/value-objects/federation-node-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,4CAA4C;AAC5C,MAAM,CAAN,IAAY,mBAOX;AAPD,WAAY,mBAAmB;IAC7B,8DAA8D;IAC9D,wCAAiB,CAAA;IACjB,gEAAgE;IAChE,8CAAuB,CAAA;IACvB,2EAA2E;IAC3E,0CAAmB,CAAA;AACrB,CAAC,EAPW,mBAAmB,KAAnB,mBAAmB,QAO9B;AAUD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAShE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAyB,EACzB,EAAuB;IAEvB,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAC9B,IAAI,IAAI,KAAK,mBAAmB,CAAC,MAAM,EAAE,CAAC;QACxC,OAAO,EAAE,KAAK,mBAAmB,CAAC,SAAS,IAAI,EAAE,KAAK,mBAAmB,CAAC,OAAO,CAAC;IACpF,CAAC;IACD,IAAI,IAAI,KAAK,mBAAmB,CAAC,SAAS,EAAE,CAAC;QAC3C,OAAO,EAAE,KAAK,mBAAmB,CAAC,MAAM,IAAI,EAAE,KAAK,mBAAmB,CAAC,OAAO,CAAC;IACjF,CAAC;IACD,+DAA+D;IAC/D,OAAO,EAAE,KAAK,mBAAmB,CAAC,MAAM,CAAC;AAC3C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,WAAiB,EACjB,GAAS,EACT,aAAqB,8BAA8B;IAEnD,OAAO,GAAG,CAAC,OAAO,EAAE,GAAG,WAAW,CAAC,OAAO,EAAE,IAAI,UAAU,CAAC;AAC7D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,WAAiB,EACjB,GAAS,EACT,aAAqB,4BAA4B;IAEjD,OAAO,GAAG,CAAC,OAAO,EAAE,GAAG,WAAW,CAAC,OAAO,EAAE,IAAI,UAAU,CAAC;AAC7D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export { AgentFederationPlugin } from './plugin.js';
+export { FederationNode, type FederationNodeProps, type FederationNodeCapabilities, type FederationNodeMetadata, type FederationNodeStateRecord } from './domain/entities/federation-node.js';
+export { FederationNodeState, type SuspensionReason, type TransitionReason, canTransition, isCooldownElapsed, shouldAutoEvict, DEFAULT_SUSPENSION_COOLDOWN_MS, DEFAULT_AUTO_EVICTION_AGE_MS, } from './domain/value-objects/federation-node-state.js';
+export { FederationBreakerService, evaluatePolicy, DEFAULT_BREAKER_POLICY, DEFAULT_MAX_SAMPLES_PER_PEER, type BreakerPolicy, type BreakerDecision, type SendOutcome, } from './application/federation-breaker-service.js';
+export { InMemorySpendReporter, MemorySpendReporter, DEFAULT_FEDERATION_SPEND_NAMESPACE, DEFAULT_FEDERATION_SPEND_TTL_SECONDS, type SpendReporter, type MemoryStore, type MemorySpendReporterConfig, type FederationSpendEvent, } from './application/spend-reporter.js';
+export { FederationSession, type FederationSessionProps, type SessionMetrics } from './domain/entities/federation-session.js';
+export { FederationEnvelope, type FederationEnvelopeProps, type FederationMessageType, type PIIScanResult, type PIIScanDetection, type PIIScanAction, CONSENSUS_REQUIRED_TYPES, } from './domain/entities/federation-envelope.js';
+export { TrustLevel, TRUST_TRANSITION_THRESHOLDS, CAPABILITY_GATES, isOperationAllowed, getTrustLevelLabel, type TrustTransitionThreshold, } from './domain/entities/trust-level.js';
+export { PIIPipelineService, type PIIType, type PIIAction, type PIIDetection, type PIIPolicyConfig, type PIICalibration, type PIITransformResult, type PIIConfidenceThresholds, type PIIPipelineServiceDeps, } from './domain/services/pii-pipeline-service.js';
+export { DiscoveryService, type DiscoveryMechanism, type FederationManifest, type DiscoveryServiceDeps, type DiscoveryConfig, } from './domain/services/discovery-service.js';
+export { HandshakeService, type HandshakeChallenge, type HandshakeChallengeResponse, type HandshakeResult, type HandshakeServiceDeps, type HandshakeConfig, } from './domain/services/handshake-service.js';
+export { RoutingService, type RoutingMode, type RoutingResult, type ConsensusProposal, type RoutingServiceDeps, } from './domain/services/routing-service.js';
+export { AuditService, type FederationAuditEvent, type FederationAuditEventType, type AuditSeverity, type AuditCategory, type ComplianceMode, type AuditQuery, type AuditExportFormat, type AuditServiceDeps, type AuditServiceConfig, } from './domain/services/audit-service.js';
+export { TrustEvaluator, type TrustScoreComponents, type TrustTransitionResult, type ImmediateDowngradeReason, type TrustEvaluatorDeps, } from './application/trust-evaluator.js';
+export { FederationCoordinator, type FederationCoordinatorConfig, type FederationStatus, } from './application/federation-coordinator.js';
+export { PolicyEngine, type FederationClaimType, type SecurityPolicy, type PolicyEvaluationResult, type PolicyEngineDeps, } from './application/policy-engine.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,KAAK,0BAA0B,EAAE,KAAK,sBAAsB,EAAE,KAAK,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AAC9L,OAAO,EACL,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,8BAA8B,EAC9B,4BAA4B,GAC7B,MAAM,iDAAiD,CAAC;AACzD,OAAO,EACL,wBAAwB,EACxB,cAAc,EACd,sBAAsB,EACtB,4BAA4B,EAC5B,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,WAAW,GACjB,MAAM,6CAA6C,CAAC;AACrD,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,kCAAkC,EAClC,oCAAoC,EACpC,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,GAC1B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,KAAK,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAC9H,OAAO,EACL,kBAAkB,EAClB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,wBAAwB,GACzB,MAAM,0CAA0C,CAAC;AAClD,OAAO,EACL,UAAU,EACV,2BAA2B,EAC3B,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,wBAAwB,GAC9B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,kBAAkB,EAClB,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,GAC5B,MAAM,2CAA2C,CAAC;AACnD,OAAO,EACL,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,0BAA0B,EAC/B,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACxB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EACL,YAAY,EACZ,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EACL,cAAc,EACd,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,GACxB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,qBAAqB,EACrB,KAAK,2BAA2B,EAChC,KAAK,gBAAgB,GACtB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,YAAY,EACZ,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,GACtB,MAAM,gCAAgC,CAAC"}

package/dist/index.js

@@ -0,0 +1,17 @@
+export { AgentFederationPlugin } from './plugin.js';
+export { FederationNode } from './domain/entities/federation-node.js';
+export { FederationNodeState, canTransition, isCooldownElapsed, shouldAutoEvict, DEFAULT_SUSPENSION_COOLDOWN_MS, DEFAULT_AUTO_EVICTION_AGE_MS, } from './domain/value-objects/federation-node-state.js';
+export { FederationBreakerService, evaluatePolicy, DEFAULT_BREAKER_POLICY, DEFAULT_MAX_SAMPLES_PER_PEER, } from './application/federation-breaker-service.js';
+export { InMemorySpendReporter, MemorySpendReporter, DEFAULT_FEDERATION_SPEND_NAMESPACE, DEFAULT_FEDERATION_SPEND_TTL_SECONDS, } from './application/spend-reporter.js';
+export { FederationSession } from './domain/entities/federation-session.js';
+export { FederationEnvelope, CONSENSUS_REQUIRED_TYPES, } from './domain/entities/federation-envelope.js';
+export { TrustLevel, TRUST_TRANSITION_THRESHOLDS, CAPABILITY_GATES, isOperationAllowed, getTrustLevelLabel, } from './domain/entities/trust-level.js';
+export { PIIPipelineService, } from './domain/services/pii-pipeline-service.js';
+export { DiscoveryService, } from './domain/services/discovery-service.js';
+export { HandshakeService, } from './domain/services/handshake-service.js';
+export { RoutingService, } from './domain/services/routing-service.js';
+export { AuditService, } from './domain/services/audit-service.js';
+export { TrustEvaluator, } from './application/trust-evaluator.js';
+export { FederationCoordinator, } from './application/federation-coordinator.js';
+export { PolicyEngine, } from './application/policy-engine.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EAAE,cAAc,EAA0H,MAAM,sCAAsC,CAAC;AAC9L,OAAO,EACL,mBAAmB,EAGnB,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,8BAA8B,EAC9B,4BAA4B,GAC7B,MAAM,iDAAiD,CAAC;AACzD,OAAO,EACL,wBAAwB,EACxB,cAAc,EACd,sBAAsB,EACtB,4BAA4B,GAI7B,MAAM,6CAA6C,CAAC;AACrD,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,kCAAkC,EAClC,oCAAoC,GAKrC,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAoD,MAAM,yCAAyC,CAAC;AAC9H,OAAO,EACL,kBAAkB,EAMlB,wBAAwB,GACzB,MAAM,0CAA0C,CAAC;AAClD,OAAO,EACL,UAAU,EACV,2BAA2B,EAC3B,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,GAEnB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,kBAAkB,GASnB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EACL,gBAAgB,GAKjB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,gBAAgB,GAMjB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,cAAc,GAKf,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EACL,YAAY,GAUb,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EACL,cAAc,GAKf,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,qBAAqB,GAGtB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,YAAY,GAKb,MAAM,gCAAgC,CAAC"}

package/dist/mcp-tools.d.ts

@@ -0,0 +1,8 @@
+import type { MCPToolDefinition } from '@claude-flow/shared/src/plugin-interface.js';
+import type { PluginContext } from '@claude-flow/shared/src/plugin-interface.js';
+import type { FederationCoordinator } from './application/federation-coordinator.js';
+type CoordinatorGetter = () => FederationCoordinator | null;
+type ContextGetter = () => PluginContext | null;
+export declare function createMcpTools(getCoordinator: CoordinatorGetter, getContext: ContextGetter): MCPToolDefinition[];
+export {};
+//# sourceMappingURL=mcp-tools.d.ts.map

package/dist/mcp-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tools.d.ts","sourceRoot":"","sources":["../src/mcp-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AACjF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AAGrF,KAAK,iBAAiB,GAAG,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAC5D,KAAK,aAAa,GAAG,MAAM,aAAa,GAAG,IAAI,CAAC;AAMhD,wBAAgB,cAAc,CAC5B,cAAc,EAAE,iBAAiB,EACjC,UAAU,EAAE,aAAa,GACxB,iBAAiB,EAAE,CAoWrB"}