@vellumai/assistant 0.6.4 → 0.6.6

package/.prettierignore

@@ -5,3 +5,8 @@
 # Prompt template files use _ as a comment marker prefix. Prettier escapes
 # these to \_ which breaks the comment-stripping preprocessor.
 src/prompts/templates/**/*.md
+
+# Compaction prompt assets are consumed verbatim as the LLM system prompt.
+# Prettier's markdown formatting (blank lines between headers, trailing
+# newlines) would change the prompt content, so we skip formatting here.
+src/context/prompts/**/*.md

package/AGENTS.md

@@ -14,7 +14,15 @@ When you introduce a new env var that the assistant process needs to read at run
 
 ## Daemon startup philosophy
 
-The daemon must **never** block startup under *any circumstance*. All possible errors should be logged so that the assistant can recover from it's corrupted state after the fact.
+The daemon must **never** block startup under _any circumstance_. All possible errors should be logged so that the assistant can recover from it's corrupted state after the fact.
+
+## Post-execution hooks
+
+Tool post-execution hooks (`src/daemon/tool-side-effects.ts`) run after a tool executor returns. They are an **observation-and-notification layer** only: refresh client-side state, broadcast events, kick off orthogonal background work (e.g. icon generation). Hooks must not re-do work the executor already performed, and must not attempt recovery when the executor failed — failures surface in the tool result for the LLM to act on.
+
+Do not coordinate hook behaviour by re-parsing the tool's JSON response to infer what the executor did (e.g. "if field X is missing, retry step Y"). That couples the LLM-facing response shape to internal daemon logic and breaks silently when the response shape evolves. Keep the hook's logic independent of the result payload, or if the hook genuinely needs executor-internal state, pass it through a typed side channel — never through a JSON round-trip.
+
+Shared mutable resources written by more than one caller (e.g. `dist/` directories produced by `compileApp()`) must be serialised per-resource so concurrent callers cannot race on `rm -rf` + write sequences.
 
 ## Code comments
 

package/ARCHITECTURE.md

@@ -595,13 +595,13 @@ Audio-to-text conversion occurs in five distinct runtime boundaries, each with i
 
 **Boundary overview:**
 
-| Boundary                     | Runtime                                                                       | Provider (current)                             | Adapter module                                                                                                                                    | Caller                                                                                               |
-| ---------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| **Telephony (hybrid)**       | Twilio-native ConversationRelay or daemon media-stream (provider-conditional) | Configured STT provider (via `services.stt`)   | `src/calls/telephony-stt-routing.ts`                                                                                                              | `src/calls/twilio-routes.ts`                                                                         |
-| **Daemon batch**             | Daemon process (REST API to provider)                                         | Configured STT provider (via `services.stt`)   | `src/stt/daemon-batch-transcriber.ts`                                                                                                             | `src/runtime/routes/inbound-stages/transcribe-audio.ts`                                              |
-| **Conversation streaming**   | Daemon process (WebSocket-based)                                              | Deepgram or Google Gemini (via `services.stt`) | `src/stt/stt-stream-session.ts`, `src/providers/speech-to-text/deepgram-realtime.ts`, `src/providers/speech-to-text/google-gemini-live-stream.ts` | `VoiceInputManager` (macOS conversation), `InputBarView` (iOS conversation) via gateway WS proxy     |
-| **Client service-first**     | macOS / iOS via gateway → daemon                                              | Configured STT provider (via `services.stt`)   | `src/runtime/routes/stt-routes.ts`, `clients/shared/Network/STTClient.swift`                                                                      | `VoiceInputManager` (macOS dictation), `InputBarView` (iOS), `OpenAIVoiceService` (macOS voice mode) |
-| **Client-native (fallback)** | macOS / iOS on-device                                                         | Apple Speech (`SFSpeechRecognizer`)            | `clients/macos/.../SpeechRecognizerAdapter.swift`, `clients/ios/.../SpeechRecognizerAdapter.swift`                                                | Fallback when STT service is unconfigured or fails                                                   |
+| Boundary                     | Runtime                                                                       | Provider (current)                           | Adapter module                                                                                                                                                                                                                                             | Caller                                                                                               |
+| ---------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| **Telephony (hybrid)**       | Twilio-native ConversationRelay or daemon media-stream (provider-conditional) | Configured STT provider (via `services.stt`) | `src/calls/telephony-stt-routing.ts`                                                                                                                                                                                                                       | `src/calls/twilio-routes.ts`                                                                         |
+| **Daemon batch**             | Daemon process (REST API to provider)                                         | Configured STT provider (via `services.stt`) | `src/stt/daemon-batch-transcriber.ts`                                                                                                                                                                                                                      | `src/runtime/routes/inbound-stages/transcribe-audio.ts`                                              |
+| **Conversation streaming**   | Daemon process (WebSocket-based)                                              | Configured STT provider (via `services.stt`) | `src/stt/stt-stream-session.ts`, `src/providers/speech-to-text/deepgram-realtime.ts`, `src/providers/speech-to-text/google-gemini-live-stream.ts`, `src/providers/speech-to-text/openai-whisper-stream.ts`, `src/providers/speech-to-text/xai-realtime.ts` | `VoiceInputManager` (macOS conversation), `InputBarView` (iOS conversation) via gateway WS proxy     |
+| **Client service-first**     | macOS / iOS via gateway → daemon                                              | Configured STT provider (via `services.stt`) | `src/runtime/routes/stt-routes.ts`, `clients/shared/Network/STTClient.swift`                                                                                                                                                                               | `VoiceInputManager` (macOS dictation), `InputBarView` (iOS), `OpenAIVoiceService` (macOS voice mode) |
+| **Client-native (fallback)** | macOS / iOS on-device                                                         | Apple Speech (`SFSpeechRecognizer`)          | `clients/macos/.../SpeechRecognizerAdapter.swift`, `clients/ios/.../SpeechRecognizerAdapter.swift`                                                                                                                                                         | Fallback when STT service is unconfigured or fails                                                   |
 
 **Telephony boundary (hybrid routing):**
 
@@ -750,32 +750,28 @@ These differences are intentional — the adapters were designed for their respe
 
 ### Update Bulletin System
 
-Release-driven update notification system that surfaces release notes to the assistant via the system prompt.
+Release-driven update notification system that dispatches a background conversation to process release notes when a release lands.
 
 **Data flow:**
 
-1. **Bundled template** (`src/prompts/templates/UPDATES.md`) — source of release notes, maintained per-release in the repo.
-2. **Startup sync** (`syncUpdateBulletinOnStartup()` in `src/config/update-bulletin.ts`) — materializes the bundled template into the workspace `UPDATES.md` on daemon boot. Uses atomic write (temp + rename) for crash safety.
-3. **System prompt injection** — `buildSystemPrompt()` reads workspace `UPDATES.md` and injects it as a `## Recent Updates` section with judgment-based handling instructions.
-4. **Completion by deletion** — the assistant deletes `UPDATES.md` when it has actioned all updates. Next startup detects the deletion and marks those releases as completed in checkpoint state.
-5. **Cross-release merge** — if pending updates from a prior release exist when a new release lands, both release blocks coexist in the same file.
+1. **Storage** — Release notes live at `<workspace>/UPDATES.md`. The file is written by workspace migrations; each release that needs to surface notes ships a dedicated migration in `src/workspace/migrations/` that appends a release-notes block to the file. The workspace-migration runner is the authoritative idempotency mechanism: `runWorkspaceMigrations()` records each migration's `WorkspaceMigration.id` in `<workspace>/data/.workspace-migrations.json` and never re-runs an ID that is already in the `applied` set.
+2. **Dispatch** — At daemon startup (after `runWorkspaceMigrations()`), `runUpdateBulletinJobIfNeeded()` is invoked fire-and-forget. It hashes the current `UPDATES.md` content and compares against the `updates:last_processed_hash` checkpoint. When the hashes differ, it bootstraps a `conversationType: "background"` conversation and calls `wakeAgentForOpportunity()` so the agent processes the bulletin without any interactive session.
+3. **Completion** — The agent acts on the contents and deletes `UPDATES.md` when done. The job persists the new hash to `updates:last_processed_hash` post-wake, so subsequent startups short-circuit until the file is repopulated by a future migration.
 
 **Checkpoint keys** (in `memory_checkpoints` table):
 
-- `updates:active_releases` — JSON array of version strings currently active.
-- `updates:completed_releases` — JSON array of version strings already completed.
+- `updates:last_processed_hash` — content hash of the `UPDATES.md` payload most recently dispatched to the background job.
 
 **Key source files:**
 
-| File                                   | Purpose                                                   |
-| -------------------------------------- | --------------------------------------------------------- |
-| `src/prompts/templates/UPDATES.md`     | Bundled release-note template                             |
-| `src/config/update-bulletin.ts`        | Startup sync logic (materialize, delete-complete, merge)  |
-| `src/config/update-bulletin-format.ts` | Release block formatter/parser helpers                    |
-| `src/config/update-bulletin-state.ts`  | Checkpoint state helpers for active/completed releases    |
-| `src/prompts/system-prompt.ts`         | Prompt injection of updates section                       |
-| `src/daemon/config-watcher.ts`         | File watcher — evicts sessions on UPDATES.md changes      |
-| `src/permissions/defaults.ts`          | Auto-allow rules for file_read/write/edit + rm UPDATES.md |
+| File                                   | Purpose                                                                                   |
+| -------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `src/workspace/migrations/`            | Per-release migrations that append release notes to `UPDATES.md`                          |
+| `src/workspace/migrations/registry.ts` | Append-only `WORKSPACE_MIGRATIONS` registry                                               |
+| `src/prompts/update-bulletin-job.ts`   | `runUpdateBulletinJobIfNeeded()` — hash check, background dispatch, and checkpoint update |
+| `src/daemon/lifecycle.ts`              | Fire-and-forget dispatch of `runUpdateBulletinJobIfNeeded()` after DB init at startup     |
+| `src/config/schemas/updates.ts`        | `updates.enabled` config toggle (defaults to `true`; disables the background dispatch)    |
+| `src/permissions/defaults.ts`          | Auto-allow rules for file_read/write/edit + bare-filename `rm UPDATES.md`                 |
 
 ---
 
@@ -1049,13 +1045,11 @@ When all four reducer tiers are exhausted and the provider still rejects, the ov
 
 | Session Type    | Config Policy           | Action                                                                                                      |
 | --------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------- |
-| Interactive     | `"summarize"` (default) | `request_user_approval` — prompt the user via `PermissionPrompter` before compressing the latest turn       |
+| Interactive     | `"summarize"` (default) | `auto_compress_latest_turn` — compress without asking                                                       |
 | Non-interactive | `"truncate"` (default)  | `auto_compress_latest_turn` — compress without asking                                                       |
 | Any             | `"drop"`                | `fail_gracefully` — fall through to the final context-overflow fallback, which emits a `conversation_error` |
 
-**Approval gate:** For interactive sessions, the pipeline uses `requestCompressionApproval()` in `context-overflow-approval.ts`, which presents a confirmation prompt through the existing `PermissionPrompter` flow (`POST /v1/confirm`). The prompt uses a reserved pseudo tool name (`context_overflow_compression`) so the UI can display a meaningful label. The decision is one-shot per overflow (no "always allow" option).
-
-**Deny handling:** If the user declines compression, the session emits a graceful assistant explanation message ("The conversation has grown too long...") instead of a `conversation_error`. The deny message is persisted to conversation history and delivered via `assistant_text_delta` events, so the user sees a normal chat bubble rather than an error toast. The turn ends cleanly without triggering the error classification pipeline.
+When standard compaction has been exhausted and the provider still reports a context overflow, the recovery pipeline forces an emergency compaction of the latest turn with aggressive settings (`force: true`, `minKeepRecentUserTurns: 0`). The user is not prompted — compaction is always automatic. Users who want to opt out entirely can set `contextWindow.overflowRecovery.interactiveLatestTurnCompression` to `"drop"`, which short-circuits to a graceful failure instead.
 
 ### Config
 
@@ -1071,13 +1065,12 @@ All overflow recovery settings live under `contextWindow.overflowRecovery` in th
 
 ### Key Source Files
 
-| File                                      | Purpose                                                                          |
-| ----------------------------------------- | -------------------------------------------------------------------------------- |
-| `src/daemon/context-overflow-reducer.ts`  | Tiered reducer: four-tier pipeline with idempotent steps and cumulative state    |
-| `src/daemon/context-overflow-policy.ts`   | Overflow policy resolver: maps config + interactivity to concrete action         |
-| `src/daemon/context-overflow-approval.ts` | Approval gate: prompts user for latest-turn compression via `PermissionPrompter` |
-| `src/daemon/conversation-agent-loop.ts`   | Integration: preflight budget check, convergence loop, approval/deny flow        |
-| `src/config/core-schema.ts`               | `ContextOverflowRecoveryConfigSchema` with defaults and validation               |
+| File                                     | Purpose                                                                       |
+| ---------------------------------------- | ----------------------------------------------------------------------------- |
+| `src/daemon/context-overflow-reducer.ts` | Tiered reducer: four-tier pipeline with idempotent steps and cumulative state |
+| `src/daemon/context-overflow-policy.ts`  | Overflow policy resolver: maps config + interactivity to concrete action      |
+| `src/daemon/conversation-agent-loop.ts`  | Integration: preflight budget check, convergence loop, emergency compaction   |
+| `src/config/core-schema.ts`              | `ContextOverflowRecoveryConfigSchema` with defaults and validation            |
 
 ---
 
@@ -1566,22 +1559,24 @@ graph TB
 
     FIND_RULE -->|"Deny rule"| DENY["decision: deny<br/>Blocked by rule"]
     FIND_RULE -->|"Ask rule"| PROMPT_ASK["decision: prompt<br/>Always ask user"]
-    FIND_RULE -->|"Allow rule"| RISK_CHECK{"Risk level?"}
-    FIND_RULE -->|"No match"| NO_MATCH{"Fallback logic"}
+    FIND_RULE -->|"Allow rule / No match"| SANDBOX_CHECK{"sandboxAutoApprove?<br/>(bash + allowlisted +<br/>containerized)"}
+
+    SANDBOX_CHECK -->|"yes"| AUTO_SANDBOX["decision: allow<br/>Sandbox auto-approve"]
+    SANDBOX_CHECK -->|"no, has Allow rule"| RISK_CHECK{"Risk level?"}
+    SANDBOX_CHECK -->|"no, no match"| NO_MATCH{"Fallback logic"}
 
     RISK_CHECK -->|"Low / Medium"| AUTO_ALLOW["decision: allow<br/>Auto-allowed by rule"]
-    RISK_CHECK -->|"High"| HIGH_CHECK{"allowHighRisk<br/>on rule?"}
-    HIGH_CHECK -->|"true"| AUTO_ALLOW
-    HIGH_CHECK -->|"false / absent"| PROMPT_HIGH["decision: prompt<br/>High risk override"]
+    RISK_CHECK -->|"High"| RISK_THRESHOLD{"Risk-based<br/>threshold fallback"}
 
     NO_MATCH -->|"tool.origin === 'skill'"| PROMPT_SKILL["decision: prompt<br/>Skill tools always ask"]
     NO_MATCH -->|"strict mode"| PROMPT_STRICT["decision: prompt<br/>No implicit auto-allow"]
-    NO_MATCH -->|"workspace mode (default)"| WS_CHECK{"Workspace-scoped<br/>invocation?"}
+    NO_MATCH -->|"workspace mode (default)"| WS_CHECK{"Workspace-scoped<br/>+ Low risk?"}
     WS_CHECK -->|"yes"| AUTO_WS["decision: allow<br/>Workspace-scoped auto-allow"]
-    WS_CHECK -->|"no"| RISK_FALLBACK_WS{"Risk level?"}
-    RISK_FALLBACK_WS -->|"Low"| AUTO_WS_LOW["decision: allow<br/>Low risk auto-allow"]
-    RISK_FALLBACK_WS -->|"Medium"| PROMPT_WS_MED["decision: prompt"]
-    RISK_FALLBACK_WS -->|"High"| PROMPT_WS_HIGH["decision: prompt"]
+    WS_CHECK -->|"no"| RISK_THRESHOLD
+
+    RISK_THRESHOLD{"risk ≤ autoApproveUpTo<br/>threshold?"}
+    RISK_THRESHOLD -->|"yes"| AUTO_THRESHOLD["decision: allow<br/>within auto-approve threshold"]
+    RISK_THRESHOLD -->|"no"| PROMPT_THRESHOLD["decision: prompt<br/>above auto-approve threshold"]
 ```
 
 ### Permission Modes: Workspace and Strict
@@ -1599,7 +1594,7 @@ The `permissions.mode` config option (`workspace` or `strict`) controls the defa
 | `browser_*` skill tools with system default rules  | Auto-allowed (priority 100 allow rules)       | Auto-allowed (priority 100 allow rules)       |
 | Skill-origin tools with no matching rule           | Prompted                                      | Prompted                                      |
 | Allow rules for non-high-risk tools                | Auto-allowed                                  | Auto-allowed                                  |
-| Allow rules with `allowHighRisk: true`             | Auto-allowed (even high risk)                 | Auto-allowed (even high risk)                 |
+| Allow rules + containerized bash (high risk)       | Auto-allowed (runtime check)                  | Auto-allowed (runtime check)                  |
 | Deny rules                                         | Blocked                                       | Blocked                                       |
 
 **Workspace mode** (default) auto-allows operations scoped to the workspace (file reads/writes/edits within the workspace directory, sandboxed bash) without prompting. Host operations, network requests, and operations outside the workspace still follow the normal approval flow. Explicit deny and ask rules override auto-allow.
@@ -1621,7 +1616,6 @@ Rules are stored in `~/.vellum/protected/trust.json` with version `3`. Each rule
 | `decision`        | `allow \| deny \| ask` | What to do when the rule matches                                         |
 | `priority`        | `number`               | Higher priority wins; deny wins ties at equal priority                   |
 | `executionTarget` | `string?`              | `sandbox` or `host` — restricts by execution context                     |
-| `allowHighRisk`   | `boolean?`             | When true, auto-allows even high-risk invocations                        |
 
 Missing optional fields act as wildcards. A rule with no `executionTarget` matches any target.
 
@@ -1715,7 +1709,7 @@ When a permission prompt is sent to the client (via `confirmation_request` SSE e
 | `allowlistOptions` | Suggested patterns for "always allow" rules         |
 | `scopeOptions`     | Suggested scopes for rule persistence               |
 
-The user can respond with: `allow` (one-time), `always_allow` (create allow rule), `always_allow_high_risk` (create allow rule with `allowHighRisk: true`), `deny` (one-time), or `always_deny` (create deny rule).
+The user can respond with: `allow` (one-time), `always_allow` (create allow rule), `deny` (one-time), or `always_deny` (create deny rule). In containerized environments, commands tagged with `sandboxAutoApprove` in their risk spec are auto-allowed via the approval policy's sandbox auto-approve check; non-allowlisted commands (network tools, runtimes, package managers) use the user's `autoApproveUpTo` threshold. All other risk-based decisions use the `autoApproveUpTo` threshold (default: `"low"`) -- tools at or below the threshold are auto-allowed, those above are prompted.
 
 ### Canonical Paths
 
@@ -2094,7 +2088,7 @@ Connected channels are resolved at signal emission time: vellum is always includ
 
 **Audit trail (SQLite):** `notification_events` → `notification_decisions` (with `conversationActions` in validation results) → `notification_deliveries` (with `conversation_id`, `message_id`, `conversation_strategy`, `conversation_action`, `conversation_target_id`, `conversation_fallback_used`)
 
-**Configuration:** `notifications.decisionModelIntent` in `config.json`.
+**Configuration:** `llm.callSites.notificationDecision` (decision engine) and `llm.callSites.preferenceExtraction` (preference extractor) in `config.json`. Both fall back to `llm.default` when unset.
 
 ---
 

package/Dockerfile

@@ -24,8 +24,17 @@ COPY packages/egress-proxy ./packages/egress-proxy
 COPY assistant/package.json assistant/bun.lock ./assistant/
 RUN cd /app/assistant && bun install --frozen-lockfile
 
-# Copy source
-COPY assistant ./assistant
+# Copy bundled first-party skills and install their deps. The repo-root
+# .dockerignore is the single source of truth for which skills (and which
+# files within them) ship in the assistant image -- adding or removing a
+# bundled skill is a .dockerignore edit, not a Dockerfile edit.
+COPY skills ./skills
+RUN set -eu; for pkg in /app/skills/*/package.json; do \
+      [ -e "$pkg" ] || continue; \
+      dir="$(dirname "$pkg")"; \
+      echo "Installing dependencies for $dir"; \
+      (cd "$dir" && (bun install --frozen-lockfile 2>/dev/null || bun install)); \
+    done
 
 # Final stage
 FROM debian:trixie-slim@sha256:4ffb3a1511099754cddc70eb1b12e50ffdb67619aa0ab6c13fcd800a78ef7c7a AS runner
@@ -121,8 +130,13 @@ EXPOSE 3001
 ENV RUNTIME_HTTP_PORT=3001
 ENV IS_CONTAINERIZED=true
 
-# Copy from builder
+# Copy installed deps + shared packages + bundled skills from builder.
+# Skills stay in the builder copy because they require per-skill `bun install` runs.
 COPY --from=builder /app /app
+
+# Copy source separately to avoid invalidating builder layer.
+COPY assistant ./
+
 RUN chmod +x /app/assistant/docker-entrypoint.sh
 
 # Run the daemon + http server

package/README.md

@@ -47,9 +47,9 @@ cp .env.example .env
 
 ## Update Bulletin
 
-When a release includes relevant updates, the assistant materializes release notes from the bundled `src/prompts/templates/UPDATES.md` into `~/.vellum/workspace/UPDATES.md` on startup. The assistant uses judgment to surface updates to the user when relevant, and deletes the file when done.
+Release notes are surfaced via a background conversation dispatched at daemon startup. Workspace migrations write release notes to `<workspace>/UPDATES.md`; `runUpdateBulletinJobIfNeeded()` then spawns a `conversationType: "background"` conversation (via `wakeAgentForOpportunity()`) whenever the file's content hash changes. The agent uses judgment to surface updates to the user when relevant, and deletes the file when done.
 
-**For release maintainers:** Update `assistant/src/prompts/templates/UPDATES.md` with release notes before each relevant release. Leave the template empty (or comment-only) for releases with no user/assistant-facing changes.
+**For release maintainers:** Add a new migration under `assistant/src/workspace/migrations/0XX-release-notes-<slug>.ts` with the release notes inline as a string literal, and append the export to `WORKSPACE_MIGRATIONS` in `assistant/src/workspace/migrations/registry.ts`. Migrations are append-only. Idempotency is handled by the workspace-migration runner — `runWorkspaceMigrations()` records each migration's `WorkspaceMigration.id` in `<workspace>/data/.workspace-migrations.json` and never re-runs an ID that is already in the `applied` set, so release-notes migrations do not need an in-file guard. Skip the migration entirely for releases with no user/assistant-facing changes.
 
 ## Usage
 
@@ -86,7 +86,6 @@ bun run src/index.ts                # interactive CLI session
 | `assistant config set\|get\|list`                  | Manage configuration                             |
 | `assistant keys set\|list\|delete`                 | Manage API keys in secure storage                |
 | `assistant trust list\|remove\|clear`              | Manage trust rules                               |
-| `assistant doctor`                                 | Run diagnostic checks                            |
 
 ## Project Structure
 
@@ -204,7 +203,7 @@ The runtime exposes a RESTful HTTP API for Twilio configuration, credential mana
 | Method | Path                                        | Description                                                                                                                                 |
 | ------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
 | GET    | `/v1/integrations/twilio/config`            | Returns current state: `hasCredentials` (boolean) and `phoneNumber` (if assigned)                                                           |
-| POST   | `/v1/integrations/twilio/credentials`       | Validates and stores Account SID and Auth Token in secure storage (CES / encrypted file store)                                               |
+| POST   | `/v1/integrations/twilio/credentials`       | Validates and stores Account SID and Auth Token in secure storage (CES / encrypted file store)                                              |
 | DELETE | `/v1/integrations/twilio/credentials`       | Removes stored credentials. Preserves the phone number in config so re-entering credentials resumes working without reassigning the number. |
 | GET    | `/v1/integrations/twilio/numbers`           | Lists all incoming phone numbers on the Twilio account with their capabilities                                                              |
 | POST   | `/v1/integrations/twilio/numbers/provision` | Purchases a new phone number. Accepts optional `areaCode` and `country`. Auto-assigns and configures webhooks when ingress is available.    |

package/__tests__/permissions/gateway-threshold-reader.test.ts

@@ -0,0 +1,283 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+
+// ── Mocks ────────────────────────────────────────────────────────────────────
+
+let mockFeatureFlagEnabled = true;
+
+mock.module("../../src/config/assistant-feature-flags.js", () => ({
+  isAssistantFeatureFlagEnabled: (_key: string, _config: unknown) =>
+    mockFeatureFlagEnabled,
+}));
+
+mock.module("../../src/config/loader.js", () => ({
+  getConfig: () => ({}),
+}));
+
+// Track gatewayGet calls for assertion
+const gatewayGetCalls: string[] = [];
+let gatewayGetHandler: (path: string) => unknown = () => ({});
+
+mock.module("../../src/runtime/gateway-internal-client.js", () => ({
+  GatewayRequestError: class GatewayRequestError extends Error {
+    statusCode: number;
+    gatewayError: string | undefined;
+    constructor(message: string, statusCode: number, gatewayError?: string) {
+      super(message);
+      this.name = "GatewayRequestError";
+      this.statusCode = statusCode;
+      this.gatewayError = gatewayError;
+    }
+  },
+  gatewayGet: async <T>(path: string): Promise<T> => {
+    gatewayGetCalls.push(path);
+    return gatewayGetHandler(path) as T;
+  },
+}));
+
+// Suppress logger output in tests
+mock.module("../../src/util/logger.js", () => ({
+  getLogger: () => ({
+    warn: () => {},
+    info: () => {},
+    error: () => {},
+    debug: () => {},
+  }),
+}));
+
+import {
+  _clearGlobalCacheForTesting,
+  getAutoApproveThreshold,
+} from "../../src/permissions/gateway-threshold-reader.js";
+// Import GatewayRequestError from the mock so we can throw instances of it
+const { GatewayRequestError } =
+  await import("../../src/runtime/gateway-internal-client.js");
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function resetMocks(): void {
+  mockFeatureFlagEnabled = true;
+  gatewayGetCalls.length = 0;
+  gatewayGetHandler = () => ({});
+  _clearGlobalCacheForTesting();
+}
+
+afterEach(resetMocks);
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe("getAutoApproveThreshold", () => {
+  test("returns undefined when feature flag is off", async () => {
+    mockFeatureFlagEnabled = false;
+    const result = await getAutoApproveThreshold("conv-123", "conversation");
+    expect(result).toBeUndefined();
+    // Should not make any gateway calls
+    expect(gatewayGetCalls).toHaveLength(0);
+  });
+
+  test("returns global defaults when gateway returns them", async () => {
+    gatewayGetHandler = (path: string) => {
+      if (path === "/v1/permissions/thresholds") {
+        return {
+          interactive: "medium",
+          background: "low",
+          headless: "none",
+        };
+      }
+      return {};
+    };
+
+    // conversation maps to interactive
+    expect(await getAutoApproveThreshold(undefined, "conversation")).toBe(
+      "medium",
+    );
+
+    _clearGlobalCacheForTesting();
+
+    expect(await getAutoApproveThreshold(undefined, "background")).toBe("low");
+
+    _clearGlobalCacheForTesting();
+
+    expect(await getAutoApproveThreshold(undefined, "headless")).toBe("none");
+  });
+
+  test("returns conversation override when it exists", async () => {
+    gatewayGetHandler = (path: string) => {
+      if (path === "/v1/permissions/thresholds/conversations/conv-xyz") {
+        return { threshold: "medium" };
+      }
+      if (path === "/v1/permissions/thresholds") {
+        return {
+          interactive: "low",
+          background: "medium",
+          headless: "none",
+        };
+      }
+      return {};
+    };
+
+    const result = await getAutoApproveThreshold("conv-xyz", "conversation");
+    expect(result).toBe("medium");
+    // Should have called the conversation endpoint, not the global one
+    expect(gatewayGetCalls).toEqual([
+      "/v1/permissions/thresholds/conversations/conv-xyz",
+    ]);
+  });
+
+  test("falls back to global when conversation override returns 404", async () => {
+    gatewayGetHandler = (path: string) => {
+      if (path.startsWith("/v1/permissions/thresholds/conversations/")) {
+        throw new GatewayRequestError("Not found", 404, "Not found");
+      }
+      if (path === "/v1/permissions/thresholds") {
+        return {
+          interactive: "low",
+          background: "medium",
+          headless: "none",
+        };
+      }
+      return {};
+    };
+
+    const result = await getAutoApproveThreshold("conv-123", "conversation");
+    expect(result).toBe("low");
+    // Should have called both endpoints
+    expect(gatewayGetCalls).toEqual([
+      "/v1/permissions/thresholds/conversations/conv-123",
+      "/v1/permissions/thresholds",
+    ]);
+  });
+
+  test("falls back to hardcoded defaults on gateway error", async () => {
+    gatewayGetHandler = () => {
+      throw new Error("Connection refused");
+    };
+
+    // conversation → "low"
+    expect(await getAutoApproveThreshold(undefined, "conversation")).toBe(
+      "low",
+    );
+
+    _clearGlobalCacheForTesting();
+
+    // background → "medium"
+    expect(await getAutoApproveThreshold(undefined, "background")).toBe(
+      "medium",
+    );
+
+    _clearGlobalCacheForTesting();
+
+    // headless → "none"
+    expect(await getAutoApproveThreshold(undefined, "headless")).toBe("none");
+  });
+
+  test("falls back to hardcoded defaults on non-404 conversation error", async () => {
+    gatewayGetHandler = (path: string) => {
+      if (path.startsWith("/v1/permissions/thresholds/conversations/")) {
+        throw new GatewayRequestError("Internal error", 500, "Server error");
+      }
+      // Should not reach global endpoint
+      return {
+        interactive: "medium",
+        background: "medium",
+        headless: "medium",
+      };
+    };
+
+    const result = await getAutoApproveThreshold("conv-123", "conversation");
+    // Should fall back to hardcoded default for conversation, not global endpoint
+    expect(result).toBe("low");
+    // Should have only called the conversation endpoint
+    expect(gatewayGetCalls).toEqual([
+      "/v1/permissions/thresholds/conversations/conv-123",
+    ]);
+  });
+
+  test("caching: second call within 30s does not re-fetch global", async () => {
+    let fetchCount = 0;
+    gatewayGetHandler = (path: string) => {
+      if (path === "/v1/permissions/thresholds") {
+        fetchCount++;
+        return {
+          interactive: "medium",
+          background: "low",
+          headless: "none",
+        };
+      }
+      return {};
+    };
+
+    // First call — should fetch
+    const first = await getAutoApproveThreshold(undefined, "conversation");
+    expect(first).toBe("medium");
+    expect(fetchCount).toBe(1);
+
+    // Second call — should use cache
+    const second = await getAutoApproveThreshold(undefined, "background");
+    expect(second).toBe("low");
+    expect(fetchCount).toBe(1); // Still 1, cache hit
+
+    // Third call — still cached
+    const third = await getAutoApproveThreshold(undefined, "headless");
+    expect(third).toBe("none");
+    expect(fetchCount).toBe(1); // Still 1
+
+    // After clearing cache, should re-fetch
+    _clearGlobalCacheForTesting();
+    const fourth = await getAutoApproveThreshold(undefined, "conversation");
+    expect(fourth).toBe("medium");
+    expect(fetchCount).toBe(2); // Incremented
+  });
+
+  test("defaults executionContext to conversation when omitted", async () => {
+    gatewayGetHandler = (path: string) => {
+      if (path === "/v1/permissions/thresholds") {
+        return {
+          interactive: "medium",
+          background: "low",
+          headless: "none",
+        };
+      }
+      return {};
+    };
+
+    // executionContext omitted — should default to "conversation" → interactive
+    const result = await getAutoApproveThreshold(undefined, undefined);
+    expect(result).toBe("medium");
+  });
+
+  test("skips conversation override when no conversationId", async () => {
+    gatewayGetHandler = (path: string) => {
+      if (path === "/v1/permissions/thresholds") {
+        return {
+          interactive: "low",
+          background: "medium",
+          headless: "none",
+        };
+      }
+      return {};
+    };
+
+    const result = await getAutoApproveThreshold(undefined, "conversation");
+    expect(result).toBe("low");
+    // Should only call global endpoint, not conversation
+    expect(gatewayGetCalls).toEqual(["/v1/permissions/thresholds"]);
+  });
+
+  test("skips conversation override for non-conversation contexts", async () => {
+    gatewayGetHandler = (path: string) => {
+      if (path === "/v1/permissions/thresholds") {
+        return {
+          interactive: "low",
+          background: "medium",
+          headless: "none",
+        };
+      }
+      return {};
+    };
+
+    // Even with a conversationId, background context should not check conversation override
+    const result = await getAutoApproveThreshold("conv-123", "background");
+    expect(result).toBe("medium");
+    expect(gatewayGetCalls).toEqual(["/v1/permissions/thresholds"]);
+  });
+});

package/bun.lock

@@ -11,6 +11,8 @@
         "@modelcontextprotocol/sdk": "1.27.1",
         "@qdrant/js-client-rest": "1.17.0",
         "@resvg/resvg-js": "2.6.2",
+        "@resvg/resvg-js-darwin-arm64": "2.6.2",
+        "@resvg/resvg-js-darwin-x64": "2.6.2",
         "@sentry/node": "10.43.0",
         "@vellumai/ces-contracts": "file:../packages/ces-contracts",
         "@vellumai/credential-storage": "file:../packages/credential-storage",
@@ -30,6 +32,7 @@
         "postgres": "3.4.8",
         "qrcode": "1.5.4",
         "rrule": "2.8.1",
+        "tar-stream": "3.1.7",
         "tldts": "7.0.25",
         "tree-sitter-bash": "0.25.1",
         "uuid": "11.1.0",
@@ -54,8 +57,8 @@
     },
   },
   "overrides": {
-    "lodash": "^4.18.0",
-    "path-to-regexp": "^8.4.0",
+    "lodash": "4.18.1",
+    "path-to-regexp": "8.4.2",
   },
   "packages": {
     "@agentclientprotocol/sdk": ["@agentclientprotocol/sdk@0.16.1", "", { "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" } }, "sha512-1ad+Sc/0sCtZGHthxxvgEUo5Wsbw16I+aF+YwdiLnPwkZG8KAGUEAPK6LM6Pf69lCyJPt1Aomk1d+8oE3C4ZEw=="],
@@ -986,7 +989,7 @@
 
     "strip-json-comments": ["strip-json-comments@5.0.3", "", {}, "sha512-1tB5mhVo7U+ETBKNf92xT4hrQa3pm0MZ0PQvuDnWgAAGHDsfp4lPSpiS6psrSiet87wyGPh9ft6wmhOMQ0hDiw=="],
 
-    "tar-stream": ["tar-stream@3.1.8", "", { "dependencies": { "b4a": "^1.6.4", "bare-fs": "^4.5.5", "fast-fifo": "^1.2.0", "streamx": "^2.15.0" } }, "sha512-U6QpVRyCGHva435KoNWy9PRoi2IFYCgtEhq9nmrPPpbRacPs9IH4aJ3gbrFC8dPcXvdSZ4XXfXT5Fshbp2MtlQ=="],
+    "tar-stream": ["tar-stream@3.1.7", "", { "dependencies": { "b4a": "^1.6.4", "fast-fifo": "^1.2.0", "streamx": "^2.15.0" } }, "sha512-qJj60CXt7IU1Ffyc3NJMjh6EkuCFej46zUqJ4J7pqYlThyd9bO0XBTmcOIhSzZJVWfsLks0+nle/j538YAW9RQ=="],
 
     "teex": ["teex@1.0.1", "", { "dependencies": { "streamx": "^2.12.5" } }, "sha512-eYE6iEI62Ni1H8oIa7KlDU6uQBtqr4Eajni3wX7rpfXD8ysFx8z0+dri+KWEPWpBsxXfxu58x/0jvTVT1ekOSg=="],
 
@@ -1096,6 +1099,8 @@
 
     "ajv-formats/ajv": ["ajv@8.18.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A=="],
 
+    "archiver/tar-stream": ["tar-stream@3.1.8", "", { "dependencies": { "b4a": "^1.6.4", "bare-fs": "^4.5.5", "fast-fifo": "^1.2.0", "streamx": "^2.15.0" } }, "sha512-U6QpVRyCGHva435KoNWy9PRoi2IFYCgtEhq9nmrPPpbRacPs9IH4aJ3gbrFC8dPcXvdSZ4XXfXT5Fshbp2MtlQ=="],
+
     "cross-spawn/which": ["which@2.0.2", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "./bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="],
 
     "ecdsa-sig-formatter/safe-buffer": ["safe-buffer@5.2.1", "", {}, "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ=="],