@sw4rm/js-sdk 0.5.0 → 0.6.0

package/dist/esm/index.js

@@ -1857,25 +1857,25 @@ var require_codegen = __commonJS({
 var require_fetch = __commonJS({
   "node_modules/@protobufjs/fetch/index.js"(exports2, module2) {
     "use strict";
-    module2.exports = fetch;
+    module2.exports = fetch2;
     var asPromise = require_aspromise();
     var inquire2 = require_inquire();
-    var fs3 = inquire2("fs");
-    function fetch(filename, options, callback) {
+    var fs5 = inquire2("fs");
+    function fetch2(filename, options, callback) {
       if (typeof options === "function") {
         callback = options;
         options = {};
       } else if (!options)
         options = {};
       if (!callback)
-        return asPromise(fetch, this, filename, options);
-      if (!options.xhr && fs3 && fs3.readFile)
-        return fs3.readFile(filename, function fetchReadFileCallback(err, contents) {
-          return err && typeof XMLHttpRequest !== "undefined" ? fetch.xhr(filename, options, callback) : err ? callback(err) : callback(null, options.binary ? contents : contents.toString("utf8"));
+        return asPromise(fetch2, this, filename, options);
+      if (!options.xhr && fs5 && fs5.readFile)
+        return fs5.readFile(filename, function fetchReadFileCallback(err, contents) {
+          return err && typeof XMLHttpRequest !== "undefined" ? fetch2.xhr(filename, options, callback) : err ? callback(err) : callback(null, options.binary ? contents : contents.toString("utf8"));
         });
-      return fetch.xhr(filename, options, callback);
+      return fetch2.xhr(filename, options, callback);
     }
-    fetch.xhr = function fetch_xhr(filename, options, callback) {
+    fetch2.xhr = function fetch_xhr(filename, options, callback) {
       var xhr = new XMLHttpRequest();
       xhr.onreadystatechange = function fetchOnReadyStateChange() {
         if (xhr.readyState !== 4)
@@ -1908,15 +1908,15 @@ var require_fetch = __commonJS({
 var require_path = __commonJS({
   "node_modules/@protobufjs/path/index.js"(exports2) {
     "use strict";
-    var path5 = exports2;
+    var path7 = exports2;
     var isAbsolute = (
       /**
        * Tests if the specified path is absolute.
        * @param {string} path Path to test
        * @returns {boolean} `true` if path is absolute
        */
-      path5.isAbsolute = function isAbsolute2(path6) {
-        return /^(?:\/|\w+:)/.test(path6);
+      path7.isAbsolute = function isAbsolute2(path8) {
+        return /^(?:\/|\w+:)/.test(path8);
       }
     );
     var normalize = (
@@ -1925,9 +1925,9 @@ var require_path = __commonJS({
        * @param {string} path Path to normalize
        * @returns {string} Normalized path
        */
-      path5.normalize = function normalize2(path6) {
-        path6 = path6.replace(/\\/g, "/").replace(/\/{2,}/g, "/");
-        var parts = path6.split("/"), absolute = isAbsolute(path6), prefix = "";
+      path7.normalize = function normalize2(path8) {
+        path8 = path8.replace(/\\/g, "/").replace(/\/{2,}/g, "/");
+        var parts = path8.split("/"), absolute = isAbsolute(path8), prefix = "";
         if (absolute)
           prefix = parts.shift() + "/";
         for (var i = 0; i < parts.length; ) {
@@ -1946,7 +1946,7 @@ var require_path = __commonJS({
         return prefix + parts.join("/");
       }
     );
-    path5.resolve = function resolve(originPath, includePath, alreadyNormalized) {
+    path7.resolve = function resolve(originPath, includePath, alreadyNormalized) {
       if (!alreadyNormalized)
         includePath = normalize(includePath);
       if (isAbsolute(includePath))
@@ -2097,16 +2097,16 @@ var require_namespace = __commonJS({
       object.onRemove(this);
       return clearCache(this);
     };
-    Namespace.prototype.define = function define2(path5, json) {
-      if (util.isString(path5))
-        path5 = path5.split(".");
-      else if (!Array.isArray(path5))
+    Namespace.prototype.define = function define2(path7, json) {
+      if (util.isString(path7))
+        path7 = path7.split(".");
+      else if (!Array.isArray(path7))
         throw TypeError("illegal path");
-      if (path5 && path5.length && path5[0] === "")
+      if (path7 && path7.length && path7[0] === "")
         throw Error("path must be relative");
       var ptr = this;
-      while (path5.length > 0) {
-        var part = path5.shift();
+      while (path7.length > 0) {
+        var part = path7.shift();
         if (ptr.nested && ptr.nested[part]) {
           ptr = ptr.nested[part];
           if (!(ptr instanceof Namespace))
@@ -2143,26 +2143,26 @@ var require_namespace = __commonJS({
       });
       return this;
     };
-    Namespace.prototype.lookup = function lookup(path5, filterTypes, parentAlreadyChecked) {
+    Namespace.prototype.lookup = function lookup(path7, filterTypes, parentAlreadyChecked) {
       if (typeof filterTypes === "boolean") {
         parentAlreadyChecked = filterTypes;
         filterTypes = void 0;
       } else if (filterTypes && !Array.isArray(filterTypes))
         filterTypes = [filterTypes];
-      if (util.isString(path5) && path5.length) {
-        if (path5 === ".")
+      if (util.isString(path7) && path7.length) {
+        if (path7 === ".")
           return this.root;
-        path5 = path5.split(".");
-      } else if (!path5.length)
+        path7 = path7.split(".");
+      } else if (!path7.length)
         return this;
-      var flatPath = path5.join(".");
-      if (path5[0] === "")
-        return this.root.lookup(path5.slice(1), filterTypes);
+      var flatPath = path7.join(".");
+      if (path7[0] === "")
+        return this.root.lookup(path7.slice(1), filterTypes);
       var found = this.root._fullyQualifiedObjects && this.root._fullyQualifiedObjects["." + flatPath];
       if (found && (!filterTypes || filterTypes.indexOf(found.constructor) > -1)) {
         return found;
       }
-      found = this._lookupImpl(path5, flatPath);
+      found = this._lookupImpl(path7, flatPath);
       if (found && (!filterTypes || filterTypes.indexOf(found.constructor) > -1)) {
         return found;
       }
@@ -2170,7 +2170,7 @@ var require_namespace = __commonJS({
         return null;
       var current = this;
       while (current.parent) {
-        found = current.parent._lookupImpl(path5, flatPath);
+        found = current.parent._lookupImpl(path7, flatPath);
         if (found && (!filterTypes || filterTypes.indexOf(found.constructor) > -1)) {
           return found;
         }
@@ -2178,49 +2178,49 @@ var require_namespace = __commonJS({
       }
       return null;
     };
-    Namespace.prototype._lookupImpl = function lookup(path5, flatPath) {
+    Namespace.prototype._lookupImpl = function lookup(path7, flatPath) {
       if (Object.prototype.hasOwnProperty.call(this._lookupCache, flatPath)) {
         return this._lookupCache[flatPath];
       }
-      var found = this.get(path5[0]);
+      var found = this.get(path7[0]);
       var exact = null;
       if (found) {
-        if (path5.length === 1) {
+        if (path7.length === 1) {
           exact = found;
         } else if (found instanceof Namespace) {
-          path5 = path5.slice(1);
-          exact = found._lookupImpl(path5, path5.join("."));
+          path7 = path7.slice(1);
+          exact = found._lookupImpl(path7, path7.join("."));
         }
       } else {
         for (var i = 0; i < this.nestedArray.length; ++i)
-          if (this._nestedArray[i] instanceof Namespace && (found = this._nestedArray[i]._lookupImpl(path5, flatPath)))
+          if (this._nestedArray[i] instanceof Namespace && (found = this._nestedArray[i]._lookupImpl(path7, flatPath)))
             exact = found;
       }
       this._lookupCache[flatPath] = exact;
       return exact;
     };
-    Namespace.prototype.lookupType = function lookupType(path5) {
-      var found = this.lookup(path5, [Type]);
+    Namespace.prototype.lookupType = function lookupType(path7) {
+      var found = this.lookup(path7, [Type]);
       if (!found)
-        throw Error("no such type: " + path5);
+        throw Error("no such type: " + path7);
       return found;
     };
-    Namespace.prototype.lookupEnum = function lookupEnum(path5) {
-      var found = this.lookup(path5, [Enum]);
+    Namespace.prototype.lookupEnum = function lookupEnum(path7) {
+      var found = this.lookup(path7, [Enum]);
       if (!found)
-        throw Error("no such Enum '" + path5 + "' in " + this);
+        throw Error("no such Enum '" + path7 + "' in " + this);
       return found;
     };
-    Namespace.prototype.lookupTypeOrEnum = function lookupTypeOrEnum(path5) {
-      var found = this.lookup(path5, [Type, Enum]);
+    Namespace.prototype.lookupTypeOrEnum = function lookupTypeOrEnum(path7) {
+      var found = this.lookup(path7, [Type, Enum]);
       if (!found)
-        throw Error("no such Type or Enum '" + path5 + "' in " + this);
+        throw Error("no such Type or Enum '" + path7 + "' in " + this);
       return found;
     };
-    Namespace.prototype.lookupService = function lookupService(path5) {
-      var found = this.lookup(path5, [Service]);
+    Namespace.prototype.lookupService = function lookupService(path7) {
+      var found = this.lookup(path7, [Service]);
       if (!found)
-        throw Error("no such Service '" + path5 + "' in " + this);
+        throw Error("no such Service '" + path7 + "' in " + this);
       return found;
     };
     Namespace._configure = function(Type_, Service_, Enum_) {
@@ -3366,12 +3366,12 @@ var require_root = __commonJS({
             if (parsed.imports) {
               for (; i2 < parsed.imports.length; ++i2)
                 if (resolved2 = getBundledFileName(parsed.imports[i2]) || self2.resolvePath(filename2, parsed.imports[i2]))
-                  fetch(resolved2);
+                  fetch2(resolved2);
             }
             if (parsed.weakImports) {
               for (i2 = 0; i2 < parsed.weakImports.length; ++i2)
                 if (resolved2 = getBundledFileName(parsed.weakImports[i2]) || self2.resolvePath(filename2, parsed.weakImports[i2]))
-                  fetch(resolved2, true);
+                  fetch2(resolved2, true);
             }
           }
         } catch (err) {
@@ -3381,7 +3381,7 @@ var require_root = __commonJS({
           finish(null, self2);
         }
       }
-      function fetch(filename2, weak) {
+      function fetch2(filename2, weak) {
         filename2 = getBundledFileName(filename2) || filename2;
         if (self2.files.indexOf(filename2) > -1) {
           return;
@@ -3433,7 +3433,7 @@ var require_root = __commonJS({
       }
       for (var i = 0, resolved; i < filename.length; ++i)
         if (resolved = self2.resolvePath("", filename[i]))
-          fetch(resolved);
+          fetch2(resolved);
       if (sync) {
         self2.resolveAll();
         return self2;
@@ -3621,14 +3621,14 @@ var require_util = __commonJS({
       Object.defineProperty(object, "$type", { value: enm, enumerable: false });
       return enm;
     };
-    util.setProperty = function setProperty(dst, path5, value, ifNotSet) {
-      function setProp(dst2, path6, value2) {
-        var part = path6.shift();
+    util.setProperty = function setProperty(dst, path7, value, ifNotSet) {
+      function setProp(dst2, path8, value2) {
+        var part = path8.shift();
         if (part === "__proto__" || part === "prototype") {
           return dst2;
         }
-        if (path6.length > 0) {
-          dst2[part] = setProp(dst2[part] || {}, path6, value2);
+        if (path8.length > 0) {
+          dst2[part] = setProp(dst2[part] || {}, path8, value2);
         } else {
           var prevValue = dst2[part];
           if (prevValue && ifNotSet)
@@ -3641,10 +3641,10 @@ var require_util = __commonJS({
       }
       if (typeof dst !== "object")
         throw TypeError("dst must be an object");
-      if (!path5)
+      if (!path7)
         throw TypeError("path must be specified");
-      path5 = path5.split(".");
-      return setProp(dst, path5, value);
+      path7 = path7.split(".");
+      return setProp(dst, path7, value);
     };
     Object.defineProperty(util, "decorateRoot", {
       get: function() {
@@ -4191,12 +4191,12 @@ var require_object = __commonJS({
        */
       fullName: {
         get: function() {
-          var path5 = [this.name], ptr = this.parent;
+          var path7 = [this.name], ptr = this.parent;
           while (ptr) {
-            path5.unshift(ptr.name);
+            path7.unshift(ptr.name);
             ptr = ptr.parent;
           }
-          return path5.join(".");
+          return path7.join(".");
         }
       }
     });
@@ -8178,19 +8178,19 @@ var require_util2 = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.addCommonProtos = exports2.loadProtosWithOptionsSync = exports2.loadProtosWithOptions = void 0;
-    var fs3 = __require("fs");
-    var path5 = __require("path");
+    var fs5 = __require("fs");
+    var path7 = __require("path");
     var Protobuf = require_protobufjs();
     function addIncludePathResolver(root, includePaths) {
       const originalResolvePath = root.resolvePath;
       root.resolvePath = (origin, target) => {
-        if (path5.isAbsolute(target)) {
+        if (path7.isAbsolute(target)) {
           return target;
         }
         for (const directory of includePaths) {
-          const fullPath = path5.join(directory, target);
+          const fullPath = path7.join(directory, target);
           try {
-            fs3.accessSync(fullPath, fs3.constants.R_OK);
+            fs5.accessSync(fullPath, fs5.constants.R_OK);
             return fullPath;
           } catch (err) {
             continue;
@@ -9505,6 +9505,8 @@ var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
   ErrorCode2[ErrorCode2["TTL_EXPIRED"] = 13] = "TTL_EXPIRED";
   ErrorCode2[ErrorCode2["DUPLICATE_DETECTED"] = 14] = "DUPLICATE_DETECTED";
   ErrorCode2[ErrorCode2["ALREADY_IN_PROGRESS"] = 15] = "ALREADY_IN_PROGRESS";
+  ErrorCode2[ErrorCode2["OVERLOADED"] = 16] = "OVERLOADED";
+  ErrorCode2[ErrorCode2["REDIRECT"] = 20] = "REDIRECT";
   ErrorCode2[ErrorCode2["INTERNAL_ERROR"] = 99] = "INTERNAL_ERROR";
   return ErrorCode2;
 })(ErrorCode || {});
@@ -10779,6 +10781,38 @@ var HandoffStatus = /* @__PURE__ */ ((HandoffStatus2) => {
   HandoffStatus2[HandoffStatus2["EXPIRED"] = 5] = "EXPIRED";
   return HandoffStatus2;
 })(HandoffStatus || {});
+var DEFAULT_MAX_RETRIES_ON_OVERLOADED = 2;
+var DEFAULT_INITIAL_BACKOFF_MS = 250;
+var DEFAULT_BACKOFF_MULTIPLIER = 2;
+var DEFAULT_MAX_BACKOFF_MS = 2e3;
+var DEFAULT_MAX_REDIRECTS = 0;
+function defaultDelegationPolicy() {
+  return {
+    maxRetriesOnOverloaded: DEFAULT_MAX_RETRIES_ON_OVERLOADED,
+    initialBackoffMs: DEFAULT_INITIAL_BACKOFF_MS,
+    backoffMultiplier: DEFAULT_BACKOFF_MULTIPLIER,
+    maxBackoffMs: DEFAULT_MAX_BACKOFF_MS,
+    allowSpilloverRouting: false,
+    maxRedirects: DEFAULT_MAX_REDIRECTS
+  };
+}
+function normalizeDelegationPolicy(policy) {
+  const defaults = defaultDelegationPolicy();
+  const maxRetriesOnOverloaded = policy?.maxRetriesOnOverloaded;
+  const initialBackoffMs = policy?.initialBackoffMs;
+  const backoffMultiplier = policy?.backoffMultiplier;
+  const maxBackoffMs = policy?.maxBackoffMs;
+  const allowSpilloverRouting = policy?.allowSpilloverRouting;
+  const maxRedirects = policy?.maxRedirects;
+  return {
+    maxRetriesOnOverloaded: maxRetriesOnOverloaded === void 0 ? defaults.maxRetriesOnOverloaded : maxRetriesOnOverloaded,
+    initialBackoffMs: initialBackoffMs !== void 0 && initialBackoffMs > 0 ? initialBackoffMs : defaults.initialBackoffMs,
+    backoffMultiplier: backoffMultiplier !== void 0 && backoffMultiplier > 0 ? backoffMultiplier : defaults.backoffMultiplier,
+    maxBackoffMs: maxBackoffMs !== void 0 && maxBackoffMs > 0 ? maxBackoffMs : defaults.maxBackoffMs,
+    allowSpilloverRouting: allowSpilloverRouting ?? defaults.allowSpilloverRouting,
+    maxRedirects: maxRedirects === void 0 ? defaults.maxRedirects : maxRedirects
+  };
+}
 var HandoffValidationError = class extends Error {
   constructor(message) {
     super(message);
@@ -10827,9 +10861,15 @@ var HandoffClient = class {
         `Handoff request with ID '${request.requestId}' already exists`
       );
     }
+    if (request.budget !== void 0 && (!request.budget.deadlineEpochMs || request.budget.deadlineEpochMs <= 0)) {
+      throw new HandoffValidationError(
+        "budget.deadlineEpochMs is required for cross-swarm delegation"
+      );
+    }
     const requestWithTimestamp = {
       ...request,
-      createdAt: request.createdAt || (/* @__PURE__ */ new Date()).toISOString()
+      createdAt: request.createdAt || (/* @__PURE__ */ new Date()).toISOString(),
+      delegationPolicy: request.budget !== void 0 || request.delegationPolicy !== void 0 ? normalizeDelegationPolicy(request.delegationPolicy) : void 0
     };
     this.requests.set(request.requestId, requestWithTimestamp);
     if (request.toAgent) {
@@ -10851,7 +10891,8 @@ var HandoffClient = class {
     const timeoutResponse = {
       requestId: request.requestId,
       accepted: false,
-      rejectionReason: `Handoff request timed out after ${timeoutMs}ms`
+      rejectionReason: `Handoff request timed out after ${timeoutMs}ms`,
+      rejectionCode: 3 /* ACK_TIMEOUT */
     };
     this.responses.set(request.requestId, timeoutResponse);
     if (request.toAgent && this.pendingByAgent.has(request.toAgent)) {
@@ -10916,7 +10957,7 @@ var HandoffClient = class {
    * await client.rejectHandoff("handoff-123", "Agent at capacity");
    * ```
    */
-  async rejectHandoff(handoffId, reason) {
+  async rejectHandoff(handoffId, reason, options) {
     const request = this.requests.get(handoffId);
     if (!request) {
       throw new HandoffValidationError(
@@ -10931,7 +10972,10 @@ var HandoffClient = class {
     const response = {
       requestId: handoffId,
       accepted: false,
-      rejectionReason: reason
+      rejectionReason: reason,
+      rejectionCode: options?.rejectionCode ?? 0 /* ERROR_CODE_UNSPECIFIED */,
+      retryAfterMs: options?.retryAfterMs,
+      redirectToAgentId: options?.redirectToAgentId
     };
     this.responses.set(handoffId, response);
     if (request.toAgent && this.pendingByAgent.has(request.toAgent)) {
@@ -11435,8 +11479,8 @@ function nowHlcStub(date = /* @__PURE__ */ new Date()) {
   const wallUs = date.getTime() * 1e3;
   let node = "unknown";
   try {
-    const os = __require("node:os");
-    node = os.hostname() || "unknown";
+    const os3 = __require("node:os");
+    node = os3.hostname() || "unknown";
   } catch {
     node = "browser";
   }
@@ -11893,6 +11937,542 @@ function decodeBase64(b64) {
   return new Uint8Array(Buffer.from(b64, "base64"));
 }
 
+// src/runtime/delegation.ts
+import { randomUUID } from "node:crypto";
+var RETRY_AFTER_JITTER_RATIO = 0.2;
+var DEFAULT_EFFECTIVE_MAX_REDIRECTS = 2;
+function defaultNowMs() {
+  return Date.now();
+}
+function defaultSleepMs(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function defaultRandUniform(low, high) {
+  if (high <= low) {
+    return low;
+  }
+  return low + Math.random() * (high - low);
+}
+function normalizePolicy(policy) {
+  return {
+    maxRetriesOnOverloaded: policy?.maxRetriesOnOverloaded ?? DEFAULT_MAX_RETRIES_ON_OVERLOADED,
+    initialBackoffMs: policy?.initialBackoffMs !== void 0 && policy.initialBackoffMs > 0 ? policy.initialBackoffMs : DEFAULT_INITIAL_BACKOFF_MS,
+    backoffMultiplier: policy?.backoffMultiplier !== void 0 && policy.backoffMultiplier > 0 ? policy.backoffMultiplier : DEFAULT_BACKOFF_MULTIPLIER,
+    maxBackoffMs: policy?.maxBackoffMs !== void 0 && policy.maxBackoffMs > 0 ? policy.maxBackoffMs : DEFAULT_MAX_BACKOFF_MS,
+    allowSpilloverRouting: policy?.allowSpilloverRouting ?? false,
+    maxRedirects: policy?.maxRedirects ?? DEFAULT_MAX_REDIRECTS
+  };
+}
+function deadlineExhaustedResponse(requestId) {
+  return {
+    requestId,
+    accepted: false,
+    rejectionReason: "Delegation deadline exhausted before handoff acceptance",
+    rejectionCode: 3 /* ACK_TIMEOUT */
+  };
+}
+function invalidRedirectResponse(requestId, reason) {
+  return {
+    requestId,
+    accepted: false,
+    rejectionReason: reason,
+    rejectionCode: 6 /* VALIDATION_ERROR */
+  };
+}
+function effectiveMaxRedirects(policy) {
+  const configured = policy.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+  return configured > 0 ? configured : DEFAULT_EFFECTIVE_MAX_REDIRECTS;
+}
+function nextRetryWaitMs(response, retryIndex, policy, randUniformFn) {
+  if (response.retryAfterMs !== void 0 && response.retryAfterMs > 0) {
+    const retryAfter = response.retryAfterMs;
+    const jitter = randUniformFn(0, retryAfter * RETRY_AFTER_JITTER_RATIO);
+    return Math.floor(retryAfter + jitter);
+  }
+  const initialBackoffMs = policy.initialBackoffMs ?? DEFAULT_INITIAL_BACKOFF_MS;
+  const backoffMultiplier = policy.backoffMultiplier ?? DEFAULT_BACKOFF_MULTIPLIER;
+  const maxBackoffMs = policy.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
+  const exponential = initialBackoffMs * backoffMultiplier ** retryIndex;
+  const bounded = Math.min(exponential, maxBackoffMs);
+  return Math.floor(randUniformFn(0, bounded));
+}
+function deductWallTime(request, elapsedMs) {
+  if (request.budget?.wallTimeRemainingMs !== void 0) {
+    request.budget.wallTimeRemainingMs = Math.max(
+      request.budget.wallTimeRemainingMs - elapsedMs,
+      0
+    );
+  }
+}
+function budgetExhausted(budget, nowMs) {
+  return budget.wallTimeRemainingMs !== void 0 && budget.wallTimeRemainingMs <= 0 || nowMs > budget.deadlineEpochMs;
+}
+async function delegateToSwarm(options) {
+  if (!options.budget.deadlineEpochMs || options.budget.deadlineEpochMs <= 0) {
+    throw new HandoffValidationError(
+      "budget.deadlineEpochMs is required for cross-swarm delegation"
+    );
+  }
+  if (options.timeoutMs !== void 0 && options.timeoutMs < 0) {
+    throw new HandoffValidationError("timeoutMs must be >= 0");
+  }
+  const nowMs = options.nowMsFn ?? defaultNowMs;
+  const sleepMs = options.sleepMsFn ?? defaultSleepMs;
+  const randUniform = options.randUniformFn ?? defaultRandUniform;
+  const policy = normalizePolicy(options.delegationPolicy);
+  const requestBudget = { ...options.budget };
+  const request = {
+    requestId: options.requestId ?? randomUUID(),
+    fromAgent: options.fromAgent,
+    toAgent: options.toAgent,
+    reason: options.reason,
+    contextSnapshot: options.contextSnapshot ?? new Uint8Array(),
+    capabilitiesRequired: [...options.capabilitiesRequired ?? []],
+    priority: options.priority ?? 0,
+    timeoutMs: options.timeoutMs,
+    budget: requestBudget,
+    delegationPolicy: policy
+  };
+  const maxRetriesOnOverloaded = policy.maxRetriesOnOverloaded ?? DEFAULT_MAX_RETRIES_ON_OVERLOADED;
+  let retryIndex = 0;
+  let redirectHops = 0;
+  const redirectBound = effectiveMaxRedirects(policy);
+  const visitedAgents = /* @__PURE__ */ new Set([request.toAgent]);
+  while (true) {
+    const startMs = nowMs();
+    if (budgetExhausted(request.budget, startMs)) {
+      return deadlineExhaustedResponse(request.requestId);
+    }
+    const response = await options.sendHandoffFn(request);
+    const endMs = nowMs();
+    const elapsedMs = Math.max(endMs - startMs, 0);
+    deductWallTime(request, elapsedMs);
+    if (response.accepted) {
+      return response;
+    }
+    if (budgetExhausted(request.budget, endMs)) {
+      return deadlineExhaustedResponse(request.requestId);
+    }
+    if (response.rejectionCode !== 16 /* OVERLOADED */) {
+      if (response.rejectionCode !== 20 /* REDIRECT */) {
+        return response;
+      }
+      if (!policy.allowSpilloverRouting) {
+        return response;
+      }
+      const targetAgent = response.redirectToAgentId?.trim();
+      if (!targetAgent) {
+        return invalidRedirectResponse(
+          request.requestId,
+          "Redirect response missing non-empty redirectToAgentId"
+        );
+      }
+      if (visitedAgents.has(targetAgent)) {
+        return invalidRedirectResponse(
+          request.requestId,
+          `Redirect loop detected for agent '${targetAgent}'`
+        );
+      }
+      if (redirectHops >= redirectBound) {
+        return response;
+      }
+      request.toAgent = targetAgent;
+      visitedAgents.add(targetAgent);
+      redirectHops += 1;
+      continue;
+    }
+    if (retryIndex >= maxRetriesOnOverloaded) {
+      return response;
+    }
+    const waitMs = nextRetryWaitMs(response, retryIndex, policy, randUniform);
+    retryIndex += 1;
+    const remainingDeadlineMs = request.budget.deadlineEpochMs - endMs;
+    const remainingWallTimeMs = request.budget?.wallTimeRemainingMs;
+    if (waitMs <= 0 || remainingWallTimeMs !== void 0 && waitMs > remainingWallTimeMs || waitMs > remainingDeadlineMs) {
+      return response;
+    }
+    const beforeSleepMs = nowMs();
+    await sleepMs(waitMs);
+    const afterSleepMs = nowMs();
+    deductWallTime(request, Math.max(afterSleepMs - beforeSleepMs, 0));
+  }
+}
+
+// src/runtime/cancellation.ts
+var MIN_GRACE_PERIOD_MS = 5e3;
+var CancellationValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CancellationValidationError";
+  }
+};
+function defaultNowMs2() {
+  return Date.now();
+}
+function normalizeCorrelationId(correlationId) {
+  const normalized = correlationId.trim();
+  if (!normalized) {
+    throw new CancellationValidationError(
+      "cancel.correlationId is required and must be a non-empty string"
+    );
+  }
+  return normalized;
+}
+function normalizeReason(reason) {
+  if (reason === void 0) {
+    return "";
+  }
+  return reason.trim();
+}
+function normalizeGracePeriodMs(gracePeriodMs) {
+  const requested = gracePeriodMs !== void 0 && Number.isFinite(gracePeriodMs) && gracePeriodMs > 0 ? Math.floor(gracePeriodMs) : 0;
+  return Math.max(requested, MIN_GRACE_PERIOD_MS);
+}
+function normalizeMetadataValue(value) {
+  if (value === null) {
+    return null;
+  }
+  if (typeof value === "string") {
+    return value.trim();
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : void 0;
+  }
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (typeof value === "bigint") {
+    return value.toString();
+  }
+  if (typeof value === "object") {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return void 0;
+    }
+  }
+  return void 0;
+}
+function normalizeMetadata(metadata, options) {
+  const { reason, gracePeriodMs } = options;
+  const normalized = {};
+  if (metadata !== void 0) {
+    for (const [rawKey, rawValue] of Object.entries(metadata)) {
+      const key = rawKey.trim();
+      if (!key) {
+        continue;
+      }
+      const value = normalizeMetadataValue(rawValue);
+      if (value !== void 0) {
+        normalized[key] = value;
+      }
+    }
+  }
+  normalized.reason = reason;
+  normalized.grace_period_ms = gracePeriodMs;
+  return normalized;
+}
+function cloneMetadata(metadata) {
+  return { ...metadata };
+}
+function cloneFlag(flag) {
+  return {
+    cancelled: flag.cancelled,
+    gracePeriodMs: flag.gracePeriodMs,
+    cancelTimeMs: flag.cancelTimeMs,
+    metadata: cloneMetadata(flag.metadata)
+  };
+}
+var CancellationManager = class {
+  childDelegations = /* @__PURE__ */ new Map();
+  cancellationFlags = /* @__PURE__ */ new Map();
+  nowMs;
+  constructor(options = {}) {
+    this.nowMs = options.nowMsFn ?? defaultNowMs2;
+  }
+  registerChildDelegation(parentCorrelationId, childCorrelationId) {
+    const parent = normalizeCorrelationId(parentCorrelationId);
+    const child = normalizeCorrelationId(childCorrelationId);
+    if (!this.childDelegations.has(parent)) {
+      this.childDelegations.set(parent, /* @__PURE__ */ new Set());
+    }
+    this.childDelegations.get(parent).add(child);
+  }
+  handleCancelDelegation(cancel) {
+    const correlationId = normalizeCorrelationId(cancel.correlationId);
+    const gracePeriodMs = normalizeGracePeriodMs(cancel.gracePeriodMs);
+    const reason = normalizeReason(cancel.reason);
+    const cancelTimeMs = this.nowMs();
+    const metadata = normalizeMetadata(cancel.metadata, {
+      reason,
+      gracePeriodMs
+    });
+    const flag = {
+      cancelled: true,
+      gracePeriodMs,
+      cancelTimeMs,
+      metadata
+    };
+    this.cancellationFlags.set(correlationId, cloneFlag(flag));
+    for (const childCorrelationId of this.childDelegations.get(correlationId) ?? []) {
+      this.cancellationFlags.set(childCorrelationId, cloneFlag(flag));
+    }
+    return {
+      acknowledged: true,
+      correlationId,
+      gracePeriodMs,
+      message: "Cancellation recorded",
+      metadata: cloneMetadata(metadata)
+    };
+  }
+  isCancelled(correlationId) {
+    const normalized = correlationId.trim();
+    if (!normalized) {
+      return false;
+    }
+    const entry = this.cancellationFlags.get(normalized);
+    return Boolean(entry?.cancelled);
+  }
+  isGraceExpired(correlationId, nowMs) {
+    const normalized = correlationId.trim();
+    if (!normalized) {
+      return false;
+    }
+    const entry = this.cancellationFlags.get(normalized);
+    if (entry === void 0 || !entry.cancelled) {
+      return false;
+    }
+    const currentMs = nowMs ?? this.nowMs();
+    return currentMs - entry.cancelTimeMs >= entry.gracePeriodMs;
+  }
+  forcedPreemptionErrorCode(correlationId, nowMs) {
+    if (this.isGraceExpired(correlationId, nowMs)) {
+      return 12 /* FORCED_PREEMPTION */;
+    }
+    return 0 /* ERROR_CODE_UNSPECIFIED */;
+  }
+  collectForcedPreemptions(correlationIds, nowMs) {
+    const currentMs = nowMs ?? this.nowMs();
+    const forced = /* @__PURE__ */ new Set();
+    for (const correlationId of correlationIds) {
+      if (this.isGraceExpired(correlationId, currentMs)) {
+        forced.add(correlationId);
+      }
+    }
+    return forced;
+  }
+};
+
+// src/runtime/gateway.ts
+var REGISTRATION_TYPE_STANDARD_AGENT = 1;
+var REGISTRATION_TYPE_SWARM_GATEWAY = 2;
+var AGENT_STATE_INITIALIZING = 1;
+var AGENT_STATE_RUNNING = 4;
+var AGENT_STATE_FAILED = 10;
+var AGENT_STATE_SHUTTING_DOWN = 11;
+var DEFAULT_PEER_LIVENESS_THRESHOLD_MS = 3e4;
+var NON_SERVING_AGENT_STATES = /* @__PURE__ */ new Set([
+  AGENT_STATE_INITIALIZING,
+  AGENT_STATE_FAILED,
+  AGENT_STATE_SHUTTING_DOWN
+]);
+var GatewayValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "GatewayValidationError";
+  }
+};
+function defaultNowMs3() {
+  return Date.now();
+}
+function sameCapabilities(peerCapabilities, localCapabilities) {
+  const peerSet = new Set(peerCapabilities);
+  if (peerSet.size !== localCapabilities.size) {
+    return false;
+  }
+  for (const localCapability of localCapabilities) {
+    if (!peerSet.has(localCapability)) {
+      return false;
+    }
+  }
+  return true;
+}
+var PeerSelector = class {
+  localAgentId;
+  localCapabilities;
+  nowMs;
+  peerHealthFn;
+  livenessThresholdMs;
+  peers = [];
+  runtime = /* @__PURE__ */ new Map();
+  rrCursor = 0;
+  constructor(options) {
+    const threshold = options.livenessThresholdMs ?? DEFAULT_PEER_LIVENESS_THRESHOLD_MS;
+    if (threshold < 0) {
+      throw new GatewayValidationError("livenessThresholdMs must be >= 0");
+    }
+    this.localAgentId = options.localAgentId;
+    this.localCapabilities = new Set(options.localCapabilities ?? []);
+    this.nowMs = options.nowMsFn ?? defaultNowMs3;
+    this.peerHealthFn = options.peerHealthFn ?? (() => true);
+    this.livenessThresholdMs = threshold;
+  }
+  setPeers(peers) {
+    this.peers = [...peers];
+    const activeIds = new Set(this.peers.map((peer) => peer.agentId));
+    for (const agentId of [...this.runtime.keys()]) {
+      if (!activeIds.has(agentId)) {
+        this.runtime.delete(agentId);
+      }
+    }
+    const nowMs = this.nowMs();
+    for (const peer of this.peers) {
+      if (!this.runtime.has(peer.agentId)) {
+        this.runtime.set(peer.agentId, {
+          state: AGENT_STATE_RUNNING,
+          lastHeartbeatMs: nowMs,
+          cooldownUntilMs: 0
+        });
+      }
+    }
+  }
+  updatePeerRuntimeState(agentId, options = {}) {
+    const runtime = this.ensureRuntime(agentId);
+    if (options.state !== void 0) {
+      runtime.state = options.state;
+    }
+    if (options.lastHeartbeatMs !== void 0) {
+      runtime.lastHeartbeatMs = Math.max(Math.floor(options.lastHeartbeatMs), 0);
+    }
+    if (options.cooldownUntilMs !== void 0) {
+      runtime.cooldownUntilMs = Math.max(Math.floor(options.cooldownUntilMs), 0);
+    }
+    this.runtime.set(agentId, runtime);
+  }
+  touchPeerHeartbeat(agentId, options = {}) {
+    this.updatePeerRuntimeState(agentId, {
+      state: options.state,
+      lastHeartbeatMs: options.nowMs ?? this.nowMs()
+    });
+  }
+  recordPeerOverloaded(agentId, options = {}) {
+    const runtime = this.ensureRuntime(agentId);
+    const nowMs = this.nowMs();
+    const retryAfterMs = Math.max(Math.floor(options.retryAfterMs ?? 0), 0);
+    const localCooldownMs = Math.max(Math.floor(options.localCooldownMs ?? 0), 0);
+    const cooldownMs = Math.max(retryAfterMs, localCooldownMs);
+    runtime.cooldownUntilMs = Math.max(runtime.cooldownUntilMs, nowMs + cooldownMs);
+    this.runtime.set(agentId, runtime);
+  }
+  isEligible(peer) {
+    if (peer.registrationType !== REGISTRATION_TYPE_SWARM_GATEWAY) {
+      return false;
+    }
+    if (peer.agentId === this.localAgentId) {
+      return false;
+    }
+    return sameCapabilities(peer.capabilities, this.localCapabilities);
+  }
+  selectPeer() {
+    const healthy = this.peers.filter((peer) => this.isHealthy(peer));
+    if (healthy.length === 0) {
+      return "";
+    }
+    const idx = this.rrCursor % healthy.length;
+    this.rrCursor += 1;
+    return healthy[idx].agentId;
+  }
+  ensureRuntime(agentId) {
+    const existing = this.runtime.get(agentId);
+    if (existing !== void 0) {
+      return existing;
+    }
+    return {
+      state: AGENT_STATE_RUNNING,
+      lastHeartbeatMs: this.nowMs(),
+      cooldownUntilMs: 0
+    };
+  }
+  isHealthy(peer) {
+    if (!this.isEligible(peer)) {
+      return false;
+    }
+    if (!this.peerHealthFn(peer)) {
+      return false;
+    }
+    const runtime = this.runtime.get(peer.agentId);
+    if (runtime === void 0) {
+      return false;
+    }
+    const nowMs = this.nowMs();
+    if (runtime.cooldownUntilMs > nowMs) {
+      return false;
+    }
+    if (nowMs - runtime.lastHeartbeatMs > this.livenessThresholdMs) {
+      return false;
+    }
+    if (NON_SERVING_AGENT_STATES.has(runtime.state)) {
+      return false;
+    }
+    return true;
+  }
+};
+var GatewayRedirectEmitter = class {
+  retryAfterMs;
+  peerSelector;
+  constructor(options) {
+    if ((options.retryAfterMs ?? 0) < 0) {
+      throw new GatewayValidationError("retryAfterMs must be >= 0");
+    }
+    this.retryAfterMs = options.retryAfterMs ?? 1e3;
+    this.peerSelector = new PeerSelector({
+      localAgentId: options.agentId,
+      localCapabilities: options.capabilities ?? [],
+      nowMsFn: options.nowMsFn,
+      peerHealthFn: options.peerHealthFn,
+      livenessThresholdMs: options.peerLivenessThresholdMs
+    });
+    this.peerSelector.setPeers(options.peerDescriptors ?? []);
+  }
+  setPeerDescriptors(peers) {
+    this.peerSelector.setPeers(peers);
+  }
+  updatePeerRuntimeState(agentId, options = {}) {
+    this.peerSelector.updatePeerRuntimeState(agentId, options);
+  }
+  touchPeerHeartbeat(agentId, options = {}) {
+    this.peerSelector.touchPeerHeartbeat(agentId, options);
+  }
+  recordPeerOverloaded(agentId, options = {}) {
+    this.peerSelector.recordPeerOverloaded(agentId, options);
+  }
+  emitOverloadedResponse(request) {
+    if (request.delegationPolicy?.allowSpilloverRouting) {
+      const redirectToAgentId = this.peerSelector.selectPeer();
+      if (redirectToAgentId) {
+        return {
+          requestId: request.requestId,
+          accepted: false,
+          rejectionReason: "Gateway at capacity; redirect to peer gateway",
+          rejectionCode: 20 /* REDIRECT */,
+          retryAfterMs: 0,
+          redirectToAgentId
+        };
+      }
+    }
+    return {
+      requestId: request.requestId,
+      accepted: false,
+      rejectionReason: "Gateway at capacity",
+      rejectionCode: 16 /* OVERLOADED */,
+      retryAfterMs: this.retryAfterMs
+    };
+  }
+};
+
 // src/persistence/persistence.ts
 import fsp from "node:fs/promises";
 import path2 from "node:path";
@@ -14022,8 +14602,8 @@ function defaultPath() {
 }
 var FileBackend = class {
   path;
-  constructor(path5) {
-    this.path = path5 ?? defaultPath();
+  constructor(path7) {
+    this.path = path7 ?? defaultPath();
     mkdirSync2(dirname2(this.path), { recursive: true });
     try {
       chmodSync(dirname2(this.path), 448);
@@ -14153,30 +14733,879 @@ async function selectBackend(mode) {
   }
 }
 
+// src/llm/client.ts
+var LlmError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "LlmError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var LlmAuthenticationError = class extends LlmError {
+  constructor(message) {
+    super(message);
+    this.name = "LlmAuthenticationError";
+  }
+};
+var LlmRateLimitError = class extends LlmError {
+  constructor(message) {
+    super(message);
+    this.name = "LlmRateLimitError";
+  }
+};
+var LlmTimeoutError = class extends LlmError {
+  constructor(message) {
+    super(message);
+    this.name = "LlmTimeoutError";
+  }
+};
+var LlmContextLengthError = class extends LlmError {
+  constructor(message) {
+    super(message);
+    this.name = "LlmContextLengthError";
+  }
+};
+
+// src/llm/rateLimiter.ts
+function envBool(name, defaultVal) {
+  const raw = (process.env[name] ?? defaultVal).toLowerCase();
+  return !["0", "false", "no"].includes(raw);
+}
+function buildRateLimiterConfig(overrides) {
+  return {
+    tokensPerMinute: overrides?.tokensPerMinute ?? parseInt(process.env["LLM_RATE_LIMIT_TOKENS_PER_MIN"] ?? "250000", 10),
+    burstAllowance: overrides?.burstAllowance ?? 1,
+    minTokensPerRequest: overrides?.minTokensPerRequest ?? 100,
+    maxWaitSeconds: overrides?.maxWaitSeconds ?? 120,
+    enabled: overrides?.enabled ?? envBool("LLM_RATE_LIMIT_ENABLED", "1"),
+    adaptiveEnabled: overrides?.adaptiveEnabled ?? envBool("LLM_RATE_LIMIT_ADAPTIVE", "1"),
+    reductionFactor: overrides?.reductionFactor ?? parseFloat(process.env["LLM_RATE_LIMIT_REDUCTION_FACTOR"] ?? "0.7"),
+    recoveryFactor: overrides?.recoveryFactor ?? parseFloat(process.env["LLM_RATE_LIMIT_RECOVERY_FACTOR"] ?? "1.1"),
+    cooldownSeconds: overrides?.cooldownSeconds ?? parseFloat(process.env["LLM_RATE_LIMIT_COOLDOWN_SECONDS"] ?? "30"),
+    successesForRecovery: overrides?.successesForRecovery ?? parseInt(
+      process.env["LLM_RATE_LIMIT_RECOVERY_SUCCESS_THRESHOLD"] ?? "20",
+      10
+    )
+  };
+}
+var TokenBucket = class {
+  config;
+  baseTpm;
+  currentTpm;
+  minTpm;
+  tokens;
+  lastRefill;
+  lastRateLimitTime = null;
+  successesSinceLimit = 0;
+  constructor(config) {
+    this.config = buildRateLimiterConfig(config);
+    this.baseTpm = this.config.tokensPerMinute;
+    this.currentTpm = this.config.tokensPerMinute;
+    this.minTpm = Math.max(1e3, this.baseTpm * 0.25);
+    this.tokens = this.currentTpm;
+    this.lastRefill = performance.now();
+  }
+  // -- Internal helpers ----------------------------------------------------
+  refill() {
+    const now = performance.now();
+    const elapsedSeconds = (now - this.lastRefill) / 1e3;
+    const refill = elapsedSeconds * (this.currentTpm / 60);
+    this.tokens = Math.min(
+      this.tokens + refill,
+      this.currentTpm * this.config.burstAllowance
+    );
+    this.lastRefill = now;
+    this.maybeRecover(now);
+  }
+  maybeRecover(now) {
+    if (!this.config.adaptiveEnabled)
+      return;
+    if (this.currentTpm >= this.baseTpm)
+      return;
+    if (this.lastRateLimitTime === null)
+      return;
+    if ((now - this.lastRateLimitTime) / 1e3 < this.config.cooldownSeconds)
+      return;
+    if (this.successesSinceLimit < this.config.successesForRecovery)
+      return;
+    const newLimit = Math.min(
+      this.baseTpm,
+      this.currentTpm * this.config.recoveryFactor
+    );
+    if (newLimit > this.currentTpm) {
+      this.currentTpm = newLimit;
+      this.successesSinceLimit = 0;
+    }
+  }
+  // -- Public API ----------------------------------------------------------
+  /**
+   * Acquire tokens, waiting if necessary.
+   *
+   * @param estimatedTokens - Estimated token count for the request.
+   * @returns Time spent waiting in milliseconds (0 if immediate).
+   * @throws Error if waiting exceeds {@link RateLimiterConfig.maxWaitSeconds}.
+   */
+  async acquire(estimatedTokens) {
+    if (!this.config.enabled)
+      return 0;
+    estimatedTokens = Math.max(estimatedTokens, this.config.minTokensPerRequest);
+    const waitStart = performance.now();
+    for (; ; ) {
+      this.refill();
+      if (this.tokens >= estimatedTokens) {
+        this.tokens -= estimatedTokens;
+        return performance.now() - waitStart;
+      }
+      const elapsed = (performance.now() - waitStart) / 1e3;
+      if (elapsed >= this.config.maxWaitSeconds) {
+        throw new Error(
+          `Rate limiter: waited ${elapsed.toFixed(1)}s for ${estimatedTokens} tokens`
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+  }
+  /**
+   * Record a 429 event -- adaptively reduce budget.
+   *
+   * Call this when the upstream API returns HTTP 429 or an equivalent
+   * rate-limit error.
+   */
+  recordRateLimit() {
+    if (!(this.config.enabled && this.config.adaptiveEnabled))
+      return;
+    this.lastRateLimitTime = performance.now();
+    this.successesSinceLimit = 0;
+    const newLimit = Math.max(
+      this.minTpm,
+      this.currentTpm * this.config.reductionFactor
+    );
+    if (newLimit < this.currentTpm) {
+      this.currentTpm = newLimit;
+      this.tokens = Math.min(this.tokens, this.currentTpm);
+    }
+  }
+  /**
+   * Record a successful request for adaptive recovery.
+   *
+   * Call this after each successful API response.
+   */
+  recordSuccess() {
+    if (!(this.config.enabled && this.config.adaptiveEnabled))
+      return;
+    this.successesSinceLimit += 1;
+  }
+  /** Current available token count. */
+  get availableTokens() {
+    return this.tokens;
+  }
+  /** Current tokens-per-minute budget (may be reduced after 429). */
+  get currentTokensPerMinute() {
+    return this.currentTpm;
+  }
+};
+var globalBucket = null;
+function getGlobalRateLimiter(config) {
+  if (globalBucket === null) {
+    globalBucket = new TokenBucket(config);
+  }
+  return globalBucket;
+}
+function resetGlobalRateLimiter() {
+  globalBucket = null;
+}
+
+// src/llm/mock.ts
+var MockLlmClient = class {
+  /** The model name returned in responses. */
+  defaultModel;
+  responses;
+  responseIndex = 0;
+  responseGenerator;
+  _callCount = 0;
+  _callHistory = [];
+  constructor(opts) {
+    this.defaultModel = opts?.defaultModel ?? "mock-model";
+    this.responses = opts?.responses ?? [];
+    this.responseGenerator = opts?.responseGenerator;
+  }
+  /** Number of queries made to this client. */
+  get callCount() {
+    return this._callCount;
+  }
+  /** History of all calls made to this client. */
+  get callHistory() {
+    return this._callHistory;
+  }
+  /** Reset call count, history, and response index. */
+  reset() {
+    this._callCount = 0;
+    this._callHistory.length = 0;
+    this.responseIndex = 0;
+  }
+  /**
+   * Return a mock response.
+   *
+   * Priority for determining response content:
+   *   1. `responseGenerator` function (if provided)
+   *   2. `responses` array (cycles through entries)
+   *   3. Default echo: "Mock response to: <prompt>"
+   *
+   * @param prompt - The prompt (recorded in history).
+   * @param opts   - Optional query configuration (recorded in history).
+   * @returns LlmResponse with mock content.
+   */
+  async query(prompt, opts) {
+    const model = opts?.model ?? this.defaultModel;
+    const maxTokens = opts?.maxTokens ?? 4096;
+    const temperature = opts?.temperature ?? 1;
+    this._callCount += 1;
+    this._callHistory.push({
+      prompt,
+      systemPrompt: opts?.systemPrompt,
+      maxTokens,
+      temperature,
+      model
+    });
+    let content;
+    if (this.responseGenerator) {
+      content = this.responseGenerator(prompt);
+    } else if (this.responses.length > 0) {
+      content = this.responses[this.responseIndex % this.responses.length];
+      this.responseIndex += 1;
+    } else {
+      content = `Mock response to: ${prompt.slice(0, 100)}`;
+    }
+    return {
+      content,
+      model,
+      usage: {
+        input_tokens: Math.max(Math.floor(prompt.length / 4), 1),
+        output_tokens: Math.max(Math.floor(content.length / 4), 1)
+      },
+      metadata: { mock: true, call_count: this._callCount }
+    };
+  }
+  /**
+   * Stream a mock response.
+   *
+   * Yields the response word by word to simulate streaming.
+   *
+   * @param prompt - The prompt (recorded in history).
+   * @param opts   - Optional query configuration.
+   * @yields Words from the mock response.
+   */
+  async *streamQuery(prompt, opts) {
+    const response = await this.query(prompt, opts);
+    const words = response.content.split(" ");
+    for (let i = 0; i < words.length; i++) {
+      yield words[i] + (i < words.length - 1 ? " " : "");
+    }
+  }
+};
+
+// src/llm/groq.ts
+import fs3 from "node:fs";
+import os from "node:os";
+import path5 from "node:path";
+var DEFAULT_MODEL = "llama-3.3-70b-versatile";
+var BASE_URL = "https://api.groq.com/openai/v1/chat/completions";
+var GroqClient = class _GroqClient {
+  /** The resolved API key. */
+  apiKey;
+  /** The default model used when none is specified per-call. */
+  defaultModel;
+  timeoutMs;
+  rateLimiter;
+  constructor(opts) {
+    this.defaultModel = opts?.defaultModel ?? process.env["GROQ_DEFAULT_MODEL"] ?? DEFAULT_MODEL;
+    const envKey = process.env["GROQ_API_KEY"]?.trim();
+    const resolved = opts?.apiKey ?? envKey ?? _GroqClient.loadKeyFile();
+    if (!resolved) {
+      throw new LlmAuthenticationError(
+        "No Groq API key. Set GROQ_API_KEY, pass apiKey, or create ~/.groq"
+      );
+    }
+    this.apiKey = resolved;
+    this.timeoutMs = opts?.timeoutMs ?? 12e4;
+    this.rateLimiter = getGlobalRateLimiter();
+  }
+  /**
+   * Load API key from ~/.groq file.
+   *
+   * @returns The key string, or null if the file does not exist.
+   */
+  static loadKeyFile() {
+    try {
+      const keyPath = path5.join(os.homedir(), ".groq");
+      if (fs3.existsSync(keyPath)) {
+        return fs3.readFileSync(keyPath, "utf-8").trim();
+      }
+    } catch {
+    }
+    return null;
+  }
+  // -- Helpers -------------------------------------------------------------
+  estimateTokens(prompt, systemPrompt) {
+    let total = prompt.length;
+    if (systemPrompt)
+      total += systemPrompt.length;
+    return Math.max(Math.floor(total / 4), 100);
+  }
+  buildMessages(prompt, systemPrompt) {
+    const messages = [];
+    if (systemPrompt) {
+      messages.push({ role: "system", content: systemPrompt });
+    }
+    messages.push({ role: "user", content: prompt });
+    return messages;
+  }
+  /**
+   * Map an HTTP error response to the appropriate LlmError subclass.
+   *
+   * @param status  - HTTP status code.
+   * @param body    - Parsed response body (if available).
+   * @param message - Raw error message.
+   */
+  mapError(status, body, message) {
+    if (status === 401 || status === 403) {
+      return new LlmAuthenticationError(`Groq auth failed (${status}): ${message}`);
+    }
+    if (status === 429) {
+      this.rateLimiter.recordRateLimit();
+      return new LlmRateLimitError(`Groq rate limit exceeded: ${message}`);
+    }
+    if (status === 408 || status === 504) {
+      return new LlmTimeoutError(`Groq request timed out (${status}): ${message}`);
+    }
+    const errorObj = body?.["error"];
+    const code = errorObj?.["code"];
+    if (code === "context_length_exceeded") {
+      return new LlmContextLengthError(`Groq context length exceeded: ${message}`);
+    }
+    return new LlmError(`Groq API error (${status}): ${message}`);
+  }
+  // -- Public API ----------------------------------------------------------
+  /**
+   * Send a query to Groq and get a complete response.
+   *
+   * @param prompt - The user prompt/query.
+   * @param opts   - Optional query configuration.
+   * @returns LlmResponse with generated content and metadata.
+   */
+  async query(prompt, opts) {
+    const useModel = opts?.model ?? this.defaultModel;
+    const maxTokens = opts?.maxTokens ?? 4096;
+    const temperature = opts?.temperature ?? 1;
+    const systemPrompt = opts?.systemPrompt;
+    const estimated = this.estimateTokens(prompt, systemPrompt);
+    await this.rateLimiter.acquire(estimated);
+    const body = {
+      model: useModel,
+      messages: this.buildMessages(prompt, systemPrompt),
+      max_tokens: maxTokens,
+      temperature
+    };
+    let response;
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      response = await fetch(BASE_URL, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      clearTimeout(timer);
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new LlmTimeoutError(`Groq request timed out after ${this.timeoutMs}ms`);
+      }
+      throw new LlmError(`Groq network error: ${String(err)}`);
+    }
+    if (!response.ok) {
+      let errorBody = null;
+      let errorMessage = response.statusText;
+      try {
+        errorBody = await response.json();
+        const errorObj = errorBody?.["error"];
+        errorMessage = errorObj?.["message"] ?? errorMessage;
+      } catch {
+      }
+      throw this.mapError(response.status, errorBody, errorMessage);
+    }
+    const data = await response.json();
+    this.rateLimiter.recordSuccess();
+    const choices = data["choices"];
+    const firstChoice = choices?.[0];
+    const messageObj = firstChoice?.["message"];
+    const content = messageObj?.["content"] ?? "";
+    const usageObj = data["usage"];
+    let usage;
+    if (usageObj) {
+      usage = {
+        input_tokens: usageObj["prompt_tokens"] ?? 0,
+        output_tokens: usageObj["completion_tokens"] ?? 0
+      };
+    }
+    return {
+      content,
+      model: data["model"] ?? useModel,
+      usage
+    };
+  }
+  /**
+   * Stream a query response chunk by chunk.
+   *
+   * Uses Server-Sent Events (SSE) streaming from the Groq API.
+   *
+   * @param prompt - The user prompt/query.
+   * @param opts   - Optional query configuration.
+   * @yields Text chunks as they arrive from the API.
+   */
+  async *streamQuery(prompt, opts) {
+    const useModel = opts?.model ?? this.defaultModel;
+    const maxTokens = opts?.maxTokens ?? 4096;
+    const temperature = opts?.temperature ?? 1;
+    const systemPrompt = opts?.systemPrompt;
+    const estimated = this.estimateTokens(prompt, systemPrompt);
+    await this.rateLimiter.acquire(estimated);
+    const body = {
+      model: useModel,
+      messages: this.buildMessages(prompt, systemPrompt),
+      max_tokens: maxTokens,
+      temperature,
+      stream: true
+    };
+    let response;
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      response = await fetch(BASE_URL, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      clearTimeout(timer);
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new LlmTimeoutError(`Groq request timed out after ${this.timeoutMs}ms`);
+      }
+      throw new LlmError(`Groq network error: ${String(err)}`);
+    }
+    if (!response.ok) {
+      let errorBody = null;
+      let errorMessage = response.statusText;
+      try {
+        errorBody = await response.json();
+        const errorObj = errorBody?.["error"];
+        errorMessage = errorObj?.["message"] ?? errorMessage;
+      } catch {
+      }
+      throw this.mapError(response.status, errorBody, errorMessage);
+    }
+    if (!response.body) {
+      throw new LlmError("Groq streaming response has no body");
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let streamCompleted = false;
+    try {
+      for (; ; ) {
+        const { done, value } = await reader.read();
+        if (done)
+          break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed || !trimmed.startsWith("data: "))
+            continue;
+          const payload = trimmed.slice(6);
+          if (payload === "[DONE]") {
+            streamCompleted = true;
+            return;
+          }
+          try {
+            const chunk = JSON.parse(payload);
+            const choices = chunk["choices"];
+            const delta = choices?.[0]?.["delta"];
+            const content = delta?.["content"];
+            if (content)
+              yield content;
+          } catch {
+          }
+        }
+      }
+      streamCompleted = true;
+    } finally {
+      reader.releaseLock();
+      if (streamCompleted)
+        this.rateLimiter.recordSuccess();
+    }
+  }
+};
+
+// src/llm/anthropic.ts
+import fs4 from "node:fs";
+import os2 from "node:os";
+import path6 from "node:path";
+var DEFAULT_MODEL2 = "claude-sonnet-4-20250514";
+var BASE_URL2 = "https://api.anthropic.com/v1/messages";
+var ANTHROPIC_VERSION = "2023-06-01";
+var AnthropicClient = class _AnthropicClient {
+  /** The resolved API key. */
+  apiKey;
+  /** The default model used when none is specified per-call. */
+  defaultModel;
+  timeoutMs;
+  rateLimiter;
+  constructor(opts) {
+    this.defaultModel = opts?.defaultModel ?? process.env["ANTHROPIC_DEFAULT_MODEL"] ?? DEFAULT_MODEL2;
+    const envKey = process.env["ANTHROPIC_API_KEY"]?.trim();
+    const resolved = opts?.apiKey ?? envKey ?? _AnthropicClient.loadKeyFile();
+    if (!resolved) {
+      throw new LlmAuthenticationError(
+        "No Anthropic API key. Set ANTHROPIC_API_KEY, pass apiKey, or create ~/.anthropic"
+      );
+    }
+    this.apiKey = resolved;
+    this.timeoutMs = opts?.timeoutMs ?? 3e5;
+    this.rateLimiter = getGlobalRateLimiter();
+  }
+  /**
+   * Load API key from ~/.anthropic file.
+   *
+   * @returns The key string, or null if the file does not exist.
+   */
+  static loadKeyFile() {
+    try {
+      const keyPath = path6.join(os2.homedir(), ".anthropic");
+      if (fs4.existsSync(keyPath)) {
+        return fs4.readFileSync(keyPath, "utf-8").trim();
+      }
+    } catch {
+    }
+    return null;
+  }
+  // -- Helpers -------------------------------------------------------------
+  estimateTokens(prompt, systemPrompt) {
+    let total = prompt.length;
+    if (systemPrompt)
+      total += systemPrompt.length;
+    return Math.max(Math.floor(total / 4), 100);
+  }
+  /**
+   * Map an HTTP error response to the appropriate LlmError subclass.
+   *
+   * @param status  - HTTP status code.
+   * @param body    - Parsed response body (if available).
+   * @param message - Raw error message.
+   */
+  mapError(status, body, message) {
+    if (status === 401 || status === 403) {
+      return new LlmAuthenticationError(
+        `Anthropic auth failed (${status}): ${message}`
+      );
+    }
+    if (status === 429) {
+      this.rateLimiter.recordRateLimit();
+      return new LlmRateLimitError(
+        `Anthropic rate limit exceeded: ${message}`
+      );
+    }
+    if (status === 408 || status === 504) {
+      return new LlmTimeoutError(
+        `Anthropic request timed out (${status}): ${message}`
+      );
+    }
+    const errorType = body?.["error"];
+    const errType = errorType?.["type"];
+    if (errType === "invalid_request_error") {
+      const msg = message.toLowerCase();
+      if (msg.includes("context") || msg.includes("token")) {
+        return new LlmContextLengthError(
+          `Anthropic context length exceeded: ${message}`
+        );
+      }
+    }
+    const lowerMsg = message.toLowerCase();
+    if (lowerMsg.includes("credit balance") || lowerMsg.includes("billing")) {
+      return new LlmAuthenticationError(
+        `Anthropic billing error: ${message}`
+      );
+    }
+    return new LlmError(`Anthropic API error (${status}): ${message}`);
+  }
+  // -- Public API ----------------------------------------------------------
+  /**
+   * Send a query to Anthropic and get a complete response.
+   *
+   * System prompts are sent via the top-level `system` parameter rather
+   * than as a system message in the messages array, per the Anthropic API
+   * specification.
+   *
+   * @param prompt - The user prompt/query.
+   * @param opts   - Optional query configuration.
+   * @returns LlmResponse with generated content and metadata.
+   */
+  async query(prompt, opts) {
+    const useModel = opts?.model ?? this.defaultModel;
+    const maxTokens = opts?.maxTokens ?? 4096;
+    const temperature = opts?.temperature ?? 1;
+    const systemPrompt = opts?.systemPrompt;
+    const estimated = this.estimateTokens(prompt, systemPrompt);
+    await this.rateLimiter.acquire(estimated);
+    const requestBody = {
+      model: useModel,
+      messages: [{ role: "user", content: prompt }],
+      max_tokens: maxTokens,
+      temperature
+    };
+    if (systemPrompt) {
+      requestBody["system"] = systemPrompt;
+    }
+    let response;
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      response = await fetch(BASE_URL2, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": this.apiKey,
+          "anthropic-version": ANTHROPIC_VERSION
+        },
+        body: JSON.stringify(requestBody),
+        signal: controller.signal
+      });
+      clearTimeout(timer);
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new LlmTimeoutError(
+          `Anthropic request timed out after ${this.timeoutMs}ms`
+        );
+      }
+      throw new LlmError(`Anthropic network error: ${String(err)}`);
+    }
+    if (!response.ok) {
+      let errorBody = null;
+      let errorMessage = response.statusText;
+      try {
+        errorBody = await response.json();
+        const errorObj = errorBody?.["error"];
+        errorMessage = errorObj?.["message"] ?? errorMessage;
+      } catch {
+      }
+      throw this.mapError(response.status, errorBody, errorMessage);
+    }
+    const data = await response.json();
+    this.rateLimiter.recordSuccess();
+    const contentBlocks = data["content"];
+    const textParts = [];
+    if (contentBlocks) {
+      for (const block of contentBlocks) {
+        if (block["type"] === "text" && typeof block["text"] === "string") {
+          textParts.push(block["text"]);
+        }
+      }
+    }
+    const content = textParts.join("").trim();
+    const usageObj = data["usage"];
+    const inputTokens = usageObj?.["input_tokens"] ?? 0;
+    const outputTokens = usageObj?.["output_tokens"] ?? 0;
+    return {
+      content,
+      model: data["model"] ?? useModel,
+      usage: {
+        input_tokens: inputTokens,
+        output_tokens: outputTokens
+      }
+    };
+  }
+  /**
+   * Stream a query response chunk by chunk.
+   *
+   * Uses Server-Sent Events (SSE) streaming from the Anthropic API.
+   * System prompts are sent via the top-level `system` parameter.
+   *
+   * @param prompt - The user prompt/query.
+   * @param opts   - Optional query configuration.
+   * @yields Text chunks as they arrive from the API.
+   */
+  async *streamQuery(prompt, opts) {
+    const useModel = opts?.model ?? this.defaultModel;
+    const maxTokens = opts?.maxTokens ?? 4096;
+    const temperature = opts?.temperature ?? 1;
+    const systemPrompt = opts?.systemPrompt;
+    const estimated = this.estimateTokens(prompt, systemPrompt);
+    await this.rateLimiter.acquire(estimated);
+    const requestBody = {
+      model: useModel,
+      messages: [{ role: "user", content: prompt }],
+      max_tokens: maxTokens,
+      temperature,
+      stream: true
+    };
+    if (systemPrompt) {
+      requestBody["system"] = systemPrompt;
+    }
+    let response;
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      response = await fetch(BASE_URL2, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": this.apiKey,
+          "anthropic-version": ANTHROPIC_VERSION
+        },
+        body: JSON.stringify(requestBody),
+        signal: controller.signal
+      });
+      clearTimeout(timer);
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new LlmTimeoutError(
+          `Anthropic request timed out after ${this.timeoutMs}ms`
+        );
+      }
+      throw new LlmError(`Anthropic network error: ${String(err)}`);
+    }
+    if (!response.ok) {
+      let errorBody = null;
+      let errorMessage = response.statusText;
+      try {
+        errorBody = await response.json();
+        const errorObj = errorBody?.["error"];
+        errorMessage = errorObj?.["message"] ?? errorMessage;
+      } catch {
+      }
+      throw this.mapError(response.status, errorBody, errorMessage);
+    }
+    if (!response.body) {
+      throw new LlmError("Anthropic streaming response has no body");
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let streamCompleted = false;
+    try {
+      for (; ; ) {
+        const { done, value } = await reader.read();
+        if (done)
+          break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed || !trimmed.startsWith("data: "))
+            continue;
+          const payload = trimmed.slice(6);
+          try {
+            const event = JSON.parse(payload);
+            const eventType = event["type"];
+            if (eventType === "content_block_delta") {
+              const delta = event["delta"];
+              if (delta?.["type"] === "text_delta") {
+                const text = delta["text"];
+                if (text)
+                  yield text;
+              }
+            } else if (eventType === "message_stop") {
+              streamCompleted = true;
+              return;
+            }
+          } catch {
+          }
+        }
+      }
+      streamCompleted = true;
+    } finally {
+      reader.releaseLock();
+      if (streamCompleted)
+        this.rateLimiter.recordSuccess();
+    }
+  }
+};
+
+// src/llm/factory.ts
+function createLlmClient(opts) {
+  const clientType = (opts?.clientType ?? process.env["LLM_CLIENT_TYPE"] ?? "mock").toLowerCase();
+  const model = opts?.model ?? process.env["LLM_DEFAULT_MODEL"];
+  if (clientType === "mock") {
+    return new MockLlmClient({
+      defaultModel: model ?? "mock-model"
+    });
+  }
+  if (clientType === "groq") {
+    return new GroqClient({
+      apiKey: opts?.apiKey,
+      defaultModel: model,
+      timeoutMs: opts?.timeoutMs
+    });
+  }
+  if (clientType === "anthropic") {
+    return new AnthropicClient({
+      apiKey: opts?.apiKey,
+      defaultModel: model,
+      timeoutMs: opts?.timeoutMs
+    });
+  }
+  throw new Error(
+    `Unknown LLM client type: "${clientType}". Valid types: "groq", "anthropic", "mock"`
+  );
+}
+
 // src/index.ts
-var version = "0.5.0";
+var version = "0.6.0";
 export {
   ACKLifecycleManager,
+  AGENT_STATE_FAILED,
+  AGENT_STATE_INITIALIZING,
+  AGENT_STATE_RUNNING,
+  AGENT_STATE_SHUTTING_DOWN,
   AckStage2 as AckStage,
   ActivityBuffer,
   ActivityBufferSync,
   ActivityClient,
   AgentState,
   AgentStateMachine,
+  AnthropicClient,
   ArtifactType,
   BaseClient,
   BordaCountAggregator,
   BufferFullError,
   CT_AGENT_REPORT_V1,
   CT_SCHEDULER_COMMAND_V1,
+  CancellationManager,
+  CancellationValidationError,
   CommunicationClass,
   ConfidenceWeightedAggregator,
   ConnectorClient,
   DEDUP_WINDOW_S,
   DEFAULT_ACK_TIMEOUT_MS,
+  DEFAULT_BACKOFF_MULTIPLIER,
+  DEFAULT_EFFECTIVE_MAX_REDIRECTS,
   DEFAULT_ESCALATION_POLICY,
   DEFAULT_EXECUTION_POLICY,
+  DEFAULT_INITIAL_BACKOFF_MS,
+  DEFAULT_MAX_BACKOFF_MS,
+  DEFAULT_MAX_REDIRECTS,
+  DEFAULT_MAX_RETRIES_ON_OVERLOADED,
   DEFAULT_NEGOTIATION_POLICY,
+  DEFAULT_PEER_LIVENESS_THRESHOLD_MS,
   DebateIntensity,
   DecisionOutcome,
   DefaultWorktreePolicy,
@@ -14185,6 +15614,9 @@ export {
   ErrorCode,
   ErrorCodeMapper,
   FileBackend,
+  GatewayRedirectEmitter,
+  GatewayValidationError,
+  GroqClient,
   HITLClient,
   HandoffClient,
   HandoffStatus,
@@ -14199,11 +15631,19 @@ export {
   JSONFilePersistence,
   JsonFilePolicyStore,
   KeyringBackend,
+  LlmAuthenticationError,
+  LlmContextLengthError,
+  LlmError,
+  LlmRateLimitError,
+  LlmTimeoutError,
   LoggingClient,
+  MIN_GRACE_PERIOD_MS,
   MajorityVoteAggregator,
   MaxEntriesStrategy,
   MessageProcessor,
   MessageType,
+  MockLlmClient,
+  NON_SERVING_AGENT_STATES,
   NegotiationClient,
   NegotiationError,
   NegotiationRoomClient,
@@ -14212,12 +15652,16 @@ export {
   NegotiationValidationError,
   NoOpAuditor,
   NodeStatus,
+  PeerSelector,
   PermissionError,
   PersistentActivityBuffer,
   PersistentWorktreeState,
   PolicyStoreError,
   PolicyViolationError,
   PreemptionError,
+  REGISTRATION_TYPE_STANDARD_AGENT,
+  REGISTRATION_TYPE_SWARM_GATEWAY,
+  RETRY_AFTER_JITTER_RATIO,
   ReasoningClient,
   RegistryClient,
   Resolver,
@@ -14240,6 +15684,7 @@ export {
   StateTransitionError,
   Sw4rmError,
   TimeoutError,
+  TokenBucket,
   ToolClient,
   TriggerType,
   ValidationError,
@@ -14255,8 +15700,10 @@ export {
   aggregateVotes,
   buildAckEnvelope,
   buildEnvelope,
+  buildRateLimiterConfig,
   computeEnvelopeHash,
   computeIdempotencyToken,
+  createLlmClient,
   createResilientIncomingStream,
   createSimpleProof,
   decodeAgentReportV1,
@@ -14265,10 +15712,12 @@ export {
   defaultEndpoints,
   defaultRetryPolicy,
   defaultSW4RMConfig,
+  delegateToSwarm,
   durationToMs,
   encodeSchedulerCommandV1,
   getConfig,
   getDefaultStore,
+  getGlobalRateLimiter,
   getValidTransitions,
   isTerminalEnvelopeState,
   isValidTransition,
@@ -14283,6 +15732,7 @@ export {
   parseNegotiationEvent,
   resetConfig,
   resetDefaultStore,
+  resetGlobalRateLimiter,
   selectBackend,
   sendMessageWithAck,
   setConfig,