@vellumai/assistant 0.9.0 → 0.10.0-staging.2

package/src/runtime/agent-wake.ts

@@ -58,6 +58,7 @@ import { resolveEffectiveContextWindow } from "../config/llm-context-resolution.
 import { getConfig } from "../config/loader.js";
 import type { LLMCallSite } from "../config/schemas/llm.js";
 import type { Conversation } from "../daemon/conversation.js";
+import { recordUsage } from "../daemon/conversation-usage.js";
 import { getDiskPressureStatus } from "../daemon/disk-pressure-guard.js";
 import {
   classifyDiskPressureTurnPolicy,
@@ -195,6 +196,14 @@ export interface WakeOptions {
    * retrospectives whose conversation title already says "(Retrospective)").
    */
   suppressWakeSurface?: boolean;
+  /**
+   * Run the wake's turn as non-interactive (no client present). Threads to the
+   * agent loop's `isNonInteractive`, which gates the `<non_interactive_context>`
+   * and `<background_turn>` injectors. Fork-based memory retrospectives set this
+   * to the source conversation's background-turn state so the fork reproduces
+   * the source's injected turn block (prompt-cache prefix parity). Default false.
+   */
+  isNonInteractive?: boolean;
   /**
    * Optional exact tool allowlist for this wake. Used by internal maintenance
    * jobs that need the assistant's judgment but must not execute arbitrary
@@ -587,6 +596,7 @@ export async function wakeAgentForOpportunity(
       opts.forceOverrideProfile ??
       getConversationOverrideProfile(conversationId);
     const callSite = opts.callSite ?? "mainAgent";
+    const isNonInteractive = opts.isNonInteractive ?? false;
     const config = getConfig();
     const effectiveContextWindow = resolveEffectiveContextWindow({
       llm: config.llm,
@@ -784,6 +794,47 @@ export async function wakeAgentForOpportunity(
       if (event.type === "compaction_completed") {
         recordCompactionEndBestEffort(conversationId, event);
       }
+      // Normal user turns record usage via the `dispatchAgentEvent` event handler)
+      // Wakes run their own onEvent and bypass it, so record here.
+      if (event.type === "usage") {
+        try {
+          recordUsage(
+            {
+              conversationId,
+              providerName: event.actualProvider ?? conversation.provider.name,
+              usageStats: conversation.usageStats,
+            },
+            event.inputTokens,
+            event.outputTokens,
+            event.model,
+            () => {},
+            "main_agent",
+            `wake:${source}`,
+            event.cacheCreationInputTokens ?? 0,
+            event.cacheReadInputTokens ?? 0,
+            event.rawResponse,
+            1,
+            undefined,
+            // Mirror the profile state the request actually ran under:
+            // `forceOverrideProfile` floats the override above the call-site
+            // profile (fork retrospectives with matchConversationProfile), and
+            // the conversation-id seed resolves the same mix arm the dispatch
+            // path chose. Without these, attribution credits the call-site
+            // profile/arm instead of the one that ran.
+            {
+              callSite,
+              overrideProfile: overrideProfile ?? null,
+              forceOverrideProfile,
+              selectionSeed: conversationId,
+            },
+          );
+        } catch (err) {
+          log.warn(
+            { conversationId, source, err },
+            "agent-wake: usage recording failed (non-fatal)",
+          );
+        }
+      }
       // Replicates the recordRequestLog side-effect in `handleUsage` because
       // wakes own their own onEvent and never reach `dispatchAgentEvent`.
       // Defer persistence while buffering — see `pendingLogs` above.
@@ -1080,6 +1131,7 @@ export async function wakeAgentForOpportunity(
           trust: wakeTrust,
           overrideProfile,
           forceOverrideProfile,
+          isNonInteractive,
           // The wake's compaction lives in the pre-run gate above
           // (`conversation.maybeCompact()`), never in the loop: the in-loop
           // budget gate and overflow-recovery ladder stay disabled because

package/src/runtime/assistant-event-hub.ts

@@ -40,6 +40,7 @@ export function capabilityForMessageType(
   return HOST_PREFIX_TO_CAPABILITY[stem];
 }
 import { appendEventToStream } from "../signals/event-stream.js";
+import { IntegrityError } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
 import type { AssistantEvent } from "./assistant-event.js";
 import { buildAssistantEvent } from "./assistant-event.js";
@@ -757,9 +758,22 @@ async function createCanonicalRequestForConfirmation(
       });
     }
   } catch (err) {
-    log.debug(
-      { err, conversationId },
-      "Failed to create canonical request from broadcast",
-    );
+    if (err instanceof IntegrityError) {
+      // The confirmation could not be promoted to a canonical guardian request
+      // (e.g. its trust context resolved no guardianPrincipalId). Channel
+      // guardian decisions — reactions, buttons, and text — all route through
+      // the canonical pipeline, so without this record none of them can resolve
+      // the confirmation. Surface it rather than swallowing: for a guardian's
+      // own confirmation a bound principal should always be present.
+      log.warn(
+        { err, conversationId, requestId: msg.requestId },
+        "Could not create canonical guardian request for confirmation; channel guardian decisions will not work for it",
+      );
+    } else {
+      log.debug(
+        { err, conversationId },
+        "Failed to create canonical request from broadcast",
+      );
+    }
   }
 }

package/src/runtime/auth/__tests__/route-policy.test.ts

@@ -210,6 +210,18 @@ describe("ROUTES policy declarations", () => {
     expect(route!.policy!.requiredScopes).toContain("chat.write");
   });
 
+  test("platform/status is readable by browser actors", async () => {
+    const { ROUTES } = await import("../../routes/index.js");
+    const route = ROUTES.find(
+      (r) => r.endpoint === "platform/status" && r.method === "GET",
+    );
+    expect(route).toBeDefined();
+    expect(route!.policy).not.toBeNull();
+    expect(route!.policy!.allowedPrincipalTypes).toContain("actor");
+    expect(route!.policy!.allowedPrincipalTypes).toContain("local");
+    expect(route!.policy!.requiredScopes).toContain("settings.read");
+  });
+
   test("confirm declares an approval-write policy", async () => {
     const { ROUTES } = await import("../../routes/index.js");
     const route = ROUTES.find((r) => r.endpoint === "confirm");

package/src/runtime/auth/require-bound-guardian.ts

@@ -27,10 +27,7 @@ export function requireBoundGuardian(
     // No guardian yet — in pre-bootstrap state, allow through
     return null;
   }
-  if (
-    (guardianResult.channel.externalUserId ??
-      guardianResult.contact.principalId) !== authContext.actorPrincipalId
-  ) {
+  if (guardianResult.channel.address !== authContext.actorPrincipalId) {
     return httpError(
       "FORBIDDEN",
       "Actor is not the bound guardian for this channel",

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/capabilities.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, test } from "bun:test";
+
+import type { TrustClass } from "./actor-trust-resolver.js";
+import { type CapabilitySet, resolveCapabilities } from "./capabilities.js";
+
+/**
+ * The capability matrix — the single source of truth for what each trust class
+ * may do. If a call site's behavior changes during migration, it changes here
+ * (reviewed in one diff) instead of across the ~40 inline conditionals.
+ */
+const MATRIX: Record<TrustClass, CapabilitySet> = {
+  guardian: {
+    canSelfApproveTools: true,
+    sensitiveToolApproval: "self",
+    canManageSchedules: true,
+    canUseVerificationControlPlane: true,
+    canSelfAuthorizeArchiveBySender: true,
+    canAccessMemory: true,
+    canAccessPrivilegedDocuments: true,
+    canRunUnsandboxedShell: true,
+    mayBeInteractive: true,
+    canActUnderDiskPressureCleanup: true,
+    promptTrustGuidance: "none",
+  },
+  trusted_contact: {
+    canSelfApproveTools: false,
+    sensitiveToolApproval: "escalate-and-wait",
+    canManageSchedules: false,
+    canUseVerificationControlPlane: false,
+    canSelfAuthorizeArchiveBySender: false,
+    canAccessMemory: false,
+    canAccessPrivilegedDocuments: false,
+    canRunUnsandboxedShell: false,
+    mayBeInteractive: true,
+    canActUnderDiskPressureCleanup: false,
+    promptTrustGuidance: "social-engineering-defense",
+  },
+  unverified_contact: {
+    canSelfApproveTools: false,
+    sensitiveToolApproval: "escalate-and-wait",
+    canManageSchedules: false,
+    canUseVerificationControlPlane: false,
+    canSelfAuthorizeArchiveBySender: false,
+    canAccessMemory: false,
+    canAccessPrivilegedDocuments: false,
+    canRunUnsandboxedShell: false,
+    mayBeInteractive: true,
+    canActUnderDiskPressureCleanup: false,
+    promptTrustGuidance: "social-engineering-defense",
+  },
+  unknown: {
+    canSelfApproveTools: false,
+    sensitiveToolApproval: "deny",
+    canManageSchedules: false,
+    canUseVerificationControlPlane: false,
+    canSelfAuthorizeArchiveBySender: false,
+    canAccessMemory: false,
+    canAccessPrivilegedDocuments: false,
+    canRunUnsandboxedShell: false,
+    mayBeInteractive: false,
+    canActUnderDiskPressureCleanup: false,
+    promptTrustGuidance: "stranger-warning",
+  },
+};
+
+describe("resolveCapabilities", () => {
+  for (const trustClass of Object.keys(MATRIX) as TrustClass[]) {
+    test(`resolves the full capability set for "${trustClass}"`, () => {
+      expect(resolveCapabilities(trustClass)).toEqual(MATRIX[trustClass]);
+    });
+  }
+
+  test("undefined fail-closes to the `unknown` capability set", () => {
+    expect(resolveCapabilities(undefined)).toEqual(MATRIX.unknown);
+  });
+
+  test("an unrecognized/legacy string fail-closes to the `unknown` capability set", () => {
+    expect(resolveCapabilities("non_guardian")).toEqual(MATRIX.unknown);
+    expect(resolveCapabilities("some_future_role")).toEqual(MATRIX.unknown);
+  });
+
+  test("inherited Object.prototype keys fail-closed (no prototype read)", () => {
+    for (const key of [
+      "__proto__",
+      "constructor",
+      "toString",
+      "hasOwnProperty",
+    ]) {
+      expect(resolveCapabilities(key)).toEqual(MATRIX.unknown);
+    }
+  });
+
+  test("unverified_contact is byte-for-byte identical to trusted_contact (admission-only distinction)", () => {
+    expect(resolveCapabilities("unverified_contact")).toEqual(
+      resolveCapabilities("trusted_contact"),
+    );
+  });
+
+  test("only guardian self-approves; only guardian/contacts may be interactive", () => {
+    expect(resolveCapabilities("guardian").canSelfApproveTools).toBe(true);
+    expect(resolveCapabilities("trusted_contact").canSelfApproveTools).toBe(
+      false,
+    );
+
+    expect(resolveCapabilities("guardian").mayBeInteractive).toBe(true);
+    expect(resolveCapabilities("trusted_contact").mayBeInteractive).toBe(true);
+    expect(resolveCapabilities("unverified_contact").mayBeInteractive).toBe(
+      true,
+    );
+    expect(resolveCapabilities("unknown").mayBeInteractive).toBe(false);
+  });
+
+  test("sensitive tool approval is graded across the three tiers", () => {
+    expect(resolveCapabilities("guardian").sensitiveToolApproval).toBe("self");
+    expect(resolveCapabilities("trusted_contact").sensitiveToolApproval).toBe(
+      "escalate-and-wait",
+    );
+    expect(resolveCapabilities("unknown").sensitiveToolApproval).toBe("deny");
+  });
+});

package/src/runtime/capabilities.ts

@@ -0,0 +1,197 @@
+/**
+ * Trust capabilities — what an actor may do once admitted.
+ *
+ * Separates *what an actor can do* (capabilities/permissions) from *who the
+ * actor is* (`TrustClass`, their role/level). The ~40+ decision sites
+ * read a named capability instead of re-deriving permissions inline from the
+ * This resolves the class to a named capability set in one place so call sites
+ * read a capability instead of re-deriving it.
+ *
+ * Stateless / derive-on-read: capabilities are derived from the already-resolved
+ * (and already-persisted) `trustClass` at point of use. Nothing here is stored;
+ * `trustClass` remains the persisted field in retry payloads, the journal store,
+ * and conversation CRUD.
+ *
+ * Admission is a SEPARATE axis: `TRUST_CLASS_RANK` vs `ADMISSION_FLOOR`
+ * ("who gets in the door") is intentionally not modeled here. `CapabilitySet`
+ * is the "what they may do once inside" axis.
+ *
+ * Context-dependent decisions (interactivity routing, self-approval races,
+ * channel-specific overrides) COMPOSE these primitives with runtime context.
+ * They are not encoded in the table; named composition helpers live in
+ * `effective-capabilities.ts` (and `resolveRoutingState` in
+ * `trust-context-resolver.ts`).
+ */
+
+import type { TrustClass } from "./actor-trust-resolver.js";
+
+/**
+ * Outcome when an actor invokes a tool that requires guardian approval.
+ * - `self`: the actor self-approves (guardian).
+ * - `escalate-and-wait`: route to the guardian and wait inline for a grant.
+ * - `deny`: fail-closed, no escalation or wait.
+ */
+export type SensitiveToolApproval = "self" | "escalate-and-wait" | "deny";
+
+/**
+ * Which trust-guidance block to inject into the model prompt. The capability
+ * layer owns the *selector*; the prompt layer owns the copy for each value.
+ */
+export type PromptTrustGuidance =
+  | "none"
+  | "social-engineering-defense"
+  | "stranger-warning";
+
+/**
+ * What an actor may do once admitted, derived purely from their trust class.
+ */
+export interface CapabilitySet {
+  // --- Tool approval mechanism ---
+  /**
+   * Auto-approves *ordinary* tool calls (e.g. background/platform-hosted bash)
+   * and honors the actor's own pending-confirmation callback. The
+   * sensitive/guardian-required tool path is governed separately by
+   * `sensitiveToolApproval`; the two are independent levers.
+   */
+  canSelfApproveTools: boolean;
+  /** Outcome when a guardian-approval-required (sensitive) tool is invoked. */
+  sensitiveToolApproval: SensitiveToolApproval;
+
+  // --- Privileged tool gates ---
+  /** May create/update schedules. */
+  canManageSchedules: boolean;
+  /** May use verification control-plane tools. */
+  canUseVerificationControlPlane: boolean;
+  /**
+   * May treat its own `user_approved` flag as sufficient authorization to
+   * archive-by-sender. Non-guardians can still archive by sender, but must be
+   * authorized via surface action, task, or explicit prompt approval instead.
+   */
+  canSelfAuthorizeArchiveBySender: boolean;
+
+  // --- Data & memory ---
+  /**
+   * May access long-term / cross-conversation memory — both the memory *tools*
+   * (recall, auto-analysis, retrospection, graph extraction) and *visibility*
+   * of cross-conversation history in assembled context. Untrusted actors are
+   * walled off from both.
+   */
+  canAccessMemory: boolean;
+  /**
+   * May perform privileged (non-conversation-scoped) document operations from
+   * trust class alone. The effective decision also honors privileged channels —
+   * see `canActOnPrivilegedDocuments` in `effective-capabilities.ts`.
+   */
+  canAccessPrivilegedDocuments: boolean;
+
+  // --- Execution environment ---
+  /**
+   * May run the shell WITHOUT the untrusted sandbox / CES lockdown (no
+   * `VELLUM_UNTRUSTED_SHELL`, no credential-secrecy confinement).
+   */
+  canRunUnsandboxedShell: boolean;
+
+  // --- Interactivity & resource ---
+  /**
+   * Trust class alone permits interactive guardian-approval waits. Composed
+   * downstream with `guardianRouteResolvable` to derive `promptWaitingAllowed`
+   * (see `resolveRoutingState`).
+   */
+  mayBeInteractive: boolean;
+  /** May trigger cleanup-mode operations under disk pressure. */
+  canActUnderDiskPressureCleanup: boolean;
+
+  // --- Prompt shaping ---
+  /** Which trust-guidance block to inject into the model prompt. */
+  promptTrustGuidance: PromptTrustGuidance;
+}
+
+/**
+ * Guardian: full control-plane access, self-approves tools.
+ */
+const GUARDIAN_CAPABILITIES: CapabilitySet = {
+  canSelfApproveTools: true,
+  sensitiveToolApproval: "self",
+  canManageSchedules: true,
+  canUseVerificationControlPlane: true,
+  canSelfAuthorizeArchiveBySender: true,
+  canAccessMemory: true,
+  canAccessPrivilegedDocuments: true,
+  canRunUnsandboxedShell: true,
+  mayBeInteractive: true,
+  canActUnderDiskPressureCleanup: true,
+  promptTrustGuidance: "none",
+};
+
+/**
+ * Trusted / unverified contacts: may invoke tools but escalate sensitive ones
+ * to the guardian; no privileged data access; sandboxed execution.
+ *
+ * `trusted_contact` and `unverified_contact` are deliberately identical here —
+ * the distinction is admission-only (see `actor-trust-resolver.ts`). The matrix
+ * test pins this invariant.
+ */
+const CONTACT_CAPABILITIES: CapabilitySet = {
+  canSelfApproveTools: false,
+  sensitiveToolApproval: "escalate-and-wait",
+  canManageSchedules: false,
+  canUseVerificationControlPlane: false,
+  canSelfAuthorizeArchiveBySender: false,
+  canAccessMemory: false,
+  canAccessPrivilegedDocuments: false,
+  canRunUnsandboxedShell: false,
+  mayBeInteractive: true,
+  canActUnderDiskPressureCleanup: false,
+  promptTrustGuidance: "social-engineering-defense",
+};
+
+/**
+ * Unknown actors: fail-closed. No escalation, no interactivity, treated as a
+ * potential stranger in the prompt.
+ */
+const UNKNOWN_CAPABILITIES: CapabilitySet = {
+  canSelfApproveTools: false,
+  sensitiveToolApproval: "deny",
+  canManageSchedules: false,
+  canUseVerificationControlPlane: false,
+  canSelfAuthorizeArchiveBySender: false,
+  canAccessMemory: false,
+  canAccessPrivilegedDocuments: false,
+  canRunUnsandboxedShell: false,
+  mayBeInteractive: false,
+  canActUnderDiskPressureCleanup: false,
+  promptTrustGuidance: "stranger-warning",
+};
+
+const CAPABILITIES_BY_CLASS: Record<TrustClass, CapabilitySet> = {
+  guardian: GUARDIAN_CAPABILITIES,
+  trusted_contact: CONTACT_CAPABILITIES,
+  unverified_contact: CONTACT_CAPABILITIES,
+  unknown: UNKNOWN_CAPABILITIES,
+};
+
+/**
+ * Resolve the capability set for a trust class. Pure and stateless.
+ *
+ * This is the single fail-closed trust boundary: any value that is not a
+ * recognized `TrustClass` — including `undefined` and legacy/persisted strings
+ * (e.g. `"non_guardian"`) — resolves to the `unknown` capability set. Callers
+ * pass their raw trust value directly; they never re-derive "is this a known
+ * class?" at the call site. The `(string & {})` member keeps autocomplete for
+ * the known classes while still accepting an arbitrary string.
+ *
+ * The lookup uses an own-property check so raw values that name inherited
+ * members (`"__proto__"`, `"constructor"`, `"toString"`) fail closed to the
+ * `unknown` set rather than reading off `Object.prototype`.
+ */
+export function resolveCapabilities(
+  trustClass: TrustClass | (string & {}) | undefined,
+): CapabilitySet {
+  if (
+    trustClass != null &&
+    Object.prototype.hasOwnProperty.call(CAPABILITIES_BY_CLASS, trustClass)
+  ) {
+    return CAPABILITIES_BY_CLASS[trustClass as TrustClass];
+  }
+  return UNKNOWN_CAPABILITIES;
+}

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

@@ -1,27 +1,35 @@
 /**
  * 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";
 
+export type {
+  ApprovalActionOption,
+  ApprovalUIMetadata,
+  PermissionRequestDetails,
+} from "@vellumai/gateway-client";
+// Re-export shared wire types + schemas so existing daemon imports keep working.
+export {
+  ApprovalUIMetadataSchema,
+  PermissionRequestDetailsSchema,
+} 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 +40,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 +60,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-retry-sweep.ts

@@ -52,6 +52,7 @@ function parseTrustRuntimeContext(value: unknown): TrustContext | undefined {
   if (
     trustClass !== "guardian" &&
     trustClass !== "trusted_contact" &&
+    trustClass !== "unverified_contact" &&
     trustClass !== "unknown"
   ) {
     return undefined;

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

@@ -333,7 +333,7 @@ export function getGuardianBinding(
       id: result.channel.id,
       assistantId,
       channel,
-      guardianExternalUserId: result.channel.externalUserId ?? "",
+      guardianExternalUserId: result.channel.address,
       guardianDeliveryChatId: result.channel.externalChatId ?? "",
       guardianPrincipalId: result.contact.principalId ?? "",
       status: "active" as const,
@@ -355,11 +355,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;

package/src/runtime/client-health.ts

@@ -0,0 +1,26 @@
+/**
+ * Health heuristics for connected SSE clients.
+ */
+
+/** Keep-alive comment sent to idle clients every 7 s by default. */
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 7_000;
+
+/**
+ * Whether a client looks degraded: its last heartbeat (`lastActiveAt`) is
+ * stale by more than two heartbeat intervals. This surfaces a
+ * registered-but-not-heartbeating connection — the symptom of a flapping
+ * extension SSE stream — whether it never heartbeated or heartbeated and
+ * then froze. A healthy client (fresh or actively heartbeating) has a
+ * recent `lastActiveAt` and is not flagged.
+ *
+ * Limitation: a just-reconnected flapping client has a fresh
+ * `lastActiveAt` and looks healthy in a single snapshot — this is
+ * best-effort visibility, not a liveness guarantee.
+ */
+export function isClientDegraded(
+  lastActiveAt: Date,
+  now: Date,
+  heartbeatIntervalMs: number,
+): boolean {
+  return now.getTime() - lastActiveAt.getTime() > 2 * heartbeatIntervalMs;
+}