@vellumai/assistant 0.3.27 → 0.3.28

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.
@@ -1874,6 +1909,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.3.27",
+  "version": "0.3.28",
   "type": "module",
   "bin": {
     "vellum": "./src/index.ts"

package/scripts/ipc/generate-swift.ts

@@ -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__/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__/bundled-asset.test.ts

@@ -0,0 +1,107 @@
+import { mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+
+import { resolveBundledDir } from '../util/bundled-asset.js';
+
+let tempDir: string;
+
+beforeEach(() => {
+  tempDir = join(tmpdir(), `bundled-asset-test-${crypto.randomUUID()}`);
+  mkdirSync(tempDir, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe('resolveBundledDir', () => {
+  test('source mode: returns join(callerDir, relativePath) when callerDir is a normal path', () => {
+    const result = resolveBundledDir('/some/source/path', 'templates', 'templates');
+    expect(result).toBe(join('/some/source/path', 'templates'));
+  });
+
+  test('source mode: does not check existsSync for the source path', () => {
+    // Even if the resolved path does not exist, it returns it as-is
+    const result = resolveBundledDir('/nonexistent/path', 'templates', 'templates');
+    expect(result).toBe(join('/nonexistent/path', 'templates'));
+  });
+
+  describe('compiled mode (/$bunfs/ prefix)', () => {
+    // In compiled mode, process.execPath determines fallback locations.
+    // We simulate by creating real directories at the expected fallback paths.
+
+    let savedExecPath: string;
+
+    beforeEach(() => {
+      savedExecPath = process.execPath;
+    });
+
+    afterEach(() => {
+      process.execPath = savedExecPath;
+    });
+
+    test('prefers Contents/Resources/<bundleName> when it exists', () => {
+      // Simulate macOS .app bundle: binary at Contents/MacOS/vellum-daemon
+      const macosDir = join(tempDir, 'Contents', 'MacOS');
+      const resourcesDir = join(tempDir, 'Contents', 'Resources');
+      mkdirSync(macosDir, { recursive: true });
+      mkdirSync(join(resourcesDir, 'templates'), { recursive: true });
+
+      process.execPath = join(macosDir, 'vellum-daemon');
+
+      const result = resolveBundledDir('/$bunfs/root/src/config', 'templates', 'templates');
+      expect(result).toBe(join(resourcesDir, 'templates'));
+    });
+
+    test('falls back to <execDir>/<bundleName> when Resources does not exist', () => {
+      // Simulate standalone binary deployment (no .app bundle)
+      const binDir = join(tempDir, 'bin');
+      mkdirSync(join(binDir, 'templates'), { recursive: true });
+
+      process.execPath = join(binDir, 'vellum-daemon');
+
+      const result = resolveBundledDir('/$bunfs/root/src/config', 'templates', 'templates');
+      expect(result).toBe(join(binDir, 'templates'));
+    });
+
+    test('falls back to source path when neither Resources nor execDir have the asset', () => {
+      const binDir = join(tempDir, 'bin');
+      mkdirSync(binDir, { recursive: true });
+      // Don't create any asset directories
+
+      process.execPath = join(binDir, 'vellum-daemon');
+
+      const result = resolveBundledDir('/$bunfs/root/src/config', 'templates', 'templates');
+      expect(result).toBe(join('/$bunfs/root/src/config', 'templates'));
+    });
+
+    test('Resources path takes priority over execDir path when both exist', () => {
+      const macosDir = join(tempDir, 'Contents', 'MacOS');
+      const resourcesDir = join(tempDir, 'Contents', 'Resources');
+      mkdirSync(macosDir, { recursive: true });
+      mkdirSync(join(resourcesDir, 'hook-templates'), { recursive: true });
+      // Also create at execDir level
+      mkdirSync(join(macosDir, 'hook-templates'), { recursive: true });
+
+      process.execPath = join(macosDir, 'vellum-daemon');
+
+      const result = resolveBundledDir('/$bunfs/root/src/hooks', '../../hook-templates', 'hook-templates');
+      expect(result).toBe(join(resourcesDir, 'hook-templates'));
+    });
+
+    test('works with different bundleName values', () => {
+      const macosDir = join(tempDir, 'Contents', 'MacOS');
+      const resourcesDir = join(tempDir, 'Contents', 'Resources');
+      mkdirSync(macosDir, { recursive: true });
+      mkdirSync(join(resourcesDir, 'prebuilt'), { recursive: true });
+
+      process.execPath = join(macosDir, 'vellum-daemon');
+
+      const result = resolveBundledDir('/$bunfs/root/src/home-base/prebuilt', '.', 'prebuilt');
+      expect(result).toBe(join(resourcesDir, 'prebuilt'));
+    });
+  });
+});