@vellumai/assistant 0.4.2 → 0.4.4

package/src/notifications/guardian-question-mode.ts

@@ -0,0 +1,419 @@
+/**
+ * Shared request-kind and instruction-mode resolver for guardian.question signals.
+ *
+ * Explicit request kinds provide a stable contract between producers and
+ * notification rendering logic, avoiding implicit inference from incidental
+ * fields like `toolName`.
+ */
+
+export const GUARDIAN_QUESTION_REQUEST_KINDS = {
+  pending_question: 'pending_question',
+  tool_approval: 'tool_approval',
+  tool_grant_request: 'tool_grant_request',
+  access_request: 'access_request',
+} as const;
+
+export type GuardianQuestionRequestKind = keyof typeof GUARDIAN_QUESTION_REQUEST_KINDS;
+export type GuardianQuestionInstructionMode = 'approval' | 'answer';
+
+interface GuardianRequestKindModeConfig {
+  defaultMode: GuardianQuestionInstructionMode;
+  modeWhenToolNamePresent?: GuardianQuestionInstructionMode;
+}
+
+const REQUEST_KIND_MODE_CONFIG: Record<GuardianQuestionRequestKind, GuardianRequestKindModeConfig> = {
+  pending_question: {
+    defaultMode: 'answer',
+    modeWhenToolNamePresent: 'approval',
+  },
+  tool_approval: {
+    defaultMode: 'approval',
+  },
+  tool_grant_request: {
+    defaultMode: 'approval',
+  },
+  access_request: {
+    defaultMode: 'approval',
+  },
+};
+
+interface GuardianQuestionPayloadBase {
+  requestId: string;
+  requestCode: string;
+  questionText: string;
+}
+
+interface GuardianQuestionPayloadBaseWithDiscriminator extends GuardianQuestionPayloadBase {
+  requestKind: GuardianQuestionRequestKind;
+  [key: string]: unknown;
+}
+
+export interface GuardianRequestModeInput {
+  kind: unknown;
+  toolName?: unknown;
+}
+
+export interface GuardianRequestTextInput {
+  requestCode: string;
+  questionText?: string | null;
+  toolName?: string | null;
+}
+
+type GuardianDisambiguationCategory = 'questions' | 'approvals';
+
+interface GuardianModeTextConfig {
+  invalidActionWithCode: (requestCode: string) => string;
+  invalidActionWithoutCode: string;
+  buildCodeOnlyHeader: (request: GuardianRequestTextInput) => string;
+  buildCodeOnlyDetailLine: (request: GuardianRequestTextInput) => string | null;
+  buildDisambiguationLabel: (request: Pick<GuardianRequestTextInput, 'questionText' | 'toolName'>) => string;
+  disambiguationCategory: GuardianDisambiguationCategory;
+}
+
+const MODE_TEXT_CONFIG: Record<GuardianQuestionInstructionMode, GuardianModeTextConfig> = {
+  answer: {
+    invalidActionWithCode: (requestCode) =>
+      `I found request ${requestCode}, but I still need your answer. Reply "${requestCode} <your answer>".`,
+    invalidActionWithoutCode:
+      "I couldn't determine your answer. Reply with the request code followed by your answer (e.g., \"ABC123 3pm works\").",
+    buildCodeOnlyHeader: (request) => `I found question ${request.requestCode}.`,
+    buildCodeOnlyDetailLine: (request) => request.questionText ? `Question: ${request.questionText}` : null,
+    buildDisambiguationLabel: (request) => request.questionText ?? 'question',
+    disambiguationCategory: 'questions',
+  },
+  approval: {
+    invalidActionWithCode: (requestCode) =>
+      `I found request ${requestCode}, but I need to know your decision. Reply "${requestCode} approve" or "${requestCode} reject".`,
+    invalidActionWithoutCode:
+      "I couldn't determine your intended action. Reply with the request code followed by 'approve' or 'reject' (e.g., \"ABC123 approve\").",
+    buildCodeOnlyHeader: (request) => `I found request ${request.requestCode} for ${request.toolName ?? 'an action'}.`,
+    buildCodeOnlyDetailLine: (request) => request.questionText ? `Details: ${request.questionText}` : null,
+    buildDisambiguationLabel: (request) => request.toolName ?? request.questionText ?? 'action',
+    disambiguationCategory: 'approvals',
+  },
+};
+
+export interface PendingQuestionGuardianPayload extends GuardianQuestionPayloadBaseWithDiscriminator {
+  requestKind: 'pending_question';
+  callSessionId: string;
+  activeGuardianRequestCount: number;
+  /**
+   * Voice tool-approval requests are persisted as pending_question with tool
+   * metadata so they still route through pending-question resolution.
+   */
+  toolName?: string;
+}
+
+export interface ToolApprovalGuardianPayload extends GuardianQuestionPayloadBaseWithDiscriminator {
+  requestKind: 'tool_approval';
+  toolName: string;
+}
+
+export interface ToolGrantGuardianPayload extends GuardianQuestionPayloadBaseWithDiscriminator {
+  requestKind: 'tool_grant_request';
+  toolName: string;
+}
+
+export interface AccessRequestGuardianPayload extends GuardianQuestionPayloadBaseWithDiscriminator {
+  requestKind: 'access_request';
+}
+
+export type GuardianQuestionPayload =
+  | PendingQuestionGuardianPayload
+  | ToolApprovalGuardianPayload
+  | ToolGrantGuardianPayload
+  | AccessRequestGuardianPayload;
+
+export interface GuardianQuestionModeResolution {
+  mode: GuardianQuestionInstructionMode;
+  requestKind: GuardianQuestionRequestKind | null;
+  legacyFallbackUsed: boolean;
+}
+
+function nonEmptyString(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+export function parseGuardianQuestionRequestKind(
+  payload: Record<string, unknown>,
+): GuardianQuestionRequestKind | null {
+  const raw = nonEmptyString(payload.requestKind);
+  if (!raw) return null;
+
+  switch (raw) {
+    case 'pending_question':
+    case 'tool_approval':
+    case 'tool_grant_request':
+    case 'access_request':
+      return raw;
+    default:
+      return null;
+  }
+}
+
+function parseBasePayload(payload: Record<string, unknown>): GuardianQuestionPayloadBase | null {
+  const requestId = nonEmptyString(payload.requestId);
+  const requestCode = nonEmptyString(payload.requestCode);
+  const questionText = nonEmptyString(payload.questionText);
+  if (!requestId || !requestCode || !questionText) return null;
+  return { requestId, requestCode, questionText };
+}
+
+/**
+ * Parse a guardian.question context payload into a strict discriminated union.
+ *
+ * Returns null when required fields for the declared requestKind are missing,
+ * or when requestKind is absent/unknown.
+ */
+export function parseGuardianQuestionPayload(
+  payload: Record<string, unknown>,
+): GuardianQuestionPayload | null {
+  const requestKind = parseGuardianQuestionRequestKind(payload);
+  if (!requestKind) return null;
+
+  const base = parseBasePayload(payload);
+  if (!base) return null;
+
+  switch (requestKind) {
+    case 'pending_question': {
+      const callSessionId = nonEmptyString(payload.callSessionId);
+      const activeGuardianRequestCount = typeof payload.activeGuardianRequestCount === 'number'
+        ? payload.activeGuardianRequestCount
+        : undefined;
+      const toolName = nonEmptyString(payload.toolName);
+      if (!callSessionId || activeGuardianRequestCount === undefined || Number.isNaN(activeGuardianRequestCount)) {
+        return null;
+      }
+      const pendingQuestionPayload: PendingQuestionGuardianPayload = {
+        requestKind,
+        ...base,
+        callSessionId,
+        activeGuardianRequestCount,
+      };
+      if (toolName) {
+        pendingQuestionPayload.toolName = toolName;
+      }
+      return {
+        ...pendingQuestionPayload,
+      };
+    }
+    case 'tool_approval':
+    case 'tool_grant_request': {
+      const toolName = nonEmptyString(payload.toolName);
+      if (!toolName) return null;
+      return {
+        requestKind,
+        ...base,
+        toolName,
+      };
+    }
+    case 'access_request':
+      return {
+        requestKind,
+        ...base,
+      };
+    default:
+      return null;
+  }
+}
+
+export function resolveGuardianInstructionModeForRequestKind(
+  requestKind: GuardianQuestionRequestKind,
+  toolName?: string | null,
+): GuardianQuestionInstructionMode {
+  const config = REQUEST_KIND_MODE_CONFIG[requestKind];
+  const normalizedToolName = nonEmptyString(toolName);
+  if (normalizedToolName && config.modeWhenToolNamePresent) {
+    return config.modeWhenToolNamePresent;
+  }
+
+  return config.defaultMode;
+}
+
+export function resolveGuardianInstructionModeFromFields(
+  requestKindValue: unknown,
+  toolNameValue: unknown,
+): { requestKind: GuardianQuestionRequestKind; mode: GuardianQuestionInstructionMode } | null {
+  const requestKind = parseGuardianQuestionRequestKind({ requestKind: requestKindValue });
+  if (!requestKind) return null;
+
+  return {
+    requestKind,
+    mode: resolveGuardianInstructionModeForRequestKind(requestKind, nonEmptyString(toolNameValue)),
+  };
+}
+
+export function resolveGuardianInstructionModeForRequest(
+  request?: GuardianRequestModeInput | null,
+): GuardianQuestionInstructionMode {
+  if (!request) return 'approval';
+  const modeResolution = resolveGuardianInstructionModeFromFields(request.kind, request.toolName);
+  if (!modeResolution) return 'approval';
+  return modeResolution.mode;
+}
+
+function getModeTextConfig(mode: GuardianQuestionInstructionMode): GuardianModeTextConfig {
+  return MODE_TEXT_CONFIG[mode];
+}
+
+export function buildGuardianReplyDirective(
+  requestCode: string,
+  mode: GuardianQuestionInstructionMode,
+): string {
+  switch (mode) {
+    case 'approval':
+      return `Reply "${requestCode} approve" or "${requestCode} reject".`;
+    case 'answer':
+      return `Reply "${requestCode} <your answer>".`;
+    default: {
+      const _never: never = mode;
+      return _never;
+    }
+  }
+}
+
+export function buildGuardianRequestCodeInstruction(
+  requestCode: string,
+  mode: GuardianQuestionInstructionMode,
+): string {
+  return `Reference code: ${requestCode}. ${buildGuardianReplyDirective(requestCode, mode)}`;
+}
+
+export function buildGuardianInvalidActionReply(
+  mode: GuardianQuestionInstructionMode,
+  requestCode?: string,
+): string {
+  const config = getModeTextConfig(mode);
+  if (requestCode) return config.invalidActionWithCode(requestCode);
+  return config.invalidActionWithoutCode;
+}
+
+export function buildGuardianCodeOnlyClarification(
+  mode: GuardianQuestionInstructionMode,
+  request: GuardianRequestTextInput,
+): string {
+  const config = getModeTextConfig(mode);
+  const lines = [
+    config.buildCodeOnlyHeader(request),
+  ];
+  const detailLine = config.buildCodeOnlyDetailLine(request);
+  if (detailLine) {
+    lines.push(detailLine);
+  }
+  lines.push(buildGuardianReplyDirective(request.requestCode, mode));
+  return lines.join('\n');
+}
+
+export function buildGuardianDisambiguationLabel(
+  mode: GuardianQuestionInstructionMode,
+  request: Pick<GuardianRequestTextInput, 'questionText' | 'toolName'>,
+): string {
+  return getModeTextConfig(mode).buildDisambiguationLabel(request);
+}
+
+export function buildGuardianDisambiguationExample(
+  mode: GuardianQuestionInstructionMode,
+  requestCode: string,
+): string {
+  const category = getModeTextConfig(mode).disambiguationCategory;
+  const replyDirective = buildGuardianReplyDirective(requestCode, mode);
+  return `For ${category}: ${replyDirective.replace(/^Reply/, 'reply')}`;
+}
+
+export function hasGuardianRequestCodeInstruction(
+  text: string | undefined,
+  requestCode: string,
+  mode: GuardianQuestionInstructionMode,
+): boolean {
+  if (typeof text !== 'string') return false;
+  const upper = text.toUpperCase();
+  const normalizedCode = requestCode.toUpperCase();
+
+  switch (mode) {
+    case 'approval':
+      return upper.includes(`${normalizedCode} APPROVE`) && upper.includes(`${normalizedCode} REJECT`);
+    case 'answer': {
+      const hasAnswerInstruction = upper.includes(`${normalizedCode} <YOUR ANSWER>`);
+      const hasApprovalInstruction = upper.includes(`${normalizedCode} APPROVE`) || upper.includes(`${normalizedCode} REJECT`);
+      return hasAnswerInstruction && !hasApprovalInstruction;
+    }
+    default: {
+      const _never: never = mode;
+      return _never;
+    }
+  }
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function normalizeInstructionText(value: string): string {
+  return value
+    .replace(/[ \t]+\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+export function stripConflictingGuardianRequestInstructions(
+  text: string,
+  requestCode: string,
+  mode: GuardianQuestionInstructionMode,
+): string {
+  const escapedCode = escapeRegExp(requestCode);
+  const approvalInstructionPattern = new RegExp(
+    `(?:Reference\\s+code:\\s*${escapedCode}\\.?\\s*)?Reply\\s+"${escapedCode}\\s+approve"\\s+or\\s+"${escapedCode}\\s+reject"\\.?`,
+    'ig',
+  );
+  const answerInstructionPattern = new RegExp(
+    `(?:Reference\\s+code:\\s*${escapedCode}\\.?\\s*)?Reply\\s+"${escapedCode}\\s+<your\\s+answer>"\\.?`,
+    'ig',
+  );
+
+  const next = mode === 'answer'
+    ? text.replace(approvalInstructionPattern, '')
+    : text.replace(answerInstructionPattern, '');
+
+  return normalizeInstructionText(next);
+}
+
+/**
+ * Resolve guardian reply instruction mode from request kind.
+ *
+ * Backward compatibility: if requestKind is missing/unknown, fall back to
+ * toolName presence so previously persisted payloads keep working.
+ */
+export function resolveGuardianQuestionInstructionMode(
+  payload: Record<string, unknown>,
+): GuardianQuestionModeResolution {
+  const parsed = parseGuardianQuestionPayload(payload);
+  if (parsed) {
+    const parsedToolName = nonEmptyString('toolName' in parsed ? parsed.toolName : null);
+    return {
+      mode: resolveGuardianInstructionModeForRequestKind(parsed.requestKind, parsedToolName),
+      requestKind: parsed.requestKind,
+      legacyFallbackUsed: false,
+    };
+  }
+
+  const requestKindResolution = resolveGuardianInstructionModeFromFields(
+    payload.requestKind,
+    payload.toolName,
+  );
+  if (requestKindResolution) {
+    return {
+      mode: requestKindResolution.mode,
+      requestKind: requestKindResolution.requestKind,
+      legacyFallbackUsed: true,
+    };
+  }
+
+  const toolName = nonEmptyString(payload.toolName);
+  return {
+    mode: toolName ? 'approval' : 'answer',
+    requestKind: null,
+    legacyFallbackUsed: true,
+  };
+}

package/src/notifications/signal.ts

@@ -4,6 +4,8 @@
  * decision engine route contextually.
  */
 
+import type { GuardianQuestionPayload } from './guardian-question-mode.js';
+
 export interface AttentionHints {
   requiresAction: boolean;
   urgency: 'low' | 'medium' | 'high';
@@ -14,14 +16,23 @@ export interface AttentionHints {
 
 export type RoutingIntent = 'single_channel' | 'multi_channel' | 'all_channels';
 
-export interface NotificationSignal {
+export interface NotificationEventContextPayloadMap {
+  'guardian.question': GuardianQuestionPayload;
+}
+
+export type NotificationContextPayload<TEventName extends string = string> =
+  TEventName extends keyof NotificationEventContextPayloadMap
+    ? NotificationEventContextPayloadMap[TEventName]
+    : Record<string, unknown>;
+
+export interface NotificationSignal<TEventName extends string = string> {
   signalId: string;
   assistantId: string;
   createdAt: number; // epoch ms
   sourceChannel: string; // free-form: 'vellum', 'telegram', 'voice', 'scheduler', etc.
   sourceSessionId: string;
-  sourceEventName: string; // free-form: 'reminder_fired', 'schedule_complete', 'guardian_question', etc.
-  contextPayload: Record<string, unknown>;
+  sourceEventName: TEventName; // free-form: 'reminder_fired', 'schedule_complete', 'guardian_question', etc.
+  contextPayload: NotificationContextPayload<TEventName>;
   attentionHints: AttentionHints;
   /** Routing intent from the source (e.g. reminder). Controls post-decision channel enforcement. */
   routingIntent?: RoutingIntent;

package/src/permissions/checker.ts

@@ -776,7 +776,19 @@ export async function generateAllowlistOptions(toolName: string, input: Record<s
   return [{ label: '*', description: 'Everything', pattern: '*' }];
 }
 
-export function generateScopeOptions(workingDir: string, _toolName?: string): ScopeOption[] {
+// Directory-based scope only applies to filesystem and shell tools.
+// All other tools auto-use "everywhere" (the client handles this).
+export const SCOPE_AWARE_TOOLS = new Set([
+  'bash', 'host_bash',
+  'file_read', 'file_write', 'file_edit',
+  'host_file_read', 'host_file_write', 'host_file_edit',
+]);
+
+export function generateScopeOptions(workingDir: string, toolName?: string): ScopeOption[] {
+  if (toolName && !SCOPE_AWARE_TOOLS.has(toolName)) {
+    return [];
+  }
+
   const home = homedir();
   const options: ScopeOption[] = [];
 

package/src/permissions/prompter.ts

@@ -21,14 +21,25 @@ interface PendingPrompt {
   timer: ReturnType<typeof setTimeout>;
 }
 
+export type ConfirmationStateCallback = (
+  requestId: string,
+  state: 'pending' | 'approved' | 'denied' | 'timed_out' | 'resolved_stale',
+  source: 'button' | 'inline_nl' | 'auto_deny' | 'timeout' | 'system',
+) => void;
+
 export class PermissionPrompter {
   private pending = new Map<string, PendingPrompt>();
   private sendToClient: (msg: ServerMessage) => void;
+  private onStateChanged?: ConfirmationStateCallback;
 
   constructor(sendToClient: (msg: ServerMessage) => void) {
     this.sendToClient = sendToClient;
   }
 
+  setOnStateChanged(cb: ConfirmationStateCallback): void {
+    this.onStateChanged = cb;
+  }
+
   updateSender(sendToClient: (msg: ServerMessage) => void): void {
     this.sendToClient = sendToClient;
   }
@@ -60,6 +71,7 @@ export class PermissionPrompter {
       const timer = setTimeout(() => {
         this.pending.delete(requestId);
         log.warn({ requestId, toolName }, 'Permission prompt timed out, defaulting to deny');
+        this.onStateChanged?.(requestId, 'timed_out', 'timeout');
         resolve({ decision: 'deny' });
       }, timeoutMs);
 
@@ -90,6 +102,8 @@ export class PermissionPrompter {
         executionTarget,
         persistentDecisionsAllowed: persistentDecisionsAllowed ?? true,
       });
+
+      this.onStateChanged?.(requestId, 'pending', 'system');
     });
   }
 

package/src/providers/anthropic/client.ts

@@ -512,6 +512,10 @@ export class AnthropicProvider implements Provider {
             )
           : this.client.messages.stream(params, { signal: timeoutSignal });
 
+        // Track whether we've seen a text content block so we can insert a
+        // separator between consecutive text blocks in the same response.
+        let hasSeenTextBlock = false;
+
         stream.on("text", (text) => {
           onEvent?.({ type: "text_delta", text });
         });
@@ -527,6 +531,22 @@ export class AnthropicProvider implements Provider {
         let pendingInputJsonFlush: ReturnType<typeof setTimeout> | undefined;
 
         stream.on("streamEvent", (event) => {
+          // Insert a space separator when a new text content block starts
+          // after a previous one, so consecutive text blocks don't get
+          // concatenated without whitespace (e.g. "sentence.NextSentence").
+          // Uses a space instead of \n because the client's MarkdownRenderer
+          // can collapse soft line breaks (\n) within a paragraph.
+          if (event.type === 'content_block_start' && event.content_block.type === 'text') {
+            if (hasSeenTextBlock) {
+              onEvent?.({ type: "text_delta", text: " " });
+            }
+            hasSeenTextBlock = true;
+          } else if (event.type === 'content_block_start') {
+            // Reset on non-text blocks so that text separated by tool_use
+            // (text -> tool_use -> text) doesn't get a spurious leading space
+            // in the second text segment.
+            hasSeenTextBlock = false;
+          }
           if (event.type === 'content_block_start' && event.content_block.type === 'tool_use') {
             currentStreamingToolName = event.content_block.name;
             accumulatedInputJson = '';

package/src/providers/provider-send-message.ts

@@ -107,10 +107,22 @@ export function extractText(response: ProviderResponse): string {
  * Extract all text blocks from a ProviderResponse and join them.
  */
 export function extractAllText(response: ProviderResponse): string {
-  return response.content
+  const parts = response.content
     .filter((b): b is Extract<ContentBlock, { type: 'text' }> => b.type === 'text')
-    .map((b) => b.text)
-    .join('');
+    .map((b) => b.text);
+  // Join consecutive text blocks with a space, but skip the separator when
+  // either side already has whitespace (avoids double-spacing).
+  let result = parts[0] ?? '';
+  for (let i = 1; i < parts.length; i++) {
+    const prev = result[result.length - 1];
+    const next = parts[i][0];
+    if (prev && next && prev !== ' ' && prev !== '\n' && prev !== '\t' &&
+        next !== ' ' && next !== '\n' && next !== '\t') {
+      result += ' ';
+    }
+    result += parts[i];
+  }
+  return result;
 }
 
 /**