@vellumai/assistant 0.12.5 → 0.12.6-dev.202609292019.a6f6d85

package/.env.example

@@ -2,6 +2,8 @@
 ANTHROPIC_API_KEY=sk-ant-...
 OPENAI_API_KEY=sk-...
 GEMINI_API_KEY=...
+# Optional. IO Intelligence (io.net) open-models endpoint.
+IONET_API_KEY=...
 # Optional. TypeSafe / Jev System One decision model.
 TYPESAFE_API_KEY=...
 # Optional for authenticated/proxied Ollama deployments

package/ARCHITECTURE.md

@@ -45,6 +45,12 @@ Resource pressure monitoring reports sustained CPU/memory pressure on platform-h
 
 **Lifecycle:** `src/daemon/resource-pressure-guard-lifecycle.ts` starts the guard at daemon boot with the first sample deferred onto a macrotask so it never blocks startup, and stops the guard (cancelling any pending deferred sample) on shutdown. The web chat banner built on this status is documented in the repo-level [`/ARCHITECTURE.md`](../ARCHITECTURE.md) "Resource Pressure Monitoring" section.
 
+### OOM Priority
+
+When the container hits its memory limit, the kernel kills the process with the highest `oom_score` (memory share plus `oom_score_adj`). `src/util/oom-priority.ts` steers that choice so the assistant is never the victim of a runaway tool: the daemon sets itself to -700 as the first thing in `runDaemon`, before any spawn. Children inherit the parent's value at fork, so every spawn path resets its child: shell children get +1000 from the Linux prefix in `buildShellInvocation` (`packages/environments`), desktop children and ACP agents and terminals get +1000 from `withOomScoreAdj`, an `sh -c ... exec` wrapper that keeps pid and process group, and workers, the embedding worker, and Qdrant get 0 from a parent-side write right after spawn (the resource monitor gets -500 so it outlives everything but the daemon and records the kill). The monitor also sweeps the daemon's descendants every few seconds (`src/monitoring/oom-inheritance-sweep.ts`) and writes 0 over any negative value it finds, logging the comm, so a spawn path that forgets the reset degrades to a few seconds of inherited protection instead of a protected runaway. Bundled plugins (the memory plugin's rerank worker, for one) rely on the sweep rather than importing the helper, since the plugin import boundary forbids reaching outside the plugin. Raising never needs a capability; lowering needs `CAP_SYS_RESOURCE`, which the platform grants and self-hosted Docker does not, where the daemon simply stays at 0. Nothing here caps a single process or acts early: it only decides who dies once the kernel has to kill.
+
+**Verification telemetry:** the resource monitor reports kernel OOM kills in the container as a `watchdog` event with `check_name` `oom_kill` (`src/monitoring/oom-kill-reporter.ts`). It reads the kernel log through `dmesg` (the `/dev/kmsg` device is not mounted in the container; `dmesg` uses the syslog syscall, which the Kata profile permits) when the cgroup `memory.events` kill counter moves, on its first scan after start (the kill that took the daemon down restarts the monitor with it), and once a minute as a fallback. The log is shared by every container on that kernel, so a kill is attributed by the cgroup path in the kernel's `oom-kill:` header, matched against the container's own id, which it reads from the runtime-named mounts in `/proc/self/mountinfo` because `/proc/self/cgroup` reads `/` inside a cgroup namespace (`attribution: "cgroup"`). The kernel rate-limits that header in a burst, so header-less kills are attributed by the counter, re-read after the log: credit left after the header-attributed kills names header-less kills oldest first, header-less kills beyond the credit are another container's, and credit for a kill counted but not yet logged is spent on the next scan or reported unnamed (`attribution: "cgroup_counter"`). The first scan and hosts without the counter claim every new kill not assigned elsewhere by a header (`attribution: "kernel_log"`). The `detail` bag lists each victim's comm, `oom_score_adj` and resident size, the cgroup memory figures at the time, and `killed_daemon`, detected by the daemon's -700 score rather than a pid the restart has since replaced; where the log is unreadable a counter move still yields a victimless event. A cursor (kernel boot id plus last log timestamp) on the monitor data dir advances only after the event is queued, so a telemetry store outage delays a report rather than losing one, and resets when the kernel reboots.
+
 ### Single-Header JWT Auth Model
 
 All HTTP API requests use a single `Authorization: Bearer <jwt>` header for authentication. The JWT carries identity, permissions, and policy versioning in a unified token.
@@ -902,6 +908,23 @@ graph LR
 
 ---
 
+## Automatic Done
+
+`src/conversations/auto-archive.ts` runs an opt-in automatic Done sweep after startup recovery, on assistant config or feature-flag invalidation, and hourly. It marks eligible inactive native chats through the existing `archived_at` state. Candidate selection and the conditional update share the same persisted eligibility predicates; runtime checks run synchronously with each conditional write. Explicit reopening records `last_reopened_at` to grant a full inactivity interval.
+
+```mermaid
+flowchart LR
+    TRIGGER[Startup recovery / config or feature-flag change / hourly timer] --> PAGE[Bounded candidate page]
+    PAGE --> GUARDIAN[Read pending guardian requests]
+    GUARDIAN --> CHECK[Recheck config and runtime activity]
+    CHECK --> CAS[Conditional SQLite Done update]
+    CAS --> SYNC[Conversation list and metadata invalidation]
+```
+
+Readiness, eligibility, restart behavior, and the gateway snapshot boundary are documented in [Automatic Done](docs/automatic-done.md).
+
+---
+
 ## Plugin-Declared Schedules: Declaration → Reconciler → cron_jobs
 
 Plugins contribute recurring schedules as a surface: directories under

package/docs/automatic-done.md

@@ -0,0 +1,32 @@
+# Automatic Done
+
+Chats Settings exposes `conversations.autoArchive` through the assistant config. `enabled` defaults to `false`; `afterDays` defaults to `7` and accepts `1`, `7`, `14`, or `30`. The worker additionally requires the `sidebar-done` feature flag so the setting cannot activate legacy archive behavior.
+
+Auto Archive marks eligible inactive chats **Done** by setting the existing `archived_at` field. The chat remains visible in All Chats and Done, retains its transcript, and can be reopened. No schedule is cancelled and no data is deleted. New visible activity uses the existing resurfacing path.
+
+## Eligibility
+
+Inactivity is elapsed wall time since the latest of the last message (or creation for an empty chat) and an explicit reopen. Title edits, read receipts, config edits and other `updated_at` writes do not count as conversation activity. Migration `386-conversations-last-reopened-at.ts` adds a nullable marker without backfilling or changing existing chats. Only an actual Done-to-open transition records that marker, giving a reopened chat a full configured interval.
+
+Candidates must be unarchived standard native chats. Native notification-origin chats are eligible; an external channel binding takes precedence over the legacy origin field. Pinned, private, scheduled, background, system, consolidation and child/subagent conversations are excluded. Chats with unread assistant output, pending guardian input, a live ACP session, a running workflow, an active mode session or a nonterminal subagent are excluded.
+
+The final runtime check also excludes accepted sends, queued/processing turns, voice residency, pending standalone surfaces, local interactions, background tool work, wake dispatches and unfinished turn finalization. ACP resume reservations are checked against their persisted parent before the resumed session registers as live.
+
+## Lifecycle and concurrency
+
+The assistant owns one worker, independent of client pages. Its first sweep waits for interrupted conversation recovery, database migration readiness and startup completion. Failed startup recovery leaves the worker paused until restart. Config or assistant feature-flag invalidation and an hourly timer trigger later sweeps; overlapping triggers coalesce. The gateway flag listener publishes invalidation only after its cache refresh succeeds, including reconnect catch-up, so consumers see the refreshed gate. A failed refresh emits no invalidation. Shutdown cancels retries, removes the subscription/timer and prevents a late recovery promise from starting work.
+
+Each sweep scans bounded pages of 100 candidates with an activity/id keyset. For every page, it reads the exhaustive pending guardian-request list through the gateway. A failed read leaves that page untouched. Final eligibility and the write run synchronously inside each SQLite retry attempt. The SQL compare-and-set checks sampled message/reopen cursors and all persisted eligibility again, so activity, pinning, input-related processing, workflow/session changes, or reopening during the asynchronous gateway read cannot overwrite newer state.
+
+Gateway-owned guardian requests live outside the assistant database. The page read is a snapshot, not a distributed transaction: a remote request created after that read cannot be atomically excluded by SQLite. Local interaction, processing and queue checks close the ordinary same-process window. The worker fails closed on an unavailable gateway or uncertain runtime state; the cross-service snapshot boundary remains explicit.
+
+Successful updates publish the existing conversation-list and per-conversation metadata invalidations once per changed page, including updates committed before a later failure. There is no new transport event or persistent worker cursor. A restart safely scans eligible rows again, and already Done rows are excluded.
+
+## Code and validation
+
+- `src/conversations/auto-archive.ts`: scheduling, startup barrier, guardian snapshot and invalidation batching.
+- `src/conversations/auto-archive-activity.ts`: synchronous runtime blockers.
+- `src/persistence/conversation-auto-archive.ts`: shared SQL eligibility, paging and conditional writes.
+- `src/persistence/conversation-crud.ts`: explicit reopen marker and existing activity resurfacing.
+
+Focused tests cover eligibility and cursor races, reopen grace, paging, pending input, retries, lifecycle cancellation, coalescing and client invalidation. Migration tests verify existing data and idempotence.

package/docs/desktop-browser-cli.md

@@ -53,8 +53,9 @@ Non-platform assistants keep their connected-computer behavior.
 Explicit `target: "connected-computer"` or `target_client_id` selects a connected
 computer on every client. The selected target never falls back to another
 computer when unavailable. The virtual desktop uses a fixed 1440x810 display.
-Observations return full-screen screenshots and mouse actions use the same
-screen coordinates.
+Observations return full-screen screenshots and mouse actions use screen
+points. Screenshot metadata uses the transport-optimized image dimensions and
+provides per-axis conversion from image pixels to those screen points.
 Viewer resizing scales the canvas locally without changing the desktop layout.
 
 Observe first and pass the returned `observation_id` with each native action.

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/package.json

@@ -28,7 +28,8 @@
     "./guardian-requests": "./src/guardian-requests.ts",
     "./platform-credential": "./src/platform-credential.ts",
     "./plan-credit": "./src/plan-credit.ts",
-    "./integration-categories": "./src/integration-categories.ts"
+    "./integration-categories": "./src/integration-categories.ts",
+    "./mcp-oauth": "./src/mcp-oauth.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/__tests__/mcp-oauth.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  buildMcpOAuthCallbackUrl,
+  buildMcpOAuthClientMetadata,
+  buildMcpOAuthClientMetadataUrl,
+} from "../mcp-oauth.js";
+
+describe("MCP OAuth client metadata", () => {
+  test("builds the public client document", () => {
+    expect(
+      buildMcpOAuthClientMetadata({
+        clientId:
+          "https://velay.example/assistant-123/oauth/client-metadata.json",
+        redirectUris: [
+          "https://velay.example/assistant-123/webhooks/oauth/callback",
+        ],
+      }),
+    ).toEqual({
+      client_id:
+        "https://velay.example/assistant-123/oauth/client-metadata.json",
+      redirect_uris: [
+        "https://velay.example/assistant-123/webhooks/oauth/callback",
+      ],
+      token_endpoint_auth_method: "none",
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      client_name: "Vellum Assistant",
+      logo_uri: "https://www.vellum.ai/favicon.svg",
+    });
+  });
+
+  test("builds callback and metadata URLs from one normalized base", () => {
+    const baseUrl = "https://velay.example/assistant-123///";
+    expect(buildMcpOAuthCallbackUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/webhooks/oauth/callback",
+    );
+    expect(buildMcpOAuthClientMetadataUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/oauth/client-metadata.json",
+    );
+  });
+
+  test("canonicalizes equivalent public base URL spellings", () => {
+    const baseUrl = " https://VELAY.EXAMPLE:443/a/../assistant-123/// ";
+
+    expect(buildMcpOAuthCallbackUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/webhooks/oauth/callback",
+    );
+    expect(buildMcpOAuthClientMetadataUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/oauth/client-metadata.json",
+    );
+  });
+});

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/index.ts

@@ -30,6 +30,7 @@ export * from "./ingress.js";
 export * from "./no-response.js";
 export * from "./plan-credit.js";
 export * from "./integration-categories.js";
+export * from "./mcp-oauth.js";
 export * from "./platform-credential.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/mcp-oauth.ts

@@ -0,0 +1,60 @@
+import { normalizeHttpPublicBaseUrlWithoutTrailingSlash } from "./ingress.js";
+
+export const MCP_OAUTH_CALLBACK_PATH = "/webhooks/oauth/callback";
+export const MCP_OAUTH_CLIENT_METADATA_PATH = "/oauth/client-metadata.json";
+export const MCP_OAUTH_CLIENT_LOGO_URI = "https://www.vellum.ai/favicon.svg";
+
+export interface McpOAuthClientMetadata {
+  client_id?: string;
+  redirect_uris: string[];
+  token_endpoint_auth_method: "none";
+  grant_types: ["authorization_code", "refresh_token"];
+  response_types: ["code"];
+  client_name: string;
+  logo_uri: string;
+  software_id?: string;
+  software_version?: string;
+}
+
+export interface BuildMcpOAuthClientMetadataOptions {
+  clientId?: string;
+  redirectUris: string[];
+  clientName?: string;
+  softwareId?: string;
+  softwareVersion?: string;
+}
+
+export function buildMcpOAuthClientMetadata(
+  options: BuildMcpOAuthClientMetadataOptions,
+): McpOAuthClientMetadata {
+  return {
+    ...(options.clientId && { client_id: options.clientId }),
+    redirect_uris: options.redirectUris,
+    token_endpoint_auth_method: "none",
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    client_name: options.clientName ?? "Vellum Assistant",
+    logo_uri: MCP_OAUTH_CLIENT_LOGO_URI,
+    ...(options.softwareId && { software_id: options.softwareId }),
+    ...(options.softwareVersion && {
+      software_version: options.softwareVersion,
+    }),
+  };
+}
+
+export function buildMcpOAuthCallbackUrl(publicBaseUrl: string): string {
+  return `${normalizeBaseUrl(publicBaseUrl)}${MCP_OAUTH_CALLBACK_PATH}`;
+}
+
+export function buildMcpOAuthClientMetadataUrl(publicBaseUrl: string): string {
+  return `${normalizeBaseUrl(publicBaseUrl)}${MCP_OAUTH_CLIENT_METADATA_PATH}`;
+}
+
+function normalizeBaseUrl(publicBaseUrl: string): string {
+  const normalized =
+    normalizeHttpPublicBaseUrlWithoutTrailingSlash(publicBaseUrl);
+  if (!normalized) {
+    throw new Error("MCP OAuth public base URL must be an absolute HTTP URL");
+  }
+  return normalized;
+}

package/node_modules/@vellumai/environments/src/shell.test.ts

@@ -3,18 +3,30 @@ import { describe, expect, test } from "bun:test";
 import {
   buildShellInvocation,
   buildShellSpawnFlags,
+  CHILD_OOM_SCORE_ADJ,
   pathListDelimiter,
   prependUniquePathEntries,
 } from "./shell.js";
 
 describe("buildShellInvocation", () => {
   test("uses Bash on POSIX hosts", () => {
-    expect(buildShellInvocation("printf hello", "linux")).toEqual({
+    expect(buildShellInvocation("printf hello", "darwin")).toEqual({
       command: "bash",
       args: ["-c", "--", "printf hello"],
     });
   });
 
+  test("raises the shell's OOM-kill priority on Linux", () => {
+    expect(buildShellInvocation("printf hello", "linux")).toEqual({
+      command: "bash",
+      args: [
+        "-c",
+        "--",
+        `echo ${CHILD_OOM_SCORE_ADJ} 2>/dev/null >/proc/self/oom_score_adj; printf hello`,
+      ],
+    });
+  });
+
   test("uses encoded non-interactive PowerShell on Windows", () => {
     const invocation = buildShellInvocation(
       "Write-Output 'hello 世界'",

package/node_modules/@vellumai/environments/src/shell.ts

@@ -24,6 +24,23 @@ if (-not $__vellumCommandSucceeded) {
 }
 exit 0`;
 
+/**
+ * `oom_score_adj` for assistant-owned tool processes. Any positive value
+ * outranks a 0-scored process; 1000 makes a tool the kernel's first choice
+ * whenever the container runs out of memory, so the assistant itself is never
+ * the victim of a runaway command.
+ */
+export const CHILD_OOM_SCORE_ADJ = 1000;
+
+/**
+ * Prefix for a Bash `-c` script that raises the shell's own OOM-kill priority
+ * before the command runs. Every process the command forks inherits it. Bash
+ * performs a builtin's redirection itself, so `/proc/self` is the shell.
+ * Redirections apply left to right, so stderr goes to /dev/null before the
+ * procfs open can fail and complain about it.
+ */
+const LINUX_OOM_SCORE_ADJ_PREFIX = `echo ${CHILD_OOM_SCORE_ADJ} 2>/dev/null >/proc/self/oom_score_adj; `;
+
 export function buildShellInvocation(
   command: string,
   hostPlatform: NodeJS.Platform = process.platform,
@@ -45,7 +62,11 @@ export function buildShellInvocation(
       ],
     };
   }
-  return { command: "bash", args: ["-c", "--", command] };
+  const script =
+    hostPlatform === "linux"
+      ? `${LINUX_OOM_SCORE_ADJ_PREFIX}${command}`
+      : command;
+  return { command: "bash", args: ["-c", "--", script] };
 }
 
 /**

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/package.json

@@ -28,7 +28,8 @@
     "./guardian-requests": "./src/guardian-requests.ts",
     "./platform-credential": "./src/platform-credential.ts",
     "./plan-credit": "./src/plan-credit.ts",
-    "./integration-categories": "./src/integration-categories.ts"
+    "./integration-categories": "./src/integration-categories.ts",
+    "./mcp-oauth": "./src/mcp-oauth.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/__tests__/mcp-oauth.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  buildMcpOAuthCallbackUrl,
+  buildMcpOAuthClientMetadata,
+  buildMcpOAuthClientMetadataUrl,
+} from "../mcp-oauth.js";
+
+describe("MCP OAuth client metadata", () => {
+  test("builds the public client document", () => {
+    expect(
+      buildMcpOAuthClientMetadata({
+        clientId:
+          "https://velay.example/assistant-123/oauth/client-metadata.json",
+        redirectUris: [
+          "https://velay.example/assistant-123/webhooks/oauth/callback",
+        ],
+      }),
+    ).toEqual({
+      client_id:
+        "https://velay.example/assistant-123/oauth/client-metadata.json",
+      redirect_uris: [
+        "https://velay.example/assistant-123/webhooks/oauth/callback",
+      ],
+      token_endpoint_auth_method: "none",
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      client_name: "Vellum Assistant",
+      logo_uri: "https://www.vellum.ai/favicon.svg",
+    });
+  });
+
+  test("builds callback and metadata URLs from one normalized base", () => {
+    const baseUrl = "https://velay.example/assistant-123///";
+    expect(buildMcpOAuthCallbackUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/webhooks/oauth/callback",
+    );
+    expect(buildMcpOAuthClientMetadataUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/oauth/client-metadata.json",
+    );
+  });
+
+  test("canonicalizes equivalent public base URL spellings", () => {
+    const baseUrl = " https://VELAY.EXAMPLE:443/a/../assistant-123/// ";
+
+    expect(buildMcpOAuthCallbackUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/webhooks/oauth/callback",
+    );
+    expect(buildMcpOAuthClientMetadataUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/oauth/client-metadata.json",
+    );
+  });
+});

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/index.ts

@@ -30,6 +30,7 @@ export * from "./ingress.js";
 export * from "./no-response.js";
 export * from "./plan-credit.js";
 export * from "./integration-categories.js";
+export * from "./mcp-oauth.js";
 export * from "./platform-credential.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/mcp-oauth.ts

@@ -0,0 +1,60 @@
+import { normalizeHttpPublicBaseUrlWithoutTrailingSlash } from "./ingress.js";
+
+export const MCP_OAUTH_CALLBACK_PATH = "/webhooks/oauth/callback";
+export const MCP_OAUTH_CLIENT_METADATA_PATH = "/oauth/client-metadata.json";
+export const MCP_OAUTH_CLIENT_LOGO_URI = "https://www.vellum.ai/favicon.svg";
+
+export interface McpOAuthClientMetadata {
+  client_id?: string;
+  redirect_uris: string[];
+  token_endpoint_auth_method: "none";
+  grant_types: ["authorization_code", "refresh_token"];
+  response_types: ["code"];
+  client_name: string;
+  logo_uri: string;
+  software_id?: string;
+  software_version?: string;
+}
+
+export interface BuildMcpOAuthClientMetadataOptions {
+  clientId?: string;
+  redirectUris: string[];
+  clientName?: string;
+  softwareId?: string;
+  softwareVersion?: string;
+}
+
+export function buildMcpOAuthClientMetadata(
+  options: BuildMcpOAuthClientMetadataOptions,
+): McpOAuthClientMetadata {
+  return {
+    ...(options.clientId && { client_id: options.clientId }),
+    redirect_uris: options.redirectUris,
+    token_endpoint_auth_method: "none",
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    client_name: options.clientName ?? "Vellum Assistant",
+    logo_uri: MCP_OAUTH_CLIENT_LOGO_URI,
+    ...(options.softwareId && { software_id: options.softwareId }),
+    ...(options.softwareVersion && {
+      software_version: options.softwareVersion,
+    }),
+  };
+}
+
+export function buildMcpOAuthCallbackUrl(publicBaseUrl: string): string {
+  return `${normalizeBaseUrl(publicBaseUrl)}${MCP_OAUTH_CALLBACK_PATH}`;
+}
+
+export function buildMcpOAuthClientMetadataUrl(publicBaseUrl: string): string {
+  return `${normalizeBaseUrl(publicBaseUrl)}${MCP_OAUTH_CLIENT_METADATA_PATH}`;
+}
+
+function normalizeBaseUrl(publicBaseUrl: string): string {
+  const normalized =
+    normalizeHttpPublicBaseUrlWithoutTrailingSlash(publicBaseUrl);
+  if (!normalized) {
+    throw new Error("MCP OAuth public base URL must be an absolute HTTP URL");
+  }
+  return normalized;
+}

package/node_modules/@vellumai/gateway-client/src/__tests__/status-contracts.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  FeatureFlagsIpcResponseSchema,
+  VelayStatusIpcResponseSchema,
+} from "../gateway-ipc-contracts.js";
+
+describe("gateway status IPC contracts", () => {
+  test("filters unsupported feature flag values independently", () => {
+    expect(
+      FeatureFlagsIpcResponseSchema.parse({
+        enabled: true,
+        model: "balanced",
+        count: 3,
+        nested: { enabled: true },
+      }),
+    ).toEqual({ enabled: true, model: "balanced" });
+  });
+
+  test("rejects non-record feature flag responses", () => {
+    expect(FeatureFlagsIpcResponseSchema.safeParse([]).success).toBe(false);
+    expect(FeatureFlagsIpcResponseSchema.safeParse(null).success).toBe(false);
+  });
+
+  test("normalizes a malformed Velay public URL to null", () => {
+    expect(
+      VelayStatusIpcResponseSchema.parse({
+        connected: false,
+        publicUrl: 42,
+      }),
+    ).toEqual({ connected: false, publicUrl: null });
+  });
+
+  test("requires a boolean Velay connection state", () => {
+    expect(
+      VelayStatusIpcResponseSchema.safeParse({ connected: "yes" }).success,
+    ).toBe(false);
+  });
+});

package/node_modules/@vellumai/gateway-client/src/gateway-ipc-contracts.ts

@@ -17,6 +17,31 @@ export const GATEWAY_LOG_LEVEL_NAMES = [
 ] as const;
 export type GatewayLogLevelName = (typeof GATEWAY_LOG_LEVEL_NAMES)[number];
 
+export const FeatureFlagsIpcResponseSchema = z
+  .record(z.string(), z.unknown())
+  .transform((flags): Record<string, boolean | string> => {
+    const parsed: Record<string, boolean | string> = {};
+    for (const [key, value] of Object.entries(flags)) {
+      if (typeof value === "boolean" || typeof value === "string") {
+        parsed[key] = value;
+      }
+    }
+    return parsed;
+  });
+
+export type FeatureFlagsIpcResponse = z.infer<
+  typeof FeatureFlagsIpcResponseSchema
+>;
+
+export const VelayStatusIpcResponseSchema = z.object({
+  connected: z.boolean(),
+  publicUrl: z.string().nullable().catch(null),
+});
+
+export type VelayStatusIpcResponse = z.infer<
+  typeof VelayStatusIpcResponseSchema
+>;
+
 const GatewayLogsTailIpcParamsShape = {
   n: z.number().int().min(1).max(1000).optional(),
   level: z.enum(GATEWAY_LOG_LEVEL_NAMES).optional(),

package/node_modules/@vellumai/service-contracts/package.json

@@ -28,7 +28,8 @@
     "./guardian-requests": "./src/guardian-requests.ts",
     "./platform-credential": "./src/platform-credential.ts",
     "./plan-credit": "./src/plan-credit.ts",
-    "./integration-categories": "./src/integration-categories.ts"
+    "./integration-categories": "./src/integration-categories.ts",
+    "./mcp-oauth": "./src/mcp-oauth.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/service-contracts/src/__tests__/mcp-oauth.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  buildMcpOAuthCallbackUrl,
+  buildMcpOAuthClientMetadata,
+  buildMcpOAuthClientMetadataUrl,
+} from "../mcp-oauth.js";
+
+describe("MCP OAuth client metadata", () => {
+  test("builds the public client document", () => {
+    expect(
+      buildMcpOAuthClientMetadata({
+        clientId:
+          "https://velay.example/assistant-123/oauth/client-metadata.json",
+        redirectUris: [
+          "https://velay.example/assistant-123/webhooks/oauth/callback",
+        ],
+      }),
+    ).toEqual({
+      client_id:
+        "https://velay.example/assistant-123/oauth/client-metadata.json",
+      redirect_uris: [
+        "https://velay.example/assistant-123/webhooks/oauth/callback",
+      ],
+      token_endpoint_auth_method: "none",
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      client_name: "Vellum Assistant",
+      logo_uri: "https://www.vellum.ai/favicon.svg",
+    });
+  });
+
+  test("builds callback and metadata URLs from one normalized base", () => {
+    const baseUrl = "https://velay.example/assistant-123///";
+    expect(buildMcpOAuthCallbackUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/webhooks/oauth/callback",
+    );
+    expect(buildMcpOAuthClientMetadataUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/oauth/client-metadata.json",
+    );
+  });
+
+  test("canonicalizes equivalent public base URL spellings", () => {
+    const baseUrl = " https://VELAY.EXAMPLE:443/a/../assistant-123/// ";
+
+    expect(buildMcpOAuthCallbackUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/webhooks/oauth/callback",
+    );
+    expect(buildMcpOAuthClientMetadataUrl(baseUrl)).toBe(
+      "https://velay.example/assistant-123/oauth/client-metadata.json",
+    );
+  });
+});

package/node_modules/@vellumai/service-contracts/src/index.ts

@@ -30,6 +30,7 @@ export * from "./ingress.js";
 export * from "./no-response.js";
 export * from "./plan-credit.js";
 export * from "./integration-categories.js";
+export * from "./mcp-oauth.js";
 export * from "./platform-credential.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";

package/node_modules/@vellumai/service-contracts/src/mcp-oauth.ts

@@ -0,0 +1,60 @@
+import { normalizeHttpPublicBaseUrlWithoutTrailingSlash } from "./ingress.js";
+
+export const MCP_OAUTH_CALLBACK_PATH = "/webhooks/oauth/callback";
+export const MCP_OAUTH_CLIENT_METADATA_PATH = "/oauth/client-metadata.json";
+export const MCP_OAUTH_CLIENT_LOGO_URI = "https://www.vellum.ai/favicon.svg";
+
+export interface McpOAuthClientMetadata {
+  client_id?: string;
+  redirect_uris: string[];
+  token_endpoint_auth_method: "none";
+  grant_types: ["authorization_code", "refresh_token"];
+  response_types: ["code"];
+  client_name: string;
+  logo_uri: string;
+  software_id?: string;
+  software_version?: string;
+}
+
+export interface BuildMcpOAuthClientMetadataOptions {
+  clientId?: string;
+  redirectUris: string[];
+  clientName?: string;
+  softwareId?: string;
+  softwareVersion?: string;
+}
+
+export function buildMcpOAuthClientMetadata(
+  options: BuildMcpOAuthClientMetadataOptions,
+): McpOAuthClientMetadata {
+  return {
+    ...(options.clientId && { client_id: options.clientId }),
+    redirect_uris: options.redirectUris,
+    token_endpoint_auth_method: "none",
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    client_name: options.clientName ?? "Vellum Assistant",
+    logo_uri: MCP_OAUTH_CLIENT_LOGO_URI,
+    ...(options.softwareId && { software_id: options.softwareId }),
+    ...(options.softwareVersion && {
+      software_version: options.softwareVersion,
+    }),
+  };
+}
+
+export function buildMcpOAuthCallbackUrl(publicBaseUrl: string): string {
+  return `${normalizeBaseUrl(publicBaseUrl)}${MCP_OAUTH_CALLBACK_PATH}`;
+}
+
+export function buildMcpOAuthClientMetadataUrl(publicBaseUrl: string): string {
+  return `${normalizeBaseUrl(publicBaseUrl)}${MCP_OAUTH_CLIENT_METADATA_PATH}`;
+}
+
+function normalizeBaseUrl(publicBaseUrl: string): string {
+  const normalized =
+    normalizeHttpPublicBaseUrlWithoutTrailingSlash(publicBaseUrl);
+  if (!normalized) {
+    throw new Error("MCP OAuth public base URL must be an absolute HTTP URL");
+  }
+  return normalized;
+}