@relaymessenger/pi 0.1.4-staging.4 → 0.1.4-staging.40

package/README.md

@@ -15,3 +15,27 @@ pi install npm:@relaymessenger/pi
 
 Set `RELAY_AGENT_TOKEN` before using `/relay-connect`. Set
 `RELAY_BASE_URL` when the Agent belongs to a non-default API environment.
+
+## Selection
+
+End the final Pi answer with a `selection` JSON fence holding the question as
+`title` (1 to 60 characters) and the `options`; any words outside the fence go
+as a normal message above the card.
+The RPC prompt preserves ordered rich parts, `selected_values`, and `reply_to`
+as data. FULL sync still fails closed rather than discarding skipped context.
+
+New human reply text is literal `• ` + each selected source label joined with
+`\n`, followed by `selection_response` metadata in source-option order. Dispatch
+with `selected_values` and the explicit source target, never label parsing.
+Exact legacy comma-joined text remains a server compatibility input. The person
+checks any number of options and submits them once; checking sends nothing, and
+a person answers a given selection once. iOS may draw a checkmark in place of
+each bullet and repeat the prompt's title, as presentation only.
+
+## Payment
+
+The agent ends the final Pi answer with a `payment` JSON fence holding the
+payment request's fields (`description`, `category`, and `amount` with
+`currency`, or `mode: "subscription"` with `price_id`). The plugin creates the
+request with its own Relay token, on the card's own idempotency key; the words
+go first and the payment card follows as its own Message.

package/dist/index.d.ts

@@ -1,4 +1,31 @@
-import Relay from "@relaymessenger/sdk";
+import Relay, { type MessagePart, type PaymentRequestCreateParams, type RelayWebhookEvent } from "@relaymessenger/sdk";
+/**
+ * A dialog one of the person's own Pi extensions opened with `ctx.ui.select`
+ * or `ctx.ui.confirm`, the way Pi asks before a tool runs: Pi has "No
+ * permission popups" and leaves confirmation flows to extensions (Pi README;
+ * examples/extensions/permission-gate.ts). In RPC mode each one arrives as an
+ * `extension_ui_request` and waits for an `extension_ui_response` (Pi
+ * docs/rpc.md, "Extension UI Protocol").
+ */
+export interface PiDialog {
+    readonly method: "select" | "confirm";
+    readonly title: string;
+    readonly message?: string;
+    /** What the person picks from: the select's options, or Yes and No for a confirm. */
+    readonly options: readonly string[];
+    /** Pi's own wait: "the agent-side will auto-resolve with a default value when the timeout expires". */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+/** Who answers Pi's dialogs, and reads the taps that answer them. */
+export interface PiApprovals {
+    /** The option picked, or undefined for no answer. */
+    dialog(request: PiDialog): Promise<string | undefined>;
+    /** Whether this event answered a dialog, so it starts no turn. */
+    take(event: RelayWebhookEvent): Promise<boolean>;
+}
+/** A confirm's two options. */
+export declare const CONFIRM_OPTIONS: readonly ["Yes", "No"];
 export interface PiChannelOptions {
     readonly agentToken: string;
     readonly baseURL?: string;
@@ -7,6 +34,12 @@ export interface PiChannelOptions {
     readonly rpcTimeoutMs?: number;
     readonly spawnPi?: (command: string, args: readonly string[], chatId: string) => PiProcess;
     readonly relay?: Relay;
+    /**
+     * Answers the person's own extensions' dialogs. Without it, a dialog is
+     * dismissed at once (`cancelled: true`), so the extension gets its own
+     * "no answer" and the turn goes on.
+     */
+    readonly approvals?: PiApprovals;
 }
 export interface PiProcess {
     readonly stdin: {
@@ -16,6 +49,42 @@ export interface PiProcess {
     readonly stdout: AsyncIterable<string>;
     readonly kill: () => void;
 }
+interface RpcRecord {
+    readonly type?: string;
+    readonly id?: string;
+    readonly success?: boolean;
+    readonly data?: {
+        text?: string | null;
+    };
+    readonly error?: string;
+    /** `extension_ui_request` fields (Pi docs/rpc.md). */
+    readonly method?: string;
+    readonly title?: string;
+    readonly message?: string;
+    readonly options?: unknown;
+    readonly timeout?: 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>;
+/** A dialog request as `PiDialog`, or undefined for a method a card cannot answer (input, editor, fire-and-forget). */
+export declare const piDialog: (record: RpcRecord) => Omit<PiDialog, "signal"> | undefined;
+/**
+ * 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.
+ */
+export declare const piPrompt: (message: string) => string;
+/**
+ * The messages an answer becomes: each link written alone on a line as its
+ * own message, text in chunks the API takes, and the buttons its fenced block
+ * asked for under the last words. A block pi wrote that cannot be read stays
+ * in the words, so nothing the person was told is lost.
+ */
+export declare const answerMessages: (answer: string) => {
+    parts: MessagePart[];
+    error?: string;
+    payment?: PaymentRequestCreateParams;
+}[];
 export declare class PiChannel {
     #private;
     constructor(options: PiChannelOptions);
@@ -23,3 +92,4 @@ export declare class PiChannel {
     stop(): void;
 }
 export declare const runPiChannel: (options: PiChannelOptions, signal?: AbortSignal) => Promise<void>;
+export {};

package/dist/index.js

@@ -1,6 +1,31 @@
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
-import Relay, {} from "@relaymessenger/sdk";
+import Relay, { BUTTONS_BLOCK_INSTRUCTION, BUTTONS_GUIDANCE, PAYMENT_BLOCK_INSTRUCTION, PAYMENT_GUIDANCE, selectionReply, selectionReplyContext, SELECTION_GUIDANCE, SELECTION_BLOCK_INSTRUCTION, LINK_LINE_INSTRUCTION, answerMessages as splitAnswer, createPaymentPart, RelayAPIError, } from "@relaymessenger/sdk";
+/** A confirm's two options. */
+export const CONFIRM_OPTIONS = ["Yes", "No"];
+/** The `extension_ui_response` to one dialog request, from the option picked. */
+export const dialogResponse = (record, picked) => {
+    if (picked === undefined)
+        return { type: "extension_ui_response", id: record.id, cancelled: true };
+    if (record.method === "confirm")
+        return { type: "extension_ui_response", id: record.id, confirmed: picked === CONFIRM_OPTIONS[0] };
+    return { type: "extension_ui_response", id: record.id, value: picked };
+};
+/** A dialog request as `PiDialog`, or undefined for a method a card cannot answer (input, editor, fire-and-forget). */
+export const piDialog = (record) => {
+    if (record.type !== "extension_ui_request" || typeof record.id !== "string")
+        return undefined;
+    const timeoutMs = typeof record.timeout === "number" && record.timeout > 0 ? record.timeout : undefined;
+    const base = { title: typeof record.title === "string" ? record.title : "", ...(typeof record.message === "string" ? { message: record.message } : {}), ...(timeoutMs !== undefined ? { timeoutMs } : {}) };
+    if (record.method === "confirm")
+        return { method: "confirm", options: CONFIRM_OPTIONS, ...base };
+    if (record.method === "select" && Array.isArray(record.options) && record.options.every((option) => typeof option === "string") && record.options.length) {
+        return { method: "select", options: record.options, ...base };
+    }
+    return undefined;
+};
+/** The dialog methods that wait for an answer (Pi docs/rpc.md). */
+const DIALOG_METHODS = new Set(["select", "confirm", "input", "editor"]);
 class ChildPiProcess {
     #child;
     constructor(command, args) { this.#child = spawn(command, [...args], { stdio: ["pipe", "pipe", "pipe"] }); this.#child.stderr.resume(); }
@@ -11,18 +36,82 @@ class ChildPiProcess {
 const textFromEvent = (event) => {
     if (event.event_type !== "message.received" || event.data.direction !== "inbound")
         return null;
-    return event.data.parts
-        .flatMap((part) => part.type === "text" || part.type === "link"
-        ? [part.value]
-        : part.type === "button_reply" ? [part.label] : [])
-        .join("\n").trim() || null;
+    const text = event.data.parts
+        .flatMap((part) => part.type === "text" || part.type === "link" ? [part.value] : [])
+        .join("\n").trim();
+    const context = selectionReplyContext(selectionReply(event.data.parts, event.data.reply_to), {
+        parts: event.data.parts, ...(event.data.reply_to ? { reply_to: event.data.reply_to } : {}),
+    });
+    if (!text && !context)
+        return null;
+    return [text, context].filter(Boolean).join("\n\n");
+};
+/**
+ * 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.
+ */
+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. 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} ${PAYMENT_BLOCK_INSTRUCTION} ${PAYMENT_GUIDANCE}`;
+/**
+ * The messages an answer becomes: each link written alone on a line as its
+ * own message, text in chunks the API takes, and the buttons its fenced block
+ * asked for under the last words. A block pi wrote that cannot be read stays
+ * in the words, so nothing the person was told is lost.
+ */
+export const answerMessages = (answer) => {
+    const split = splitAnswer(answer);
+    const messages = [];
+    for (const [first, ...rest] of split.messages) {
+        if (first?.type !== "text" || first.value.length <= 10_000) {
+            messages.push({ parts: first ? [first, ...rest] : rest });
+            continue;
+        }
+        const chunks = first.value.match(/[\s\S]{1,10000}/gu) ?? [];
+        for (const [index, chunk] of chunks.entries()) {
+            messages.push({ parts: [{ type: "text", value: chunk }, ...(index === chunks.length - 1 ? rest : [])] });
+        }
+    }
+    if (split.error && messages[0])
+        messages[0].error = split.error;
+    // The payment request the block described: created with the card's own key
+    // and sent as the last Message.
+    if (split.payment)
+        messages.push({ parts: [], payment: split.payment });
+    return messages;
 };
 class ChatSession {
     process;
     lines;
     settled = false;
     nextId = 0;
-    constructor(process) { this.process = process; this.lines = process.stdout[Symbol.asyncIterator](); }
+    /** Dialogs waiting on a person; Pi is silent meanwhile, which is not a stall. */
+    dialogs = 0;
+    #approvals;
+    #stop = new AbortController();
+    constructor(process, approvals) {
+        this.process = process;
+        this.lines = process.stdout[Symbol.asyncIterator]();
+        this.#approvals = approvals;
+    }
+    /** Answers one dialog without holding up the reading of Pi's output. */
+    #answer(record) {
+        const dialog = piDialog(record);
+        const reply = (picked) => {
+            try {
+                this.process.stdin.write(`${JSON.stringify(dialogResponse(record, picked))}\n`);
+            }
+            catch { /* Pi is gone. */ }
+        };
+        if (!dialog || !this.#approvals) {
+            reply(undefined);
+            return;
+        }
+        this.dialogs += 1;
+        void this.#approvals.dialog({ ...dialog, signal: this.#stop.signal })
+            .catch(() => undefined)
+            .then((picked) => { reply(picked); })
+            .finally(() => { this.dialogs -= 1; });
+    }
     async read(timeoutMs, signal) {
         if (signal?.aborted)
             throw new Error("Pi RPC request aborted");
@@ -32,7 +121,14 @@ class ChatSession {
             const result = await Promise.race([
                 this.lines.next(),
                 new Promise((_, reject) => {
-                    timer = setTimeout(() => reject(new Error("Pi RPC request timed out")), timeoutMs);
+                    const expire = () => {
+                        if (this.dialogs > 0) {
+                            timer = setTimeout(expire, timeoutMs);
+                            return;
+                        }
+                        reject(new Error("Pi RPC request timed out"));
+                    };
+                    timer = setTimeout(expire, timeoutMs);
                     onAbort = () => reject(new Error("Pi RPC request aborted"));
                     signal?.addEventListener("abort", onAbort, { once: true });
                 }),
@@ -42,6 +138,8 @@ class ChatSession {
             const record = JSON.parse(result.value);
             if (record.type === "agent_settled")
                 this.settled = true;
+            if (record.type === "extension_ui_request" && DIALOG_METHODS.has(String(record.method)))
+                this.#answer(record);
             return record;
         }
         finally {
@@ -63,7 +161,7 @@ class ChatSession {
             }
         }
     }
-    stop() { this.process.stdin.end(); this.process.kill(); }
+    stop() { this.#stop.abort(); this.process.stdin.end(); this.process.kill(); }
 }
 export class PiChannel {
     #relay;
@@ -85,7 +183,8 @@ export class PiChannel {
         this.#abortListener = () => this.stop();
         signal?.addEventListener("abort", this.#abortListener, { once: true });
         try {
-            await this.#relay.websocket.run({ ...(signal ? { signal } : {}), onEvent: async (event) => this.#handle(event, signal), onFullSync: async () => { throw new Error("Pi channel cannot acknowledge FULL sync without a durable Relay inbox"); } });
+            await this.#relay.websocket.run({ ...(signal ? { signal } : {}), onEvent: async (event) => { if (await this.#options.approvals?.take(event))
+                    return; await this.#handle(event, signal); }, onFullSync: async () => { throw new Error("Pi channel cannot acknowledge FULL sync without a durable Relay inbox"); } });
         }
         finally {
             this.stop();
@@ -96,6 +195,10 @@ export class PiChannel {
     stop() { for (const session of this.#sessions.values())
         session.stop(); this.#sessions.clear(); }
     async #handle(event, signal) {
+        // Concurrent redelivery must await the original handoff, not ACK early.
+        const inflight = this.#inflight.get(event.event_id);
+        if (inflight)
+            return inflight;
         if (this.#seen.has(event.event_id))
             return;
         const message = textFromEvent(event);
@@ -122,11 +225,11 @@ 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));
+            session = new ChatSession(this.#spawnPi(this.#options.piCommand ?? "pi", ["--mode", "rpc", ...(this.#options.piArgs ?? [])], data.chat.id), this.#options.approvals);
             this.#sessions.set(data.chat.id, session);
         }
         const timeout = this.#options.rpcTimeoutMs ?? 60_000;
-        await session.command("prompt", { message }, timeout, signal);
+        await session.command("prompt", { message: piPrompt(message) }, timeout, signal);
         if (!session.settled) {
             while (!session.settled)
                 await session.read(timeout, signal);
@@ -135,9 +238,36 @@ export class PiChannel {
         const answer = response.data?.text?.trim();
         if (!answer)
             throw new Error("Pi returned no final text answer");
-        const chunks = answer.match(/[\s\S]{1,10000}/gu) ?? [];
-        for (const [index, chunk] of chunks.entries())
-            await this.#relay.chats.messages.send(data.chat.id, { message: { parts: [{ type: "text", value: chunk }], idempotency_key: `pi-${event.event_id}-${index}` } });
+        const messages = answerMessages(answer);
+        if (messages[0]?.error)
+            console.error(`Relay: the component block in pi's answer was left as text: ${messages[0].error}.`);
+        // An answer to another agent replies to its Message, as a bot's reply
+        // names the message it answers (Telegram `reply_parameters.message_id`); Relay's
+        // A2A door gives a calling agent the reply that names its message. A
+        // person's Message is not named, so the chat looks as it always has. An
+        // agent may not reply to buttons or a selection, and a reply names part 0.
+        // Turns in one chat already run one after another, so an agent's two
+        // messages each get their own answer.
+        const opening = data.parts[0]?.type;
+        const replyTo = data.sender_handle.kind === "agent" && opening !== "buttons" && opening !== "selection"
+            ? { reply_to: { message_id: data.id } }
+            : {};
+        for (const [index, message] of messages.entries()) {
+            const key = `pi-${event.event_id}-${index}`;
+            let parts = message.parts;
+            if (message.payment) {
+                try {
+                    parts = [await createPaymentPart(this.#relay, message.payment, key)];
+                }
+                catch (error) {
+                    if (!(error instanceof RelayAPIError) || error.retryable)
+                        throw error;
+                    console.error(`Relay: the payment in pi's answer was not sent: ${error.message}`);
+                    continue;
+                }
+            }
+            await this.#relay.chats.messages.send(data.chat.id, { message: { parts, idempotency_key: key, ...(index === 0 ? replyTo : {}) } });
+        }
     }
 }
 export const runPiChannel = (options, signal) => new PiChannel(options).run(signal);

package/dist/native.d.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 /**
  * Pi-native entry point. It deliberately exposes only lifecycle-safe commands;
  * Relay ingress remains owned by runPiChannel so the CLI and extension share

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relaymessenger/pi",
-  "version": "0.1.4-staging.4",
+  "version": "0.1.4-staging.40",
   "description": "Relay Messenger channel for Pi over Relay v1 WebSocket delivery.",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,11 +34,11 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@relaymessenger/sdk": "0.3.6-staging.4"
+    "@relaymessenger/sdk": "0.3.6-staging.44"
   },
   "devDependencies": {
-    "@mariozechner/pi-coding-agent": "0.73.1",
-    "@types/node": "26.0.0",
+    "@earendil-works/pi-coding-agent": "0.86.0",
+    "@types/node": "26.6.2",
     "typescript": "7.0.2",
     "vitest": "4.1.11"
   },