@spinabot/brigade 1.1.0 → 1.2.0

package/dist/agents/channels/approval-callback-codec.js

@@ -0,0 +1,173 @@
+/**
+ * Approval-callback codec — the wire format for inline-button approvals.
+ *
+ * Some channels (Telegram, Slack block-kit, Discord components) render an
+ * approval prompt as native buttons instead of a "reply yes/no" text card. When
+ * the operator taps a button the channel delivers a `callback_query`-style event
+ * carrying an opaque payload string the BUTTON declared at send time. This codec
+ * is the central, channel-neutral encode/decode for that payload: it packs the
+ * pending-approval id + the chosen decision into one short string, and unpacks
+ * it back on the way in.
+ *
+ * THE 64-BYTE BUDGET. Telegram's `callback_data` is capped at **64 bytes** (a
+ * hard Bot API limit — a longer value is rejected outright). That is the
+ * tightest channel constraint, so this codec treats 64 bytes as the universal
+ * ceiling: {@link encodeApprovalCallback} returns `undefined` when the payload
+ * would exceed it (the caller then omits / falls back to the text prompt rather
+ * than ship an oversized button). The budget is measured in UTF-8 BYTES, not
+ * `string.length`, so a multi-byte id can't sneak past the limit.
+ *
+ * WIRE FORMAT (channel-neutral, no brand tokens, printable ASCII only):
+ *
+ *     <tag>:<base64url(approvalId)>:<decisionCode>
+ *
+ *   - `tag` is the constant {@link APPROVAL_CALLBACK_TAG} = `"bv1"` (a versioned
+ *     marker — `b`rigade callback `v1` — that lets the decoder reject foreign
+ *     button payloads fast and lets a future format bump cleanly).
+ *   - the approval id is base64url-encoded so it can carry the `:`/`-`/`_`
+ *     characters real ids use without colliding with the field delimiter.
+ *   - `decisionCode` is a single char: `o` = allow-once, `a` = allow-always,
+ *     `d` = deny. Single chars (rather than the full `allow-always` words) keep
+ *     the payload comfortably inside 64 bytes.
+ *
+ * No NUL / control bytes ever appear: base64url is `[A-Za-z0-9_-]`, the tag is
+ * lowercase ASCII, the delimiter is a printable colon, and the decision code is
+ * one of three ASCII letters.
+ *
+ * The decision vocabulary is the channel-approval subset of the bridge's
+ * `ApprovalDecisionKind` — exactly the three an operator can choose from a
+ * button (`allow-once` / `allow-always` / `deny`); the bridge's other kinds
+ * (`allow-pattern`, `allow-session`) are not button-reachable.
+ */
+/**
+ * Versioned, brand-neutral marker prefixing every approval callback payload.
+ * `b`rigade callback `v1`. Bumping the version (`bv2`, …) lets a new wire
+ * format coexist with old in-flight buttons.
+ */
+export const APPROVAL_CALLBACK_TAG = "bv1";
+/**
+ * Telegram's `callback_data` hard limit — the tightest channel constraint, used
+ * here as the universal ceiling. Measured in UTF-8 bytes.
+ */
+export const APPROVAL_CALLBACK_MAX_BYTES = 64;
+const DELIMITER = ":";
+/** Map a full decision kind to its single-char wire code. */
+function decisionToCode(decision) {
+    switch (decision) {
+        case "allow-once":
+            return "o";
+        case "allow-always":
+            return "a";
+        case "deny":
+            return "d";
+    }
+}
+/** Map a single-char wire code back to a decision kind (or null if unknown). */
+function codeToDecision(code) {
+    switch (code) {
+        case "o":
+            return "allow-once";
+        case "a":
+            return "allow-always";
+        case "d":
+            return "deny";
+        default:
+            return null;
+    }
+}
+/** Base64url-encode (no padding) — `[A-Za-z0-9_-]`, never a NUL/control byte. */
+function toBase64Url(value) {
+    return Buffer.from(value, "utf8").toString("base64url");
+}
+/** Base64url-decode back to UTF-8. Returns "" on malformed input. */
+function fromBase64Url(value) {
+    try {
+        return Buffer.from(value, "base64url").toString("utf8");
+    }
+    catch {
+        return "";
+    }
+}
+/** True iff `value` fits the universal callback-data byte budget. */
+export function fitsApprovalCallback(value) {
+    return Buffer.byteLength(value, "utf8") <= APPROVAL_CALLBACK_MAX_BYTES;
+}
+/**
+ * Build the standard three approval buttons (Allow once / Allow always / Deny)
+ * for an approval id, each carrying its codec-encoded payload. A channel's
+ * `sendApprovalPrompt` calls this to get a ready-made, byte-safe button spec
+ * instead of re-deriving the encoding by hand, then maps each `{ label, data }`
+ * onto its own native button type.
+ *
+ * `allowAlways: false` drops the "Allow always" button (for approvals where
+ * persisting an allowlist entry doesn't apply). Any button whose payload would
+ * exceed the 64-byte budget is OMITTED (never shipped oversized) — in practice
+ * that only happens for pathologically long approval ids, and the caller should
+ * fall back to the text prompt when fewer than two buttons come back.
+ */
+export function buildApprovalCallbackButtons(args) {
+    const specs = [
+        { label: "Allow once", decision: "allow-once" },
+        ...(args.allowAlways === false
+            ? []
+            : [{ label: "Allow always", decision: "allow-always" }]),
+        { label: "Deny", decision: "deny" },
+    ];
+    const buttons = [];
+    for (const spec of specs) {
+        const data = encodeApprovalCallback({ approvalId: args.approvalId, decision: spec.decision });
+        if (!data)
+            continue; // oversized payload → omit this button
+        buttons.push({ label: spec.label, decision: spec.decision, data });
+    }
+    return buttons;
+}
+/**
+ * Encode an approval id + decision into a callback payload string.
+ *
+ * Returns `undefined` when the result would exceed {@link APPROVAL_CALLBACK_MAX_BYTES}
+ * (64 UTF-8 bytes) OR when the approval id is empty — in either case the caller
+ * must NOT render that button (fall back to the text prompt). A non-undefined
+ * return is always a wire-safe, printable-ASCII string under the limit.
+ */
+export function encodeApprovalCallback(args) {
+    const id = args.approvalId.trim();
+    if (!id)
+        return undefined;
+    const payload = `${APPROVAL_CALLBACK_TAG}${DELIMITER}${toBase64Url(id)}${DELIMITER}${decisionToCode(args.decision)}`;
+    if (!fitsApprovalCallback(payload))
+        return undefined;
+    return payload;
+}
+/**
+ * Decode a callback payload string back into `{ approvalId, decision }`.
+ *
+ * Returns `null` for anything that isn't a well-formed approval callback — a
+ * foreign button payload, a truncated/garbled string, an unknown decision code,
+ * or an oversized value. A `null` return means "not an approval callback; let
+ * the caller fall through" exactly like the text decoder's `null`.
+ */
+export function decodeApprovalCallback(data) {
+    if (typeof data !== "string" || data.length === 0)
+        return null;
+    // Reject oversized payloads up front — anything over the budget could not
+    // have been minted by our encoder, so it isn't ours to decode.
+    if (!fitsApprovalCallback(data))
+        return null;
+    const parts = data.split(DELIMITER);
+    if (parts.length !== 3)
+        return null;
+    const [tag, idB64, code] = parts;
+    if (tag !== APPROVAL_CALLBACK_TAG)
+        return null;
+    if (!idB64)
+        return null;
+    const approvalId = fromBase64Url(idB64).trim();
+    if (!approvalId)
+        return null;
+    const decision = codeToDecision(code ?? "");
+    if (decision === null)
+        return null;
+    return { approvalId, decision };
+}
+//# sourceMappingURL=approval-callback-codec.js.map

package/dist/agents/channels/approval-callback-codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-callback-codec.js","sourceRoot":"","sources":["../../../src/agents/channels/approval-callback-codec.ts"],"names":[],"mappings":"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"}

package/dist/agents/channels/approval-router.d.ts

@@ -40,7 +40,10 @@
  * threading a registry through 8 layers of args is the same fight as
  * the bridge itself (see `approval-bridge.ts` for the same rationale).
  */
+import type { BrigadeConfig } from "../../config/io.js";
 import type { ApprovalDecision, ApprovalDecisionKind, ApprovalRequest } from "../approval-bridge.js";
+import type { ChannelApprovalCapability, ChannelApprovalKind } from "./types.adapters.js";
+import type { RuntimeEnv } from "./types.core.js";
 /** A pending approval the channel router is waiting on a yes/no for. */
 export interface ChannelApprovalRoute {
     channelId: string;
@@ -58,13 +61,38 @@ export interface ChannelApprovalRoute {
  * `startChannels` boot from each adapter's outbound surface.
  */
 export interface ChannelApprovalDispatcher {
-    /** Send the approval prompt to the conversation. */
+    /**
+     * Send the approval prompt to the conversation. The return is intentionally
+     * widened to accept adapters whose `sendText` now yields `{ messageId? }`
+     * (the additive outbound-id surface) — the router ignores any returned id;
+     * it only needs the send to resolve.
+     */
     sendText: (conversationId: string, text: string, opts?: {
         threadId?: string;
         accountId?: string;
-    }) => Promise<void>;
+    }) => Promise<{
+        messageId?: string;
+    } | void>;
     /** Human-readable label for log lines + the prompt header (e.g. "WhatsApp"). */
     prettyName: string;
+    /**
+     * Optional native-button approval capability. When the registering channel's
+     * adapter exposes `approvalCapability.sendApprovalPrompt`, the router renders
+     * the approval question via THAT (inline buttons carrying codec-encoded
+     * callback payloads) instead of the default text card. Absent → text path.
+     * Additive: dispatchers registered with only `{ sendText, prettyName }`
+     * (WhatsApp, the manager's default) keep using the text prompt unchanged.
+     */
+    approvalCapability?: ChannelApprovalCapability;
+    /**
+     * Supplies the `runtime` + `cfg` a native `sendApprovalPrompt` call needs.
+     * Only consulted when `approvalCapability.sendApprovalPrompt` is present, so
+     * text-only dispatchers never need it.
+     */
+    getApprovalContext?: () => {
+        runtime: RuntimeEnv;
+        cfg: BrigadeConfig;
+    };
 }
 /**
  * Register an adapter's outbound surface so the bridge can route prompts
@@ -114,38 +142,67 @@ export declare function dispatchChannelApproval(args: {
     route: ChannelApprovalRoute;
     resolveOnBridge: (decision: ApprovalDecision) => void;
 }): Promise<boolean>;
+export declare function tryConsumeChannelApprovalReply(args: {
+    channelId: string;
+    conversationId: string;
+    text: string;
+    threadId?: string;
+    accountId?: string;
+    agentId?: string;
+}): {
+    matched: true;
+    decision: ApprovalDecisionKind;
+    approvalId: string;
+} | {
+    matched: false;
+};
 /**
- * Try to consume `text` as a yes/no reply to a pending approval for this
- * peer. Returns:
- *   - `true`  → text WAS a yes/no answer + bridge has been resolved; the
- *               caller (channel inbound handler) should `return` and NOT
- *               dispatch a turn for this message.
- *   - `false` → no pending approval for this peer, OR text wasn't a
- *               yes/no shape. Caller proceeds with normal dispatch.
+ * Try to consume an inline-button press (Telegram `callback_query` etc.) as the
+ * answer to a pending approval for this peer. Mirrors `tryConsumeChannelApprovalReply`
+ * but decodes the button's codec payload instead of free text, and runs an
+ * optional central authorization gate before settling.
  *
- * Notes for the channel inbound:
- *   - Must be called AFTER the access-policy check (we only intercept
- *     trusted peers — strangers can't accidentally answer an approval).
- *   - Must be called BEFORE the abort-trigger check (the abort word "stop"
- *     overlaps the "no" vocabulary; pending-approval intent wins).
- *   - The channel adapter's `sendText` for the acknowledgement is the
- *     caller's responsibility — the router only does the bridge plumbing.
- *     This keeps the router test-friendly (no I/O side effects on the
- *     intercept path) and lets per-channel formatting differ.
+ * Returns:
+ *   - `{ matched: true, decision, approvalId }` — the payload decoded to a
+ *     pending approval for an AUTHORIZED presser and the bridge was resolved.
+ *     The caller should acknowledge the press and NOT dispatch a turn.
+ *   - `{ matched: false, refused: true, reason }` — the payload matched a
+ *     pending approval but the presser was refused by `authorizeApprover`. The
+ *     pending entry is left intact (a non-operator press must not consume the
+ *     operator's approval). The caller should ack with the refusal reason.
+ *   - `{ matched: false }` — not an approval callback for this peer (foreign /
+ *     malformed payload, or no pending entry). Caller proceeds normally.
+ *
+ * MUST be called AFTER the channel access gate (only trusted peers reach here)
+ * and BEFORE the text-reply path. `authorizeApprover` is the channel's own
+ * predicate (from its `ChannelApprovalCapability`); when provided it is invoked
+ * centrally so a non-operator's button press is refused here, not in the
+ * adapter.
  */
-export declare function tryConsumeChannelApprovalReply(args: {
+export declare function tryConsumeChannelApprovalCallback(args: {
     channelId: string;
     conversationId: string;
-    text: string;
+    callbackData: string;
     threadId?: string;
     accountId?: string;
     agentId?: string;
+    senderId?: string;
+    authorizeApprover?: (params: {
+        accountId?: string;
+        senderId?: string;
+        approvalKind: ChannelApprovalKind;
+    }) => {
+        authorized: boolean;
+        reason?: string;
+    };
 }): {
     matched: true;
     decision: ApprovalDecisionKind;
     approvalId: string;
 } | {
     matched: false;
+    refused?: true;
+    reason?: string;
 };
 /**
  * Cancel a pending approval by request id (e.g. on session abort).

package/dist/agents/channels/approval-router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"approval-router.d.ts","sourceRoot":"","sources":["../../../src/agents/channels/approval-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAIrG,wEAAwE;AACxE,MAAM,WAAW,oBAAoB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kIAAkI;IAClI,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACzC,oDAAoD;IACpD,QAAQ,EAAE,CACT,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,KAC5C,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC;CACnB;AAkED;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAChD,SAAS,EAAE,MAAM,EACjB,qBAAqB,EAAE,MAAM,GAAG,SAAS,GAAG,yBAAyB,EACrE,eAAe,CAAC,EAAE,yBAAyB,GACzC,IAAI,CAYN;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAoB3F;AAED,6DAA6D;AAC7D,wBAAgB,8BAA8B,IAAI,MAAM,EAAE,CAEzD;AAED,sEAAsE;AACtE,wBAAgB,2BAA2B,IAAI,KAAK,CAAC;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACd,CAAC,CAYD;AA2FD;;;;;;;;;;;;GAYG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IACnD,OAAO,EAAE,eAAe,CAAC;IACzB,KAAK,EAAE,oBAAoB,CAAC;IAC5B,eAAe,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,IAAI,CAAC;CACtD,GAAG,OAAO,CAAC,OAAO,CAAC,CAwGnB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,oBAAoB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CA+C7F;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAOlE;AAED,4DAA4D;AAC5D,wBAAgB,kCAAkC,IAAI,IAAI,CAKzD"}
+{"version":3,"file":"approval-router.d.ts","sourceRoot":"","sources":["../../../src/agents/channels/approval-router.ts"],"names":[],"mappings":"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"}

package/dist/agents/channels/approval-router.js

@@ -42,6 +42,7 @@
  */
 import { createSubsystemLogger } from "../../logging/subsystem-logger.js";
 import { resolveGlobalSingleton } from "../../shared/global-singleton.js";
+import { decodeApprovalCallback, } from "./approval-callback-codec.js";
 const log = createSubsystemLogger("brigade/channel-approvals");
 /** All three approval-router maps are pinned via global-singleton so a hot-reload / dual-build run shares one routing state. */
 const APPROVAL_ROUTER_DISPATCHERS_KEY = Symbol.for("brigade.approvalRouter.dispatchers");
@@ -181,6 +182,16 @@ function buildPromptText(args) {
         "Times out in 5 minutes.",
     ].join("\n");
 }
+/**
+ * Infer the approval KIND for a request so a native prompt can label itself
+ * ("approve this shell command" vs "approve this plugin action"). Brigade's
+ * exec-gate raises shell-command approvals (the overwhelming common case); a
+ * `plugin:`-prefixed id marks a plugin-capability approval. The distinction is
+ * cosmetic for the channel render — the bridge resolution is identical.
+ */
+function approvalKindForRequest(request) {
+    return request.id.startsWith("plugin:") ? "plugin" : "exec";
+}
 /**
  * Decode an operator's text reply into a decision kind. Liberal in what
  * it accepts so the operator can type the obvious shapes without thinking:
@@ -299,7 +310,33 @@ export async function dispatchChannelApproval(args) {
             sendOpts.threadId = route.threadId;
         if (route.accountId)
             sendOpts.accountId = route.accountId;
-        await dispatcher.sendText(route.conversationId, prompt, Object.keys(sendOpts).length > 0 ? sendOpts : undefined);
+        // Native inline-button render when the channel opted in; otherwise the
+        // default text prompt. The button payloads carry codec-encoded
+        // `{ approvalId, decision }` and the press comes back as an
+        // `InboundMessage.callbackQuery` → `tryConsumeChannelApprovalCallback`.
+        const native = dispatcher.approvalCapability?.sendApprovalPrompt;
+        if (native) {
+            const promptCtx = dispatcher.getApprovalContext?.();
+            const promptParams = {
+                // `runtime`/`cfg` come from the registering channel; fall back to
+                // empty shapes so a capability that ignores them still works.
+                runtime: promptCtx?.runtime ?? {},
+                cfg: promptCtx?.cfg ?? {},
+                conversationId: route.conversationId,
+                ...(route.accountId !== undefined ? { accountId: route.accountId } : {}),
+                ...(route.threadId !== undefined ? { threadId: route.threadId } : {}),
+                approvalId: request.id,
+                approvalKind: approvalKindForRequest(request),
+                command: request.command,
+                ...(request.toolName !== undefined ? { toolName: request.toolName } : {}),
+                ...(request.cwd !== undefined ? { cwd: request.cwd } : {}),
+                timeoutMs: request.timeoutMs,
+            };
+            await native(promptParams);
+        }
+        else {
+            await dispatcher.sendText(route.conversationId, prompt, Object.keys(sendOpts).length > 0 ? sendOpts : undefined);
+        }
     }
     catch (err) {
         // Release the reserved slot so the WS-fallback path can run cleanly.
@@ -345,6 +382,7 @@ export async function dispatchChannelApproval(args) {
         conversationId: route.conversationId,
         approvalId: request.id,
         via: dispatcher.prettyName,
+        render: dispatcher.approvalCapability?.sendApprovalPrompt ? "buttons" : "text",
     });
     return true;
 }
@@ -367,13 +405,14 @@ export async function dispatchChannelApproval(args) {
  *     This keeps the router test-friendly (no I/O side effects on the
  *     intercept path) and lets per-channel formatting differ.
  */
-export function tryConsumeChannelApprovalReply(args) {
-    // First, try the exact-route key (covers thread + account + agent
-    // disambiguation). If nothing matches AND the caller didn't pin all
-    // dimensions, scan for any pending entry whose route's pinned dimensions
-    // agree with the caller — that handles the WhatsApp-style flat-DM case
-    // where the inbound carries no threadId but the approval was raised on
-    // the same channel+conversation.
+/**
+ * Locate the pending approval that a reply / callback from this peer should
+ * settle, returning the entry + its map key. Shared by BOTH the text-reply and
+ * the inline-button consumers so the peer-disambiguation rules (exact-route key
+ * first, then a per-channel+conversation fallback scan for under-pinned
+ * inbounds like WhatsApp flat-DMs) are identical on both paths.
+ */
+function findPendingEntry(args) {
     const exactKey = peerKey({
         channelId: args.channelId,
         conversationId: args.conversationId,
@@ -381,45 +420,132 @@ export function tryConsumeChannelApprovalReply(args) {
         ...(args.accountId !== undefined ? { accountId: args.accountId } : {}),
         ...(args.agentId !== undefined ? { agentId: args.agentId } : {}),
     });
-    let entry = pendingByPeer.get(exactKey);
-    let entryKey = exactKey;
-    if (!entry) {
-        // Fall back to a per-channel + per-conversation scan that matches when
-        // the caller didn't pin every dimension (e.g. WhatsApp inbound has no
-        // thread/account). Stops on the first agreeing route to preserve the
-        // "one prompt per peer at a time" invariant.
-        for (const [k, candidate] of pendingByPeer.entries()) {
-            const r = candidate.route;
-            if (r.channelId !== args.channelId || r.conversationId !== args.conversationId)
-                continue;
-            if (args.threadId !== undefined && r.threadId !== undefined && r.threadId !== args.threadId)
-                continue;
-            if (args.accountId !== undefined && r.accountId !== undefined && r.accountId !== args.accountId)
-                continue;
-            if (args.agentId !== undefined && r.agentId !== undefined && r.agentId !== args.agentId)
-                continue;
-            entry = candidate;
-            entryKey = k;
-            break;
-        }
+    const exact = pendingByPeer.get(exactKey);
+    if (exact)
+        return { entry: exact, entryKey: exactKey };
+    // Fall back to a per-channel + per-conversation scan that matches when the
+    // caller didn't pin every dimension (e.g. WhatsApp inbound has no
+    // thread/account). Stops on the first agreeing route to preserve the
+    // "one prompt per peer at a time" invariant.
+    for (const [k, candidate] of pendingByPeer.entries()) {
+        const r = candidate.route;
+        if (r.channelId !== args.channelId || r.conversationId !== args.conversationId)
+            continue;
+        if (args.threadId !== undefined && r.threadId !== undefined && r.threadId !== args.threadId)
+            continue;
+        if (args.accountId !== undefined && r.accountId !== undefined && r.accountId !== args.accountId)
+            continue;
+        if (args.agentId !== undefined && r.agentId !== undefined && r.agentId !== args.agentId)
+            continue;
+        return { entry: candidate, entryKey: k };
     }
-    if (!entry)
+    return undefined;
+}
+/** Evict a resolved entry from both maps + cancel its watchdog, then settle the bridge. */
+function settlePending(entry, entryKey, kind) {
+    pendingByPeer.delete(entryKey);
+    pendingById.delete(entry.request.id);
+    clearTimeout(entry.timer);
+    entry.resolveOnBridge({ kind });
+}
+export function tryConsumeChannelApprovalReply(args) {
+    const found = findPendingEntry(args);
+    if (!found)
         return { matched: false };
     const kind = decodeReply(args.text);
     if (kind === null)
         return { matched: false };
-    pendingByPeer.delete(entryKey);
-    pendingById.delete(entry.request.id);
-    clearTimeout(entry.timer);
-    const decision = { kind };
-    entry.resolveOnBridge(decision);
+    settlePending(found.entry, found.entryKey, kind);
     log.info("approval resolved via channel reply", {
         channelId: args.channelId,
         conversationId: args.conversationId,
-        approvalId: entry.request.id,
+        approvalId: found.entry.request.id,
         decision: kind,
     });
-    return { matched: true, decision: kind, approvalId: entry.request.id };
+    return { matched: true, decision: kind, approvalId: found.entry.request.id };
+}
+/**
+ * Try to consume an inline-button press (Telegram `callback_query` etc.) as the
+ * answer to a pending approval for this peer. Mirrors `tryConsumeChannelApprovalReply`
+ * but decodes the button's codec payload instead of free text, and runs an
+ * optional central authorization gate before settling.
+ *
+ * Returns:
+ *   - `{ matched: true, decision, approvalId }` — the payload decoded to a
+ *     pending approval for an AUTHORIZED presser and the bridge was resolved.
+ *     The caller should acknowledge the press and NOT dispatch a turn.
+ *   - `{ matched: false, refused: true, reason }` — the payload matched a
+ *     pending approval but the presser was refused by `authorizeApprover`. The
+ *     pending entry is left intact (a non-operator press must not consume the
+ *     operator's approval). The caller should ack with the refusal reason.
+ *   - `{ matched: false }` — not an approval callback for this peer (foreign /
+ *     malformed payload, or no pending entry). Caller proceeds normally.
+ *
+ * MUST be called AFTER the channel access gate (only trusted peers reach here)
+ * and BEFORE the text-reply path. `authorizeApprover` is the channel's own
+ * predicate (from its `ChannelApprovalCapability`); when provided it is invoked
+ * centrally so a non-operator's button press is refused here, not in the
+ * adapter.
+ */
+export function tryConsumeChannelApprovalCallback(args) {
+    // Decode FIRST — a foreign / malformed button payload is simply "not ours".
+    const decoded = decodeApprovalCallback(args.callbackData);
+    if (!decoded)
+        return { matched: false };
+    const found = findPendingEntry(args);
+    if (!found)
+        return { matched: false };
+    // The decoded payload must reference the SAME pending approval we matched by
+    // peer — otherwise a stale button from a previous (already-resolved-and-
+    // replaced) prompt could settle the wrong approval.
+    if (found.entry.request.id !== decoded.approvalId)
+        return { matched: false };
+    // Central approver authorization: refuse a non-operator press BEFORE
+    // settling. Leave the pending entry intact so the real operator can still
+    // answer.
+    if (args.authorizeApprover) {
+        const verdict = args.authorizeApprover({
+            ...(args.accountId !== undefined ? { accountId: args.accountId } : {}),
+            ...(args.senderId !== undefined ? { senderId: args.senderId } : {}),
+            approvalKind: approvalKindForRequest(found.entry.request),
+        });
+        if (!verdict.authorized) {
+            log.warn("approval callback refused — presser not authorized", {
+                channelId: args.channelId,
+                conversationId: args.conversationId,
+                approvalId: found.entry.request.id,
+                senderId: args.senderId,
+            });
+            return {
+                matched: false,
+                refused: true,
+                ...(verdict.reason !== undefined ? { reason: verdict.reason } : {}),
+            };
+        }
+    }
+    const kind = callbackDecisionToBridgeKind(decoded.decision);
+    settlePending(found.entry, found.entryKey, kind);
+    log.info("approval resolved via channel callback", {
+        channelId: args.channelId,
+        conversationId: args.conversationId,
+        approvalId: found.entry.request.id,
+        decision: kind,
+    });
+    return { matched: true, decision: kind, approvalId: found.entry.request.id };
+}
+/** Map a codec decision onto the bridge's decision-kind vocabulary. */
+function callbackDecisionToBridgeKind(decision) {
+    // The codec's three values are a strict subset of ApprovalDecisionKind, so
+    // this is a widening pass — kept explicit so a future codec value can't
+    // silently leak an unhandled kind onto the bridge.
+    switch (decision) {
+        case "allow-once":
+            return "allow-once";
+        case "allow-always":
+            return "allow-always";
+        case "deny":
+            return "deny";
+    }
 }
 /**
  * Cancel a pending approval by request id (e.g. on session abort).