@relaymessenger/pi 0.1.11-staging.0 → 0.1.11-staging.1

package/README.md

@@ -47,6 +47,52 @@ to the chat the Message came from once Pi reports `agent_settled`. A run that
 ends with no words stays silent and sends nothing; a run that fails with no
 words sends `Sorry, something went wrong on my side.`
 
+## With pi-channels
+
+[pi-channels](https://github.com/espennilsen/pi/tree/main/packages/pi-channels)
+routes Messages between Pi and Telegram, Slack and webhooks. With this
+extension also installed, Relay is one more pi-channels adapter, named
+`relay`: `channel:send` to a Relay chat, routes, cron output and the chat
+bridge all work with it, and Relay Messages arrive on `channel:receive`.
+
+```bash
+pi install npm:@e9n/pi-channels
+pi install npm:@relaymessenger/pi
+```
+
+Put a `relay` key in the `pi-channels` settings, beside the routes that name
+your Relay chats (`~/.pi/agent/settings.json`, or `.pi/settings.json` in a
+project):
+
+```json
+{
+  "pi-channels": {
+    "relay": {
+      "agentTokenCommand": ["secret-tool", "lookup", "service", "relay", "username", "agent"],
+      "senders": ["alice"]
+    },
+    "routes": {
+      "me": { "adapter": "relay", "recipient": "3f1c9a52-8d4e-4b7a-9c61-2e5f0d8b7a14" }
+    },
+    "bridge": { "enabled": true }
+  }
+}
+```
+
+The token is `RELAY_AGENT_TOKEN`, else whatever `agentTokenCommand` prints; it
+is never logged. `baseURL`, `senders` and `transcribeCpp` work as in session
+mode. Do not add `relay` under `adapters`: pi-channels makes only its own
+adapter types from there, and would report `Unknown adapter type: relay`.
+
+The recipient is a Relay chat id. An incoming Message's `sender` is its chat
+id too, so the chat bridge answers in the same chat; the sender's Handle and
+the Message id are in `metadata`. Outgoing text goes through the same answer
+parser as Pi's answers, so `buttons`, `selection`, `place` and the other
+fenced blocks are sent as their parts. Photos and files arrive as
+attachments in a temporary folder; voice notes arrive as their transcript
+when `transcribeCpp` is set. The adapter keeps its own Relay WebSocket, so do
+not also run session mode on the same Agent Token.
+
 ## Parts, silence and tools
 
 Pi's final text carries Relay's parts as fenced blocks, read by the SDK's

package/dist/index.d.ts

@@ -121,5 +121,10 @@ export declare const repliedContext: (relay: Relay, data: MessageWebhookData) =>
  * `answerMessages` makes of it, each on `${key}-${index}`.
  */
 export declare const sendAnswer: (relay: Relay, data: MessageWebhookData, key: string, answer: string) => Promise<void>;
+/**
+ * Sends an answer to one chat as the Messages `answerMessages` makes of it,
+ * each on `${key}-${index}`; the first replies to `replyTo` when given.
+ */
+export declare const sendToChat: (relay: Relay, chatId: string, key: string, answer: string, replyTo?: string) => Promise<void>;
 export declare const runPiChannel: (options: PiChannelOptions, signal?: AbortSignal) => Promise<void>;
 export {};

package/dist/index.js

@@ -290,9 +290,6 @@ export const repliedContext = async (relay, data) => {
  * `answerMessages` makes of it, each on `${key}-${index}`.
  */
 export const sendAnswer = async (relay, data, key, answer) => {
-    const messages = answerMessages(answer);
-    if (messages[0]?.error)
-        console.error(`Relay: the component block in pi's answer was left as text: ${messages[0].error}.`);
     // An answer to another agent replies to its Message, as a bot's reply
     // names the message it answers (Telegram `reply_parameters.message_id`), so
     // an agent that sent several knows which one it answers. A person's
@@ -301,9 +298,17 @@ export const sendAnswer = async (relay, data, key, answer) => {
     // Turns in one chat already run one after another, so an agent's two
     // messages each get their own answer.
     const opening = data.parts[0]?.type;
-    const replyTo = data.sender_handle?.kind === "agent" && opening !== "buttons" && opening !== "selection"
-        ? { reply_to: { message_id: data.id } }
-        : {};
+    const replyTo = data.sender_handle?.kind === "agent" && opening !== "buttons" && opening !== "selection" ? data.id : undefined;
+    await sendToChat(relay, data.chat.id, key, answer, replyTo);
+};
+/**
+ * Sends an answer to one chat as the Messages `answerMessages` makes of it,
+ * each on `${key}-${index}`; the first replies to `replyTo` when given.
+ */
+export const sendToChat = async (relay, chatId, key, answer, replyTo) => {
+    const messages = answerMessages(answer);
+    if (messages[0]?.error)
+        console.error(`Relay: the component block in pi's answer was left as text: ${messages[0].error}.`);
     for (const [index, message] of messages.entries()) {
         const messageKey = `${key}-${index}`;
         let parts = message.parts;
@@ -318,7 +323,7 @@ export const sendAnswer = async (relay, data, key, answer) => {
                 continue;
             }
         }
-        await relay.chats.messages.send(data.chat.id, { message: { parts, idempotency_key: messageKey, ...(index === 0 ? replyTo : {}) } });
+        await relay.chats.messages.send(chatId, { message: { parts, idempotency_key: messageKey, ...(index === 0 && replyTo ? { reply_to: { message_id: replyTo } } : {}) } });
     }
 };
 export const runPiChannel = (options, signal) => new PiChannel(options).run(signal);

package/dist/native.d.ts

@@ -19,6 +19,12 @@ export interface RelaySettings {
 }
 /** The `relay` settings, or none when the file or key is missing or unreadable. */
 export declare const relaySettings: (dir?: string) => Promise<RelaySettings>;
+/**
+ * The `relay` key of the `pi-channels` settings, beside pi-channels' own
+ * `slack` key: global settings.json, then the project's .pi/settings.json
+ * over it, as pi-channels merges its settings. None when absent.
+ */
+export declare const piChannelsRelaySettings: (cwd: string, dir?: string) => Promise<RelaySettings | undefined>;
 /** RELAY_AGENT_TOKEN, else what `agentTokenCommand` prints; never logged. */
 export declare const agentToken: (settings: RelaySettings) => Promise<string | undefined>;
 /**

package/dist/native.js

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import Relay from "@relaymessenger/sdk";
 import { RELAY_CHAT_ID_ENV, runPiChannel } from "./index.js";
 import { relayTools } from "./tools.js";
+import { registerRelayAdapter, relayChannelAdapter, RELAY_ADAPTER } from "./pi-channels.js";
 import { SessionChannel } from "./session.js";
 import { transcribeCpp } from "./voice.js";
 let controller;
@@ -21,6 +22,25 @@ export const relaySettings = async (dir = agentDir()) => {
         return {};
     }
 };
+/**
+ * The `relay` key of the `pi-channels` settings, beside pi-channels' own
+ * `slack` key: global settings.json, then the project's .pi/settings.json
+ * over it, as pi-channels merges its settings. None when absent.
+ */
+export const piChannelsRelaySettings = async (cwd, dir = agentDir()) => {
+    const read = async (file) => {
+        try {
+            const value = JSON.parse(await readFile(file, "utf8"))["pi-channels"]?.relay;
+            return value && typeof value === "object" ? value : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const global = await read(join(dir, "settings.json"));
+    const project = await read(join(cwd, ".pi", "settings.json"));
+    return global || project ? { ...global, ...project } : undefined;
+};
 /** RELAY_AGENT_TOKEN, else what `agentTokenCommand` prints; never logged. */
 export const agentToken = async (settings) => {
     const env = process.env.RELAY_AGENT_TOKEN?.trim();
@@ -81,6 +101,33 @@ const attachSession = (pi) => {
         channel = undefined;
     });
 };
+/**
+ * Relay as a pi-channels adapter, registered with `channel:register` when
+ * pi-channels is loaded and its settings have a `relay` key. It registers on
+ * `resources_discover`, which Pi fires after every `session_start` handler,
+ * because pi-channels' `session_start` drops adapters registered before it.
+ */
+const attachPiChannels = (pi) => {
+    pi.on("resources_discover", async (event) => {
+        if (process.env.PI_SUBAGENT_CHILD === "1")
+            return;
+        const settings = await piChannelsRelaySettings(event.cwd);
+        if (!settings)
+            return;
+        const token = await agentToken(settings);
+        if (!token) {
+            console.error("Relay: no Agent Token (RELAY_AGENT_TOKEN or pi-channels.relay.agentTokenCommand); the pi-channels adapter is off.");
+            return;
+        }
+        const baseURL = process.env.RELAY_BASE_URL?.trim() || settings.baseURL;
+        const voice = settings.transcribeCpp;
+        registerRelayAdapter(pi.events, () => relayChannelAdapter({
+            relay: new Relay({ apiKey: token, ...(baseURL ? { baseURL } : {}) }),
+            ...(settings.senders ? { senders: settings.senders } : {}),
+            ...(voice ? { transcribe: transcribeCpp({ module: home(voice.module), model: home(voice.model) }) } : {}),
+        }), RELAY_ADAPTER);
+    });
+};
 /** The Relay tools, as Pi registers a tool (docs/extensions.md, registerTool). */
 const registerRelayTools = (pi, relay, chatId) => {
     for (const tool of relayTools(relay, chatId))
@@ -107,6 +154,7 @@ const attachChatTools = (pi) => {
 export default function relayPiExtension(pi) {
     attachChatTools(pi);
     attachSession(pi);
+    attachPiChannels(pi);
     pi.registerCommand("relay-connect", {
         description: "Start the Relay channel using the configured Agent Token",
         handler: async (_args, ctx) => {

package/dist/pi-channels.d.ts

@@ -0,0 +1,71 @@
+import type Relay from "@relaymessenger/sdk";
+import type { MessageWebhookData, RelayWebhookEvent } from "@relaymessenger/sdk";
+import type { Transcribe } from "./voice.js";
+export interface ChannelMessage {
+    readonly adapter: string;
+    /** The Relay chat id. */
+    readonly recipient: string;
+    readonly text?: string;
+    readonly source?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+export interface IncomingAttachment {
+    readonly type: "image" | "document" | "audio";
+    readonly path: string;
+    readonly filename?: string;
+    readonly mimeType?: string;
+    readonly size?: number;
+}
+export interface IncomingMessage {
+    readonly adapter: string;
+    /** The Relay chat id, so a reply to the sender goes back to the chat. */
+    readonly sender: string;
+    readonly text: string;
+    readonly attachments?: IncomingAttachment[];
+    readonly metadata?: Record<string, unknown>;
+}
+export interface ChannelAdapter {
+    readonly direction: "outgoing" | "incoming" | "bidirectional";
+    send(message: ChannelMessage): Promise<void>;
+    start(onMessage: (message: IncomingMessage) => void): Promise<void>;
+    stop(): Promise<void>;
+    sendTyping(recipient: string): Promise<void>;
+}
+/** The adapter name routes and the chat bridge use. */
+export declare const RELAY_ADAPTER = "relay";
+export interface RelayAdapterOptions {
+    readonly relay: Relay;
+    /** Handles whose Messages are received; any sender when empty or absent. */
+    readonly senders?: readonly string[];
+    /** Words for a voice note. Without it a voice note is named, not heard. */
+    readonly transcribe?: Transcribe;
+    /** Where downloaded photos and files go; pi-channels' Telegram adapter uses the same folder. */
+    readonly downloadDir?: string;
+}
+/**
+ * One Relay Message as a pi-channels incoming message: its words, the
+ * Message it replies to, voice notes as their transcript, and photos and
+ * files downloaded to a temporary path as attachments (as pi-channels'
+ * Telegram adapter does). Null for a Message with nothing in it.
+ */
+export declare const incomingMessage: (relay: Relay, event: RelayWebhookEvent & {
+    data: MessageWebhookData;
+}, options?: Pick<RelayAdapterOptions, "transcribe" | "downloadDir">) => Promise<IncomingMessage | null>;
+/**
+ * Relay as a pi-channels adapter. Incoming Messages arrive on the Agent's
+ * Relay WebSocket; outgoing text goes to the chat named as the recipient
+ * through `chats.messages.send`, with fenced blocks (buttons, selection,
+ * place, ...) sent as their parts by the SDK's answer parser.
+ */
+export declare const relayChannelAdapter: (options: RelayAdapterOptions) => ChannelAdapter;
+/** The part of Pi's event bus the adapter uses (Pi docs/extensions.md, pi.events). */
+export interface EventBus {
+    emit(channel: string, data: unknown): void;
+}
+/**
+ * Registers the adapter with pi-channels when it is loaded and does not
+ * already hold one by that name. pi-channels answers `channel:list` and
+ * `channel:register` through their callbacks synchronously, so no answer
+ * means it is not installed. Returns whether the adapter is registered now.
+ */
+export declare const registerRelayAdapter: (events: EventBus, adapter: () => ChannelAdapter, name?: string) => boolean;

package/dist/pi-channels.js

@@ -0,0 +1,143 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { extname, join } from "node:path";
+import { repliedContext, sendToChat, wordsOf } from "./index.js";
+import { downloadMedia } from "./session.js";
+/** The adapter name routes and the chat bridge use. */
+export const RELAY_ADAPTER = "relay";
+/** Inbound Messages from a Handle, and only the listed Handles when there is a list. */
+const received = (event, senders = []) => {
+    if (event.event_type !== "message.received" || event.data.direction !== "inbound")
+        return false;
+    const data = event.data;
+    if (!data.sender_handle)
+        return false;
+    if (!senders.length)
+        return true;
+    const handle = (value) => value.replace(/^@/u, "").toLowerCase();
+    return senders.some((sender) => handle(sender) === handle(data.sender_handle.handle));
+};
+/**
+ * One Relay Message as a pi-channels incoming message: its words, the
+ * Message it replies to, voice notes as their transcript, and photos and
+ * files downloaded to a temporary path as attachments (as pi-channels'
+ * Telegram adapter does). Null for a Message with nothing in it.
+ */
+export const incomingMessage = async (relay, event, options = {}) => {
+    const data = event.data;
+    const lines = [];
+    const attachments = [];
+    for (const part of data.parts) {
+        if (part.type !== "media")
+            continue;
+        const media = part;
+        const mime = String(media.mime_type ?? "").toLowerCase();
+        const name = media.filename || "file";
+        if (mime.startsWith("audio/")) {
+            const words = options.transcribe
+                ? await downloadMedia(relay, media).then((bytes) => options.transcribe(bytes, name)).catch(() => undefined)
+                : undefined;
+            lines.push(words ? `[voice note, transcribed]: ${words}` : `[voice note: ${name}, could not be transcribed]`);
+            continue;
+        }
+        try {
+            const bytes = await downloadMedia(relay, media);
+            const dir = options.downloadDir ?? join(tmpdir(), "pi-channels");
+            await mkdir(dir, { recursive: true });
+            const path = join(dir, `${Date.now()}-${randomUUID()}${extname(name)}`);
+            await writeFile(path, bytes);
+            attachments.push({ type: mime.startsWith("image/") ? "image" : "document", path, filename: name, ...(mime ? { mimeType: mime } : {}), size: bytes.length });
+        }
+        catch {
+            lines.push(`[file: ${name}, could not be downloaded]`);
+        }
+    }
+    const text = [wordsOf(data), lines.join("\n"), await repliedContext(relay, data)].filter(Boolean).join("\n\n");
+    if (!text && !attachments.length)
+        return null;
+    return {
+        adapter: RELAY_ADAPTER,
+        sender: data.chat.id,
+        text,
+        ...(attachments.length ? { attachments } : {}),
+        metadata: {
+            eventId: event.event_id,
+            messageId: data.id,
+            chatId: data.chat.id,
+            isGroup: data.chat.is_group,
+            handle: data.sender_handle?.handle,
+            handleKind: data.sender_handle?.kind,
+        },
+    };
+};
+/**
+ * Relay as a pi-channels adapter. Incoming Messages arrive on the Agent's
+ * Relay WebSocket; outgoing text goes to the chat named as the recipient
+ * through `chats.messages.send`, with fenced blocks (buttons, selection,
+ * place, ...) sent as their parts by the SDK's answer parser.
+ */
+export const relayChannelAdapter = (options) => {
+    const { relay } = options;
+    const seen = new Set();
+    let stop;
+    return {
+        direction: "bidirectional",
+        async send(message) {
+            if (!message.recipient)
+                throw new Error("Relay needs a chat id as the recipient");
+            const text = message.text?.trim();
+            if (!text)
+                return;
+            const key = typeof message.metadata?.idempotencyKey === "string" ? message.metadata.idempotencyKey : `pi-channels-${randomUUID()}`;
+            await sendToChat(relay, message.recipient, key, text);
+        },
+        async start(onMessage) {
+            if (stop)
+                return;
+            const controller = new AbortController();
+            stop = controller;
+            void relay.websocket.run({
+                signal: controller.signal,
+                onEvent: async (event) => {
+                    if (seen.has(event.event_id) || !received(event, options.senders))
+                        return;
+                    const incoming = await incomingMessage(relay, event, options);
+                    seen.add(event.event_id);
+                    if (incoming)
+                        onMessage(incoming);
+                },
+                // pi-channels keeps no inbox to rebuild from.
+                onFullSync: async () => { console.error("Relay: FULL sync acknowledged; Messages sent while pi-channels was away were not delivered."); },
+                onError: (error) => { console.error(`Relay: ${error instanceof Error ? error.message : String(error)}`); },
+            }).catch((error) => {
+                console.error(`Relay: the pi-channels adapter stopped: ${error instanceof Error ? error.message : String(error)}`);
+            }).finally(() => { if (stop === controller)
+                stop = undefined; });
+        },
+        async stop() {
+            stop?.abort();
+            stop = undefined;
+        },
+        async sendTyping(recipient) {
+            await relay.chats.startTyping(recipient);
+        },
+    };
+};
+/**
+ * Registers the adapter with pi-channels when it is loaded and does not
+ * already hold one by that name. pi-channels answers `channel:list` and
+ * `channel:register` through their callbacks synchronously, so no answer
+ * means it is not installed. Returns whether the adapter is registered now.
+ */
+export const registerRelayAdapter = (events, adapter, name = RELAY_ADAPTER) => {
+    let listed;
+    events.emit("channel:list", { callback: (items) => { listed = items; } });
+    if (!listed)
+        return false;
+    if (listed.some((item) => item.type === "adapter" && item.name === name))
+        return false;
+    let ok = false;
+    events.emit("channel:register", { name, adapter: adapter(), callback: (result) => { ok = result; } });
+    return ok;
+};

package/dist/session.d.ts

@@ -78,3 +78,5 @@ export declare class SessionChannel {
     next(): void;
     stop(): void;
 }
+/** The bytes behind a media part; an expired url is renewed once. */
+export declare const downloadMedia: (relay: Relay, part: MediaPartResponse) => Promise<Buffer>;

package/dist/session.js

@@ -172,16 +172,20 @@ export class SessionChannel {
         this.#pending = undefined;
         this.#ended = [];
     }
-    async #download(part) {
-        let response = part.url ? await fetch(part.url).catch(() => undefined) : undefined;
-        // A media url lasts 60 minutes; GET /v1/attachments/{id} makes a fresh one.
-        if (!response?.ok && part.id) {
-            const fresh = (await this.#relay.attachments.retrieve(part.id)).download_url;
-            if (fresh)
-                response = await fetch(fresh);
-        }
-        if (!response?.ok)
-            throw new Error(`Relay attachment download failed (${response?.status ?? "no url"})`);
-        return Buffer.from(await response.arrayBuffer());
+    #download(part) {
+        return downloadMedia(this.#relay, part);
     }
 }
+/** The bytes behind a media part; an expired url is renewed once. */
+export const downloadMedia = async (relay, part) => {
+    let response = part.url ? await fetch(part.url).catch(() => undefined) : undefined;
+    // A media url lasts 60 minutes; GET /v1/attachments/{id} makes a fresh one.
+    if (!response?.ok && part.id) {
+        const fresh = (await relay.attachments.retrieve(part.id)).download_url;
+        if (fresh)
+            response = await fetch(fresh);
+    }
+    if (!response?.ok)
+        throw new Error(`Relay attachment download failed (${response?.status ?? "no url"})`);
+    return Buffer.from(await response.arrayBuffer());
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relaymessenger/pi",
-  "version": "0.1.11-staging.0",
+  "version": "0.1.11-staging.1",
   "description": "Relay Messenger channel for Pi over Relay v1 WebSocket delivery.",
   "type": "module",
   "main": "./dist/index.js",