@vellumai/assistant 0.11.2 → 0.11.3-staging.2

package/src/__tests__/helpers/hub-clients.ts

@@ -0,0 +1,42 @@
+/**
+ * Register and tear down client subscribers on an assistant event hub.
+ *
+ * The caller supplies the hub, so this helper holds no runtime import into
+ * `src/` and stays safe for the test preload's import graph.
+ */
+import type { HostProxyCapability, InterfaceId } from "../../channels/types.js";
+import type {
+  AssistantEventHub,
+  DesktopPresenceState,
+} from "../../runtime/assistant-event-hub.js";
+
+export interface RegisterHubClientArgs {
+  hub: AssistantEventHub;
+  clientId: string;
+  interfaceId?: InterfaceId;
+  capabilities?: HostProxyCapability[];
+  actorPrincipalId?: string;
+  /** Reported immediately after subscribing, when supplied. */
+  presence?: DesktopPresenceState;
+}
+
+export function registerHubClient(args: RegisterHubClientArgs): void {
+  const { hub } = args;
+  hub.subscribe({
+    type: "client",
+    clientId: args.clientId,
+    interfaceId: args.interfaceId ?? "macos",
+    capabilities: args.capabilities ?? [],
+    actorPrincipalId: args.actorPrincipalId,
+    callback: () => {},
+  });
+  if (args.presence) {
+    hub.setClientPresence(args.clientId, args.presence);
+  }
+}
+
+export function clearHubClients(hub: AssistantEventHub): void {
+  for (const client of hub.listClients()) {
+    hub.disposeClient(client.clientId);
+  }
+}

package/src/__tests__/helpers/mock-conversation.ts

@@ -0,0 +1,46 @@
+/**
+ * Build a stand-in `Conversation` for tests that exercise functions taking the
+ * live conversation (surface helpers, the tool executor, post-execution
+ * hooks).
+ *
+ * Those functions read a handful of fields off a `Conversation` that has ~150
+ * members, so a test double supplies only what the function under test
+ * touches. `Partial<Conversation>` keeps the literal contextually typed —
+ * field types and callback parameter types are still checked against the real
+ * class, and a renamed or retyped member still breaks the build — while the
+ * single assertion here confines the unavoidable widening to one place
+ * instead of one `as unknown as` per test file.
+ *
+ * The `Conversation` import is type-only, so this helper contributes nothing
+ * to the runtime import graph.
+ */
+
+import type { Conversation } from "../../daemon/conversation.js";
+import type { ChannelCapabilities } from "../../daemon/conversation-runtime-assembly.js";
+
+/**
+ * `TExtra` carries test-only fields a double hangs off the same object
+ * (recorded calls, captured messages) through to the return type, so a caller
+ * can still read `ctx.processMessageCalls` off the result.
+ */
+export function asConversation<TExtra extends object = object>(
+  mock: Partial<Conversation> & TExtra,
+): Conversation & TExtra {
+  return mock as unknown as Conversation & TExtra;
+}
+
+/**
+ * Fill a partial capability set out to a full `ChannelCapabilities`.
+ *
+ * Surface tests care about `channel` and `supportsDynamicUi`; the remaining
+ * required fields are noise at the call site but must be present for the
+ * value to be a real `ChannelCapabilities`. Defaults are the conservative
+ * ones (no dashboard, no voice), so a test that forgets to opt in gets the
+ * restrictive branch rather than a silently permissive one.
+ */
+export function mockChannelCapabilities(
+  caps: Pick<ChannelCapabilities, "channel" | "supportsDynamicUi"> &
+    Partial<ChannelCapabilities>,
+): ChannelCapabilities {
+  return { dashboardCapable: false, supportsVoiceInput: false, ...caps };
+}

package/src/__tests__/helpers/verification-sessions-ipc-sim.ts

@@ -22,6 +22,8 @@
 import { randomBytes, randomUUID } from "node:crypto";
 
 import {
+  bindsSameIdentity,
+  boundIdentity,
   hashVerificationSecret,
   VERIFICATION_SESSIONS_IPC_METHODS,
   type VerificationSessionWire,
@@ -62,10 +64,29 @@ function isInterceptable(s: VerificationSessionWire): boolean {
   return (INTERCEPTABLE_STATUSES as readonly string[]).includes(s.status);
 }
 
-function revokeInterceptable(channel: string): void {
+const OUTBOUND_LIVE_STATUSES = ["pending_bootstrap", "awaiting_response"];
+
+/**
+ * Mirrors the gateway store: an outbound mint supersedes only sessions bound
+ * to the same identity, leaving other actors and inbound challenges alone.
+ * The identity rule itself comes from the shared contract, so this cannot
+ * drift from what the gateway does.
+ */
+function revokeSameActorOutbound(
+  channel: string,
+  params: SimCreateOutboundParams,
+): void {
+  const identity = boundIdentity(params);
+  if (identity === null) {
+    return;
+  }
   const now = Date.now();
   for (const s of sessions.values()) {
-    if (s.channel === channel && isInterceptable(s)) {
+    if (
+      s.channel === channel &&
+      OUTBOUND_LIVE_STATUSES.includes(s.status) &&
+      bindsSameIdentity(boundIdentity(s), identity)
+    ) {
       s.status = "revoked";
       s.updatedAt = now;
     }
@@ -164,7 +185,7 @@ export interface SimCreateOutboundResult {
 export function createOutboundSession(
   params: SimCreateOutboundParams,
 ): SimCreateOutboundResult {
-  revokeInterceptable(params.channel);
+  revokeSameActorOutbound(params.channel, params);
 
   const isUnbound = params.identityBindingStatus === "pending_bootstrap";
   const secret = isUnbound
@@ -220,17 +241,30 @@ export type SimGuardedCreateOutboundResult =
 export function createOutboundSessionGuarded(
   params: SimCreateOutboundParams & {
     requireSourceSessionPending?: string;
-    ifNoneActive?: boolean;
     ifNoneActiveForExternalUserId?: string;
   },
 ): SimGuardedCreateOutboundResult {
   const {
     requireSourceSessionPending,
-    ifNoneActive,
     ifNoneActiveForExternalUserId,
     ...createParams
   } = params;
 
+  if (ifNoneActiveForExternalUserId !== undefined) {
+    // Scoped, like the gateway. Reading the channel's latest and comparing
+    // misses this sender's session whenever somebody else started later.
+    const active = findActiveSession(params.channel, {
+      expectedExternalUserId: ifNoneActiveForExternalUserId,
+    });
+    if (active !== null) {
+      return { conflict: true, reason: "active_session_exists" };
+    }
+  }
+
+  // Claim the named source row. Winning the claim IS the guard, so a second
+  // claim of the same deep-link token conflicts. The identity-scoped revoke
+  // cannot do this: a bootstrap row carries whichever identity was bound onto
+  // it last.
   if (requireSourceSessionPending !== undefined) {
     const source = sessions.get(requireSourceSessionPending);
     if (
@@ -240,20 +274,8 @@ export function createOutboundSessionGuarded(
     ) {
       return { conflict: true, reason: "source_session_not_pending" };
     }
-  }
-
-  if (ifNoneActive && findActiveSession(params.channel) !== null) {
-    return { conflict: true, reason: "active_session_exists" };
-  }
-
-  if (ifNoneActiveForExternalUserId !== undefined) {
-    const active = findActiveSession(params.channel);
-    if (
-      active !== null &&
-      active.expectedExternalUserId === ifNoneActiveForExternalUserId
-    ) {
-      return { conflict: true, reason: "active_session_exists" };
-    }
+    source.status = "revoked";
+    source.updatedAt = Date.now();
   }
 
   return createOutboundSession(createParams);
@@ -309,6 +331,10 @@ export function getPendingSession(
 
 export function findActiveSession(
   channel: string,
+  filter: {
+    expectedExternalUserId?: string;
+    verificationPurpose?: "guardian" | "trusted_contact";
+  } = {},
 ): VerificationSessionWire | null {
   const now = Date.now();
   return (
@@ -318,7 +344,11 @@ export function findActiveSession(
           s.channel === channel &&
           (s.status === "pending_bootstrap" ||
             s.status === "awaiting_response") &&
-          s.expiresAt > now,
+          s.expiresAt > now &&
+          (!filter.expectedExternalUserId ||
+            s.expectedExternalUserId === filter.expectedExternalUserId) &&
+          (!filter.verificationPurpose ||
+            s.verificationPurpose === filter.verificationPurpose),
       )
       .sort(newestFirst)[0] ?? null
   );
@@ -475,50 +505,24 @@ function recordInvalidAttempt(key: string): void {
   rateLimits.set(key, entry);
 }
 
+/**
+ * Mirrors the gateway consume path. Both sides read the shared
+ * `boundIdentity`, so the sim cannot accept a code the real service would
+ * refuse. A session bound to no identity, or not yet finally bound
+ * (`pending_bootstrap`), bypasses the check as it does at the gateway.
+ */
 function checkIdentityMatch(
   session: VerificationSessionWire,
   actorExternalUserId: string,
   actorChatId: string,
 ): boolean {
-  const hasExpectedIdentity =
-    session.expectedExternalUserId != null ||
-    session.expectedChatId != null ||
-    session.expectedPhoneE164 != null;
-  // pending_bootstrap (and unbound inbound) sessions bypass the check.
-  if (!hasExpectedIdentity || session.identityBindingStatus !== "bound") {
+  const identity = boundIdentity(session);
+  if (identity === null || session.identityBindingStatus !== "bound") {
     return true;
   }
-
-  if (
-    session.expectedPhoneE164 != null &&
-    (actorExternalUserId === session.expectedPhoneE164 ||
-      actorExternalUserId === session.expectedExternalUserId)
-  ) {
-    return true;
-  }
-
-  // Shared-chatId caveat: when both expected fields are set, require the
-  // externalUserId match — chat IDs can be shared.
-  if (session.expectedChatId != null) {
-    if (session.expectedExternalUserId != null) {
-      if (actorExternalUserId === session.expectedExternalUserId) {
-        return true;
-      }
-    } else if (actorChatId === session.expectedChatId) {
-      return true;
-    }
-  }
-
-  if (
-    session.expectedPhoneE164 == null &&
-    session.expectedChatId == null &&
-    session.expectedExternalUserId != null &&
-    actorExternalUserId === session.expectedExternalUserId
-  ) {
-    return true;
-  }
-
-  return false;
+  return identity.field === "chatId"
+    ? actorChatId === identity.value
+    : actorExternalUserId === identity.value;
 }
 
 export function validateAndConsumeVerification(

package/src/__tests__/history-repair.test.ts

@@ -572,8 +572,10 @@ describe("repairHistory", () => {
     ).toBe(true);
   });
 
-  test("trailing server_tool_use gets synthetic result in same assistant message", () => {
-    // No trailing user message needed — result goes in the assistant message
+  test("trailing server_tool_use is preserved as a deferred execution", () => {
+    // An unanswered server_tool_use at the tail is a deferred search the
+    // provider executes on the next request; repairing it would cancel the
+    // search.
     const messages: Message[] = [
       { role: "user", content: [{ type: "text", text: "Go" }] },
       {
@@ -591,21 +593,107 @@ describe("repairHistory", () => {
 
     const { messages: repaired, stats } = repairHistory(messages);
 
-    expect(stats.missingToolResultsInserted).toBe(1);
-    // Result is in the assistant message
+    expect(stats.missingToolResultsInserted).toBe(0);
     expect(repaired).toHaveLength(2);
     expect(repaired[1].role).toBe("assistant");
-    expect(repaired[1].content).toHaveLength(2);
-    expect(repaired[1].content[1]).toMatchObject({
-      type: "web_search_tool_result",
-      tool_use_id: "stu_1",
-      content: {
-        type: "web_search_tool_result_error",
-        error_code: "unavailable",
-      },
+    expect(repaired[1].content).toHaveLength(1);
+    expect(repaired[1].content[0]).toMatchObject({
+      type: "server_tool_use",
+      id: "stu_1",
     });
   });
 
+  test("deferred mixed tail (tool_use + server_tool_use, then tool_result) survives a reload untouched", () => {
+    // Persisted mid-deferral shape: the model called a client tool and a
+    // search in one parallel group, the client result came back, and the
+    // daemon reloaded before the next model call ran the search.
+    const messages: Message[] = [
+      { role: "user", content: [{ type: "text", text: "Check both" }] },
+      {
+        role: "assistant",
+        content: [
+          { type: "tool_use", id: "tu_a", name: "file_read", input: {} },
+          {
+            type: "server_tool_use",
+            id: "stu_deferred",
+            name: "web_search",
+            input: { query: "news" },
+          },
+        ],
+      },
+      {
+        role: "user",
+        content: [
+          { type: "tool_result", tool_use_id: "tu_a", content: "file" },
+        ],
+      },
+    ];
+
+    const { messages: repaired, stats } = repairHistory(messages);
+
+    expect(stats.missingToolResultsInserted).toBe(0);
+    expect(stats.orphanToolResultsDowngraded).toBe(0);
+    expect(repaired).toHaveLength(3);
+    expect(repaired[1].content.map((b) => b.type)).toEqual([
+      "tool_use",
+      "server_tool_use",
+    ]);
+  });
+
+  test("cross-message server tool pair from a completed deferred execution survives a reload untouched", () => {
+    const messages: Message[] = [
+      { role: "user", content: [{ type: "text", text: "Check both" }] },
+      {
+        role: "assistant",
+        content: [
+          { type: "tool_use", id: "tu_a", name: "file_read", input: {} },
+          {
+            type: "server_tool_use",
+            id: "stu_split",
+            name: "web_search",
+            input: { query: "news" },
+          },
+        ],
+      },
+      {
+        role: "user",
+        content: [
+          { type: "tool_result", tool_use_id: "tu_a", content: "file" },
+        ],
+      },
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "web_search_tool_result",
+            tool_use_id: "stu_split",
+            content: [
+              {
+                type: "web_search_result",
+                url: "https://example.com",
+                title: "Example",
+              },
+            ],
+          },
+          { type: "text", text: "Found it." },
+        ],
+      },
+    ];
+
+    const { messages: repaired, stats } = repairHistory(messages);
+
+    expect(stats.missingToolResultsInserted).toBe(0);
+    expect(stats.orphanToolResultsDowngraded).toBe(0);
+    expect(repaired[1].content.map((b) => b.type)).toEqual([
+      "tool_use",
+      "server_tool_use",
+    ]);
+    expect(repaired[3].content.map((b) => b.type)).toEqual([
+      "web_search_tool_result",
+      "text",
+    ]);
+  });
+
   test("synthetic web_search_tool_result is placed immediately after its server_tool_use, not at end", () => {
     // Regression: synthetic results appended to the end of the content array
     // get separated from their server_tool_use by ensureToolPairing's split
@@ -648,6 +736,12 @@ describe("repairHistory", () => {
           },
         ],
       },
+      // A later assistant message closes the deferral window: the searches
+      // never executed, so they are genuine orphans.
+      {
+        role: "assistant",
+        content: [{ type: "text", text: "Skill ready." }],
+      },
     ];
 
     const { messages: repaired, stats } = repairHistory(messages);
@@ -866,6 +960,12 @@ describe("repairHistory", () => {
           },
         ],
       },
+      // A later exchange closes the deferral window for stu_missing_result.
+      { role: "user", content: [{ type: "text", text: "and?" }] },
+      {
+        role: "assistant",
+        content: [{ type: "text", text: "done" }],
+      },
     ];
 
     const { messages: repaired, stats } = repairHistory(messages);

package/src/__tests__/host-bash-proxy.test.ts

@@ -742,8 +742,11 @@ describe("HostBashProxy", () => {
   });
 
   describe("same-user binding (sourceActorPrincipalId)", () => {
-    const SAME_USER_REJECTION =
-      "Submitting actor does not match the target client's actor for this request. The targeted client's authenticated user must submit the result.";
+    // The proxy path names which comparison failed, so each rejection asserts
+    // its own reason — a turn with no actor, a client registered without one,
+    // and two genuinely different users are three different problems.
+    const CROSS_USER_REJECTION =
+      "Submitting actor does not match the target client's actor for this request. The target client is signed in as a different user — run `assistant clients list` to see which connected clients you own.";
 
     test("same-user targeted request succeeds", async () => {
       setup();
@@ -784,7 +787,7 @@ describe("HostBashProxy", () => {
       );
 
       expect(result.isError).toBe(true);
-      expect(result.content).toBe(SAME_USER_REJECTION);
+      expect(result.content).toBe(CROSS_USER_REJECTION);
       // No broadcast and no pending registration
       expect(sentMessages).toHaveLength(0);
     });
@@ -807,7 +810,9 @@ describe("HostBashProxy", () => {
       );
 
       expect(result.isError).toBe(true);
-      expect(result.content).toBe(SAME_USER_REJECTION);
+      expect(result.content).toContain(
+        "registered without an authenticated user",
+      );
       expect(sentMessages).toHaveLength(0);
     });
 
@@ -823,7 +828,7 @@ describe("HostBashProxy", () => {
       );
 
       expect(result.isError).toBe(true);
-      expect(result.content).toBe(SAME_USER_REJECTION);
+      expect(result.content).toContain("no authenticated actor");
       expect(sentMessages).toHaveLength(0);
     });
 

package/src/__tests__/host-bash-routes.test.ts

@@ -312,6 +312,73 @@ describe("handleHostBashResult", () => {
     });
   });
 
+  // ── Fill-if-missing: persisted target healed after registration ────
+  //
+  // A request registered while the target's SSE record had no principal
+  // persists `targetActorPrincipalId: undefined`. Once the SSE self-heal
+  // fills the hub record, the result route re-reads the live record,
+  // but ONLY when the persisted value is missing.
+
+  describe("targeted request - missing persisted target principal fills from the live hub record", () => {
+    test("accepts a matching submitter when the hub record was healed after registration", async () => {
+      const requestId = "req-healed-target";
+      // Registered pre-heal: hub had no principal, so nothing was persisted.
+      registerPending(requestId, { targetClientId: "client-abc" });
+      // SSE self-heal fills the hub record afterwards.
+      clientActorPrincipals.set("client-abc", "principal-shared");
+
+      const result = await handleHostBashResult({
+        body: bashBody(requestId),
+        headers: {
+          "x-vellum-client-id": "client-abc",
+          "x-vellum-actor-principal-id": "principal-shared",
+        },
+      });
+
+      expect(result).toEqual({ accepted: true });
+      expect(resolvedIds).toContain(requestId);
+    });
+
+    test("still throws ForbiddenError (403) for a submitter with a different principal than the healed target", () => {
+      const requestId = "req-healed-target-mismatch";
+      registerPending(requestId, { targetClientId: "client-abc" });
+      clientActorPrincipals.set("client-abc", "principal-victim");
+
+      expect(() =>
+        handleHostBashResult({
+          body: bashBody(requestId),
+          headers: {
+            "x-vellum-client-id": "client-abc",
+            "x-vellum-actor-principal-id": "principal-attacker",
+          },
+        }),
+      ).toThrow(ForbiddenError);
+      expect(pendingStore.has(requestId)).toBe(true);
+    });
+
+    test("a present persisted principal always wins over the live hub record", () => {
+      // The fill is missing-only: a persisted value captured at registration
+      // is never overridden, so a submitter matching only the (different)
+      // live record is still rejected.
+      const requestId = "req-persisted-wins";
+      registerPending(requestId, {
+        targetClientId: "client-abc",
+        targetActorPrincipalId: "principal-registration",
+      });
+      clientActorPrincipals.set("client-abc", "principal-live");
+
+      expect(() =>
+        handleHostBashResult({
+          body: bashBody(requestId),
+          headers: {
+            "x-vellum-client-id": "client-abc",
+            "x-vellum-actor-principal-id": "principal-live",
+          },
+        }),
+      ).toThrow(ForbiddenError);
+    });
+  });
+
   // ── Untargeted-request behavior (regression for new check) ─────────
 
   describe("untargeted request — actor principal check is skipped", () => {

package/src/__tests__/host-browser-proxy.test.ts

@@ -867,7 +867,7 @@ describe("HostBrowserProxy", () => {
       );
 
       expect(result.isError).toBe(true);
-      expect(result.content).toContain("Submitting actor does not match");
+      expect(result.content).toContain("signed in as a different user");
       expect(getPublishedMessages()).toHaveLength(0);
     });
 
@@ -1054,7 +1054,7 @@ describe("HostBrowserProxy", () => {
       );
 
       expect(result.isError).toBe(true);
-      expect(result.content).toContain("Submitting actor does not match");
+      expect(result.content).toContain("signed in as a different user");
       expect(result.content).not.toContain("extension_required");
       expect(getPublishedMessages()).toHaveLength(0);
     });

package/src/__tests__/host-cu-proxy.test.ts

@@ -1416,9 +1416,7 @@ describe("HostCuProxy", () => {
       );
 
       expect(result.isError).toBe(true);
-      expect(result.content).toContain(
-        "Submitting actor does not match the target client's actor",
-      );
+      expect(result.content).toContain("signed in as a different user");
       expect(sentMessages).toHaveLength(0);
     });
 
@@ -1444,9 +1442,7 @@ describe("HostCuProxy", () => {
       );
 
       expect(result.isError).toBe(true);
-      expect(result.content).toContain(
-        "Submitting actor does not match the target client's actor",
-      );
+      expect(result.content).toContain("no authenticated actor");
       expect(sentMessages).toHaveLength(0);
     });
 
@@ -1473,7 +1469,7 @@ describe("HostCuProxy", () => {
 
       expect(result.isError).toBe(true);
       expect(result.content).toContain(
-        "Submitting actor does not match the target client's actor",
+        "registered without an authenticated user",
       );
       expect(sentMessages).toHaveLength(0);
     });

package/src/__tests__/host-file-proxy.test.ts

@@ -693,9 +693,7 @@ describe("HostFileProxy", () => {
       );
 
       expect(result.isError).toBe(true);
-      expect(result.content).toContain(
-        "Submitting actor does not match the target client's actor",
-      );
+      expect(result.content).toContain("signed in as a different user");
       // No host_file_request was broadcast.
       expect(sentMessages).toHaveLength(0);
     });
@@ -720,7 +718,7 @@ describe("HostFileProxy", () => {
 
       expect(result.isError).toBe(true);
       expect(result.content).toContain(
-        "Submitting actor does not match the target client's actor",
+        "registered without an authenticated user",
       );
       expect(sentMessages).toHaveLength(0);
     });
@@ -744,9 +742,7 @@ describe("HostFileProxy", () => {
       );
 
       expect(result.isError).toBe(true);
-      expect(result.content).toContain(
-        "Submitting actor does not match the target client's actor",
-      );
+      expect(result.content).toContain("no authenticated actor");
       expect(sentMessages).toHaveLength(0);
     });
 

package/src/__tests__/host-file-read-tool.test.ts

@@ -27,6 +27,7 @@ mock.module("../daemon/host-file-proxy.js", () => ({
 }));
 
 import { hostFileReadTool } from "../tools/host-filesystem/read.js";
+import { DEFAULT_READ_LINE_LIMIT } from "../tools/shared/filesystem/file-ops-service.js";
 import type { ToolContext } from "../tools/types.js";
 
 const testDirs: string[] = [];
@@ -226,13 +227,16 @@ describe("host_file_read image support", () => {
 
     expect(result.isError).toBe(false);
     expect(result.contentBlocks).toHaveLength(1);
+    // The proxied request carries the resolved default window, so a host read
+    // is bounded by the same limit as a local one rather than streaming a
+    // whole file across the bridge.
     expect(requests).toEqual([
       {
         input: {
           operation: "read",
           path: "/host/screenshot.png",
           offset: undefined,
-          limit: undefined,
+          limit: DEFAULT_READ_LINE_LIMIT,
         },
         conversationId: "test-conversation",
         signal: undefined,