@relaymessenger/pi 0.1.14 → 0.1.15-staging.0

package/README.md

@@ -64,6 +64,24 @@ its last words to the chat of the last Message, kept in
 `relay-last-chat.json` in the agent directory so it survives a restart; a turn
 typed in the session stays there.
 
+## Owner approval in session mode
+
+With [`@gotgenes/pi-permission-system`](https://www.npmjs.com/package/@gotgenes/pi-permission-system)
+loaded, a gated tool call in a run a Relay Message started is asked of the
+agent's owners with the same card the Relay CLI sends in channel mode:
+**Allow once**, **Allow for session** or **Deny**, in each owner's own chat
+with the agent. Only an owner's tap counts. No answer in 10 minutes denies
+it. Allow for session covers the patterns the permission system suggests
+for the call, until the session ends. A run typed at the app, a path or
+external-directory ask (the chain will not let a link allow those), or an
+agent no owner can be reached for is asked in the app as before.
+
+Turn it on by naming the `relay` link in the permission system's config:
+
+```json
+{ "authorizerChain": ["relay"] }
+```
+
 ## With pi-channels
 
 [pi-channels](https://github.com/espennilsen/pi/tree/main/packages/pi-channels)

package/dist/approvals.d.ts

@@ -0,0 +1,194 @@
+import { type MessagePart, type Relay, type RelayWebhookEvent } from "@relaymessenger/sdk";
+import type { PiApprovals } from "./index.js";
+/**
+ * Relays a coding agent's own permission prompts to the people who own the
+ * Relay agent, as a card in each owner's chat with the agent.
+ *
+ * The harness decides what needs a person's yes; this process only carries
+ * the question and the answer. That is how every integration of a messenger
+ * with a coding agent does it: Claude Code's channels relay the harness's
+ * permission prompt and let the harness apply the verdict (Claude Code
+ * channels reference, "Relay permission prompts"; saved at
+ * _sources/approvals-inkbox-20260926/claude-code-channels-reference.md), and
+ * Inkbox's Claude Code and Codex plugins forward each `can_use_tool` and
+ * `requestApproval` to the human (inkbox-claude-code-plugin-sessions.py.txt
+ * `_can_use_tool`; inkbox-codex-plugin-codex_client.py.txt
+ * `_handle_server_request`).
+ *
+ * Only an owner answers. The official Telegram plugin sends the prompt only to
+ * allowlisted DMs (claude-plugins-official-telegram-server.ts.txt); the
+ * iMessage plugin sends it to the owner's own chat because "that authority is
+ * the owner's alone" (claude-plugins-official-imessage-server.ts.txt). Relay
+ * names the owners itself: `GET /v1/me` returns `owner_people` for the calling
+ * Agent Token (Relay-Server server/src/me.ts, `app.get("/me")`).
+ *
+ * The card is a `rich_card` whose reply suggestions are the harness's
+ * choices; a tap comes back as the owner's own message, a `suggestion_response`
+ * carrying the choice's id and replying to the card. A Pi select with more
+ * choices than a card holds is a single-choice `selection` instead, answered
+ * by a `selection_response`. A tap from anyone else is not registered, and
+ * the card stays open for an owner to answer.
+ */
+/**
+ * How a person may answer, in the words every harness maps to. `choice` is an
+ * option of a question that is neither an allow nor a deny (a Pi extension's
+ * `select`).
+ */
+export type ApprovalDecision = "allow_once" | "allow_session" | "deny" | "choice";
+/** One choice the harness offers, with the label the card shows. */
+export interface ApprovalChoice {
+    /** The harness's own id for the choice, handed back to it unchanged. */
+    id: string;
+    label: string;
+    decision: ApprovalDecision;
+}
+/** One permission prompt from a harness. */
+export interface ApprovalRequest {
+    /** Who is asking, e.g. "Claude Code". */
+    harness: string;
+    /** The tool it wants to use, e.g. "Bash". */
+    tool: string;
+    /** The card's title, one sentence; `<harness> asks to use <tool>.` when absent. */
+    title?: string;
+    /** The command or file the harness wants to use. */
+    summary: string;
+    /**
+     * A plain line under the command: Bash's own description of it, which
+     * Claude Code's terminal prompt shows under the command too.
+     */
+    note?: string;
+    /** The full input as a person reads it. */
+    detail: string;
+    /**
+     * Whether `detail` holds anything `summary` and `note` do not: an input
+     * field beyond the summarized value and the note. The card then shows
+     * `detail` in place of them.
+     */
+    extra: boolean;
+    /** The harness's own choices, allow first. */
+    choices: readonly ApprovalChoice[];
+    /**
+     * How long to wait for an answer. The harness's own timeout when it sets
+     * one (Codex's `autoResolutionMs`); otherwise `APPROVAL_TIMEOUT_MS`.
+     */
+    timeoutMs?: number;
+    /** Stops the wait, for example when the turn is cancelled. */
+    signal?: AbortSignal;
+}
+/** How a prompt ended. With no `choice`, the harness is told no. */
+export interface ApprovalOutcome {
+    choice?: ApprovalChoice;
+    /** The owner who answered. */
+    by?: string;
+    reason: "answered" | "timeout" | "no_owner" | "unsent" | "aborted";
+}
+/**
+ * Inkbox waits 600 seconds for a person's answer and then treats the request
+ * as not approved (`permission_timeout_s: float = 600.0`,
+ * inkbox-claude-code-plugin-config.py.txt:108 and
+ * inkbox-codex-plugin-config.py.txt:132).
+ */
+export declare const APPROVAL_TIMEOUT_MS = 600000;
+/** The one line the terminal shows when nobody can be asked. */
+export declare const noOwnerLine: (request: Pick<ApprovalRequest, "harness" | "tool">) => string;
+/** What the reply to the card says once a prompt has ended. */
+export declare const outcomeLine: (outcome: ApprovalOutcome) => string;
+/**
+ * The contract's limits (Relay-Server contracts/developer/openapi.yaml), the
+ * card's from the SDK; a `SelectionPart` subtitle is 512 characters and an
+ * id-bearing `SelectionOption` has a 24-character label and a 200-character id.
+ */
+export declare const CARD_LIMITS: {
+    readonly title: 200;
+    readonly description: 2000;
+    readonly suggestions: 4;
+    readonly label: 25;
+    readonly replyId: 256;
+    readonly selectionTitle: 60;
+    readonly selectionSubtitle: 512;
+    readonly selectionOptions: 25;
+    readonly selectionLabel: 24;
+    readonly selectionId: 200;
+};
+/** The card's title: the harness's sentence, or `<harness> asks to use <tool>.` */
+export declare const cardTitle: (request: ApprovalRequest) => string;
+/**
+ * The card's description, plain text as the app draws it (Relay-iOS
+ * RelayRichCardRow.swift, `Text(description)`): the command and its note, or,
+ * when the input holds more than them, the whole input as a person reads it.
+ * Cut at the contract's 2,000 characters with a closing "…".
+ */
+export declare const cardDescription: (request: ApprovalRequest) => string | undefined;
+/**
+ * The prefix of every reply id on an approval card. Relay stores a reply
+ * suggestion's `id` as sent and returns it in the person's
+ * `suggestion_response` (or `selection_response`), so a tap on any approval
+ * card, even one a bridge process no longer holds (sent before a restart),
+ * is known by its id alone and never becomes a person's turn.
+ */
+export declare const APPROVAL_REPLY_PREFIX = "relay-approval:";
+/** Whether a reply id is one an approval card gave out. */
+export declare const isApprovalReplyId: (id: string) => boolean;
+/**
+ * The message part that asks: a `rich_card` with one reply suggestion per
+ * choice, or, past the card's 4 suggestions, a single-choice `selection` of up
+ * to 25 options.
+ */
+export declare const approvalPart: (request: ApprovalRequest) => MessagePart;
+/** The choice a reply id names, as `approvalPart` gave it out. */
+export declare const choiceFor: (request: ApprovalRequest, id: string) => ApprovalChoice | undefined;
+/**
+ * A tap on a card, as `message.received` carries it: the card message it
+ * replies to, and the id of the reply the person chose. A card reply is plain
+ * text then `suggestion_response`; a picker answer, plain text then
+ * `selection_response` (Relay-Server contracts/developer/openapi.yaml,
+ * `SuggestionResponsePart` and `SelectionResponsePart`).
+ */
+export declare const readAnswer: (event: RelayWebhookEvent) => {
+    messageId: string;
+    id: string;
+} | undefined;
+/** The Relay calls this needs: who owns the agent, and the chat with each owner. */
+export type ApprovalClient = Pick<Relay, "chats" | "me">;
+export interface OwnerApprovalsOptions {
+    client: ApprovalClient;
+    say(line: string): void;
+}
+/**
+ * One per bridge process. `ask` sends the card and waits; `take` reads every
+ * event first and keeps the answers to its own cards, so they never start a turn.
+ */
+export declare class OwnerApprovals {
+    #private;
+    constructor(options: OwnerApprovalsOptions);
+    ask(request: ApprovalRequest): Promise<ApprovalOutcome>;
+    /**
+     * Whether this event is an answer to one of this process's approval cards.
+     * Such an event is handled here and must not start a turn.
+     */
+    take(event: RelayWebhookEvent): Promise<boolean>;
+}
+/** What a harness is told when a prompt ends without an allow (Inkbox's words, sessions.py.txt:1249). */
+export declare const denialMessage: (outcome: ApprovalOutcome) => string;
+/** One line of a tool input, for the card's summary. */
+export declare const inputSummary: (input: Record<string, unknown>) => string;
+/** Whether an input says anything in a field other than `shown`, the ones the card draws. */
+export declare const beyond: (input: Record<string, unknown>, shown: readonly string[]) => boolean;
+/**
+ * A tool input as its card shows it: the summarized value, Bash's own
+ * description as the note, the readable detail, and whether the input holds
+ * more. An input with no field to summarize is summarized whole.
+ */
+export declare const inputCard: (input: Record<string, unknown>) => Pick<ApprovalRequest, "summary" | "note" | "detail" | "extra">;
+/**
+ * The whole tool input as a person reads it, for the card's description: an Edit is its
+ * file and a diff (a MultiEdit, a diff per edit), a Write its file and the
+ * content, anything else one `name: value` line per field.
+ */
+export declare const inputDetail: (input: unknown) => string;
+/**
+ * Pi's dialogs, answered by the owners. A confirm is Yes or No, an allow and
+ * a deny; a select offers the extension's own options, each as it wrote it.
+ * The card's first line is the extension's own title.
+ */
+export declare const piApprovals: (approvals: Pick<OwnerApprovals, "ask" | "take">) => PiApprovals;

package/dist/approvals.js

@@ -0,0 +1,424 @@
+import { createHash } from "node:crypto";
+import { RICH_CARD_DESCRIPTION_MAX_LENGTH, RICH_CARD_MAX_SUGGESTIONS, RICH_CARD_TITLE_MAX_LENGTH, SELECTION_MAX_OPTIONS, SELECTION_TITLE_MAX_LENGTH, SUGGESTION_ID_MAX_LENGTH, SUGGESTION_LABEL_MAX_LENGTH, selectionReply, suggestionReply, } from "@relaymessenger/sdk";
+/**
+ * Inkbox waits 600 seconds for a person's answer and then treats the request
+ * as not approved (`permission_timeout_s: float = 600.0`,
+ * inkbox-claude-code-plugin-config.py.txt:108 and
+ * inkbox-codex-plugin-config.py.txt:132).
+ */
+export const APPROVAL_TIMEOUT_MS = 600_000;
+/** The one line the terminal shows when nobody can be asked. */
+export const noOwnerLine = (request) => `${request.harness} was not allowed to use ${request.tool}: nobody who owns this agent has a Relay app account to approve it. Link a phone from Settings in the Relay console, or with \`relay phone link\`.`;
+/** What the reply to the card says once a prompt has ended. */
+export const outcomeLine = (outcome) => {
+    const who = outcome.by ? `@${outcome.by}` : "Someone";
+    switch (outcome.choice?.decision) {
+        case "allow_once": return `${who} allowed this once.`;
+        case "allow_session": return `${who} allowed this for this session.`;
+        case "deny": return `${who} denied this.`;
+        case "choice": return `${who} chose ${outcome.choice.label}.`;
+        default: break;
+    }
+    if (outcome.reason === "timeout")
+        return "Timed out, not approved.";
+    return "Not approved.";
+};
+/**
+ * The contract's limits (Relay-Server contracts/developer/openapi.yaml), the
+ * card's from the SDK; a `SelectionPart` subtitle is 512 characters and an
+ * id-bearing `SelectionOption` has a 24-character label and a 200-character id.
+ */
+export const CARD_LIMITS = {
+    title: RICH_CARD_TITLE_MAX_LENGTH,
+    description: RICH_CARD_DESCRIPTION_MAX_LENGTH,
+    suggestions: RICH_CARD_MAX_SUGGESTIONS,
+    label: SUGGESTION_LABEL_MAX_LENGTH,
+    replyId: SUGGESTION_ID_MAX_LENGTH,
+    selectionTitle: SELECTION_TITLE_MAX_LENGTH,
+    selectionSubtitle: 512,
+    selectionOptions: SELECTION_MAX_OPTIONS,
+    selectionLabel: 24,
+    selectionId: 200,
+};
+const clip = (text, max) => text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+const oneLine = (text) => text.replace(/\s+/gu, " ").trim();
+/** The card's title: the harness's sentence, or `<harness> asks to use <tool>.` */
+export const cardTitle = (request) => oneLine(request.title ?? "") || `${request.harness} asks to use ${request.tool}.`;
+/**
+ * The card's description, plain text as the app draws it (Relay-iOS
+ * RelayRichCardRow.swift, `Text(description)`): the command and its note, or,
+ * when the input holds more than them, the whole input as a person reads it.
+ * Cut at the contract's 2,000 characters with a closing "…".
+ */
+export const cardDescription = (request) => {
+    const text = request.extra
+        ? request.detail.trim()
+        : [request.summary.trim(), request.note?.trim() ?? ""].filter(Boolean).join("\n\n");
+    return text ? clip(text, CARD_LIMITS.description) : undefined;
+};
+/**
+ * The prefix of every reply id on an approval card. Relay stores a reply
+ * suggestion's `id` as sent and returns it in the person's
+ * `suggestion_response` (or `selection_response`), so a tap on any approval
+ * card, even one a bridge process no longer holds (sent before a restart),
+ * is known by its id alone and never becomes a person's turn.
+ */
+export const APPROVAL_REPLY_PREFIX = "relay-approval:";
+/** Whether a reply id is one an approval card gave out. */
+export const isApprovalReplyId = (id) => id.startsWith(APPROVAL_REPLY_PREFIX);
+/**
+ * The id a choice's reply carries: the prefix and the harness's own id, or,
+ * when that is longer than the contract allows, the prefix and the SHA-256 of
+ * the harness's id, which no two different ids share.
+ */
+const replyId = (choice, max) => {
+    const plain = `${APPROVAL_REPLY_PREFIX}${choice.id}`;
+    return plain.length <= max ? plain : `${APPROVAL_REPLY_PREFIX}sha256:${createHash("sha256").update(choice.id).digest("hex")}`;
+};
+/** Whether the choices fit on one card's suggestions. */
+const onCard = (request) => request.choices.length <= CARD_LIMITS.suggestions;
+/**
+ * The message part that asks: a `rich_card` with one reply suggestion per
+ * choice, or, past the card's 4 suggestions, a single-choice `selection` of up
+ * to 25 options.
+ */
+export const approvalPart = (request) => {
+    if (request.choices.length > CARD_LIMITS.selectionOptions) {
+        throw new Error(`${request.harness} offered ${request.choices.length} choices; a Relay approval list holds at most ${CARD_LIMITS.selectionOptions}, so it was not sent.`);
+    }
+    const ids = request.choices.map((choice) => replyId(choice, onCard(request) ? CARD_LIMITS.replyId : CARD_LIMITS.selectionId));
+    if (new Set(ids).size !== ids.length) {
+        throw new Error(`${request.harness} offered two choices with the same id; the owner's answer could not say which, so it was not sent.`);
+    }
+    const description = cardDescription(request);
+    if (onCard(request)) {
+        return {
+            type: "rich_card",
+            title: clip(cardTitle(request), CARD_LIMITS.title),
+            ...(description !== undefined ? { description } : {}),
+            suggestions: request.choices.map((choice, index) => ({
+                type: "reply",
+                label: clip(oneLine(choice.label) || choice.id, CARD_LIMITS.label),
+                id: ids[index],
+            })),
+        };
+    }
+    return {
+        type: "selection",
+        title: clip(cardTitle(request), CARD_LIMITS.selectionTitle),
+        ...(description !== undefined ? { subtitle: clip(description, CARD_LIMITS.selectionSubtitle) } : {}),
+        multiple: false,
+        options: request.choices.map((choice, index) => ({
+            id: ids[index],
+            label: clip(oneLine(choice.label) || choice.id, CARD_LIMITS.selectionLabel),
+        })),
+    };
+};
+/** The choice a reply id names, as `approvalPart` gave it out. */
+export const choiceFor = (request, id) => {
+    const max = onCard(request) ? CARD_LIMITS.replyId : CARD_LIMITS.selectionId;
+    return request.choices.find((choice) => replyId(choice, max) === id);
+};
+/**
+ * A tap on a card, as `message.received` carries it: the card message it
+ * replies to, and the id of the reply the person chose. A card reply is plain
+ * text then `suggestion_response`; a picker answer, plain text then
+ * `selection_response` (Relay-Server contracts/developer/openapi.yaml,
+ * `SuggestionResponsePart` and `SelectionResponsePart`).
+ */
+export const readAnswer = (event) => {
+    if (event.event_type !== "message.received")
+        return undefined;
+    const parts = event.data.parts ?? [];
+    const card = suggestionReply(parts, event.data.reply_to);
+    if (card)
+        return { messageId: card.reply_to.message_id, id: card.id };
+    const picked = selectionReply(parts, event.data.reply_to);
+    const id = picked?.selected_ids?.[0] ?? picked?.selected_values[0];
+    return picked && id !== undefined ? { messageId: picked.reply_to.message_id, id } : undefined;
+};
+/**
+ * One per bridge process. `ask` sends the card and waits; `take` reads every
+ * event first and keeps the answers to its own cards, so they never start a turn.
+ */
+export class OwnerApprovals {
+    #client;
+    #say;
+    /** Open prompts, by the message id of each owner's card. */
+    #pending = new Map();
+    /** Cards already settled, so a late tap on one is dropped quietly. */
+    #settled = new Set();
+    /** Cards being sent: Relay has not yet named their message ids. */
+    #sending = 0;
+    /**
+     * Answers to cards this process does not hold yet, kept while a card is
+     * being sent: the owner can tap a card before the response that names it
+     * arrives. Forgotten once nothing is being sent.
+     */
+    #early = new Map();
+    constructor(options) {
+        this.#client = options.client;
+        this.#say = options.say;
+    }
+    async ask(request) {
+        if (request.signal?.aborted)
+            return { reason: "aborted" };
+        // A prompt no card can carry fails loudly to the harness, before anything is sent.
+        let part;
+        try {
+            part = approvalPart(request);
+        }
+        catch (error) {
+            this.#say(error instanceof Error ? error.message : String(error));
+            throw error;
+        }
+        // Read fresh each time, so an owner who links a phone while the bridge
+        // runs is asked from the next prompt on.
+        let me;
+        try {
+            me = await this.#client.me.retrieve();
+        }
+        catch (error) {
+            this.#say(`${request.harness} was not allowed to use ${request.tool}: Relay did not say who owns this agent (${error instanceof Error ? error.message : String(error)}).`);
+            return { reason: "unsent" };
+        }
+        const owners = me.owner_people ?? [];
+        if (!owners.length) {
+            this.#say(noOwnerLine(request));
+            return { reason: "no_owner" };
+        }
+        let settle;
+        const done = new Promise((resolve) => { settle = resolve; });
+        const pending = { request, owners: new Set(owners.map((owner) => owner.handle)), cards: [], settle };
+        for (const owner of owners) {
+            this.#sending += 1;
+            try {
+                // The chat between the agent and this owner: Relay reuses the direct
+                // chat of the pair (Relay-Server messaging.ts, `createOrReuseChat`).
+                const sent = await this.#client.chats.create({
+                    from: me.handle,
+                    to: [owner.handle],
+                    message: { parts: [part] },
+                });
+                const card = { chatId: sent.chat.id, messageId: sent.chat.message.id, owner: owner.handle };
+                pending.cards.push(card);
+                this.#pending.set(card.messageId, pending);
+                const early = this.#early.get(card.messageId);
+                if (early) {
+                    this.#early.delete(card.messageId);
+                    await this.take(early);
+                }
+            }
+            catch (error) {
+                this.#say(`The approval card did not reach @${owner.handle}: ${error instanceof Error ? error.message : String(error)}.`);
+            }
+            finally {
+                this.#sending -= 1;
+                if (this.#sending === 0)
+                    this.#early.clear();
+            }
+        }
+        if (!pending.cards.length) {
+            this.#say(`${request.harness} was not allowed to use ${request.tool}: no owner could be asked.`);
+            return { reason: "unsent" };
+        }
+        this.#say(`Asked ${pending.cards.map((card) => `@${card.owner}`).join(", ")} to approve ${request.tool}.`);
+        const timeoutMs = request.timeoutMs ?? APPROVAL_TIMEOUT_MS;
+        const timer = setTimeout(() => settle({ reason: "timeout" }), timeoutMs);
+        const abort = () => settle({ reason: "aborted" });
+        request.signal?.addEventListener("abort", abort, { once: true });
+        const outcome = await done;
+        clearTimeout(timer);
+        request.signal?.removeEventListener("abort", abort);
+        for (const card of pending.cards) {
+            this.#pending.delete(card.messageId);
+            this.#settled.add(card.messageId);
+        }
+        // The card cannot change once sent, so what happened is a reply to it in
+        // every owner's chat.
+        await Promise.all(pending.cards.map(async (card) => {
+            try {
+                await this.#client.chats.messages.send(card.chatId, {
+                    message: { parts: [{ type: "text", value: outcomeLine(outcome) }], reply_to: { message_id: card.messageId, part_index: 0 } },
+                });
+            }
+            catch { /* The harness already has its answer; an unanswered card is the lesser harm. */ }
+        }));
+        this.#say(`${request.tool}: ${outcomeLine(outcome)}`);
+        return outcome;
+    }
+    /**
+     * Whether this event is an answer to one of this process's approval cards.
+     * Such an event is handled here and must not start a turn.
+     */
+    async take(event) {
+        const answer = readAnswer(event);
+        if (!answer || event.event_type !== "message.received")
+            return false;
+        if (this.#settled.has(answer.messageId))
+            return true;
+        const pending = this.#pending.get(answer.messageId);
+        // An answer to an approval card this process does not hold (sent before a
+        // restart, or by another bridge of the same agent) is dropped quietly: the
+        // harness that asked is gone, and the tap is not a message to answer.
+        if (!pending) {
+            if (!isApprovalReplyId(answer.id))
+                return false;
+            // A card being sent right now may be this one.
+            if (this.#sending > 0)
+                this.#early.set(answer.messageId, event);
+            return true;
+        }
+        const sender = event.data.sender_handle;
+        // A sender with no Handle, or anyone but an owner, is not registered, and
+        // the card stays open.
+        if (!sender || sender.kind !== "user" || !pending.owners.has(sender.handle))
+            return true;
+        const choice = choiceFor(pending.request, answer.id);
+        if (!choice)
+            return true;
+        pending.settle({ reason: "answered", choice, by: sender.handle });
+        return true;
+    }
+}
+/** What a harness is told when a prompt ends without an allow (Inkbox's words, sessions.py.txt:1249). */
+export const denialMessage = (outcome) => {
+    switch (outcome.reason) {
+        case "timeout": return "The agent's owner did not answer in time, so treating that as not approved.";
+        case "no_owner": return "Nobody who owns this agent can be asked, so treating that as not approved.";
+        case "unsent": return "The agent's owner could not be asked, so treating that as not approved.";
+        case "aborted": return "The request was cancelled, so treating that as not approved.";
+        default: return "The agent's owner denied this, so treating that as not approved.";
+    }
+};
+/** The input field the card's summary shows, in order of preference. */
+const summaryKey = (input) => ["command", "cmd", "file_path", "path", "notebook_path", "url", "pattern", "query"].find((key) => {
+    const value = input[key];
+    return (typeof value === "string" && value.trim() !== "") || (Array.isArray(value) && value.every((part) => typeof part === "string"));
+});
+/** One line of a tool input, for the card's summary. */
+export const inputSummary = (input) => {
+    const key = summaryKey(input);
+    const value = key === undefined ? undefined : input[key];
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value))
+        return value.join(" ");
+    return JSON.stringify(input);
+};
+/** Whether a value says anything: not absent, false, blank, or empty. */
+const says = (value) => {
+    if (value === undefined || value === null || value === false)
+        return false;
+    if (typeof value === "string")
+        return value.trim() !== "";
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (typeof value === "object")
+        return Object.keys(value).length > 0;
+    return true;
+};
+/** Whether an input says anything in a field other than `shown`, the ones the card draws. */
+export const beyond = (input, shown) => Object.entries(input).some(([key, value]) => !shown.includes(key) && says(value));
+/**
+ * A tool input as its card shows it: the summarized value, Bash's own
+ * description as the note, the readable detail, and whether the input holds
+ * more. An input with no field to summarize is summarized whole.
+ */
+export const inputCard = (input) => {
+    const key = summaryKey(input);
+    const description = key === "command" && typeof input.description === "string" && input.description.trim() ? input.description : undefined;
+    return {
+        summary: inputSummary(input),
+        ...(description !== undefined ? { note: description } : {}),
+        detail: inputDetail(input),
+        extra: key !== undefined && beyond(input, description !== undefined ? [key, "description"] : [key]),
+    };
+};
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const isScalar = (value) => value === null || typeof value !== "object";
+/** A value on one line, for an item of a list. */
+const inline = (value) => {
+    if (typeof value === "string")
+        return value;
+    if (isRecord(value))
+        return Object.entries(value).map(([key, item]) => `${key}: ${inline(item)}`).join(", ");
+    if (Array.isArray(value))
+        return value.map(inline).join(", ");
+    return String(value);
+};
+/** One `name: value` line per field; a multi-line value kept as it is, a nested one indented under its name. */
+const fields = (input, indent = "") => Object.entries(input).filter(([, value]) => value !== undefined).flatMap(([key, value]) => {
+    if (isRecord(value))
+        return [`${indent}${key}:`, ...fields(value, `${indent}  `)];
+    if (Array.isArray(value) && !value.every(isScalar))
+        return [`${indent}${key}:`, ...value.map((item) => `${indent}  - ${inline(item)}`)];
+    return [`${indent}${key}: ${inline(value)}`];
+});
+/** A replacement as a diff: `-` before each old line, `+` before each new one. */
+const diff = (before, after) => [
+    ...before.split("\n").map((line) => `- ${line}`),
+    ...after.split("\n").map((line) => `+ ${line}`),
+];
+const isReplacement = (value) => isRecord(value) && typeof value.old_string === "string" && typeof value.new_string === "string";
+/**
+ * The whole tool input as a person reads it, for the card's description: an Edit is its
+ * file and a diff (a MultiEdit, a diff per edit), a Write its file and the
+ * content, anything else one `name: value` line per field.
+ */
+export const inputDetail = (input) => {
+    if (typeof input === "string")
+        return input;
+    if (!isRecord(input)) {
+        try {
+            return JSON.stringify(input) ?? String(input);
+        }
+        catch {
+            return String(input);
+        }
+    }
+    const { file_path: path, ...rest } = input;
+    if (typeof path === "string" && isReplacement(input)) {
+        const { old_string: _old, new_string: _new, ...other } = rest;
+        return [path, ...diff(input.old_string, input.new_string), ...fields(other)].join("\n");
+    }
+    if (typeof path === "string" && Array.isArray(input.edits) && input.edits.every(isReplacement)) {
+        const { edits, ...other } = rest;
+        return [
+            path,
+            ...edits.flatMap(({ old_string: before, new_string: after, ...more }) => [...diff(before, after), ...fields(more)]),
+            ...fields(other),
+        ].join("\n");
+    }
+    if (typeof path === "string" && typeof input.content === "string") {
+        const { content, ...other } = rest;
+        return [path, content, ...fields(other)].join("\n");
+    }
+    return fields(input).join("\n");
+};
+/**
+ * Pi's dialogs, answered by the owners. A confirm is Yes or No, an allow and
+ * a deny; a select offers the extension's own options, each as it wrote it.
+ * The card's first line is the extension's own title.
+ */
+export const piApprovals = (approvals) => ({
+    dialog: async (dialog) => {
+        const choices = dialog.method === "confirm"
+            ? [{ id: "Yes", label: "Yes", decision: "allow_once" }, { id: "No", label: "No", decision: "deny" }]
+            : dialog.options.map((option) => ({ id: option, label: option, decision: "choice" }));
+        const outcome = await approvals.ask({
+            harness: "Pi",
+            tool: oneLine(dialog.title).slice(0, 80) || "a question",
+            title: dialog.title.trim() || "Pi asks a question.",
+            summary: dialog.message ?? "",
+            detail: [dialog.title, dialog.message].filter(Boolean).join("\n\n"),
+            // The title is the card's first line and the message its summary.
+            extra: false,
+            choices,
+            ...(dialog.timeoutMs !== undefined ? { timeoutMs: dialog.timeoutMs } : {}),
+            ...(dialog.signal ? { signal: dialog.signal } : {}),
+        });
+        return outcome.choice?.id;
+    },
+    take: (event) => approvals.take(event),
+});

package/dist/index.d.ts

@@ -170,4 +170,6 @@ export declare const sendToChat: (relay: Relay, chatId: string, key: string, ans
  */
 export declare const typing: (relay: Relay, chatId: string, on: boolean) => Promise<void>;
 export declare const runPiChannel: (options: PiChannelOptions, signal?: AbortSignal) => Promise<void>;
-export {};
+/** The owner approval cards, shared with the Relay CLI. */
+export * from "./approvals.js";
+export * from "./session-approvals.js";

package/dist/index.js

@@ -545,3 +545,6 @@ export const typing = (relay, chatId, on) => Promise.resolve()
     console.error(`Relay: typing indicator failed: ${error instanceof Error ? error.message : String(error)}`);
 });
 export const runPiChannel = (options, signal) => new PiChannel(options).run(signal);
+/** The owner approval cards, shared with the Relay CLI. */
+export * from "./approvals.js";
+export * from "./session-approvals.js";

package/dist/native.js

@@ -7,6 +7,8 @@ import { RELAY_CHAT_ID_ENV, RELAY_HINT_SECTION, relayHint, runPiChannel } from "
 import { relayTools } from "./tools.js";
 import { registerRelayAdapter, relayChannelAdapter, RELAY_ADAPTER } from "./pi-channels.js";
 import { SessionChannel } from "./session.js";
+import { OwnerApprovals } from "./approvals.js";
+import { registerRelayAuthorizer, relayAuthorizer } from "./session-approvals.js";
 import { transcribeCpp } from "./voice.js";
 let controller;
 let running;
@@ -58,6 +60,32 @@ const sessionMode = (settings) => (process.env.RELAY_PI_MODE?.trim() || settings
 const attachSession = (pi) => {
     let channel;
     let stop;
+    // The owner's approval card, as a pi-permission-system chain link: registered
+    // once both the channel and that extension's session are up, in either order.
+    let link;
+    let permissionsSession;
+    let unregister;
+    const register = () => {
+        if (unregister || !link || !permissionsSession)
+            return;
+        try {
+            unregister = registerRelayAuthorizer(permissionsSession, (ask) => link.authorize(ask));
+        }
+        catch (error) {
+            console.error(`Relay: the approval link was not registered: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    pi.events.on("permissions:ready", (data) => {
+        const sessionId = data?.sessionId;
+        if (typeof sessionId !== "string" || !sessionId)
+            return;
+        if (sessionId !== permissionsSession) {
+            unregister?.();
+            unregister = undefined;
+            permissionsSession = sessionId;
+        }
+        register();
+    });
     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
@@ -78,9 +106,11 @@ const attachSession = (pi) => {
         const voice = settings.transcribeCpp;
         stop = new AbortController();
         const relay = new Relay({ apiKey: token, ...(baseURL ? { baseURL } : {}) });
+        const approvals = new OwnerApprovals({ client: relay, say: (line) => { console.error(`Relay: ${line}`); } });
         channel = new SessionChannel(pi, {
             agentToken: token,
             relay,
+            approvals,
             isIdle: () => ctx.isIdle(),
             lastChatFile: join(agentDir(), "relay-last-chat.json"),
             ...(baseURL ? { baseURL } : {}),
@@ -88,6 +118,8 @@ const attachSession = (pi) => {
             ...(voice ? { transcribe: transcribeCpp({ module: home(voice.module), model: home(voice.model) }) } : {}),
         });
         const current = channel;
+        link = relayAuthorizer({ approvals, fromRelay: () => current.fromRelay });
+        register();
         registerRelayTools(pi, relay, () => current.chatId, () => current.messageId, (chat) => current.latestIn(chat));
         void channel.run(stop.signal).catch((error) => {
             console.error(`Relay: the session channel stopped: ${error instanceof Error ? error.message : String(error)}`);
@@ -101,8 +133,12 @@ const attachSession = (pi) => {
     pi.on("session_shutdown", async () => {
         stop?.abort();
         channel?.stop();
+        unregister?.();
         stop = undefined;
         channel = undefined;
+        link = undefined;
+        unregister = undefined;
+        permissionsSession = undefined;
     });
 };
 /**

package/dist/session-approvals.d.ts

@@ -0,0 +1,73 @@
+import { type ApprovalChoice, type OwnerApprovals } from "./approvals.js";
+/**
+ * The owner's approval card for the Pi session Relay runs in, through
+ * `@gotgenes/pi-permission-system`.
+ *
+ * In RPC mode that extension asks with `ctx.ui.select`, which Pi sends to
+ * the app driving the session as an `extension_ui_request` (pi-permission-
+ * system src/authority/permission-dialog.ts, `requestPermissionDecisionFromUi`;
+ * Pi docs/rpc.md, "Extension UI Protocol"). Another extension in the same
+ * process cannot answer that dialog. What it offers instead is a live-
+ * authority chain link: a sibling extension registers one with
+ * `registerAuthorizer`, and the link answers `allow`, `deny` or `defer` before
+ * the dialog opens (docs/cross-extension-api.md, "Ready Event";
+ * docs/configuration.md, "Authorizer chain"). The operator turns it on by
+ * naming it in `authorizerChain`.
+ *
+ * This link sends the same card the Relay CLI sends in channel mode when the
+ * run asking was started by a Relay Message, and defers otherwise, so a run
+ * typed at the app is asked in the app as before.
+ */
+/** The name to list in pi-permission-system's `authorizerChain`. */
+export declare const RELAY_AUTHORIZER = "relay";
+/** The parts of pi-permission-system's `PromptPermissionDetails` the card reads (dist/public.d.ts). */
+export interface PermissionAsk {
+    readonly payload: {
+        readonly request: {
+            readonly surface: string;
+            readonly toolName: string | null;
+            readonly value: string;
+        };
+    };
+    readonly sessionApproval?: {
+        readonly grants: readonly {
+            readonly surface: string;
+            readonly pattern: string;
+        }[];
+    };
+    readonly accessIntent?: {
+        readonly surface: string;
+    };
+}
+/** pi-permission-system's `AuthorizerVerdict`. */
+export type PermissionVerdict = {
+    kind: "allow";
+} | {
+    kind: "deny";
+    reason?: string;
+} | {
+    kind: "defer";
+};
+export declare const RELAY_APPROVAL_CHOICES: readonly ApprovalChoice[];
+export interface RelayAuthorizerOptions {
+    readonly approvals: Pick<OwnerApprovals, "ask">;
+    /** Whether the run asking now was started by a Relay Message. */
+    readonly fromRelay: () => boolean;
+    /** How long the owner has to answer; `APPROVAL_TIMEOUT_MS` (10 minutes) when absent. */
+    readonly timeoutMs?: number;
+}
+/**
+ * The link's `authorize`. An answered card allows or denies; a card nobody
+ * answers in time denies; a card that could not be sent defers to the app.
+ */
+export declare const relayAuthorizer: (options: RelayAuthorizerOptions) => {
+    authorize(ask: PermissionAsk): Promise<PermissionVerdict>;
+    /** Forgets this session's grants, at `session_shutdown`. */
+    reset(): void;
+};
+/**
+ * Registers the link with the session's pi-permission-system, read from the
+ * process-global map its docs name, so Relay needs no dependency on it. Does
+ * nothing when it is not loaded. Returns the disposer.
+ */
+export declare const registerRelayAuthorizer: (sessionId: string, authorize: (ask: PermissionAsk) => Promise<PermissionVerdict>) => (() => void) | undefined;

package/dist/session-approvals.js

@@ -0,0 +1,97 @@
+import { denialMessage } from "./approvals.js";
+/**
+ * The owner's approval card for the Pi session Relay runs in, through
+ * `@gotgenes/pi-permission-system`.
+ *
+ * In RPC mode that extension asks with `ctx.ui.select`, which Pi sends to
+ * the app driving the session as an `extension_ui_request` (pi-permission-
+ * system src/authority/permission-dialog.ts, `requestPermissionDecisionFromUi`;
+ * Pi docs/rpc.md, "Extension UI Protocol"). Another extension in the same
+ * process cannot answer that dialog. What it offers instead is a live-
+ * authority chain link: a sibling extension registers one with
+ * `registerAuthorizer`, and the link answers `allow`, `deny` or `defer` before
+ * the dialog opens (docs/cross-extension-api.md, "Ready Event";
+ * docs/configuration.md, "Authorizer chain"). The operator turns it on by
+ * naming it in `authorizerChain`.
+ *
+ * This link sends the same card the Relay CLI sends in channel mode when the
+ * run asking was started by a Relay Message, and defers otherwise, so a run
+ * typed at the app is asked in the app as before.
+ */
+/** The name to list in pi-permission-system's `authorizerChain`. */
+export const RELAY_AUTHORIZER = "relay";
+export const RELAY_APPROVAL_CHOICES = [
+    { id: "allow_once", label: "Allow once", decision: "allow_once" },
+    { id: "allow_session", label: "Allow for session", decision: "allow_session" },
+    { id: "deny", label: "Deny", decision: "deny" },
+];
+/**
+ * The surfaces whose `allow` the chain caps to `defer` ("bounded-delegation
+ * checkpoint", docs/configuration.md): `path` and `external_directory` with
+ * their directional members. An owner asked about one could not approve it.
+ */
+const capped = (surface) => /^(path|external_directory)(_|$)/u.test(surface);
+/**
+ * The grant an "Allow for session" stands for: the session patterns
+ * pi-permission-system suggests for the ask, else the exact surface and
+ * value. A later ask is allowed without a card only when it carries the same
+ * key, so the link never allows more than the owner saw.
+ */
+const grantKey = (ask) => {
+    const grants = ask.sessionApproval?.grants;
+    if (grants?.length)
+        return JSON.stringify(grants.map((grant) => [grant.surface, grant.pattern]).sort());
+    return JSON.stringify([ask.payload.request.surface, ask.payload.request.value]);
+};
+/**
+ * The link's `authorize`. An answered card allows or denies; a card nobody
+ * answers in time denies; a card that could not be sent defers to the app.
+ */
+export const relayAuthorizer = (options) => {
+    const granted = new Set();
+    return {
+        reset: () => { granted.clear(); },
+        authorize: async (ask) => {
+            if (!options.fromRelay() || capped(ask.accessIntent?.surface ?? ask.payload.request.surface))
+                return { kind: "defer" };
+            const key = grantKey(ask);
+            if (granted.has(key))
+                return { kind: "allow" };
+            const { surface, toolName, value } = ask.payload.request;
+            const tool = toolName ?? surface;
+            const patterns = ask.sessionApproval?.grants.map((grant) => grant.pattern).join(", ");
+            const outcome = await options.approvals.ask({
+                harness: "Pi",
+                tool,
+                title: `Pi asks to use ${tool}.`,
+                summary: value,
+                ...(patterns ? { note: `Allow for session covers ${patterns}` } : {}),
+                detail: value,
+                extra: false,
+                choices: RELAY_APPROVAL_CHOICES,
+                ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+            });
+            switch (outcome.choice?.decision) {
+                case "allow_session":
+                    granted.add(key);
+                    return { kind: "allow" };
+                case "allow_once": return { kind: "allow" };
+                case "deny": return { kind: "deny", reason: denialMessage(outcome) };
+                default: break;
+            }
+            // Nobody answered in time: not approved. No owner could be asked: the app asks.
+            return outcome.reason === "timeout" ? { kind: "deny", reason: denialMessage(outcome) } : { kind: "defer" };
+        },
+    };
+};
+/** pi-permission-system's per-session services (src/service.ts, `SESSION_SERVICES_KEY`; docs/cross-extension-api.md, "How It Works"). */
+const SERVICES = Symbol.for("@gotgenes/pi-permission-system:session-services");
+/**
+ * Registers the link with the session's pi-permission-system, read from the
+ * process-global map its docs name, so Relay needs no dependency on it. Does
+ * nothing when it is not loaded. Returns the disposer.
+ */
+export const registerRelayAuthorizer = (sessionId, authorize) => {
+    const services = globalThis[SERVICES];
+    return services?.get(sessionId)?.registerAuthorizer(RELAY_AUTHORIZER, authorize);
+};

package/dist/session.d.ts

@@ -1,4 +1,5 @@
 import Relay, { type MediaPartResponse, type MessageWebhookData, type RelayWebhookEvent } from "@relaymessenger/sdk";
+import type { OwnerApprovals } from "./approvals.js";
 import type { Transcribe } from "./voice.js";
 export interface TextBlock {
     readonly type: "text";
@@ -44,6 +45,8 @@ export interface SessionChannelOptions {
      * run no Message started (a helper's result) sends its words there.
      */
     readonly lastChatFile?: string;
+    /** The owner approval cards: a tap on one answers it and is not a Message for the session. */
+    readonly approvals?: Pick<OwnerApprovals, "take">;
 }
 /**
  * The line sent when a run fails before it has words, so the person is not
@@ -131,6 +134,8 @@ export declare class SessionChannel {
      * turn started the newest waiting background run, else the last chat.
      */
     get chatId(): string | undefined;
+    /** Whether a Relay Message started or steered the run going now. */
+    get fromRelay(): boolean;
     /** The Message the tools react and thread to, chosen as `chatId` is. */
     get messageId(): string | undefined;
     /** The newest Message of a chat the session has heard from. */

package/dist/session.js

@@ -229,7 +229,13 @@ export class SessionChannel {
         const inflight = this.#inflight.get(event.event_id);
         if (inflight)
             return inflight;
-        if (this.#seen.has(event.event_id) || !accepts(event, this.#options.senders))
+        if (this.#seen.has(event.event_id))
+            return;
+        if (await this.#options.approvals?.take(event)) {
+            this.#seen.add(event.event_id);
+            return;
+        }
+        if (!accepts(event, this.#options.senders))
             return;
         const handoff = (async () => {
             const content = await sessionContent(event.data, {
@@ -259,6 +265,10 @@ export class SessionChannel {
     get chatId() {
         return (this.#pending?.data ?? this.#background.at(-1)?.data ?? this.#last)?.chat.id;
     }
+    /** Whether a Relay Message started or steered the run going now. */
+    get fromRelay() {
+        return this.#pending !== undefined;
+    }
     /** The Message the tools react and thread to, chosen as `chatId` is. */
     get messageId() {
         return (this.#pending?.data ?? this.#background.at(-1)?.data ?? this.#last)?.id;

package/package.json

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