@vellumai/assistant 0.3.4 → 0.3.5

package/src/runtime/routes/channel-routes.ts

@@ -44,6 +44,8 @@ import type {
   MessageProcessor,
   RuntimeAttachmentMetadata,
 } from '../http-types.js';
+import type { GuardianRuntimeContext } from '../../daemon/session-runtime-assembly.js';
+import { composeApprovalMessage } from '../approval-message-composer.js';
 
 const log = getLogger('runtime-http');
 
@@ -110,6 +112,19 @@ export interface GuardianContext {
   denialReason?: DenialReason;
 }
 
+function toGuardianRuntimeContext(sourceChannel: string, ctx: GuardianContext): GuardianRuntimeContext {
+  return {
+    sourceChannel,
+    actorRole: ctx.actorRole,
+    guardianChatId: ctx.guardianChatId,
+    guardianExternalUserId: ctx.guardianExternalUserId,
+    requesterIdentifier: ctx.requesterIdentifier,
+    requesterExternalUserId: ctx.requesterExternalUserId,
+    requesterChatId: ctx.requesterChatId,
+    denialReason: ctx.denialReason,
+  };
+}
+
 /** Guardian approval request expiry (30 minutes). */
 const GUARDIAN_APPROVAL_TTL_MS = 30 * 60 * 1000;
 
@@ -138,10 +153,10 @@ function buildGuardianDenyContext(
   sourceChannel: string,
 ): string {
   if (denialReason === 'no_identity') {
-    return `Permission denied: the action "${toolName}" requires guardian approval, but your identity could not be verified on ${sourceChannel}. Do not retry yet. Explain this clearly, ask the user to message from a verifiable direct account/chat, and then retry after identity is available.`;
+    return `Permission denied: ${composeApprovalMessage({ scenario: 'guardian_deny_no_identity', toolName, channel: sourceChannel })} Do not retry yet. Ask the user to message from a verifiable direct account/chat, and then retry after identity is available.`;
   }
 
-  return `Permission denied: the action "${toolName}" requires guardian approval, but no guardian is configured for this ${sourceChannel} channel. Do not retry yet. Explain that a guardian must be set up first. The guardian/admin should open the Channels section in Settings and click "Verify Guardian", or ask the assistant to set up guardian verification. The setup flow will provide a verification token to send as /guardian_verify <token> in the ${sourceChannel} chat.`;
+  return `Permission denied: ${composeApprovalMessage({ scenario: 'guardian_deny_no_binding', toolName, channel: sourceChannel })} Do not retry yet. Offer to set up guardian verification. The setup flow will provide a verification token to send as /guardian_verify <token>.`;
 }
 
 // ---------------------------------------------------------------------------
@@ -396,11 +411,13 @@ export async function handleChannelInbound(
         token,
         body.senderExternalUserId,
         externalChatId,
+        body.senderUsername,
+        body.senderName,
       );
 
       const replyText = verifyResult.success
-        ? 'Guardian verified successfully. Your identity is now linked to this bot.'
-        : 'Verification failed. Please try again later.';
+        ? composeApprovalMessage({ scenario: 'guardian_verify_success' })
+        : verifyResult.reason;
 
       try {
         await deliverChannelReply(replyCallbackUrl, {
@@ -427,15 +444,25 @@ export async function handleChannelInbound(
   // side-effect controls and their approvals route to the guardian's chat.
   //
   // Guardian actor-role resolution always runs.
-  let guardianCtx: GuardianContext = { actorRole: 'guardian' };
+  let guardianCtx: GuardianContext;
   if (body.senderExternalUserId) {
+    const requesterLabel = body.senderUsername
+      ? `@${body.senderUsername}`
+      : body.senderExternalUserId;
     const senderIsGuardian = isGuardian(assistantId, sourceChannel, body.senderExternalUserId);
-    if (!senderIsGuardian) {
+    if (senderIsGuardian) {
+      const binding = getGuardianBinding(assistantId, sourceChannel);
+      guardianCtx = {
+        actorRole: 'guardian',
+        guardianChatId: binding?.guardianDeliveryChatId ?? externalChatId,
+        guardianExternalUserId: binding?.guardianExternalUserId ?? body.senderExternalUserId,
+        requesterIdentifier: requesterLabel,
+        requesterExternalUserId: body.senderExternalUserId,
+        requesterChatId: externalChatId,
+      };
+    } else {
       const binding = getGuardianBinding(assistantId, sourceChannel);
       if (binding) {
-        const requesterLabel = body.senderUsername
-          ? `@${body.senderUsername}`
-          : body.senderExternalUserId;
         guardianCtx = {
           actorRole: 'non-guardian',
           guardianChatId: binding.guardianDeliveryChatId,
@@ -450,6 +477,7 @@ export async function handleChannelInbound(
         guardianCtx = {
           actorRole: 'unverified_channel',
           denialReason: 'no_binding',
+          requesterIdentifier: requesterLabel,
           requesterExternalUserId: body.senderExternalUserId,
           requesterChatId: externalChatId,
         };
@@ -462,6 +490,7 @@ export async function handleChannelInbound(
     guardianCtx = {
       actorRole: 'unverified_channel',
       denialReason: 'no_identity',
+      requesterIdentifier: body.senderUsername ? `@${body.senderUsername}` : undefined,
       requesterExternalUserId: undefined,
       requesterChatId: externalChatId,
     };
@@ -524,6 +553,7 @@ export async function handleChannelInbound(
       senderName: body.senderName,
       senderExternalUserId: body.senderExternalUserId,
       senderUsername: body.senderUsername,
+      guardianCtx,
       replyCallbackUrl,
       assistantId,
     });
@@ -562,6 +592,8 @@ export async function handleChannelInbound(
         bearerToken,
         guardianCtx,
         assistantId,
+        metadataHints,
+        metadataUxBrief,
       });
     } else {
       // Fire-and-forget: process the message and deliver the reply in the background.
@@ -574,6 +606,7 @@ export async function handleChannelInbound(
         attachmentIds: hasAttachments ? attachmentIds : undefined,
         sourceChannel,
         externalChatId,
+        guardianCtx,
         metadataHints,
         metadataUxBrief,
         replyCallbackUrl,
@@ -598,6 +631,7 @@ interface BackgroundProcessingParams {
   attachmentIds?: string[];
   sourceChannel: string;
   externalChatId: string;
+  guardianCtx: GuardianContext;
   metadataHints: string[];
   metadataUxBrief?: string;
   replyCallbackUrl?: string;
@@ -614,6 +648,7 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
     attachmentIds,
     sourceChannel,
     externalChatId,
+    guardianCtx,
     metadataHints,
     metadataUxBrief,
     replyCallbackUrl,
@@ -633,6 +668,8 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
             hints: metadataHints.length > 0 ? metadataHints : undefined,
             uxBrief: metadataUxBrief,
           },
+          assistantId,
+          guardianContext: toGuardianRuntimeContext(sourceChannel, guardianCtx),
         },
         sourceChannel,
       );
@@ -695,6 +732,8 @@ interface ApprovalProcessingParams {
   bearerToken?: string;
   guardianCtx: GuardianContext;
   assistantId: string;
+  metadataHints: string[];
+  metadataUxBrief?: string;
 }
 
 /**
@@ -722,6 +761,8 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
     bearerToken,
     guardianCtx,
     assistantId,
+    metadataHints,
+    metadataUxBrief,
   } = params;
 
   const isNonGuardian = guardianCtx.actorRole === 'non-guardian';
@@ -736,6 +777,10 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
         {
           ...((isNonGuardian || isUnverifiedChannel) ? { forceStrictSideEffects: true } : {}),
           sourceChannel,
+          hints: metadataHints.length > 0 ? metadataHints : undefined,
+          uxBrief: metadataUxBrief,
+          assistantId,
+          guardianContext: toGuardianRuntimeContext(sourceChannel, guardianCtx),
         },
       );
 
@@ -826,7 +871,7 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
               try {
                 await deliverChannelReply(replyCallbackUrl, {
                   chatId: guardianCtx.requesterChatId ?? externalChatId,
-                  text: `Your request to run "${pending[0].toolName}" could not be sent to the guardian for approval. The action has been denied.`,
+                  text: composeApprovalMessage({ scenario: 'guardian_delivery_failed', toolName: pending[0].toolName }),
                   assistantId,
                 }, bearerToken);
               } catch (notifyErr) {
@@ -839,7 +884,7 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
               try {
                 await deliverChannelReply(replyCallbackUrl, {
                   chatId: guardianCtx.requesterChatId ?? externalChatId,
-                  text: `Your request to run "${pending[0].toolName}" has been sent to the guardian for approval.`,
+                  text: composeApprovalMessage({ scenario: 'guardian_request_forwarded', toolName: pending[0].toolName }),
                   assistantId,
                 }, bearerToken);
               } catch (err) {
@@ -1066,7 +1111,7 @@ async function handleApprovalInterception(
         try {
           await deliverChannelReply(replyCallbackUrl, {
             chatId: externalChatId,
-            text: `You have ${allPending.length} pending approval requests. Please use the approval buttons to respond to a specific request.`,
+            text: composeApprovalMessage({ scenario: 'guardian_disambiguation', pendingCount: allPending.length }),
             assistantId,
           }, bearerToken);
         } catch (err) {
@@ -1099,7 +1144,7 @@ async function handleApprovalInterception(
         try {
           await deliverChannelReply(replyCallbackUrl, {
             chatId: externalChatId,
-            text: 'Only the verified guardian can approve or deny this request.',
+            text: composeApprovalMessage({ scenario: 'guardian_identity_mismatch' }),
             assistantId,
           }, bearerToken);
         } catch (err) {
@@ -1133,10 +1178,11 @@ async function handleApprovalInterception(
 
         if (result.applied) {
           // Notify the requester's chat about the outcome with the tool name
-          const toolLabel = guardianApproval.toolName;
-          const outcomeText = decision.action === 'reject'
-            ? `Your request to run "${toolLabel}" was denied by the guardian.`
-            : `Your request to run "${toolLabel}" was approved by the guardian.`;
+          const outcomeText = composeApprovalMessage({
+            scenario: 'guardian_decision_outcome',
+            decision: decision.action === 'reject' ? 'denied' : 'approved',
+            toolName: guardianApproval.toolName,
+          });
           try {
             await deliverChannelReply(replyCallbackUrl, {
               chatId: guardianApproval.requesterChatId,
@@ -1242,7 +1288,7 @@ async function handleApprovalInterception(
         try {
           await deliverChannelReply(replyCallbackUrl, {
             chatId: externalChatId,
-            text: 'Your request is pending guardian approval. Only the verified guardian can approve or deny this request.',
+            text: composeApprovalMessage({ scenario: 'request_pending_guardian' }),
             assistantId,
           }, bearerToken);
         } catch (err) {
@@ -1269,7 +1315,7 @@ async function handleApprovalInterception(
         try {
           await deliverChannelReply(replyCallbackUrl, {
             chatId: externalChatId,
-            text: 'Your guardian approval request has expired and the action has been denied. Please try again.',
+            text: composeApprovalMessage({ scenario: 'guardian_expired_requester', toolName: pending[0].toolName }),
             assistantId,
           }, bearerToken);
         } catch (err) {
@@ -1538,7 +1584,7 @@ export function sweepExpiredGuardianApprovals(
     // Notify the requester that the approval expired
     deliverChannelReply(deliverUrl, {
       chatId: approval.requesterChatId,
-      text: `Your guardian approval request for "${approval.toolName}" has expired and the action has been denied. Please try again.`,
+      text: composeApprovalMessage({ scenario: 'guardian_expired_requester', toolName: approval.toolName }),
       assistantId: approval.assistantId,
     }, bearerToken).catch((err) => {
       log.error({ err, runId: approval.runId }, 'Failed to notify requester of guardian approval expiry');
@@ -1547,7 +1593,7 @@ export function sweepExpiredGuardianApprovals(
     // Notify the guardian that the approval expired
     deliverChannelReply(deliverUrl, {
       chatId: approval.guardianChatId,
-      text: `The approval request for "${approval.toolName}" from user ${approval.requesterExternalUserId} has expired and was automatically denied.`,
+      text: composeApprovalMessage({ scenario: 'guardian_expired_guardian', toolName: approval.toolName, requesterIdentifier: approval.requesterExternalUserId }),
       assistantId: approval.assistantId,
     }, bearerToken).catch((err) => {
       log.error({ err, runId: approval.runId }, 'Failed to notify guardian of approval expiry');

package/src/runtime/run-orchestrator.ts

@@ -18,6 +18,7 @@ import type { Run } from '../memory/runs-store.js';
 import type { Session } from '../daemon/session.js';
 import type { ServerMessage } from '../daemon/ipc-protocol.js';
 import { resolveChannelCapabilities } from '../daemon/session-runtime-assembly.js';
+import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.js';
 import type { UserDecision } from '../permissions/types.js';
 import { checkIngressForSecrets } from '../security/secret-ingress.js';
 import { IngressBlockedError } from '../util/errors.js';
@@ -37,7 +38,11 @@ interface PendingRunState {
 }
 
 export interface RunOrchestratorDeps {
-  getOrCreateSession: (conversationId: string) => Promise<Session>;
+  getOrCreateSession: (conversationId: string, transport?: {
+    channelId: string;
+    hints?: string[];
+    uxBrief?: string;
+  }) => Promise<Session>;
   resolveAttachments: (attachmentIds: string[]) => Array<{
     id: string;
     filename: string;
@@ -67,6 +72,20 @@ export interface RunStartOptions {
    * default 'http-api'.
    */
   sourceChannel?: string;
+  /**
+   * Transport hints from sourceMetadata (e.g. reply-context cues).
+   * Forwarded to the session so the agent loop can incorporate them.
+   */
+  hints?: string[];
+  /**
+   * Brief UX context from sourceMetadata (e.g. UI surface description).
+   * Forwarded to the session so the agent loop can tailor its response.
+   */
+  uxBrief?: string;
+  /** Assistant scope for multi-assistant channels. */
+  assistantId?: string;
+  /** Guardian trust/identity context for the inbound actor. */
+  guardianContext?: GuardianRuntimeContext;
 }
 
 // ---------------------------------------------------------------------------
@@ -104,7 +123,17 @@ export class RunOrchestrator {
       throw new IngressBlockedError(ingressCheck.userNotice!, ingressCheck.detectedTypes);
     }
 
-    const session = await this.deps.getOrCreateSession(conversationId);
+    // Build transport metadata when channel context is available so the
+    // session receives the same hints/uxBrief as the non-orchestrator path.
+    const transport = options?.sourceChannel
+      ? {
+          channelId: options.sourceChannel,
+          hints: options.hints,
+          uxBrief: options.uxBrief,
+        }
+      : undefined;
+
+    const session = await this.deps.getOrCreateSession(conversationId, transport);
 
     if (session.isProcessing()) {
       throw new Error('Session is already processing a message');
@@ -121,6 +150,8 @@ export class RunOrchestrator {
       ...session.memoryPolicy,
       strictSideEffects,
     };
+    session.setAssistantId(options?.assistantId ?? 'self');
+    session.setGuardianContext(options?.guardianContext ?? null);
 
     const attachments = attachmentIds
       ? this.deps.resolveAttachments(attachmentIds)
@@ -201,6 +232,8 @@ export class RunOrchestrator {
       // Reset channel capabilities so a subsequent IPC/desktop session on the
       // same conversation is not incorrectly treated as an HTTP-API client.
       session.setChannelCapabilities(null);
+      session.setGuardianContext(null);
+      session.setAssistantId('self');
       // Reset the session's client callback to a no-op so the stale
       // closure doesn't intercept events from future runs on the same session.
       // Set hasNoClient=true here since the run is done and no HTTP caller

package/src/tools/assets/materialize.ts

@@ -41,8 +41,8 @@ function formatBytes(bytes: number): string {
 /**
  * Load an attachment row (including base64 data) by its primary key.
  *
- * Not scoped by assistantId because ToolContext doesn't carry it.
- * Cross-thread isolation is enforced by the visibility check in execute().
+ * Not scoped by assistantId because attachment access is enforced by
+ * conversation visibility checks in execute().
  */
 function loadAttachmentById(
   attachmentId: string,

package/src/tools/calls/call-start.ts

@@ -54,6 +54,7 @@ class CallStartTool implements Tool {
       task: input.task as string,
       context: input.context as string | undefined,
       conversationId: context.conversationId,
+      assistantId: context.assistantId,
       callerIdentityMode: input.caller_identity_mode as 'assistant_number' | 'user_number' | undefined,
     });
 

package/src/tools/credentials/vault.ts

@@ -630,7 +630,7 @@ class CredentialStoreTool implements Tool {
                 const dmChannel = await conversationsOpen(botToken, installingUserId);
                 const welcomeMsg =
                   `You have installed ${identity.user}, an AI Assistant, on ${identity.team}. ` +
-                  `Manage the assistant experience for this workspace in the workspace settings page.`;
+                  `You can manage the assistant experience for this workspace by chatting with the assistant or from the Settings page.`;
                 await postMessage(botToken, dmChannel.channel.id, welcomeMsg);
               }
             } catch (err) {

package/src/tools/execution-target.ts

@@ -1,7 +1,12 @@
 import type { ExecutionTarget } from './types.js';
 import { getTool } from './registry.js';
 
-export function resolveExecutionTarget(toolName: string): ExecutionTarget {
+export interface ManifestOverride {
+  risk: 'low' | 'medium' | 'high';
+  execution_target: 'host' | 'sandbox';
+}
+
+export function resolveExecutionTarget(toolName: string, manifestOverride?: ManifestOverride): ExecutionTarget {
   const tool = getTool(toolName);
   // Manifest-declared execution target is authoritative — check it first so
   // skill tools with host_/computer_use_ prefixes aren't mis-classified.
@@ -13,6 +18,11 @@ export function resolveExecutionTarget(toolName: string): ExecutionTarget {
   if (tool?.executionMode === 'proxy') {
     return 'host';
   }
+  // Use manifest metadata for unregistered skill tools so the Permission
+  // Simulator shows accurate execution targets instead of defaulting to sandbox.
+  if (!tool && manifestOverride) {
+    return manifestOverride.execution_target;
+  }
   // Prefix heuristics for core tools that don't declare an explicit target.
   if (toolName.startsWith('host_') || toolName.startsWith('computer_use_')) {
     return 'host';

package/src/tools/network/web-search.ts

@@ -268,7 +268,7 @@ class WebSearchTool implements Tool {
         apiKey = fallbackKey;
       } else {
         return {
-          content: 'Error: No web search API key configured. Set PERPLEXITY_API_KEY or BRAVE_API_KEY environment variable, or configure a key in settings.',
+          content: 'Error: No web search API key configured. Set a PERPLEXITY_API_KEY or BRAVE_API_KEY environment variable, or configure it from the Settings page under API Keys.',
           isError: true,
         };
       }

package/src/tools/types.ts

@@ -87,6 +87,8 @@ export interface ToolContext {
   workingDir: string;
   sessionId: string;
   conversationId: string;
+  /** Logical assistant scope for multi-assistant routing. */
+  assistantId?: string;
   /** When set, the tool execution is part of a task run. Used to retrieve ephemeral permission rules. */
   taskRunId?: string;
   /** Per-message request ID for log correlation across session/connection boundaries. */

package/src/twitter/router.ts

@@ -41,7 +41,7 @@ export async function routedPostTweet(
   if (strategy === 'oauth') {
     // User explicitly wants OAuth
     if (!oauthIsAvailable()) {
-      throw Object.assign(new Error('OAuth is not configured. Set up OAuth credentials in Settings, or switch to browser strategy: `vellum x strategy set browser`.'), {
+      throw Object.assign(new Error('OAuth is not configured. Provide your X developer credentials here in the chat to set up OAuth, or switch to browser strategy: `vellum x strategy set browser`.'), {
         pathUsed: 'oauth' as const,
         suggestAlternative: 'browser' as const,
       });

package/src/util/platform.ts

@@ -45,6 +45,41 @@ export function getClipboardCommand(): string | null {
   return null;
 }
 
+/**
+ * Read and parse the lockfile, trying the primary path (~/.vellum.lock.json)
+ * first, then falling back to the legacy path (~/.vellum.lockfile.json).
+ * Respects BASE_DATA_DIR for non-standard home directories.
+ * Returns null if neither file exists or both are malformed.
+ */
+export function readLockfile(): Record<string, unknown> | null {
+  const base = process.env.BASE_DATA_DIR?.trim() || homedir();
+  const candidates = [
+    join(base, '.vellum.lock.json'),
+    join(base, '.vellum.lockfile.json'),
+  ];
+  for (const lockPath of candidates) {
+    if (!existsSync(lockPath)) continue;
+    try {
+      const raw = JSON.parse(readFileSync(lockPath, 'utf-8'));
+      if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        return raw as Record<string, unknown>;
+      }
+    } catch {
+      // malformed JSON — try next
+    }
+  }
+  return null;
+}
+
+/**
+ * Write data to the primary lockfile (~/.vellum.lock.json).
+ * Respects BASE_DATA_DIR for non-standard home directories.
+ */
+export function writeLockfile(data: Record<string, unknown>): void {
+  const base = process.env.BASE_DATA_DIR?.trim() || homedir();
+  writeFileSync(join(base, '.vellum.lock.json'), JSON.stringify(data, null, 2) + '\n');
+}
+
 /**
  * Returns the root ~/.vellum directory. User-facing files (config, prompt
  * files, skills) and runtime files (socket, PID) live here.