@vellumai/assistant 0.3.28 → 0.4.0

package/ARCHITECTURE.md

@@ -392,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
 

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.28",
+  "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,
   });
 

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__/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);

package/src/__tests__/call-controller.test.ts

@@ -32,6 +32,8 @@ mock.module('../util/logger.js', () => ({
 
 mock.module('../config/loader.js', () => ({
   getConfig: () => ({
+    ui: {},
+    
     provider: 'anthropic',
     providerOrder: ['anthropic'],
     apiKeys: { anthropic: 'test-key' },
@@ -47,6 +49,7 @@ mock.module('../config/loader.js', () => ({
       model: undefined,
     },
     memory: { enabled: false },
+    notifications: { decisionModelIntent: 'latency-optimized' },
   }),
 }));
 
@@ -127,11 +130,11 @@ import {
   updateCallSession,
 } from '../calls/call-store.js';
 import type { RelayConnection } from '../calls/relay-server.js';
-import { getDb, initializeDb, resetDb } from '../memory/db.js';
 import {
-  getGuardianActionRequest,
-  getPendingRequestByCallSessionId,
-} from '../memory/guardian-action-store.js';
+  getCanonicalGuardianRequest,
+  getPendingCanonicalRequestByCallSessionId,
+} from '../memory/canonical-guardian-store.js';
+import { getDb, initializeDb, resetDb } from '../memory/db.js';
 import { conversations } from '../memory/schema.js';
 
 initializeDb();
@@ -192,6 +195,8 @@ function ensureConversation(id: string): void {
 
 function resetTables() {
   const db = getDb();
+  db.run('DELETE FROM canonical_guardian_deliveries');
+  db.run('DELETE FROM canonical_guardian_requests');
   db.run('DELETE FROM guardian_action_deliveries');
   db.run('DELETE FROM guardian_action_requests');
   db.run('DELETE FROM call_pending_questions');
@@ -631,7 +636,7 @@ describe('call-controller', () => {
   test('handleCallerUtterance: passes guardian context to startVoiceTurn', async () => {
     const guardianCtx = {
       sourceChannel: 'voice' as const,
-      actorRole: 'non-guardian' as const,
+      trustClass: 'trusted_contact' as const,
       guardianExternalUserId: '+15550009999',
       guardianChatId: '+15550009999',
       requesterExternalUserId: '+15550002222',
@@ -683,13 +688,13 @@ describe('call-controller', () => {
   test('setGuardianContext: subsequent turns use updated guardian context', async () => {
     const initialCtx = {
       sourceChannel: 'voice' as const,
-      actorRole: 'unverified_channel' as const,
+      trustClass: 'unknown' as const,
       denialReason: 'no_binding' as const,
     };
 
     const upgradedCtx = {
       sourceChannel: 'voice' as const,
-      actorRole: 'guardian' as const,
+      trustClass: 'guardian' as const,
       guardianExternalUserId: '+15550003333',
       guardianChatId: '+15550003333',
     };
@@ -1163,7 +1168,7 @@ describe('call-controller', () => {
     await new Promise((r) => setTimeout(r, 10));
 
     // Verify a guardian action request was created
-    const pendingRequest = getPendingRequestByCallSessionId(session.id);
+    const pendingRequest = getPendingCanonicalRequestByCallSessionId(session.id);
     expect(pendingRequest).not.toBeNull();
     expect(pendingRequest!.status).toBe('pending');
 
@@ -1175,11 +1180,10 @@ describe('call-controller', () => {
     // Wait for the consultation timeout
     await new Promise((r) => setTimeout(r, 200));
 
-    // The guardian action request should now be expired with call_timeout reason
-    const timedOutRequest = getGuardianActionRequest(pendingRequest!.id);
+    // The canonical guardian request should now be expired
+    const timedOutRequest = getCanonicalGuardianRequest(pendingRequest!.id);
     expect(timedOutRequest).not.toBeNull();
     expect(timedOutRequest!.status).toBe('expired');
-    expect(timedOutRequest!.expiredReason).toBe('call_timeout');
 
     // Event should be recorded
     const events = getCallEvents(session.id);
@@ -1277,7 +1281,7 @@ describe('call-controller', () => {
     expect(question!.questionText).toBe('Allow send_email to bob@example.com?');
 
     // Verify the guardian action request has tool metadata
-    const pendingRequest = getPendingRequestByCallSessionId(session.id);
+    const pendingRequest = getPendingCanonicalRequestByCallSessionId(session.id);
     expect(pendingRequest).not.toBeNull();
     expect(pendingRequest!.toolName).toBe('send_email');
     expect(pendingRequest!.inputDigest).not.toBeNull();
@@ -1305,7 +1309,7 @@ describe('call-controller', () => {
     await controller.handleCallerUtterance('Send it');
     await new Promise((r) => setTimeout(r, 50));
 
-    const request1 = getPendingRequestByCallSessionId(session.id);
+    const request1 = getPendingCanonicalRequestByCallSessionId(session.id);
     expect(request1).not.toBeNull();
 
     // Compute expected digest independently using the same utility
@@ -1326,7 +1330,7 @@ describe('call-controller', () => {
     await new Promise((r) => setTimeout(r, 50));
 
     // Verify the guardian action request has NO tool metadata
-    const pendingRequest = getPendingRequestByCallSessionId(session.id);
+    const pendingRequest = getPendingCanonicalRequestByCallSessionId(session.id);
     expect(pendingRequest).not.toBeNull();
     expect(pendingRequest!.toolName).toBeNull();
     expect(pendingRequest!.inputDigest).toBeNull();
@@ -1384,7 +1388,7 @@ describe('call-controller', () => {
     expect(question!.questionText).toBe('Allow send_message?');
 
     // Verify tool metadata was parsed correctly
-    const pendingRequest = getPendingRequestByCallSessionId(session.id);
+    const pendingRequest = getPendingCanonicalRequestByCallSessionId(session.id);
     expect(pendingRequest).not.toBeNull();
     expect(pendingRequest!.toolName).toBe('send_message');
     expect(pendingRequest!.inputDigest).not.toBeNull();
@@ -1411,7 +1415,7 @@ describe('call-controller', () => {
     await controller.handleCallerUtterance('Do something');
     await new Promise((r) => setTimeout(r, 50));
 
-    const pendingRequest = getPendingRequestByCallSessionId(session.id);
+    const pendingRequest = getPendingCanonicalRequestByCallSessionId(session.id);
     expect(pendingRequest).not.toBeNull();
     expect(pendingRequest!.questionText).toBe('Fallback question?');
     // Tool metadata should be null since the approval marker was malformed
@@ -1547,7 +1551,7 @@ describe('call-controller', () => {
 
     const firstQuestionId = controller.getPendingConsultationQuestionId();
     expect(firstQuestionId).not.toBeNull();
-    const firstRequest = getPendingRequestByCallSessionId(session.id);
+    const firstRequest = getPendingCanonicalRequestByCallSessionId(session.id);
     expect(firstRequest).not.toBeNull();
 
     // Repeated ASK_GUARDIAN with same informational question (no tool metadata)
@@ -1559,7 +1563,7 @@ describe('call-controller', () => {
 
     // Should coalesce: same consultation ID, same request
     expect(controller.getPendingConsultationQuestionId()).toBe(firstQuestionId);
-    const currentRequest = getPendingRequestByCallSessionId(session.id);
+    const currentRequest = getPendingCanonicalRequestByCallSessionId(session.id);
     expect(currentRequest).not.toBeNull();
     expect(currentRequest!.id).toBe(firstRequest!.id);
     expect(currentRequest!.status).toBe('pending');
@@ -1589,7 +1593,7 @@ describe('call-controller', () => {
 
     const firstQuestionId = controller.getPendingConsultationQuestionId();
     expect(firstQuestionId).not.toBeNull();
-    const firstRequest = getPendingRequestByCallSessionId(session.id);
+    const firstRequest = getPendingCanonicalRequestByCallSessionId(session.id);
     expect(firstRequest).not.toBeNull();
 
     // Repeated ASK_GUARDIAN_APPROVAL with same tool/input
@@ -1601,7 +1605,7 @@ describe('call-controller', () => {
 
     // Should coalesce: same consultation, same request
     expect(controller.getPendingConsultationQuestionId()).toBe(firstQuestionId);
-    const currentRequest = getPendingRequestByCallSessionId(session.id);
+    const currentRequest = getPendingCanonicalRequestByCallSessionId(session.id);
     expect(currentRequest!.id).toBe(firstRequest!.id);
     expect(currentRequest!.status).toBe('pending');
 
@@ -1623,7 +1627,7 @@ describe('call-controller', () => {
     await controller.handleCallerUtterance('Send email');
     await new Promise((r) => setTimeout(r, 50));
 
-    const firstRequest = getPendingRequestByCallSessionId(session.id);
+    const firstRequest = getPendingCanonicalRequestByCallSessionId(session.id);
     expect(firstRequest).not.toBeNull();
     expect(firstRequest!.toolName).toBe('send_email');
 
@@ -1640,18 +1644,15 @@ describe('call-controller', () => {
     await new Promise((r) => setTimeout(r, 100));
 
     // New consultation should be active
-    const secondRequest = getPendingRequestByCallSessionId(session.id);
+    const secondRequest = getPendingCanonicalRequestByCallSessionId(session.id);
     expect(secondRequest).not.toBeNull();
     expect(secondRequest!.id).not.toBe(firstRequest!.id);
     expect(secondRequest!.toolName).toBe('calendar_create');
 
-    // Old request should be expired with 'superseded' reason
-    const expiredRequest = getGuardianActionRequest(firstRequest!.id);
+    // Old request should be expired (superseded by the new one)
+    const expiredRequest = getCanonicalGuardianRequest(firstRequest!.id);
     expect(expiredRequest).not.toBeNull();
     expect(expiredRequest!.status).toBe('expired');
-    expect(expiredRequest!.expiredReason).toBe('superseded');
-    expect(expiredRequest!.supersededByRequestId).toBe(secondRequest!.id);
-    expect(expiredRequest!.supersededAt).not.toBeNull();
 
     controller.destroy();
   });
@@ -1671,7 +1672,7 @@ describe('call-controller', () => {
     await controller.handleCallerUtterance('Send email to Bob');
     await new Promise((r) => setTimeout(r, 50));
 
-    const firstRequest = getPendingRequestByCallSessionId(session.id);
+    const firstRequest = getPendingCanonicalRequestByCallSessionId(session.id);
     expect(firstRequest).not.toBeNull();
     expect(firstRequest!.toolName).toBe('send_email');
 
@@ -1685,7 +1686,7 @@ describe('call-controller', () => {
     await new Promise((r) => setTimeout(r, 50));
 
     // Should coalesce: the inherited tool metadata matches the existing consultation
-    const currentRequest = getPendingRequestByCallSessionId(session.id);
+    const currentRequest = getPendingCanonicalRequestByCallSessionId(session.id);
     expect(currentRequest!.id).toBe(firstRequest!.id);
     expect(currentRequest!.status).toBe('pending');