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

package/README.md

@@ -102,8 +102,18 @@ 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
@@ -130,7 +140,7 @@ aliases of `message` file and react.
 `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

@@ -92,18 +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
  * (`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. 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.";
+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,18 +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. 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}`;
+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
  * (`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. 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.";
+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;
@@ -276,7 +287,7 @@ 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;
@@ -285,7 +296,7 @@ export class PiChannel {
         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);

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,8 +45,8 @@ 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>;

package/dist/session.js

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import Relay, {} from "@relaymessenger/sdk";
-import { messageIdLine, piPrompt, repliedContext, replyTag, sendAnswer, sendToChat, 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
@@ -11,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 = "") => {
@@ -40,7 +40,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, 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("");

package/package.json

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