@vellumai/assistant 0.9.0 → 0.9.1-staging.1

package/src/plugins/defaults/surface-completion-nudge/hooks/post-model-call.ts

@@ -0,0 +1,276 @@
+/**
+ * Default `post-model-call` hook: when a user-facing turn is about to end with a
+ * progress surface the model showed but never closed, nudge the model — once
+ * per run — to complete or dismiss it, then re-query so it can act.
+ *
+ * Motivation: the model can call `ui_show` with a `task_progress` card (or a
+ * `work_result` in an `in_progress` state) to show live progress, but weaker
+ * models often never advance it to a terminal status or `ui_dismiss` it. The
+ * surface then renders a spinner forever, long after the work finished. Static
+ * prompt guidance is easy to ignore; a reminder injected at the moment the turn
+ * would otherwise end — with a concrete "you left this open" signal — is far
+ * more salient.
+ *
+ * The nudge is strictly best-effort and self-targeting:
+ * - It fires at most once per run (no looping if the model declines).
+ * - It is advisory — the model may leave the surface open if the work it
+ *   represents is genuinely still running.
+ * - A model that already completed or dismissed its surfaces is never nudged,
+ *   so capable models that close their surfaces pay nothing.
+ *
+ * Only a finalized, no-tool, main-agent reply is actionable:
+ * - A provider rejection carries no turn content to assess (a recovery hook
+ *   like history-repair owns that).
+ * - A tool-bearing turn continues naturally — the loop runs the tools and the
+ *   model gets another chance to close the surface — so we leave it alone.
+ * - Background call sites (wake, title-gen, memory) have no live user watching
+ *   a spinner, so the nudge would only burn a model round.
+ *
+ * No subagent guard is needed: the `ui-surface` tools are gated on a connected
+ * client (see `conversation-tool-setup.ts`), and subagents have none — so a
+ * subagent can never create a surface and so can never trigger this hook.
+ *
+ * The dangling-surface signal is derived from the current response cycle (the
+ * messages after the last genuine user prompt) by correlating each progress
+ * `ui_show` with its `surface_id` result and folding in later `ui_update` /
+ * `ui_dismiss` calls. Deriving the cycle boundary from history content rather
+ * than an index means mid-run compaction (which rewrites the array in place)
+ * can't invalidate it.
+ *
+ * The one-shot bound is split across two hooks: this hook marks the
+ * conversation when it nudges, and the sibling `stop` hook clears the mark when
+ * the turn terminates, so the next run nudges afresh.
+ *
+ * Defaults register before any user plugin, so this hook runs at the front of
+ * the `post-model-call` chain — later hooks see (and may override) its decision.
+ */
+
+import type { PluginHookFn, PostModelCallContext } from "@vellumai/plugin-api";
+
+import type { ContentBlock, Message } from "../../../../providers/types.js";
+import {
+  isSurfaceCompletionNudged,
+  markSurfaceCompletionNudged,
+} from "../nudge-state-store.js";
+
+/**
+ * Canonical nudge text. Shown to the model as provider-only context, never to
+ * the user. Kept verbatim so a plugin that wraps the default sees a stable
+ * string. Deliberately soft: the model may leave the surface open if the work
+ * is genuinely still running.
+ */
+export const SURFACE_COMPLETION_NUDGE_TEXT =
+  '<system_notice>You showed the user a progress surface this turn (a task_progress card or a work_result) and are about to end the turn with it still marked in_progress. If that work is finished, advance it to a terminal state now — call ui_update to set its status to "completed" (or "failed"), or ui_dismiss it — so the user is not left watching a card spin forever. Do this only if the work it represents is actually done; if it is genuinely still running, leave it. Then give your final reply.</system_notice>';
+
+/**
+ * Surface statuses that mean the progress surface has reached a terminal state
+ * and needs no completion nudge. Covers both `task_progress`
+ * (`completed`/`failed`) and `work_result` (`completed`/`partial`/`failed`),
+ * plus `cancelled` for tolerance.
+ */
+const TERMINAL_STATUSES = new Set([
+  "completed",
+  "failed",
+  "partial",
+  "cancelled",
+]);
+
+function hasToolUse(content: ReadonlyArray<ContentBlock>): boolean {
+  return content.some((block) => block.type === "tool_use");
+}
+
+/** A user-role message carrying only tool results, not a fresh prompt. */
+function isToolResultMessage(message: Message): boolean {
+  return (
+    message.role === "user" &&
+    message.content.length > 0 &&
+    message.content.every((block) => block.type === "tool_result")
+  );
+}
+
+/**
+ * Messages belonging to the current response cycle: everything after the last
+ * genuine user prompt. Falls back to the whole history when none is found.
+ */
+function currentCycleMessages(
+  messages: ReadonlyArray<Message>,
+): ReadonlyArray<Message> {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message.role === "user" && !isToolResultMessage(message)) {
+      return messages.slice(i + 1);
+    }
+  }
+  return messages;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object"
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+/**
+ * Pull a surface status out of a `ui_show` / `ui_update` input, tolerating the
+ * shapes the server-side normalization accepts: nested under
+ * `data.templateData` (task_progress), under `data` (work_result), or at the
+ * top level. Returns a lowercased status, or `undefined` when none is present.
+ */
+function extractStatus(input: Record<string, unknown>): string | undefined {
+  const data = asRecord(input.data);
+  const templateData =
+    asRecord(data?.templateData) ?? asRecord(input.templateData);
+  const raw = templateData?.status ?? data?.status ?? input.status;
+  return typeof raw === "string" ? raw.trim().toLowerCase() : undefined;
+}
+
+/**
+ * Whether a `ui_show` input describes a surface with a progress lifecycle: a
+ * `task_progress` card or a `work_result`. Returns the initial status when so.
+ */
+function progressShowInfo(input: Record<string, unknown>): {
+  isProgress: boolean;
+  status: string | undefined;
+} {
+  const surfaceType = input.surface_type;
+  if (surfaceType === "work_result") {
+    return { isProgress: true, status: extractStatus(input) };
+  }
+  if (surfaceType === "card") {
+    const data = asRecord(input.data);
+    const template = data?.template ?? input.template;
+    if (template === "task_progress") {
+      return { isProgress: true, status: extractStatus(input) };
+    }
+  }
+  return { isProgress: false, status: undefined };
+}
+
+function surfaceIdOf(input: Record<string, unknown>): string | undefined {
+  return typeof input.surface_id === "string" ? input.surface_id : undefined;
+}
+
+/** Parse the `{ surfaceId }` JSON a successful `ui_show` returns. */
+function parseSurfaceId(content: string): string | undefined {
+  try {
+    const parsed = JSON.parse(content) as unknown;
+    const record = asRecord(parsed);
+    return typeof record?.surfaceId === "string" ? record.surfaceId : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+interface SurfaceState {
+  /** Latest known status, lowercased; `undefined` when never set explicitly. */
+  status: string | undefined;
+  dismissed: boolean;
+}
+
+function isNonTerminal(state: SurfaceState): boolean {
+  if (state.dismissed) return false;
+  return state.status === undefined || !TERMINAL_STATUSES.has(state.status);
+}
+
+/**
+ * True when the current response cycle left at least one progress surface
+ * (a `task_progress` card or `work_result`) open: shown but neither advanced to
+ * a terminal status nor dismissed.
+ *
+ * Each progress `ui_show` is correlated to its `surface_id` via the matching
+ * tool result (the result lands in the next message; updates and dismisses
+ * arrive in later messages, after the model has the id in hand). Later
+ * `ui_update` / `ui_dismiss` calls fold their status / dismissal onto the
+ * tracked surface.
+ */
+function hasDanglingProgressSurface(messages: ReadonlyArray<Message>): boolean {
+  const surfaces = new Map<string, SurfaceState>();
+  // tool_use_id -> initial status of a progress ui_show awaiting its result id.
+  const pendingShows = new Map<string, string | undefined>();
+
+  for (const message of currentCycleMessages(messages)) {
+    if (message.role === "assistant") {
+      for (const block of message.content) {
+        if (block.type !== "tool_use") continue;
+        if (block.name === "ui_show") {
+          const info = progressShowInfo(block.input);
+          if (info.isProgress) pendingShows.set(block.id, info.status);
+        } else if (block.name === "ui_update") {
+          const id = surfaceIdOf(block.input);
+          const status = extractStatus(block.input);
+          if (id && status !== undefined) {
+            const existing = surfaces.get(id);
+            if (existing) existing.status = status;
+            else surfaces.set(id, { status, dismissed: false });
+          }
+        } else if (block.name === "ui_dismiss") {
+          const id = surfaceIdOf(block.input);
+          if (id) {
+            const existing = surfaces.get(id);
+            if (existing) existing.dismissed = true;
+            else surfaces.set(id, { status: undefined, dismissed: true });
+          }
+        }
+      }
+      continue;
+    }
+    if (message.role !== "user") continue;
+    for (const block of message.content) {
+      // guard:allow-tool-result-only — only the local tool executor's
+      // `tool_result` carries a `ui_show` `surfaceId` to correlate. A
+      // `web_search_tool_result` comes from a `server_tool_use`, never a
+      // `ui_show`, so it can never match a pending show and is correctly skipped.
+      if (block.type !== "tool_result") continue;
+      if (!pendingShows.has(block.tool_use_id)) continue;
+      const initialStatus = pendingShows.get(block.tool_use_id);
+      pendingShows.delete(block.tool_use_id);
+      const id = parseSurfaceId(block.content);
+      if (!id) continue;
+      const existing = surfaces.get(id);
+      // A later update/dismiss can register the id before its show result is
+      // scanned only if history was reordered; guard so we never clobber a
+      // known terminal/dismissed state with the initial status.
+      if (existing) {
+        if (existing.status === undefined && !existing.dismissed) {
+          existing.status = initialStatus;
+        }
+      } else {
+        surfaces.set(id, { status: initialStatus, dismissed: false });
+      }
+    }
+  }
+
+  for (const state of surfaces.values()) {
+    if (isNonTerminal(state)) return true;
+  }
+  return false;
+}
+
+const postModelCall: PluginHookFn<PostModelCallContext> = async (ctx) => {
+  // A provider rejection carries no turn content to assess (a recovery hook
+  // owns the rejection).
+  if (ctx.error) return;
+  // A tool-bearing turn continues mid-run — the loop runs the tools and the
+  // model gets another chance to close the surface — so leave it alone.
+  if (hasToolUse(ctx.content)) return;
+  // Only nudge the user-facing reply: background call sites have no live user
+  // watching a spinner.
+  if (ctx.callSite !== "mainAgent") return;
+  // One nudge per run; the sibling `stop` hook clears the mark on terminal stop.
+  if (isSurfaceCompletionNudged(ctx.conversationId)) return;
+
+  if (!hasDanglingProgressSurface(ctx.messages)) return;
+
+  markSurfaceCompletionNudged(ctx.conversationId);
+  ctx.messages.push({
+    role: "user",
+    content: [{ type: "text", text: SURFACE_COMPLETION_NUDGE_TEXT }],
+  });
+  ctx.decision = "continue";
+  ctx.logger.info(
+    { plugin: "surface-completion-nudge", conversationId: ctx.conversationId },
+    "Turn ending with an open progress surface — nudging the model to complete or dismiss it",
+  );
+};
+
+export default postModelCall;

package/src/plugins/defaults/surface-completion-nudge/hooks/stop.ts

@@ -0,0 +1,22 @@
+/**
+ * Default `stop` hook: clears the per-conversation surface-completion nudge
+ * bound when a turn terminates.
+ *
+ * The `post-model-call` hook (see `./post-model-call.ts`) marks the bound when
+ * it nudges the model to close a dangling progress surface. `stop` is the
+ * definitive terminal hook — it fires exactly once when the turn is truly
+ * ending, after every retry decision has been made — so clearing the bound here
+ * unconditionally guarantees the next run nudges afresh, no matter how the turn
+ * ended (a finalized reply, an abort, or a retry the loop's per-run backstop
+ * refused).
+ */
+
+import type { PluginHookFn, StopContext } from "@vellumai/plugin-api";
+
+import { clearSurfaceCompletionNudged } from "../nudge-state-store.js";
+
+const stop: PluginHookFn<StopContext> = async (ctx) => {
+  clearSurfaceCompletionNudged(ctx.conversationId);
+};
+
+export default stop;

package/src/plugins/defaults/surface-completion-nudge/nudge-state-store.ts

@@ -0,0 +1,46 @@
+/**
+ * Per-conversation surface-completion nudge state.
+ *
+ * The `post-model-call` hook nudges the model — once per run — to complete or
+ * dismiss a progress surface it left `in_progress` when the turn was about to
+ * end, asking the loop to re-query so the model can act on it. That nudge is
+ * bounded to one pass per run: if the model declines or fails to close the
+ * surface, the hook lets the turn end rather than looping on it.
+ *
+ * The two hooks split this state's lifecycle: `post-model-call` marks a
+ * conversation when it issues the nudge, and the sibling `stop` hook clears the
+ * mark when the turn terminates. A conversation therefore only holds an entry
+ * while a nudge is in flight, and the next run nudges afresh.
+ *
+ * This module is side-effect free: importing it only initializes an empty store
+ * and registers no plugin.
+ */
+
+/** Conversations with a surface-completion nudge in flight for the current run. */
+const nudgeInFlight = new Set<string>();
+
+/** Whether the conversation already issued its one nudge this run. */
+export function isSurfaceCompletionNudged(conversationId: string): boolean {
+  return nudgeInFlight.has(conversationId);
+}
+
+/** Record that the conversation issued its one nudge this run. */
+export function markSurfaceCompletionNudged(conversationId: string): void {
+  nudgeInFlight.add(conversationId);
+}
+
+/**
+ * Clear the conversation's nudge mark so the next run nudges afresh. The
+ * sibling `stop` hook calls this when the turn terminates.
+ */
+export function clearSurfaceCompletionNudged(conversationId: string): void {
+  nudgeInFlight.delete(conversationId);
+}
+
+/**
+ * Test-only: drop every conversation's nudge state so a suite that drives the
+ * hook directly starts each case from an empty store.
+ */
+export function resetSurfaceCompletionNudgeStoreForTests(): void {
+  nudgeInFlight.clear();
+}

package/src/plugins/defaults/surface-completion-nudge/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "default-surface-completion-nudge",
+  "version": "1.0.0",
+  "description": "First-party default plugin that nudges the model to complete or dismiss a progress surface it left in_progress when the turn ends.",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "peerDependencies": {
+    "@vellumai/plugin-api": "^0.8.0"
+  }
+}

package/src/plugins/defaults/task-progress-nudge/hooks/post-tool-use.ts

@@ -56,7 +56,7 @@ import type { ContentBlock, Message } from "../../../../providers/types.js";
  * are fine and the model may skip it when wrapping up.
  */
 export const TASK_PROGRESS_NUDGE_TEXT =
-  '<system_notice>You are several tool calls into this turn and have not shown the user a progress card. If you are doing multi-step work, call ui_show now with surface_type "card" and template "task_progress" (coarse steps are fine — a rough "Working on X" beats no signal) so the user can see what is happening, and keep it updated with ui_update as you go. Skip this if you are about to finish; never let it interrupt the actual work.</system_notice>';
+  '<system_notice>You are several tool calls into this turn with no progress card shown. A card is optional, not required: if the turn is wrapping up, is not really multi-step, or you cannot form clean steps, skip it and keep working — a one-line note of what you are doing is a fine substitute, and proceeding with no card is also fine. Only if a live step tracker would genuinely help the user, show it with a SINGLE self-contained ui_show call that already contains the steps: ui_show({ surface_type: "card", data: { template: "task_progress", templateData: { title: "<what you are doing>", status: "in_progress", steps: [{ label: "<step 1>", status: "in_progress" }, { label: "<step 2>", status: "pending" }] } } }). Coarse steps are fine. Do not call ui_show with an empty `data: {}` and fill it in afterward — an empty card renders as a blank box; either include the steps now or skip the card. Advance it later with ui_update under `data.templateData`. Never let the card interrupt the actual work; if one ever looks wrong, just dismiss it and move on. You will not be nudged about this again this turn.</system_notice>';
 
 /**
  * Number of tool-use rounds in a turn, with no task_progress card shown, that

package/src/prompts/persona-resolver.ts

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 
 import {
-  findContactByChannelExternalId,
+  findContactByAddress,
   findGuardianForChannel,
   listGuardianChannels,
 } from "../contacts/contact-store.js";
@@ -88,7 +88,7 @@ function resolveUserFilename(
       }
     } else if (trustContext.requesterExternalUserId) {
       // Channel-routed request — look up contact by channel identity
-      const contactWithChannels = findContactByChannelExternalId(
+      const contactWithChannels = findContactByAddress(
         trustContext.sourceChannel,
         trustContext.requesterExternalUserId,
       );

package/src/runtime/AGENTS.md

@@ -22,7 +22,6 @@ GET handlers must be safe and side-effect-free — they must not enqueue backgro
 
 Accepted exceptions (stale-while-revalidate caches): a GET handler may kick off a bounded, fire-and-forget background refresh of a generated-content cache when no fresh cache exists, provided the handler itself stays read-only and returns immediately with cached/fallback copy, the refresh is single-flight (concurrent GETs share one regeneration), and a TTL bounds regeneration frequency. Current instances:
 
-- `GET /v1/identity/intro` — refreshes the generated greeting cache; the background prompt may only depend on static identity/soul context plus caller-supplied local hour/minute.
 - `GET /v1/home/feed` — refreshes the personalized home greeting and suggested-prompt caches via `revalidateHomeContentInBackground()`, which publishes `home_feed_updated` when fresh content lands so clients refetch. This is intentional: home content is generated on demand (when a user actually views Home), never at daemon startup or on a timer.
 - `GET /v1/conversation-starters` — enqueues a `generate_conversation_starters` memory job when the starter set is stale, cooldown-gated and deduped against in-flight jobs.
 

package/src/runtime/actor-trust-resolver.ts

@@ -14,7 +14,6 @@
 import type { ChannelId } from "../channels/types.js";
 import {
   findContactByAddress,
-  findContactByChannelExternalId,
   findGuardianForChannel,
 } from "../contacts/contact-store.js";
 import type { ContactChannel, ContactWithChannels } from "../contacts/types.js";
@@ -181,19 +180,14 @@ export function resolveActorTrust(
   if (guardianResult) {
     const { contact: guardianContact, channel: guardianChannel } =
       guardianResult;
-    const canonicalGuardianId = guardianChannel.externalUserId
-      ? canonicalizeInboundIdentity(
-          input.sourceChannel,
-          guardianChannel.externalUserId,
-        )
-      : null;
     guardianBindingMatch = {
-      guardianExternalUserId: guardianChannel.externalUserId ?? "",
+      guardianExternalUserId:
+        guardianChannel.externalUserId ?? guardianChannel.address ?? "",
       guardianDeliveryChatId: guardianChannel.externalChatId,
     };
     guardianPrincipalId = guardianContact.principalId ?? undefined;
     isGuardian =
-      canonicalGuardianId != null && canonicalGuardianId === canonicalSenderId;
+      guardianChannel.address.toLowerCase() === canonicalSenderId.toLowerCase();
   }
 
   log.debug(
@@ -206,37 +200,18 @@ export function resolveActorTrust(
   );
 
   // --- Member lookup via contacts ---
-  // Primary path: match by externalUserId (populated after channel verification
-  // completes, or for channels registered via the verification upsert path).
-  // Fallback path: match by address (covers channels registered by the inbound
-  // name-capture flow, where address is set but externalUserId remains NULL
-  // until the DTMF challenge succeeds). Mirrors the gateway's OR-based lookup
-  // in ContactStore.getContactByPhoneNumber so the runtime's unverified-caller
-  // guard fires for pre-verification channels the gateway passes through.
   let memberRecord: ActorTrustContext["memberRecord"] = null;
-  const byExternalId = findContactByChannelExternalId(
+  const byAddress = findContactByAddress(
     input.sourceChannel,
     canonicalSenderId,
   );
-  const byExternalIdChannel = byExternalId?.channels.find(
+  const byAddressChannel = byAddress?.channels.find(
     (ch) =>
       ch.type === input.sourceChannel &&
-      ch.externalUserId === canonicalSenderId,
+      ch.address.toLowerCase() === canonicalSenderId.toLowerCase(),
   );
-
-  if (byExternalId && byExternalIdChannel) {
-    memberRecord = { contact: byExternalId, channel: byExternalIdChannel };
-  } else {
-    // Address fallback: catches channels where externalUserId is not yet set.
-    const byAddress = findContactByAddress(input.sourceChannel, canonicalSenderId);
-    const byAddressChannel = byAddress?.channels.find(
-      (ch) =>
-        ch.type === input.sourceChannel &&
-        ch.address?.toLowerCase() === canonicalSenderId.toLowerCase(),
-    );
-    if (byAddress && byAddressChannel) {
-      memberRecord = { contact: byAddress, channel: byAddressChannel };
-    }
+  if (byAddress && byAddressChannel) {
+    memberRecord = { contact: byAddress, channel: byAddressChannel };
   }
 
   log.debug(
@@ -244,23 +219,16 @@ export function resolveActorTrust(
       channel: input.sourceChannel,
       canonicalSenderId,
       found: !!memberRecord,
-      via: memberRecord?.channel.externalUserId ? "externalUserId" : memberRecord ? "address" : "none",
+      via: memberRecord ? "address" : "none",
     },
     "trust-resolver member lookup",
   );
 
   // Only use member metadata when the record's channel identity matches the
   // current sender to avoid misidentification in group chats.
-  // Primary check: externalUserId (canonicalized to handle E.164 variance).
-  // Fallback: address match for channels where externalUserId is NULL (e.g.
-  // name-capture registrations that haven't completed DTMF verification yet).
-  const memberMatchesSender = memberRecord?.channel.externalUserId
-    ? canonicalizeInboundIdentity(
-        input.sourceChannel,
-        memberRecord.channel.externalUserId,
-      ) === canonicalSenderId
-    : (memberRecord?.channel.address?.toLowerCase() ===
-      canonicalSenderId.toLowerCase());
+  const memberMatchesSender =
+    memberRecord?.channel.address.toLowerCase() ===
+    canonicalSenderId.toLowerCase();
 
   const memberDisplayName =
     memberMatchesSender &&

package/src/runtime/btw-sidechain.ts

@@ -31,10 +31,9 @@ export interface RunBtwSidechainParams {
   /**
    * Unified call-site identifier. The provider layer resolves
    * provider/model/maxTokens/effort/speed/temperature/thinking/contextWindow
-   * via `resolveCallSiteConfig(callSite, config.llm)`. Defaults to
-   * `'identityIntro'` since this side-chain runner was originally introduced
-   * for the identity intro generation path; callers (greeting, title, etc.)
-   * override it with their own call-site ID.
+   * via `resolveCallSiteConfig(callSite, config.llm)`. Generic BTW traffic
+   * uses `identityIntro`; callers with a narrower purpose override it with
+   * their own call-site ID.
    */
   callSite?: LLMCallSite;
   signal?: AbortSignal;
@@ -95,8 +94,6 @@ export async function runBtwSidechain(
       config: {
         max_tokens: params.maxTokens ?? 1024,
         tool_choice: { type: "none" },
-        // Default call site is "identityIntro" — the original purpose of
-        // this side-chain runner. Callers may override per invocation.
         callSite: params.callSite ?? ("identityIntro" as LLMCallSite),
       },
       onEvent: (event) => {

package/src/runtime/channel-approval-types.ts

@@ -1,27 +1,31 @@
 /**
  * Channel-agnostic approval flow types.
  *
- * These types model the approval prompt/decision lifecycle for tool-use
- * confirmations surfaced through external channels (Telegram, Slack, etc.).
- * They are intentionally decoupled from any specific channel so that the
- * same approval flow can be reused across transports.
+ * Wire-format types (`ApprovalUIMetadata`, `PermissionRequestDetails`,
+ * `ApprovalActionOption`) are defined as Zod schemas in
+ * `@vellumai/gateway-client/outbound-contract` and re-exported here for
+ * convenience. Daemon-internal types that do not cross a wire boundary
+ * are defined locally.
  */
 
+import type { ApprovalActionOption } from "@vellumai/gateway-client";
+
 import type { GuardianDecisionAction } from "./guardian-decision-types.js";
 
+// Re-export shared wire types so existing daemon imports keep working.
+export type {
+  ApprovalActionOption,
+  ApprovalUIMetadata,
+  PermissionRequestDetails,
+} from "@vellumai/gateway-client";
+
 // ---------------------------------------------------------------------------
-// Approval actions
+// Approval actions (daemon-internal)
 // ---------------------------------------------------------------------------
 
 /** The set of actions a user can take on an approval prompt. */
 export type ApprovalAction = "approve_once" | "reject";
 
-/** An action presented to the user as a tappable button or text option. */
-export interface ApprovalActionOption {
-  id: ApprovalAction;
-  label: string;
-}
-
 /**
  * Map `GuardianDecisionAction[]` to `ApprovalActionOption[]` so channel
  * prompt payloads can be derived from the unified decision action set.
@@ -32,13 +36,13 @@ export function toApprovalActionOptions(
   actions: GuardianDecisionAction[],
 ): ApprovalActionOption[] {
   return actions.map((a) => ({
-    id: a.action as ApprovalAction,
+    id: a.action,
     label: a.label,
   }));
 }
 
 // ---------------------------------------------------------------------------
-// Approval prompt
+// Approval prompt (daemon-internal)
 // ---------------------------------------------------------------------------
 
 /** The approval prompt model sent to users via a channel. */
@@ -52,38 +56,7 @@ export interface ChannelApprovalPrompt {
 }
 
 // ---------------------------------------------------------------------------
-// Approval UI metadata (gateway callback payload)
-// ---------------------------------------------------------------------------
-
-/**
- * Tool-permission-specific details carried alongside the approval payload.
- * Channels that support rich UI (e.g. Slack Block Kit) use these fields
- * to render a detailed permission request card with risk indicators,
- * tool arguments, and requester identity.
- */
-export interface PermissionRequestDetails {
-  toolName: string;
-  riskLevel: string;
-  toolInput: Record<string, unknown>;
-  /** Present for guardian-escalated requests to identify who is asking. */
-  requesterIdentifier?: string;
-}
-
-/**
- * Metadata attached to gateway callback payloads so the channel adapter
- * can render approval UI and route the user's decision back to the
- * correct pending interaction.
- */
-export interface ApprovalUIMetadata {
-  requestId: string;
-  actions: ApprovalActionOption[];
-  plainTextFallback: string;
-  /** When present, the approval is a tool permission request with extra context. */
-  permissionDetails?: PermissionRequestDetails;
-}
-
-// ---------------------------------------------------------------------------
-// Decision result
+// Decision result (daemon-internal)
 // ---------------------------------------------------------------------------
 
 /** How the user communicated their decision. */

package/src/runtime/channel-invite-transports/telegram.ts

@@ -36,10 +36,10 @@ import type {
 
 /**
  * Ensure the Telegram bot username is resolved and cached in config.
- * When the bot token was configured via CLI `credential set`,
- * `credential_store` tool, or ingress secret redirect, the `getMe` API
- * call that populates the config is skipped — this function fills that
- * gap so that invite share links can be generated.
+ * When the bot token was configured via the `assistant credentials set` CLI
+ * or ingress secret redirect, the `getMe` API call that populates the config
+ * is skipped — this function fills that gap so that invite share links can be
+ * generated.
  */
 export async function ensureTelegramBotUsernameResolved(): Promise<void> {
   if (getTelegramBotUsername() && getTelegramBotId()) {

package/src/runtime/channel-verification-service.ts

@@ -333,7 +333,8 @@ export function getGuardianBinding(
       id: result.channel.id,
       assistantId,
       channel,
-      guardianExternalUserId: result.channel.externalUserId ?? "",
+      guardianExternalUserId:
+        result.channel.externalUserId ?? result.channel.address ?? "",
       guardianDeliveryChatId: result.channel.externalChatId ?? "",
       guardianPrincipalId: result.contact.principalId ?? "",
       status: "active" as const,
@@ -355,11 +356,11 @@ export function getGuardianBinding(
 export function isGuardian(
   assistantId: string,
   channel: string,
-  externalUserId: string,
+  address: string,
 ): boolean {
   const result = findGuardianForChannel(channel);
   if (result) {
-    return result.channel.externalUserId === externalUserId;
+    return result.channel.address.toLowerCase() === address.toLowerCase();
   }
 
   return false;