@vellumai/assistant 0.3.3 → 0.3.4

package/README.md

@@ -46,7 +46,6 @@ cp .env.example .env
 | `OLLAMA_BASE_URL` | No | `http://127.0.0.1:11434/v1` | Ollama base URL |
 | `RUNTIME_HTTP_PORT` | No | — | Enable the HTTP server (required for gateway/web) |
 | `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. |
-| `CHANNEL_APPROVALS_ENABLED` | No | `false` | Enable channel approval flow including interactive approval UX, guardian enforcement (`forceStrictSideEffects`, fail-closed denial), and approval prompt routing. Actor-role classification runs regardless, but enforcement requires this flag. |
 | `VELLUM_DAEMON_SOCKET` | No | `~/.vellum/vellum.sock` | Override the daemon socket path |
 
 ## Usage
@@ -124,7 +123,7 @@ assistant/
 
 ## Channel Approval Flow
 
-When the assistant needs tool-use confirmation during a channel session (e.g., Telegram), the approval flow intercepts the run and surfaces an interactive prompt to the user. This is gated behind the `CHANNEL_APPROVALS_ENABLED=true` environment variable.
+When the assistant needs tool-use confirmation during a channel session (e.g., Telegram), the approval flow intercepts the run and surfaces an interactive prompt to the user. This approval-aware path is always enabled whenever orchestrator + callback context are available.
 
 ### How it works
 
@@ -164,24 +163,17 @@ Channels that do not support rich inline approval UI (e.g., inline keyboards) re
 
 ### Enabling
 
-Set the environment variable before starting the daemon:
-
-```bash
-CHANNEL_APPROVALS_ENABLED=true
-```
-
-When disabled (the default), channel messages follow the standard fire-and-forget processing path without approval interception.
+Channel approvals are always enabled for channel traffic when orchestrator + callback context are available.
 
 ### Guardian-Specific Behavior
 
-Guardian actor-role *classification* (determining whether a sender is guardian, non-guardian, or unverified) runs unconditionally. However, guardian *enforcement* -- `forceStrictSideEffects`, fail-closed denial for unverified channels, and approval prompt routing to guardians -- only executes when `CHANNEL_APPROVALS_ENABLED=true`. When the flag is off, messages go through the standard fire-and-forget processing path (`processChannelMessageInBackground`), which does not apply guardian enforcement.
+Guardian actor-role *classification* (determining whether a sender is guardian, non-guardian, or unverified) runs unconditionally. Guardian *enforcement* for non-guardian/unverified actors (`forceStrictSideEffects`, fail-closed denial for unverified channels, and approval prompt routing to guardians) is always active when orchestrator + callback context are available.
 
 | Flag / Behavior | Description |
 |-----------------|-------------|
-| `CHANNEL_APPROVALS_ENABLED=true` | Enables the full channel approval flow: approval prompts, callback-based decisions, reminder messages, **and** guardian enforcement (`forceStrictSideEffects`, fail-closed denial, approval routing to guardians). Actor-role classification runs regardless. |
-| `forceStrictSideEffects` | Automatically set on runs triggered by non-guardian or unverified-channel senders so all side-effect tools require approval. Only applied when `CHANNEL_APPROVALS_ENABLED=true`. |
-| **Fail-closed no-binding** | When no guardian binding exists for a channel, the sender is classified as `unverified_channel`. Any sensitive action is auto-denied with a notice that no guardian has been configured. Only enforced when `CHANNEL_APPROVALS_ENABLED=true`. |
-| **Fail-closed no-identity** | When `senderExternalUserId` is absent but a guardian binding exists for the channel, the actor is classified as `unverified_channel`. Only enforced when `CHANNEL_APPROVALS_ENABLED=true`. |
+| `forceStrictSideEffects` | Automatically set on runs triggered by non-guardian or unverified-channel senders so all side-effect tools require approval. |
+| **Fail-closed no-binding** | When no guardian binding exists for a channel, the sender is classified as `unverified_channel`. Any sensitive action is auto-denied with a notice that no guardian has been configured. |
+| **Fail-closed no-identity** | When `senderExternalUserId` is absent, the actor is classified as `unverified_channel` (even if no guardian binding exists yet). |
 | **Guardian-only approval** | Non-guardian senders cannot approve their own pending actions. Only the verified guardian can approve or deny. |
 | **Expired approval auto-deny** | A proactive sweep runs every 60 seconds to find expired guardian approval requests (30-minute TTL). Expired approvals are auto-denied, and both the requester and guardian are notified. If a non-guardian interacts before the sweep runs, the expiry is also detected reactively. |
 
@@ -293,9 +285,9 @@ The image runs as non-root user `assistant` (uid 1001) and exposes port `3001`.
 | Symptom | Cause | Resolution |
 |---------|-------|------------|
 | 403 `GATEWAY_ORIGIN_REQUIRED` on `/channels/inbound` | Missing or invalid `X-Gateway-Origin` header | Ensure `RUNTIME_GATEWAY_ORIGIN_SECRET` is set to the same value on both gateway and runtime. If not using a dedicated secret, ensure the bearer token (`RUNTIME_BEARER_TOKEN` or `~/.vellum/http-token`) is shared. |
-| Non-guardian actions silently denied | No guardian binding for the channel and `CHANNEL_APPROVALS_ENABLED=true`. The system is fail-closed when enforcement is active. | Run the guardian verification flow from the desktop UI to bind a guardian. |
+| Non-guardian actions silently denied | No guardian binding for the channel. The system is fail-closed for unverified channels. | Run the guardian verification flow from the desktop UI to bind a guardian. |
 | Guardian approval expired | The 30-minute TTL elapsed. The proactive sweep auto-denied the approval and notified both parties. | The requester must re-trigger the action. |
-| `forceStrictSideEffects` unexpectedly active | The sender is classified as `non-guardian` or `unverified_channel` (requires `CHANNEL_APPROVALS_ENABLED=true`) | Verify the sender's `externalUserId` matches the guardian binding, or set up a guardian binding for the channel. |
+| `forceStrictSideEffects` unexpectedly active | The sender is classified as `non-guardian` or `unverified_channel` | Verify the sender's `externalUserId` matches the guardian binding, or set up a guardian binding for the channel. |
 
 ### Invalid RRULE set expressions
 

package/package.json

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

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

@@ -27,6 +27,14 @@ mock.module('../util/logger.js', () => ({
     }),
 }));
 
+// ── User reference mock ──────────────────────────────────────────────
+
+let mockUserReference = 'my human';
+
+mock.module('../config/user-reference.js', () => ({
+  resolveUserReference: () => mockUserReference,
+}));
+
 // ── Config mock ─────────────────────────────────────────────────────
 
 let mockCallModel: string | undefined = undefined;
@@ -197,6 +205,7 @@ describe('call-orchestrator', () => {
   beforeEach(() => {
     resetTables();
     mockCallModel = undefined;
+    mockUserReference = 'my human';
     // Reset the stream mock to default behaviour
     mockStreamFn.mockImplementation(() => createMockStream(['Hello', ' there']));
   });
@@ -414,6 +423,166 @@ describe('call-orchestrator', () => {
     orchestrator.destroy();
   });
 
+  test('LLM APIUserAbortError: treats as expected abort without technical-issue fallback', async () => {
+    mockStreamFn.mockImplementation(() => {
+      const emitter = new EventEmitter();
+      return {
+        on: (event: string, handler: (...args: unknown[]) => void) => {
+          emitter.on(event, handler);
+          return { on: () => ({ on: () => ({}) }) };
+        },
+        finalMessage: () => {
+          const err = new Error('user abort');
+          err.name = 'APIUserAbortError';
+          return Promise.reject(err);
+        },
+      };
+    });
+
+    const { relay, orchestrator } = setupOrchestrator();
+    await orchestrator.handleCallerUtterance('Hello');
+
+    const errorTokens = relay.sentTokens.filter((t) => t.token.includes('technical issue'));
+    expect(errorTokens.length).toBe(0);
+    expect(orchestrator.getState()).toBe('idle');
+
+    orchestrator.destroy();
+  });
+
+  test('stale superseded turn errors do not emit technical-issue fallback', async () => {
+    let callCount = 0;
+    mockStreamFn.mockImplementation(() => {
+      callCount++;
+      if (callCount === 1) {
+        const emitter = new EventEmitter();
+        return {
+          on: (event: string, handler: (...args: unknown[]) => void) => {
+            emitter.on(event, handler);
+            return { on: () => ({ on: () => ({}) }) };
+          },
+          finalMessage: () =>
+            new Promise((_, reject) => {
+              setTimeout(() => reject(new Error('stale stream failure')), 20);
+            }),
+        };
+      }
+      return createMockStream(['Second turn response.']);
+    });
+
+    const { relay, orchestrator } = setupOrchestrator();
+
+    const firstTurnPromise = orchestrator.handleCallerUtterance('First utterance');
+    // Allow the first turn to enter runLlm before the second utterance interrupts it.
+    await new Promise((r) => setTimeout(r, 5));
+    const secondTurnPromise = orchestrator.handleCallerUtterance('Second utterance');
+
+    await Promise.all([firstTurnPromise, secondTurnPromise]);
+
+    const allTokens = relay.sentTokens.map((t) => t.token).join('');
+    expect(allTokens).toContain('Second turn response.');
+    expect(allTokens).not.toContain('technical issue');
+
+    orchestrator.destroy();
+  });
+
+  test('rapid caller barge-in coalesces contiguous user turns for role alternation', async () => {
+    let callCount = 0;
+    mockStreamFn.mockImplementation((...args: unknown[]) => {
+      callCount++;
+      if (callCount === 1) {
+        const emitter = new EventEmitter();
+        const options = args[1] as { signal?: AbortSignal } | undefined;
+        return {
+          on: (event: string, handler: (...evtArgs: unknown[]) => void) => {
+            emitter.on(event, handler);
+            return { on: () => ({ on: () => ({}) }) };
+          },
+          finalMessage: () =>
+            new Promise((_, reject) => {
+              options?.signal?.addEventListener('abort', () => {
+                const err = new Error('aborted');
+                err.name = 'AbortError';
+                reject(err);
+              }, { once: true });
+            }),
+        };
+      }
+
+      const firstArg = args[0] as { messages: Array<{ role: string; content: string }> };
+      const roles = firstArg.messages.map((m) => m.role);
+      for (let i = 1; i < roles.length; i++) {
+        expect(!(roles[i - 1] === 'user' && roles[i] === 'user')).toBe(true);
+      }
+      const userMessages = firstArg.messages.filter((m) => m.role === 'user');
+      const lastUser = userMessages[userMessages.length - 1];
+      expect(lastUser?.content).toContain('First caller utterance');
+      expect(lastUser?.content).toContain('Second caller utterance');
+      return createMockStream(['Merged turn handled.']);
+    });
+
+    const { relay, orchestrator } = setupOrchestrator();
+    const firstTurnPromise = orchestrator.handleCallerUtterance('First caller utterance');
+    await new Promise((r) => setTimeout(r, 5));
+    const secondTurnPromise = orchestrator.handleCallerUtterance('Second caller utterance');
+
+    await Promise.all([firstTurnPromise, secondTurnPromise]);
+
+    const allTokens = relay.sentTokens.map((t) => t.token).join('');
+    expect(allTokens).toContain('Merged turn handled.');
+
+    orchestrator.destroy();
+  });
+
+  test('interrupt then next caller prompt still preserves role alternation', async () => {
+    let callCount = 0;
+    mockStreamFn.mockImplementation((...args: unknown[]) => {
+      callCount++;
+      if (callCount === 1) {
+        const emitter = new EventEmitter();
+        const options = args[1] as { signal?: AbortSignal } | undefined;
+        return {
+          on: (event: string, handler: (...evtArgs: unknown[]) => void) => {
+            emitter.on(event, handler);
+            return { on: () => ({ on: () => ({}) }) };
+          },
+          finalMessage: () =>
+            new Promise((_, reject) => {
+              options?.signal?.addEventListener('abort', () => {
+                const err = new Error('aborted');
+                err.name = 'AbortError';
+                reject(err);
+              }, { once: true });
+            }),
+        };
+      }
+
+      const firstArg = args[0] as { messages: Array<{ role: string; content: string }> };
+      const roles = firstArg.messages.map((m) => m.role);
+      for (let i = 1; i < roles.length; i++) {
+        expect(!(roles[i - 1] === 'user' && roles[i] === 'user')).toBe(true);
+      }
+      const userMessages = firstArg.messages.filter((m) => m.role === 'user');
+      const lastUser = userMessages[userMessages.length - 1];
+      expect(lastUser?.content).toContain('First caller utterance');
+      expect(lastUser?.content).toContain('Second caller utterance');
+      return createMockStream(['Post-interrupt response.']);
+    });
+
+    const { relay, orchestrator } = setupOrchestrator();
+    const firstTurnPromise = orchestrator.handleCallerUtterance('First caller utterance');
+    await new Promise((r) => setTimeout(r, 5));
+    orchestrator.handleInterrupt();
+    const secondTurnPromise = orchestrator.handleCallerUtterance('Second caller utterance');
+
+    await Promise.all([firstTurnPromise, secondTurnPromise]);
+
+    const allTokens = relay.sentTokens.map((t) => t.token).join('');
+    expect(allTokens).toContain('Post-interrupt response.');
+    expect(allTokens).not.toContain('technical issue');
+
+    orchestrator.destroy();
+  });
+
   test('handleUserAnswer: returns false when not in waiting_on_user state', async () => {
     const { orchestrator } = setupOrchestrator();
 
@@ -435,6 +604,87 @@ describe('call-orchestrator', () => {
     orchestrator.destroy();
   });
 
+  test('handleInterrupt: increments llmRunVersion to suppress stale turn side effects', async () => {
+    // Use a stream whose finalMessage resolves immediately but whose
+    // continuation (the code after `await stream.finalMessage()`) will
+    // run asynchronously. This simulates the race where the promise
+    // microtask is queued right as handleInterrupt fires.
+    mockStreamFn.mockImplementation(() => {
+      const emitter = new EventEmitter();
+      return {
+        on: (event: string, handler: (...args: unknown[]) => void) => {
+          emitter.on(event, handler);
+          return { on: () => ({ on: () => ({}) }) };
+        },
+        finalMessage: () => {
+          // Emit some tokens synchronously
+          emitter.emit('text', 'Stale response that should be suppressed.');
+          return Promise.resolve({
+            content: [{ type: 'text', text: 'Stale response that should be suppressed.' }],
+          });
+        },
+      };
+    });
+
+    const { relay, orchestrator } = setupOrchestrator();
+
+    // Start an LLM turn (don't await — we want to interrupt mid-flight)
+    const turnPromise = orchestrator.handleCallerUtterance('Hello');
+
+    // Interrupt immediately. Because finalMessage resolves as a microtask,
+    // its continuation hasn't run yet. handleInterrupt increments
+    // llmRunVersion so the continuation's isCurrentRun check will fail.
+    orchestrator.handleInterrupt();
+
+    // Let the stale turn's microtask continuation execute
+    await turnPromise;
+
+    // The orchestrator should remain idle — the stale turn must not
+    // have pushed state to waiting_on_user or any other post-turn state.
+    expect(orchestrator.getState()).toBe('idle');
+
+    // No technical-issue fallback should have been sent
+    const errorTokens = relay.sentTokens.filter((t) => t.token.includes('technical issue'));
+    expect(errorTokens.length).toBe(0);
+
+    // endSession should NOT have been called by the stale turn
+    expect(relay.endCalled).toBe(false);
+
+    orchestrator.destroy();
+  });
+
+  test('handleInterrupt: sends turn terminator when interrupting active speech', async () => {
+    mockStreamFn.mockImplementation((...args: unknown[]) => {
+      const emitter = new EventEmitter();
+      const options = args[1] as { signal?: AbortSignal } | undefined;
+      return {
+        on: (event: string, handler: (...evtArgs: unknown[]) => void) => {
+          emitter.on(event, handler);
+          return { on: () => ({ on: () => ({}) }) };
+        },
+        finalMessage: () =>
+          new Promise((_, reject) => {
+            options?.signal?.addEventListener('abort', () => {
+              const err = new Error('aborted');
+              err.name = 'AbortError';
+              reject(err);
+            }, { once: true });
+          }),
+      };
+    });
+
+    const { relay, orchestrator } = setupOrchestrator();
+    const turnPromise = orchestrator.handleCallerUtterance('Start speaking');
+    await new Promise((r) => setTimeout(r, 5));
+    orchestrator.handleInterrupt();
+    await turnPromise;
+
+    const endTurnMarkers = relay.sentTokens.filter((t) => t.token === '' && t.last === true);
+    expect(endTurnMarkers.length).toBeGreaterThan(0);
+
+    orchestrator.destroy();
+  });
+
   // ── destroy ───────────────────────────────────────────────────────
 
   test('destroy: unregisters orchestrator', () => {
@@ -622,4 +872,75 @@ describe('call-orchestrator', () => {
 
     orchestrator.destroy();
   });
+
+  // ── System prompt: identity phrasing ────────────────────────────────
+
+  test('system prompt contains resolved user reference (default)', async () => {
+    mockStreamFn.mockImplementation((...args: unknown[]) => {
+      const firstArg = args[0] as { system: string };
+      expect(firstArg.system).toContain('on behalf of my human');
+      return createMockStream(['Hello.']);
+    });
+
+    const { orchestrator } = setupOrchestrator();
+    await orchestrator.handleCallerUtterance('Hi');
+    orchestrator.destroy();
+  });
+
+  test('system prompt contains resolved user reference when set to a name', async () => {
+    mockUserReference = 'John';
+    mockStreamFn.mockImplementation((...args: unknown[]) => {
+      const firstArg = args[0] as { system: string };
+      expect(firstArg.system).toContain('on behalf of John');
+      return createMockStream(['Hello John\'s contact.']);
+    });
+
+    const { orchestrator } = setupOrchestrator();
+    await orchestrator.handleCallerUtterance('Hi');
+    orchestrator.destroy();
+  });
+
+  test('system prompt does not hardcode "your user" in the opening line', async () => {
+    mockUserReference = 'Alice';
+    mockStreamFn.mockImplementation((...args: unknown[]) => {
+      const firstArg = args[0] as { system: string };
+      expect(firstArg.system).not.toContain('on behalf of your user');
+      expect(firstArg.system).toContain('on behalf of Alice');
+      return createMockStream(['Hi there.']);
+    });
+
+    const { orchestrator } = setupOrchestrator();
+    await orchestrator.handleCallerUtterance('Hello');
+    orchestrator.destroy();
+  });
+
+  test('system prompt includes assistant identity bias rule', async () => {
+    mockStreamFn.mockImplementation((...args: unknown[]) => {
+      const firstArg = args[0] as { system: string };
+      expect(firstArg.system).toContain('refer to yourself as an assistant');
+      expect(firstArg.system).toContain('Avoid the phrase "AI assistant" unless directly asked');
+      return createMockStream(['Sure thing.']);
+    });
+
+    const { orchestrator } = setupOrchestrator();
+    await orchestrator.handleCallerUtterance('Hi');
+    orchestrator.destroy();
+  });
+
+  test('assistant identity rule appears before disclosure rule in prompt', async () => {
+    mockStreamFn.mockImplementation((...args: unknown[]) => {
+      const firstArg = args[0] as { system: string };
+      const prompt = firstArg.system;
+      const identityIdx = prompt.indexOf('refer to yourself as an assistant');
+      const disclosureIdx = prompt.indexOf('Be concise');
+      expect(identityIdx).toBeGreaterThan(-1);
+      expect(disclosureIdx).toBeGreaterThan(-1);
+      expect(identityIdx).toBeLessThan(disclosureIdx);
+      return createMockStream(['OK.']);
+    });
+
+    const { orchestrator } = setupOrchestrator();
+    await orchestrator.handleCallerUtterance('Test');
+    orchestrator.destroy();
+  });
 });