@vellumai/assistant 0.12.5 → 0.12.6-dev.202609292116.41f7caa

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.
@@ -612,12 +618,12 @@ Every phone call connects over Twilio Media Streams: the voice webhook emits `<C
 
 Transcription mode is selected once per session in `media-stream-stt-session.ts`:
 
-- **Streaming** (default): when `calls.voice.telephonyStreaming` is enabled and the `telephony` role resolves a streaming transcriber (`resolveStreamingTranscriber({ role: "telephony" })`), inbound audio is decoded (mu-law → PCM16, resampled 8 kHz → 16 kHz) and fed to the provider's realtime adapter. Replies trigger only on utterance-boundary finals (for Deepgram, `speech_final`/`UtteranceEnd`, never mid-sentence `is_final` segments), and barge-in fires from local energy VAD, never from transcriber partials. While something is interruptible (an assistant turn in flight, thinking or speaking, or a completed turn's tail still playing from Twilio's buffer), caller speech arms the shared sustained-speech barge-in guard (`src/calls/barge-in-guard.ts`, the same accounting live voice uses: speech accumulates toward 250 ms, short gaps are tolerated, a run that is mostly silence resets) and every inbound frame feeds it; outside that window the guard is dropped, so the caller's own utterance never carries into a turn that starts before the local VAD ends it. Only a fired guard reaches `CallController.handleBargeIn`, which interrupts a turn in either phase and ignores an idle controller (the playing tail is cleared instead).
+- **Streaming** (default): when `calls.voice.telephonyStreaming` is enabled and the `telephony` role resolves a streaming transcriber (`resolveStreamingTranscriber({ role: "telephony" })`), inbound audio is decoded (mu-law → PCM16, resampled 8 kHz → 16 kHz) and fed to the provider's realtime adapter. Replies trigger only on utterance-boundary finals (for Deepgram, `speech_final`/`UtteranceEnd`, never mid-sentence `is_final` segments), and barge-in fires from local energy VAD, never from transcriber partials. Interim `partial` events are forwarded to the controller as `handleCallerPartial`: they commit nothing and start no turn, they are never persisted and never reach a setup flow, and they exist so a boundary the front door held mid-thought can be replayed on the caller's newest words rather than only the ones the provider has finalized. While something is interruptible (an assistant turn in flight, thinking or speaking, or a completed turn's tail still playing from Twilio's buffer), caller speech arms the shared sustained-speech barge-in guard (`src/calls/barge-in-guard.ts`, the same accounting live voice uses: speech accumulates toward 250 ms, short gaps are tolerated, a run that is mostly silence resets) and every inbound frame feeds it; outside that window the guard is dropped, so the caller's own utterance never carries into a turn that starts before the local VAD ends it. Only a fired guard reaches `CallController.handleBargeIn`, which interrupts a turn in either phase and ignores an idle controller (the playing tail is cleared instead).
 - **Batch fallback**: otherwise the session segments turns with the energy-based `MediaTurnDetector` and transcribes each completed turn via the same role's batch API. Both halves of a call read the `telephony` role, which is why a role names its consumer rather than a boundary.
 
-Every phone turn runs the same two-leg triage as live voice through `startVoiceTurn` (`src/calls/voice-session-bridge.ts`): `call-controller.ts` opens on a toolless front-door leg (`routingLeg: "front-door"`, the `voiceFrontDoor` call site) and drives it through the shared `createFrontDoorLegCoordinator` (`src/calls/voice-leg-coordinator.ts`), which reads the stream through the verdict machine and sequences the hand-off (pause narration, abort the leg, resolve and speak the bridge, mark it as the floor holder, start the escalated leg pinned to the conversation's own model, re-arm narration); each driver supplies only a host for how text and the bridge are spoken, how a leg is started or aborted, and (live voice only) the speculative hold and commit. Phone has no partial transcripts, so the hold verdict is never taught and routing is escalate-only. The controller also passes the bridge's turn callbacks (tool activity is recorded as `tool_use_started` / `tool_use_completed` call events, persisted row ids ride the `assistant_spoke` event), `launchedAtMs` for dispatch timing, and a `voiceTelemetry` bag keyed by the call session with a `phone_inbound` / `phone_outbound` entry. Both drivers share the spoken progress narration cadence (`src/calls/voice-progress-cadence.ts`, tuned by `voice.frontModel.progress`): the cadence owns the tool-activity log, the triggers (an ops burst, a long operation completing, a full interval of audible silence with news, the `maxSilenceMs` heartbeat) and the generated or static phrase, while each driver supplies its own view of audible silence (live voice from its TTS queue and playback-tail estimate; the media-stream transport from `isPlaybackIdle()` and a running sum of sent frame durations) and how to speak a phrase.
+Every phone turn runs the same two-leg triage as live voice through `startVoiceTurn` (`src/calls/voice-session-bridge.ts`): `call-controller.ts` opens on a toolless front-door leg (`routingLeg: "front-door"`, the `voiceFrontDoor` call site) and drives it through the shared `createFrontDoorLegCoordinator` (`src/calls/voice-leg-coordinator.ts`), which reads the stream through the verdict machine and sequences the hand-off (pause narration, abort the leg, resolve and speak the bridge, mark it as the floor holder, start the escalated leg pinned to the conversation's own model, re-arm narration); each driver supplies only a host for how text and the bridge are spoken, how a leg is started or aborted, and (live voice only) the speculative hold and commit. A leg that carries the caller's own words is also the turn's endpoint decision, so it is taught the hold verdict: silence alone cannot tell a finished sentence from a thinking pause, and answering a fragment makes the rest of the sentence read as a barge-in that interrupts the assistant's own reply. On a hold the leg is discarded (its persisted user row rolled back through the handle's `discard`), the floor goes straight back to the caller, and the words are carried into their next final so the whole sentence is judged together. If no next words arrive, a replay timer (`voice.frontModel.endpointExtensionMs`) answers the sentence as it stands; any partial re-arms that timer and the next final cancels it. A partial also stretches the wait to at least `calls.voice.utteranceEndMs` plus a margin, because the provider still owes a final for those words and that final is the better boundary: racing it would ask the same words twice, once on the interim guess and once on the committed text. Reaching the timer with a partial outstanding therefore means no final is coming, so the interim text rides along as the only record of what the caller said. `voice.frontModel.endpointMaxExtensions` caps consecutive holds per sentence, after which the leg must answer. Openers, instructions, and other assistant-initiated turns are never dispatched that way. The controller also passes the bridge's turn callbacks (tool activity is recorded as `tool_use_started` / `tool_use_completed` call events, persisted row ids ride the `assistant_spoke` event), `launchedAtMs` for dispatch timing, and a `voiceTelemetry` bag keyed by the call session with a `phone_inbound` / `phone_outbound` entry. Both drivers share the spoken progress narration cadence (`src/calls/voice-progress-cadence.ts`, tuned by `voice.frontModel.progress`): the cadence owns the tool-activity log, the triggers (an ops burst, a long operation completing, a full interval of audible silence with news, the `maxSilenceMs` heartbeat) and the generated or static phrase, while each driver supplies its own view of audible silence (live voice from its TTS queue and playback-tail estimate; the media-stream transport from `isPlaybackIdle()` and a running sum of sent frame durations) and how to speak a phrase.
 
-Both drivers also share the per-turn latency marks (`src/calls/voice-metrics.ts`). The controller opens a turn's marks when it dispatches, seeded with when the caller's transcript arrived, and stamps the leg dispatch, the first assistant delta, the first audible audio, a barge-in, and how the turn settled. Live voice streams a snapshot to its client on every mark; a call has no client on the line, so the aggregate is logged once per turn, cancelled turns included. Each call also records a `phone_call_started` / `phone_call_ended` pair on the onboarding telemetry substrate (`src/telemetry/phone-call-funnel.ts`), written by the call store at session creation and at the single terminal status transition: duration is the gap between the two rows, and a call that took no caller turn carries why on the end row (`silent_no_connect` when it never connected, `silent_no_turn` when it did and nobody spoke).
+Both drivers also share the per-turn latency marks (`src/calls/voice-metrics.ts`). The controller opens a turn's marks when it dispatches, seeded with when the caller's transcript arrived and when the provider first had interim words for that same utterance, and stamps the leg dispatch, the first assistant delta, the first audible audio, a barge-in, an endpoint hold, and how the turn settled. A held turn settles as `endpoint_hold` and hands both seeds to the turn that finally answers, so the caller's wait is still measured from the moment they stopped talking. Live voice streams a snapshot to its client on every mark; a call has no client on the line, so the aggregate is logged once per turn, cancelled turns included. Each call also records a `phone_call_started` / `phone_call_ended` pair on the onboarding telemetry substrate (`src/telemetry/phone-call-funnel.ts`), written by the call store at session creation and at the single terminal status transition: duration is the gap between the two rows, and a call that took no caller turn carries why on the end row (`silent_no_connect` when it never connected, `silent_no_turn` when it did and nobody spoke).
 
 A credential preflight (`resolveTelephonyCredentialReadiness()` in `src/calls/telephony-credential-preflight.ts`) gates every call: it requires a credentialed, telephony-capable STT provider **and** a media-stream-playable TTS provider (the configured one or a credentialed playable fallback). Inbound calls that fail the preflight receive `<Say>` setup-required copy plus `<Hangup/>` instead of a doomed stream; outbound placement fails before dialing via `preflightVoiceIngress()` with the same user-facing message.
 
@@ -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";