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

package/README.md

@@ -109,13 +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 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,
-`relay_send_media` uploads a file from the machine and sends it as its own
-Message (`reply_to` threads it to a Message by id), and `relay_react` reacts
+In session mode every assistant text of a run is sent, in order, each split
+at blank lines into its own Message (OpenClaw's `chunkMode: "newline"`); a
+fenced block stays with the words above it. A run that starts a background
+pi-subagents task remembers the Message it answered, and the task's result is
+sent as a reply to that Message.
+
+The extension registers the `message` tool for the chat Pi is answering (Pi
+`registerTool`, after OpenClaw's shared `message` tool): `action: "send"`
+texts the person now (`text`, optional `reply_to`), `action: "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.
+reaction), the Message being answered unless `message_id` names another, and
+`action: "file"` uploads a file from the machine and sends it as its own
+Message. A run that texts with `message` sends no final text, so nothing is
+sent twice. `relay_request_location` asks the person to share their location
+and `relay_read_location` reads where everyone sharing is now.
+`relay_send_media` and `relay_react` stay registered for one release as
+aliases of `message` file and react.
 `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.

package/dist/index.d.ts

@@ -63,6 +63,15 @@ interface RpcRecord {
     readonly message?: string;
     readonly options?: unknown;
     readonly timeout?: unknown;
+    /** `tool_execution_start` fields (Pi docs/rpc.md). */
+    readonly toolName?: string;
+    readonly isError?: boolean;
+    /** `tool_execution_end`: the tool's result. */
+    readonly result?: {
+        details?: {
+            sent?: unknown;
+        };
+    };
 }
 /** The `extension_ui_response` to one dialog request, from the option picked. */
 export declare const dialogResponse: (record: Pick<RpcRecord, "id" | "method">, picked: string | undefined) => Record<string, unknown>;
@@ -90,12 +99,11 @@ 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_react`), and the reply tags OpenClaw's channels read
+ * (`message`, `relay_request_location`, `relay_read_location`), 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. 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.";
+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. message texts the person now (action send), reacts to a Message with an emoji (react), or sends a file from this machine (file). 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;
 /**

package/dist/index.js

@@ -77,15 +77,14 @@ const textFromEvent = (event) => {
  * This process sends pi's final text for it, and the same buttons and link
  * rules every other runtime carries.
  */
-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}`;
+export const piPrompt = (message) => `${message}\n\nWrite your answer as your final message: Relay sends that answer to the chat for you. Or text the person yourself with the message tool, then end with no text so nothing is sent twice. 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_react`), and the reply tags OpenClaw's channels read
+ * (`message`, `relay_request_location`, `relay_read_location`), 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. 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.";
+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. message texts the person now (action send), reacts to a Message with an emoji (react), or sends a file from this machine (file). 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;
@@ -131,6 +130,8 @@ class ChatSession {
     process;
     lines;
     settled = false;
+    /** Whether Pi texted the chat itself with `message` since the last prompt, so its final text is not sent again. */
+    texted = false;
     nextId = 0;
     /** Dialogs waiting on a person; Pi is silent meanwhile, which is not a stall. */
     dialogs = 0;
@@ -186,6 +187,8 @@ class ChatSession {
             const record = JSON.parse(result.value);
             if (record.type === "agent_settled")
                 this.settled = true;
+            if (record.type === "tool_execution_end" && record.toolName === "message" && !record.isError && record.result?.details?.sent === true)
+                this.texted = true;
             if (record.type === "extension_ui_request" && DIALOG_METHODS.has(String(record.method)))
                 this.#answer(record);
             return record;
@@ -280,6 +283,7 @@ export class PiChannel {
         const replyLine = await repliedContext(this.#relay, data);
         // The person sees Pi typing while it works; it stops once the answer is sent.
         await typing(this.#relay, data.chat.id, true);
+        session.texted = false;
         try {
             await session.command("prompt", { message: piPrompt([message, replyLine, messageIdLine(data)].filter(Boolean).join("\n\n")) }, timeout, signal);
             if (!session.settled) {
@@ -288,8 +292,9 @@ export class PiChannel {
             }
             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)
+            // No words is Pi's choice to stay silent, and a Pi that texted with
+            // `message` has said it (OpenClaw didSendViaMessagingTool): nothing is sent.
+            if (!answer || session.texted)
                 return;
             await sendAnswer(this.#relay, data, `pi-${event.event_id}`, answer);
         }

package/dist/session.d.ts

@@ -51,11 +51,37 @@ export interface SessionMedia {
  */
 export declare const sessionContent: (data: MessageWebhookData, media: SessionMedia, replyLine?: string) => Promise<SessionContent | null>;
 /**
- * What a finished run sends: the words of its last assistant message,
- * `NO_ANSWER` when that message ended in an error with no words, or undefined
- * for a run that chose to say nothing.
+ * What a finished run sends: the words of every assistant message in order,
+ * `NO_ANSWER` when it has none and its last assistant message ended in an
+ * error, or nothing for a run that chose to say nothing.
  */
-export declare const lastAnswer: (messages: readonly unknown[]) => string | undefined;
+export declare const runAnswers: (messages: readonly unknown[]) => string[];
+/**
+ * Whether the run texted the chat itself with `message` send, so its final
+ * words are not sent again (OpenClaw didSendViaMessagingTool). Only a send
+ * that went out counts: the tool marks it with `details.sent`.
+ */
+export declare const textedWithMessage: (messages: readonly unknown[]) => boolean;
+/** pi-subagents' tool, whose result carries `details.asyncId` when it started a background run (pi-subagents src/runs/background/async-execution.js). */
+export declare const SUBAGENT_TOOL = "subagent";
+/** The custom message pi-subagents sends when a background run finishes (src/runs/background/notify.js). */
+export declare const SUBAGENT_NOTICE = "subagent-notify";
+/** The background runs a run started: each pi-subagents launch's id and directory. */
+export declare const backgroundLaunches: (messages: readonly unknown[]) => {
+    id: string;
+    dir?: string;
+}[];
+/**
+ * One answer as the bubbles a person would send: split at blank lines
+ * (OpenClaw chunkMode "newline"), a fenced block kept whole and under the
+ * words before it, so buttons and cards stay with their text.
+ */
+export declare const bubbles: (answer: string) => string[];
+/**
+ * One answer as bubbles, its reply tag read from the whole answer first and
+ * carried by the first bubble, so a tag on a line of its own still threads.
+ */
+export declare const taggedBubbles: (answer: string) => string[];
 /** One-to-one Messages from a Handle, and only the listed Handles when there is a list. */
 export declare const accepts: (event: RelayWebhookEvent, senders?: readonly string[]) => event is RelayWebhookEvent & {
     data: MessageWebhookData;
@@ -73,17 +99,23 @@ export declare class SessionChannel {
     run(signal?: AbortSignal): Promise<void>;
     /** Takes one event: an accepted Message waits its turn in the session. */
     receive(event: RelayWebhookEvent): Promise<void>;
-    /** The chat whose Message the session is answering now, for the Relay tools. */
+    /**
+     * The chat the Relay tools act on: the one whose Message the session is
+     * answering, else (a background result's run) the chat of the Message whose
+     * turn started the newest waiting background run, else the last chat.
+     */
     get chatId(): string | undefined;
-    /** The Message the session is answering now, for relay_react. */
+    /** The Message the tools react and thread to, chosen as `chatId` is. */
     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. 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.
+     * the next one starts. Every assistant text of the run goes out as bubbles,
+     * unless the run texted the chat itself with `message`. A run no Message
+     * started and no one typed (a helper's result) sends its words as a reply to
+     * the Message whose turn started that background run, or else to the last
+     * chat, as OpenClaw sends an unprompted turn to the last route.
      */
     settled(): Promise<void>;
     /**

package/dist/session.js

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import Relay, {} from "@relaymessenger/sdk";
-import { messageIdLine, piPrompt, repliedContext, sendAnswer, typing, wordsOf } from "./index.js";
+import { messageIdLine, piPrompt, repliedContext, replyTag, sendAnswer, sendToChat, typing, wordsOf } from "./index.js";
+import { MESSAGE_TOOL } from "./tools.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
@@ -41,21 +42,101 @@ export const sessionContent = async (data, media, replyLine = "") => {
         return null;
     return [{ type: "text", text: piPrompt([words, messageIdLine(data)].filter(Boolean).join("\n\n")) }, ...images];
 };
+const blocksOf = (message) => Array.isArray(message.content) ? message.content : [];
+const textOf = (message) => typeof message.content === "string" ? message.content : blocksOf(message).flatMap((block) => block?.type === "text" && block.text ? [block.text] : []).join("");
 /**
- * What a finished run sends: the words of its last assistant message,
- * `NO_ANSWER` when that message ended in an error with no words, or undefined
- * for a run that chose to say nothing.
+ * What a finished run sends: the words of every assistant message in order,
+ * `NO_ANSWER` when it has none and its last assistant message ended in an
+ * error, or nothing for a run that chose to say nothing.
  */
-export const lastAnswer = (messages) => {
-    for (let index = messages.length - 1; index >= 0; index--) {
-        const message = messages[index];
-        if (message?.role !== "assistant")
+export const runAnswers = (messages) => {
+    const assistants = messages.filter((message) => message?.role === "assistant");
+    const answers = assistants.map((message) => textOf(message).trim()).filter(Boolean);
+    if (answers.length)
+        return answers;
+    return assistants.at(-1)?.stopReason === "error" ? [NO_ANSWER] : [];
+};
+/**
+ * Whether the run texted the chat itself with `message` send, so its final
+ * words are not sent again (OpenClaw didSendViaMessagingTool). Only a send
+ * that went out counts: the tool marks it with `details.sent`.
+ */
+export const textedWithMessage = (messages) => messages.some((message) => message?.role === "toolResult" && message.toolName === MESSAGE_TOOL
+    && !message.isError && message.details?.sent === true);
+/** pi-subagents' tool, whose result carries `details.asyncId` when it started a background run (pi-subagents src/runs/background/async-execution.js). */
+export const SUBAGENT_TOOL = "subagent";
+/** The custom message pi-subagents sends when a background run finishes (src/runs/background/notify.js). */
+export const SUBAGENT_NOTICE = "subagent-notify";
+/** The background runs a run started: each pi-subagents launch's id and directory. */
+export const backgroundLaunches = (messages) => messages.flatMap((message) => {
+    if (message?.role !== "toolResult" || message.toolName !== SUBAGENT_TOOL || message.isError)
+        return [];
+    const details = message.details;
+    if (typeof details?.asyncId !== "string" || !details.asyncId)
+        return [];
+    return [{ id: details.asyncId, ...(typeof details.asyncDir === "string" && details.asyncDir ? { dir: details.asyncDir } : {}) }];
+});
+/**
+ * One answer as the bubbles a person would send: split at blank lines
+ * (OpenClaw chunkMode "newline"), a fenced block kept whole and under the
+ * words before it, so buttons and cards stay with their text.
+ */
+export const bubbles = (answer) => {
+    const out = [];
+    let current = [];
+    // The open fence's character and length: CommonMark closes it with the same
+    // character, at least as many, and nothing after but spaces.
+    let fence;
+    let fencedBlock = false;
+    const flush = () => {
+        const text = current.join("\n").trim();
+        current = [];
+        const block = fencedBlock;
+        fencedBlock = false;
+        if (!text)
+            return;
+        if (block && out.length)
+            out[out.length - 1] += `\n\n${text}`;
+        else
+            out.push(text);
+    };
+    for (const line of answer.replace(/\r\n?/gu, "\n").split("\n")) {
+        const marker = /^ {0,3}(`{3,}|~{3,})(.*)$/u.exec(line);
+        if (!fence && marker && !(marker[1][0] === "`" && marker[2].includes("`"))) {
+            flush();
+            fence = { char: marker[1][0], length: marker[1].length };
+            fencedBlock = true;
+            current.push(line);
+            continue;
+        }
+        if (fence) {
+            current.push(line);
+            if (marker && marker[1][0] === fence.char && marker[1].length >= fence.length && !marker[2].trim()) {
+                fence = undefined;
+                flush();
+            }
+            continue;
+        }
+        if (!line.trim()) {
+            flush();
             continue;
-        const blocks = Array.isArray(message.content) ? message.content : [];
-        const text = blocks.flatMap((block) => block?.type === "text" && block.text ? [block.text] : []).join("").trim();
-        return text || (message.stopReason === "error" ? NO_ANSWER : undefined);
+        }
+        current.push(line);
     }
-    return undefined;
+    flush();
+    return out;
+};
+/**
+ * One answer as bubbles, its reply tag read from the whole answer first and
+ * carried by the first bubble, so a tag on a line of its own still threads.
+ */
+export const taggedBubbles = (answer) => {
+    const tagged = replyTag(answer);
+    const parts = bubbles(tagged.answer);
+    if (tagged.replyTo === undefined || !parts.length)
+        return parts;
+    parts[0] = `${tagged.replyTo === "current" ? "[[reply_to_current]]" : `[[reply_to:${tagged.replyTo}]]`} ${parts[0]}`;
+    return parts;
 };
 /** One-to-one Messages from a Handle, and only the listed Handles when there is a list. */
 export const accepts = (event, senders = []) => {
@@ -89,6 +170,10 @@ export class SessionChannel {
     // "user" for a typed or Relay prompt, "custom" for an extension's message.
     #origin;
     #last;
+    // Whether a run since the last settle texted the chat itself with `message`.
+    #texted = false;
+    // Background runs a Message's turn started, so each result threads to that Message.
+    #background = [];
     constructor(pi, options) {
         if (!options.agentToken.trim())
             throw new Error("Relay Agent Token is required");
@@ -137,38 +222,56 @@ export class SessionChannel {
             this.#inflight.delete(event.event_id);
         }
     }
-    /** The chat whose Message the session is answering now, for the Relay tools. */
+    /**
+     * The chat the Relay tools act on: the one whose Message the session is
+     * answering, else (a background result's run) the chat of the Message whose
+     * turn started the newest waiting background run, else the last chat.
+     */
     get chatId() {
-        return this.#pending?.data.chat.id;
+        return (this.#pending?.data ?? this.#background.at(-1)?.data ?? this.#last)?.chat.id;
     }
-    /** The Message the session is answering now, for relay_react. */
+    /** The Message the tools react and thread to, chosen as `chatId` is. */
     get messageId() {
-        return this.#pending?.data.id;
+        return (this.#pending?.data ?? this.#background.at(-1)?.data ?? this.#last)?.id;
     }
     /** Pi's `agent_end`: the messages of the run that just ended. */
     ended(messages) {
         if (!this.#pending && this.#origin === undefined)
             this.#origin = messages[0]?.role ?? null;
         this.#ended = messages;
+        if (textedWithMessage(messages))
+            this.#texted = true;
+        const data = this.#pending?.data;
+        if (data)
+            for (const launch of backgroundLaunches(messages))
+                this.#background.push({ ...launch, data });
     }
     /**
      * 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.
+     * the next one starts. Every assistant text of the run goes out as bubbles,
+     * unless the run texted the chat itself with `message`. A run no Message
+     * started and no one typed (a helper's result) sends its words as a reply to
+     * the Message whose turn started that background run, or else 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;
+        const answers = this.#texted ? [] : runAnswers(this.#ended).flatMap(taggedBubbles);
+        const unprompted = !turn && this.#origin && this.#origin !== "user";
+        const started = unprompted ? this.#startedBy(this.#ended[0]) : undefined;
         this.#ended = [];
         this.#origin = undefined;
+        this.#texted = false;
         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);
+            for (const [index, bubble] of answers.entries()) {
+                if (turn)
+                    await sendAnswer(this.#relay, turn.data, index ? `${turn.key}-p${index}` : turn.key, bubble);
+                else if (started)
+                    await sendToChat(this.#relay, started.data.chat.id, `pi-background-${started.id}-${index}`, bubble, started.data.id, started.data.id);
+                else if (unprompted && this.#last)
+                    await sendAnswer(this.#relay, this.#last, `pi-unprompted-${Date.now()}-${index}`, bubble);
+            }
         }
         catch (error) {
             console.error(`Relay: the answer was not sent: ${error instanceof Error ? error.message : String(error)}`);
@@ -179,6 +282,22 @@ export class SessionChannel {
             this.next();
         }
     }
+    /**
+     * The Message whose turn started the background run this notice reports,
+     * found by the run's id or directory in the notice; the one waiting run when
+     * a pi-subagents notice names none. It is forgotten once found.
+     */
+    #startedBy(first) {
+        const notice = first;
+        if (notice?.role !== "custom")
+            return undefined;
+        const words = textOf(notice);
+        const named = this.#background.filter((launch) => words.includes(launch.id) || (launch.dir !== undefined && words.includes(launch.dir)));
+        const found = named.length ? named : notice.customType === SUBAGENT_NOTICE && this.#background.length === 1 ? [...this.#background] : [];
+        for (const launch of found)
+            this.#background.splice(this.#background.indexOf(launch), 1);
+        return found[0];
+    }
     /**
      * 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
@@ -209,6 +328,8 @@ export class SessionChannel {
         this.#pending = undefined;
         this.#ended = [];
         this.#origin = undefined;
+        this.#texted = false;
+        this.#background.length = 0;
     }
     /** Keeps the chat of an accepted Message, across restarts, for unprompted answers. */
     #remember(data) {

package/dist/tools.d.ts

@@ -1,5 +1,7 @@
 import { type ReactionType } from "@relaymessenger/sdk";
 import type Relay from "@relaymessenger/sdk";
+/** The tool a Pi texts the person with (OpenClaw's shared `message` tool: send, react, file). */
+export declare const MESSAGE_TOOL = "message";
 /** One tool result as Pi reads it (Pi docs/extensions.md, registerTool). */
 export interface RelayToolResult {
     content: {
@@ -22,8 +24,8 @@ export declare const relayReaction: (emoji: string) => {
     custom_emoji?: string;
 };
 /**
- * The Relay tools a Pi gets for the chat it is answering: ask for the
- * person's location, read it, send a file, and react to a Message. `chatId`
+ * The Relay tools a Pi gets for the chat it is answering: `message` to text,
+ * react and send a file, and the tools to ask for and read the person's location. `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.
  */

package/dist/tools.js

@@ -2,6 +2,9 @@ import { randomUUID } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { basename, extname } from "node:path";
 import { RelayAPIError } from "@relaymessenger/sdk";
+import { sendToChat } from "./index.js";
+/** The tool a Pi texts the person with (OpenClaw's shared `message` tool: send, react, file). */
+export const MESSAGE_TOOL = "message";
 const result = (text, details = {}) => ({ content: [{ type: "text", text }], details });
 /** Relay's refusal as the model's result, so it reads what to change; anything else is thrown. */
 const refusal = (error) => {
@@ -37,8 +40,8 @@ export const relayReaction = (emoji) => {
     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, send a file, and react to a Message. `chatId`
+ * The Relay tools a Pi gets for the chat it is answering: `message` to text,
+ * react and send a file, and the tools to ask for and read the person's location. `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.
  */
@@ -50,7 +53,86 @@ export const relayTools = (relay, chatId, messageId = () => undefined) => {
         return id;
     };
     const named = (value) => typeof value === "string" && value.trim() ? value.trim() : undefined;
+    const sendFile = async (toolCallId, params) => {
+        const path = String(params.path ?? "");
+        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()}`, ...(replyTo ? { reply_to: { message_id: replyTo } } : {}) },
+            });
+            return result(`Sent ${basename(path)}.`, { attachment_id: allocation.attachment_id });
+        }
+        catch (error) {
+            return refusal(error);
+        }
+    };
+    const react = async (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);
+        }
+    };
+    const sendText = async (toolCallId, params) => {
+        const text = typeof params.text === "string" ? params.text.trim() : "";
+        if (!text)
+            return result("Write the text to send.");
+        const replyTo = named(params.reply_to);
+        try {
+            await sendToChat(relay, chat(), `pi-message-${toolCallId || randomUUID()}`, text, replyTo, messageId());
+            // `sent` tells the channel this run has texted, so its final words are not sent again.
+            return result("Sent.", { sent: true });
+        }
+        catch (error) {
+            return refusal(error);
+        }
+    };
     return [
+        {
+            name: MESSAGE_TOOL,
+            label: "Message",
+            description: "Text the person in this Relay chat, the way a person texts: send a message now (several short ones read better than one long one), "
+                + "react to a Message with an emoji, or send a file. A message you send here is delivered at once, so when you have sent your answer this way "
+                + "end with no text and nothing more is sent. reply_to threads to a Message by its id.",
+            parameters: {
+                type: "object",
+                properties: {
+                    action: { type: "string", enum: ["send", "react", "file"], description: "send: a text message. react: an emoji reaction. file: a file from this machine." },
+                    text: { type: "string", description: "send: the words. Buttons, cards and the other blocks work as in an answer." },
+                    reply_to: { type: "string", description: "send, file: optional id of a Message in this chat to thread to." },
+                    emoji: { type: "string", description: "react: ❤️ 👍 👎 😂 ‼️ ❓ are tapbacks, any other emoji is a custom reaction." },
+                    message_id: { type: "string", description: "react: optional id of the Message to react to; the one being answered when absent." },
+                    remove: { type: "boolean", description: "react: take the reaction back." },
+                    path: { type: "string", description: "file: the file's path on this machine: a photo, video, audio, PDF or document." },
+                },
+                required: ["action"],
+                additionalProperties: false,
+            },
+            execute: async (toolCallId, params) => {
+                if (params.action === "send")
+                    return sendText(toolCallId, params);
+                if (params.action === "react")
+                    return react(params);
+                if (params.action === "file")
+                    return sendFile(toolCallId, params);
+                return result("Name an action: send, react or file.");
+            },
+        },
         {
             name: "relay_request_location",
             label: "Request location",
@@ -84,71 +166,30 @@ export const relayTools = (relay, chatId, messageId = () => undefined) => {
                 }
             },
         },
+        // The 0.1.11 names, kept for one release so a session that learned them still works; `message` replaces both.
         {
             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, and reply_to to thread it to a Message by its id.",
+            description: "Same as message with action file. Give path, and reply_to to thread it.",
             parameters: {
                 type: "object",
-                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." },
-                },
+                properties: { path: { type: "string" }, reply_to: { type: "string" } },
                 required: ["path"],
                 additionalProperties: false,
             },
-            execute: async (toolCallId, params) => {
-                const path = String(params.path ?? "");
-                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()}`, ...(replyTo ? { reply_to: { message_id: replyTo } } : {}) },
-                    });
-                    return result(`Sent ${basename(path)}.`, { attachment_id: allocation.attachment_id });
-                }
-                catch (error) {
-                    return refusal(error);
-                }
-            },
+            execute: (toolCallId, params) => sendFile(toolCallId, params),
         },
         {
             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.",
+            description: "Same as message with action react.",
             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." },
-                },
+                properties: { emoji: { type: "string" }, message_id: { type: "string" }, remove: { type: "boolean" } },
                 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);
-                }
-            },
+            execute: (_toolCallId, params) => react(params),
         },
     ];
 };

package/package.json

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