@vellumai/assistant 0.4.9 → 0.4.11

package/ARCHITECTURE.md

@@ -2085,3 +2085,27 @@ The daemon uses a single fixed internal scope constant — `DAEMON_INTERNAL_ASSI
 |------|---------|
 | `src/runtime/assistant-scope.ts` | Exports `DAEMON_INTERNAL_ASSISTANT_ID` constant |
 | `src/__tests__/assistant-id-boundary-guard.test.ts` | Guard tests enforcing the identity boundary |
+
+### Canonical Trust-Context Model
+
+The guardian trust system uses a three-valued `TrustClass` — `'guardian'`, `'trusted_contact'`, or `'unknown'` — as the single vocabulary for actor trust classification across all channels and runtime paths. There is no legacy `actorRole` concept; all trust decisions flow through `TrustClass`.
+
+**`GuardianRuntimeContext`** (in `src/daemon/session-runtime-assembly.ts`) is the single runtime carrier for trust state on channel-originated turns. It carries `trustClass`, guardian identity fields, and requester metadata. The `guardianPrincipalId` field is typed as `?: string` (optional but non-nullable) — a principal ID is present when a guardian binding exists but is never `null`.
+
+**Explicit trust gates:** `guardianTrustClass` is a **required** field in `ToolContext` (in `src/tools/types.ts`). Every tool execution must carry a trust classification — the field is not optional. This ensures trust-gated tool policies (guardian control-plane restrictions, host-tool blocking for untrusted actors) cannot be bypassed by omitting the classification.
+
+**Guardian bindings** (in `src/memory/guardian-bindings.ts`) always carry `guardianPrincipalId: string` as a required, non-null field. A binding without a principal ID is invalid and cannot be created.
+
+**Strict retry sweep parsing:** The channel retry sweep (`src/runtime/channel-retry-sweep.ts`) uses `parseGuardianRuntimeContext()` which validates `trustClass` against the canonical three-value set. There is no fallback to a legacy `actorRole` field — stored payloads that lack a valid `trustClass` are rejected deterministically to prevent silent privilege escalation. When `guardianCtx` is entirely absent from a stored payload (pre-guardian events), the sweep synthesizes an explicit `trustClass: 'unknown'` context so that replay never proceeds without a trust classification.
+
+**Rollout note — legacy `actorRole` payloads:** Previously failed events stored with only `actorRole` (no `trustClass`) will be marked as failed on each retry attempt and eventually dead-lettered after exhausting `RETRY_MAX_ATTEMPTS`. This is an intentional security tradeoff: replaying these events with inferred trust would violate the explicit-trust model. If legacy events need to be recovered, they should be repaired (adding a canonical `trustClass` to the stored payload) before replay via `replayDeadLetters()`.
+
+**Key files:**
+
+| File | Purpose |
+|------|---------|
+| `src/daemon/session-runtime-assembly.ts` | `GuardianRuntimeContext` type definition |
+| `src/tools/types.ts` | `ToolContext.guardianTrustClass` (required trust gate) |
+| `src/runtime/channel-retry-sweep.ts` | Strict `trustClass` parser for retry sweep |
+| `src/memory/guardian-bindings.ts` | `GuardianBinding` with required `guardianPrincipalId` |
+| `src/__tests__/trust-context-guards.test.ts` | Guard tests enforcing trust-context type invariants |

package/Dockerfile

@@ -87,7 +87,7 @@ RUN echo 'Dir::State "/data/dpkg";' > /etc/apt/apt.conf.d/99data-dir && \
     chown -R assistant:assistant /data/apt /data/dpkg
 
 ENV PATH="/data/usr/bin:/data/usr/sbin:${PATH}"
-ENV LD_LIBRARY_PATH="/data/usr/lib:/data/usr/lib/x86_64-linux-gnu:${LD_LIBRARY_PATH}"
+ENV LD_LIBRARY_PATH="/data/usr/lib:/data/usr/lib/x86_64-linux-gnu:/data/usr/lib/aarch64-linux-gnu:${LD_LIBRARY_PATH}"
 
 USER root
 

package/README.md

@@ -58,30 +58,37 @@ When a release includes relevant updates, the daemon materializes release notes
 
 ## Usage
 
-### Start the daemon
+### Lifecycle management (recommended)
+
+Use the `vellum` CLI to manage daemon and gateway processes:
 
 ```bash
-bun run src/index.ts daemon start
+vellum wake    # start daemon + gateway from current checkout
+vellum ps      # list assistants and per-assistant process status
+vellum sleep   # stop daemon + gateway (directory-agnostic)
 ```
 
-### Interactive CLI
+> **Note:** `vellum wake` requires a hatched assistant. Run `vellum hatch` first, or launch the macOS app which handles hatching automatically.
 
-```bash
-bun run src/index.ts
-```
+### Development: raw bun commands
 
-### Dev mode (auto-restart on file changes)
+For low-level development (e.g., working on the daemon itself):
 
 ```bash
-bun run src/index.ts dev
+bun run src/index.ts daemon start   # start daemon only
+bun run src/index.ts                # interactive CLI session
+bun run src/index.ts dev            # dev mode (auto-restart on file changes)
 ```
 
 ### CLI commands
 
 | Command | Description |
 |---------|-------------|
+| `vellum wake` | Start daemon + gateway from current checkout |
+| `vellum sleep` | Stop daemon + gateway processes |
+| `vellum ps` | List assistants and per-assistant process status |
 | `vellum` | Launch interactive CLI session |
-| `vellum daemon start\|stop\|restart\|status` | Manage the daemon process |
+| `vellum daemon start\|stop\|restart\|status` | Manage the daemon process (low-level) |
 | `vellum dev` | Run daemon with auto-restart on file changes |
 | `vellum sessions list\|new\|export\|clear` | Manage conversation sessions |
 | `vellum config set\|get\|list` | Manage configuration |

package/package.json

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

package/src/__tests__/account-registry.test.ts

@@ -45,6 +45,7 @@ const _ctx: ToolContext = {
   workingDir: '/tmp',
   sessionId: 'test-session',
   conversationId: 'test-conv',
+  guardianTrustClass: 'guardian',
 };
 
 afterAll(() => {

package/src/__tests__/actor-token-service.test.ts

@@ -340,6 +340,7 @@ describe('guardian vellum migration', () => {
       channel: 'telegram',
       guardianExternalUserId: 'tg-user-123',
       guardianDeliveryChatId: 'tg-chat-456',
+      guardianPrincipalId: 'tg-user-123',
       verifiedVia: 'challenge',
     });
 

package/src/__tests__/app-builder-tool-scripts.test.ts

@@ -53,6 +53,7 @@ function makeContext(overrides: Partial<ToolContext> = {}): ToolContext {
     workingDir: '/tmp',
     sessionId: 'session-1',
     conversationId: 'conv-1',
+    guardianTrustClass: 'guardian',
     ...overrides,
   };
 }

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

@@ -69,6 +69,7 @@ const dummyContext: ToolContext = {
   workingDir: sandboxDir,
   sessionId: 'sess-test',
   conversationId: 'conv-test',
+  guardianTrustClass: 'guardian',
 };
 
 // ---------------------------------------------------------------------------
@@ -322,6 +323,7 @@ describe('AssetMaterializeTool visibility policy', () => {
       workingDir: sandboxDir,
       sessionId: 'sess-test',
       conversationId: otherConv.id,
+      guardianTrustClass: 'guardian',
     };
 
     const result = await assetMaterializeTool.execute(
@@ -344,6 +346,7 @@ describe('AssetMaterializeTool visibility policy', () => {
       workingDir: sandboxDir,
       sessionId: 'sess-test',
       conversationId: privateConv.id,
+      guardianTrustClass: 'guardian',
     };
 
     const result = await assetMaterializeTool.execute(
@@ -367,6 +370,7 @@ describe('AssetMaterializeTool visibility policy', () => {
       workingDir: sandboxDir,
       sessionId: 'sess-test',
       conversationId: otherConv.id,
+      guardianTrustClass: 'guardian',
     };
 
     const result = await assetMaterializeTool.execute(
@@ -391,6 +395,7 @@ describe('AssetMaterializeTool visibility policy', () => {
       workingDir: sandboxDir,
       sessionId: 'sess-test',
       conversationId: standardConv.id,
+      guardianTrustClass: 'guardian',
     };
 
     const result = await assetMaterializeTool.execute(
@@ -417,6 +422,7 @@ describe('AssetMaterializeTool visibility policy', () => {
       workingDir: sandboxDir,
       sessionId: 'sess-test',
       conversationId: privateConv2.id,
+      guardianTrustClass: 'guardian',
     };
 
     const result = await assetMaterializeTool.execute(
@@ -444,6 +450,7 @@ describe('AssetMaterializeTool visibility policy', () => {
       workingDir: sandboxDir,
       sessionId: 'sess-test',
       conversationId: otherConv.id,
+      guardianTrustClass: 'guardian',
     };
 
     const result = await assetMaterializeTool.execute(

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

@@ -88,6 +88,7 @@ const dummyContext: ToolContext = {
   workingDir: '/tmp',
   sessionId: 'sess-test',
   conversationId: 'conv-test',
+  guardianTrustClass: 'guardian',
 };
 
 // ---------------------------------------------------------------------------
@@ -378,6 +379,7 @@ describe('AssetSearchTool visibility policy', () => {
       workingDir: '/tmp',
       sessionId: 'sess-test',
       conversationId: otherConv.id,
+      guardianTrustClass: 'guardian',
     };
 
     const result = await assetSearchTool.execute({}, context);
@@ -396,6 +398,7 @@ describe('AssetSearchTool visibility policy', () => {
       workingDir: '/tmp',
       sessionId: 'sess-test',
       conversationId: privateConv.id,
+      guardianTrustClass: 'guardian',
     };
 
     const result = await assetSearchTool.execute({}, context);
@@ -415,6 +418,7 @@ describe('AssetSearchTool visibility policy', () => {
       workingDir: '/tmp',
       sessionId: 'sess-test',
       conversationId: otherPrivateConv.id,
+      guardianTrustClass: 'guardian',
     };
 
     const result = await assetSearchTool.execute({}, context);
@@ -434,6 +438,7 @@ describe('AssetSearchTool visibility policy', () => {
       workingDir: '/tmp',
       sessionId: 'sess-test',
       conversationId: standardConv.id,
+      guardianTrustClass: 'guardian',
     };
 
     const result = await assetSearchTool.execute({}, context);
@@ -457,6 +462,7 @@ describe('AssetSearchTool visibility policy', () => {
       workingDir: '/tmp',
       sessionId: 'sess-test',
       conversationId: otherConv.id,
+      guardianTrustClass: 'guardian',
     };
 
     const result = await assetSearchTool.execute({}, context);
@@ -472,6 +478,7 @@ describe('AssetSearchTool visibility policy', () => {
       workingDir: '/tmp',
       sessionId: 'sess-test',
       conversationId: conv.id,
+      guardianTrustClass: 'guardian',
     };
 
     const result = await assetSearchTool.execute({}, context);

package/src/__tests__/browser-fill-credential.test.ts

@@ -81,6 +81,7 @@ const ctx: ToolContext = {
   sessionId: 'test-session',
   conversationId: 'test-conversation',
   workingDir: '/tmp',
+  guardianTrustClass: 'guardian',
 };
 
 function resetMockPage() {

package/src/__tests__/call-start-guardian-guard.test.ts

@@ -45,6 +45,7 @@ function makeContext(): ToolContext {
     sessionId: 'session-1',
     conversationId: 'conversation-1',
     assistantId: 'self',
+    guardianTrustClass: 'guardian',
   };
 }
 

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

@@ -246,6 +246,7 @@ describe('inbound callback metadata triggers decision handling', () => {
       channel: 'telegram',
       guardianExternalUserId: 'telegram-user-default',
       guardianDeliveryChatId: 'chat-123',
+      guardianPrincipalId: 'telegram-user-default',
     });
   });
 
@@ -321,6 +322,7 @@ describe('inbound text matching approval phrases triggers decision handling', ()
       channel: 'telegram',
       guardianExternalUserId: 'telegram-user-default',
       guardianDeliveryChatId: 'chat-123',
+      guardianPrincipalId: 'telegram-user-default',
     });
   });
 
@@ -384,6 +386,7 @@ describe('non-decision messages during pending approval (legacy fallback)', () =
       channel: 'telegram',
       guardianExternalUserId: 'telegram-user-default',
       guardianDeliveryChatId: 'chat-123',
+      guardianPrincipalId: 'telegram-user-default',
     });
   });
 
@@ -458,6 +461,7 @@ describe('empty content with callbackData bypasses validation', () => {
       channel: 'telegram',
       guardianExternalUserId: 'telegram-user-default',
       guardianDeliveryChatId: 'chat-123',
+      guardianPrincipalId: 'telegram-user-default',
     });
   });
 
@@ -551,6 +555,7 @@ describe('callback requestId validation', () => {
       channel: 'telegram',
       guardianExternalUserId: 'telegram-user-default',
       guardianDeliveryChatId: 'chat-123',
+      guardianPrincipalId: 'telegram-user-default',
     });
   });
 
@@ -651,6 +656,7 @@ describe('no immediate reply after approval decision', () => {
       channel: 'telegram',
       guardianExternalUserId: 'telegram-user-default',
       guardianDeliveryChatId: 'chat-123',
+      guardianPrincipalId: 'telegram-user-default',
     });
   });
 
@@ -773,6 +779,7 @@ describe('SMS channel approval decisions', () => {
       channel: 'sms',
       guardianExternalUserId: 'sms-user-default',
       guardianDeliveryChatId: 'sms-chat-123',
+      guardianPrincipalId: 'sms-user-default',
     });
   });
 
@@ -1026,6 +1033,7 @@ describe('guardian decision scoping — multiple pending approvals', () => {
       channel: 'telegram',
       guardianExternalUserId: 'guardian-scope-user',
       guardianDeliveryChatId: 'guardian-scope-chat',
+      guardianPrincipalId: 'guardian-scope-user',
     });
 
     const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
@@ -1099,6 +1107,7 @@ describe('ambiguous plain-text decision with multiple pending requests', () => {
       channel: 'telegram',
       guardianExternalUserId: 'guardian-ambig-user',
       guardianDeliveryChatId: 'guardian-ambig-chat',
+      guardianPrincipalId: 'guardian-ambig-user',
     });
 
     const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
@@ -1548,6 +1557,7 @@ describe('conversational approval engine — standard path', () => {
       channel: 'telegram',
       guardianExternalUserId: 'telegram-user-default',
       guardianDeliveryChatId: 'chat-123',
+      guardianPrincipalId: 'telegram-user-default',
     });
   });
 
@@ -1717,6 +1727,7 @@ describe('guardian conversational approval via conversation engine', () => {
       channel: 'telegram',
       guardianExternalUserId: 'guardian-conv-user',
       guardianDeliveryChatId: 'guardian-conv-chat',
+      guardianPrincipalId: 'guardian-conv-user',
     });
 
     const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
@@ -1781,6 +1792,7 @@ describe('guardian conversational approval via conversation engine', () => {
       channel: 'telegram',
       guardianExternalUserId: 'guardian-nlp-user',
       guardianDeliveryChatId: 'guardian-nlp-chat',
+      guardianPrincipalId: 'guardian-nlp-user',
     });
 
     const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
@@ -1843,6 +1855,7 @@ describe('guardian conversational approval via conversation engine', () => {
       channel: 'telegram',
       guardianExternalUserId: 'guardian-dg-user',
       guardianDeliveryChatId: 'guardian-dg-chat',
+      guardianPrincipalId: 'guardian-dg-user',
     });
 
     const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
@@ -1892,6 +1905,7 @@ describe('guardian conversational approval via conversation engine', () => {
       channel: 'telegram',
       guardianExternalUserId: 'guardian-multi-user',
       guardianDeliveryChatId: 'guardian-multi-chat',
+      guardianPrincipalId: 'guardian-multi-user',
     });
 
     const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
@@ -1981,6 +1995,7 @@ describe('keep_pending remains conversational — standard path', () => {
       channel: 'telegram',
       guardianExternalUserId: 'telegram-user-default',
       guardianDeliveryChatId: 'chat-123',
+      guardianPrincipalId: 'telegram-user-default',
     });
   });
 
@@ -2029,6 +2044,7 @@ describe('keep_pending remains conversational — guardian path', () => {
       channel: 'telegram',
       guardianExternalUserId: 'guardian-user-fb',
       guardianDeliveryChatId: 'guardian-chat-fb',
+      guardianPrincipalId: 'guardian-user-fb',
     });
 
     const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
@@ -2091,6 +2107,7 @@ describe('requester cancel of guardian-gated pending request', () => {
       channel: 'telegram',
       guardianExternalUserId: 'guardian-cancel',
       guardianDeliveryChatId: 'guardian-cancel-chat',
+      guardianPrincipalId: 'guardian-cancel',
     });
   });
 
@@ -2346,6 +2363,7 @@ describe('engine decision race condition — standard path', () => {
       channel: 'telegram',
       guardianExternalUserId: 'telegram-user-default',
       guardianDeliveryChatId: 'chat-123',
+      guardianPrincipalId: 'telegram-user-default',
     });
   });
 
@@ -2407,6 +2425,7 @@ describe('engine decision race condition — guardian path', () => {
       channel: 'telegram',
       guardianExternalUserId: 'guardian-race-user',
       guardianDeliveryChatId: 'guardian-race-chat',
+      guardianPrincipalId: 'guardian-race-user',
     });
 
     const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
@@ -2482,12 +2501,14 @@ describe('non-decision status reply for different channels', () => {
       channel: 'telegram',
       guardianExternalUserId: 'telegram-user-default',
       guardianDeliveryChatId: 'chat-123',
+      guardianPrincipalId: 'telegram-user-default',
     });
     createBinding({
       assistantId: 'self',
       channel: 'sms',
       guardianExternalUserId: 'telegram-user-default',
       guardianDeliveryChatId: 'chat-123',
+      guardianPrincipalId: 'telegram-user-default',
     });
   });
 
@@ -2572,6 +2593,7 @@ describe('background channel processing approval prompts', () => {
       channel: 'telegram',
       guardianExternalUserId: 'telegram-user-default',
       guardianDeliveryChatId: 'chat-123',
+      guardianPrincipalId: 'telegram-user-default',
     });
 
     const deliverPromptSpy = spyOn(gatewayClient, 'deliverApprovalPrompt').mockResolvedValue(undefined);
@@ -2625,6 +2647,7 @@ describe('background channel processing approval prompts', () => {
       channel: 'telegram',
       guardianExternalUserId: '  telegram-user-default  ',
       guardianDeliveryChatId: 'chat-123',
+      guardianPrincipalId: '  telegram-user-default  ',
     });
 
     const deliverPromptSpy = spyOn(gatewayClient, 'deliverApprovalPrompt').mockResolvedValue(undefined);
@@ -2676,6 +2699,7 @@ describe('background channel processing approval prompts', () => {
       channel: 'telegram',
       guardianExternalUserId: 'guardian-user-other',
       guardianDeliveryChatId: 'guardian-chat-other',
+      guardianPrincipalId: 'guardian-user-other',
     });
 
     const processCalls: Array<{ options?: Record<string, unknown> }> = [];
@@ -2779,6 +2803,8 @@ describe('NL approval routing via destination-scoped canonical requests', () =>
       channel: 'telegram',
       guardianExternalUserId: guardianUserId,
       guardianDeliveryChatId: guardianChatId,
+
+      guardianPrincipalId: guardianUserId,
     });
 
     // Create canonical tool_approval request WITHOUT guardianExternalUserId
@@ -2835,6 +2861,8 @@ describe('NL approval routing via destination-scoped canonical requests', () =>
       channel: 'telegram',
       guardianExternalUserId: guardianUserId,
       guardianDeliveryChatId: differentChatId,
+
+      guardianPrincipalId: guardianUserId,
     });
 
     // Create canonical pending_question WITHOUT guardianExternalUserId
@@ -2890,6 +2918,7 @@ describe('trusted-contact self-approval blocked before guardian approval row exi
       channel: 'telegram',
       guardianExternalUserId: 'guardian-tc-selfapproval',
       guardianDeliveryChatId: 'guardian-tc-selfapproval-chat',
+      guardianPrincipalId: 'guardian-tc-selfapproval',
     });
   });