@vellumai/assistant 0.11.2-dev.202608071820.0d9e564 → 0.11.2-dev.202608072015.e50ee9a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.2-dev.202608071820.0d9e564",
+  "version": "0.11.2-dev.202608072015.e50ee9a",
   "license": "MIT",
   "type": "module",
   "exports": {

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

@@ -406,18 +406,6 @@ export interface VoiceTurnHandle {
  * on a live phone call" framing (the session system prompt already
  * provides assistant identity) and guardian context (injected separately).
  */
-/**
- * Steering shared by every voice channel. A sign-in flow opens a browser
- * window mid-call that the caller may be unable to see or complete, whether it
- * is reached through a ui-surface tool or through shell and CLI tools (e.g.
- * `assistant oauth connect`). Tell the model to speak the limitation and defer
- * the flow to text chat instead.
- *
- * This outlives the ui-surface restriction it was written alongside: a
- * live-voice call can now show surfaces, but a browser window handing control
- * to a third party mid-call is a different problem, and one a minimized room
- * does not solve.
- */
 /**
  * How long a live-voice call waits on an approval before deciding it itself.
  *
@@ -428,8 +416,23 @@ export interface VoiceTurnHandle {
  */
 const VOICE_APPROVAL_TIMEOUT_MS = 45_000;
 
-export const VOICE_NO_SETUP_FLOWS_RULE =
-  "Never start account connections, OAuth or sign-in flows, or any other action that opens a browser window or needs the user's screen during this call — not even through shell or CLI tools. If the task needs one, say so briefly and offer to finish it in text chat after the call.";
+/**
+ * Telephony-only steering. A sign-in flow opens a browser window on a screen
+ * the caller does not have in front of them, whether it is reached through a
+ * ui-surface tool or through shell and CLI tools (e.g. `assistant oauth
+ * connect`). Tell the model to speak the limitation and defer the flow to text
+ * chat instead.
+ *
+ * Scoped to the phone because the screen is what decides it. A phone call has
+ * no screen, so the `open_url` signal a CLI tool can reach lands somewhere the
+ * caller will never see, and that signal bus carries no capability or
+ * conversation context, so this rule is the only thing standing in front of it
+ * here. A live-voice call is the opposite case: the user is holding the screen,
+ * and the room minimizes itself to hand it back (see
+ * LIVE_VOICE_SETUP_FLOW_TEACHING).
+ */
+const PHONE_NO_SETUP_FLOWS_RULE =
+  "Never start account connections, OAuth or sign-in flows, or any other action that opens a browser window or needs the user's screen during this call, not even through shell or CLI tools. If the task needs one, say so briefly and offer to finish it in text chat after the call.";
 
 function buildVoiceCallControlPrompt(opts: {
   isInbound: boolean;
@@ -523,7 +526,7 @@ function buildVoiceCallControlPrompt(opts: {
     "9. After the opening greeting turn, treat the Task field as background context only — do not re-execute its instructions on subsequent turns.",
     '10. Do not make up information. If you are unsure, use [ASK_GUARDIAN: your question] to consult your guardian. For tool permission requests, use [ASK_GUARDIAN_APPROVAL: {"question":"...","toolName":"...","input":{...}}].',
     `11. Your text is sent directly to a text-to-speech engine. Never use markdown formatting (asterisks, headers, backticks, links) or emojis in your spoken responses. Write plain conversational text only. Protocol markers like ${opts.isCallerGuardian ? "[END_CALL]" : "[ASK_GUARDIAN: ...] and [END_CALL]"} are not spoken text and should still be used normally.`,
-    `12. ${VOICE_NO_SETUP_FLOWS_RULE}`,
+    `12. ${PHONE_NO_SETUP_FLOWS_RULE}`,
   );
 
   // Triage-and-escalate routing rules. The front-door leg decides and may

package/src/live-voice/__tests__/live-voice-events.test.ts

@@ -4,7 +4,6 @@ import type {
   VoiceTurnCallbacks,
   VoiceTurnOptions,
 } from "../../calls/voice-session-bridge.js";
-import { VOICE_NO_SETUP_FLOWS_RULE } from "../../calls/voice-session-bridge.js";
 import type {
   StreamingTranscriber,
   SttStreamServerEvent,
@@ -254,14 +253,14 @@ describe("LiveVoiceSession archive and metrics events", () => {
       userMessageInterface: "macos",
       assistantMessageInterface: "macos",
       // Pins the full production control prompt for the FRONT-DOOR leg (the
-      // first leg of every routed turn): the speech-first rule (which now
-      // permits a surface, since the room reveals one by itself) and the
-      // shared no-setup-flows rule (no OAuth/browser flows mid-call). The [-1]
-      // room-minimize teaching is deliberately absent — only the escalated
-      // leg learns it (see live-voice-triage-escalate.test.ts).
+      // first leg of every routed turn): the speech-first rule, and nothing
+      // else. This leg is toolless, so both the screen-reveal and setup-flow
+      // teachings are deliberately absent. It has nothing to show and no
+      // connection to run, and its capability digest already routes anything
+      // needing a tool to the escalated leg (see
+      // live-voice-triage-escalate.test.ts).
       voiceControlPrompt:
-        "You are speaking in a local live voice session. Keep replies brief and conversational. Speech is the main channel: say the answer, and do not narrate a surface instead of answering. You can also put something on screen when it genuinely helps (a form, a list to pick from, a progress card for long work); the call overlay minimizes by itself once you finish speaking, so the user sees it without doing anything. Never tell the user you cannot show them something. " +
-        VOICE_NO_SETUP_FLOWS_RULE,
+        "You are speaking in a local live voice session. Keep replies brief and conversational. Speech is the main channel: say the answer, and do not narrate a surface instead of answering. You can also put something on screen when it genuinely helps (a form, a list to pick from, a progress card for long work); the call overlay minimizes by itself once you finish speaking, so the user sees it without doing anything. Never tell the user you cannot show them something. ",
     });
     callbacks?.assistant_text_delta?.(makeTextDelta("Hello there."));
     callbacks?.message_complete?.(makeMessageComplete());

package/src/live-voice/__tests__/live-voice-triage-escalate.test.ts

@@ -190,6 +190,35 @@ describe("live-voice triage-and-escalate routing", () => {
     expect(escalated?.content).toBe(ESCALATION_CONTINUATION_CONTENT);
   });
 
+  test("no leg is told to refuse setup flows, and the escalated leg is told to run them", async () => {
+    const { starter } = scriptedStartVoiceTurn({
+      frontDoor: ["[1] ", "Let me think about that."],
+      escalated: ["The detailed answer is 42."],
+    });
+    const { frames, session } = createHarness(starter);
+
+    await driveTurn(session);
+    await waitFor(() => starter.mock.calls.length >= 2);
+    await waitFor(() => frames.some((frame) => frame.type === "tts_done"));
+
+    const frontDoorPrompt =
+      starter.mock.calls[0]?.[0]?.voiceControlPrompt ?? "";
+    const escalatedPrompt =
+      starter.mock.calls[1]?.[0]?.voiceControlPrompt ?? "";
+    // The phone's no-setup-flows rule must not leak onto a channel that has a
+    // screen: it contradicts the base prompt's "never tell the user you cannot
+    // show them something".
+    expect(frontDoorPrompt).not.toContain("Never start account connections");
+    expect(escalatedPrompt).not.toContain("Never start account connections");
+    expect(frontDoorPrompt).not.toContain("finish it in text chat");
+    expect(escalatedPrompt).not.toContain("finish it in text chat");
+    // The leg that can actually run one is told to.
+    expect(escalatedPrompt).toContain("This includes connecting accounts");
+    // The toolless fast leg is not: a connection is not its to run, and its
+    // capability digest already routes anything needing a tool here.
+    expect(frontDoorPrompt).not.toContain("This includes connecting accounts");
+  });
+
   test("the screen-reveal teaching reaches the escalated leg's prompt but never the front-door leg's", async () => {
     const { starter } = scriptedStartVoiceTurn({
       frontDoor: ["[1] ", "Let me think about that."],

package/src/live-voice/live-voice-session.ts

@@ -17,7 +17,6 @@ import type {
 import {
   getConversationTurnTeardown,
   resolveProcessingWaitMs,
-  VOICE_NO_SETUP_FLOWS_RULE,
   waitForPriorTurnTeardown,
 } from "../calls/voice-session-bridge.js";
 import {
@@ -744,6 +743,20 @@ const LIVE_VOICE_CONTROL_PROMPT_BASE =
 const LIVE_VOICE_SCREEN_REVEAL_TEACHING =
   "The call renders as a full-screen overlay covering the app. Whenever you put something on screen, the overlay minimizes by itself as soon as you finish speaking, and the user is looking at what you made. So speak as if you are showing it to them right now (for example, close with something like: take a look), and never say you cannot show it, that this is a voice call, or that they should check it later. Never emit bracketed markers of any kind. ";
 
+// The setup-flow case, spelled out because it is the one the model gets wrong
+// on its own: connecting an account reads as something a call cannot do, so it
+// declines and offers to do it later in text, which is the exact thing the base
+// prompt above forbids.
+//
+// It can do it. The connect card is a ui surface like any other, so showing it
+// minimizes the room on the same latch (`revealsUiSurface`), and the user is at
+// the screen the browser window opens on. Appended alongside the screen-reveal
+// teaching, to the same legs, for the same reason: the front-door leg is
+// toolless, so a setup flow is not its to run, and its capability digest
+// already tells it to escalate anything needing a tool rather than refuse.
+const LIVE_VOICE_SETUP_FLOW_TEACHING =
+  "This includes connecting accounts. If a task needs an account connected or a sign-in completed, put the connection up on screen and let the user do it now. Do not decline it, and do not defer it to text chat. Say what you are connecting and that it is in front of them. ";
+
 // System-level guidance appended to a barge-in turn's control prompt so the
 // model treats the new utterance as a continuation of the request it was cut
 // off answering, rather than a fresh follow-up. Reaches the model only; it is
@@ -800,21 +813,21 @@ function buildLiveDeliveryNote(request: string, answer: string): string {
   return `The user interrupted you earlier, and in the background you finished ${what}. The call is still live and nobody is speaking, so tell them briefly that it is done and give them the result. Do not re-run any tool calls; the work is already complete, and do not repeat it verbatim if it no longer fits. What you produced was:\n\n${answer}`;
 }
 
-// Assemble a leg's model-facing control prompt: the base live-voice rules,
-// the screen-reveal teaching (withheld from the front-door leg, see
-// LIVE_VOICE_SCREEN_REVEAL_TEACHING), the shared no-setup-flows rule, plus
-// any pending barge-in merge context, completed-continuation context, and/or
-// the announcement instruction. A turn can carry several (a barge-in follow-up
-// that also has a continuation result waiting); the notes are model-only and
-// never render as user bubbles.
+// Assemble a leg's model-facing control prompt: the base live-voice rules, the
+// screen-reveal and setup-flow teaching (both withheld from the front-door leg,
+// see LIVE_VOICE_SCREEN_REVEAL_TEACHING), plus any pending barge-in merge
+// context, completed-continuation context, and/or the announcement instruction.
+// A turn can carry several (a barge-in follow-up that also has a continuation
+// result waiting); the notes are model-only and never render as user bubbles.
 function buildVoiceControlPrompt(
   turn: ActiveAssistantTurn,
   leg: { frontDoor?: boolean },
 ): string {
   let prompt =
     LIVE_VOICE_CONTROL_PROMPT_BASE +
-    (leg.frontDoor === true ? "" : LIVE_VOICE_SCREEN_REVEAL_TEACHING) +
-    VOICE_NO_SETUP_FLOWS_RULE;
+    (leg.frontDoor === true
+      ? ""
+      : LIVE_VOICE_SCREEN_REVEAL_TEACHING + LIVE_VOICE_SETUP_FLOW_TEACHING);
   if (turn.interruptedRequest) {
     prompt = `${prompt}\n\n${buildInterruptionMergeNote(turn.interruptedRequest)}`;
   }

package/src/plugin-api/__tests__/oauth-callback-url-export.test.ts

@@ -0,0 +1,29 @@
+/**
+ * Guards that `resolveOauthCallbackUrl` reaches plugins.
+ *
+ * The shim written into `<workspaceDir>/node_modules/@vellumai/plugin-api`
+ * re-binds whatever `Object.keys()` finds on the plugin-api namespace, so an
+ * export missing from `index.ts` is missing from every installed plugin with
+ * no other signal than a plugin failing to import it.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { PLUGIN_API_EXPORTS } from "../../embedded/plugin-api.js";
+import * as pluginApi from "../index.js";
+
+describe("plugin-api OAuth callback export", () => {
+  test("is exported from the plugin-api surface", () => {
+    expect(typeof pluginApi.resolveOauthCallbackUrl).toEqual("function");
+  });
+
+  test("is carried into the generated shim's binding list", () => {
+    expect(PLUGIN_API_EXPORTS).toContain("resolveOauthCallbackUrl");
+  });
+
+  test("takes no arguments, so a plugin cannot vary the URI", () => {
+    // The value a Client ID Metadata Document publishes and the value the
+    // host later authorizes with have to be the same string.
+    expect(pluginApi.resolveOauthCallbackUrl.length).toEqual(0);
+  });
+});

package/src/plugin-api/index.ts

@@ -180,6 +180,16 @@ export {
 // the same resolution as `webhooks register`, and registers the callback route
 // on the managed branches. The plugin defaults to the one in context.
 export { resolveWebhookUrl, type WebhookUrlOptions } from "./webhook-url.js";
+// Resolve the redirect URI an authorization server should send a user back
+// to after consent. One shared route serves every OAuth flow in the
+// assistant, demultiplexed by OAuth `state`, so this takes no arguments and
+// returns the same URL for every caller and every attempt. A plugin needs it
+// when it publishes something that has to name the redirect URI ahead of the
+// flow, such as a Client ID Metadata Document, whose `redirect_uris` an
+// authorization server matches exactly. Throws when no public ingress is
+// configured and the assistant is not connected to the platform, which is the
+// case where no URL would work.
+export { resolveOauthCallbackUrl } from "../inbound/oauth-callback-url.js";
 // Resolve a provider for a call site (optionally overriding the profile) so a
 // plugin can run inference through the workspace's configured profiles and
 // credentials — managed-proxy or BYOK — without supplying its own API key.