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

package/README.md

@@ -47,6 +47,59 @@ 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.`
 
+A Message that arrives while the session is busy with a run Relay did not
+start steers that run (`deliverAs: "steer"`), and its answer goes back once
+the run settles. A run no one prompted, such as a pi-subagents result, sends
+its last words to the chat of the last Message, kept in
+`relay-last-chat.json` in the agent directory so it survives a restart; a turn
+typed in the session stays there.
+
+## 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
@@ -56,14 +109,23 @@ Pi's final text carries Relay's parts as fenced blocks, read by the SDK's
 with no words is Pi choosing to stay silent: nothing is sent, in the channel
 and in the session alike.
 
-The extension registers three tools for the chat Pi is answering (Pi
+The extension registers four tools for the chat Pi is answering (Pi
 `registerTool`): `relay_request_location` asks the person to share their
-location, `relay_read_location` reads where everyone sharing is now, and
+location, `relay_read_location` reads where everyone sharing is now,
 `relay_send_media` uploads a file from the machine and sends it as its own
-Message. `runPiChannel` starts each chat's Pi with `RELAY_PI_CHAT_ID`,
+Message (`reply_to` threads it to a Message by id), and `relay_react` reacts
+to a Message with an emoji (the six tapbacks, or any other emoji as a custom
+reaction), the Message being answered unless `message_id` names another.
+`runPiChannel` starts each chat's Pi with `RELAY_PI_CHAT_ID`,
 `RELAY_AGENT_TOKEN` and `RELAY_BASE_URL` set, so that Pi gets the tools; in
 session mode they act on the chat whose Message is being answered.
 
+Each prompt ends with `[Relay message id: <id>]`. An answer that contains
+`[[reply_to_current]]` is sent as a reply to that Message, and one with
+`[[reply_to:<id>]]` as a reply to the Message named; the tag is removed from
+the words (the reply tags of OpenClaw's rich output protocol). Pi's typing
+indicator shows in the chat from the start of a turn until its answer is sent.
+
 ## Selection
 
 End the final Pi answer with a `selection` JSON fence holding the question as

package/dist/index.d.ts

@@ -90,9 +90,23 @@ export declare const wordsOf: (data: MessageWebhookData) => string;
 export declare const piPrompt: (message: string) => string;
 /**
  * The Relay tools the Pi extension registers when Relay starts it for a chat
- * (`relay_request_location`, `relay_read_location`, `relay_send_media`).
+ * (`relay_request_location`, `relay_read_location`, `relay_send_media`,
+ * `relay_react`), and the reply tags OpenClaw's channels read
+ * (docs/reference/rich-output-protocol.md: `[[reply_to_current]]`,
+ * `[[reply_to:<id>]]`).
  */
-export declare const RELAY_TOOLS_LINE = " In a one-to-one chat, relay_request_location asks the person to share their location and relay_read_location reads where everyone sharing is now. relay_send_media sends a file from this machine as its own Message.";
+export declare const RELAY_TOOLS_LINE = " In a one-to-one chat, relay_request_location asks the person to share their location and relay_read_location reads where everyone sharing is now. relay_send_media sends a file from this machine as its own Message. relay_react reacts to a Message with an emoji. Each Message names its Relay message id; to thread your answer to a Message, put [[reply_to_current]] (the Message you are answering) or [[reply_to:<id>]] in it: the tag is removed and not shown.";
+/** The id of the Message being answered, as one line of data the Relay tools and reply tags can name. */
+export declare const messageIdLine: (data: Pick<MessageWebhookData, "id">) => string;
+/**
+ * An answer's reply tag: the words without any `[[reply_to_current]]` or
+ * `[[reply_to:<id>]]`, and the Message the first one names (`current` for the
+ * Message being answered). No tag leaves the words as they are.
+ */
+export declare const replyTag: (answer: string) => {
+    answer: string;
+    replyTo?: string;
+};
 /**
  * The messages an answer becomes: each link written alone on a line as its
  * own message, text in chunks the API takes, and the buttons its fenced block
@@ -121,5 +135,18 @@ 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. A
+ * reply tag in the answer wins and is removed: `[[reply_to:<id>]]` names the
+ * Message, `[[reply_to_current]]` names `current`, and no reply when there is
+ * no current Message.
+ */
+export declare const sendToChat: (relay: Relay, chatId: string, key: string, answer: string, replyTo?: string, current?: string) => Promise<void>;
+/**
+ * Shows or clears Pi's typing indicator in a chat. It is a courtesy: a
+ * failure is logged and the turn goes on.
+ */
+export declare const typing: (relay: Relay, chatId: string, on: boolean) => Promise<void>;
 export declare const runPiChannel: (options: PiChannelOptions, signal?: AbortSignal) => Promise<void>;
 export {};

package/dist/index.js

@@ -80,9 +80,26 @@ const textFromEvent = (event) => {
 export const piPrompt = (message) => `${message}\n\nWrite your answer as your final message. Relay sends that answer to the chat for you, so do not send it yourself. To stay silent, end with no text: nothing is sent. Write chat text. Inline Markdown draws: bold, italic, strikethrough, code, links. Headings, lists and code fences show as written.\n\n${BUTTONS_BLOCK_INSTRUCTION} ${LINK_LINE_INSTRUCTION} ${BUTTONS_GUIDANCE} ${SELECTION_BLOCK_INSTRUCTION} ${SELECTION_GUIDANCE} ${FORM_BLOCK_INSTRUCTION} ${FORM_GUIDANCE} ${CARD_BLOCK_INSTRUCTION} ${CARD_GUIDANCE} ${PLACE_BLOCK_INSTRUCTION} ${PAYMENT_BLOCK_INSTRUCTION} ${PAYMENT_GUIDANCE} ${RATING_REQUEST_BLOCK_INSTRUCTION} ${RATING_REQUEST_GUIDANCE}${RELAY_TOOLS_LINE}`;
 /**
  * The Relay tools the Pi extension registers when Relay starts it for a chat
- * (`relay_request_location`, `relay_read_location`, `relay_send_media`).
+ * (`relay_request_location`, `relay_read_location`, `relay_send_media`,
+ * `relay_react`), and the reply tags OpenClaw's channels read
+ * (docs/reference/rich-output-protocol.md: `[[reply_to_current]]`,
+ * `[[reply_to:<id>]]`).
  */
-export const RELAY_TOOLS_LINE = " In a one-to-one chat, relay_request_location asks the person to share their location and relay_read_location reads where everyone sharing is now. relay_send_media sends a file from this machine as its own Message.";
+export const RELAY_TOOLS_LINE = " In a one-to-one chat, relay_request_location asks the person to share their location and relay_read_location reads where everyone sharing is now. relay_send_media sends a file from this machine as its own Message. relay_react reacts to a Message with an emoji. Each Message names its Relay message id; to thread your answer to a Message, put [[reply_to_current]] (the Message you are answering) or [[reply_to:<id>]] in it: the tag is removed and not shown.";
+/** The id of the Message being answered, as one line of data the Relay tools and reply tags can name. */
+export const messageIdLine = (data) => data.id ? `[Relay message id: ${data.id}]` : "";
+const REPLY_TAG = /\[\[\s*reply_to(?:_current|\s*:\s*([^\]\s]+))\s*\]\]/gu;
+/**
+ * An answer's reply tag: the words without any `[[reply_to_current]]` or
+ * `[[reply_to:<id>]]`, and the Message the first one names (`current` for the
+ * Message being answered). No tag leaves the words as they are.
+ */
+export const replyTag = (answer) => {
+    const first = [...answer.matchAll(REPLY_TAG)][0];
+    if (!first)
+        return { answer };
+    return { answer: answer.replace(REPLY_TAG, "").replace(/[ \t]+\n/gu, "\n").trim(), replyTo: first[1] ?? "current" };
+};
 /**
  * The messages an answer becomes: each link written alone on a line as its
  * own message, text in chunks the API takes, and the buttons its fenced block
@@ -261,17 +278,24 @@ export class PiChannel {
         }
         const timeout = this.#options.rpcTimeoutMs ?? 60_000;
         const replyLine = await repliedContext(this.#relay, data);
-        await session.command("prompt", { message: piPrompt([message, replyLine].filter(Boolean).join("\n\n")) }, timeout, signal);
-        if (!session.settled) {
-            while (!session.settled)
-                await session.read(timeout, signal);
+        // The person sees Pi typing while it works; it stops once the answer is sent.
+        await typing(this.#relay, data.chat.id, true);
+        try {
+            await session.command("prompt", { message: piPrompt([message, replyLine, messageIdLine(data)].filter(Boolean).join("\n\n")) }, timeout, signal);
+            if (!session.settled) {
+                while (!session.settled)
+                    await session.read(timeout, signal);
+            }
+            const response = await session.command("get_last_assistant_text", {}, timeout, signal);
+            const answer = response.data?.text?.trim();
+            // No words is Pi's choice to stay silent: nothing is sent.
+            if (!answer)
+                return;
+            await sendAnswer(this.#relay, data, `pi-${event.event_id}`, answer);
+        }
+        finally {
+            await typing(this.#relay, data.chat.id, false);
         }
-        const response = await session.command("get_last_assistant_text", {}, timeout, signal);
-        const answer = response.data?.text?.trim();
-        // No words is Pi's choice to stay silent: nothing is sent.
-        if (!answer)
-            return;
-        await sendAnswer(this.#relay, data, `pi-${event.event_id}`, answer);
     }
 }
 /**
@@ -290,9 +314,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
@@ -300,10 +321,25 @@ export const sendAnswer = async (relay, data, key, answer) => {
     // not reply to buttons or a selection, and a reply names part 0.
     // Turns in one chat already run one after another, so an agent's two
     // messages each get their own answer.
+    // A reply tag Pi wrote names the Message itself and wins.
     const opening = data.parts[0]?.type;
-    const replyTo = data.sender_handle?.kind === "agent" && opening !== "buttons" && opening !== "selection"
-        ? { reply_to: { message_id: data.id } }
-        : {};
+    const answerable = opening !== "buttons" && opening !== "selection";
+    const replyTo = data.sender_handle?.kind === "agent" && answerable ? data.id : undefined;
+    await sendToChat(relay, data.chat.id, key, answer, replyTo, answerable ? data.id : undefined);
+};
+/**
+ * Sends an answer to one chat as the Messages `answerMessages` makes of it,
+ * each on `${key}-${index}`; the first replies to `replyTo` when given. A
+ * reply tag in the answer wins and is removed: `[[reply_to:<id>]]` names the
+ * Message, `[[reply_to_current]]` names `current`, and no reply when there is
+ * no current Message.
+ */
+export const sendToChat = async (relay, chatId, key, answer, replyTo, current) => {
+    const tagged = replyTag(answer);
+    const target = tagged.replyTo === undefined ? replyTo : tagged.replyTo === "current" ? current : tagged.replyTo;
+    const messages = answerMessages(tagged.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 +354,16 @@ 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 && target ? { reply_to: { message_id: target } } : {}) } });
     }
 };
+/**
+ * Shows or clears Pi's typing indicator in a chat. It is a courtesy: a
+ * failure is logged and the turn goes on.
+ */
+export const typing = (relay, chatId, on) => Promise.resolve()
+    .then(() => on ? relay.chats.startTyping(chatId) : relay.chats.stopTyping(chatId))
+    .catch((error) => {
+    console.error(`Relay: typing indicator failed: ${error instanceof Error ? error.message : String(error)}`);
+});
 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();
@@ -62,12 +82,13 @@ const attachSession = (pi) => {
             agentToken: token,
             relay,
             isIdle: () => ctx.isIdle(),
+            lastChatFile: join(agentDir(), "relay-last-chat.json"),
             ...(baseURL ? { baseURL } : {}),
             ...(senders ? { senders } : {}),
             ...(voice ? { transcribe: transcribeCpp({ module: home(voice.module), model: home(voice.model) }) } : {}),
         });
         const current = channel;
-        registerRelayTools(pi, relay, () => current.chatId);
+        registerRelayTools(pi, relay, () => current.chatId, () => current.messageId);
         void channel.run(stop.signal).catch((error) => {
             console.error(`Relay: the session channel stopped: ${error instanceof Error ? error.message : String(error)}`);
         });
@@ -81,9 +102,36 @@ 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))
+const registerRelayTools = (pi, relay, chatId, messageId) => {
+    for (const tool of relayTools(relay, chatId, messageId))
         pi.registerTool(tool);
 };
 /**
@@ -107,6 +155,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,145 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { extname, join } from "node:path";
+import { messageIdLine, 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 words = [wordsOf(data), lines.join("\n"), await repliedContext(relay, data)].filter(Boolean).join("\n\n");
+    if (!words && !attachments.length)
+        return null;
+    // The Message's id, as session mode gives it, so relay_react and reply tags can name it.
+    const text = [words, messageIdLine(data)].filter(Boolean).join("\n\n");
+    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

@@ -14,7 +14,7 @@ export type SessionContent = (TextBlock | ImageBlock)[];
 /** What the session is given in place of the Pi it would otherwise start. */
 export interface SessionPi {
     sendUserMessage(content: SessionContent, options?: {
-        deliverAs: "followUp";
+        deliverAs: "followUp" | "steer";
     }): void;
 }
 export interface SessionChannelOptions {
@@ -27,6 +27,11 @@ export interface SessionChannelOptions {
     readonly transcribe?: Transcribe;
     /** Whether the session is between runs, so a Message can start one now. */
     readonly isIdle: () => boolean;
+    /**
+     * Where the chat of the last accepted Message is kept across restarts. A
+     * run no Message started (a helper's result) sends its words there.
+     */
+    readonly lastChatFile?: string;
 }
 /**
  * The line sent when a run fails before it has words, so the person is not
@@ -70,11 +75,24 @@ export declare class SessionChannel {
     receive(event: RelayWebhookEvent): Promise<void>;
     /** The chat whose Message the session is answering now, for the Relay tools. */
     get chatId(): string | undefined;
+    /** The Message the session is answering now, for relay_react. */
+    get messageId(): string | undefined;
     /** Pi's `agent_end`: the messages of the run that just ended. */
     ended(messages: readonly unknown[]): void;
-    /** Pi's `agent_settled`: the pending Message is answered and cleared, then the next one starts. */
+    /**
+     * Pi's `agent_settled`: the pending Message is answered and cleared, then
+     * the next one starts. A run no Message started and no one typed (a
+     * helper's result) sends its words to the last chat, as OpenClaw sends an
+     * unprompted turn to the last route.
+     */
     settled(): Promise<void>;
-    /** Starts the next waiting Message when nothing of Relay's is running and the session is idle. */
+    /**
+     * Starts the next waiting Message when nothing of Relay's is running. When
+     * the session is busy with a run Relay did not start, the Message steers
+     * that run and its settled answer goes to the chat once.
+     */
     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

@@ -1,5 +1,6 @@
+import { readFileSync, writeFileSync } from "node:fs";
 import Relay, {} from "@relaymessenger/sdk";
-import { piPrompt, repliedContext, sendAnswer, wordsOf } from "./index.js";
+import { messageIdLine, piPrompt, repliedContext, sendAnswer, typing, wordsOf } from "./index.js";
 /**
  * The line sent when a run fails before it has words, so the person is not
  * left waiting. A run that ends with no words on its own is Pi staying
@@ -38,7 +39,7 @@ export const sessionContent = async (data, media, replyLine = "") => {
     const words = [wordsOf(data), lines.join("\n"), replyLine].filter(Boolean).join("\n\n");
     if (!words)
         return null;
-    return [{ type: "text", text: piPrompt(words) }, ...images];
+    return [{ type: "text", text: piPrompt([words, messageIdLine(data)].filter(Boolean).join("\n\n")) }, ...images];
 };
 /**
  * What a finished run sends: the words of its last assistant message,
@@ -84,12 +85,21 @@ export class SessionChannel {
     #inflight = new Map();
     #pending;
     #ended = [];
+    // The role of the first message of the first run since the last settle:
+    // "user" for a typed or Relay prompt, "custom" for an extension's message.
+    #origin;
+    #last;
     constructor(pi, options) {
         if (!options.agentToken.trim())
             throw new Error("Relay Agent Token is required");
         this.#pi = pi;
         this.#options = options;
         this.#relay = options.relay ?? new Relay({ apiKey: options.agentToken, ...(options.baseURL ? { baseURL: options.baseURL } : {}) });
+        try {
+            if (options.lastChatFile)
+                this.#last = JSON.parse(readFileSync(options.lastChatFile, "utf8"));
+        }
+        catch { /* no chat yet */ }
     }
     run(signal) {
         return this.#relay.websocket.run({
@@ -113,6 +123,7 @@ export class SessionChannel {
                 ...(this.#options.transcribe ? { transcribe: this.#options.transcribe } : {}),
             }, await repliedContext(this.#relay, event.data));
             this.#seen.add(event.event_id);
+            this.#remember(event.data);
             if (!content)
                 return;
             this.#queue.push({ data: event.data, key: `pi-${event.event_id}`, content });
@@ -130,34 +141,60 @@ export class SessionChannel {
     get chatId() {
         return this.#pending?.data.chat.id;
     }
+    /** The Message the session is answering now, for relay_react. */
+    get messageId() {
+        return this.#pending?.data.id;
+    }
     /** Pi's `agent_end`: the messages of the run that just ended. */
     ended(messages) {
-        if (this.#pending)
-            this.#ended = messages;
+        if (!this.#pending && this.#origin === undefined)
+            this.#origin = messages[0]?.role ?? null;
+        this.#ended = messages;
     }
-    /** Pi's `agent_settled`: the pending Message is answered and cleared, then the next one starts. */
+    /**
+     * Pi's `agent_settled`: the pending Message is answered and cleared, then
+     * the next one starts. A run no Message started and no one typed (a
+     * helper's result) sends its words to the last chat, as OpenClaw sends an
+     * unprompted turn to the last route.
+     */
     async settled() {
         const turn = this.#pending;
         this.#pending = undefined;
         const answer = lastAnswer(this.#ended);
+        const unprompted = !turn && this.#origin && this.#origin !== "user" ? this.#last : undefined;
         this.#ended = [];
+        this.#origin = undefined;
         try {
             if (turn && answer)
                 await sendAnswer(this.#relay, turn.data, turn.key, answer);
+            else if (unprompted && answer)
+                await sendAnswer(this.#relay, unprompted, `pi-unprompted-${Date.now()}`, answer);
         }
         catch (error) {
             console.error(`Relay: the answer was not sent: ${error instanceof Error ? error.message : String(error)}`);
         }
         finally {
+            if (turn)
+                await typing(this.#relay, turn.data.chat.id, false);
             this.next();
         }
     }
-    /** Starts the next waiting Message when nothing of Relay's is running and the session is idle. */
+    /**
+     * Starts the next waiting Message when nothing of Relay's is running. When
+     * the session is busy with a run Relay did not start, the Message steers
+     * that run and its settled answer goes to the chat once.
+     */
     next() {
-        if (this.#pending || !this.#queue.length || !this.#options.isIdle())
+        if (this.#pending || !this.#queue.length)
             return;
         const turn = this.#queue.shift();
         this.#pending = turn;
+        // The person sees Pi typing while it works, steered or not; settled() stops it once the answer is sent.
+        void typing(this.#relay, turn.data.chat.id, true);
+        if (!this.#options.isIdle()) {
+            this.#pi.sendUserMessage(turn.content, { deliverAs: "steer" });
+            return;
+        }
         this.#ended = [];
         try {
             this.#pi.sendUserMessage(turn.content);
@@ -171,17 +208,33 @@ export class SessionChannel {
         this.#queue.length = 0;
         this.#pending = undefined;
         this.#ended = [];
+        this.#origin = undefined;
     }
-    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);
+    /** Keeps the chat of an accepted Message, across restarts, for unprompted answers. */
+    #remember(data) {
+        this.#last = { id: data.id, chat: { id: data.chat.id }, sender_handle: { handle: data.sender_handle?.handle }, parts: [] };
+        try {
+            if (this.#options.lastChatFile)
+                writeFileSync(this.#options.lastChatFile, JSON.stringify(this.#last));
         }
-        if (!response?.ok)
-            throw new Error(`Relay attachment download failed (${response?.status ?? "no url"})`);
-        return Buffer.from(await response.arrayBuffer());
+        catch (error) {
+            console.error(`Relay: the last chat was not saved: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    #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/dist/tools.d.ts

@@ -1,3 +1,4 @@
+import { type ReactionType } from "@relaymessenger/sdk";
 import type Relay from "@relaymessenger/sdk";
 /** One tool result as Pi reads it (Pi docs/extensions.md, registerTool). */
 export interface RelayToolResult {
@@ -15,9 +16,15 @@ export interface RelayTool {
     parameters: Record<string, unknown>;
     execute(toolCallId: string, params: Record<string, unknown>): Promise<RelayToolResult>;
 }
+/** The Relay reaction for an emoji: a tapback, or a custom emoji of 1 to 32 characters. */
+export declare const relayReaction: (emoji: string) => {
+    type: ReactionType;
+    custom_emoji?: string;
+};
 /**
  * The Relay tools a Pi gets for the chat it is answering: ask for the
- * person's location, read it, and send a file. `chatId` is read when the tool
- * runs, so a session that moves between chats acts on the current one.
+ * person's location, read it, send a file, and react to a Message. `chatId`
+ * and `messageId` (the Message being answered) are read when the tool runs,
+ * so a session that moves between chats acts on the current one.
  */
-export declare const relayTools: (relay: Relay, chatId: () => string | undefined) => RelayTool[];
+export declare const relayTools: (relay: Relay, chatId: () => string | undefined, messageId?: () => string | undefined) => RelayTool[];

package/dist/tools.js

@@ -21,18 +21,35 @@ const CONTENT_TYPES = {
     ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
     ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
 };
+/** Relay's six tapbacks, by the emoji a model writes for each; any other emoji is a custom reaction (as packages/openclaw/src/actions.ts). */
+const TAPBACKS = {
+    "❤️": "love", "❤": "love", "love": "love",
+    "👍": "like", "like": "like",
+    "👎": "dislike", "dislike": "dislike",
+    "😂": "laugh", "laugh": "laugh",
+    "‼️": "emphasize", "‼": "emphasize", "emphasize": "emphasize",
+    "❓": "question", "?": "question", "question": "question",
+};
+/** The Relay reaction for an emoji: a tapback, or a custom emoji of 1 to 32 characters. */
+export const relayReaction = (emoji) => {
+    const value = emoji.trim();
+    const tapback = TAPBACKS[value] ?? TAPBACKS[value.toLowerCase()];
+    return tapback ? { type: tapback } : { type: "custom", custom_emoji: value };
+};
 /**
  * The Relay tools a Pi gets for the chat it is answering: ask for the
- * person's location, read it, and send a file. `chatId` is read when the tool
- * runs, so a session that moves between chats acts on the current one.
+ * person's location, read it, send a file, and react to a Message. `chatId`
+ * and `messageId` (the Message being answered) are read when the tool runs,
+ * so a session that moves between chats acts on the current one.
  */
-export const relayTools = (relay, chatId) => {
+export const relayTools = (relay, chatId, messageId = () => undefined) => {
     const chat = () => {
         const id = chatId();
         if (!id)
             throw new Error("No Relay chat is being answered now.");
         return id;
     };
+    const named = (value) => typeof value === "string" && value.trim() ? value.trim() : undefined;
     return [
         {
             name: "relay_request_location",
@@ -71,10 +88,13 @@ export const relayTools = (relay, chatId) => {
             name: "relay_send_media",
             label: "Send file",
             description: "Send a file from this machine to the Relay chat as its own Message: a photo, video, audio, PDF or document. "
-                + "Give its path.",
+                + "Give its path, and reply_to to thread it to a Message by its id.",
             parameters: {
                 type: "object",
-                properties: { path: { type: "string", description: "The file's path on this machine." } },
+                properties: {
+                    path: { type: "string", description: "The file's path on this machine." },
+                    reply_to: { type: "string", description: "Optional: the id of a Message in this chat to thread the file to." },
+                },
                 required: ["path"],
                 additionalProperties: false,
             },
@@ -83,12 +103,13 @@ export const relayTools = (relay, chatId) => {
                 const contentType = CONTENT_TYPES[extname(path).toLowerCase()];
                 if (!contentType)
                     return result(`Relay does not take ${extname(path) || "files without an extension"}; send a photo, video, audio, PDF or document.`);
+                const replyTo = named(params.reply_to);
                 const bytes = await readFile(path);
                 try {
                     const allocation = await relay.attachments.create({ filename: basename(path), content_type: contentType, size_bytes: bytes.byteLength });
                     await relay.attachments.upload(allocation, new Uint8Array(bytes));
                     await relay.chats.messages.send(chat(), {
-                        message: { parts: [{ type: "media", attachment_id: allocation.attachment_id }], idempotency_key: `pi-media-${toolCallId || randomUUID()}` },
+                        message: { parts: [{ type: "media", attachment_id: allocation.attachment_id }], idempotency_key: `pi-media-${toolCallId || randomUUID()}`, ...(replyTo ? { reply_to: { message_id: replyTo } } : {}) },
                     });
                     return result(`Sent ${basename(path)}.`, { attachment_id: allocation.attachment_id });
                 }
@@ -97,5 +118,37 @@ export const relayTools = (relay, chatId) => {
                 }
             },
         },
+        {
+            name: "relay_react",
+            label: "React",
+            description: "React to a Message in this Relay chat with an emoji: ❤️ 👍 👎 😂 ‼️ ❓ are tapbacks, any other emoji is a custom reaction. "
+                + "Reacts to the Message you are answering unless message_id names another. Set remove to take a reaction back.",
+            parameters: {
+                type: "object",
+                properties: {
+                    emoji: { type: "string", description: "The emoji to react with." },
+                    message_id: { type: "string", description: "Optional: the id of the Message to react to; the one being answered when absent." },
+                    remove: { type: "boolean", description: "Remove this reaction instead of adding it." },
+                },
+                required: ["emoji"],
+                additionalProperties: false,
+            },
+            execute: async (_toolCallId, params) => {
+                const emoji = named(params.emoji);
+                if (!emoji)
+                    return result("Name the emoji to react with.");
+                const target = named(params.message_id) ?? messageId();
+                if (!target)
+                    return result("No Relay Message is being answered now; name one with message_id.");
+                const remove = params.remove === true;
+                try {
+                    await relay.messages.addReaction(target, { operation: remove ? "remove" : "add", ...relayReaction(emoji) });
+                    return result(`${remove ? "Removed" : "Reacted"} ${emoji}.`, { message_id: target });
+                }
+                catch (error) {
+                    return refusal(error);
+                }
+            },
+        },
     ];
 };

package/package.json

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