@relaymessenger/pi 0.1.11 → 0.1.12-staging.1

package/README.md

@@ -102,25 +102,45 @@ not also run session mode on the same Agent Token.
 
 ## Parts, silence and tools
 
+Relay describes itself once, in the system prompt, the way Hermes and
+OpenClaw give each platform a short hint: what renders in a Relay chat, that
+the final answer is sent to the chat, and that the `message` tool can text,
+react or send a file, images included, at any time. `runPiChannel` passes it
+with `--append-system-prompt`; session mode adds it as a `relay` section from
+`before_agent_start` while Relay is attached. Each Message reaches Pi as its
+own words only: the text, the Message it replies to, and its Relay message id.
+The pi-channels adapter adds no hint: pi-channels answers in its own
+subprocesses, started with `--no-extensions`.
+
 Pi's final text carries Relay's parts as fenced blocks, read by the SDK's
-`answerMessages`, and every prompt teaches them: `buttons`, `selection`,
+`answerMessages`, and the hint teaches them: `buttons`, `selection`,
 `form`, `rich_card`, `carousel` (2 to 10 cards), `place`, `payment` and
 `rating_request`, plus a URL alone on a line for a link card. A final answer
 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.
 
-Each prompt ends with `[Relay message id: <id>]`. An answer that contains
+Each Message 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

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>;
@@ -83,19 +92,27 @@ export declare const piEnv: (options: Pick<PiChannelOptions, "agentToken" | "bas
  */
 export declare const wordsOf: (data: MessageWebhookData) => string;
 /**
- * The prompt pi is given for one message: the words, then how to answer.
- * This process sends pi's final text for it, and the same buttons and link
- * rules every other runtime carries.
+ * What Relay is and what renders there, given once in the system prompt as a
+ * platform hint (Hermes PLATFORM_HINTS, OpenClaw inboundFormattingHints), so
+ * each Message reaches Pi as the person's own words.
  */
-export declare const piPrompt: (message: string) => string;
+export declare const RELAY_HINT: string;
+/** The system prompt section the hint goes in: Pi wraps it as `<relay>…</relay>`. */
+export declare const RELAY_HINT_SECTION = "relay";
 /**
  * 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 whole hint: what renders, then the Relay tools. */
+export declare const relayHint: () => string;
+/**
+ * One inbound Message as Pi reads it: the person's words, the line naming
+ * the Message it replies to, and its Relay message id.
+ */
+export declare const inboundText: (words: string, replyLine: string, data: Pick<MessageWebhookData, "id">) => string;
 /** 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

@@ -73,19 +73,29 @@ const textFromEvent = (event) => {
     return wordsOf(event.data) || null;
 };
 /**
- * The prompt pi is given for one message: the words, then how to answer.
- * This process sends pi's final text for it, and the same buttons and link
- * rules every other runtime carries.
+ * What Relay is and what renders there, given once in the system prompt as a
+ * platform hint (Hermes PLATFORM_HINTS, OpenClaw inboundFormattingHints), so
+ * each Message reaches Pi as the person's own words.
  */
-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 RELAY_HINT = `You are in a Relay chat, a messaging app on the person's phone. Your final message is sent to the chat as your answer, and a final message with no text sends nothing. The message tool can text the person, react to a Message with an emoji, or send a file from this machine, images included, at any time; a run that texted with it sends no final message, so nothing is sent twice. Inline Markdown renders: bold, italic, strikethrough, code, links. Headings, lists and code fences show as written.
+
+${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}`;
+/** The system prompt section the hint goes in: Pi wraps it as `<relay>…</relay>`. */
+export const RELAY_HINT_SECTION = "relay";
 /**
  * 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 whole hint: what renders, then the Relay tools. */
+export const relayHint = () => `${RELAY_HINT}\n\n${RELAY_TOOLS_LINE}`;
+/**
+ * One inbound Message as Pi reads it: the person's words, the line naming
+ * the Message it replies to, and its Relay message id.
+ */
+export const inboundText = (words, replyLine, data) => [words, replyLine, messageIdLine(data)].filter(Boolean).join("\n\n");
 /** 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 +141,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 +198,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;
@@ -273,23 +287,25 @@ export class PiChannel {
         const data = event.data;
         let session = this.#sessions.get(data.chat.id);
         if (!session) {
-            session = new ChatSession(this.#spawnPi(this.#options.piCommand ?? "pi", ["--mode", "rpc", ...(this.#options.piArgs ?? [])], data.chat.id), this.#options.approvals);
+            session = new ChatSession(this.#spawnPi(this.#options.piCommand ?? "pi", ["--mode", "rpc", "--append-system-prompt", relayHint(), ...(this.#options.piArgs ?? [])], data.chat.id), this.#options.approvals);
             this.#sessions.set(data.chat.id, session);
         }
         const timeout = this.#options.rpcTimeoutMs ?? 60_000;
         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);
+            await session.command("prompt", { message: inboundText(message, replyLine, data) }, 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)
+            // 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/native.d.ts

@@ -27,6 +27,14 @@ export declare const relaySettings: (dir?: string) => Promise<RelaySettings>;
 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>;
+/**
+ * Puts the Relay hint in the system prompt as its own section, which Pi
+ * sends once and patches only when it changes (docs/extensions.md,
+ * before_agent_start).
+ */
+export declare const addRelayHint: (options: {
+    sections: Record<string, string>;
+}) => void;
 /**
  * Pi-native entry point. By default it exposes only lifecycle-safe commands,
  * and Relay ingress is owned by runPiChannel so the CLI and extension share

package/dist/native.js

@@ -3,7 +3,7 @@ import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import Relay from "@relaymessenger/sdk";
-import { RELAY_CHAT_ID_ENV, runPiChannel } from "./index.js";
+import { RELAY_CHAT_ID_ENV, RELAY_HINT_SECTION, relayHint, runPiChannel } from "./index.js";
 import { relayTools } from "./tools.js";
 import { registerRelayAdapter, relayChannelAdapter, RELAY_ADAPTER } from "./pi-channels.js";
 import { SessionChannel } from "./session.js";
@@ -93,6 +93,8 @@ const attachSession = (pi) => {
             console.error(`Relay: the session channel stopped: ${error instanceof Error ? error.message : String(error)}`);
         });
     });
+    pi.on("before_agent_start", async (event) => { if (channel)
+        addRelayHint(event.systemPromptOptions); });
     pi.on("agent_end", async (event) => { channel?.ended(event.messages); });
     pi.on("agent_settled", async () => { await channel?.settled(); });
     pi.on("session_shutdown", async () => {
@@ -129,6 +131,14 @@ const attachPiChannels = (pi) => {
         }), RELAY_ADAPTER);
     });
 };
+/**
+ * Puts the Relay hint in the system prompt as its own section, which Pi
+ * sends once and patches only when it changes (docs/extensions.md,
+ * before_agent_start).
+ */
+export const addRelayHint = (options) => {
+    options.sections[RELAY_HINT_SECTION] = relayHint();
+};
 /** The Relay tools, as Pi registers a tool (docs/extensions.md, registerTool). */
 const registerRelayTools = (pi, relay, chatId, messageId) => {
     for (const tool of relayTools(relay, chatId, messageId))

package/dist/session.d.ts

@@ -45,17 +45,43 @@ export interface SessionMedia {
     readonly transcribe?: Transcribe;
 }
 /**
- * One Message as the session's user message: its words with the same answer
- * rules the channel gives Pi, each photo as image content, each voice note as
+ * One Message as the session's user message: its words and Relay message id,
+ * each photo as image content, each voice note as
  * its transcript, and any other file named. Null for a Message with nothing.
  */
 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 { inboundText, 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
@@ -10,8 +11,8 @@ export const NO_ANSWER = "Sorry, something went wrong on my side.";
 /** The image types a model takes as image content; any other file is named in words. */
 const IMAGE_TYPES = new Set(["image/jpeg", "image/png", "image/gif", "image/webp"]);
 /**
- * One Message as the session's user message: its words with the same answer
- * rules the channel gives Pi, each photo as image content, each voice note as
+ * One Message as the session's user message: its words and Relay message id,
+ * each photo as image content, each voice note as
  * its transcript, and any other file named. Null for a Message with nothing.
  */
 export const sessionContent = async (data, media, replyLine = "") => {
@@ -39,23 +40,103 @@ 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, messageIdLine(data)].filter(Boolean).join("\n\n")) }, ...images];
+    return [{ type: "text", text: inboundText(words, "", data) }, ...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",
+  "version": "0.1.12-staging.1",
   "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"
+    "@relaymessenger/sdk": "0.5.4-staging.0"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.86.0",