@vellumai/assistant 0.12.2 → 0.12.3-staging.1

package/src/mcp/tool-caps.ts

@@ -0,0 +1,176 @@
+/**
+ * Code-owned MCP tool-count caps and the selection used when they bind.
+ *
+ * Caps live here, not in workspace config: migration 153 strips
+ * `maxTools` / `globalMaxTools` from `config.json`. The numbers are a
+ * context-window budget, not a permission gate. Allowlists and risk
+ * still decide what a turn may call.
+ *
+ * The global cap is applied by a deterministic round-robin across
+ * servers sorted by id. Insertion order must not empty a later server
+ * while earlier ones keep every tool.
+ */
+
+import {
+  MCP_GLOBAL_MAX_TOOLS,
+  MCP_MAX_TOOLS_PER_SERVER,
+} from "../config/schemas/mcp.js";
+
+export interface McpServerToolSet<T> {
+  serverId: string;
+  tools: readonly T[];
+}
+
+export interface McpToolCapDecision {
+  serverId: string;
+  discovered: number;
+  kept: number;
+  droppedByPerServerCap: number;
+  droppedByGlobalCap: number;
+}
+
+export interface McpToolCapResult<T> {
+  servers: Array<{ serverId: string; tools: T[] }>;
+  discoveredToolCount: number;
+  keptToolCount: number;
+  droppedToolCount: number;
+  globalCap: number;
+  perServerCap: number;
+  decisions: McpToolCapDecision[];
+}
+
+export function applyMcpToolCaps<T>(
+  servers: ReadonlyArray<McpServerToolSet<T>>,
+  options?: { globalMax?: number; perServerMax?: number },
+): McpToolCapResult<T> {
+  const globalCap = options?.globalMax ?? MCP_GLOBAL_MAX_TOOLS;
+  const perServerCap = options?.perServerMax ?? MCP_MAX_TOOLS_PER_SERVER;
+  const discoveredToolCount = servers.reduce(
+    (sum, server) => sum + server.tools.length,
+    0,
+  );
+
+  const afterPerServer = servers.map((server) => {
+    const droppedByPerServerCap = Math.max(
+      0,
+      server.tools.length - perServerCap,
+    );
+    return {
+      serverId: server.serverId,
+      tools: server.tools.slice(0, perServerCap),
+      discovered: server.tools.length,
+      droppedByPerServerCap,
+    };
+  });
+
+  const afterPerServerCount = afterPerServer.reduce(
+    (sum, server) => sum + server.tools.length,
+    0,
+  );
+  if (afterPerServerCount <= globalCap) {
+    const decisions = afterPerServer.map((server) => ({
+      serverId: server.serverId,
+      discovered: server.discovered,
+      kept: server.tools.length,
+      droppedByPerServerCap: server.droppedByPerServerCap,
+      droppedByGlobalCap: 0,
+    }));
+    return {
+      servers: afterPerServer.map((server) => ({
+        serverId: server.serverId,
+        tools: [...server.tools],
+      })),
+      discoveredToolCount,
+      keptToolCount: afterPerServerCount,
+      droppedToolCount: discoveredToolCount - afterPerServerCount,
+      globalCap,
+      perServerCap,
+      decisions,
+    };
+  }
+
+  const order = [...afterPerServer].sort((a, b) =>
+    a.serverId.localeCompare(b.serverId),
+  );
+  const selected = new Map<string, T[]>(
+    order.map((server) => [server.serverId, []]),
+  );
+  const cursors = new Map<string, number>(
+    order.map((server) => [server.serverId, 0]),
+  );
+  let kept = 0;
+  let progressed = true;
+  while (kept < globalCap && progressed) {
+    progressed = false;
+    for (const server of order) {
+      if (kept >= globalCap) {
+        break;
+      }
+      const cursor = cursors.get(server.serverId) ?? 0;
+      const tool = server.tools[cursor];
+      if (tool !== undefined) {
+        selected.get(server.serverId)?.push(tool);
+        cursors.set(server.serverId, cursor + 1);
+        kept += 1;
+        progressed = true;
+      }
+    }
+  }
+
+  const decisions = afterPerServer.map((server) => {
+    const keptTools = selected.get(server.serverId) ?? [];
+    return {
+      serverId: server.serverId,
+      discovered: server.discovered,
+      kept: keptTools.length,
+      droppedByPerServerCap: server.droppedByPerServerCap,
+      droppedByGlobalCap: server.tools.length - keptTools.length,
+    };
+  });
+
+  return {
+    servers: afterPerServer.map((server) => ({
+      serverId: server.serverId,
+      tools: [...(selected.get(server.serverId) ?? [])],
+    })),
+    discoveredToolCount,
+    keptToolCount: kept,
+    droppedToolCount: discoveredToolCount - kept,
+    globalCap,
+    perServerCap,
+    decisions,
+  };
+}
+
+export interface McpStartupSnapshot {
+  configuredServerCount: number;
+  connectedServerCount: number;
+  discoveredToolCount: number;
+  registeredToolCount: number;
+  droppedToolCount: number;
+  truncatedServerIds: string[];
+  errorServerCount: number;
+  needsAuthServerCount: number;
+}
+
+export const EMPTY_MCP_STARTUP_SNAPSHOT: McpStartupSnapshot = {
+  configuredServerCount: 0,
+  connectedServerCount: 0,
+  discoveredToolCount: 0,
+  registeredToolCount: 0,
+  droppedToolCount: 0,
+  truncatedServerIds: [],
+  errorServerCount: 0,
+  needsAuthServerCount: 0,
+};
+
+export function truncatedServerIdsFromCaps(
+  decisions: readonly McpToolCapDecision[],
+): string[] {
+  return decisions
+    .filter(
+      (decision) =>
+        decision.droppedByPerServerCap > 0 || decision.droppedByGlobalCap > 0,
+    )
+    .map((decision) => decision.serverId);
+}

package/src/messaging/provider-message-metadata.ts

@@ -30,9 +30,9 @@ import { CHANNEL_IDS } from "../channels/types.js";
  * The schema passes through what it does not name, so a provider carries its
  * own fields (Slack's file markers and timezone labels) on this same object
  * and validates them with its own schema. This is how `SourceMetadataSchema`
- * already carries `slackBotMentioned` and the email fields on the wire: one
- * object per row, no per-provider sub-envelope, and no second copy of
- * anything named here.
+ * carries `botMentioned` and the email fields on the wire: one object per
+ * row, no per-provider sub-envelope, and no second copy of anything named
+ * here.
  */
 
 const providerReactionMetadataSchema = z.object({

package/src/notifications/__tests__/copy-composer.test.ts

@@ -503,6 +503,76 @@ describe("composeFallbackCopy plugin schedule templates", () => {
   });
 });
 
+// ── activity.complete rendering ───────────────────────────────────────
+
+describe("activity.complete copy", () => {
+  function completeSignal(
+    contextPayload: Record<string, unknown>,
+  ): NotificationSignal {
+    return makeSignal({
+      sourceEventName: "activity.complete",
+      contextPayload,
+    });
+  }
+
+  test("a producer-authored title survives the fallback path", () => {
+    // The home feed reads the payload title first; the popup must say the
+    // same thing when the classifier was unreachable.
+    const copy = composeFallbackCopy(
+      completeSignal({
+        title: "Skill updated: Weekly Report Export",
+        summary: "Added the retry after an expired session.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.title).toBe("Skill updated: Weekly Report Export");
+    expect(copy.vellum?.body).toBe("Added the retry after an expired session.");
+  });
+
+  test("the pass-through's requestedTitle is honored when no title is set", () => {
+    const copy = composeFallbackCopy(
+      completeSignal({
+        requestedTitle: "Nightly export finished",
+        summary: "Wrote 12 files to the reports folder.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.title).toBe("Nightly export finished");
+  });
+
+  test("without an authored title the headline is the summary's first sentence", () => {
+    const copy = composeFallbackCopy(
+      completeSignal({
+        summary:
+          "Added the retry after an expired session. Dropped the login step.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.title).toBe(
+      "Added the retry after an expired session.",
+    );
+  });
+
+  test("an authored title the normalizer rejects falls back to the derived one", () => {
+    const copy = composeFallbackCopy(
+      completeSignal({
+        title: "Skill\nupdated",
+        summary: "Added the retry after an expired session.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.title).toBe(
+      "Added the retry after an expired session.",
+    );
+  });
+
+  test("neither a title nor a summary still says something happened", () => {
+    const copy = composeFallbackCopy(completeSignal({}), CHANNELS);
+    expect(copy.vellum?.title).toBe("Activity complete");
+    expect(copy.vellum?.body).toBe("An activity has completed");
+  });
+});
+
 // ── deriveTitle ───────────────────────────────────────────────────────
 
 describe("deriveTitle", () => {

package/src/notifications/copy-composer.ts

@@ -346,14 +346,22 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
 
   // Titled by what was done rather than by the kind of event: the summary's
   // first sentence is the outcome ("Finished the fuel-system diagnostic app"),
-  // which is what a reader scanning the bell wants to see. A summary without
-  // one still gets a title that says something happened.
+  // which is what a reader scanning the bell wants to see. A producer that
+  // names its subject in the payload keeps that name here, read in the same
+  // order the home feed reads it, so the headline is the same whether or not
+  // the classifier ran. A summary with neither still gets a title that says
+  // something happened.
   "activity.complete": (payload) => {
     const summary = nonEmpty(
       typeof payload.summary === "string" ? payload.summary : undefined,
     );
+    const authored = normalizeTitle(
+      readPayloadString(payload, "title") ??
+        readPayloadString(payload, "requestedTitle") ??
+        "",
+    );
     return {
-      title: summary ? deriveTitle(summary) : "Activity complete",
+      title: authored || (summary ? deriveTitle(summary) : "Activity complete"),
       body: summary ?? "An activity has completed",
     };
   },

package/src/notifications/schedule-result-producer.ts

@@ -103,12 +103,10 @@ export interface ScheduleResultNotificationParams {
  * conversation can come back too and are harmless, because only this run's
  * own call ids are matched.
  *
- * A Slack Web API post through bash is deliberately not a route, because its
- * success proves nothing about the post. Slack refuses a call with HTTP 200
- * and `ok: false` in the body, and the authenticated-request command fails
- * only on a non-2xx status, so a post Slack refused still leaves a successful
- * tool result. A run that posts that way gets the fallback too: at worst a
- * duplicate, never a silence.
+ * A Slack Web API post through bash is deliberately not a route. It is off
+ * the guided path and unrecorded, and recognizing it would mean reading a
+ * shell command for a method name. A run that posts that way gets the
+ * fallback too: at worst a duplicate, never a silence.
  */
 function deliveredThroughMessagingTool(
   conversationId: string,

package/src/oauth/AGENTS.md

@@ -10,6 +10,8 @@ Add an entry to `PROVIDER_SEED_DATA`. Required fields: `provider`, `authorizeUrl
 
 `injectionTemplates` is also a security boundary, not only an injection rule. `assistant oauth request` and `assistant channels request` accept an absolute URL only when its host matches one of the entry's `hostPattern` values (`assertOAuthRequestUrlAllowed` in `../runtime/routes/oauth-commands-routes.ts`), so that list is the full set of hosts the credential may be sent to. A pattern matches exactly unless it starts with `*.`; reserve the wildcard for per-tenant hosts that cannot be enumerated (`*.salesforce.com`), and name a fixed host the provider documents (`files.slack.com`) by name. The guard sees only the URL the caller passes: the connection follows a redirect itself, and a cross-origin hop carries no `Authorization`, so a redirect target never receives the credential and never needs listing.
 
+`responseOkField` declares the boolean a provider's API puts in every response body to report success (Slack: `ok`), and it is read in one place, `providerReportsFailure` in `identity-verifier.ts`. It is not `identityOkField`, which governs only the identity call and stays the documented `--identity-ok-field` contract. Both request doors and `oauth ping` treat an explicit `false` under a 2xx as a failed call, since such a provider hides refusals behind a successful status; a body without the field leaves the status as the verdict. Declare it on every row that calls such an API, the bot row included.
+
 If the provider will support managed mode, set `managedServiceConfigKey` to a slug matching the key you will add to `ServicesSchema` (e.g. `"acme-oauth"`).
 
 ### 2. _(managed only)_ Add a service schema — `../config/schemas/services.ts`

package/src/oauth/__tests__/identity-verifier.test.ts

@@ -1,6 +1,9 @@
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
-import { verifyIdentity } from "../identity-verifier.js";
+import {
+  providerReportsFailure,
+  verifyIdentity,
+} from "../identity-verifier.js";
 import type { OAuthProviderRow } from "../oauth-store.js";
 
 // ---------------------------------------------------------------------------
@@ -66,6 +69,7 @@ function makeProviderRow(
     identityResponsePaths: null,
     identityFormat: null,
     identityOkField: null,
+    responseOkField: null,
     featureFlag: null,
     createdAt: now,
     updatedAt: now,
@@ -469,3 +473,34 @@ describe("verifyIdentity", () => {
     });
   });
 });
+
+describe("providerReportsFailure", () => {
+  test("reads an explicit false in the declared field as failure", () => {
+    expect(
+      providerReportsFailure(
+        { responseOkField: "ok" },
+        { ok: false, error: "invalid_auth" },
+      ),
+    ).toBe(true);
+    expect(
+      providerReportsFailure({ responseOkField: "ok" }, { ok: true }),
+    ).toBe(false);
+  });
+
+  test("a body without the field says nothing", () => {
+    // A download or an endpoint outside the envelope; the status decides.
+    expect(providerReportsFailure({ responseOkField: "ok" }, null)).toBe(false);
+    expect(
+      providerReportsFailure({ responseOkField: "ok" }, Buffer.from("png")),
+    ).toBe(false);
+    expect(
+      providerReportsFailure({ responseOkField: "ok" }, { data: {} }),
+    ).toBe(false);
+  });
+
+  test("a provider that declares no field never reports failure", () => {
+    expect(
+      providerReportsFailure({ responseOkField: null }, { ok: false }),
+    ).toBe(false);
+  });
+});

package/src/oauth/identity-verifier.ts

@@ -27,6 +27,30 @@ function getNestedValue(obj: unknown, dotPath: string): unknown {
   return current;
 }
 
+/**
+ * Whether a response body says the call failed, read through the ok field the
+ * provider declares (`responseOkField`).
+ *
+ * Some APIs report failure inside a successful HTTP exchange: Slack documents
+ * that every Web API response is a JSON object with a top-level boolean `ok`,
+ * false on failure, so the status code alone reads a refused call as a
+ * success. The provider row is where that envelope is declared, and this is
+ * the one reader of it for calls whose endpoint is not known in advance (ping
+ * and the authenticated-request doors). Only an explicit `false` counts: a
+ * body without the field, such as a file download or an endpoint outside the
+ * envelope, says nothing, and the status stays the verdict. The identity
+ * verifier reads its own field, `identityOkField`, for the one call it makes.
+ */
+export function providerReportsFailure(
+  providerRow: Pick<OAuthProviderRow, "responseOkField">,
+  body: unknown,
+): boolean {
+  if (!providerRow.responseOkField) {
+    return false;
+  }
+  return getNestedValue(body, providerRow.responseOkField) === false;
+}
+
 /** Safely parse a JSON string, returning a fallback on failure or null/undefined input. */
 function safeJsonParse<T>(value: string | null | undefined, fallback: T): T {
   if (value == null) {

package/src/oauth/oauth-store.ts

@@ -59,7 +59,7 @@ export type OAuthConnectionRow = typeof oauthConnections.$inferSelect;
  * managedServiceConfigKey,
  * loopbackPort, injectionTemplates, appType, setupNotes,
  * identityUrl, identityMethod, identityHeaders, identityBody,
- * identityResponsePaths, identityFormat, identityOkField, featureFlag,
+ * identityResponsePaths, identityFormat, identityOkField, responseOkField, featureFlag,
  * scopeSeparator, defaultScopes, availableScopes)
  * and display metadata (displayLabel, description, dashboardUrl,
  * clientIdPlaceholder, logoUrl, requiresClientSecret) propagate to existing
@@ -111,6 +111,7 @@ export function seedProviders(
     identityResponsePaths?: string[];
     identityFormat?: string;
     identityOkField?: string;
+    responseOkField?: string;
     featureFlag?: string;
   }>,
 ): void {
@@ -175,6 +176,7 @@ export function seedProviders(
       : null;
     const identityFormat = p.identityFormat ?? null;
     const identityOkField = p.identityOkField ?? null;
+    const responseOkField = p.responseOkField ?? null;
     const featureFlag = p.featureFlag ?? null;
 
     db.insert(oauthProviders)
@@ -216,6 +218,7 @@ export function seedProviders(
         identityResponsePaths,
         identityFormat,
         identityOkField,
+        responseOkField,
         featureFlag,
         createdAt: now,
         updatedAt: now,
@@ -259,6 +262,7 @@ export function seedProviders(
           identityResponsePaths,
           identityFormat,
           identityOkField,
+          responseOkField,
           featureFlag,
           updatedAt: now,
         },
@@ -359,6 +363,7 @@ export function registerProvider(params: {
   identityResponsePaths?: string[];
   identityFormat?: string;
   identityOkField?: string;
+  responseOkField?: string;
   featureFlag?: string;
 }): OAuthProviderRow {
   const db = getDb();
@@ -425,6 +430,7 @@ export function registerProvider(params: {
       : null,
     identityFormat: params.identityFormat ?? null,
     identityOkField: params.identityOkField ?? null,
+    responseOkField: params.responseOkField ?? null,
     featureFlag: params.featureFlag ?? null,
     createdAt: now,
     updatedAt: now,
@@ -486,6 +492,7 @@ export function updateProvider(
     identityResponsePaths: string[];
     identityFormat: string;
     identityOkField: string;
+    responseOkField: string;
     featureFlag: string;
     managedServiceIsPaid: boolean;
   }>,
@@ -610,6 +617,9 @@ export function updateProvider(
   if (params.identityOkField !== undefined) {
     set.identityOkField = params.identityOkField;
   }
+  if (params.responseOkField !== undefined) {
+    set.responseOkField = params.responseOkField;
+  }
   if (params.featureFlag !== undefined) {
     set.featureFlag = params.featureFlag;
   }

package/src/oauth/provider-serializer.ts

@@ -141,6 +141,7 @@ function _serializeProvider(
       : null,
     identityFormat: row.identityFormat ?? null,
     identityOkField: row.identityOkField ?? null,
+    responseOkField: row.responseOkField ?? null,
     featureFlag: row.featureFlag ?? null,
     redirectUri:
       options?.redirectUri !== undefined ? options.redirectUri : null,

package/src/oauth/seed-providers.ts

@@ -104,6 +104,14 @@ export const PROVIDER_SEED_DATA: Record<
     identityResponsePaths?: string[];
     identityFormat?: string;
     identityOkField?: string;
+    /**
+     * Dot path of the boolean the provider's API puts in every response body
+     * to report success (Slack: `ok`). Ping and the authenticated-request
+     * doors read an explicit `false` under a 2xx as a failed call, since such
+     * a provider hides refusals behind a successful status. Distinct from
+     * `identityOkField`, which governs only the identity call.
+     */
+    responseOkField?: string;
     featureFlag?: string;
     logoUrl?: string;
   }
@@ -256,6 +264,7 @@ export const PROVIDER_SEED_DATA: Record<
     appType: "Slack App",
     identityUrl: "https://slack.com/api/auth.test",
     identityOkField: "ok",
+    responseOkField: "ok",
     identityResponsePaths: ["user", "team"],
     identityFormat: "@${user} (${team})",
   },
@@ -1221,6 +1230,9 @@ export const PROVIDER_SEED_DATA: Record<
     authorizeUrl: "urn:manual-token",
     tokenExchangeUrl: "urn:manual-token",
     pingUrl: "https://slack.com/api/auth.test",
+    // The bot answers through the same Web API envelope as the person's
+    // integration, and auth.test refuses a revoked token inside an HTTP 200.
+    responseOkField: "ok",
     baseUrl: "https://slack.com/api",
     displayLabel: "Slack Channel",
     description: "Channel bot token",

package/src/permissions/confirmation-guardian-request.test.ts

@@ -111,6 +111,22 @@ describe("createGuardianRequestForConfirmation", () => {
     expect(expiresAt).toBeLessThanOrEqual(after + APPROVAL_WINDOW_MS);
   });
 
+  test("describes the request by the status sentence, never a tool's own reason argument", async () => {
+    await createGuardianRequestForConfirmation(
+      { ...MSG, input: { reason: "Task complete" } },
+      "conv-1",
+    );
+    await createGuardianRequestForConfirmation(
+      { ...MSG, input: { activity: "Stopping the app" } },
+      "conv-1",
+    );
+
+    expect(createCalls.map((call) => call.activityText)).toEqual([
+      undefined,
+      "Stopping the app",
+    ]);
+  });
+
   test("expires the row and skips the bridge when the confirmation resolved mid-create", async () => {
     confirmationPending = false;
 

package/src/permissions/confirmation-guardian-request.ts

@@ -73,10 +73,9 @@ export async function createGuardianRequestForConfirmation(
     const sourceChannel = trustContext?.sourceChannel ?? "vellum";
     const inputRecord = msg.input as Record<string, unknown>;
     const activityRaw =
-      (typeof inputRecord.activity === "string"
+      typeof inputRecord.activity === "string"
         ? inputRecord.activity
-        : undefined) ??
-      (typeof inputRecord.reason === "string" ? inputRecord.reason : undefined);
+        : undefined;
     // Tool approvals are decisionable: without a bound principal nobody could
     // ever decide them (mirrors the gateway create's integrity guard).
     const guardianPrincipalId = trustContext?.guardianPrincipalId;

package/src/permissions/question-prompter.test.ts

@@ -455,3 +455,34 @@ describe("QuestionPrompter", () => {
     expect(sent).toHaveLength(0);
   });
 });
+
+test("desktop help presentation survives broadcast and pending recovery until Done", async () => {
+  const { prompter, sent } = makePrompter();
+  const pending = prompter.prompt({
+    conversationId: "conv-123",
+    questions: [
+      {
+        question: "Please complete the CAPTCHA.",
+        presentation: "virtual_desktop",
+        options: [
+          { id: "done", label: "Done" },
+          { id: "skip", label: "Skip" },
+        ],
+      },
+    ],
+  });
+  const request = sent.find(
+    (event) => event.type === "question_request",
+  ) as QuestionRequestEvent;
+  expect(request.questions[0]?.presentation).toBe("virtual_desktop");
+  expect(_piStore.get(request.requestId)?.questionDetails?.entries).toEqual(
+    request.questions,
+  );
+  resolveBatch(request.requestId, [
+    { questionId: "q1", kind: "option", optionId: "done" },
+  ]);
+  expect((await pending).entries).toEqual([
+    { questionId: "q1", decision: "option", optionId: "done" },
+  ]);
+  expect(_piStore.has(request.requestId)).toBe(false);
+});

package/src/permissions/question-prompter.ts

@@ -77,6 +77,7 @@ export interface QuestionPromptParamsEntry {
   description?: string;
   options: QuestionOption[];
   freeTextPlaceholder?: string;
+  presentation?: QuestionEntry["presentation"];
 }
 
 export interface QuestionPromptParams {
@@ -201,6 +202,7 @@ export class QuestionPrompter {
       description: q.description,
       options: q.options,
       freeTextPlaceholder: q.freeTextPlaceholder,
+      ...(q.presentation ? { presentation: q.presentation } : {}),
     }));
     const orderedIds = entries.map((e) => e.id);
     const optionsById: Record<string, string[]> = {};