@vellumai/assistant 0.12.3 → 0.12.4-dev.202609231715.8da971c

package/src/calls/voice-escalation-judge.ts

@@ -9,15 +9,16 @@
  * correct reply need something the front door cannot do from here? A
  * confident yes overrules a front-door answer and hands the turn off.
  *
- * The judge runs only when the `voiceEscalationJudge` call site resolves to
- * the TypeSafe provider. Every other outcome (no such profile, provider
- * error, timeout, unparseable answer) is a "clear" verdict, so the front
- * door's own decision stands exactly as it would without the judge.
+ * The judge uses managed Jev by default when Vellum-managed inference is
+ * available. An explicit TypeSafe call-site override can use a user-owned
+ * connection. Every other outcome (unavailable route, provider error,
+ * timeout, unparseable answer) is a "clear" verdict, so the front door's own
+ * decision stands exactly as it would without the judge.
  */
 
+import { askTypesafeNoul } from "../providers/jev/ask.js";
 import type { Message, Provider } from "../providers/types.js";
 import { safeStringSlice } from "../util/unicode.js";
-import { askTypesafeNoul } from "./typesafe-noul.js";
 
 export const VOICE_ESCALATION_JUDGE_CALL_SITE = "voiceEscalationJudge";
 
@@ -57,7 +58,7 @@ export interface EscalationJudgement {
 }
 
 const ESCALATION_QUESTION =
-  "The voice assistant answering right now has NO tools and no access to the user's accounts, files, messages, calendar, screen, apps, the web, or saved memories. Would a correct reply to what the caller just said require doing something it cannot do from here: taking an action (sending, scheduling, creating, editing, changing, opening, calling), looking up live or current information, or retrieving a personal fact that is not already stated in the recent conversation? Answer yes if the caller is asking for, or agreeing to, any such action, even vaguely or via a short confirmation of an earlier offer. Answer no for conversation, opinions, general knowledge, and questions answerable from the recent conversation.";
+  "The voice assistant answering right now has NO tools and no access to the user's accounts, files, messages, calendar, apps, the web, or saved memories. It can start or refresh screen sharing and inspect shared screen images through built-in call controls. Answer no when the caller only asks to share their screen, look at their screen, or describe what is visible; obtaining a screen view does not require escalation. Requests to click, type, edit, or draw/highlight on the screen still require escalation. Would a correct reply to what the caller just said require doing something it cannot do from here: taking an action (sending, scheduling, creating, editing, changing, opening, calling), looking up live or current information, or retrieving a personal fact that is not already stated in the recent conversation? Answer yes if the caller is asking for, or agreeing to, any such action, even vaguely or via a short confirmation of an earlier offer. Answer no for conversation, opinions, general knowledge, and questions answerable from the recent conversation.";
 
 function textOf(message: Message): string {
   return message.content

package/src/calls/voice-leg-coordinator.ts

@@ -33,7 +33,10 @@ import {
 /** The phrase spoken across the hand-off, as {@link resolveSpokenEscalationBridge} settles it. */
 export type SpokenEscalationBridge = ReturnType<
   typeof resolveSpokenEscalationBridge
->;
+> & {
+  /** The answer path already emitted this text; only flush pending speech. */
+  alreadyReleased?: boolean;
+};
 
 /** The leg that answers for real after the front-door leg handed off. */
 export interface EscalatedLeg {
@@ -169,8 +172,8 @@ export function createFrontDoorLegCoordinator(options: {
   };
 
   const handOff = (
-    cappedBridge: string,
-    opts: { overruled?: boolean } = {},
+    bridgeText: string,
+    opts: { overruled?: boolean; alreadyReleased?: boolean } = {},
   ): void => {
     if (handedOff || !host.isLive()) {
       return;
@@ -182,7 +185,13 @@ export function createFrontDoorLegCoordinator(options: {
     } else {
       host.abortLeg();
     }
-    const bridge = resolveSpokenEscalationBridge(cappedBridge, host.language());
+    const bridge: SpokenEscalationBridge = opts.alreadyReleased
+      ? {
+          spokenBridge: bridgeText,
+          usesFallback: false,
+          alreadyReleased: true,
+        }
+      : resolveSpokenEscalationBridge(bridgeText, host.language());
     host.speakBridge(bridge);
     // The bridge is the turn's spoken acknowledgement: narration keeps its
     // minimum gap from it rather than following it back to back.
@@ -299,6 +308,8 @@ export function createFrontDoorLegCoordinator(options: {
         const step = verdict.finish();
         if (step.kind === "bridge") {
           handOff(step.bridge);
+        } else if (step.kind === "terminal-escalate") {
+          handOff(step.bridge, { alreadyReleased: true });
         }
       }
       return handedOff;

package/src/calls/voice-screen-annotation.ts

@@ -0,0 +1,44 @@
+import { shouldAttachHostProxyForCapability } from "../daemon/host-proxy-preactivation.js";
+import { skillLoadTool } from "../tools/skills/load.js";
+import type { ToolContext } from "../tools/types.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("voice-screen-annotation");
+
+export async function loadVoiceScreenAnnotation(
+  context: ToolContext,
+): Promise<string | null> {
+  if (
+    !shouldAttachHostProxyForCapability(
+      "host_cu_annotate",
+      context.transportInterface,
+      context.sourceActorPrincipalId,
+    )
+  ) {
+    return null;
+  }
+  try {
+    const result = await skillLoadTool.execute(
+      { skill: "screen-annotation" },
+      context,
+      { readOnly: true },
+    );
+    if (result.isError) {
+      log.warn(
+        { conversationId: context.conversationId, error: result.content },
+        "Could not preload screen annotation",
+      );
+      return null;
+    }
+    return [
+      "The user is sharing their screen. skill_load has automatically loaded screen-annotation for this turn. Use its tools through skill_execute when pointing at the shared screen.",
+      result.content,
+    ].join("\n\n");
+  } catch (err) {
+    log.warn(
+      { err, conversationId: context.conversationId },
+      "Could not preload screen annotation",
+    );
+    return null;
+  }
+}

package/src/calls/voice-session-bridge.ts

@@ -32,7 +32,9 @@ import { CONVERSATION_BUSY_MESSAGE } from "../daemon/conversation-messaging.js";
 import type { ModeSessionSourceHandle } from "../daemon/conversation-mode-session.js";
 import { resolveChannelCapabilities } from "../daemon/conversation-runtime-assembly.js";
 import { getOrCreateConversation } from "../daemon/conversation-store.js";
+import { getEffectiveEnabledPluginSet } from "../daemon/conversation-tool-setup.js";
 import { preactivateHostProxySkills } from "../daemon/host-proxy-preactivation.js";
+import { resolveTrustClass } from "../daemon/trust-context.js";
 import type { TrustContext } from "../daemon/trust-context-types.js";
 import {
   newestPersistedSightFrame,
@@ -71,19 +73,21 @@ import {
 import {
   CALL_OPENING_MARKER,
   CALL_VERIFICATION_COMPLETE_MARKER,
-  ESCALATE_VERDICT_TOKEN,
+  ESCALATE_VERDICT_TOKENS,
   HOLD_VERDICT_TOKEN,
   stripInternalSpeechMarkers,
   terminalControlMarkerLength,
 } from "./voice-control-protocol.js";
 import { judgeEscalation } from "./voice-escalation-judge.js";
 import type { VoiceEscalationTarget } from "./voice-escalation-target.js";
+import { loadVoiceScreenAnnotation } from "./voice-screen-annotation.js";
 import {
   createFrontDoorStreamGate,
   escalatedContinuationRule,
   ESCALATION_CONTINUATION_CONTENT,
   frontDoorCapabilityDigest,
   frontDoorDecisionRule,
+  leadingEscalationToken,
   spokenBridgeText,
   type VoiceRoutingLeg,
 } from "./voice-triage-escalate.js";
@@ -452,6 +456,8 @@ export interface VoiceTurnOptions {
    * session reports `macos` for its channel capabilities, iOS included.
    */
   macosDesktopSession?: boolean;
+  /** The desktop client currently shares a surface with this voice session. */
+  screenSharing?: boolean;
   /** Whether this is an inbound call (no outbound task). */
   isInbound: boolean;
   /** The outbound call task, if any. */
@@ -835,30 +841,32 @@ function trimOuterTextEdges(blocks: ContentBlock[]): ContentBlock[] {
  * `ESCALATE_VERDICT_TOKEN` reduces to a single text block holding the
  * capped bridge; empty spoken text means the caller heard only the canned
  * fallback bridge, which is audio-only and never a transcript row, so the
- * caller should delete the row. Stray verdict tokens elsewhere in an
- * answer were never spoken (the live gate strips them) and are stripped
- * from the persisted text to match.
+ * caller should delete the row. A terminal escalation keeps all speech
+ * already released before the verdict. Other stray verdict tokens were
+ * never spoken and are stripped from the persisted text to match.
  */
 export function cutFrontDoorContentAtVerdict(
   blocks: ContentBlock[],
 ): { blocks: ContentBlock[]; spokenText: string } | null {
   const joinedText = joinedTextOfBlocks(blocks);
-  if (joinedText.trimStart().startsWith(ESCALATE_VERDICT_TOKEN)) {
-    const spokenText = spokenBridgeText(joinedText);
+  const spokenText = spokenBridgeText(joinedText);
+  if (
+    spokenText.length > 0 ||
+    leadingEscalationToken(joinedText) !== undefined
+  ) {
     return {
       blocks: spokenText.length > 0 ? [{ type: "text", text: spokenText }] : [],
       spokenText,
     };
   }
   if (
-    !joinedText.includes(ESCALATE_VERDICT_TOKEN) &&
+    !ESCALATE_VERDICT_TOKENS.some((token) => joinedText.includes(token)) &&
     !joinedText.includes(HOLD_VERDICT_TOKEN)
   ) {
     return null;
   }
   const kept = stripMarkersFromBlocks(blocks);
-  const spokenText = joinedTextOfBlocks(kept).trim();
-  return { blocks: kept, spokenText };
+  return { blocks: kept, spokenText: joinedTextOfBlocks(kept).trim() };
 }
 
 // ---------------------------------------------------------------------------
@@ -1806,6 +1814,20 @@ export async function startVoiceTurn(
       ? createFrontDoorStreamGate(opts.unifiedVerdict === true)
       : null;
 
+  const broadcastFrontDoorText = (
+    msg: Extract<AssistantEvent, { type: "assistant_text_delta" }>,
+  ): void => {
+    // Answer text waits for the judge, including text flushed at completion.
+    if (
+      frontDoorStreamGate?.answering &&
+      !escalationJudgeSettled &&
+      hubHold === null
+    ) {
+      hubHold = [];
+    }
+    emitHubEvent(msg);
+  };
+
   /**
    * Broadcast one agent-loop event to hub subscribers, holding a front-door
    * leg's control-plane text back at the boundary rather than emitting it and
@@ -1820,16 +1842,7 @@ export async function startVoiceTurn(
     }
     const released = frontDoorStreamGate.push(msg.text);
     if (released.length > 0) {
-      // Answer text while the escalation judge is out: hold it, and every
-      // leg event after it, until the verdict says the caller hears it.
-      if (
-        frontDoorStreamGate.answering &&
-        !escalationJudgeSettled &&
-        hubHold === null
-      ) {
-        hubHold = [];
-      }
-      emitHubEvent({ ...msg, text: released });
+      broadcastFrontDoorText({ ...msg, text: released });
     }
   };
 
@@ -2108,6 +2121,23 @@ export async function startVoiceTurn(
           sourceInterface,
           sourceActorPrincipalId,
         );
+        if (opts.screenSharing === true) {
+          const annotation = await loadVoiceScreenAnnotation({
+            conversationId: opts.conversationId,
+            workingDir: conversation.workingDir,
+            trustClass: resolveTrustClass(opts.trustContext),
+            transportInterface: sourceInterface,
+            clientOs: "macos",
+            enabledPluginSet: getEffectiveEnabledPluginSet(conversation),
+            sourceActorPrincipalId,
+            signal: opts.signal,
+          });
+          if (annotation !== null) {
+            conversation.setVoiceCallControlPrompt(
+              [voiceCallControlPrompt, annotation].filter(Boolean).join("\n\n"),
+            );
+          }
+        }
       }
       await conversation.runAgentLoop(persistedContent, messageId, {
         ...(opts.subagentNotification?.cronRunId
@@ -2128,7 +2158,7 @@ export async function startVoiceTurn(
             // never hands off, and correspondingly never flushes.
             const trailing = frontDoorStreamGate.finish();
             if (trailing.length > 0) {
-              broadcastMessage({
+              broadcastFrontDoorText({
                 type: "assistant_text_delta",
                 text: trailing,
                 ...(reservedAssistantRowId !== null

package/src/calls/voice-triage-escalate.ts

@@ -6,8 +6,8 @@
  *
  *   - `[0]` ({@link HOLD_VERDICT_TOKEN}, unified front-door only): the
  *     caller is mid-thought — the leg is discarded and listening continues.
- *   - `[1]` ({@link ESCALATE_VERDICT_TOKEN}) followed by ONE short natural
- *     holding phrase: the turn is too tricky — the phrase is spoken (capped
+ *   - `[ESCALATE]` ({@link ESCALATE_VERDICT_TOKEN}) followed by ONE short natural
+ *     holding phrase: the turn is too tricky. The phrase is spoken (capped
  *     at a single sentence) while the turn re-runs on the conversation's
  *     own profile, the model the caller's typed turns already run on.
  *     Because the holding phrase is spoken, the caller never hears the
@@ -20,6 +20,9 @@
  * the escalation hand-off: the bridge is capped session-side instead of
  * trusting the model to stop. Every infra failure fails open to a normal
  * committed answer turn.
+ * A standalone terminal `[ESCALATE]` is recovered at normal completion without
+ * delaying answer streaming or repeating the already released speech.
+ * The numeric `[1]` verdict is accepted only at the start of a reply.
  *
  * This module owns the routing policy in one place: the profile key, the
  * leg-specific prompt rules, the leading-token classifier, and the bridge
@@ -32,13 +35,20 @@ import {
   localizedOrDefault,
 } from "../util/language-subtag.js";
 import {
+  createControlMarkerHoldback,
   ESCALATE_VERDICT_TOKEN,
+  ESCALATE_VERDICT_TOKENS,
   HOLD_VERDICT_TOKEN,
   stripInternalSpeechMarkers,
 } from "./voice-control-protocol.js";
 
 export { ESCALATE_VERDICT_TOKEN, HOLD_VERDICT_TOKEN };
 
+export function leadingEscalationToken(text: string): string | undefined {
+  const leading = text.trimStart();
+  return ESCALATE_VERDICT_TOKENS.find((token) => leading.startsWith(token));
+}
+
 // The fast model fronting every turn is pinned by the `voiceFrontDoor` call
 // site (see config/call-site-defaults.ts) — no per-turn profile override.
 // The escalated leg is pinned by the bridge to the conversation's own
@@ -156,7 +166,7 @@ export const BRIDGE_SENTENCE_END_REGEX = new RegExp(
 );
 
 /**
- * Normalize a raw post-`[1]` stream into the bridge that is actually
+ * Normalize the post-verdict stream into the bridge that is actually
  * spoken: internal markers stripped, cut just after the first sentence
  * terminator, hard-capped at {@link MAX_ESCALATION_BRIDGE_CHARS}, trimmed.
  * The session speaks exactly this, the persisted front-door row keeps
@@ -174,7 +184,7 @@ export function capEscalationBridge(rawBridge: string): string {
 }
 
 /**
- * Whether enough of the post-`[1]` stream has arrived to finalize the
+ * Whether enough of the post-verdict stream has arrived to finalize the
  * bridge and hand off: a sentence terminator landed, or the hard cap is
  * reached. Until then the session keeps buffering (the bridge is spoken in
  * one piece at hand-off, so what is spoken is exactly the capped bridge).
@@ -188,24 +198,21 @@ export function isEscalationBridgeComplete(rawBridge: string): boolean {
 }
 
 /**
- * The spoken bridge of a front-door leg's FULL raw output: empty unless the
- * output leads with {@link ESCALATE_VERDICT_TOKEN} (a stray token later in
- * an answer is not an escalation under the verdict-first protocol), else
- * the capped bridge that followed the token. Used by transcript hygiene to
- * reconstruct what the caller heard from a persisted row, by running the
- * same verdict machine the live stream ran through.
+ * The spoken bridge of a front-door leg's full raw output: the capped
+ * phrase following a leading verdict, or the already released speech
+ * before a terminal verdict. Other output has no bridge. Transcript hygiene
+ * replays the same verdict machine to reconstruct what the caller heard.
  */
 export function spokenBridgeText(frontDoorText: string): string {
   const machine = createFrontDoorVerdictMachine(false);
   const step = machine.push(frontDoorText);
-  if (step.kind !== "escalate") {
-    return "";
-  }
-  if (step.bridge !== null) {
+  if (step.kind === "escalate" && step.bridge !== null) {
     return step.bridge;
   }
   const finished = machine.finish();
-  return finished.kind === "bridge" ? finished.bridge : "";
+  return finished.kind === "bridge" || finished.kind === "terminal-escalate"
+    ? finished.bridge
+    : "";
 }
 
 /**
@@ -221,7 +228,8 @@ export function needsFallbackBridge(frontDoorText: string): boolean {
 /**
  * Classification of a front-door leg's accumulated leading output (already
  * `trimStart()`ed). `pending` means the stream could still become a verdict
- * token — keep buffering; everything else is final for the leg.
+ * token: keep buffering. Other results select the leg's streaming path;
+ * a terminal escalation verdict is checked separately at completion.
  */
 export type FrontDoorLeadingVerdict =
   | "pending"
@@ -250,12 +258,12 @@ export function classifyFrontDoorLeading(
   if (holdEnabled && leading.startsWith(HOLD_VERDICT_TOKEN)) {
     return "hold";
   }
-  if (leading.startsWith(ESCALATE_VERDICT_TOKEN)) {
+  if (leadingEscalationToken(leading) !== undefined) {
     return "escalate";
   }
   const candidates = holdEnabled
-    ? [HOLD_VERDICT_TOKEN, ESCALATE_VERDICT_TOKEN]
-    : [ESCALATE_VERDICT_TOKEN];
+    ? [HOLD_VERDICT_TOKEN, ...ESCALATE_VERDICT_TOKENS]
+    : ESCALATE_VERDICT_TOKENS;
   if (candidates.some((token) => token.startsWith(leading))) {
     return "pending";
   }
@@ -287,6 +295,8 @@ export type FrontDoorStep =
   | { readonly kind: "bridging" }
   /** The capped bridge is complete: hand off to the escalated leg. */
   | { readonly kind: "bridge"; readonly bridge: string }
+  /** A terminal verdict hands off using the answer text already released. */
+  | { readonly kind: "terminal-escalate"; readonly bridge: string }
   /** The leg already held, handed off, or finished; nothing more happens. */
   | { readonly kind: "done" };
 
@@ -299,8 +309,9 @@ export type FrontDoorStep =
  *
  * `push` feeds one delta and reports what it decided. `finish` is called
  * when the leg completes normally: a bridge that stopped short of a
- * sentence terminator hands off with what arrived. A leg that is cancelled
- * instead never calls `finish`.
+ * sentence terminator hands off with what arrived. A standalone terminal
+ * escalation token also hands off, using the already released answer as
+ * its bridge. A cancelled leg never calls `finish`.
  */
 export interface FrontDoorVerdictMachine {
   push(deltaText: string): FrontDoorStep;
@@ -359,7 +370,9 @@ export function createFrontDoorVerdictMachine(
         }
         if (verdict === "escalate") {
           stage = "bridging";
-          bridgeRaw = raw.trimStart().slice(ESCALATE_VERDICT_TOKEN.length);
+          bridgeRaw = raw
+            .trimStart()
+            .slice(leadingEscalationToken(raw)!.length);
           return {
             kind: "escalate",
             bridge: isEscalationBridgeComplete(bridgeRaw)
@@ -379,6 +392,17 @@ export function createFrontDoorVerdictMachine(
       if (stage === "bridging") {
         return completeBridge();
       }
+      if (stage === "answer") {
+        stage = "done";
+        const text = raw.trimEnd();
+        const beforeToken = text.slice(0, -ESCALATE_VERDICT_TOKEN.length);
+        if (text.endsWith(ESCALATE_VERDICT_TOKEN) && /\s$/.test(beforeToken)) {
+          return {
+            kind: "terminal-escalate",
+            bridge: stripInternalSpeechMarkers(beforeToken).trim(),
+          };
+        }
+      }
       stage = "done";
       return DONE_STEP;
     },
@@ -419,14 +443,25 @@ export interface FrontDoorStreamGate {
  *   `usesFallbackBridge` in `live-voice-session.ts`) and deletes the row
  *   rather than persisting a phrase the model never really produced, so
  *   there is no displayed text for the gate to agree with.
- * - `answer`: the leg's output IS the reply, so every delta passes through,
- *   including the leading text held back while the verdict was pending.
+ * - `answer`: speech streams immediately, with control markers held back
+ *   and stripped using the same filter as the audio drivers.
  */
 export function createFrontDoorStreamGate(
   holdEnabled: boolean,
 ): FrontDoorStreamGate {
   const machine = createFrontDoorVerdictMachine(holdEnabled);
   let answering = false;
+  let rawSpeech = "";
+  let releasedSpeech = "";
+  const flushSpeech = createControlMarkerHoldback((text) => {
+    releasedSpeech += text;
+  });
+  const filterSpeech = (text: string, force = false): string => {
+    rawSpeech += text;
+    releasedSpeech = "";
+    flushSpeech(rawSpeech, { force });
+    return releasedSpeech;
+  };
   const releasable = (bridge: string): string =>
     bridge.length < MIN_SPOKEN_BRIDGE_CHARS ? "" : bridge;
   const release = (step: FrontDoorStep): string => {
@@ -443,8 +478,8 @@ export function createFrontDoorStreamGate(
     }
   };
   return {
-    push: (deltaText) => release(machine.push(deltaText)),
-    finish: () => release(machine.finish()),
+    push: (deltaText) => filterSpeech(release(machine.push(deltaText))),
+    finish: () => filterSpeech(release(machine.finish()), true),
     get answering() {
       return answering;
     },

package/src/cli/commands/__tests__/plugins.test.ts

@@ -66,6 +66,20 @@ let platformInstallCalls: Array<{ name: string; force?: boolean }> = [];
 let upgradePluginCalls: UpgradePluginOptions[] = [];
 let catalogMatches: PluginSearchMatch[] = [];
 let catalogError: Error | null = null;
+const CATALOG_COMMIT = "a".repeat(40);
+
+function githubCatalogMatch(name: string): PluginSearchMatch {
+  return {
+    name,
+    path: `github:example-org/${name}@${CATALOG_COMMIT}`,
+    category: null,
+    source: {
+      kind: "github",
+      repo: `example-org/${name}`,
+      ref: CATALOG_COMMIT,
+    },
+  };
+}
 
 /**
  * Queued daemon IPC responses. The default (empty queue) is a transport
@@ -269,7 +283,10 @@ beforeEach(() => {
   installPluginCalls = [];
   platformInstallCalls = [];
   upgradePluginCalls = [];
-  catalogMatches = [];
+  catalogMatches = [
+    githubCatalogMatch("example"),
+    githubCatalogMatch("imessage"),
+  ];
   catalogError = null;
   ipcResults = [];
   inspectResult = null;
@@ -485,6 +502,17 @@ describe("plugins install - declared-schedules consent", () => {
     ]);
     expect(r.exitCode).toBe(0);
   });
+
+  test("does not use the outage fallback for a gated integration", async () => {
+    catalogError = new Error("catalog unavailable");
+
+    const r = await runCommand(["plugins", "install", "gamma"]);
+
+    expect(installPluginCalls).toHaveLength(0);
+    expect(platformInstallCalls).toHaveLength(0);
+    expect(r.stderr).toContain("not in the marketplace catalog");
+    expect(r.exitCode).toBe(1);
+  });
 });
 
 describe("plugins upgrade - declared-schedules consent (local fallback)", () => {

package/src/cli/commands/channel-verification-sessions.help.ts

@@ -44,7 +44,11 @@ Examples:
           description:
             "Destination address for outbound verification (handle, phone number, user ID, or email address)",
         },
-        { flags: "--rebind", description: "Replace existing guardian binding" },
+        {
+          flags: "--rebind",
+          description:
+            "Create a code although the channel already has a guardian (see below)",
+        },
         {
           flags: "--conversation-id <conversationId>",
           description: "Conversation ID for inbound challenges",
@@ -74,7 +78,13 @@ Routes between three creation modes based on the provided options:
   2. Outbound: --channel <ch> --destination <dest>
      Sends a verification code to the given destination. Supports telegram
      (handle or chat ID), phone (E.164 number), slack and discord (user ID),
-     and email. Use --rebind to replace an existing guardian binding.
+     and email.
+
+--rebind creates a code although the channel already has a guardian. On
+telegram, slack, discord and email, only the account already bound can redeem
+that code, which is how the same guardian verifies again. A code never moves
+the guardian to a different account there: run "revoke" first, then create
+without --rebind. On phone, an outbound code replaces the bound number.
 
   3. Inbound: --channel <ch> (no --destination)
      Generates a challenge secret for the guardian to send back on the

package/src/cli/commands/oauth/index.help.ts

@@ -804,7 +804,8 @@ Examples:
   $ assistant oauth request --provider google https://www.googleapis.com/calendar/v3/calendars/primary/events
   $ assistant oauth request --provider slack -H "Content-Type: application/json" -d '{"channel":"C123"}' /api/chat.postMessage --json
   $ assistant oauth request --provider google -X POST -H "Content-Type: multipart/related; boundary=b" -d @upload.txt "https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart"
-  $ assistant oauth request --provider google -X POST -H "Content-Type: application/pdf" -d @report.pdf "https://www.googleapis.com/upload/drive/v3/files?uploadType=media"`,
+  $ assistant oauth request --provider google -X POST -H "Content-Type: application/pdf" -d @report.pdf "https://www.googleapis.com/upload/drive/v3/files?uploadType=media"
+  $ assistant oauth request --provider google -X POST -H "Content-Type: message/rfc822" -d @draft.eml "https://www.googleapis.com/upload/gmail/v1/users/me/drafts?uploadType=media"`,
     },
     {
       name: "disconnect",
@@ -929,9 +930,14 @@ Requests with unsupported headers, including If-Match and Idempotency-Key,
 are rejected before calling the provider. A connection using your own OAuth
 app can preserve those headers.
 
+The printed base URL is a path prefix. Concatenating a provider path onto it
+works, and so does a host-absolute path such as /upload/gmail/... or
+/v1/charges: the gateway remaps that request onto the grant's prefix.
+
 Examples:
   $ assistant oauth proxy-url stripe_link
-  $ eval "$(assistant oauth proxy-url stripe_link --export)" && LINK_API_BASE_URL="$VELLUM_OAUTH_PROXY_BASE_URL" LINK_ACCESS_TOKEN="$VELLUM_OAUTH_PROXY_TOKEN" LINK_NO_REFRESH=1 link-cli payment-methods list --format json`,
+  $ eval "$(assistant oauth proxy-url stripe_link --export)" && LINK_API_BASE_URL="$VELLUM_OAUTH_PROXY_BASE_URL" LINK_ACCESS_TOKEN="$VELLUM_OAUTH_PROXY_TOKEN" LINK_NO_REFRESH=1 link-cli payment-methods list --format json
+  $ eval "$(assistant oauth proxy-url google --export)" && curl -X POST -H "Authorization: Bearer $VELLUM_OAUTH_PROXY_TOKEN" -H "Content-Type: message/rfc822" --data-binary @draft.eml "$VELLUM_OAUTH_PROXY_BASE_URL/upload/gmail/v1/users/me/drafts?uploadType=media"`,
     },
   ],
 };

package/src/cli/commands/oauth/request.test.ts

@@ -309,6 +309,38 @@ describe("oauth request body encoding", () => {
       },
     ]);
   });
+
+  test("forwards a Gmail rfc822 draft upload URL and body", async () => {
+    const rfc822 =
+      "From: user@example.com\r\nTo: user@example.com\r\nSubject: Draft\r\n\r\nHello\r\n";
+    const { exitCode } = await runRequestCommand([
+      "--provider",
+      "google",
+      "-s",
+      "-X",
+      "POST",
+      "-H",
+      "Content-Type: message/rfc822",
+      "-d",
+      rfc822,
+      "https://www.googleapis.com/upload/gmail/v1/users/me/drafts?uploadType=media",
+    ]);
+
+    expect(exitCode).toBe(0);
+    expect(handleRequestCalls).toEqual([
+      {
+        body: {
+          provider: "google",
+          url: "https://www.googleapis.com/upload/gmail/v1/users/me/drafts?uploadType=media",
+          method: "POST",
+          headers: {
+            "Content-Type": "message/rfc822",
+          },
+          parsed_data: rfc822,
+        },
+      },
+    ]);
+  });
 });
 
 describe("oauth request body output", () => {

package/src/cli/commands/platform/index.help.ts

@@ -55,7 +55,8 @@ Fields:
   isPlatform          Whether IS_PLATFORM is set (boolean)
   baseUrl             VELLUM_PLATFORM_URL — the platform gateway base URL
   assistantId         This assistant's platform UUID
-  hasAssistantApiKey  Whether a stored assistant API key is available
+  hasAssistantApiKey  Whether a stored assistant API key is available; null
+                      when the credential store could not be read
   hasWebhookSecret    Whether a stored webhook secret is available (needed
                       for email and other inbound webhook channels)
   available           Whether callback registration prerequisites are satisfied

package/src/cli/commands/platform/index.ts

@@ -24,7 +24,7 @@ interface PlatformStatusResult {
   isPlatform: boolean;
   baseUrl: string;
   assistantId: string;
-  hasAssistantApiKey: boolean;
+  hasAssistantApiKey: boolean | null;
   hasWebhookSecret: boolean;
   available: boolean;
   organizationId: string | null;
@@ -95,7 +95,13 @@ export function registerPlatformCommand(program: Command): void {
             log.info(`Base URL: ${result.baseUrl || "(not set)"}`);
             log.info(`Assistant ID: ${result.assistantId || "(not set)"}`);
             log.info(
-              `Assistant API key: ${result.hasAssistantApiKey ? "set" : "not set"}`,
+              `Assistant API key: ${
+                result.hasAssistantApiKey === null
+                  ? "unknown (credential store unreachable)"
+                  : result.hasAssistantApiKey
+                    ? "set"
+                    : "not set"
+              }`,
             );
             log.info(
               `Webhook secret: ${result.hasWebhookSecret ? "set" : "not set (run ensure-registration to provision)"}`,