@perkos/perkos-a2a 0.8.35 → 0.9.0

package/dist/index.js

@@ -18408,7 +18408,7 @@ var require_view = __commonJS({
     var dirname = path.dirname;
     var basename = path.basename;
     var extname = path.extname;
-    var join = path.join;
+    var join2 = path.join;
     var resolve = path.resolve;
     module.exports = View;
     function View(name, options) {
@@ -18456,12 +18456,12 @@ var require_view = __commonJS({
     };
     View.prototype.resolve = function resolve2(dir, file) {
       var ext = this.ext;
-      var path2 = join(dir, file);
+      var path2 = join2(dir, file);
       var stat = tryStat(path2);
       if (stat && stat.isFile()) {
         return path2;
       }
-      path2 = join(dir, basename(file, ext), "index" + ext);
+      path2 = join2(dir, basename(file, ext), "index" + ext);
       stat = tryStat(path2);
       if (stat && stat.isFile()) {
         return path2;
@@ -19094,7 +19094,7 @@ var require_send = __commonJS({
     var Stream = __require("stream");
     var util = __require("util");
     var extname = path.extname;
-    var join = path.join;
+    var join2 = path.join;
     var normalize = path.normalize;
     var resolve = path.resolve;
     var sep = path.sep;
@@ -19313,7 +19313,7 @@ var require_send = __commonJS({
           return res;
         }
         parts = path2.split(sep);
-        path2 = normalize(join(root, path2));
+        path2 = normalize(join2(root, path2));
       } else {
         if (UP_PATH_REGEXP.test(path2)) {
           debug('malicious path "%s"', path2);
@@ -19448,7 +19448,7 @@ var require_send = __commonJS({
           if (err) return self.onStatError(err);
           return self.error(404);
         }
-        var p = join(path2, self._index[i]);
+        var p = join2(path2, self._index[i]);
         debug('stat "%s"', p);
         fs.stat(p, function(err2, stat) {
           if (err2) return next(err2);
@@ -22608,6 +22608,218 @@ var require_constants = __commonJS({
   }
 });
 
+// ../../../../node_modules/node-gyp-build/node-gyp-build.js
+var require_node_gyp_build = __commonJS({
+  "../../../../node_modules/node-gyp-build/node-gyp-build.js"(exports, module) {
+    var fs = __require("fs");
+    var path = __require("path");
+    var os = __require("os");
+    var runtimeRequire = typeof __webpack_require__ === "function" ? __non_webpack_require__ : __require;
+    var vars = process.config && process.config.variables || {};
+    var prebuildsOnly = !!process.env.PREBUILDS_ONLY;
+    var abi = process.versions.modules;
+    var runtime = isElectron() ? "electron" : isNwjs() ? "node-webkit" : "node";
+    var arch = process.env.npm_config_arch || os.arch();
+    var platform = process.env.npm_config_platform || os.platform();
+    var libc = process.env.LIBC || (isAlpine(platform) ? "musl" : "glibc");
+    var armv = process.env.ARM_VERSION || (arch === "arm64" ? "8" : vars.arm_version) || "";
+    var uv = (process.versions.uv || "").split(".")[0];
+    module.exports = load;
+    function load(dir) {
+      return runtimeRequire(load.resolve(dir));
+    }
+    load.resolve = load.path = function(dir) {
+      dir = path.resolve(dir || ".");
+      try {
+        var name = runtimeRequire(path.join(dir, "package.json")).name.toUpperCase().replace(/-/g, "_");
+        if (process.env[name + "_PREBUILD"]) dir = process.env[name + "_PREBUILD"];
+      } catch (err) {
+      }
+      if (!prebuildsOnly) {
+        var release = getFirst(path.join(dir, "build/Release"), matchBuild);
+        if (release) return release;
+        var debug = getFirst(path.join(dir, "build/Debug"), matchBuild);
+        if (debug) return debug;
+      }
+      var prebuild = resolve(dir);
+      if (prebuild) return prebuild;
+      var nearby = resolve(path.dirname(process.execPath));
+      if (nearby) return nearby;
+      var target = [
+        "platform=" + platform,
+        "arch=" + arch,
+        "runtime=" + runtime,
+        "abi=" + abi,
+        "uv=" + uv,
+        armv ? "armv=" + armv : "",
+        "libc=" + libc,
+        "node=" + process.versions.node,
+        process.versions.electron ? "electron=" + process.versions.electron : "",
+        typeof __webpack_require__ === "function" ? "webpack=true" : ""
+        // eslint-disable-line
+      ].filter(Boolean).join(" ");
+      throw new Error("No native build was found for " + target + "\n    loaded from: " + dir + "\n");
+      function resolve(dir2) {
+        var tuples = readdirSync(path.join(dir2, "prebuilds")).map(parseTuple);
+        var tuple = tuples.filter(matchTuple(platform, arch)).sort(compareTuples)[0];
+        if (!tuple) return;
+        var prebuilds = path.join(dir2, "prebuilds", tuple.name);
+        var parsed = readdirSync(prebuilds).map(parseTags);
+        var candidates = parsed.filter(matchTags(runtime, abi));
+        var winner = candidates.sort(compareTags(runtime))[0];
+        if (winner) return path.join(prebuilds, winner.file);
+      }
+    };
+    function readdirSync(dir) {
+      try {
+        return fs.readdirSync(dir);
+      } catch (err) {
+        return [];
+      }
+    }
+    function getFirst(dir, filter) {
+      var files = readdirSync(dir).filter(filter);
+      return files[0] && path.join(dir, files[0]);
+    }
+    function matchBuild(name) {
+      return /\.node$/.test(name);
+    }
+    function parseTuple(name) {
+      var arr = name.split("-");
+      if (arr.length !== 2) return;
+      var platform2 = arr[0];
+      var architectures = arr[1].split("+");
+      if (!platform2) return;
+      if (!architectures.length) return;
+      if (!architectures.every(Boolean)) return;
+      return { name, platform: platform2, architectures };
+    }
+    function matchTuple(platform2, arch2) {
+      return function(tuple) {
+        if (tuple == null) return false;
+        if (tuple.platform !== platform2) return false;
+        return tuple.architectures.includes(arch2);
+      };
+    }
+    function compareTuples(a, b) {
+      return a.architectures.length - b.architectures.length;
+    }
+    function parseTags(file) {
+      var arr = file.split(".");
+      var extension2 = arr.pop();
+      var tags = { file, specificity: 0 };
+      if (extension2 !== "node") return;
+      for (var i = 0; i < arr.length; i++) {
+        var tag = arr[i];
+        if (tag === "node" || tag === "electron" || tag === "node-webkit") {
+          tags.runtime = tag;
+        } else if (tag === "napi") {
+          tags.napi = true;
+        } else if (tag.slice(0, 3) === "abi") {
+          tags.abi = tag.slice(3);
+        } else if (tag.slice(0, 2) === "uv") {
+          tags.uv = tag.slice(2);
+        } else if (tag.slice(0, 4) === "armv") {
+          tags.armv = tag.slice(4);
+        } else if (tag === "glibc" || tag === "musl") {
+          tags.libc = tag;
+        } else {
+          continue;
+        }
+        tags.specificity++;
+      }
+      return tags;
+    }
+    function matchTags(runtime2, abi2) {
+      return function(tags) {
+        if (tags == null) return false;
+        if (tags.runtime && tags.runtime !== runtime2 && !runtimeAgnostic(tags)) return false;
+        if (tags.abi && tags.abi !== abi2 && !tags.napi) return false;
+        if (tags.uv && tags.uv !== uv) return false;
+        if (tags.armv && tags.armv !== armv) return false;
+        if (tags.libc && tags.libc !== libc) return false;
+        return true;
+      };
+    }
+    function runtimeAgnostic(tags) {
+      return tags.runtime === "node" && tags.napi;
+    }
+    function compareTags(runtime2) {
+      return function(a, b) {
+        if (a.runtime !== b.runtime) {
+          return a.runtime === runtime2 ? -1 : 1;
+        } else if (a.abi !== b.abi) {
+          return a.abi ? -1 : 1;
+        } else if (a.specificity !== b.specificity) {
+          return a.specificity > b.specificity ? -1 : 1;
+        } else {
+          return 0;
+        }
+      };
+    }
+    function isNwjs() {
+      return !!(process.versions && process.versions.nw);
+    }
+    function isElectron() {
+      if (process.versions && process.versions.electron) return true;
+      if (process.env.ELECTRON_RUN_AS_NODE) return true;
+      return typeof window !== "undefined" && window.process && window.process.type === "renderer";
+    }
+    function isAlpine(platform2) {
+      return platform2 === "linux" && fs.existsSync("/etc/alpine-release");
+    }
+    load.parseTags = parseTags;
+    load.matchTags = matchTags;
+    load.compareTags = compareTags;
+    load.parseTuple = parseTuple;
+    load.matchTuple = matchTuple;
+    load.compareTuples = compareTuples;
+  }
+});
+
+// ../../../../node_modules/node-gyp-build/index.js
+var require_node_gyp_build2 = __commonJS({
+  "../../../../node_modules/node-gyp-build/index.js"(exports, module) {
+    var runtimeRequire = typeof __webpack_require__ === "function" ? __non_webpack_require__ : __require;
+    if (typeof runtimeRequire.addon === "function") {
+      module.exports = runtimeRequire.addon.bind(runtimeRequire);
+    } else {
+      module.exports = require_node_gyp_build();
+    }
+  }
+});
+
+// ../../../../node_modules/bufferutil/fallback.js
+var require_fallback = __commonJS({
+  "../../../../node_modules/bufferutil/fallback.js"(exports, module) {
+    "use strict";
+    var mask = (source, mask2, output, offset, length) => {
+      for (var i = 0; i < length; i++) {
+        output[offset + i] = source[i] ^ mask2[i & 3];
+      }
+    };
+    var unmask = (buffer, mask2) => {
+      const length = buffer.length;
+      for (var i = 0; i < length; i++) {
+        buffer[i] ^= mask2[i & 3];
+      }
+    };
+    module.exports = { mask, unmask };
+  }
+});
+
+// ../../../../node_modules/bufferutil/index.js
+var require_bufferutil = __commonJS({
+  "../../../../node_modules/bufferutil/index.js"(exports, module) {
+    "use strict";
+    try {
+      module.exports = require_node_gyp_build2()(__dirname);
+    } catch (e) {
+      module.exports = require_fallback();
+    }
+  }
+});
+
 // node_modules/ws/lib/buffer-util.js
 var require_buffer_util = __commonJS({
   "node_modules/ws/lib/buffer-util.js"(exports, module) {
@@ -22668,7 +22880,7 @@ var require_buffer_util = __commonJS({
     };
     if (!process.env.WS_NO_BUFFER_UTIL) {
       try {
-        const bufferUtil = __require("bufferutil");
+        const bufferUtil = require_bufferutil();
         module.exports.mask = function(source, mask, output, offset, length) {
           if (length < 48) _mask(source, mask, output, offset, length);
           else bufferUtil.mask(source, mask, output, offset, length);
@@ -23116,6 +23328,55 @@ var require_permessage_deflate = __commonJS({
   }
 });
 
+// ../../../../node_modules/utf-8-validate/fallback.js
+var require_fallback2 = __commonJS({
+  "../../../../node_modules/utf-8-validate/fallback.js"(exports, module) {
+    "use strict";
+    function isValidUTF8(buf) {
+      const len = buf.length;
+      let i = 0;
+      while (i < len) {
+        if ((buf[i] & 128) === 0) {
+          i++;
+        } else if ((buf[i] & 224) === 192) {
+          if (i + 1 === len || (buf[i + 1] & 192) !== 128 || (buf[i] & 254) === 192) {
+            return false;
+          }
+          i += 2;
+        } else if ((buf[i] & 240) === 224) {
+          if (i + 2 >= len || (buf[i + 1] & 192) !== 128 || (buf[i + 2] & 192) !== 128 || buf[i] === 224 && (buf[i + 1] & 224) === 128 || // overlong
+          buf[i] === 237 && (buf[i + 1] & 224) === 160) {
+            return false;
+          }
+          i += 3;
+        } else if ((buf[i] & 248) === 240) {
+          if (i + 3 >= len || (buf[i + 1] & 192) !== 128 || (buf[i + 2] & 192) !== 128 || (buf[i + 3] & 192) !== 128 || buf[i] === 240 && (buf[i + 1] & 240) === 128 || // overlong
+          buf[i] === 244 && buf[i + 1] > 143 || buf[i] > 244) {
+            return false;
+          }
+          i += 4;
+        } else {
+          return false;
+        }
+      }
+      return true;
+    }
+    module.exports = isValidUTF8;
+  }
+});
+
+// ../../../../node_modules/utf-8-validate/index.js
+var require_utf_8_validate = __commonJS({
+  "../../../../node_modules/utf-8-validate/index.js"(exports, module) {
+    "use strict";
+    try {
+      module.exports = require_node_gyp_build2()(__dirname);
+    } catch (e) {
+      module.exports = require_fallback2();
+    }
+  }
+});
+
 // node_modules/ws/lib/validation.js
 var require_validation = __commonJS({
   "node_modules/ws/lib/validation.js"(exports, module) {
@@ -23307,7 +23568,7 @@ var require_validation = __commonJS({
       };
     } else if (!process.env.WS_NO_UTF_8_VALIDATE) {
       try {
-        const isValidUTF8 = __require("utf-8-validate");
+        const isValidUTF8 = require_utf_8_validate();
         module.exports.isValidUTF8 = function(buf) {
           return buf.length < 32 ? _isValidUTF8(buf) : isValidUTF8(buf);
         };
@@ -24793,7 +25054,7 @@ var require_websocket = __commonJS({
     var http = __require("http");
     var net = __require("net");
     var tls = __require("tls");
-    var { randomBytes, createHash } = __require("crypto");
+    var { randomBytes, createHash: createHash2 } = __require("crypto");
     var { Duplex, Readable } = __require("stream");
     var { URL: URL2 } = __require("url");
     var PerMessageDeflate2 = require_permessage_deflate();
@@ -25453,7 +25714,7 @@ var require_websocket = __commonJS({
           abortHandshake(websocket, socket, "Invalid Upgrade header");
           return;
         }
-        const digest = createHash("sha1").update(key + GUID).digest("base64");
+        const digest = createHash2("sha1").update(key + GUID).digest("base64");
         if (res.headers["sec-websocket-accept"] !== digest) {
           abortHandshake(websocket, socket, "Invalid Sec-WebSocket-Accept header");
           return;
@@ -25732,7 +25993,7 @@ var require_stream = __commonJS({
       };
       duplex._final = function(callback) {
         if (ws.readyState === ws.CONNECTING) {
-          ws.once("open", function open() {
+          ws.once("open", function open2() {
             duplex._final(callback);
           });
           return;
@@ -25753,7 +26014,7 @@ var require_stream = __commonJS({
       };
       duplex._write = function(chunk, encoding, callback) {
         if (ws.readyState === ws.CONNECTING) {
-          ws.once("open", function open() {
+          ws.once("open", function open2() {
             duplex._write(chunk, encoding, callback);
           });
           return;
@@ -25820,7 +26081,7 @@ var require_websocket_server = __commonJS({
     var EventEmitter = __require("events");
     var http = __require("http");
     var { Duplex } = __require("stream");
-    var { createHash } = __require("crypto");
+    var { createHash: createHash2 } = __require("crypto");
     var extension2 = require_extension();
     var PerMessageDeflate2 = require_permessage_deflate();
     var subprotocol2 = require_subprotocol();
@@ -26121,7 +26382,7 @@ var require_websocket_server = __commonJS({
           );
         }
         if (this._state > RUNNING) return abortHandshake(socket, 503);
-        const digest = createHash("sha1").update(key + GUID).digest("base64");
+        const digest = createHash2("sha1").update(key + GUID).digest("base64");
         const headers = [
           "HTTP/1.1 101 Switching Protocols",
           "Upgrade: websocket",
@@ -27261,8 +27522,8 @@ var A2AServer = class {
       const task = response.result;
       if (task?.id && !isTerminalTaskState(task.status?.state)) {
         const terminal = await this.waitForLocalTaskTerminal(task.id).catch((err) => {
-          const errMsg = err instanceof Error ? err.message : String(err);
-          this.logger.info(`[perkos-a2a] Waiting for relay task ${task.id} terminal state failed: ${errMsg}`);
+          const errMsg2 = err instanceof Error ? err.message : String(err);
+          this.logger.info(`[perkos-a2a] Waiting for relay task ${task.id} terminal state failed: ${errMsg2}`);
           return null;
         });
         if (terminal) {
@@ -27272,9 +27533,9 @@ var A2AServer = class {
       }
       this.relayClient?.sendTaskResponse(msg, response);
     }).catch((err) => {
-      const errMsg = err instanceof Error ? err.message : String(err);
-      this.logger.error(`[perkos-a2a] Failed to process relay task: ${errMsg}`);
-      this.relayClient?.sendTaskResponse(msg, this.error(rpcId, -32603, errMsg));
+      const errMsg2 = err instanceof Error ? err.message : String(err);
+      this.logger.error(`[perkos-a2a] Failed to process relay task: ${errMsg2}`);
+      this.relayClient?.sendTaskResponse(msg, this.error(rpcId, -32603, errMsg2));
     });
   }
   startRelayClient() {
@@ -27390,7 +27651,7 @@ var A2AServer = class {
 };
 
 // src/index.ts
-import { randomUUID as randomUUID5 } from "crypto";
+import { randomUUID as randomUUID6 } from "crypto";
 
 // src/agentic-actions.ts
 var FALLBACK_AGENT_ALIASES = [
@@ -27805,6 +28066,550 @@ ${replyResultText2}` : void 0,
   return true;
 }
 
+// src/chat-client.ts
+import { randomUUID as randomUUID5 } from "node:crypto";
+
+// src/chat-store.ts
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import {
+  appendFile,
+  mkdir,
+  open,
+  readFile,
+  writeFile
+} from "node:fs/promises";
+import { homedir as homedir2 } from "node:os";
+import { join } from "node:path";
+function safeConvId(convId) {
+  if (!/^[A-Za-z0-9_-]{1,128}$/.test(convId)) {
+    throw new Error(`invalid convId: ${convId}`);
+  }
+  return convId;
+}
+var ChatStore = class {
+  root;
+  constructor(options = {}) {
+    this.root = options.storeRoot ?? join(homedir2(), ".perkos", "conversations");
+  }
+  /** Directory for a single conversation. */
+  dirFor(convId) {
+    return join(this.root, safeConvId(convId));
+  }
+  /** Path to the JSONL log for a conv. */
+  jsonlPath(convId) {
+    return join(this.dirFor(convId), "messages.jsonl");
+  }
+  /** Path to the metadata file for a conv. */
+  metaPath(convId) {
+    return join(this.dirFor(convId), "metadata.json");
+  }
+  /** Ensure the conv directory exists. Idempotent. */
+  async ensureDir(convId) {
+    await mkdir(this.dirFor(convId), { recursive: true });
+  }
+  /**
+   * Write metadata for a conversation. Called on `channel_join` so the agent
+   * has a local record of which participants belong to a conv.
+   */
+  async writeMetadata(meta) {
+    await this.ensureDir(meta.convId);
+    await writeFile(this.metaPath(meta.convId), JSON.stringify(meta, null, 2));
+  }
+  async readMetadata(convId) {
+    try {
+      const raw = await readFile(this.metaPath(convId), "utf8");
+      return JSON.parse(raw);
+    } catch (err) {
+      if (isNotFound(err)) return null;
+      throw err;
+    }
+  }
+  /**
+   * Append a message to the conversation log. The line written is exactly
+   * `JSON.stringify(msg) + "\n"`. The store does not validate ordering; if
+   * messages arrive out of timestamp order, that is recorded as-is.
+   */
+  async append(convId, msg) {
+    await this.ensureDir(convId);
+    await appendFile(this.jsonlPath(convId), JSON.stringify(msg) + "\n");
+  }
+  /**
+   * Read a history page, reverse-chronological. Returns messages with
+   * timestamp strictly less than `before` (if provided), up to `limit`.
+   *
+   * The output order is chronological ascending — i.e. callers can `concat`
+   * pages from oldest to newest without sorting.
+   */
+  async readPage(convId, opts) {
+    const limit = Math.max(1, Math.min(500, opts.limit));
+    const before = opts.before ?? null;
+    let lines;
+    try {
+      const raw = await readFile(this.jsonlPath(convId), "utf8");
+      lines = raw.split("\n").filter((l) => l.length > 0);
+    } catch (err) {
+      if (isNotFound(err)) return { messages: [], hasMore: false };
+      throw err;
+    }
+    const collected = [];
+    let hasMore = false;
+    for (let i = lines.length - 1; i >= 0; i--) {
+      let msg;
+      try {
+        msg = JSON.parse(lines[i]);
+      } catch {
+        continue;
+      }
+      if (before && msg.timestamp >= before) continue;
+      if (collected.length >= limit) {
+        hasMore = true;
+        break;
+      }
+      collected.push(msg);
+    }
+    return { messages: collected.reverse(), hasMore };
+  }
+  /**
+   * Produce a tamper-evident summary of the conversation log for receipt
+   * issuance. Streams `messages.jsonl` through sha256 (followed by a
+   * separator + metadata.json content if present), so memory usage stays
+   * constant regardless of conv size.
+   *
+   * The hash is deterministic: same jsonl bytes → same hex string. A
+   * downstream verifier with the jsonl can recompute and confirm.
+   *
+   * Returns counts + first/last timestamps for the receipt manifest.
+   */
+  async computeReceipt(convId) {
+    const path = this.jsonlPath(convId);
+    try {
+      const fd = await open(path, "r");
+      await fd.close();
+    } catch (err) {
+      if (isNotFound(err)) return null;
+      throw err;
+    }
+    const stream = createReadStream(path, { encoding: "utf8", highWaterMark: 64 * 1024 });
+    const hash = createHash("sha256");
+    let messageCount = 0;
+    let firstMessageAt = null;
+    let lastMessageAt = null;
+    let leftover = "";
+    return new Promise((resolve, reject) => {
+      stream.on("data", (chunk) => {
+        const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        hash.update(text);
+        const combined = leftover + text;
+        const lines = combined.split("\n");
+        leftover = lines.pop() ?? "";
+        for (const line of lines) {
+          if (!line) continue;
+          messageCount++;
+          try {
+            const parsed = JSON.parse(line);
+            const ts = parsed.timestamp;
+            if (typeof ts === "string") {
+              if (firstMessageAt === null || ts < firstMessageAt) firstMessageAt = ts;
+              if (lastMessageAt === null || ts > lastMessageAt) lastMessageAt = ts;
+            }
+          } catch {
+          }
+        }
+      });
+      stream.on("end", async () => {
+        if (leftover.length > 0) {
+          messageCount++;
+          try {
+            const parsed = JSON.parse(leftover);
+            const ts = parsed.timestamp;
+            if (typeof ts === "string") {
+              if (firstMessageAt === null || ts < firstMessageAt) firstMessageAt = ts;
+              if (lastMessageAt === null || ts > lastMessageAt) lastMessageAt = ts;
+            }
+          } catch {
+          }
+        }
+        try {
+          const metaRaw = await readFile(this.metaPath(convId), "utf8");
+          hash.update("");
+          hash.update(metaRaw);
+        } catch {
+        }
+        resolve({
+          transcriptHash: hash.digest("hex"),
+          hashAlgo: "sha256",
+          messageCount,
+          firstMessageAt,
+          lastMessageAt
+        });
+      });
+      stream.on("error", (err) => reject(err));
+    });
+  }
+  /**
+   * Return the number of messages in the log. Useful for tests and stats.
+   * Avoid using this on the hot path — it reads the full file.
+   */
+  async count(convId) {
+    let fd;
+    try {
+      fd = await open(this.jsonlPath(convId), "r");
+    } catch (err) {
+      if (isNotFound(err)) return 0;
+      throw err;
+    }
+    try {
+      const raw = await fd.readFile({ encoding: "utf8" });
+      return raw.split("\n").filter((l) => l.length > 0).length;
+    } finally {
+      await fd.close();
+    }
+  }
+};
+function isNotFound(err) {
+  return !!err && typeof err === "object" && err.code === "ENOENT";
+}
+
+// src/chat-client.ts
+var DEFAULT_URL = "wss://chat.perkos.xyz/chat";
+var DEFAULT_HISTORY_LIMIT = 50;
+var DEFAULT_MIN_RECONNECT = 1e3;
+var DEFAULT_MAX_RECONNECT = 6e4;
+var DEFAULT_HEARTBEAT_MS = 25e3;
+var AUTH_TIMEOUT_MS = 1e4;
+var ChatClient = class {
+  ws = null;
+  config;
+  agentName;
+  handlers;
+  logger;
+  store;
+  reconnectMs;
+  reconnectTimer = null;
+  heartbeatTimer = null;
+  connected = false;
+  authed = false;
+  stopped = false;
+  constructor(opts) {
+    this.agentName = opts.agentName;
+    const cfg = opts.config;
+    this.config = {
+      enabled: cfg.enabled,
+      url: cfg.url || DEFAULT_URL,
+      apiKey: cfg.apiKey,
+      storeRoot: cfg.storeRoot,
+      defaultHistoryLimit: cfg.defaultHistoryLimit ?? DEFAULT_HISTORY_LIMIT,
+      minReconnectMs: cfg.minReconnectMs ?? DEFAULT_MIN_RECONNECT,
+      maxReconnectMs: cfg.maxReconnectMs ?? DEFAULT_MAX_RECONNECT,
+      heartbeatIntervalMs: cfg.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_MS
+    };
+    this.handlers = opts.handlers ?? {};
+    this.logger = this.handlers.logger ?? { info: console.log, error: console.error };
+    this.store = new ChatStore({ storeRoot: this.config.storeRoot });
+    this.reconnectMs = this.config.minReconnectMs;
+  }
+  /** Storage handle — exposed so consumers can read history without going through the wire. */
+  getStore() {
+    return this.store;
+  }
+  isConnected() {
+    return this.connected && this.authed;
+  }
+  start() {
+    if (!this.config.enabled) {
+      this.logger.info("[perkos-chat] disabled in config; not connecting");
+      return;
+    }
+    if (!this.config.apiKey) {
+      this.logger.error("[perkos-chat] missing apiKey; cannot connect");
+      return;
+    }
+    this.stopped = false;
+    this.connect();
+  }
+  stop() {
+    this.stopped = true;
+    this.clearTimers();
+    if (this.ws) {
+      try {
+        this.ws.close(1e3, "client shutting down");
+      } catch {
+      }
+      this.ws = null;
+    }
+    this.connected = false;
+    this.authed = false;
+  }
+  /**
+   * Send a reply from this agent into a conversation. Appends to the local
+   * store optimistically, then sends to the server. If the WS is offline,
+   * the local store is still updated and the message is dropped from the
+   * wire — callers should re-send after reconnect if guaranteed delivery is
+   * required (the simple agent loop should just regenerate from history).
+   */
+  async sendReply(opts) {
+    const id = randomUUID5();
+    const msg = {
+      id,
+      from: `agent:${this.agentName}`,
+      text: opts.text,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      replyTo: opts.replyTo ?? null
+    };
+    await this.store.append(opts.convId, msg);
+    const frame = {
+      type: "chat_reply",
+      id,
+      convId: opts.convId,
+      walletAddress: opts.walletAddress,
+      text: opts.text,
+      replyTo: opts.replyTo ?? null
+    };
+    const delivered = this.sendFrame(frame);
+    return { id, delivered };
+  }
+  // -------------------------------------------------------------------------
+  // WebSocket lifecycle
+  // -------------------------------------------------------------------------
+  connect() {
+    if (this.stopped) return;
+    const url = this.config.url;
+    this.logger.info(`[perkos-chat] connecting to ${url}`);
+    try {
+      this.ws = new wrapper_default(url);
+    } catch (err) {
+      this.logger.error(`[perkos-chat] failed to construct WS: ${errMsg(err)}`);
+      this.scheduleReconnect();
+      return;
+    }
+    let authTimer = setTimeout(() => {
+      if (!this.authed) {
+        this.logger.error("[perkos-chat] auth timeout");
+        try {
+          this.ws?.close(4002, "auth timeout");
+        } catch {
+        }
+      }
+    }, AUTH_TIMEOUT_MS);
+    this.ws.on("open", () => {
+      this.connected = true;
+      this.reconnectMs = this.config.minReconnectMs;
+      this.sendFrame({
+        type: "auth",
+        role: "agent",
+        agentName: this.agentName,
+        apiKey: this.config.apiKey
+      });
+    });
+    this.ws.on("message", (data) => {
+      let frame;
+      try {
+        frame = JSON.parse(data.toString("utf8"));
+      } catch {
+        this.logger.error("[perkos-chat] failed to parse frame");
+        return;
+      }
+      if (authTimer) {
+        clearTimeout(authTimer);
+        authTimer = null;
+      }
+      void this.handleFrame(frame);
+    });
+    this.ws.on("close", (code, reason) => {
+      this.connected = false;
+      this.authed = false;
+      this.clearTimers();
+      if (authTimer) {
+        clearTimeout(authTimer);
+        authTimer = null;
+      }
+      if (!this.stopped) {
+        this.logger.info(`[perkos-chat] disconnected (${code}: ${reason?.toString() || "no reason"}); reconnecting`);
+        this.scheduleReconnect();
+      }
+    });
+    this.ws.on("error", (err) => {
+      this.logger.error(`[perkos-chat] WS error: ${errMsg(err)}`);
+    });
+  }
+  async handleFrame(frame) {
+    switch (frame.type) {
+      case "auth_ok":
+        this.authed = true;
+        this.logger.info(`[perkos-chat] authed as agent:${this.agentName}`);
+        this.startHeartbeat();
+        return;
+      case "auth_error":
+        this.logger.error(`[perkos-chat] auth_error ${frame.code}: ${frame.message}`);
+        try {
+          this.ws?.close(4401, frame.code);
+        } catch {
+        }
+        return;
+      case "chat_deliver":
+      case "chat_message": {
+        await this.persistInbound(frame);
+        if (this.handlers.onChatDeliver) {
+          try {
+            await this.handlers.onChatDeliver(frame);
+          } catch (err) {
+            this.logger.error(`[perkos-chat] onChatDeliver threw: ${errMsg(err)}`);
+          }
+        }
+        return;
+      }
+      case "history_request":
+        await this.respondToHistoryRequest(frame);
+        return;
+      case "receipt_request":
+        await this.respondToReceiptRequest(frame);
+        return;
+      case "channel_join":
+        await this.handleChannelJoin(frame);
+        return;
+      case "ack":
+      case "pong":
+      case "typing":
+        return;
+      case "error":
+        this.logger.error(`[perkos-chat] server error ${frame.code}: ${frame.message}`);
+        return;
+      default:
+        this.logger.info(`[perkos-chat] unknown frame type: ${frame.type}`);
+    }
+  }
+  async persistInbound(frame) {
+    const msg = {
+      id: frame.id,
+      from: frame.from,
+      text: frame.text,
+      timestamp: frame.timestamp,
+      replyTo: "replyTo" in frame ? frame.replyTo ?? null : null
+    };
+    try {
+      await this.store.append(frame.convId, msg);
+    } catch (err) {
+      this.logger.error(`[perkos-chat] failed to append to store: ${errMsg(err)}`);
+    }
+  }
+  async handleChannelJoin(frame) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const existing = await this.store.readMetadata(frame.convId);
+    const meta = {
+      convId: frame.convId,
+      participants: frame.participants,
+      historyHost: frame.historyHost,
+      createdAt: existing?.createdAt ?? now,
+      updatedAt: now
+    };
+    try {
+      await this.store.writeMetadata(meta);
+    } catch (err) {
+      this.logger.error(`[perkos-chat] failed to write metadata for ${frame.convId}: ${errMsg(err)}`);
+    }
+    if (this.handlers.onChannelJoin) {
+      try {
+        await this.handlers.onChannelJoin(frame);
+      } catch (err) {
+        this.logger.error(`[perkos-chat] onChannelJoin threw: ${errMsg(err)}`);
+      }
+    }
+  }
+  async respondToReceiptRequest(frame) {
+    let summary;
+    try {
+      summary = await this.store.computeReceipt(frame.convId);
+    } catch (err) {
+      this.logger.error(`[perkos-chat] receipt computation failed: ${errMsg(err)}`);
+      return;
+    }
+    if (!summary) {
+      this.sendFrame({
+        type: "receipt_response",
+        id: frame.id,
+        convId: frame.convId,
+        forWallet: frame.forWallet,
+        transcriptHash: "",
+        hashAlgo: "sha256",
+        messageCount: 0,
+        firstMessageAt: null,
+        lastMessageAt: null,
+        generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      return;
+    }
+    this.sendFrame({
+      type: "receipt_response",
+      id: frame.id,
+      convId: frame.convId,
+      forWallet: frame.forWallet,
+      transcriptHash: summary.transcriptHash,
+      hashAlgo: summary.hashAlgo,
+      messageCount: summary.messageCount,
+      firstMessageAt: summary.firstMessageAt,
+      lastMessageAt: summary.lastMessageAt,
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  async respondToHistoryRequest(frame) {
+    const limit = frame.limit ?? this.config.defaultHistoryLimit;
+    let page;
+    try {
+      page = await this.store.readPage(frame.convId, { before: frame.before ?? null, limit });
+    } catch (err) {
+      this.logger.error(`[perkos-chat] history read failed: ${errMsg(err)}`);
+      page = { messages: [], hasMore: false };
+    }
+    this.sendFrame({
+      type: "history_chunk",
+      id: frame.id,
+      convId: frame.convId,
+      forWallet: frame.forWallet,
+      messages: page.messages,
+      hasMore: page.hasMore
+    });
+  }
+  sendFrame(frame) {
+    if (this.ws && this.ws.readyState === wrapper_default.OPEN) {
+      this.ws.send(JSON.stringify(frame));
+      return true;
+    }
+    return false;
+  }
+  startHeartbeat() {
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+    this.heartbeatTimer = setInterval(() => {
+      if (!this.sendFrame({ type: "ping" })) {
+      }
+    }, this.config.heartbeatIntervalMs);
+  }
+  scheduleReconnect() {
+    if (this.stopped) return;
+    const delay = this.reconnectMs;
+    this.reconnectTimer = setTimeout(() => this.connect(), delay);
+    this.reconnectMs = Math.min(delay * 2, this.config.maxReconnectMs);
+  }
+  clearTimers() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+};
+function errMsg(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/types.ts
+function isWebhookEvent(msg) {
+  return msg.type === "webhook_event";
+}
+
 // src/index.ts
 function wakeGatewayAgent(requestHeartbeatNow, reason, logger, sessionKey = "agent:main") {
   if (typeof requestHeartbeatNow === "function") {
@@ -27827,6 +28632,11 @@ function openclawEventSessionKey(config) {
   if (!key) return "agent:main:main";
   return key.endsWith(":main") ? key : `${key}:main`;
 }
+function parseWalletFromIdentity(identity) {
+  if (typeof identity !== "string" || !identity.startsWith("user:")) return null;
+  const addr = identity.slice("user:".length);
+  return addr.startsWith("0x") ? addr.toLowerCase() : null;
+}
 async function deliverToHermes(config, message, logger) {
   const runtime = config.runtime || {};
   const baseUrl = (runtime.hermesUrl || "http://127.0.0.1:8642").replace(/\/+$/, "");
@@ -27916,7 +28726,7 @@ function register(api) {
       await deliverToHermes(pluginConfig, eventText, logger);
       task.artifacts.push({
         kind: "artifact",
-        artifactId: randomUUID5(),
+        artifactId: randomUUID6(),
         parts: [{ kind: "text", text: `debug: delivered task ${task.id} to Hermes API Server` }]
       });
       const finalText2 = await generateRuntimeReply(pluginConfig, text, marker);
@@ -27926,14 +28736,14 @@ function register(api) {
     if (runtimeKind === "none") {
       task.artifacts.push({
         kind: "artifact",
-        artifactId: randomUUID5(),
+        artifactId: randomUUID6(),
         parts: [{ kind: "text", text: `debug: runtime delivery disabled for ${marker}` }]
       });
       return;
     }
     task.artifacts.push({
       kind: "artifact",
-      artifactId: randomUUID5(),
+      artifactId: randomUUID6(),
       parts: [{ kind: "text", text: `debug: enqueued system event for ${marker}` }]
     });
     if (enqueueSystemEvent) {
@@ -28017,7 +28827,7 @@ function register(api) {
       if (!finalText) continue;
       task.artifacts.push({
         kind: "artifact",
-        artifactId: randomUUID5(),
+        artifactId: randomUUID6(),
         parts: [{ kind: "text", text: finalText }]
       });
       task.status = {
@@ -28041,6 +28851,83 @@ function register(api) {
       logger.info("[perkos-a2a] A2A server stopping");
     }
   });
+  const chatApiKey = pluginConfig.chat?.apiKey || pluginConfig.relay?.apiKey;
+  const chatClient = pluginConfig.chat?.enabled && chatApiKey ? new ChatClient({
+    agentName: pluginConfig.agentName,
+    config: {
+      enabled: true,
+      url: pluginConfig.chat?.url || "wss://chat.perkos.xyz/chat",
+      apiKey: chatApiKey,
+      storeRoot: pluginConfig.chat?.storeRoot,
+      defaultHistoryLimit: pluginConfig.chat?.defaultHistoryLimit,
+      minReconnectMs: pluginConfig.chat?.minReconnectMs,
+      maxReconnectMs: pluginConfig.chat?.maxReconnectMs,
+      heartbeatIntervalMs: pluginConfig.chat?.heartbeatIntervalMs
+    },
+    handlers: {
+      logger,
+      onChatDeliver: async (frame) => {
+        const walletAddress = parseWalletFromIdentity(frame.from);
+        const marker = `[PERKOS_CHAT:${frame.convId}]`;
+        const eventText = [
+          marker,
+          `From: ${frame.from}`,
+          `Conversation: ${frame.convId}`,
+          walletAddress ? `Wallet: ${walletAddress}` : "",
+          "",
+          "A user is messaging you in a PerkOS chat conversation.",
+          "To respond, call the `perkos_chat_reply` tool with:",
+          `  convId: "${frame.convId}"`,
+          walletAddress ? `  walletAddress: "${walletAddress}"` : `  walletAddress: <derived from From>`,
+          `  text: <your reply>`,
+          "",
+          "Message body:",
+          frame.text
+        ].filter(Boolean).join("\n");
+        const runtimeKind = pluginConfig.runtime?.kind || "openclaw";
+        if (runtimeKind === "hermes" || runtimeKind === "hermes-api") {
+          try {
+            await deliverToHermes(pluginConfig, eventText, logger);
+          } catch (err) {
+            logger.error(`[perkos-chat] hermes delivery failed: ${err instanceof Error ? err.message : String(err)}`);
+          }
+          return;
+        }
+        if (runtimeKind === "none") {
+          logger.info(`[perkos-chat] dropped chat_deliver for ${frame.convId} (runtime=none)`);
+          return;
+        }
+        if (enqueueSystemEvent) {
+          enqueueSystemEvent(eventText, { sessionKey: openclawEventSessionKey(pluginConfig) });
+        }
+        wakeGatewayAgent(
+          requestHeartbeatNow,
+          `[PerkOS-Chat] inbound message in ${frame.convId}`,
+          logger,
+          openclawWakeSessionKey(pluginConfig)
+        );
+      },
+      onChannelJoin: async (frame) => {
+        logger.info(`[perkos-chat] joined conv ${frame.convId} (host: ${frame.historyHost}, ${frame.participants.length} participants)`);
+      }
+    }
+  }) : null;
+  if (pluginConfig.chat?.enabled && !chatApiKey) {
+    logger.error("[perkos-chat] chat.enabled=true but no apiKey (set chat.apiKey or fall back from relay.apiKey)");
+  }
+  if (chatClient) {
+    api.registerService({
+      id: "perkos-a2a-chat",
+      start: () => {
+        chatClient.start();
+        logger.info(`[perkos-chat] client started for ${pluginConfig.agentName}`);
+      },
+      stop: () => {
+        chatClient.stop();
+        logger.info("[perkos-chat] client stopped");
+      }
+    });
+  }
   api.registerTool({
     name: "perkos_a2a_send",
     description: "Send a task to another agent via PerkOS A2A. Use this to delegate work, ask a peer to research, or route a chain/circular workflow. The message may name additional agents and a final notification target; the bridge preserves the route and prevents loops.",
@@ -28201,6 +29088,102 @@ function register(api) {
       }
     }
   });
+  api.registerTool({
+    name: "perkos_chat_reply",
+    description: "Send a reply into a PerkOS chat conversation. Use this when a user (or another agent) sent a chat message you should respond to. The system event that woke you contains `Conversation: <convId>` and `Wallet: <walletAddress>` lines you can copy directly. The reply is appended to local history first, then sent on the wire \u2014 so it's preserved even if the chat server is briefly unreachable.",
+    parameters: {
+      type: "object",
+      properties: {
+        convId: {
+          type: "string",
+          description: "Conversation id (UUID) \u2014 found in the [PERKOS_CHAT:<convId>] marker."
+        },
+        walletAddress: {
+          type: "string",
+          description: "Wallet that owns the conversation. From the `Wallet:` line of the system event."
+        },
+        text: {
+          type: "string",
+          description: "Reply body. Markdown supported."
+        },
+        replyTo: {
+          type: "string",
+          description: "Optional id of the inbound message you are replying to."
+        }
+      },
+      required: ["convId", "walletAddress", "text"]
+    },
+    async execute(_id, params) {
+      if (!chatClient) {
+        return {
+          content: [{ type: "text", text: "PerkOS-Chat client is not enabled in this agent's config." }]
+        };
+      }
+      try {
+        const result = await chatClient.sendReply({
+          convId: params.convId,
+          walletAddress: params.walletAddress,
+          text: params.text,
+          replyTo: params.replyTo ?? null
+        });
+        return {
+          content: [{
+            type: "text",
+            text: [
+              `Reply ${result.delivered ? "delivered" : "queued (offline)"}.`,
+              `Message id: ${result.id}`,
+              `Conv: ${params.convId}`
+            ].join("\n")
+          }]
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Error sending chat reply: ${msg}` }] };
+      }
+    }
+  });
+  api.registerTool({
+    name: "perkos_chat_history",
+    description: "Read recent messages from a PerkOS chat conversation (this agent's local store). Returns up to `limit` messages older than `before` (ISO timestamp), most-recent-first ordered by timestamp. Use this to recall context before composing a reply.",
+    parameters: {
+      type: "object",
+      properties: {
+        convId: { type: "string", description: "Conversation id (UUID)." },
+        before: {
+          type: "string",
+          description: "Optional ISO timestamp; only messages strictly older than this are returned. Omit to get the newest page."
+        },
+        limit: {
+          type: "number",
+          description: "Max messages to return (1-500, default 50)."
+        }
+      },
+      required: ["convId"]
+    },
+    async execute(_id, params) {
+      if (!chatClient) {
+        return {
+          content: [{ type: "text", text: "PerkOS-Chat client is not enabled in this agent's config." }]
+        };
+      }
+      try {
+        const store = chatClient.getStore();
+        const page = await store.readPage(params.convId, {
+          before: params.before ?? null,
+          limit: params.limit ?? 50
+        });
+        if (page.messages.length === 0) {
+          return { content: [{ type: "text", text: `No messages found in ${params.convId}.` }] };
+        }
+        const lines = page.messages.map((m) => `[${m.timestamp}] ${m.from}: ${m.text}`);
+        if (page.hasMore) lines.push("", "(older messages available \u2014 call again with `before` set to the earliest timestamp)");
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Error reading chat history: ${msg}` }] };
+      }
+    }
+  });
   api.registerGatewayMethod("perkos-a2a.status", ({ respond }) => {
     respond(true, {
       agent: pluginConfig.agentName,
@@ -28213,7 +29196,12 @@ function register(api) {
       pendingTasks: pendingTasks.length,
       hasSystemEventInjection: !!enqueueSystemEvent,
       protocol: "a2a",
-      version: "0.8.4"
+      version: "0.8.4",
+      chat: chatClient ? {
+        enabled: true,
+        connected: chatClient.isConnected(),
+        url: pluginConfig.chat?.url || "wss://chat.perkos.xyz/chat"
+      } : { enabled: false, connected: false, url: null }
     });
   });
   api.registerCli(
@@ -28229,6 +29217,11 @@ function register(api) {
         console.log(`Auth required: ${pluginConfig.auth?.requireApiKey || false}`);
         console.log(`Peers: ${Object.keys(pluginConfig.peers).join(", ") || "(none)"}`);
         console.log(`System event injection: ${!!enqueueSystemEvent}`);
+        if (chatClient) {
+          console.log(`Chat: enabled (connected=${chatClient.isConnected()}, url=${pluginConfig.chat?.url || "wss://chat.perkos.xyz/chat"})`);
+        } else {
+          console.log("Chat: disabled");
+        }
       });
       cmd.command("discover").description("Discover peer agents").action(async () => {
         const peers = await server.discoverPeers();
@@ -28312,10 +29305,13 @@ Relay: ${pluginConfig.relay?.enabled ? "enabled" : "disabled"}`);
 }
 export {
   A2AServer,
+  ChatClient,
+  ChatStore,
   RelayClient,
   RelayHub,
   register as default,
-  detectNetworking
+  detectNetworking,
+  isWebhookEvent
 };
 /*! Bundled license information: