@perkos/perkos-a2a 0.9.0 → 0.9.2

package/dist/chat-client.js

@@ -0,0 +1,364 @@
+/**
+ * PerkOS-Chat client.
+ *
+ * Connects an agent to `wss://chat.perkos.xyz/chat`. Handles auth, automatic
+ * reconnect with exponential backoff, heartbeat, persistent JSONL storage of
+ * incoming and outgoing messages, and history pagination.
+ *
+ * This is a sibling of `RelayClient` (which speaks the A2A task protocol).
+ * Same runtime conventions, different wire format — chat uses framed JSON
+ * with role-aware auth instead of A2A JSON-RPC.
+ *
+ * Companion server: github.com/PerkOS-xyz/PerkOS-Chat
+ */
+import { randomUUID } from "node:crypto";
+import WebSocket from "ws";
+import { ChatStore } from "./chat-store.js";
+const DEFAULT_URL = "wss://chat.perkos.xyz/chat";
+const DEFAULT_HISTORY_LIMIT = 50;
+const DEFAULT_MIN_RECONNECT = 1_000;
+const DEFAULT_MAX_RECONNECT = 60_000;
+const DEFAULT_HEARTBEAT_MS = 25_000;
+const AUTH_TIMEOUT_MS = 10_000;
+export class ChatClient {
+    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(1000, "client shutting down");
+            }
+            catch { /* ignore */ }
+            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 = randomUUID();
+        const msg = {
+            id,
+            from: `agent:${this.agentName}`,
+            text: opts.text,
+            timestamp: 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 WebSocket(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 { /* ignore */ }
+            }
+        }, 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 { /* ignore */ }
+                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:
+                // Unknown — log for visibility but don't blow up
+                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 = 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) {
+            // No jsonl for this conv → nothing to hash. Reply with an empty hash
+            // so the user sees a definitive "no content" rather than a timeout.
+            this.sendFrame({
+                type: "receipt_response",
+                id: frame.id,
+                convId: frame.convId,
+                forWallet: frame.forWallet,
+                transcriptHash: "",
+                hashAlgo: "sha256",
+                messageCount: 0,
+                firstMessageAt: null,
+                lastMessageAt: null,
+                generatedAt: 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: 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 === WebSocket.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" })) {
+                // Socket gone; close() will trigger reconnect.
+            }
+        }, 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);
+}
+//# sourceMappingURL=chat-client.js.map

package/dist/chat-client.js.map

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

package/dist/chat-store.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Append-only JSONL store for PerkOS chat conversations.
+ *
+ * Files live at:
+ *   <storeRoot>/<convId>/messages.jsonl
+ *   <storeRoot>/<convId>/metadata.json
+ *
+ * Privacy invariant: this is the canonical record of conversation content.
+ * The PerkOS cloud (Firestore) holds only metadata (title, participants,
+ * lastMessageAt). Bodies live exclusively here, on the agent's filesystem.
+ */
+import type { ChatIdentity, ChatMessage } from "./chat-types.js";
+export interface ConversationMetadata {
+    convId: string;
+    participants: ChatIdentity[];
+    historyHost: ChatIdentity;
+    /** ISO timestamp recorded the first time we see this conv. */
+    createdAt: string;
+    /** ISO timestamp of the most recent append. */
+    updatedAt: string;
+}
+export interface ChatStoreOptions {
+    /** Defaults to ~/.perkos/conversations */
+    storeRoot?: string;
+}
+export declare class ChatStore {
+    readonly root: string;
+    constructor(options?: ChatStoreOptions);
+    /** Directory for a single conversation. */
+    dirFor(convId: string): string;
+    /** Path to the JSONL log for a conv. */
+    jsonlPath(convId: string): string;
+    /** Path to the metadata file for a conv. */
+    metaPath(convId: string): string;
+    /** Ensure the conv directory exists. Idempotent. */
+    ensureDir(convId: string): Promise<void>;
+    /**
+     * Write metadata for a conversation. Called on `channel_join` so the agent
+     * has a local record of which participants belong to a conv.
+     */
+    writeMetadata(meta: ConversationMetadata): Promise<void>;
+    readMetadata(convId: string): Promise<ConversationMetadata | null>;
+    /**
+     * 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.
+     */
+    append(convId: string, msg: ChatMessage): Promise<void>;
+    /**
+     * 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.
+     */
+    readPage(convId: string, opts: {
+        before?: string | null;
+        limit: number;
+    }): Promise<{
+        messages: ChatMessage[];
+        hasMore: boolean;
+    }>;
+    /**
+     * 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.
+     */
+    computeReceipt(convId: string): Promise<{
+        transcriptHash: string;
+        hashAlgo: "sha256";
+        messageCount: number;
+        firstMessageAt: string | null;
+        lastMessageAt: string | null;
+    } | null>;
+    /**
+     * 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.
+     */
+    count(convId: string): Promise<number>;
+}
+//# sourceMappingURL=chat-store.d.ts.map

package/dist/chat-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-store.d.ts","sourceRoot":"","sources":["../src/chat-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAcH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEjE,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,YAAY,EAAE,CAAC;IAC7B,WAAW,EAAE,YAAY,CAAC;IAC1B,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAUD,qBAAa,SAAS;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,OAAO,GAAE,gBAAqB;IAI1C,2CAA2C;IAC3C,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAI9B,wCAAwC;IACxC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAIjC,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAIhC,oDAAoD;IAC9C,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C;;;OAGG;IACG,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxD,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAUxE;;;;OAIG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7D;;;;;;OAMG;IACG,QAAQ,CACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAC9C,OAAO,CAAC;QAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAkCzD;;;;;;;;;;OAUG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAC5C,cAAc,EAAE,MAAM,CAAC;QACvB,QAAQ,EAAE,QAAQ,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;QAC9B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;KAC9B,GAAG,IAAI,CAAC;IA0ET;;;OAGG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAe7C"}