@vellumai/assistant 0.3.16 → 0.3.19

package/ARCHITECTURE.md

@@ -22,6 +22,10 @@ This document owns assistant-runtime architecture details. The repo-level archit
 - 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.
 
+### Channel-Agnostic Scoped Approval Grants
+
+Scoped approval grants allow a guardian's approval decision on one channel (e.g., Telegram) to authorize a tool execution on a different channel (e.g., voice). Two scope modes exist: `request_id` (bound to a specific pending request) and `tool_signature` (bound to `toolName` + canonical `inputDigest`). Grants are one-time-use, exact-match, fail-closed, and TTL-bound. Full architecture details (lifecycle flow, security invariants, key files) live in [`docs/architecture/security.md`](docs/architecture/security.md#channel-agnostic-scoped-approval-grants).
+
 ### Outbound Guardian Verification (HTTP Endpoints)
 
 Guardian verification can be initiated through the runtime HTTP API 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.
@@ -218,7 +222,7 @@ The app token is validated by format only — it must start with `xapp-`.
 
 **Connection status:**
 
-The `GET` endpoint reports `connected: true` only when both `hasBotToken` and `hasAppToken` are true. If only one token is stored, a `warning` field describes which token is missing.
+Both `GET` and `POST` endpoints report `connected: true` only when both `hasBotToken` and `hasAppToken` are true. The `POST` endpoint additionally returns a `warning` field when only one token is stored, describing which token is missing.
 
 **Key source files:**
 
@@ -276,6 +280,33 @@ External users who are not the guardian can gain access to the assistant through
 | `src/memory/channel-guardian-store.ts` | Approval request and verification challenge persistence |
 | `src/config/vellum-skills/trusted-contacts/SKILL.md` | Skill teaching the assistant to manage contacts via HTTP API |
 
+### Update Bulletin System
+
+Release-driven update notification system that surfaces release notes to the assistant via the system prompt.
+
+**Data flow:**
+1. **Bundled template** (`src/config/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.
+
+**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.
+
+**Key source files:**
+
+| File | Purpose |
+|------|---------|
+| `src/config/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/config/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 |
+
 ---
 
 
@@ -1543,9 +1574,10 @@ Keep-alive heartbeats (every 30 s by default):
 The notification module (`assistant/src/notifications/`) uses a signal-based architecture where producers emit free-form events and an LLM-backed decision engine determines whether, where, and how to notify the user. See `assistant/src/notifications/README.md` for the full developer guide.
 
 ```
-Producer → NotificationSignal → Decision Engine (LLM) → Deterministic Checks → Broadcaster → Conversation Pairing → Adapters → Delivery
-                                       ↑                                                            ↓
-                               Preference Summary                                    notification_thread_created IPC
+Producer → NotificationSignal → Candidate Generation → Decision Engine (LLM) → Deterministic Checks → Broadcaster → Conversation Pairing → Adapters → Delivery
+                                                              ↑                                                            ↓
+                                                      Preference Summary                                    notification_thread_created IPC
+                                                      Thread Candidates                                     (creation-only — not emitted on reuse)
 ```
 
 ### Channel Policy Registry
@@ -1560,13 +1592,18 @@ Producer → NotificationSignal → Decision Engine (LLM) → Deterministic Chec
 
 Helper functions: `getDeliverableChannels()`, `getChannelPolicy()`, `isNotificationDeliverable()`, `getConversationStrategy()`.
 
-### Conversation Pairing
+### Conversation Pairing and Thread Routing
 
-Every notification delivery materializes a conversation + seed message **before** the adapter sends it (`conversation-pairing.ts`). This ensures:
+Every notification delivery materializes a conversation + seed message **before** the adapter sends it (`conversation-pairing.ts`). The pairing function now accepts a `threadAction` from the decision engine:
+
+- **`reuse_existing`**: Looks up the target conversation. If valid (exists with `source: 'notification'`), the seed message is appended to the existing thread. If invalid, falls back to creating a new conversation with `threadDecisionFallbackUsed: true`.
+- **`start_new` (default)**: Creates a fresh conversation per delivery.
+
+This ensures:
 
 1. Every delivery has an auditable conversation trail in the conversations table
 2. The macOS/iOS client can deep-link directly into the notification thread
-3. Delivery audit rows in `notification_deliveries` carry `conversation_id`, `message_id`, and `conversation_strategy` columns
+3. Delivery audit rows in `notification_deliveries` carry `conversation_id`, `message_id`, `conversation_strategy`, `thread_action`, `thread_target_conversation_id`, and `thread_decision_fallback_used` columns
 
 The pairing function (`pairDeliveryWithConversation`) is resilient — errors are caught and logged without breaking the delivery pipeline.
 
@@ -1577,19 +1614,42 @@ The notification pipeline uses a single conversation materialization path across
 1. **Canonical pipeline** (`emitNotificationSignal` → decision engine → broadcaster → conversation pairing → adapters): The broadcaster pairs each delivery with a conversation, then dispatches a `notification_intent` IPC event via the Vellum adapter. The IPC payload includes `deepLinkMetadata` (e.g. `{ conversationId }`) so the macOS/iOS client can deep-link to the relevant context when the user taps the notification.
 2. **Guardian bookkeeping** (`dispatchGuardianQuestion`): Guardian dispatch creates `guardian_action_request` / `guardian_action_delivery` audit rows derived from pipeline delivery results and the per-dispatch `onThreadCreated` callback — there is no separate thread-creation path.
 
-### Thread Surfacing via `notification_thread_created` IPC
+### Thread Surfacing via `notification_thread_created` IPC (Creation-Only)
+
+The `notification_thread_created` IPC event is emitted **only when a brand-new conversation is created** by the broadcaster. Reusing an existing thread does not trigger this event — the macOS/iOS client already knows about the conversation from the original creation. This is enforced in `broadcaster.ts` by gating on `pairing.createdNewConversation === true`.
 
-When a vellum notification thread is paired with a conversation (strategy `start_new_conversation`), the broadcaster emits a `notification_thread_created` IPC event **immediately** (before waiting for slower channel deliveries like Telegram). This pushes the thread to the macOS/iOS client so it can display the notification thread in the sidebar and deep-link to it.
+When a new vellum notification thread is created (strategy `start_new_conversation`), the broadcaster emits the IPC event **immediately** (before waiting for slower channel deliveries like Telegram). This pushes the thread to the macOS/iOS client so it can display the notification thread in the sidebar and deep-link to it.
 
 ### IPC Thread-Created Events
 
 Two IPC push events surface new threads in the macOS/iOS client sidebar:
 
-- **`notification_thread_created`** — Emitted by `broadcaster.ts` when a notification delivery creates a vellum conversation (strategy `start_new_conversation`). Payload: `{ conversationId, title, sourceEventName }`.
+- **`notification_thread_created`** — Emitted by `broadcaster.ts` when a notification delivery **creates** a new vellum conversation (strategy `start_new_conversation`, `createdNewConversation: true`). **Not** emitted when a thread is reused. Payload: `{ conversationId, title, sourceEventName }`.
 - **`task_run_thread_created`** — Emitted by `work-item-runner.ts` when a task run creates a conversation. Payload: `{ conversationId, workItemId, title }`.
 
 All events follow the same pattern: the daemon creates a server-side conversation, persists an initial message, and broadcasts the IPC event so the macOS `ThreadManager` can create a visible thread in the sidebar.
 
+### Thread Routing Decision Flow
+
+The decision engine produces per-channel thread actions using a candidate-driven approach:
+
+1. **Candidate generation** (`thread-candidates.ts`): Queries recent notification-sourced conversations (24-hour window, up to 5 per channel) and enriches them with guardian context (pending request counts).
+2. **LLM decision**: The candidate set is serialized into the system prompt. The LLM chooses `start_new` or `reuse_existing` (with a candidate `conversationId`) per channel.
+3. **Strict validation** (`validateThreadActions`): Reuse targets must exist in the candidate set. Invalid targets are downgraded to `start_new`.
+4. **Pairing execution**: `pairDeliveryWithConversation` executes the thread action — appending to an existing conversation on reuse, creating a new one otherwise.
+5. **IPC gating**: `notification_thread_created` fires only on actual creation, not on reuse.
+6. **Audit trail**: Thread actions are persisted in both `notification_decisions.validation_results` and `notification_deliveries` columns (`thread_action`, `thread_target_conversation_id`, `thread_decision_fallback_used`).
+
+### Guardian Multi-Request Disambiguation in Reused Threads
+
+When the decision engine routes multiple guardian questions to the same conversation (via `reuse_existing`), those questions share a single thread. The guardian disambiguates which question they are answering using **request-code prefixes**:
+
+- **Single pending delivery**: Matched automatically (single-match fast path).
+- **Multiple pending deliveries**: The guardian must prefix their reply with the 6-char hex request code (e.g. `A1B2C3 yes, allow it`). Case-insensitive matching.
+- **No match**: A disambiguation message is sent listing all active request codes.
+
+This invariant is enforced identically on mac/vellum (`session-process.ts`), Telegram, and SMS (`inbound-message-handler.ts`). All disambiguation messages are generated through the guardian action message composer (LLM with deterministic fallback).
+
 ### Reminder Routing Metadata
 
 Reminders carry optional `routingIntent` (`single_channel` | `multi_channel` | `all_channels`) and free-form `routingHints` metadata. When a reminder fires, this metadata flows through the notification signal into a post-decision enforcement step (`enforceRoutingIntent()` in `decision-engine.ts`) that overrides the LLM's channel selection to match the requested coverage. This enables single-reminder fanout: one reminder can produce multi-channel delivery without duplicate reminders. See `assistant/docs/architecture/scheduling.md` for the full trigger-time data flow.
@@ -1612,8 +1672,9 @@ Connected channels are resolved at signal emission time: vellum is always includ
 | `assistant/src/notifications/emit-signal.ts` | Single entry point for all producers; orchestrates the full pipeline |
 | `assistant/src/notifications/decision-engine.ts` | LLM-based routing decisions with deterministic fallback |
 | `assistant/src/notifications/deterministic-checks.ts` | Hard invariant checks (dedupe, source-active suppression, channel availability) |
-| `assistant/src/notifications/broadcaster.ts` | Dispatches decisions to channel adapters; emits `notification_thread_created` IPC |
-| `assistant/src/notifications/conversation-pairing.ts` | Materializes conversation + message per delivery based on channel strategy |
+| `assistant/src/notifications/broadcaster.ts` | Dispatches decisions to channel adapters; emits `notification_thread_created` IPC (creation-only) |
+| `assistant/src/notifications/conversation-pairing.ts` | Materializes conversation + message per delivery; executes thread reuse decisions |
+| `assistant/src/notifications/thread-candidates.ts` | Builds per-channel candidate set of recent conversations for the decision engine |
 | `assistant/src/notifications/adapters/macos.ts` | Vellum adapter — broadcasts `notification_intent` via IPC with deep-link metadata |
 | `assistant/src/notifications/adapters/telegram.ts` | Telegram adapter — POSTs to gateway `/deliver/telegram` |
 | `assistant/src/notifications/adapters/sms.ts` | SMS adapter — POSTs to gateway `/deliver/sms` via Twilio Messages API |
@@ -1624,7 +1685,7 @@ Connected channels are resolved at signal emission time: vellum is always includ
 | `assistant/src/config/bundled-skills/messaging/tools/send-notification.ts` | Explicit producer tool for user-requested notifications; emits signals into the same routing pipeline |
 | `assistant/src/calls/guardian-dispatch.ts` | Guardian question dispatch that reuses canonical notification pairing and records guardian delivery bookkeeping from pipeline results |
 
-**Audit trail (SQLite):** `notification_events` → `notification_decisions` → `notification_deliveries` (with `conversation_id`, `message_id`, `conversation_strategy`)
+**Audit trail (SQLite):** `notification_events` → `notification_decisions` (with `threadActions` in validation results) → `notification_deliveries` (with `conversation_id`, `message_id`, `conversation_strategy`, `thread_action`, `thread_target_conversation_id`, `thread_decision_fallback_used`)
 
 **Configuration:** `notifications.decisionModelIntent` in `config.json`.
 

package/README.md

@@ -50,6 +50,12 @@ cp .env.example .env
 | `RUNTIME_GATEWAY_ORIGIN_SECRET` | No | — | Dedicated secret for the `X-Gateway-Origin` proof header on `/channels/inbound`. When not set, falls back to the bearer token. Both gateway and runtime must share the same value. |
 | `VELLUM_DAEMON_SOCKET` | No | `~/.vellum/vellum.sock` | Override the daemon socket path |
 
+## Update Bulletin
+
+When a release includes relevant updates, the daemon materializes release notes from the bundled `src/config/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.
+
+**For release maintainers:** Update `assistant/src/config/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.
+
 ## Usage
 
 ### Start the daemon

package/docs/architecture/http-token-refresh.md

@@ -4,7 +4,7 @@ Design for how the daemon notifies clients of bearer token rotation and how clie
 
 ## Current State
 
-The daemon's HTTP bearer token is generated at startup and persisted to `~/.vellum/http-token` (mode 0600). Clients read this file at connection time:
+The daemon's HTTP bearer token is resolved at startup and persisted to `~/.vellum/http-token` (mode 0600). The startup token resolution order is: (1) the `RUNTIME_PROXY_BEARER_TOKEN` env var if set, (2) the existing token read from `~/.vellum/http-token` if the file is readable and non-empty, (3) a newly generated random token as a last resort. Clients read this file at connection time:
 
 - **macOS (local)**: Reads `~/.vellum/http-token` from disk via `resolveHttpTokenPath()` / `readHttpToken()`. Has direct filesystem access to the token file.
 - **iOS (remote)**: Receives the bearer token during the QR-code pairing flow. The token is stored in the iOS Keychain and used for all subsequent HTTP/SSE requests.
@@ -177,6 +177,28 @@ private rotateToken(revoke: boolean): string {
 }
 ```
 
+**Failure semantics — routine vs. revocation**:
+
+The two rotation modes have deliberately different failure ordering to match their security requirements:
+
+| | Routine (`revoke: false`) | Revocation (`revoke: true`) |
+|---|---|---|
+| **Order** | Persist to disk first, then update in-memory state | Update in-memory state first, then persist to disk |
+| **Disk write failure** | Rotation aborts cleanly — in-memory auth state is untouched, clients keep working with the old token | Old token is already invalidated in memory; the API endpoint returns an error to the caller |
+| **Rationale** | Availability: don't lock out clients if persistence fails | Security: a potentially compromised token must never remain valid, even briefly |
+
+**Revocation disk-write failure in detail**: If `writeTokenToDisk` throws after the in-memory switch during revocation, the system enters a degraded state:
+
+1. **In-memory state**: `currentToken` holds the new (unpersisted) token. The old token is rejected. All old-token SSE connections have been terminated.
+2. **Disk state**: `~/.vellum/http-token` still contains the old (now-invalid) token.
+3. **API response**: The `POST /v1/auth/rotate-token` endpoint returns an error indicating the persistence failure. The response body includes the new token so the caller can manually persist or distribute it if needed.
+4. **Client impact by platform**:
+   - **macOS**: Re-reading the token file yields the stale old token, which is rejected (401). Recovery requires a daemon restart (which generates a fresh token and persists it) or a successful retry of the rotation API call.
+   - **iOS**: Already disconnected (old-token SSE terminated). Cannot recover until the daemon restarts or the rotation is retried successfully, at which point re-pairing is required.
+   - **Chrome extension**: Same as iOS — the pasted token is stale and rejected.
+5. **Daemon restart recovery**: A daemon restart does **not** automatically heal this state. At startup, the daemon first checks for the `RUNTIME_PROXY_BEARER_TOKEN` env var, then tries to read the existing token from `~/.vellum/http-token`, and only generates a new random token if both are unavailable (see `assistant/src/daemon/lifecycle.ts`, lines 110-124). In the degraded state described here — where the disk still holds the old (now-invalid) token — a restart would reload that stale token, making it the active bearer token again. To actually recover, the operator must either: (a) manually delete or overwrite `~/.vellum/http-token` before restarting the daemon, (b) set `RUNTIME_PROXY_BEARER_TOKEN` to a known-good value, or (c) successfully retry the `POST /v1/auth/rotate-token` endpoint while the daemon is still running with the new in-memory token.
+6. **Why this is acceptable**: Revocation is a security-critical operation triggered when the old token is suspected compromised. The invariant — "a compromised token must not remain valid" — takes precedence over client convenience. The degraded state requires manual intervention but disk write failures are rare in practice (permissions, disk full), and the API response includes the new token so the caller can retry or manually persist it.
+
 **SSE event emission** (routine rotation only): The `token_rotated` event is published to `assistantEventHub` as a `ServerMessage`, reaching all connected SSE subscribers across all conversations. This event is never emitted during revocation rotations.
 
 ### 5. iOS Client Implementation

package/docs/architecture/security.md

@@ -315,3 +315,83 @@ The `allowOneTimeSend` config gate (default: `false`) enables a secondary "Send
 
 ---
 
+## Channel-Agnostic Scoped Approval Grants
+
+Scoped approval grants are a channel-agnostic primitive that allows a guardian's approval decision on one channel (e.g., Telegram) to authorize a tool execution on a different channel (e.g., voice). Each grant authorizes exactly one tool execution and is consumed atomically.
+
+### Scope Modes
+
+Two scope modes exist:
+
+| Mode | Key fields | Use case |
+|------|-----------|----------|
+| `request_id` | `requestId` | Grant is bound to a specific pending confirmation request. Consumed by matching the request ID. |
+| `tool_signature` | `toolName` + `inputDigest` | Grant is bound to a specific tool invocation identified by tool name and a canonical SHA-256 digest of the input. Consumed by matching both fields plus optional context constraints. |
+
+### Lifecycle Flow
+
+```mermaid
+sequenceDiagram
+    participant Caller as Non-Guardian Caller (Voice)
+    participant Session as Session / Agent Loop
+    participant Bridge as Voice Session Bridge
+    participant Guardian as Guardian (Telegram)
+    participant Interception as Approval Interception
+    participant GrantStore as Scoped Grant Store (SQLite)
+
+    Caller->>Session: Tool invocation triggers confirmation_request
+    Session->>Bridge: confirmation_request event
+    Note over Bridge: Non-guardian voice call cannot prompt interactively
+
+    Bridge->>Session: ASK_GUARDIAN_APPROVAL marker in agent response
+    Session->>Guardian: "Approve [tool] with [args]?" (Telegram)
+
+    Guardian->>Interception: "yes" / approve_once callback
+    Interception->>Session: handleChannelDecision(approve_once)
+    Interception->>GrantStore: createScopedApprovalGrant(tool_signature)
+    Note over GrantStore: Grant minted with 5-min TTL
+
+    Note over Bridge: On next confirmation_request for same tool+input...
+    Bridge->>GrantStore: consumeScopedApprovalGrantByToolSignature()
+    GrantStore-->>Bridge: { ok: true, grant }
+    Bridge->>Session: handleConfirmationResponse(allow)
+    Note over GrantStore: Grant status: active -> consumed (CAS)
+```
+
+### Security Invariants
+
+1. **One-time use** -- Each grant can be consumed at most once. The consume operation uses compare-and-swap (CAS) on the `status` column (`active` -> `consumed`) so concurrent consumers race safely. At most one wins.
+
+2. **Exact-match** -- All non-null scope fields on the grant must match the consumption context exactly. The `inputDigest` is a SHA-256 of the canonical JSON serialization of `{ toolName, input }`, ensuring key-order-independent matching.
+
+3. **Fail-closed** -- When no matching active grant exists, consumption returns `{ ok: false }` and the voice bridge auto-denies. There is no fallback to "allow without a grant."
+
+4. **TTL-bound** -- Grants expire after a configurable TTL (default: 5 minutes). An expiry sweep transitions active past-TTL grants to `expired` status. Expired grants cannot be consumed.
+
+5. **Context-constrained** -- Optional scope fields (`executionChannel`, `conversationId`, `callSessionId`, `requesterExternalUserId`) narrow the grant's applicability. When set on the grant, they must match the consumer's context. When null on the grant, they act as wildcards.
+
+6. **Identity-bound** -- The guardian identity is verified at the approval interception level before a grant is minted. A sender whose `externalUserId` does not match the expected guardian cannot mint a grant.
+
+7. **Persistent storage** -- Grants are stored in the SQLite `scoped_approval_grants` table, which survives daemon restarts. This ensures fail-closed behavior across restarts: consumed grants remain consumed, and no implicit "reset to allowed" occurs.
+
+### Key Source Files
+
+| File | Role |
+|------|------|
+| `assistant/src/memory/scoped-approval-grants.ts` | CRUD, atomic CAS consume, expiry sweep, context-based revocation |
+| `assistant/src/memory/migrations/033-scoped-approval-grants.ts` | SQLite schema migration for the `scoped_approval_grants` table |
+| `assistant/src/security/tool-approval-digest.ts` | Canonical JSON serialization + SHA-256 digest for tool signatures |
+| `assistant/src/runtime/routes/guardian-approval-interception.ts` | Grant minting on guardian approve_once decisions (`tryMintToolApprovalGrant`) |
+| `assistant/src/calls/voice-session-bridge.ts` | Voice consumer: checks and consumes grants before auto-denying |
+
+### Test Coverage
+
+| Test file | Scenarios covered |
+|-----------|-------------------|
+| `assistant/src/__tests__/scoped-approval-grants.test.ts` | Store CRUD, request_id consume, tool_signature consume, expiry, revocation, digest stability |
+| `assistant/src/__tests__/voice-scoped-grant-consumer.test.ts` | Voice bridge integration: grant-allowed, no-grant-denied, tool-mismatch, guardian-bypass, one-time-use, revocation on call end |
+| `assistant/src/__tests__/guardian-grant-minting.test.ts` | Grant minting: callback/engine/legacy paths, informational-skip, reject-skip, identity-mismatch, stale-skip, TTL verification |
+| `assistant/src/__tests__/scoped-grant-security-matrix.test.ts` | Security matrix: requester identity mismatch, concurrent CAS, persistence across restart, fail-closed default, cross-scope invariants |
+
+---
+

package/package.json

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

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

@@ -1748,6 +1748,10 @@ exports[`IPC message snapshots ServerMessage types skills_list_response serializ
       "emoji": "🔧",
       "id": "my-skill",
       "name": "My Skill",
+      "provenance": {
+        "kind": "first-party",
+        "provider": "Vellum",
+      },
       "source": "bundled",
       "state": "enabled",
       "updateAvailable": false,

package/src/__tests__/access-request-decision.test.ts

@@ -55,20 +55,18 @@ mock.module('../runtime/gateway-client.js', () => ({
 
 import {
   createApprovalRequest,
-  createBinding,
   getApprovalRequestById,
-  findPendingAccessRequestForRequester,
 } from '../memory/channel-guardian-store.js';
+import { getDb, initializeDb, resetDb } from '../memory/db.js';
 import {
   findActiveSession,
 } from '../runtime/channel-guardian-service.js';
-import { initializeDb, resetDb } from '../memory/db.js';
 import {
-  handleAccessRequestDecision,
   deliverVerificationCodeToGuardian,
+  handleAccessRequestDecision,
   notifyRequesterOfApproval,
-  notifyRequesterOfDenial,
   notifyRequesterOfDeliveryFailure,
+  notifyRequesterOfDenial,
 } from '../runtime/routes/access-request-decision.js';
 
 initializeDb();
@@ -85,7 +83,6 @@ afterAll(() => {
 const GUARDIAN_APPROVAL_TTL_MS = 5 * 60 * 1000;
 
 function resetState(): void {
-  const { getDb } = require('../memory/db.js');
   const db = getDb();
   db.run('DELETE FROM channel_guardian_approval_requests');
   db.run('DELETE FROM channel_guardian_bindings');
@@ -215,7 +212,7 @@ describe('access request decision handler', () => {
       'guardian-user-789',
     );
     expect(result1.type).toBe('approved');
-    const sessionId1 = result1.verificationSessionId;
+    const _sessionId1 = result1.verificationSessionId;
 
     // Approve again — should be idempotent (already resolved with same decision)
     const result2 = handleAccessRequestDecision(

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

@@ -1195,4 +1195,174 @@ describe('call-controller', () => {
 
     controller.destroy();
   });
+
+  // ── Structured tool-approval ASK_GUARDIAN_APPROVAL ──────────────────
+
+  test('ASK_GUARDIAN_APPROVAL: persists toolName and inputDigest on guardian action request', async () => {
+    const approvalPayload = JSON.stringify({
+      question: 'Allow send_email to bob@example.com?',
+      toolName: 'send_email',
+      input: { to: 'bob@example.com', subject: 'Hello' },
+    });
+    mockStartVoiceTurn.mockImplementation(createMockVoiceTurn(
+      [`Let me check with your guardian. [ASK_GUARDIAN_APPROVAL: ${approvalPayload}]`],
+    ));
+    const { session, relay, controller } = setupController('Send an email');
+
+    await controller.handleCallerUtterance('Send an email to Bob');
+
+    // Give the async dispatchGuardianQuestion a tick to create the request
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Verify controller entered waiting_on_user
+    expect(controller.getState()).toBe('waiting_on_user');
+
+    // Verify a pending question was created with the correct text
+    const question = getPendingQuestion(session.id);
+    expect(question).not.toBeNull();
+    expect(question!.questionText).toBe('Allow send_email to bob@example.com?');
+
+    // Verify the guardian action request has tool metadata
+    const pendingRequest = getPendingRequestByCallSessionId(session.id);
+    expect(pendingRequest).not.toBeNull();
+    expect(pendingRequest!.toolName).toBe('send_email');
+    expect(pendingRequest!.inputDigest).not.toBeNull();
+    expect(pendingRequest!.inputDigest!.length).toBe(64); // SHA-256 hex = 64 chars
+
+    // The ASK_GUARDIAN_APPROVAL marker should NOT appear in the relay tokens
+    const allText = relay.sentTokens.map((t) => t.token).join('');
+    expect(allText).not.toContain('[ASK_GUARDIAN_APPROVAL:');
+    expect(allText).not.toContain('send_email');
+
+    controller.destroy();
+  });
+
+  test('ASK_GUARDIAN_APPROVAL: computes deterministic digest for same tool+input', async () => {
+    const approvalPayload = JSON.stringify({
+      question: 'Allow send_email?',
+      toolName: 'send_email',
+      input: { subject: 'Hello', to: 'bob@example.com' },
+    });
+    mockStartVoiceTurn.mockImplementation(createMockVoiceTurn(
+      [`Checking. [ASK_GUARDIAN_APPROVAL: ${approvalPayload}]`],
+    ));
+    const { session, controller } = setupController('Send email');
+
+    await controller.handleCallerUtterance('Send it');
+    await new Promise((r) => setTimeout(r, 50));
+
+    const request1 = getPendingRequestByCallSessionId(session.id);
+    expect(request1).not.toBeNull();
+
+    // Compute expected digest independently using the same utility
+    const { computeToolApprovalDigest } = await import('../security/tool-approval-digest.js');
+    const expectedDigest = computeToolApprovalDigest('send_email', { subject: 'Hello', to: 'bob@example.com' });
+    expect(request1!.inputDigest).toBe(expectedDigest);
+
+    controller.destroy();
+  });
+
+  test('informational ASK_GUARDIAN: does NOT persist tool metadata (null toolName/inputDigest)', async () => {
+    mockStartVoiceTurn.mockImplementation(createMockVoiceTurn(
+      ['Let me check. [ASK_GUARDIAN: What date works best?]'],
+    ));
+    const { session, controller } = setupController('Book appointment');
+
+    await controller.handleCallerUtterance('I need to schedule something');
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Verify the guardian action request has NO tool metadata
+    const pendingRequest = getPendingRequestByCallSessionId(session.id);
+    expect(pendingRequest).not.toBeNull();
+    expect(pendingRequest!.toolName).toBeNull();
+    expect(pendingRequest!.inputDigest).toBeNull();
+    expect(pendingRequest!.questionText).toBe('What date works best?');
+
+    controller.destroy();
+  });
+
+  test('ASK_GUARDIAN_APPROVAL: strips marker from TTS output', async () => {
+    const approvalPayload = JSON.stringify({
+      question: 'Allow calendar_create?',
+      toolName: 'calendar_create',
+      input: { date: '2026-03-01', title: 'Meeting' },
+    });
+    mockStartVoiceTurn.mockImplementation(createMockVoiceTurn([
+      'Let me get approval for that. ',
+      `[ASK_GUARDIAN_APPROVAL: ${approvalPayload}]`,
+      ' Thank you.',
+    ]));
+    const { relay, controller } = setupController('Create event');
+
+    await controller.handleCallerUtterance('Create a meeting');
+
+    const allText = relay.sentTokens.map((t) => t.token).join('');
+    expect(allText).toContain('Let me get approval');
+    expect(allText).not.toContain('[ASK_GUARDIAN_APPROVAL:');
+    expect(allText).not.toContain('calendar_create');
+    expect(allText).not.toContain('inputDigest');
+
+    controller.destroy();
+  });
+
+  test('ASK_GUARDIAN_APPROVAL: handles JSON payloads containing }] in string values', async () => {
+    // The `}]` sequence inside a JSON string value previously caused the
+    // non-greedy regex to terminate early, truncating the JSON and leaking
+    // partial data into TTS output.
+    const approvalPayload = JSON.stringify({
+      question: 'Allow send_message?',
+      toolName: 'send_message',
+      input: { msg: 'test}]more', nested: { key: 'value with }] braces' } },
+    });
+    mockStartVoiceTurn.mockImplementation(createMockVoiceTurn(
+      [`Let me check. [ASK_GUARDIAN_APPROVAL: ${approvalPayload}]`],
+    ));
+    const { session, relay, controller } = setupController('Send a message');
+
+    await controller.handleCallerUtterance('Send it');
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Verify controller entered waiting_on_user with the correct question
+    expect(controller.getState()).toBe('waiting_on_user');
+    const question = getPendingQuestion(session.id);
+    expect(question).not.toBeNull();
+    expect(question!.questionText).toBe('Allow send_message?');
+
+    // Verify tool metadata was parsed correctly
+    const pendingRequest = getPendingRequestByCallSessionId(session.id);
+    expect(pendingRequest).not.toBeNull();
+    expect(pendingRequest!.toolName).toBe('send_message');
+    expect(pendingRequest!.inputDigest).not.toBeNull();
+
+    // No partial JSON or marker text should leak into TTS output
+    const allText = relay.sentTokens.map((t) => t.token).join('');
+    expect(allText).not.toContain('[ASK_GUARDIAN_APPROVAL:');
+    expect(allText).not.toContain('send_message');
+    expect(allText).not.toContain('}]');
+    expect(allText).not.toContain('test}]more');
+    expect(allText).toContain('Let me check.');
+
+    controller.destroy();
+  });
+
+  test('ASK_GUARDIAN_APPROVAL with malformed JSON: falls through to informational ASK_GUARDIAN', async () => {
+    // Malformed JSON in the approval marker — should be ignored, and if there's
+    // also an informational ASK_GUARDIAN marker, it should be used instead
+    mockStartVoiceTurn.mockImplementation(createMockVoiceTurn(
+      ['Checking. [ASK_GUARDIAN_APPROVAL: {invalid json}] [ASK_GUARDIAN: Fallback question?]'],
+    ));
+    const { session, controller } = setupController('Test fallback');
+
+    await controller.handleCallerUtterance('Do something');
+    await new Promise((r) => setTimeout(r, 50));
+
+    const pendingRequest = getPendingRequestByCallSessionId(session.id);
+    expect(pendingRequest).not.toBeNull();
+    expect(pendingRequest!.questionText).toBe('Fallback question?');
+    // Tool metadata should be null since the approval marker was malformed
+    expect(pendingRequest!.toolName).toBeNull();
+    expect(pendingRequest!.inputDigest).toBeNull();
+
+    controller.destroy();
+  });
 });

package/src/__tests__/channel-guardian.test.ts

@@ -2743,7 +2743,9 @@ describe('outbound SMS verification', () => {
       // Guardian outbound sessions (no verificationPurpose override) create
       // guardian bindings on success
       expect(result.verificationType).toBe('guardian');
-      expect(result.bindingId).toBeDefined();
+      if (result.verificationType === 'guardian') {
+        expect(result.bindingId).toBeDefined();
+      }
     }
   });