@vellumai/assistant 0.3.27 → 0.4.0

package/ARCHITECTURE.md

@@ -18,7 +18,7 @@ This document owns assistant-runtime architecture details. The repo-level archit
 - The same resolver is used by:
   - `/channels/inbound` (Telegram/SMS/WhatsApp path) before run orchestration.
   - Inbound Twilio voice setup (`RelayConnection.handleSetup`) to seed call-time actor context.
-- Runtime channel runs pass this as `guardianContext`, and session runtime assembly injects `<guardian_context>` into provider-facing prompts.
+- Runtime channel runs pass this as `guardianContext`, and session runtime assembly injects `<inbound_actor_context>` (via `inboundActorContextFromGuardian()`) into provider-facing prompts.
 - Voice calls mirror the same prompt contract: `CallController` receives guardian context on setup and refreshes it immediately after successful voice challenge verification, so the first post-verification turn is grounded as `actor_role: guardian`.
 - Voice-specific behavior (DTMF/speech verification flow, relay state machine) remains voice-local; only actor-role resolution is shared.
 
@@ -62,6 +62,41 @@ All guardian approval decisions — regardless of how they arrive — route thro
 | `src/daemon/ipc-contract/guardian-actions.ts` | IPC message type definitions for guardian action requests/responses |
 | `src/runtime/channel-approval-types.ts` | Channel-facing approval action types and `toApprovalActionOptions` bridge |
 
+### Canonical Guardian Request System
+
+The canonical guardian request system provides a channel-agnostic, unified domain for all guardian approval and question flows. It replaces the fragmented per-channel storage with a single source of truth that works identically for voice calls, Telegram/SMS/WhatsApp, and desktop UI.
+
+**Architecture layers:**
+
+1. **Canonical domain (single source of truth):** All guardian requests — tool approvals, pending questions, access requests — are persisted in the `canonical_guardian_requests` table (`src/memory/canonical-guardian-store.js`). Each request has a unique ID, a short human-readable request code, and a status that follows a CAS (compare-and-swap) lifecycle: `pending` -> `approved` | `denied` | `expired` | `cancelled`. Deliveries (notifications sent to guardians) are tracked in `canonical_guardian_deliveries`.
+
+2. **Unified apply primitive (single write path):** `applyCanonicalGuardianDecision()` in `src/approvals/guardian-decision-primitive.ts` is the single write path for all guardian decisions. It enforces identity validation, expiry checks, CAS resolution, `approve_always` downgrade (guardian-on-behalf invariant), kind-specific resolver dispatch via the resolver registry, and scoped grant minting. All callers — HTTP API, IPC handlers, inbound channel router, desktop session — route decisions through this function.
+
+3. **Shared reply router (priority-ordered routing):** `routeGuardianReply()` in `src/runtime/guardian-reply-router.ts` provides a single entry point for all inbound guardian reply processing across channels. It routes through a priority-ordered pipeline: (a) deterministic callback parsing (button presses with `apr:<requestId>:<action>`), (b) request code parsing (6-char alphanumeric prefix), (c) NL classification via the conversational approval engine. All decisions flow through `applyCanonicalGuardianDecision`.
+
+4. **Deterministic API (prompt listing and decision endpoints):** Desktop clients and API consumers use `GET /v1/guardian-actions/pending` and `POST /v1/guardian-actions/decision` (HTTP) or the equivalent IPC messages. These endpoints surface canonical requests alongside legacy pending interactions and channel approval records, with deduplication to avoid double-rendering.
+
+5. **Dual-mode (deterministic + conversational):** Guardians can respond via structured button UIs (deterministic path) or free-text conversation (NL path). Both paths converge on the same canonical primitive. Code-only messages (just a request code without decision text) return clarification instead of auto-approving. Disambiguation with multiple pending requests stays fail-closed — no auto-resolve when the target is ambiguous.
+
+**Resolver registry:** Kind-specific resolvers (`src/approvals/guardian-request-resolvers.ts`) handle side effects after CAS resolution. Built-in resolvers: `tool_approval` (channel/desktop approval path) and `pending_question` (voice call question path). New request kinds register resolvers without touching the core primitive.
+
+**Expiry sweeps:** Three complementary sweeps run on 60-second intervals to clean up stale requests:
+- `src/calls/guardian-action-sweep.ts` — voice call guardian action requests
+- `src/runtime/routes/guardian-expiry-sweep.ts` — channel guardian approval requests
+- `src/runtime/routes/canonical-guardian-expiry-sweep.ts` — canonical guardian requests (CAS-safe)
+
+**Key source files:**
+
+| File | Purpose |
+|------|---------|
+| `src/memory/canonical-guardian-store.ts` | Canonical request and delivery persistence (CRUD, CAS resolve, list with filters) |
+| `src/approvals/guardian-decision-primitive.ts` | Unified decision primitive: `applyCanonicalGuardianDecision` (canonical) and `applyGuardianDecision` (legacy) |
+| `src/approvals/guardian-request-resolvers.ts` | Resolver registry: kind-specific side-effect dispatch after CAS resolution |
+| `src/runtime/guardian-reply-router.ts` | Shared inbound router: callback -> code -> NL classification pipeline |
+| `src/runtime/routes/guardian-action-routes.ts` | HTTP endpoints for prompt listing and decision submission |
+| `src/daemon/handlers/guardian-actions.ts` | IPC handlers for desktop socket clients |
+| `src/runtime/routes/canonical-guardian-expiry-sweep.ts` | Canonical request expiry sweep |
+
 ### Outbound Guardian Verification (HTTP Endpoints)
 
 Guardian verification can be initiated through gateway HTTP endpoints (which forward to runtime handlers) as an alternative to the legacy IPC-only flow. This enables chat-first verification where the assistant guides the user through guardian setup via normal conversation.
@@ -357,26 +392,56 @@ A complementary access-granting flow where the guardian proactively creates a sh
 
 **Inbound intercept points:** Invite token extraction runs early in the inbound handler, before ACL denial, so valid invites short-circuit the membership check. Two intercept branches handle: (a) non-members — the invite creates their first member record; (b) inactive members (revoked/pending) — the invite reactivates them.
 
-**Deferred channel adapters:**
+**Channel adapter status:**
 
 | Channel | Status | Prerequisites |
 |---------|--------|--------------|
 | Telegram | Shipped | Bot username resolved from credential metadata or `TELEGRAM_BOT_USERNAME` env |
+| Voice | Shipped | Identity-bound voice code redemption via DTMF/speech in the relay state machine. Gated behind `feature_flags.voice-invite-redemption.enabled` (default OFF). |
 | SMS | Deferred | Needs a deep-link strategy compatible with SMS (short URL or web redemption page) |
 | Slack | Deferred | Needs DM-safe ingress — Socket Mode handles channel messages but DM-initiated invite flows need routing |
-| Voice | Deferred | Needs DTMF or speech-based token capture integrated with the voice relay state machine |
+
+### Voice Invite Flow (invite_redemption_pending)
+
+Voice invites use a short numeric code (4-10 digits, default 6) instead of a URL token. The guardian creates an invite bound to the invitee's E.164 phone number; the invitee redeems it by entering the code during an inbound voice call.
+
+**Creation flow:**
+1. Guardian creates a voice invite via `POST /v1/ingress/invites` with `sourceChannel: "voice"` and `expectedExternalUserId` (E.164 phone).
+2. `ingress-service.ts` generates a cryptographically random numeric code (`generateVoiceCode`), hashes it with SHA-256 (`hashVoiceCode`), and stores only the hash.
+3. The one-time plaintext `voiceCode` is returned in the creation response. The raw token is NOT returned for voice invites — redemption uses the identity-bound code flow exclusively.
+4. Guardian communicates the code to the invitee out-of-band.
+
+**Call-time redemption subflow (`invite_redemption_pending`):**
+1. Unknown caller dials in. `relay-server.ts` resolves trust via `resolveActorTrust`. Caller is `unknown`, no pending guardian challenge.
+2. If `feature_flags.voice-invite-redemption.enabled` is ON, the relay checks `findActiveVoiceInvites` for invites bound to the caller's phone number.
+3. If active, non-expired invites exist, the relay enters the `invite_redemption_pending` state (reuses the `verification_pending` connection state) and prompts the caller to enter their invite code via DTMF or speech.
+4. `redeemVoiceInviteCode` validates: identity match, code hash match, expiry, use count. On success, an active member record is upserted and the call transitions to the normal call flow.
+5. On failure, the caller gets up to 3 attempts. After max attempts, the call is terminated.
+
+**Security invariants:**
+- The plaintext voice code is returned exactly once at creation time and never stored.
+- Voice invites are identity-bound: `expectedExternalUserId` must match the caller's E.164 number. An attacker with the code but the wrong phone number cannot redeem.
+- Failure responses are intentionally generic (`invalid_or_expired`) to prevent oracle attacks.
+- Blocked members cannot bypass the guardian's explicit block via invite redemption.
+
+**Feature flag:** `feature_flags.voice-invite-redemption.enabled` (default OFF). When disabled, unknown callers with active voice invites are denied normally — the invite check is skipped entirely.
 
 **Key source files:**
 
 | File | Purpose |
 |------|---------|
-| `src/runtime/invite-redemption-service.ts` | Core redemption engine — token validation, member creation, discriminated-union outcomes |
+| `src/runtime/invite-redemption-service.ts` | Core redemption engine — token validation, voice code redemption, member creation, discriminated-union outcomes |
 | `src/runtime/invite-redemption-templates.ts` | Deterministic reply templates for each redemption outcome |
 | `src/runtime/channel-invite-transport.ts` | Transport adapter registry with `buildShareableInvite` / `extractInboundToken` interface |
 | `src/runtime/channel-invite-transports/telegram.ts` | Telegram adapter — `t.me/<bot>?start=iv_<token>` deep links, `/start iv_<token>` extraction |
+| `src/runtime/channel-invite-transports/voice.ts` | Voice transport adapter — code-based redemption metadata |
 | `src/daemon/guardian-invite-intent.ts` | Intent detection — routes create/list/revoke requests into the trusted-contacts skill |
 | `src/runtime/ingress-service.ts` | Shared business logic for invite/member operations (used by both HTTP routes and IPC) |
+| `src/runtime/routes/ingress-routes.ts` | HTTP API handlers for member/invite management including voice invite creation and redemption |
 | `src/runtime/routes/inbound-message-handler.ts` | Invite token intercept in the inbound flow (non-member and inactive-member branches) |
+| `src/calls/relay-server.ts` | Voice relay state machine — `invite_redemption_pending` subflow, feature flag gate |
+| `src/util/voice-code.ts` | Cryptographic voice code generation and SHA-256 hashing |
+| `src/memory/ingress-invite-store.ts` | Invite persistence including `findActiveVoiceInvites` for identity-bound lookup |
 
 ### Update Bulletin System
 
@@ -1874,6 +1939,18 @@ Connected channels are resolved at signal emission time: vellum is always includ
 
 
 
+### Sensitive Tool Output Placeholder Substitution
+
+Some tool outputs contain values that must reach the user's final reply but should never be visible to the LLM (e.g., invite tokens). The system handles this with a three-stage pipeline:
+
+1. **Directive extraction** (`src/tools/sensitive-output-placeholders.ts`): Tool output may include `<vellum-sensitive-output kind="invite_code" value="<raw>" />` directives. The executor strips directives, replaces raw values with deterministic placeholders (`VELLUM_ASSISTANT_INVITE_CODE_<shortId>`), and attaches `sensitiveBindings` metadata to the tool result.
+
+2. **Placeholder-only model context**: The agent loop stores placeholder->value bindings in a per-run `substitutionMap`. Tool results sent to the LLM contain only placeholders — the model generates conversational text referencing them without ever seeing the real values.
+
+3. **Post-generation substitution** (`src/agent/loop.ts`): Before emitting streamed `text_delta` events and before building the final `assistantMessage`, all placeholders are deterministically replaced with their real values. The substitution is chunk-safe for streaming (buffering partial placeholder prefixes across deltas).
+
+Key files: `src/tools/sensitive-output-placeholders.ts`, `src/tools/executor.ts` (extraction hook), `src/agent/loop.ts` (substitution), `src/config/vellum-skills/trusted-contacts/SKILL.md` (invite flow adoption).
+
 ### Notifications
 
 For full notification developer guidance and lifecycle details, see [`assistant/src/notifications/README.md`](src/notifications/README.md).

package/Dockerfile

@@ -1,5 +1,5 @@
 # Use debian as base image
-FROM debian:bookworm AS builder
+FROM debian:trixie@sha256:3615a749858a1cba49b408fb49c37093db813321355a9ab7c1f9f4836341e9db AS builder
 
 WORKDIR /app
 
@@ -26,7 +26,7 @@ RUN bun install --frozen-lockfile
 COPY . .
 
 # Final stage
-FROM debian:bookworm AS runner
+FROM debian:trixie@sha256:3615a749858a1cba49b408fb49c37093db813321355a9ab7c1f9f4836341e9db AS runner
 
 WORKDIR /app
 

package/bun.lock

@@ -8,7 +8,6 @@
         "@anthropic-ai/claude-agent-sdk": "^0.2.42",
         "@anthropic-ai/sdk": "^0.39.0",
         "@google/genai": "^1.40.0",
-        "@huggingface/transformers": "^3.8.1",
         "@modelcontextprotocol/sdk": "^1.15.1",
         "@qdrant/js-client-rest": "^1.16.2",
         "@sentry/node": "^10.38.0",
@@ -35,6 +34,7 @@
         "zod": "^4.3.6",
       },
       "devDependencies": {
+        "@huggingface/transformers": "^3.8.1",
         "@pydantic/logfire-node": "^0.13.0",
         "@types/archiver": "^7.0.0",
         "@types/bun": "^1.2.4",
@@ -46,6 +46,7 @@
         "eslint-plugin-simple-import-sort": "^12.1.1",
         "fast-check": "^4.5.3",
         "knip": "^5.83.1",
+        "prettier": "^3.8.1",
         "quicktype-core": "^23.2.6",
         "typescript": "^5.7.3",
         "typescript-eslint": "^8.54.0",
@@ -1136,6 +1137,8 @@
 
     "prelude-ls": ["prelude-ls@1.2.1", "", {}, "sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g=="],
 
+    "prettier": ["prettier@3.8.1", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg=="],
+
     "process": ["process@0.11.10", "", {}, "sha512-cdGef/drWFoydD1JsMzuFf8100nZl+GT+yacc2bEced5f9Rjk4z+WtFUTBu9PhOi9j/jfmBPu0mMEY4wIdAF8A=="],
 
     "process-nextick-args": ["process-nextick-args@2.0.1", "", {}, "sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag=="],

package/docs/trusted-contact-access.md

@@ -13,8 +13,15 @@ Design doc defining how unknown users gain access to a Vellum assistant via chan
 ## User Journey
 
 1. **Unknown user messages the assistant** on Telegram (or SMS, or any channel).
-2. **Assistant rejects the message** via the ingress ACL in `inbound-message-handler.ts`. The user has no `assistant_ingress_members` record, so the handler replies: *"Sorry, you haven't been approved to message this assistant. You can ask its Guardian for an invite."* and returns `{ denied: true, reason: 'not_a_member' }`.
-3. **Notification pipeline alerts the guardian.** The rejection triggers `emitNotificationSignal()` with `sourceEventName: 'ingress.access_request'`, routing through the decision engine to all connected channels (vellum macOS app, Telegram, etc.). The guardian sees who is requesting access.
+2. **Assistant rejects the message** via the ingress ACL in `inbound-message-handler.ts`. The user has no `assistant_ingress_members` record, so the handler replies: *"Hmm looks like you don't have access to talk to me. I'll let them know you tried talking to me and get back to you."* and returns `{ denied: true, reason: 'not_a_member' }`.
+3. **Notification pipeline alerts the guardian.** The rejection triggers `notifyGuardianOfAccessRequest()` which creates a canonical access request and calls `emitNotificationSignal()` with `sourceEventName: 'ingress.access_request'`. The notification routes through the decision engine to all connected channels (vellum macOS app, Telegram, etc.). The guardian sees who is requesting access, including a request code for approve/reject and an `open invite flow` option to start the Trusted Contacts invite flow.
+
+   **Guardian binding resolution for access requests** uses a fallback strategy:
+   1. Source-channel active binding first (e.g., Telegram binding for a Telegram access request).
+   2. Any active binding for the assistant on another channel (deterministic: most recently verified first, then alphabetical by channel).
+   3. No guardian identity — the notification pipeline delivers via trusted/vellum channels even when no channel binding exists.
+
+   This ensures unknown inbound access attempts always trigger guardian notification, even when the requester's source channel has no guardian binding.
 4. **Guardian approves the request.** The guardian responds to the notification (via Telegram inline button, macOS app, or IPC). On approval, the assistant creates a verification session via `createOutboundSession()` and generates a 6-digit verification code.
 5. **Guardian receives the verification code.** The assistant delivers the code to the guardian's verified channel (Telegram chat, SMS, etc.).
 6. **Guardian gives the code to the requester out-of-band** (in person, text message, phone call, etc.). This out-of-band transfer is the trust anchor: it proves the requester has a real-world relationship with the guardian.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.3.27",
+  "version": "0.4.0",
   "type": "module",
   "bin": {
     "vellum": "./src/index.ts"
@@ -14,6 +14,8 @@
     "ipc:inventory:update": "bun run scripts/ipc/check-contract-inventory.ts --update",
     "generate:ipc": "bun run scripts/ipc/generate-swift.ts",
     "check:ipc-generated": "bun run scripts/ipc/generate-swift.ts --check",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
     "ipc:check-swift-drift": "bun run scripts/ipc/check-swift-decoder-drift.ts",
     "lint": "eslint",
     "typecheck": "bunx tsc --noEmit",
@@ -28,7 +30,6 @@
     "@anthropic-ai/sdk": "^0.39.0",
     "@google/genai": "^1.40.0",
     "@modelcontextprotocol/sdk": "^1.15.1",
-    "@huggingface/transformers": "^3.8.1",
     "@qdrant/js-client-rest": "^1.16.2",
     "@sentry/node": "^10.38.0",
     "agentmail": "^0.1.0",
@@ -65,9 +66,11 @@
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "fast-check": "^4.5.3",
     "knip": "^5.83.1",
+    "prettier": "^3.8.1",
     "quicktype-core": "^23.2.6",
     "typescript": "^5.7.3",
     "typescript-eslint": "^8.54.0",
-    "typescript-json-schema": "^0.67.1"
+    "typescript-json-schema": "^0.67.1",
+    "@huggingface/transformers": "^3.8.1"
   }
 }

package/scripts/ipc/generate-swift.ts

@@ -94,9 +94,9 @@ function generateSchemas(): Record<string, SchemaDef> {
 
   const program = TJS.getProgramFromFiles(contractFiles, {
     strict: true,
-    target: 99,
-    module: 199,
-    moduleResolution: 99,
+    target: 'es2022',
+    module: 'commonjs',
+    moduleResolution: 'node',
     skipLibCheck: true,
   });
 
@@ -411,14 +411,18 @@ function emitStruct(s: SwiftStruct): string {
   const lines: string[] = [];
 
   if (s.doc) {
-    lines.push(`/// ${s.doc}`);
+    for (const docLine of s.doc.split('\n')) {
+      lines.push(`/// ${docLine}`);
+    }
   }
 
   lines.push(`public struct ${s.name}: Codable, Sendable {`);
 
   for (const p of s.properties) {
     if (p.doc) {
-      lines.push(`    /// ${p.doc}`);
+      for (const docLine of p.doc.split('\n')) {
+        lines.push(`    /// ${docLine}`);
+      }
     }
     lines.push(`    public let ${p.swiftName}: ${p.swiftType}`);
   }

package/src/__tests__/__snapshots__/ipc-snapshot.test.ts.snap

@@ -1302,6 +1302,15 @@ exports[`IPC message snapshots ServerMessage types message_complete serializes t
 }
 `;
 
+exports[`IPC message snapshots ServerMessage types message_request_complete serializes to expected JSON 1`] = `
+{
+  "requestId": "req-inline-001",
+  "runStillActive": true,
+  "sessionId": "sess-001",
+  "type": "message_request_complete",
+}
+`;
+
 exports[`IPC message snapshots ServerMessage types session_info serializes to expected JSON 1`] = `
 {
   "correlationId": "corr-001",
@@ -3112,3 +3121,74 @@ exports[`IPC message snapshots ServerMessage types generate_avatar_response seri
   "type": "generate_avatar_response",
 }
 `;
+
+exports[`IPC message snapshots ClientMessage types guardian_actions_pending_request serializes to expected JSON 1`] = `
+{
+  "conversationId": "conv-guardian-001",
+  "type": "guardian_actions_pending_request",
+}
+`;
+
+exports[`IPC message snapshots ClientMessage types guardian_action_decision serializes to expected JSON 1`] = `
+{
+  "action": "approve_once",
+  "conversationId": "conv-guardian-001",
+  "requestId": "req-guardian-001",
+  "type": "guardian_action_decision",
+}
+`;
+
+exports[`IPC message snapshots ClientMessage types reorder_threads serializes to expected JSON 1`] = `
+{
+  "type": "reorder_threads",
+  "updates": [
+    {
+      "displayOrder": 0,
+      "isPinned": false,
+      "sessionId": "sess-001",
+    },
+    {
+      "displayOrder": 1,
+      "isPinned": true,
+      "sessionId": "sess-002",
+    },
+  ],
+}
+`;
+
+exports[`IPC message snapshots ServerMessage types guardian_actions_pending_response serializes to expected JSON 1`] = `
+{
+  "conversationId": "conv-guardian-001",
+  "prompts": [
+    {
+      "actions": [
+        {
+          "action": "approve_once",
+          "label": "Approve once",
+        },
+        {
+          "action": "reject",
+          "label": "Reject",
+        },
+      ],
+      "callSessionId": null,
+      "conversationId": "conv-guardian-001",
+      "expiresAt": 1700100000000,
+      "questionText": "Approve tool: bash",
+      "requestCode": "REQ-GU",
+      "requestId": "req-guardian-001",
+      "state": "pending",
+      "toolName": "bash",
+    },
+  ],
+  "type": "guardian_actions_pending_response",
+}
+`;
+
+exports[`IPC message snapshots ServerMessage types guardian_action_decision_response serializes to expected JSON 1`] = `
+{
+  "applied": true,
+  "requestId": "req-guardian-001",
+  "type": "guardian_action_decision_response",
+}
+`;

package/src/__tests__/agent-loop-thinking.test.ts

@@ -44,7 +44,7 @@ describe('AgentLoop thinking budget clamping', () => {
     const config = lastConfig()!;
     const thinking = config.thinking as { type: string; budget_tokens: number };
     expect(thinking.type).toBe('enabled');
-    expect(thinking.budget_tokens).toBe(4095); // clamped to maxTokens - 1
+    expect(thinking.budget_tokens).toBe(3072); // clamped to floor(maxTokens * 0.75)
   });
 
   test('does not clamp when budget_tokens is within max_tokens', async () => {

package/src/__tests__/agent-loop.test.ts

@@ -1167,4 +1167,123 @@ describe('AgentLoop', () => {
     expect(sentBlock).toBeDefined();
     expect(sentBlock!.content).toBe(smallContent);
   });
+
+  // ---------------------------------------------------------------------------
+  // Sensitive output placeholder substitution tests
+  // ---------------------------------------------------------------------------
+
+  // 32. Tool results with sensitiveBindings populate substitution map and
+  //     final assistant message text is resolved with real values.
+  test('resolves sensitive output placeholders in final assistant message', async () => {
+    const placeholder = 'VELLUM_ASSISTANT_INVITE_CODE_TEST1234';
+    const realToken = 'realInviteToken999';
+
+    const { provider, calls } = createMockProvider([
+      toolUseResponse('t1', 'bash', { command: 'create invite' }),
+      // The LLM responds using the placeholder (it never saw the real token)
+      textResponse(`Here is your invite link: https://t.me/bot?start=iv_${placeholder}`),
+    ]);
+
+    const toolExecutor = async () => ({
+      content: `https://t.me/bot?start=iv_${placeholder}`,
+      isError: false,
+      sensitiveBindings: [{ kind: 'invite_code' as const, placeholder, value: realToken }],
+    });
+
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+    const events: AgentEvent[] = [];
+    const history = await loop.run([userMessage], collectEvents(events));
+
+    // The final assistant message in HISTORY should retain placeholders
+    // (so the model never sees real values on subsequent turns)
+    const lastAssistant = history[history.length - 1];
+    expect(lastAssistant.role).toBe('assistant');
+    const historyTextBlock = lastAssistant.content.find(
+      (b): b is Extract<ContentBlock, { type: 'text' }> => b.type === 'text',
+    );
+    expect(historyTextBlock).toBeDefined();
+    expect(historyTextBlock!.text).toContain(placeholder);
+    expect(historyTextBlock!.text).not.toContain(realToken);
+
+    // The message_complete EVENT should also retain placeholders (persisted
+    // to conversation store; real values leak on session reload otherwise)
+    const completeEvents = events.filter(
+      (e): e is Extract<AgentEvent, { type: 'message_complete' }> => e.type === 'message_complete',
+    );
+    const lastComplete = completeEvents[completeEvents.length - 1];
+    const completeText = lastComplete.message.content.find(
+      (b): b is Extract<ContentBlock, { type: 'text' }> => b.type === 'text',
+    );
+    expect(completeText!.text).toContain(placeholder);
+    expect(completeText!.text).not.toContain(realToken);
+
+    // The tool result content in provider history should contain the PLACEHOLDER,
+    // NOT the raw token (model never sees the real value)
+    const secondCallMessages = calls[1].messages;
+    const toolResultMsg = secondCallMessages.find(
+      (m) => m.role === 'user' && m.content.some((b) => b.type === 'tool_result'),
+    );
+    expect(toolResultMsg).toBeDefined();
+    const toolResultBlock = toolResultMsg!.content.find(
+      (b): b is Extract<ContentBlock, { type: 'tool_result' }> => b.type === 'tool_result',
+    );
+    expect(toolResultBlock!.content).toContain(placeholder);
+    expect(toolResultBlock!.content).not.toContain(realToken);
+  });
+
+  // 33. Streamed text_delta events have placeholders resolved to real values
+  test('resolves sensitive output placeholders in streamed text_delta events', async () => {
+    const placeholder = 'VELLUM_ASSISTANT_INVITE_CODE_STRM5678';
+    const realToken = 'streamedRealToken';
+
+    const { provider } = createMockProvider([
+      toolUseResponse('t1', 'bash', { command: 'invite' }),
+      // Response text includes the placeholder
+      textResponse(`Link: https://t.me/bot?start=iv_${placeholder}`),
+    ]);
+
+    const toolExecutor = async () => ({
+      content: `https://t.me/bot?start=iv_${placeholder}`,
+      isError: false,
+      sensitiveBindings: [{ kind: 'invite_code' as const, placeholder, value: realToken }],
+    });
+
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+    const events: AgentEvent[] = [];
+    await loop.run([userMessage], collectEvents(events));
+
+    // Collect all text_delta events from the final turn (after tool result)
+    const textDeltas = events.filter(
+      (e): e is Extract<AgentEvent, { type: 'text_delta' }> => e.type === 'text_delta',
+    );
+    const allStreamedText = textDeltas.map((e) => e.text).join('');
+
+    // Streamed text should contain the real token, not the placeholder
+    expect(allStreamedText).toContain(realToken);
+    expect(allStreamedText).not.toContain(placeholder);
+  });
+
+  // 34. Without sensitive bindings, text passes through unchanged
+  test('text passes through unchanged when no sensitive bindings exist', async () => {
+    const { provider } = createMockProvider([
+      toolUseResponse('t1', 'read_file', { path: '/test.txt' }),
+      textResponse('Normal response with no placeholders.'),
+    ]);
+
+    const toolExecutor = async () => ({
+      content: 'file contents',
+      isError: false,
+      // No sensitiveBindings
+    });
+
+    const loop = new AgentLoop(provider, 'system', {}, dummyTools, toolExecutor);
+    const events: AgentEvent[] = [];
+    const history = await loop.run([userMessage], collectEvents(events));
+
+    const lastAssistant = history[history.length - 1];
+    const textBlock = lastAssistant.content.find(
+      (b): b is Extract<ContentBlock, { type: 'text' }> => b.type === 'text',
+    );
+    expect(textBlock!.text).toBe('Normal response with no placeholders.');
+  });
 });

package/src/__tests__/approval-routes-http.test.ts

@@ -36,6 +36,8 @@ mock.module('../util/logger.js', () => ({
 
 mock.module('../config/loader.js', () => ({
   getConfig: () => ({
+    ui: {},
+    
     model: 'test',
     provider: 'test',
     apiKeys: {},
@@ -79,8 +81,11 @@ function makeIdleSession(opts?: {
     setAssistantId: () => {},
     setGuardianContext: () => {},
     setCommandIntent: () => {},
+    setTurnChannelContext: () => {},
+    setTurnInterfaceContext: () => {},
     updateClient: () => {},
     enqueueMessage: () => ({ queued: false, requestId: 'noop' }),
+    hasAnyPendingConfirmation: () => false,
     runAgentLoop: async (_content: string, _messageId: string, onEvent: (msg: ServerMessage) => void) => {
       onEvent({ type: 'assistant_text_delta', text: 'Hello!' });
       onEvent({ type: 'message_complete', sessionId: 'test-session' });
@@ -118,8 +123,11 @@ function makeConfirmationEmittingSession(opts?: {
     setAssistantId: () => {},
     setGuardianContext: () => {},
     setCommandIntent: () => {},
+    setTurnChannelContext: () => {},
+    setTurnInterfaceContext: () => {},
     updateClient: () => {},
     enqueueMessage: () => ({ queued: false, requestId: 'noop' }),
+    hasAnyPendingConfirmation: () => false,
     runAgentLoop: async (_content: string, _messageId: string, onEvent: (msg: ServerMessage) => void) => {
       // Emit confirmation_request — this triggers the hub publisher to register
       // the pending interaction
@@ -549,8 +557,8 @@ describe('standalone approval endpoints — HTTP layer', () => {
       });
 
       expect(res.status).toBe(403);
-      const body = await res.json() as { error: string };
-      expect(body.error).toContain('pattern');
+      const body = await res.json() as { error: { message: string; code?: string } };
+      expect(body.error.message).toContain('pattern');
 
       await stopServer();
     });
@@ -579,8 +587,8 @@ describe('standalone approval endpoints — HTTP layer', () => {
       });
 
       expect(res.status).toBe(403);
-      const body = await res.json() as { error: string };
-      expect(body.error).toContain('scope');
+      const body = await res.json() as { error: { message: string; code?: string } };
+      expect(body.error.message).toContain('scope');
 
       await stopServer();
     });
@@ -637,7 +645,7 @@ describe('standalone approval endpoints — HTTP layer', () => {
       const res = await fetch(url('messages'), {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
-        body: JSON.stringify({ conversationKey: 'conv-auto', content: 'Run ls', sourceChannel: 'vellum' }),
+        body: JSON.stringify({ conversationKey: 'conv-auto', content: 'Run ls', sourceChannel: 'vellum', interface: 'macos' }),
       });
       expect(res.status).toBe(202);
 

package/src/__tests__/asset-materialize-tool.test.ts

@@ -30,6 +30,8 @@ mock.module('../util/logger.js', () => ({
 
 mock.module('../config/loader.js', () => ({
   getConfig: () => ({
+    ui: {},
+    
     model: 'test',
     provider: 'test',
     apiKeys: {},

package/src/__tests__/asset-search-tool.test.ts

@@ -29,6 +29,8 @@ mock.module('../util/logger.js', () => ({
 
 mock.module('../config/loader.js', () => ({
   getConfig: () => ({
+    ui: {},
+    
     model: 'test',
     provider: 'test',
     apiKeys: {},

package/src/__tests__/assistant-events-sse-hardening.test.ts

@@ -37,6 +37,8 @@ mock.module('../util/logger.js', () => ({
 
 mock.module('../config/loader.js', () => ({
   getConfig: () => ({
+    ui: {},
+    
     model: 'test',
     provider: 'test',
     apiKeys: {},
@@ -181,8 +183,8 @@ describe('SSE route — capacity limit', () => {
 
     const response = handleSubscribeAssistantEvents(req, new URL(req.url), { hub });
     expect(response.status).toBe(503);
-    const body = await response.json() as { error: string };
-    expect(body.error).toMatch(/Too many concurrent connections/);
+    const body = await response.json() as { error: { message: string; code?: string } };
+    expect(body.error.message).toMatch(/Too many concurrent connections/);
   });
 
   test('returns 200 when hub has remaining capacity', () => {

package/src/__tests__/attachments-store.test.ts

@@ -27,6 +27,8 @@ mock.module('../util/logger.js', () => ({
 
 mock.module('../config/loader.js', () => ({
   getConfig: () => ({
+    ui: {},
+    
     model: 'test',
     provider: 'test',
     apiKeys: {},

package/src/__tests__/browser-skill-endstate.test.ts

@@ -64,10 +64,10 @@ describe('browser skill migration end-state', () => {
 
   test('startup tool definition count is reduced (no browser tools)', () => {
     const definitions = getAllToolDefinitions();
-    // Startup has ~31 definitions (no browser tools).
+    // Startup has ~15 eager + ~11 explicit definitions (no browser tools).
     // Allow wider drift for unrelated tool additions while still failing if
-    // browser tools are reintroduced at startup (+10 definitions).
-    expect(definitions.length).toBeGreaterThanOrEqual(25);
+    // browser tools are reintroduced at startup (+14 definitions).
+    expect(definitions.length).toBeGreaterThanOrEqual(10);
     expect(definitions.length).toBeLessThanOrEqual(50);
 
     const defNames = definitions.map((d) => d.name);