@perkos/perkos-a2a 0.9.0 → 0.9.2

package/dist/chat-store.js

@@ -0,0 +1,233 @@
+/**
+ * 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 { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { appendFile, mkdir, open, readFile, writeFile, } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Sanitize a convId so it can safely become a directory name. */
+function safeConvId(convId) {
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(convId)) {
+        throw new Error(`invalid convId: ${convId}`);
+    }
+    return convId;
+}
+export class ChatStore {
+    root;
+    constructor(options = {}) {
+        this.root = options.storeRoot ?? join(homedir(), ".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;
+        }
+        // Walk lines from newest (end) to oldest (start), collecting up to limit.
+        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);
+        // Probe existence first — createReadStream() defers ENOENT to the
+        // 'error' event, which would otherwise reject our Promise.
+        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 {
+                        /* malformed line — still counted toward hash */
+                    }
+                }
+            });
+            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 { /* ignore */ }
+                }
+                // Fold metadata.json into the hash if present, so the receipt
+                // also commits to participant + historyHost. Use a 0x1E (record
+                // separator) byte as an unambiguous boundary.
+                try {
+                    const metaRaw = await readFile(this.metaPath(convId), "utf8");
+                    hash.update("\x1e");
+                    hash.update(metaRaw);
+                }
+                catch {
+                    /* metadata missing → still produce a receipt over the jsonl alone */
+                }
+                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";
+}
+//# sourceMappingURL=chat-store.js.map

package/dist/chat-store.js.map

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

package/dist/chat-types.d.ts

@@ -0,0 +1,166 @@
+/**
+ * PerkOS-Chat protocol types.
+ *
+ * Wire format spoken to `wss://chat.perkos.xyz/chat`. The chat server routes
+ * frames between users (browser, authenticated via Firebase ID token) and
+ * agents (this client, authenticated via the same relay API key issued
+ * during PerkOS-Transport pairing).
+ *
+ * Companion server: github.com/PerkOS-xyz/PerkOS-Chat
+ * Full spec: see that repo's docs/protocol.md
+ */
+/** Identity strings exchanged on the chat wire. */
+export type ChatIdentity = `user:${string}` | `agent:${string}`;
+/** A single persisted message in a conversation's jsonl. */
+export interface ChatMessage {
+    id: string;
+    from: ChatIdentity;
+    /** Message body. May be markdown. */
+    text: string;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+    /** Optional id of the message this one replies to. */
+    replyTo?: string | null;
+}
+/** Sent by this client immediately after the WS opens. */
+export interface AuthFrame {
+    type: "auth";
+    role: "agent";
+    agentName: string;
+    apiKey: string;
+}
+export interface AuthOkFrame {
+    type: "auth_ok";
+    session: {
+        agentName: string;
+        scopes: string[];
+    };
+}
+export interface AuthErrorFrame {
+    type: "auth_error";
+    code: string;
+    message: string;
+}
+/** Server → agent: a new user (or another agent) sent a message in this conv. */
+export interface ChatDeliverFrame {
+    type: "chat_deliver";
+    id: string;
+    convId: string;
+    from: ChatIdentity;
+    text: string;
+    timestamp: string;
+}
+/** Server → agent: another agent posted in a multi-participant channel. */
+export interface ChatMessageInboundFrame {
+    type: "chat_message";
+    id: string;
+    convId: string;
+    from: ChatIdentity;
+    text: string;
+    replyTo?: string | null;
+    timestamp: string;
+}
+/** Agent → server: reply to a conv. The server broadcasts as `chat_message`. */
+export interface ChatReplyFrame {
+    type: "chat_reply";
+    id?: string;
+    convId: string;
+    /** Required: tells the server which wallet's conv tree to look up. */
+    walletAddress: string;
+    text: string;
+    replyTo?: string | null;
+}
+/** Server → agent: please serve a history page. */
+export interface HistoryRequestFrame {
+    type: "history_request";
+    id: string;
+    convId: string;
+    forWallet: string;
+    /** ISO timestamp — return messages strictly older than this. */
+    before?: string | null;
+    limit: number;
+}
+/** Agent → server: history chunk response. */
+export interface HistoryChunkFrame {
+    type: "history_chunk";
+    id: string;
+    convId: string;
+    forWallet: string;
+    messages: ChatMessage[];
+    hasMore: boolean;
+}
+/** Server → agent: heads-up that this agent is now a participant in a conv. */
+export interface ChannelJoinFrame {
+    type: "channel_join";
+    convId: string;
+    participants: ChatIdentity[];
+    historyHost: ChatIdentity;
+}
+export interface TypingFrame {
+    type: "typing";
+    convId: string;
+    /** When echoed by the server, this is populated. */
+    from?: ChatIdentity;
+    state: "start" | "stop";
+}
+export interface AckFrame {
+    type: "ack";
+    id: string;
+    convId: string;
+    delivered: number;
+    timestamp: string;
+}
+/** Server → agent: please compute a tamper-evident hash of this conv. */
+export interface ReceiptRequestFrame {
+    type: "receipt_request";
+    id: string;
+    convId: string;
+    /** Wallet that the receipt is being issued for. */
+    forWallet: string;
+}
+/** Agent → server: hash + metadata. Server routes back to the wallet. */
+export interface ReceiptResponseFrame {
+    type: "receipt_response";
+    id: string;
+    convId: string;
+    forWallet: string;
+    /** sha256 hex of the canonical jsonl + metadata.json. */
+    transcriptHash: string;
+    hashAlgo: "sha256";
+    messageCount: number;
+    firstMessageAt: string | null;
+    lastMessageAt: string | null;
+    /** ISO timestamp the agent produced the hash. */
+    generatedAt: string;
+}
+export interface ChatErrorFrame {
+    type: "error";
+    code: string;
+    message: string;
+}
+export interface PingFrame {
+    type: "ping";
+}
+export interface PongFrame {
+    type: "pong";
+    ts: string;
+}
+export type ChatFrame = AuthFrame | AuthOkFrame | AuthErrorFrame | ChatDeliverFrame | ChatMessageInboundFrame | ChatReplyFrame | HistoryRequestFrame | HistoryChunkFrame | ChannelJoinFrame | TypingFrame | AckFrame | ChatErrorFrame | ReceiptRequestFrame | ReceiptResponseFrame | PingFrame | PongFrame;
+export interface ChatConfig {
+    /** Whether the chat client should connect at startup. Default: false. */
+    enabled: boolean;
+    /** WebSocket URL. Default: wss://chat.perkos.xyz/chat. */
+    url: string;
+    /** Relay API key for this agent (same key used for PerkOS-Transport pairing). */
+    apiKey: string;
+    /** Root directory for the JSONL stores. Default: ~/.perkos/conversations. */
+    storeRoot?: string;
+    /** Maximum messages returned per history page. Default: 50. */
+    defaultHistoryLimit?: number;
+    /** Reconnect floor/ceiling in ms. Defaults: 1000 / 60000. */
+    minReconnectMs?: number;
+    maxReconnectMs?: number;
+    /** Heartbeat interval ms. Default: 25000. */
+    heartbeatIntervalMs?: number;
+}
+//# sourceMappingURL=chat-types.d.ts.map

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

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

package/dist/chat-types.js

@@ -0,0 +1,13 @@
+/**
+ * PerkOS-Chat protocol types.
+ *
+ * Wire format spoken to `wss://chat.perkos.xyz/chat`. The chat server routes
+ * frames between users (browser, authenticated via Firebase ID token) and
+ * agents (this client, authenticated via the same relay API key issued
+ * during PerkOS-Transport pairing).
+ *
+ * Companion server: github.com/PerkOS-xyz/PerkOS-Chat
+ * Full spec: see that repo's docs/protocol.md
+ */
+export {};
+//# sourceMappingURL=chat-types.js.map

package/dist/chat-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-types.js","sourceRoot":"","sources":["../src/chat-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/pairing.js

@@ -0,0 +1,66 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+import { generateKeyPairSync } from "crypto";
+export function defaultPairingPath(agentName) {
+    const safeName = agentName.replace(/[^a-zA-Z0-9_.-]/g, "_");
+    return join(homedir(), ".perkos", "a2a", "agents", `${safeName}.json`);
+}
+export function loadOrCreateIdentity(agentName, path = defaultPairingPath(agentName)) {
+    if (existsSync(path)) {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (raw.identity?.agentName && raw.identity?.publicKey && raw.identity?.privateKey)
+            return raw.identity;
+    }
+    const pair = generateKeyPairSync("ed25519", {
+        publicKeyEncoding: { type: "spki", format: "pem" },
+        privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    });
+    return {
+        agentName,
+        publicKey: pair.publicKey,
+        privateKey: pair.privateKey,
+        keyType: "ed25519",
+        createdAt: new Date().toISOString(),
+    };
+}
+export function savePairingProfile(profile, path = defaultPairingPath(profile.identity.agentName)) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify(profile, null, 2)}\n`, { mode: 0o600 });
+}
+export function buildClaimRequest(input) {
+    return {
+        agentName: input.identity.agentName,
+        publicKey: input.identity.publicKey,
+        keyType: input.identity.keyType,
+        runtime: input.runtime,
+        capabilities: input.capabilities?.length ? input.capabilities : ["chat", "tasks:receive", "messages:send"],
+        transport: { relay: true, publicUrl: input.publicUrl },
+        metadata: input.metadata,
+    };
+}
+export function claimUrlFromInvite(inviteUrl) {
+    const trimmed = inviteUrl.replace(/\/+$/, "");
+    return `${trimmed}/claim`;
+}
+export async function claimPairingInvite(inviteUrl, request) {
+    const response = await fetch(claimUrlFromInvite(inviteUrl), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(request),
+    });
+    const body = await response.text();
+    let parsed;
+    try {
+        parsed = body ? JSON.parse(body) : {};
+    }
+    catch {
+        throw new Error(`Pairing server returned non-JSON response (${response.status}): ${body}`);
+    }
+    if (!response.ok) {
+        const message = typeof parsed === "object" && parsed && "error" in parsed ? String(parsed.error) : body;
+        throw new Error(`Pairing claim failed (${response.status}): ${message}`);
+    }
+    return parsed;
+}
+//# sourceMappingURL=pairing.js.map

package/dist/pairing.js.map

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