@relaymessenger/pi 0.1.9 → 0.1.10-staging.0

package/README.md

@@ -16,6 +16,35 @@ 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.
 
+## Inside your own Pi session
+
+By default each chat gets its own Pi. To bring Messages into the Pi session
+that loads the extension instead, set `relay` in `~/.pi/agent/settings.json`:
+
+```json
+{
+  "relay": {
+    "mode": "session",
+    "agentTokenCommand": ["secret-tool", "lookup", "service", "relay", "username", "agent"],
+    "senders": ["alice"],
+    "transcribeCpp": { "module": "~/voice/node_modules/transcribe-cpp", "model": "~/models/parakeet.gguf" }
+  }
+}
+```
+
+`RELAY_PI_MODE=session` does the same as `mode`. The token is
+`RELAY_AGENT_TOKEN`, else whatever `agentTokenCommand` prints; it is never
+logged. `RELAY_SENDERS` (comma-separated) overrides `senders`; with neither,
+any one-to-one sender is taken. Group chats are skipped.
+
+The session starts only on a Pi in RPC mode (the session an app drives),
+never a terminal Pi, a print run or a pi-subagents helper. Each Message becomes one user message
+(`pi.sendUserMessage`): photos as image content, voice notes as their
+transcript when `transcribeCpp` is set (ffmpeg decodes them first), other
+files named. Messages wait their turn, and the session's last words go back
+to the chat the Message came from once Pi reports `agent_settled`. A run that
+ends with no words sends `Sorry, something went wrong on my side.`
+
 ## Selection
 
 End the final Pi answer with a `selection` JSON fence holding the question as

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import Relay, { type MessagePart, type PaymentRequestCreateParams, type RelayWebhookEvent } from "@relaymessenger/sdk";
+import Relay, { type MessagePart, type PaymentRequestCreateParams, type MessageWebhookData, 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
@@ -68,6 +68,12 @@ interface RpcRecord {
 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 words of one inbound Message as Pi reads them: its text and links, then
+ * the data of a pin or location share, then what a selection answers. Empty
+ * for a Message with none, such as a photo alone.
+ */
+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
@@ -91,5 +97,16 @@ export declare class PiChannel {
     run(signal?: AbortSignal): Promise<void>;
     stop(): void;
 }
+/**
+ * The Message a swipe-reply answers, as one line of data. Relay sends only the
+ * pointer, as Telegram hands a bot `reply_to_message`, so it is read once; a
+ * read that fails names the target by id instead. Empty for no reply.
+ */
+export declare const repliedContext: (relay: Relay, data: MessageWebhookData) => Promise<string>;
+/**
+ * Sends Pi's answer to the chat the Message came from, as the Messages
+ * `answerMessages` makes of it, each on `${key}-${index}`.
+ */
+export declare const sendAnswer: (relay: Relay, data: MessageWebhookData, key: string, answer: string) => Promise<void>;
 export declare const runPiChannel: (options: PiChannelOptions, signal?: AbortSignal) => Promise<void>;
 export {};

package/dist/index.js

@@ -33,26 +33,32 @@ class ChildPiProcess {
     get stdout() { return createInterface({ input: this.#child.stdout }); }
     kill = () => { this.#child.kill(); };
 }
-const textFromEvent = (event) => {
-    if (event.event_type !== "message.received" || event.data.direction !== "inbound")
-        return null;
-    // A sender with no Handle is skipped.
-    if (!event.data.sender_handle)
-        return null;
+/**
+ * The words of one inbound Message as Pi reads them: its text and links, then
+ * the data of a pin or location share, then what a selection answers. Empty
+ * for a Message with none, such as a photo alone.
+ */
+export const wordsOf = (data) => {
     // A pin and a location share have no words; their data follows the words.
     const text = [
-        event.data.parts
+        data.parts
             .flatMap((part) => part.type === "text" || part.type === "link" ? [part.value] : [])
             .join("\n").trim(),
-        locationContext(event.data.parts),
+        locationContext(data.parts),
     ].filter(Boolean).join("\n\n");
-    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 } : {}),
+    const context = selectionReplyContext(selectionReply(data.parts, data.reply_to), {
+        parts: data.parts, ...(data.reply_to ? { reply_to: data.reply_to } : {}),
     });
-    if (!text && !context)
-        return null;
     return [text, context].filter(Boolean).join("\n\n");
 };
+const textFromEvent = (event) => {
+    if (event.event_type !== "message.received" || event.data.direction !== "inbound")
+        return null;
+    // A sender with no Handle is skipped.
+    if (!event.data.sender_handle)
+        return null;
+    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
@@ -236,13 +242,7 @@ export class PiChannel {
             this.#sessions.set(data.chat.id, session);
         }
         const timeout = this.#options.rpcTimeoutMs ?? 60_000;
-        // A swipe-reply names the Message it answers, as Telegram hands a bot
-        // `reply_to_message`; Relay sends only the pointer, so it is read once. A
-        // read that fails names the target by id instead.
-        const replied = data.reply_to?.message_id ? data.reply_to : undefined;
-        const replyLine = replied
-            ? replyTargetContext(replied, await (async () => this.#relay.messages.retrieve(replied.message_id))().catch(() => undefined))
-            : "";
+        const replyLine = await repliedContext(this.#relay, data);
         await session.command("prompt", { message: piPrompt([message, replyLine].filter(Boolean).join("\n\n")) }, timeout, signal);
         if (!session.settled) {
             while (!session.settled)
@@ -252,36 +252,54 @@ export class PiChannel {
         const answer = response.data?.text?.trim();
         if (!answer)
             throw new Error("Pi returned no final text answer");
-        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`), so
-        // an agent that sent several knows which one it answers. 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 sendAnswer(this.#relay, data, `pi-${event.event_id}`, answer);
+    }
+}
+/**
+ * The Message a swipe-reply answers, as one line of data. Relay sends only the
+ * pointer, as Telegram hands a bot `reply_to_message`, so it is read once; a
+ * read that fails names the target by id instead. Empty for no reply.
+ */
+export const repliedContext = async (relay, data) => {
+    const replied = data.reply_to?.message_id ? data.reply_to : undefined;
+    if (!replied)
+        return "";
+    return replyTargetContext(replied, await (async () => relay.messages.retrieve(replied.message_id))().catch(() => undefined));
+};
+/**
+ * Sends Pi's answer to the chat the Message came from, as the Messages
+ * `answerMessages` makes of it, each on `${key}-${index}`.
+ */
+export const sendAnswer = async (relay, data, key, answer) => {
+    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`), so
+    // an agent that sent several knows which one it answers. 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 messageKey = `${key}-${index}`;
+        let parts = message.parts;
+        if (message.payment) {
+            try {
+                parts = [await createPaymentPart(relay, message.payment, messageKey)];
+            }
+            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 : {}) } });
         }
+        await relay.chats.messages.send(data.chat.id, { message: { parts, idempotency_key: messageKey, ...(index === 0 ? replyTo : {}) } });
     }
-}
+};
 export const runPiChannel = (options, signal) => new PiChannel(options).run(signal);

package/dist/native.d.ts

@@ -1,7 +1,30 @@
 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
- * the same authenticated routing implementation.
+ * The `relay` key of Pi's global settings.json. With `mode: "session"` Relay
+ * runs inside the Pi session that loads this extension; otherwise the
+ * commands below start a separate Pi per chat, as before.
+ */
+export interface RelaySettings {
+    readonly mode?: "channel" | "session";
+    /** A command that prints the Agent Token, read when RELAY_AGENT_TOKEN is unset. */
+    readonly agentTokenCommand?: readonly string[];
+    readonly baseURL?: string;
+    /** Handles whose Messages reach the session; any sender when absent. */
+    readonly senders?: readonly string[];
+    /** Voice notes heard with transcribe-cpp: its installed package and a model it loads. */
+    readonly transcribeCpp?: {
+        readonly module: string;
+        readonly model: string;
+    };
+}
+/** The `relay` settings, or none when the file or key is missing or unreadable. */
+export declare const relaySettings: (dir?: string) => Promise<RelaySettings>;
+/** RELAY_AGENT_TOKEN, else what `agentTokenCommand` prints; never logged. */
+export declare const agentToken: (settings: RelaySettings) => Promise<string | undefined>;
+/**
+ * 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
+ * the same authenticated routing implementation. With `relay.mode: "session"`
+ * (or RELAY_PI_MODE=session) Messages come into this session instead.
  */
 export default function relayPiExtension(pi: ExtensionAPI): void;

package/dist/native.js

@@ -1,12 +1,88 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { runPiChannel } from "./index.js";
+import { SessionChannel } from "./session.js";
+import { transcribeCpp } from "./voice.js";
 let controller;
 let running;
+const home = (path) => path === "~" || path.startsWith("~/") ? join(homedir(), path.slice(1)) : path;
+const agentDir = () => home(process.env.PI_CODING_AGENT_DIR?.trim() || join(homedir(), ".pi", "agent"));
+/** The `relay` settings, or none when the file or key is missing or unreadable. */
+export const relaySettings = async (dir = agentDir()) => {
+    try {
+        const settings = JSON.parse(await readFile(join(dir, "settings.json"), "utf8"));
+        return settings.relay && typeof settings.relay === "object" ? settings.relay : {};
+    }
+    catch {
+        return {};
+    }
+};
+/** RELAY_AGENT_TOKEN, else what `agentTokenCommand` prints; never logged. */
+export const agentToken = async (settings) => {
+    const env = process.env.RELAY_AGENT_TOKEN?.trim();
+    if (env)
+        return env;
+    const [command, ...args] = settings.agentTokenCommand ?? [];
+    if (!command)
+        return undefined;
+    return new Promise((done) => {
+        execFile(command, args, { encoding: "utf8", timeout: 10_000 }, (error, stdout) => done(error ? undefined : stdout.trim() || undefined));
+    });
+};
+const sessionMode = (settings) => (process.env.RELAY_PI_MODE?.trim() || settings.mode) === "session";
+/** Relay inside this session, started once per process on its first session_start. */
+const attachSession = (pi) => {
+    let channel;
+    let stop;
+    pi.on("session_start", async (_event, ctx) => {
+        // Only the RPC session an app drives: a terminal Pi on the same account
+        // would hold a second connection on the same token, a print or JSON run
+        // ends with its prompt, and a pi-subagents helper is not the session the
+        // person talks to.
+        if (stop || ctx.mode !== "rpc" || process.env.PI_SUBAGENT_CHILD === "1")
+            return;
+        const settings = await relaySettings();
+        if (!sessionMode(settings))
+            return;
+        const token = await agentToken(settings);
+        if (!token) {
+            console.error("Relay: no Agent Token (RELAY_AGENT_TOKEN or relay.agentTokenCommand); the session channel is off.");
+            return;
+        }
+        const baseURL = process.env.RELAY_BASE_URL?.trim() || settings.baseURL;
+        const senders = process.env.RELAY_SENDERS?.split(",").map((sender) => sender.trim()).filter(Boolean) ?? settings.senders;
+        const voice = settings.transcribeCpp;
+        stop = new AbortController();
+        channel = new SessionChannel(pi, {
+            agentToken: token,
+            isIdle: () => ctx.isIdle(),
+            ...(baseURL ? { baseURL } : {}),
+            ...(senders ? { senders } : {}),
+            ...(voice ? { transcribe: transcribeCpp({ module: home(voice.module), model: home(voice.model) }) } : {}),
+        });
+        void channel.run(stop.signal).catch((error) => {
+            console.error(`Relay: the session channel stopped: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    });
+    pi.on("agent_end", async (event) => { channel?.ended(event.messages); });
+    pi.on("agent_settled", async () => { await channel?.settled(); });
+    pi.on("session_shutdown", async () => {
+        stop?.abort();
+        channel?.stop();
+        stop = undefined;
+        channel = undefined;
+    });
+};
 /**
- * Pi-native entry point. It deliberately exposes only lifecycle-safe commands;
- * Relay ingress remains owned by runPiChannel so the CLI and extension share
- * the same authenticated routing implementation.
+ * 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
+ * the same authenticated routing implementation. With `relay.mode: "session"`
+ * (or RELAY_PI_MODE=session) Messages come into this session instead.
  */
 export default function relayPiExtension(pi) {
+    attachSession(pi);
     pi.registerCommand("relay-connect", {
         description: "Start the Relay channel using the configured Agent Token",
         handler: async (_args, ctx) => {

package/dist/session.d.ts

@@ -0,0 +1,71 @@
+import Relay, { type MediaPartResponse, type MessageWebhookData, type RelayWebhookEvent } from "@relaymessenger/sdk";
+import type { Transcribe } from "./voice.js";
+export interface TextBlock {
+    readonly type: "text";
+    readonly text: string;
+}
+export interface ImageBlock {
+    readonly type: "image";
+    readonly data: string;
+    readonly mimeType: string;
+}
+/** One Message as the session reads it: the words, then each photo as an image. */
+export type SessionContent = (TextBlock | ImageBlock)[];
+/** What the session is given in place of the Pi it would otherwise start. */
+export interface SessionPi {
+    sendUserMessage(content: SessionContent, options?: {
+        deliverAs: "followUp";
+    }): void;
+}
+export interface SessionChannelOptions {
+    readonly agentToken: string;
+    readonly baseURL?: string;
+    readonly relay?: Relay;
+    /** Handles whose Messages reach the session; any sender when empty or absent. */
+    readonly senders?: readonly string[];
+    /** Words for a voice note. Without it a voice note is named, not heard. */
+    readonly transcribe?: Transcribe;
+    /** Whether the session is between runs, so a Message can start one now. */
+    readonly isIdle: () => boolean;
+}
+/** The line sent when a run ends with no words, so every Message is answered. */
+export declare const NO_ANSWER = "Sorry, something went wrong on my side.";
+export interface SessionMedia {
+    /** The bytes behind a media part. */
+    download(part: MediaPartResponse): Promise<Buffer>;
+    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
+ * 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>;
+/** The words of the last assistant message in a finished run, or undefined. */
+export declare const lastAnswer: (messages: readonly unknown[]) => string | undefined;
+/** 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;
+};
+/**
+ * Relay inside the Pi session that loads it, the way pi-telegram holds a chat
+ * in its own Pi process: each Message is one user message to that session,
+ * and the session's answer goes back to the chat it came from once the run
+ * has settled (after retries and queued follow-ups). Messages wait their turn,
+ * so each gets its own answer, and one that ends with no words still gets
+ * `NO_ANSWER`.
+ */
+export declare class SessionChannel {
+    #private;
+    constructor(pi: SessionPi, options: SessionChannelOptions);
+    run(signal?: AbortSignal): Promise<void>;
+    /** Takes one event: an accepted Message waits its turn in the session. */
+    receive(event: RelayWebhookEvent): Promise<void>;
+    /** 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. */
+    settled(): Promise<void>;
+    /** Starts the next waiting Message when nothing of Relay's is running and the session is idle. */
+    next(): void;
+    stop(): void;
+}

package/dist/session.js

@@ -0,0 +1,176 @@
+import Relay, {} from "@relaymessenger/sdk";
+import { piPrompt, repliedContext, sendAnswer, wordsOf } from "./index.js";
+/** The line sent when a run ends with no words, so every Message is answered. */
+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
+ * its transcript, and any other file named. Null for a Message with nothing.
+ */
+export const sessionContent = async (data, media, replyLine = "") => {
+    const lines = [];
+    const images = [];
+    for (const part of data.parts) {
+        if (part.type !== "media")
+            continue;
+        const mime = String(part.mime_type ?? "").toLowerCase();
+        const name = part.filename || "file";
+        if (IMAGE_TYPES.has(mime)) {
+            images.push({ type: "image", data: (await media.download(part)).toString("base64"), mimeType: mime });
+            lines.push(`[photo: ${name}]`);
+        }
+        else if (mime.startsWith("audio/")) {
+            const words = media.transcribe
+                ? await media.transcribe(await media.download(part), name).catch(() => undefined)
+                : undefined;
+            lines.push(words ? `[voice note, transcribed]: ${words}` : `[voice note: ${name}, could not be transcribed]`);
+        }
+        else {
+            lines.push(`[file: ${name} (${mime || "unknown type"}), not opened]`);
+        }
+    }
+    const words = [wordsOf(data), lines.join("\n"), replyLine].filter(Boolean).join("\n\n");
+    if (!words)
+        return null;
+    return [{ type: "text", text: piPrompt(words) }, ...images];
+};
+/** The words of the last assistant message in a finished run, or undefined. */
+export const lastAnswer = (messages) => {
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        if (message?.role !== "assistant")
+            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 || undefined;
+    }
+    return undefined;
+};
+/** One-to-one Messages from a Handle, and only the listed Handles when there is a list. */
+export const accepts = (event, senders = []) => {
+    if (event.event_type !== "message.received" || event.data.direction !== "inbound")
+        return false;
+    const data = event.data;
+    if (!data.sender_handle || data.chat.is_group)
+        return false;
+    if (!senders.length)
+        return true;
+    const handle = (value) => value.replace(/^@/u, "").toLowerCase();
+    return senders.some((sender) => handle(sender) === handle(data.sender_handle.handle));
+};
+/**
+ * Relay inside the Pi session that loads it, the way pi-telegram holds a chat
+ * in its own Pi process: each Message is one user message to that session,
+ * and the session's answer goes back to the chat it came from once the run
+ * has settled (after retries and queued follow-ups). Messages wait their turn,
+ * so each gets its own answer, and one that ends with no words still gets
+ * `NO_ANSWER`.
+ */
+export class SessionChannel {
+    #pi;
+    #options;
+    #relay;
+    #queue = [];
+    #seen = new Set();
+    #inflight = new Map();
+    #pending;
+    #ended = [];
+    constructor(pi, options) {
+        if (!options.agentToken.trim())
+            throw new Error("Relay Agent Token is required");
+        this.#pi = pi;
+        this.#options = options;
+        this.#relay = options.relay ?? new Relay({ apiKey: options.agentToken, ...(options.baseURL ? { baseURL: options.baseURL } : {}) });
+    }
+    run(signal) {
+        return this.#relay.websocket.run({
+            ...(signal ? { signal } : {}),
+            onEvent: (event) => this.receive(event),
+            // The session is the record; there is no inbox here to rebuild.
+            onFullSync: async () => { console.error("Relay: FULL sync acknowledged; Messages sent while this session was away were not delivered."); },
+            onError: (error) => { console.error(`Relay: ${error instanceof Error ? error.message : String(error)}`); },
+        });
+    }
+    /** Takes one event: an accepted Message waits its turn in the session. */
+    async receive(event) {
+        const inflight = this.#inflight.get(event.event_id);
+        if (inflight)
+            return inflight;
+        if (this.#seen.has(event.event_id) || !accepts(event, this.#options.senders))
+            return;
+        const handoff = (async () => {
+            const content = await sessionContent(event.data, {
+                download: (part) => this.#download(part),
+                ...(this.#options.transcribe ? { transcribe: this.#options.transcribe } : {}),
+            }, await repliedContext(this.#relay, event.data));
+            this.#seen.add(event.event_id);
+            if (!content)
+                return;
+            this.#queue.push({ data: event.data, key: `pi-${event.event_id}`, content });
+            this.next();
+        })();
+        this.#inflight.set(event.event_id, handoff);
+        try {
+            await handoff;
+        }
+        finally {
+            this.#inflight.delete(event.event_id);
+        }
+    }
+    /** Pi's `agent_end`: the messages of the run that just ended. */
+    ended(messages) {
+        if (this.#pending)
+            this.#ended = messages;
+    }
+    /** Pi's `agent_settled`: the pending Message is answered and cleared, then the next one starts. */
+    async settled() {
+        const turn = this.#pending;
+        this.#pending = undefined;
+        const answer = lastAnswer(this.#ended) ?? NO_ANSWER;
+        this.#ended = [];
+        try {
+            if (turn)
+                await sendAnswer(this.#relay, turn.data, turn.key, answer);
+        }
+        catch (error) {
+            console.error(`Relay: the answer was not sent: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            this.next();
+        }
+    }
+    /** Starts the next waiting Message when nothing of Relay's is running and the session is idle. */
+    next() {
+        if (this.#pending || !this.#queue.length || !this.#options.isIdle())
+            return;
+        const turn = this.#queue.shift();
+        this.#pending = turn;
+        this.#ended = [];
+        try {
+            this.#pi.sendUserMessage(turn.content);
+        }
+        catch {
+            // A run began between the check and the send; this one follows it.
+            this.#pi.sendUserMessage(turn.content, { deliverAs: "followUp" });
+        }
+    }
+    stop() {
+        this.#queue.length = 0;
+        this.#pending = undefined;
+        this.#ended = [];
+    }
+    async #download(part) {
+        let response = part.url ? await fetch(part.url).catch(() => undefined) : undefined;
+        // A media url lasts 60 minutes; GET /v1/attachments/{id} makes a fresh one.
+        if (!response?.ok && part.id) {
+            const fresh = (await this.#relay.attachments.retrieve(part.id)).download_url;
+            if (fresh)
+                response = await fetch(fresh);
+        }
+        if (!response?.ok)
+            throw new Error(`Relay attachment download failed (${response?.status ?? "no url"})`);
+        return Buffer.from(await response.arrayBuffer());
+    }
+}

package/dist/voice.d.ts

@@ -0,0 +1,19 @@
+/** Words for one voice note, or undefined when it could not be heard. */
+export type Transcribe = (audio: Buffer, filename: string) => Promise<string | undefined>;
+export interface TranscribeCppOptions {
+    /** The installed transcribe-cpp package: its directory or its `dist/index.js`. */
+    readonly module: string;
+    /** A speech model transcribe-cpp loads, such as a Parakeet GGUF. */
+    readonly model: string;
+    /** Decoder for the note; ffmpeg from PATH by default. */
+    readonly ffmpeg?: string;
+    readonly threads?: number;
+}
+/** 16-bit little-endian mono PCM as the floats a speech model reads. */
+export declare const pcmFloats: (raw: Buffer) => Float32Array;
+/**
+ * A voice note heard on this machine: ffmpeg decodes it to 16 kHz mono and
+ * transcribe-cpp runs the model, loaded on the first note and kept. Relay
+ * delivers voice notes as `media` parts and does not transcribe them.
+ */
+export declare const transcribeCpp: (options: TranscribeCppOptions) => Transcribe;

package/dist/voice.js

@@ -0,0 +1,41 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+const run = (command, args) => new Promise((done, fail) => {
+    execFile(command, [...args], { encoding: "buffer", maxBuffer: 256 << 20 }, (error, stdout) => error ? fail(error) : done(stdout));
+});
+/** 16-bit little-endian mono PCM as the floats a speech model reads. */
+export const pcmFloats = (raw) => {
+    const pcm = new Float32Array(raw.length >> 1);
+    for (let index = 0; index < pcm.length; index++)
+        pcm[index] = raw.readInt16LE(index * 2) / 32768;
+    return pcm;
+};
+/**
+ * A voice note heard on this machine: ffmpeg decodes it to 16 kHz mono and
+ * transcribe-cpp runs the model, loaded on the first note and kept. Relay
+ * delivers voice notes as `media` parts and does not transcribe them.
+ */
+export const transcribeCpp = (options) => {
+    let session;
+    const load = () => session ??= (async () => {
+        const entry = options.module.endsWith(".js") ? options.module : join(options.module, "dist/index.js");
+        const { TranscribeModel } = await import(pathToFileURL(entry).href);
+        const loaded = (await TranscribeModel.load(options.model)).createSession({ nThreads: options.threads ?? 1 });
+        return async (pcm) => String((await loaded.run(pcm, { timestamps: "none" })).text ?? "").trim();
+    })();
+    return async (audio, filename) => {
+        const dir = await mkdtemp(join(tmpdir(), "relay-voice-"));
+        try {
+            const file = join(dir, filename.replace(/[^\w.-]/gu, "_") || "voice.m4a");
+            await writeFile(file, audio);
+            const raw = await run(options.ffmpeg ?? "ffmpeg", ["-v", "error", "-i", file, "-f", "s16le", "-ac", "1", "-ar", "16000", "pipe:1"]);
+            return (await (await load())(pcmFloats(raw))) || undefined;
+        }
+        finally {
+            await rm(dir, { recursive: true, force: true });
+        }
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relaymessenger/pi",
-  "version": "0.1.9",
+  "version": "0.1.10-staging.0",
   "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.3"
+    "@relaymessenger/sdk": "0.5.3-staging.0"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.86.0",