@relaymessenger/pi 0.1.11-staging.1 → 0.1.11

package/README.md

@@ -47,6 +47,13 @@ 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)
@@ -102,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
@@ -123,8 +137,16 @@ export declare const repliedContext: (relay: Relay, data: MessageWebhookData) =>
 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.
+ * 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 sendToChat: (relay: Relay, chatId: string, key: string, answer: string, replyTo?: string) => Promise<void>;
+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);
     }
 }
 /**
@@ -297,16 +321,23 @@ 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" ? data.id : undefined;
-    await sendToChat(relay, data.chat.id, key, answer, replyTo);
+    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.
+ * 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) => {
-    const messages = answerMessages(answer);
+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()) {
@@ -323,7 +354,16 @@ export const sendToChat = async (relay, chatId, key, answer, replyTo) => {
                 continue;
             }
         }
-        await relay.chats.messages.send(chatId, { message: { parts, idempotency_key: messageKey, ...(index === 0 && replyTo ? { reply_to: { message_id: 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.js

@@ -82,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)}`);
         });
@@ -129,8 +130,8 @@ const attachPiChannels = (pi) => {
     });
 };
 /** 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);
 };
 /**

package/dist/pi-channels.js

@@ -2,7 +2,7 @@ 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 { 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";
@@ -53,9 +53,11 @@ export const incomingMessage = async (relay, event, options = {}) => {
             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)
+    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,

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,22 @@ 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;
 }

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,6 +208,18 @@ export class SessionChannel {
         this.#queue.length = 0;
         this.#pending = undefined;
         this.#ended = [];
+        this.#origin = undefined;
+    }
+    /** 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));
+        }
+        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);

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.1",
+  "version": "0.1.11",
   "description": "Relay Messenger channel for Pi over Relay v1 WebSocket delivery.",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,7 +34,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@relaymessenger/sdk": "0.5.4-staging.0"
+    "@relaymessenger/sdk": "0.5.4"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.86.0",