@vellumai/assistant 0.3.4 → 0.3.5

package/src/messaging/providers/sms/adapter.ts

@@ -0,0 +1,204 @@
+/**
+ * SMS messaging provider adapter.
+ *
+ * Enables proactive outbound SMS messaging via the gateway's /deliver/sms
+ * endpoint. Similar to the Telegram provider, SMS delivery is proxied through
+ * the gateway which owns the Twilio credentials and handles the Messages API.
+ *
+ * Twilio credentials (account_sid, auth_token) and a configured phone number
+ * are required for connectivity. The phone number is resolved from the config
+ * (sms.phoneNumber), env var (TWILIO_PHONE_NUMBER), or secure key fallback.
+ *
+ * The `token` parameter in MessagingProvider methods is unused for SMS
+ * because delivery is authenticated via the gateway's bearer token, not
+ * a per-user OAuth token.
+ */
+
+import type { MessagingProvider } from '../../provider.js';
+import type {
+  Conversation,
+  Message,
+  SearchResult,
+  SendResult,
+  ConnectionInfo,
+  ListOptions,
+  HistoryOptions,
+  SearchOptions,
+  SendOptions,
+} from '../../provider-types.js';
+import { getSecureKey } from '../../../security/secure-keys.js';
+import { readHttpToken } from '../../../util/platform.js';
+import { loadConfig } from '../../../config/loader.js';
+import { getOrCreateConversation } from '../../../memory/conversation-key-store.js';
+import * as externalConversationStore from '../../../memory/external-conversation-store.js';
+import * as sms from './client.js';
+
+/** Resolve the gateway base URL, preferring GATEWAY_INTERNAL_BASE_URL if set. */
+function getGatewayUrl(): string {
+  if (process.env.GATEWAY_INTERNAL_BASE_URL) {
+    return process.env.GATEWAY_INTERNAL_BASE_URL.replace(/\/+$/, '');
+  }
+  const port = Number(process.env.GATEWAY_PORT) || 7830;
+  return `http://127.0.0.1:${port}`;
+}
+
+/** Read the runtime HTTP bearer token used to authenticate with the gateway. */
+function getBearerToken(): string {
+  const token = readHttpToken();
+  if (!token) {
+    throw new Error('No runtime HTTP bearer token available — is the daemon running?');
+  }
+  return token;
+}
+
+/** Check whether Twilio credentials are stored. */
+function hasTwilioCredentials(): boolean {
+  return (
+    !!getSecureKey('credential:twilio:account_sid') &&
+    !!getSecureKey('credential:twilio:auth_token')
+  );
+}
+
+/**
+ * Resolve the configured SMS phone number.
+ * Priority: assistant-scoped phone number > TWILIO_PHONE_NUMBER env > config sms.phoneNumber > secure key fallback.
+ */
+function getPhoneNumber(assistantId?: string): string | undefined {
+  // Check assistant-scoped phone number first
+  if (assistantId) {
+    try {
+      const config = loadConfig();
+      const assistantPhone = config.sms?.assistantPhoneNumbers?.[assistantId];
+      if (assistantPhone) return assistantPhone;
+    } catch {
+      // Config may not be available yet during early startup
+    }
+  }
+
+  const fromEnv = process.env.TWILIO_PHONE_NUMBER;
+  if (fromEnv) return fromEnv;
+
+  try {
+    const config = loadConfig();
+    if (config.sms?.phoneNumber) return config.sms.phoneNumber;
+  } catch {
+    // Config may not be available yet during early startup
+  }
+
+  return getSecureKey('credential:twilio:phone_number') || undefined;
+}
+
+function hasAnyAssistantPhoneNumber(): boolean {
+  try {
+    const config = loadConfig();
+    return Object.keys(config.sms?.assistantPhoneNumbers ?? {}).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+export const smsMessagingProvider: MessagingProvider = {
+  id: 'sms',
+  displayName: 'SMS',
+  credentialService: 'twilio',
+  capabilities: new Set(['send']),
+
+  /**
+   * SMS is connected when Twilio credentials are stored AND a phone number
+   * is configured. Without a phone number the gateway cannot determine
+   * the `from` for outbound messages.
+   */
+  isConnected(): boolean {
+    return hasTwilioCredentials() && (!!getPhoneNumber() || hasAnyAssistantPhoneNumber());
+  },
+
+  async testConnection(_token: string): Promise<ConnectionInfo> {
+    if (!hasTwilioCredentials()) {
+      return {
+        connected: false,
+        user: 'unknown',
+        platform: 'sms',
+        metadata: { error: 'No Twilio credentials found. Run the twilio-setup skill.' },
+      };
+    }
+
+    const phoneNumber = getPhoneNumber();
+    if (!phoneNumber && !hasAnyAssistantPhoneNumber()) {
+      return {
+        connected: false,
+        user: 'unknown',
+        platform: 'sms',
+        metadata: { error: 'No phone number configured. Run the twilio-setup skill to assign a number.' },
+      };
+    }
+
+    const accountSid = getSecureKey('credential:twilio:account_sid')!;
+
+    return {
+      connected: true,
+      user: phoneNumber ?? 'assistant-scoped numbers configured',
+      platform: 'sms',
+      metadata: {
+        accountSid: accountSid.slice(0, 6) + '...',
+        ...(phoneNumber ? { phoneNumber } : {}),
+        hasAssistantScopedPhoneNumbers: hasAnyAssistantPhoneNumber(),
+      },
+    };
+  },
+
+  async sendMessage(_token: string, conversationId: string, text: string, options?: SendOptions): Promise<SendResult> {
+    const gatewayUrl = getGatewayUrl();
+    const bearerToken = getBearerToken();
+    const assistantId = options?.assistantId;
+
+    const sendResult = await sms.sendMessage(gatewayUrl, bearerToken, conversationId, text, assistantId);
+
+    // Upsert external conversation binding so the conversation key mapping
+    // exists for the next inbound SMS from this number.
+    try {
+      const sourceChannel = 'sms';
+      const conversationKey = assistantId && assistantId !== 'self'
+        ? `asst:${assistantId}:${sourceChannel}:${conversationId}`
+        : `${sourceChannel}:${conversationId}`;
+      const { conversationId: internalId } = getOrCreateConversation(conversationKey);
+      // external_conversation_bindings is assistant-agnostic (unique by
+      // sourceChannel + externalChatId). Restrict proactive writes to self so
+      // multi-assistant sends cannot clobber each other's binding metadata.
+      if (!assistantId || assistantId === 'self') {
+        externalConversationStore.upsertOutboundBinding({
+          conversationId: internalId,
+          sourceChannel,
+          externalChatId: conversationId,
+        });
+      }
+    } catch {
+      // Best-effort — don't fail the send if binding upsert fails
+    }
+
+    // Use the Twilio message SID as the send result ID when available,
+    // falling back to a timestamp-based ID for older gateway versions.
+    const id = sendResult.messageSid || `sms-${Date.now()}`;
+
+    return {
+      id,
+      timestamp: Date.now(),
+      conversationId,
+    };
+  },
+
+  // SMS does not support listing conversations. The assistant can only
+  // send to known phone numbers (conversation IDs).
+  async listConversations(_token: string, _options?: ListOptions): Promise<Conversation[]> {
+    return [];
+  },
+
+  // SMS does not provide message history retrieval via the gateway.
+  async getHistory(_token: string, _conversationId: string, _options?: HistoryOptions): Promise<Message[]> {
+    return [];
+  },
+
+  // SMS does not support message search.
+  async search(_token: string, _query: string, _options?: SearchOptions): Promise<SearchResult> {
+    return { total: 0, messages: [], hasMore: false };
+  },
+};

package/src/messaging/providers/sms/client.ts

@@ -0,0 +1,93 @@
+/**
+ * Low-level SMS operations.
+ *
+ * Outbound message delivery routes through the gateway's /deliver/sms
+ * endpoint, which handles Twilio credential management and the Messages API.
+ * The gateway resolves the `from` number using the optional assistantId or
+ * its default Twilio phone number configuration.
+ */
+
+const DELIVERY_TIMEOUT_MS = 30_000;
+
+export class SmsApiError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'SmsApiError';
+  }
+}
+
+/** Payload accepted by the gateway's /deliver/sms endpoint. */
+interface DeliverPayload {
+  to: string;
+  text: string;
+  assistantId?: string;
+}
+
+/** Result returned by sendMessage with Twilio acceptance details. */
+export interface SmsSendResult {
+  messageSid?: string;
+  status?: string;
+  errorCode?: string | null;
+  errorMessage?: string | null;
+}
+
+/**
+ * Send an SMS message via the gateway's /deliver/sms endpoint.
+ *
+ * Returns Twilio acceptance details propagated from the gateway.
+ * "Accepted" means Twilio received it for delivery -- it has NOT yet
+ * been confirmed as delivered to the handset.
+ */
+export async function sendMessage(
+  gatewayUrl: string,
+  bearerToken: string,
+  to: string,
+  text: string,
+  assistantId?: string,
+): Promise<SmsSendResult> {
+  const payload: DeliverPayload = { to, text };
+  if (assistantId) {
+    payload.assistantId = assistantId;
+  }
+
+  const url = `${gatewayUrl}/deliver/sms`;
+  const resp = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${bearerToken}`,
+    },
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(DELIVERY_TIMEOUT_MS),
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => '<unreadable>');
+    throw new SmsApiError(
+      resp.status,
+      `Gateway /deliver/sms failed (${resp.status}): ${body}`,
+    );
+  }
+
+  try {
+    const data = (await resp.json()) as {
+      ok?: boolean;
+      messageSid?: string;
+      status?: string;
+      errorCode?: string | null;
+      errorMessage?: string | null;
+    };
+    return {
+      messageSid: data.messageSid,
+      status: data.status,
+      errorCode: data.errorCode,
+      errorMessage: data.errorMessage,
+    };
+  } catch {
+    // Older gateway versions may not return JSON with Twilio details
+    return {};
+  }
+}

package/src/messaging/providers/sms/types.ts

@@ -0,0 +1,7 @@
+/** Twilio SMS types used by the messaging provider. */
+
+export interface TwilioAccountInfo {
+  accountSid: string;
+  friendlyName: string;
+  phoneNumber: string;
+}

package/src/permissions/checker.ts

@@ -12,6 +12,7 @@ import { looksLikeHostPortShorthand, looksLikePathOnlyInput } from '../tools/net
 import { normalizeFilePath, isSkillSourcePath } from '../skills/path-classifier.js';
 import { isWorkspaceScopedInvocation } from './workspace-policy.js';
 import { buildShellCommandCandidates, buildShellAllowlistOptions, type ParsedCommand } from './shell-identity.js';
+import type { ManifestOverride } from '../tools/execution-target.js';
 
 // Ensures the legacy mode deprecation warning fires at most once per process.
 let _legacyDeprecationWarned = false;
@@ -244,7 +245,7 @@ async function buildCommandCandidates(toolName: string, input: Record<string, un
   return [...new Set(candidates)];
 }
 
-export async function classifyRisk(toolName: string, input: Record<string, unknown>, workingDir?: string, preParsed?: ParsedCommand): Promise<RiskLevel> {
+export async function classifyRisk(toolName: string, input: Record<string, unknown>, workingDir?: string, preParsed?: ParsedCommand, manifestOverride?: ManifestOverride): Promise<RiskLevel> {
   if (toolName === 'file_read') return RiskLevel.Low;
   if (toolName === 'file_write' || toolName === 'file_edit') {
     const filePath = getStringField(input, 'path', 'file_path');
@@ -342,6 +343,13 @@ export async function classifyRisk(toolName: string, input: Record<string, unkno
   const tool = getTool(toolName);
   if (tool) return tool.defaultRiskLevel;
 
+  // Use manifest metadata for unregistered skill tools so the Permission
+  // Simulator shows accurate risk levels instead of defaulting to Medium.
+  if (manifestOverride) {
+    const riskMap: Record<string, RiskLevel> = { low: RiskLevel.Low, medium: RiskLevel.Medium, high: RiskLevel.High };
+    return riskMap[manifestOverride.risk] ?? RiskLevel.Medium;
+  }
+
   // Unknown tool → Medium
   return RiskLevel.Medium;
 }
@@ -351,6 +359,7 @@ export async function check(
   input: Record<string, unknown>,
   workingDir: string,
   policyContext?: PolicyContext,
+  manifestOverride?: ManifestOverride,
 ): Promise<PermissionCheckResult> {
   // For shell tools, parse once and share the result to avoid duplicate tree-sitter work.
   let shellParsed: ParsedCommand | undefined;
@@ -361,7 +370,7 @@ export async function check(
     }
   }
 
-  const risk = await classifyRisk(toolName, input, workingDir, shellParsed);
+  const risk = await classifyRisk(toolName, input, workingDir, shellParsed, manifestOverride);
 
   // Build command string candidates for rule matching
   const commandCandidates = await buildCommandCandidates(toolName, input, workingDir, shellParsed);
@@ -406,11 +415,16 @@ export async function check(
   // Third-party skill-origin tools default to prompting when no trust rule
   // matches, regardless of risk level. Bundled skill tools are first-party
   // and trusted, so they fall through to the normal risk-based policy.
+  // When manifestOverride is present, the tool comes from a skill manifest
+  // but isn't registered — treat it as a third-party skill tool.
   if (!matchedRule) {
     const tool = getTool(toolName);
     if (tool?.origin === 'skill' && !tool.ownerSkillBundled) {
       return { decision: 'prompt', reason: 'Skill tool: requires approval by default' };
     }
+    if (!tool && manifestOverride) {
+      return { decision: 'prompt', reason: 'Skill tool: requires approval by default' };
+    }
   }
 
   // In strict mode, every tool without an explicit matching rule must be

package/src/runtime/approval-message-composer.ts

@@ -0,0 +1,143 @@
+/**
+ * Layered approval message composition system.
+ *
+ * Generates approval prompt text through a priority chain:
+ *   1. Assistant preface (macOS parity — reuse existing assistant text)
+ *   2. Deterministic fallback templates (natural, scenario-specific messages)
+ *
+ * A provider-backed generation layer can be inserted between 1 and 2 later.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ApprovalMessageScenario =
+  | 'standard_prompt'
+  | 'guardian_prompt'
+  | 'reminder_prompt'
+  | 'guardian_delivery_failed'
+  | 'guardian_request_forwarded'
+  | 'guardian_disambiguation'
+  | 'guardian_identity_mismatch'
+  | 'request_pending_guardian'
+  | 'guardian_decision_outcome'
+  | 'guardian_expired_requester'
+  | 'guardian_expired_guardian'
+  | 'guardian_verify_success'
+  | 'guardian_verify_failed'
+  | 'guardian_verify_challenge_setup'
+  | 'guardian_verify_status_bound'
+  | 'guardian_verify_status_unbound'
+  | 'guardian_deny_no_identity'
+  | 'guardian_deny_no_binding';
+
+export interface ApprovalMessageContext {
+  scenario: ApprovalMessageScenario;
+  channel?: string;
+  toolName?: string;
+  requesterIdentifier?: string;
+  guardianIdentifier?: string;
+  pendingCount?: number;
+  decision?: 'approved' | 'denied';
+  richUi?: boolean;
+  /** Pre-existing assistant text to reuse (macOS parity). */
+  assistantPreface?: string;
+  verifyCommand?: string;
+  ttlSeconds?: number;
+  failureReason?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compose an approval message using layered source selection:
+ *   1. If an assistant preface is provided and non-empty, return it directly.
+ *   2. Otherwise fall back to a deterministic scenario-specific template.
+ */
+export function composeApprovalMessage(context: ApprovalMessageContext): string {
+  if (context.assistantPreface && context.assistantPreface.trim().length > 0) {
+    return context.assistantPreface;
+  }
+
+  return getFallbackMessage(context);
+}
+
+// ---------------------------------------------------------------------------
+// Deterministic fallback templates
+// ---------------------------------------------------------------------------
+
+/**
+ * Return a scenario-specific deterministic fallback message.
+ *
+ * Each template is slightly more conversational than the old hard-coded
+ * strings while preserving all required semantic content (tool name,
+ * who must approve, next action, etc.).
+ */
+export function getFallbackMessage(context: ApprovalMessageContext): string {
+  switch (context.scenario) {
+    case 'standard_prompt':
+      return `I'd like to use the tool "${context.toolName ?? 'unknown'}". Would you like to allow this?`;
+
+    case 'guardian_prompt':
+      return `${context.requesterIdentifier ?? 'A user'} is requesting to use "${context.toolName ?? 'unknown'}". Please approve or deny this request.`;
+
+    case 'reminder_prompt':
+      return "I'm still waiting for your decision on the pending approval request.";
+
+    case 'guardian_delivery_failed':
+      return context.toolName
+        ? `Your request to run "${context.toolName}" could not be sent to the guardian for approval. The request has been denied for safety.`
+        : "I wasn't able to reach the guardian to request approval. The request has been denied for safety.";
+
+    case 'guardian_request_forwarded':
+      return `Your request to use "${context.toolName ?? 'unknown'}" has been forwarded to the guardian for approval. I'll let you know once they decide.`;
+
+    case 'guardian_disambiguation':
+      return `There are ${context.pendingCount ?? 'multiple'} pending approval requests. Please use the approval buttons to specify which request you're responding to.`;
+
+    case 'guardian_identity_mismatch':
+      return 'This approval request can only be handled by the designated guardian.';
+
+    case 'request_pending_guardian':
+      return 'Your request is pending guardian approval. Please wait for the guardian to respond.';
+
+    case 'guardian_decision_outcome':
+      return `The guardian has ${context.decision ?? 'decided on'} your request to use "${context.toolName ?? 'unknown'}".`;
+
+    case 'guardian_expired_requester':
+      return `The approval request for "${context.toolName ?? 'unknown'}" has expired without a guardian response. The request has been denied.`;
+
+    case 'guardian_expired_guardian':
+      return `The approval request from ${context.requesterIdentifier ?? 'the requester'} for "${context.toolName ?? 'unknown'}" has expired.`;
+
+    case 'guardian_verify_success':
+      return 'Guardian verification successful! You are now set as the guardian for this channel.';
+
+    case 'guardian_verify_failed':
+      return `Verification failed. ${context.failureReason ?? 'Please try again.'}`;
+
+    case 'guardian_verify_challenge_setup':
+      return `To complete guardian verification, send ${context.verifyCommand ?? 'the verification command'} within ${context.ttlSeconds ?? 60} seconds.`;
+
+    case 'guardian_verify_status_bound':
+      return 'A guardian is currently active for this channel.';
+
+    case 'guardian_verify_status_unbound':
+      return 'No guardian is currently configured for this channel.';
+
+    case 'guardian_deny_no_identity':
+      return 'This action requires approval, but your identity could not be verified. The request has been denied for safety.';
+
+    case 'guardian_deny_no_binding':
+      return 'This action requires guardian approval, but no guardian has been configured for this channel. The request has been denied for safety.';
+
+    default: {
+      // Exhaustive check — TypeScript will flag if a scenario is missing.
+      const _exhaustive: never = context.scenario;
+      return `Approval required. ${String(_exhaustive)}`;
+    }
+  }
+}

package/src/runtime/channel-approvals.ts

@@ -21,6 +21,7 @@ import type {
   ApprovalUIMetadata,
   ApprovalDecisionResult,
 } from './channel-approval-types.js';
+import { composeApprovalMessage } from './approval-message-composer.js';
 
 // ---------------------------------------------------------------------------
 // 1. Detect pending confirmations and build prompt
@@ -47,13 +48,17 @@ export function getChannelApprovalPrompt(
  * Internal helper: turn a PendingRunInfo into a ChannelApprovalPrompt.
  */
 function buildPromptFromRunInfo(info: PendingRunInfo): ChannelApprovalPrompt {
-  const promptText = `The assistant wants to use the tool "${info.toolName}". Do you want to allow this?`;
+  const promptText = composeApprovalMessage({
+    scenario: 'standard_prompt',
+    toolName: info.toolName,
+  });
 
   // Hide "approve always" when persistent trust rules are disallowed for this invocation.
   const actions = info.persistentDecisionsAllowed === false
     ? DEFAULT_APPROVAL_ACTIONS.filter((a) => a.id !== 'approve_always')
     : [...DEFAULT_APPROVAL_ACTIONS];
 
+  // Plain-text fallback must remain parser-compatible (contains "yes"/"always"/"no" keywords).
   const plainTextFallback = info.persistentDecisionsAllowed === false
     ? `${promptText}\n\nReply "yes" to approve or "no" to reject.`
     : `${promptText}\n\nReply "yes" to approve once, "always" to approve always, or "no" to reject.`;
@@ -166,8 +171,11 @@ export function buildGuardianApprovalPrompt(
   info: PendingRunInfo,
   requesterIdentifier: string,
 ): ChannelApprovalPrompt {
-  const promptText =
-    `User ${requesterIdentifier} is requesting to run "${info.toolName}". Approve or deny?`;
+  const promptText = composeApprovalMessage({
+    scenario: 'guardian_prompt',
+    toolName: info.toolName,
+    requesterIdentifier,
+  });
 
   // Guardian approvals are always one-time decisions — "approve always"
   // doesn't make sense when the guardian is approving on behalf of someone else.
@@ -211,7 +219,7 @@ export function channelSupportsRichApprovalUI(channel: string): boolean {
 export function buildReminderPrompt(
   pendingPrompt: ChannelApprovalPrompt,
 ): ChannelApprovalPrompt {
-  const reminderPrefix = "I'm still waiting for your decision on the previous request.";
+  const reminderPrefix = composeApprovalMessage({ scenario: 'reminder_prompt' });
   return {
     promptText: `${reminderPrefix}\n\n${pendingPrompt.promptText}`,
     actions: pendingPrompt.actions,