@vellumai/assistant 0.11.4-dev.202608202110.0dbb88d → 0.11.4-dev.202608202309.2fd95bc

package/README.md

@@ -76,7 +76,7 @@ bun run src/index.ts                # interactive CLI session
 | `vellum sleep`                                     | Stop assistant + gateway processes               |
 | `vellum ps`                                        | List assistants and per-assistant process status |
 | `assistant`                                        | Launch interactive CLI session                   |
-| `assistant conversations list\|new\|export\|clear` | Manage conversations                             |
+| `assistant conversations list\|search\|new\|export\|clear` | Manage conversations                             |
 | `assistant config set\|get\|list`                  | Manage configuration                             |
 | `assistant keys set\|list\|delete`                 | Manage API keys in secure storage                |
 | `assistant trust list\|add\|update\|remove`        | Manage trust rules                               |

package/docs/guardian-request-flow.md

@@ -141,7 +141,18 @@ at the wrong level.
 
 `routes/guardian-approval-interception.ts` + the approval prompt watcher in
 `background-dispatch.ts` predate this pipeline: they deliver a guardian's own
-tool-approval prompt in-channel mid-turn and resolve `apr:` taps against the
-in-memory confirmation directly. They remain load-bearing for that flow, and
+tool-approval prompt mid-turn and resolve `apr:` taps against the in-memory
+confirmation directly. That prompt is addressed to the guardian, not to the
+chat the turn is running in. On Slack that chat can be a shared room, and the
+card carries the tool, a command preview and live buttons.
+`resolveGuardianPromptDelivery` addresses it to the guardian's bound DM
+instead, by chat id rather than user id because that address is written to the
+delivery row and read back to match reactions, scope plain-text replies and
+edit the decided card. It returns the address and its route together, since
+the turn's own callback carries a `threadTs` naming a thread that does not
+exist in the DM. When no private address resolves it returns nothing and the
+prompt is left to the in-app confirmation, because the room is the disclosure
+this exists to prevent. Telegram group chats carry the same exposure and are
+not covered: only Slack has a chat whose privacy can be read off its id. They remain load-bearing for that flow, and
 the reply router runs first for everything the pipeline owns. Converge new
 work on the pipeline; do not extend the legacy interception.

package/node_modules/@vellumai/gateway-client/src/outbound-contract.ts

@@ -179,8 +179,6 @@ export const ChannelReplyPayloadSchema = z.object({
   messageTs: z.string().optional(),
   /** When true, the daemon generates Block Kit blocks from the text before delivery. */
   useBlocks: z.boolean().optional(),
-  /** When provided, perform one Slack streaming operation (start/append/stop). */
-  slackStream: SlackStreamOpSchema.optional(),
 });
 
 export type ChannelReplyPayload = z.infer<typeof ChannelReplyPayloadSchema>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.4-dev.202608202110.0dbb88d",
+  "version": "0.11.4-dev.202608202309.2fd95bc",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/channel-approval-routes.test.ts

@@ -1614,6 +1614,10 @@ describe("background channel processing approval prompts", () => {
       | { requestId?: string }
       | undefined;
     expect(approvalMeta?.requestId).toBe("req-bg-1");
+    // Telegram's chat is already one-to-one, so the prompt stays where the
+    // turn is. Slack, where it does not, is covered in
+    // guardian-prompt-notice-privacy.test.ts.
+    expect(deliverPromptSpy.mock.calls[0]?.[1]).toBe("chat-123");
 
     deliverPromptSpy.mockRestore();
   });

package/src/__tests__/dm-backfill.test.ts

@@ -180,6 +180,8 @@ function readPersistedSlackRows(): Array<{
   provenanceSourceChannel: string | undefined;
   provenanceGuardianExternalUserId: string | undefined;
   provenanceRequesterIdentifier: string | undefined;
+  sentAt: number | undefined;
+  createdAt: number;
 }> {
   const db = getDb();
   return db
@@ -187,6 +189,7 @@ function readPersistedSlackRows(): Array<{
       role: messages.role,
       content: messages.content,
       metadata: messages.metadata,
+      createdAt: messages.createdAt,
     })
     .from(messages)
     .all()
@@ -231,6 +234,9 @@ function readPersistedSlackRows(): Array<{
           typeof envelope.provenanceRequesterIdentifier === "string"
             ? envelope.provenanceRequesterIdentifier
             : undefined,
+        sentAt:
+          typeof envelope.sentAt === "number" ? envelope.sentAt : undefined,
+        createdAt: row.createdAt,
       };
     });
 }
@@ -588,6 +594,32 @@ describe("PR 23 — Slack DM cold-start backfill", () => {
     expect(texts).toEqual(["older A", "older B", "older D"]);
   });
 
+  test("backfilled rows carry the original send time as sentAt", async () => {
+    // History serialization prefers `sentAt` for the display timestamp, so a
+    // row without it reads as having arrived when the import ran.
+    const sentAt = Date.UTC(2026, 6, 8, 9, 15);
+    backfillDmMock.mockImplementation(async () => [
+      makeBackfilledMessage({
+        id: String(sentAt / 1000),
+        text: "six weeks old",
+        timestamp: sentAt,
+      }),
+    ]);
+
+    await handleChannelInbound(
+      buildDmRequest("live new DM"),
+      noopProcessMessage,
+      TEST_BEARER_TOKEN,
+    );
+
+    const [row] = readPersistedSlackRows();
+    expect(row).toBeDefined();
+    expect(row.sentAt).toBe(sentAt);
+    // The row is still written now; only the reported send time is historical.
+    // Asserting the gap is what proves `sentAt` is not just echoing createdAt.
+    expect(row.createdAt).toBeGreaterThan(sentAt);
+  });
+
   test("backfill refuses history rows carrying a secret, keeping the rest", async () => {
     const leakedKey = "AKIA3H7QWERTY9MNBVC2";
     backfillDmMock.mockImplementation(async () => [

package/src/__tests__/guardian-prompt-notice-privacy.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Where a guardian's own gated-tool prompt is delivered.
+ *
+ * The prompt is raised by a turn the guardian is having, and that turn can be
+ * running in a room: a shared Slack channel, a Telegram group. The card
+ * carries the tool name and a preview of the command, so delivering it where
+ * the turn is shows both to everyone there. It goes to the guardian's own
+ * bound chat instead.
+ *
+ * The address is only half of it. A callback URL addresses the turn it came
+ * from, and a param left on one either fails the send or wins over the new
+ * address outright, which is indistinguishable from never having redirected.
+ * The assertions below are written against params the transports read today
+ * *and* against one nothing reads, because the guarantee is that everything is
+ * dropped rather than that a known list is.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+  resolveGuardianPromptDelivery,
+  stripTurnDestination,
+} from "../approvals/guardian-channel-delivery.js";
+
+import "./test-preload.js";
+
+const ROOM = "C0SHARED123";
+const GUARDIAN_CHAT = "D0GUARDIANDM";
+
+describe("a prompt raised where the guardian is not alone", () => {
+  test("is addressed to the guardian's own chat", () => {
+    expect(
+      resolveGuardianPromptDelivery({
+        turnChatId: ROOM,
+        turnCallbackUrl: "https://gw.test/deliver/slack",
+        guardianChatId: GUARDIAN_CHAT,
+      }).chatId,
+    ).toBe(GUARDIAN_CHAT);
+  });
+
+  test("applies to any channel, including ones not built yet", () => {
+    // A Telegram group carries the same exposure as a shared Slack channel,
+    // and so will whatever is added next. The rule names no channel, so there
+    // is no per-channel list to keep in step with the transports.
+    for (const [turnChatId, guardianChatId] of [
+      ["-1001234567890", "555001"],
+      ["guild-channel-1", "dm-channel-1"],
+      ["room@some-future-channel", "direct@some-future-channel"],
+    ]) {
+      expect(
+        resolveGuardianPromptDelivery({
+          turnChatId,
+          turnCallbackUrl: "https://gw.test/deliver/whatever",
+          guardianChatId,
+        }).chatId,
+      ).toBe(guardianChatId);
+    }
+  });
+});
+
+describe("a prompt raised in the guardian's own chat", () => {
+  const turnCallbackUrl = "https://gw.test/deliver/slack?threadTs=111.222";
+
+  test("does not move, and keeps the turn's callback intact", () => {
+    expect(
+      resolveGuardianPromptDelivery({
+        turnChatId: GUARDIAN_CHAT,
+        turnCallbackUrl,
+        guardianChatId: GUARDIAN_CHAT,
+      }),
+    ).toEqual({ chatId: GUARDIAN_CHAT, callbackUrl: turnCallbackUrl });
+  });
+
+  test("does not move when no binding resolved", () => {
+    // The trust context falls back to the turn's own chat, so this is the same
+    // comparison as above: delivery is left exactly as it is today rather than
+    // dropped on the floor.
+    expect(
+      resolveGuardianPromptDelivery({
+        turnChatId: ROOM,
+        turnCallbackUrl,
+        guardianChatId: undefined,
+      }),
+    ).toEqual({ chatId: ROOM, callbackUrl: turnCallbackUrl });
+  });
+});
+
+describe("a redirected delivery leaves the turn behind entirely", () => {
+  const redirected = (turnCallbackUrl: string) =>
+    resolveGuardianPromptDelivery({
+      turnChatId: ROOM,
+      turnCallbackUrl,
+      guardianChatId: GUARDIAN_CHAT,
+    }).callbackUrl;
+
+  test("drops params the transports read today", () => {
+    // threadTs: Slack's thread, absent from the new chat.
+    // threadId: a Telegram forum topic, and on Discord the destination itself
+    // (`sendTarget` returns it in place of the chatId).
+    // dm: changes how Discord reads the address.
+    // channel: the turn's own chat, which the gateway hangs on every Slack
+    // callback.
+    expect(
+      redirected(
+        "https://gw.test/deliver/slack?channel=C1&threadTs=1.2&threadId=9&dm=1&messageTs=3.4",
+      ),
+    ).toBe("https://gw.test/deliver/slack");
+  });
+
+  test("drops a param nothing reads, which is the actual guarantee", () => {
+    // If this only dropped a known list, a transport that starts reading a new
+    // param would silently undo the redirect and no test would notice. The
+    // contract is that the callback keeps its channel and nothing else.
+    expect(redirected("https://gw.test/deliver/x?roomId=42")).toBe(
+      "https://gw.test/deliver/x",
+    );
+  });
+
+  test("keeps the channel, which is how the transport is resolved", () => {
+    // `isDirectDelivery` picks a transport off the path, so the path has to
+    // survive for the redirect to be deliverable at all.
+    expect(redirected("https://gw.test/deliver/telegram?threadId=7")).toContain(
+      "/deliver/telegram",
+    );
+  });
+});
+
+describe("stripTurnDestination", () => {
+  test("returns relative or malformed urls untouched", () => {
+    // They carry no params, and `new URL` throws on them.
+    expect(stripTurnDestination("/deliver/slack")).toBe("/deliver/slack");
+  });
+});

package/src/__tests__/guardian-verify-setup-skill-regression.test.ts

@@ -1,8 +1,12 @@
 /**
  * Regression tests for the guardian-verify-setup skill.
  *
- * Ensures the voice verification flow includes proactive auto-check polling
- * so the user does not have to manually ask whether verification succeeded.
+ * The behaviour under guard is proactive auto-check polling: after a code is
+ * delivered, the skill must poll for completion rather than leaving the user
+ * to ask whether it worked. Originally that existed only for voice, and these
+ * tests pinned the voice section. The three per-channel polling sections were
+ * later merged into one parameterised section, so the assertions here pin the
+ * behaviour in its shared form and cover every channel that polls.
  */
 
 import { readFileSync } from "node:fs";
@@ -23,128 +27,170 @@ const SKILL_PATH = resolve(
 
 const skillContent = readFileSync(SKILL_PATH, "utf-8");
 
+/**
+ * The channels that poll. Telegram is deliberately absent: it confirms through
+ * its own bot-driven flow, so polling it reports nothing.
+ */
+const POLLED_CHANNELS = ["phone", "slack", "discord", "email"] as const;
+
+function section(from: string, to: string): string {
+  const body = skillContent.split(from)[1]?.split(to)[0];
+  // An empty slice would make every `toContain` below fail loudly rather than
+  // silently pass, which is the intent: a renamed heading must break this.
+  return body ?? "";
+}
+
+const pollingSection = () => section("## Auto-Check Polling", "## Step 6");
+
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
 
-describe("guardian-verify-setup skill — voice auto-followup", () => {
-  test("voice path in Step 3 references the auto-check polling loop", () => {
-    // The voice success instruction in Step 3 must direct the assistant to
-    // begin the polling loop rather than waiting for the user to report back.
-    expect(skillContent).toContain(
-      "immediately begin the voice auto-check polling loop",
-    );
+describe("guardian-verify-setup skill: proactive auto-check polling", () => {
+  test("the polling section exists", () => {
+    expect(skillContent).toContain("## Auto-Check Polling");
+  });
+
+  test("Step 3 sends every polled channel into the loop", () => {
+    const step3 = section("## Step 3", "## Step 4");
+    for (const channel of POLLED_CHANNELS) {
+      const bullet = step3
+        .split("\n")
+        .filter((line) =>
+          new RegExp(
+            `^\\s*-\\s+\\*\\*(Phone|Slack|Discord|Email)\\*\\*`,
+            "i",
+          ).test(line),
+        )
+        .find((line) => new RegExp(channel, "i").test(line));
+      expect(bullet, `Step 3 has no bullet for ${channel}`).toBeDefined();
+      expect(bullet).toContain("auto-check polling loop");
+    }
   });
 
-  test("voice path in Step 4 (resend) references the auto-check polling loop", () => {
-    // After a voice resend, the same auto-check behavior must kick in.
-    const resendSection =
-      skillContent.split("## Step 4")[1]?.split("## Step 5")[0] ?? "";
-    expect(resendSection).toContain("voice auto-check polling loop");
+  test("Step 4 resend sends every polled channel back into the loop", () => {
+    const resend = section("## Step 4", "## Step 5");
+    for (const channel of POLLED_CHANNELS) {
+      expect(
+        new RegExp(`\\*\\*${channel}\\*\\*`, "i").test(resend),
+        `Step 4 has no bullet for ${channel}`,
+      ).toBe(true);
+    }
+    expect(resend).toContain("auto-check polling loop");
   });
 
-  test("contains a Voice Auto-Check Polling section", () => {
-    expect(skillContent).toContain("## Voice Auto-Check Polling");
+  test("the polling section names every polled channel and excludes Telegram", () => {
+    const body = pollingSection();
+    for (const channel of POLLED_CHANNELS) {
+      expect(body, `polling section omits ${channel}`).toContain(channel);
+    }
+    // Telegram may only appear as an exclusion, never as a channel to poll.
+    expect(body).toContain("Never Telegram");
   });
 
-  test("polling section specifies the correct status command for voice", () => {
-    const pollingSection =
-      skillContent
-        .split("## Voice Auto-Check Polling")[1]
-        ?.split("## Step 6")[0] ?? "";
-    expect(pollingSection).toContain(
-      "assistant channel-verification-sessions status --channel phone --json",
+  test("the polling command is guarded against an unset channel", () => {
+    const body = pollingSection();
+    // The command is parameterised, so the channel has to be assigned in the
+    // same block. An unset CHANNEL would call the CLI with an empty value.
+    expect(body).toContain('CHANNEL=""');
+    expect(body).toContain('if [ -z "$CHANNEL" ]');
+    expect(body).toContain(
+      'channel-verification-sessions status --channel "$CHANNEL" --json',
     );
   });
 
-  test("polling section includes ~15 second interval", () => {
-    const pollingSection =
-      skillContent
-        .split("## Voice Auto-Check Polling")[1]
-        ?.split("## Step 6")[0] ?? "";
-    expect(pollingSection).toContain("~15 seconds");
+  test("the polling section states an interval and a timeout per channel", () => {
+    const body = pollingSection();
+    expect(body).toContain("15s");
+    expect(body).toContain("20s");
+    expect(body).toContain("2 minutes");
+    expect(body).toContain("3 minutes");
   });
 
-  test("polling section includes 2-minute timeout", () => {
-    const pollingSection =
-      skillContent
-        .split("## Voice Auto-Check Polling")[1]
-        ?.split("## Step 6")[0] ?? "";
-    expect(pollingSection).toContain("2 minutes");
+  test("the polling section checks for bound: true", () => {
+    expect(pollingSection()).toContain("bound: true");
   });
 
-  test("polling section checks for bound: true", () => {
-    const pollingSection =
-      skillContent
-        .split("## Voice Auto-Check Polling")[1]
-        ?.split("## Step 6")[0] ?? "";
-    expect(pollingSection).toContain("bound: true");
+  test("success is reported proactively, not on request", () => {
+    const body = pollingSection();
+    expect(body).toContain("success message");
+    expect(body).toContain("Do NOT require the user to ask");
   });
 
-  test("polling section includes proactive success confirmation", () => {
-    const pollingSection =
-      skillContent
-        .split("## Voice Auto-Check Polling")[1]
-        ?.split("## Step 6")[0] ?? "";
-    expect(pollingSection).toContain("proactive success message");
+  test("timeout offers a resend rather than stopping silently", () => {
+    const body = pollingSection();
+    expect(body).toContain("timeout");
+    expect(body).toContain("resend");
   });
 
-  test("polling section includes timeout fallback with resend/restart offer", () => {
-    const pollingSection =
-      skillContent
-        .split("## Voice Auto-Check Polling")[1]
-        ?.split("## Step 6")[0] ?? "";
-    expect(pollingSection).toContain("timeout");
-    expect(pollingSection).toContain("resend");
+  test("the rebind guard survives, with its false-success reasoning", () => {
+    const body = pollingSection();
+    expect(body).toContain("Rebind guard");
+    expect(body).toContain("verificationSessionId");
+    expect(body).toContain("Non-rebind flows");
   });
 
-  test("polling section includes rebind guard against false-success from pre-existing binding", () => {
-    const pollingSection =
-      skillContent
-        .split("## Voice Auto-Check Polling")[1]
-        ?.split("## Step 6")[0] ?? "";
-    // Must mention rebind guard concept
-    expect(pollingSection).toContain("Rebind guard");
-    // Must instruct not to trust bound: true alone in a rebind flow
-    expect(pollingSection).toContain(
-      "do NOT treat `bound: true` alone as success",
-    );
-    // Must reference verificationSessionId as the mechanism to detect fresh binding
-    expect(pollingSection).toContain("verificationSessionId");
-    // Must clarify non-rebind flows are unaffected
-    expect(pollingSection).toContain("Non-rebind flows");
+  test("no polled channel's Step 3 bullet tells the assistant to wait", () => {
+    const step3 = section("## Step 3", "## Step 4");
+    // Narrowed to the polled bullets: Telegram's "wait for the user to confirm
+    // they clicked the link" is a real instruction for its own bootstrap flow.
+    const bullets = step3
+      .split("\n")
+      .filter((line) =>
+        /^\s*-\s+\*\*(Phone|Slack|Discord|Email)\*\*/i.test(line),
+      );
+    expect(bullets.length).toBe(POLLED_CHANNELS.length);
+    for (const bullet of bullets) {
+      expect(bullet).not.toContain("wait for the user to confirm");
+      expect(bullet).not.toContain("ask the user if it worked");
+    }
+  });
+});
+
+describe("guardian-verify-setup skill: channel coverage", () => {
+  test("every channel the CLI accepts is offered in Step 1", () => {
+    const step1 = section("## Step 1", "## Step 2");
+    for (const channel of [...POLLED_CHANNELS, "telegram"]) {
+      expect(step1, `Step 1 does not offer ${channel}`).toContain(
+        `**${channel}**`,
+      );
+    }
+  });
+
+  test("Step 2 collects a destination for every channel", () => {
+    const step2 = section("## Step 2", "## Step 3");
+    for (const channel of ["Phone", "Telegram", "Slack", "Discord", "Email"]) {
+      expect(step2, `Step 2 has no destination for ${channel}`).toContain(
+        `**${channel}**`,
+      );
+    }
   });
 
-  test("polling is voice-only — does not apply to Telegram", () => {
-    const pollingSection =
-      skillContent
-        .split("## Voice Auto-Check Polling")[1]
-        ?.split("## Step 6")[0] ?? "";
-    expect(pollingSection).toContain("voice-only");
-    expect(pollingSection).toContain("Do NOT poll for Telegram");
+  test("the missing-secret guardrail names only its exception", () => {
+    const guardrail = skillContent
+      .split("\n")
+      .find((line) => line.includes("Missing `secret` guardrail"));
+    expect(guardrail).toBeDefined();
+    // The rule covers every flow but one, so the line states that exception.
+    // Naming any other channel makes it an enumeration, and an enumeration
+    // drifts out of date the next time a channel is added.
+    expect(guardrail).toContain("except");
+    expect(guardrail).toContain("Telegram");
+    const lower = guardrail!.toLowerCase();
+    for (const channel of ["phone", "voice", "slack", "discord", "email"]) {
+      expect(lower, `guardrail enumerates ${channel}`).not.toContain(channel);
+    }
   });
 
-  test('no instruction requires waiting for user to ask "did it work?"', () => {
-    // The skill should never instruct the assistant to wait for the user to
-    // confirm that voice verification worked. The auto-check polling loop
-    // makes this unnecessary.
-    const voiceAutoCheckSection =
-      skillContent
-        .split("## Voice Auto-Check Polling")[1]
-        ?.split("## Step 6")[0] ?? "";
-    expect(voiceAutoCheckSection).toContain("Do NOT require the user to ask");
-    // The voice bullet in Step 3 should not instruct the assistant to wait
-    // for the user to confirm or ask if it worked. Narrow to just the voice
-    // bullet line to avoid false positives from Telegram's "wait for the
-    // user to confirm they clicked the link" which is unrelated to voice.
-    const step3Section =
-      skillContent.split("## Step 3")[1]?.split("## Step 4")[0] ?? "";
-    const voiceBullet = step3Section
+  test("the status and revoke guards allow every supported channel", () => {
+    // These enumerate valid CHANNEL values. A channel missing here reads to
+    // the assistant as unsupported at exactly the point a user asks for it.
+    const guards = skillContent
       .split("\n")
-      .filter((line) => /^\s*-\s+\*\*Phone\*\*/.test(line))
-      .join("\n");
-    expect(voiceBullet).not.toHaveLength(0);
-    expect(voiceBullet).not.toContain("wait for the user to confirm");
-    expect(voiceBullet).not.toContain("ask the user if it worked");
+      .filter((line) => line.includes("MUST set to one of"));
+    expect(guards.length).toBeGreaterThanOrEqual(2);
+    for (const guard of guards) {
+      expect(guard).toContain("discord");
+    }
   });
 });

package/src/approvals/guardian-channel-delivery.ts

@@ -1,11 +1,12 @@
 /**
- * Shared addressing helpers for guardian requester-facing channel notices.
+ * Shared addressing helpers for guardian-flow channel notices.
  *
- * Requester notices (approval, denial, expiry) are delivered straight to the
- * requester's chat via `deliverChannelReply` — independent of the
- * guardian-facing notification pipeline. Centralizing the addressing rules here
- * keeps the decision resolvers and the timer-driven expiry sweep from drifting
- * apart on how a requester is reached.
+ * Requester notices (approval, denial, expiry) and the guardian's own approval
+ * prompt are delivered straight to a chat via `deliverChannelReply` -
+ * independent of the guardian-facing notification pipeline. Centralizing the
+ * addressing rules here keeps the decision resolvers, the timer-driven expiry
+ * sweep and the in-turn approval prompt from drifting apart on who a message
+ * is put in front of.
  */
 
 /**
@@ -111,3 +112,66 @@ export function resolveRequesterDeliveryTarget(params: {
   }
   return requesterChatId;
 }
+
+/**
+ * Reduce a reply callback to its channel route, dropping every query param.
+ *
+ * A callback addresses the turn it came from. The gateway hangs the turn's
+ * coordinates on it as params, and each transport reads a different one:
+ * Slack a `threadTs`, Telegram a forum topic `threadId`, Discord a `threadId`
+ * that replaces the destination outright rather than narrowing it. Carried
+ * onto a delivery aimed elsewhere they either fail the send or quietly win
+ * over the new address, and a redirect that leaves one behind is
+ * indistinguishable from no redirect at all.
+ *
+ * Everything is dropped rather than a named set, so a channel added later, or
+ * a param a transport starts reading later, cannot silently escape this. The
+ * channel itself survives because it is the path, which is also what
+ * `isDirectDelivery` resolves a transport from, and nothing the gateway hangs
+ * on a deliver callback is needed to authorize or route the send.
+ *
+ * Relative or malformed URLs are returned as-is; they carry no params.
+ */
+export function stripTurnDestination(replyCallbackUrl: string): string {
+  try {
+    const url = new URL(replyCallbackUrl);
+    url.search = "";
+    return url.toString();
+  } catch {
+    return replyCallbackUrl;
+  }
+}
+
+/**
+ * Resolve where a guardian's own approval prompt is delivered.
+ *
+ * The prompt is raised by a turn the guardian is having, and that turn can be
+ * running in a room: a shared Slack channel, a Telegram group. The card
+ * carries the tool name and a preview of the command, so delivering it where
+ * the turn is shows both to everyone there.
+ *
+ * It goes to the guardian's own bound chat instead, the address they
+ * nominated when they verified and the one the notification pipeline already
+ * sends guardian cards to. No channel is named in this rule and none can be
+ * forgotten by it: a bound chat is the guardian's by definition, on any
+ * channel, including ones not built yet.
+ *
+ * A bound chat equal to the turn's chat means the turn is already there, so
+ * nothing moves. That also covers a turn where no binding resolved, since the
+ * trust context falls back to the turn's own chat, leaving delivery exactly as
+ * it is rather than dropping it.
+ */
+export function resolveGuardianPromptDelivery(params: {
+  turnChatId: string;
+  turnCallbackUrl: string;
+  guardianChatId: string | undefined;
+}): { chatId: string; callbackUrl: string } {
+  const { turnChatId, turnCallbackUrl, guardianChatId } = params;
+  if (!guardianChatId || guardianChatId === turnChatId) {
+    return { chatId: turnChatId, callbackUrl: turnCallbackUrl };
+  }
+  return {
+    chatId: guardianChatId,
+    callbackUrl: stripTurnDestination(turnCallbackUrl),
+  };
+}