@clawcrony/claw-crony 1.0.1

package/dist/src/peer-health.js

@@ -0,0 +1,169 @@
+/**
+ * Manages per-peer health checks and circuit breaker state.
+ *
+ * Health checks periodically probe each peer's Agent Card endpoint.
+ * The circuit breaker follows the standard three-state pattern:
+ *   closed → open → half-open → closed
+ */
+export class PeerHealthManager {
+    states = new Map();
+    peers;
+    healthConfig;
+    cbConfig;
+    probe;
+    log;
+    timer = null;
+    halfOpenInFlight = new Set();
+    /** Cached skills per peer, refreshed on each successful health check probe. */
+    peerSkills = new Map();
+    constructor(peers, healthConfig, cbConfig, probe, log) {
+        this.peers = peers;
+        this.healthConfig = healthConfig;
+        this.cbConfig = cbConfig;
+        this.probe = probe;
+        this.log = log;
+        // Initialize state for each peer
+        for (const peer of peers) {
+            this.states.set(peer.name, {
+                health: "unknown",
+                circuit: "closed",
+                consecutiveFailures: 0,
+                lastFailureAt: null,
+                lastCheckAt: null,
+            });
+        }
+    }
+    /** Start periodic health checks. */
+    start() {
+        if (!this.healthConfig.enabled || this.peers.length === 0)
+            return;
+        this.log("info", "peer.health.start", {
+            peers: this.peers.map((p) => p.name),
+            interval_ms: this.healthConfig.intervalMs,
+        });
+        // Run immediately, then on interval
+        this.runHealthChecks();
+        this.timer = setInterval(() => this.runHealthChecks(), this.healthConfig.intervalMs);
+    }
+    /** Stop periodic health checks. */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /** Check if a peer is available for requests (circuit is not open). */
+    isAvailable(peerName) {
+        const state = this.states.get(peerName);
+        if (!state)
+            return true; // Unknown peer → allow (fail at send)
+        if (state.circuit === "closed")
+            return true;
+        if (state.circuit === "open") {
+            // Check if cooldown has elapsed → transition to half-open
+            if (state.lastFailureAt &&
+                Date.now() - state.lastFailureAt >= this.cbConfig.resetTimeoutMs) {
+                state.circuit = "half-open";
+                this.halfOpenInFlight.add(peerName); // Only one probe allowed
+                this.log("info", "peer.circuit.half-open", { peer: peerName });
+                return true;
+            }
+            return false;
+        }
+        // half-open: allow one request at a time
+        if (this.halfOpenInFlight.has(peerName))
+            return false;
+        this.halfOpenInFlight.add(peerName);
+        return true;
+    }
+    /** Record a successful call to a peer. */
+    recordSuccess(peerName) {
+        const state = this.states.get(peerName);
+        if (!state)
+            return;
+        const prevCircuit = state.circuit;
+        state.consecutiveFailures = 0;
+        state.health = "healthy";
+        this.halfOpenInFlight.delete(peerName);
+        if (state.circuit !== "closed") {
+            state.circuit = "closed";
+            this.log("info", "peer.circuit.closed", {
+                peer: peerName,
+                previous: prevCircuit,
+            });
+        }
+    }
+    /** Record a failed call to a peer. May trigger circuit open. */
+    recordFailure(peerName) {
+        const state = this.states.get(peerName);
+        if (!state)
+            return;
+        state.consecutiveFailures += 1;
+        state.lastFailureAt = Date.now();
+        this.halfOpenInFlight.delete(peerName);
+        // half-open failure → back to open
+        if (state.circuit === "half-open") {
+            state.circuit = "open";
+            this.log("warn", "peer.circuit.open", {
+                peer: peerName,
+                reason: "half-open probe failed",
+                consecutive_failures: state.consecutiveFailures,
+            });
+            return;
+        }
+        // closed: check threshold
+        if (state.circuit === "closed" &&
+            state.consecutiveFailures >= this.cbConfig.failureThreshold) {
+            state.circuit = "open";
+            state.health = "unhealthy";
+            this.log("warn", "peer.circuit.open", {
+                peer: peerName,
+                reason: "failure threshold reached",
+                consecutive_failures: state.consecutiveFailures,
+            });
+        }
+    }
+    /** Get state for a single peer. */
+    getState(peerName) {
+        return this.states.get(peerName);
+    }
+    /** Get states for all peers. */
+    getAllStates() {
+        return new Map(this.states);
+    }
+    /** Get cached skills for all peers (populated during health checks). */
+    getPeerSkills() {
+        return new Map(this.peerSkills);
+    }
+    /** Update cached skills for a peer (called by the health probe). */
+    setPeerSkills(peerName, skills) {
+        this.peerSkills.set(peerName, skills);
+    }
+    /** Run health checks for all peers. */
+    runHealthChecks() {
+        for (const peer of this.peers) {
+            this.checkPeer(peer).catch((err) => {
+                this.log("error", "peer.health.check-error", {
+                    peer: peer.name,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+        }
+    }
+    /** Probe a single peer and update its state. */
+    async checkPeer(peer) {
+        const state = this.states.get(peer.name);
+        if (!state)
+            return;
+        const healthy = await this.probe(peer);
+        state.lastCheckAt = Date.now();
+        if (healthy) {
+            this.recordSuccess(peer.name);
+        }
+        else {
+            state.health = "unhealthy";
+            this.recordFailure(peer.name);
+        }
+    }
+}
+//# sourceMappingURL=peer-health.js.map

package/dist/src/peer-health.js.map

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

package/dist/src/peer-retry.d.ts

@@ -0,0 +1,16 @@
+import type { RetryConfig, OutboundSendResult } from "./types.js";
+type LogFn = (level: "info" | "warn", msg: string, details?: Record<string, unknown>) => void;
+/**
+ * Determine whether an error or failed result is retryable.
+ * Delegates to isRetryableTransportError for comprehensive transport-level error classification.
+ */
+export declare function isRetryable(errorOrResult: unknown): boolean;
+/**
+ * Wrap an async operation with configurable retry + exponential backoff.
+ *
+ * The function `fn` should throw on network errors or return an
+ * OutboundSendResult. Non-retryable failures are returned immediately.
+ */
+export declare function withRetry(fn: () => Promise<OutboundSendResult>, config: RetryConfig, log?: LogFn, peerName?: string): Promise<OutboundSendResult>;
+export {};
+//# sourceMappingURL=peer-retry.d.ts.map

package/dist/src/peer-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-retry.d.ts","sourceRoot":"","sources":["../../src/peer-retry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGlE,KAAK,KAAK,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;AAE9F;;;GAGG;AACH,wBAAgB,WAAW,CAAC,aAAa,EAAE,OAAO,GAAG,OAAO,CAa3D;AAeD;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,EAAE,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,EACrC,MAAM,EAAE,WAAW,EACnB,GAAG,CAAC,EAAE,KAAK,EACX,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,kBAAkB,CAAC,CA6C7B"}

package/dist/src/peer-retry.js

@@ -0,0 +1,75 @@
+import { isRetryableTransportError } from "./transport-fallback.js";
+/**
+ * Determine whether an error or failed result is retryable.
+ * Delegates to isRetryableTransportError for comprehensive transport-level error classification.
+ */
+export function isRetryable(errorOrResult) {
+    if (errorOrResult &&
+        typeof errorOrResult === "object" &&
+        "ok" in errorOrResult &&
+        "statusCode" in errorOrResult) {
+        const result = errorOrResult;
+        if (result.ok)
+            return false;
+        return isRetryableTransportError(result);
+    }
+    return isRetryableTransportError(errorOrResult);
+}
+/**
+ * Calculate delay with exponential backoff + jitter.
+ */
+function calcDelay(attempt, config) {
+    const exponential = Math.min(config.baseDelayMs * Math.pow(2, attempt), config.maxDelayMs);
+    // Add 0–10% jitter to prevent thundering herd
+    const jitter = Math.random() * exponential * 0.1;
+    return exponential + jitter;
+}
+/**
+ * Wrap an async operation with configurable retry + exponential backoff.
+ *
+ * The function `fn` should throw on network errors or return an
+ * OutboundSendResult. Non-retryable failures are returned immediately.
+ */
+export async function withRetry(fn, config, log, peerName) {
+    let lastResult;
+    for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+        try {
+            const result = await fn();
+            // Success → return immediately
+            if (result.ok)
+                return result;
+            // Non-retryable failure → return immediately
+            if (!isRetryable(result))
+                return result;
+            lastResult = result;
+        }
+        catch (error) {
+            if (!isRetryable(error)) {
+                return {
+                    ok: false,
+                    statusCode: 500,
+                    response: { error: error instanceof Error ? error.message : String(error) },
+                };
+            }
+            lastResult = {
+                ok: false,
+                statusCode: 500,
+                response: { error: error instanceof Error ? error.message : String(error) },
+            };
+        }
+        // If we have retries left, wait before the next attempt
+        if (attempt < config.maxRetries) {
+            const delay = calcDelay(attempt, config);
+            log?.("warn", "peer.retry", {
+                peer: peerName,
+                attempt: attempt + 1,
+                max_retries: config.maxRetries,
+                delay_ms: Math.round(delay),
+            });
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+    // All retries exhausted
+    return lastResult;
+}
+//# sourceMappingURL=peer-retry.js.map

package/dist/src/peer-retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-retry.js","sourceRoot":"","sources":["../../src/peer-retry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AAIpE;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,aAAsB;IAChD,IACE,aAAa;QACb,OAAO,aAAa,KAAK,QAAQ;QACjC,IAAI,IAAI,aAAa;QACrB,YAAY,IAAI,aAAa,EAC7B,CAAC;QACD,MAAM,MAAM,GAAG,aAAmC,CAAC;QACnD,IAAI,MAAM,CAAC,EAAE;YAAE,OAAO,KAAK,CAAC;QAC5B,OAAO,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO,yBAAyB,CAAC,aAAa,CAAC,CAAC;AAClD,CAAC;AAED;;GAEG;AACH,SAAS,SAAS,CAAC,OAAe,EAAE,MAAmB;IACrD,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAC1B,MAAM,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,EACzC,MAAM,CAAC,UAAU,CAClB,CAAC;IACF,8CAA8C;IAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,WAAW,GAAG,GAAG,CAAC;IACjD,OAAO,WAAW,GAAG,MAAM,CAAC;AAC9B,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAqC,EACrC,MAAmB,EACnB,GAAW,EACX,QAAiB;IAEjB,IAAI,UAA0C,CAAC;IAE/C,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,MAAM,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QAC9D,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;YAE1B,+BAA+B;YAC/B,IAAI,MAAM,CAAC,EAAE;gBAAE,OAAO,MAAM,CAAC;YAE7B,6CAA6C;YAC7C,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC;gBAAE,OAAO,MAAM,CAAC;YAExC,UAAU,GAAG,MAAM,CAAC;QACtB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;gBACxB,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,UAAU,EAAE,GAAG;oBACf,QAAQ,EAAE,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;iBAC5E,CAAC;YACJ,CAAC;YAED,UAAU,GAAG;gBACX,EAAE,EAAE,KAAK;gBACT,UAAU,EAAE,GAAG;gBACf,QAAQ,EAAE,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;aAC5E,CAAC;QACJ,CAAC;QAED,wDAAwD;QACxD,IAAI,OAAO,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;YAChC,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YACzC,GAAG,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE;gBAC1B,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,OAAO,GAAG,CAAC;gBACpB,WAAW,EAAE,MAAM,CAAC,UAAU;gBAC9B,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;aAC5B,CAAC,CAAC;YACH,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IAED,wBAAwB;IACxB,OAAO,UAAW,CAAC;AACrB,CAAC"}

package/dist/src/queueing-executor.d.ts

@@ -0,0 +1,23 @@
+import type { AgentExecutor, ExecutionEventBus, RequestContext } from "@a2a-js/sdk/server";
+import { GatewayTelemetry } from "./telemetry.js";
+interface QueueingExecutorOptions {
+    maxConcurrentTasks: number;
+    maxQueuedTasks: number;
+}
+export declare class QueueingAgentExecutor implements AgentExecutor {
+    private readonly delegate;
+    private readonly telemetry;
+    private readonly options;
+    private readonly queue;
+    private readonly pendingByTaskId;
+    private activeTasks;
+    constructor(delegate: AgentExecutor, telemetry: GatewayTelemetry, options: QueueingExecutorOptions);
+    execute(requestContext: RequestContext, eventBus: ExecutionEventBus): Promise<void>;
+    cancelTask(taskId: string, eventBus: ExecutionEventBus): Promise<void>;
+    private runEntry;
+    private drainQueue;
+    private queueDelete;
+    private pickAgentId;
+}
+export {};
+//# sourceMappingURL=queueing-executor.d.ts.map

package/dist/src/queueing-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queueing-executor.d.ts","sourceRoot":"","sources":["../../src/queueing-executor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAEV,aAAa,EACb,iBAAiB,EACjB,cAAc,EACf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,UAAU,uBAAuB;IAC/B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;CACxB;AAwED,qBAAa,qBAAsB,YAAW,aAAa;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;IAC/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsC;IACtE,OAAO,CAAC,WAAW,CAAK;gBAEZ,QAAQ,EAAE,aAAa,EAAE,SAAS,EAAE,gBAAgB,EAAE,OAAO,EAAE,uBAAuB;IASlG,OAAO,CAAC,cAAc,EAAE,cAAc,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsD7E,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;YA0B9D,QAAQ;IAwEtB,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,WAAW;CAIpB"}

package/dist/src/queueing-executor.js

@@ -0,0 +1,179 @@
+import { v4 as uuidv4 } from "uuid";
+function statusMessage(contextId, text) {
+    return {
+        kind: "message",
+        messageId: uuidv4(),
+        role: "agent",
+        contextId,
+        parts: [{ kind: "text", text }],
+    };
+}
+function taskEvent(taskId, contextId, state, text) {
+    return {
+        kind: "task",
+        id: taskId,
+        contextId,
+        status: {
+            state,
+            message: text ? statusMessage(contextId, text) : undefined,
+            timestamp: new Date().toISOString(),
+        },
+    };
+}
+function createObservedEventBus(eventBus, observer) {
+    const wrapped = {
+        publish(event) {
+            observer(event);
+            eventBus.publish(event);
+        },
+        on(eventName, listener) {
+            eventBus.on(eventName, listener);
+            return wrapped;
+        },
+        off(eventName, listener) {
+            eventBus.off(eventName, listener);
+            return wrapped;
+        },
+        once(eventName, listener) {
+            eventBus.once(eventName, listener);
+            return wrapped;
+        },
+        removeAllListeners(eventName) {
+            eventBus.removeAllListeners(eventName);
+            return wrapped;
+        },
+        finished() {
+            eventBus.finished();
+        },
+    };
+    return wrapped;
+}
+export class QueueingAgentExecutor {
+    delegate;
+    telemetry;
+    options;
+    queue = [];
+    pendingByTaskId = new Map();
+    activeTasks = 0;
+    constructor(delegate, telemetry, options) {
+        this.delegate = delegate;
+        this.telemetry = telemetry;
+        this.options = {
+            maxConcurrentTasks: Math.max(1, options.maxConcurrentTasks),
+            maxQueuedTasks: Math.max(0, options.maxQueuedTasks),
+        };
+    }
+    execute(requestContext, eventBus) {
+        return new Promise((resolve, reject) => {
+            const entry = {
+                requestContext,
+                eventBus,
+                resolve,
+                reject,
+            };
+            this.pendingByTaskId.set(requestContext.taskId, entry);
+            if (this.activeTasks < this.options.maxConcurrentTasks) {
+                void this.runEntry(entry);
+                return;
+            }
+            if (this.queue.length >= this.options.maxQueuedTasks) {
+                this.pendingByTaskId.delete(requestContext.taskId);
+                this.telemetry.recordQueueRejected(requestContext.taskId, requestContext.contextId, this.queue.length);
+                eventBus.publish(taskEvent(requestContext.taskId, requestContext.contextId, "rejected", "Gateway is overloaded; queue limit reached"));
+                eventBus.finished();
+                resolve();
+                return;
+            }
+            this.queue.push(entry);
+            this.telemetry.recordTaskQueued(requestContext.taskId, requestContext.contextId, this.queue.length, this.queue.length);
+            eventBus.publish(taskEvent(requestContext.taskId, requestContext.contextId, "submitted", `Queued for execution (position ${this.queue.length})`));
+        });
+    }
+    async cancelTask(taskId, eventBus) {
+        const queuedIndex = this.queue.findIndex((entry) => entry.requestContext.taskId === taskId);
+        if (queuedIndex !== -1) {
+            const [entry] = this.queue.splice(queuedIndex, 1);
+            if (entry) {
+                this.pendingByTaskId.delete(taskId);
+                entry.eventBus.publish(taskEvent(taskId, entry.requestContext.contextId, "canceled", "Task canceled while queued"));
+                entry.eventBus.finished();
+                entry.resolve();
+                this.telemetry.recordTaskFinish(taskId, entry.requestContext.contextId, "canceled", 0, this.activeTasks, this.queue.length);
+            }
+            return;
+        }
+        await this.delegate.cancelTask(taskId, eventBus);
+    }
+    async runEntry(entry) {
+        const { requestContext } = entry;
+        const startedAt = Date.now();
+        let finalState;
+        let finalErrorMessage;
+        this.queueDelete(requestContext.taskId);
+        this.activeTasks += 1;
+        this.telemetry.recordTaskStart(requestContext.taskId, requestContext.contextId, this.pickAgentId(requestContext), this.activeTasks, this.queue.length);
+        const observedBus = createObservedEventBus(entry.eventBus, (event) => {
+            const status = event.kind === "task" || event.kind === "status-update" ? event.status : undefined;
+            if (!status) {
+                return;
+            }
+            if (status.state === "completed" ||
+                status.state === "failed" ||
+                status.state === "canceled" ||
+                status.state === "rejected") {
+                finalState = status.state;
+                if (status.state !== "completed") {
+                    finalErrorMessage =
+                        typeof status.message?.parts?.[0] === "object" && status.message.parts[0]?.kind === "text"
+                            ? status.message.parts[0].text
+                            : finalErrorMessage;
+                }
+            }
+        });
+        try {
+            await this.delegate.execute(requestContext, observedBus);
+            entry.resolve();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            finalState = finalState || "failed";
+            finalErrorMessage = finalErrorMessage || message;
+            entry.reject(error instanceof Error ? error : new Error(message));
+            return;
+        }
+        finally {
+            this.pendingByTaskId.delete(requestContext.taskId);
+            this.activeTasks = Math.max(0, this.activeTasks - 1);
+            this.telemetry.recordTaskFinish(requestContext.taskId, requestContext.contextId, finalState || "failed", Date.now() - startedAt, this.activeTasks, this.queue.length, finalErrorMessage);
+            // Ensure eventBus.finished() is always called so the SDK's
+            // DefaultRequestHandler does not hang waiting for the signal.
+            try {
+                entry.eventBus.finished();
+            }
+            catch {
+                // already finished — safe to ignore
+            }
+            this.drainQueue();
+        }
+    }
+    drainQueue() {
+        while (this.activeTasks < this.options.maxConcurrentTasks && this.queue.length > 0) {
+            const next = this.queue.shift();
+            if (!next) {
+                break;
+            }
+            void this.runEntry(next);
+        }
+    }
+    queueDelete(taskId) {
+        const index = this.queue.findIndex((entry) => entry.requestContext.taskId === taskId);
+        if (index !== -1) {
+            this.queue.splice(index, 1);
+        }
+    }
+    pickAgentId(requestContext) {
+        const message = requestContext.userMessage;
+        return typeof message?.agentId === "string" ? message.agentId : "default";
+    }
+}
+//# sourceMappingURL=queueing-executor.js.map

package/dist/src/queueing-executor.js.map

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

package/dist/src/routing-rules.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Rule-based routing — choose peer + agentId based on message content.
+ *
+ * Rules are evaluated at send-time in priority order (higher priority first).
+ * The first matching rule wins.
+ */
+export interface RoutingRule {
+    name: string;
+    match: {
+        /** Regex pattern to match against message text (case-insensitive). */
+        pattern?: string;
+        /** Match if message contains any of these tags (OR logic). */
+        tags?: string[];
+        /** Match if target peer has any of these skills. */
+        skills?: string[];
+    };
+    target: {
+        peer: string;
+        agentId?: string;
+    };
+    /** Higher = checked first (default: 0). */
+    priority?: number;
+}
+export interface RoutingMatch {
+    peer: string;
+    agentId?: string;
+}
+/**
+ * Parse and validate routing rules from raw config.
+ *
+ * Invalid entries (missing name, target.peer, or at least one match criterion)
+ * are silently dropped.
+ */
+export declare function parseRoutingRules(raw: unknown): RoutingRule[];
+/**
+ * Evaluate rules in priority order against a message.
+ *
+ * Match criteria within a single rule are AND-combined:
+ *   - pattern: regex test against message text
+ *   - tags: any overlap between message tags and rule tags
+ *   - skills: target peer advertises at least one required skill
+ *
+ * Returns the first match or null.
+ *
+ * The `peerSkills` map is populated from Agent Card discovery during
+ * periodic health checks. Skills are cached per peer and refreshed
+ * on each successful health check probe.
+ */
+export declare function matchRule(rules: RoutingRule[], message: {
+    text: string;
+    tags?: string[];
+}, peerSkills?: Map<string, string[]>): RoutingMatch | null;
+//# sourceMappingURL=routing-rules.d.ts.map

package/dist/src/routing-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-rules.d.ts","sourceRoot":"","sources":["../../src/routing-rules.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE;QACL,sEAAsE;QACtE,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,8DAA8D;QAC9D,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAChB,oDAAoD;QACpD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC;IACF,MAAM,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,EAAE,CAuD7D;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,WAAW,EAAE,EACpB,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,EAC1C,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GACjC,YAAY,GAAG,IAAI,CAWrB"}