@vellumai/assistant 0.4.57 → 0.5.0

package/src/notifications/decision-engine.ts

@@ -852,17 +852,58 @@ async function classifyWithLLM(
  *
  * - `all_channels`: force selected channels to all connected channels.
  * - `multi_channel`: ensure at least 2 channels when 2+ are connected.
- * - `single_channel`: no override (default behavior).
+ * - `single_channel`: cap to a single channel. When explicitly set, reduces
+ *   selected channels to one — preferring the source channel if present.
  */
 export function enforceRoutingIntent(
   decision: NotificationDecision,
   routingIntent: RoutingIntent | undefined,
   connectedChannels: NotificationChannel[],
+  sourceChannel?: string,
 ): NotificationDecision {
-  if (!routingIntent || routingIntent === "single_channel") {
+  if (!routingIntent) {
     return decision;
   }
 
+  if (routingIntent === "single_channel") {
+    if (!decision.shouldNotify) {
+      return decision;
+    }
+
+    // Force delivery to the source channel only. If the source channel
+    // is among the connected channels, use it regardless of what the LLM
+    // picked (even if the LLM picked exactly one wrong channel).
+    // Otherwise fall back to capping at the first selected channel.
+    const sourceIsConnected =
+      sourceChannel &&
+      connectedChannels.includes(sourceChannel as NotificationChannel);
+    const preferred = sourceIsConnected
+      ? (sourceChannel as NotificationChannel)
+      : decision.selectedChannels[0];
+
+    // No change needed if the decision already matches.
+    if (
+      decision.selectedChannels.length === 1 &&
+      decision.selectedChannels[0] === preferred
+    ) {
+      return decision;
+    }
+
+    const enforced = { ...decision };
+    enforced.selectedChannels = [preferred];
+    enforced.reasoningSummary = `${decision.reasoningSummary} [routing_intent=single_channel enforced: capped to ${preferred}]`;
+    log.info(
+      {
+        routingIntent,
+        sourceChannel,
+        originalChannels: decision.selectedChannels,
+        enforcedChannel: preferred,
+      },
+      "Routing intent enforcement: single_channel → capped to one channel",
+    );
+    return enforced;
+  }
+
   if (!decision.shouldNotify) {
     return decision;
   }

package/src/notifications/emit-signal.ts

@@ -256,6 +256,7 @@ export async function emitNotificationSignal<TEventName extends string>(
       decision,
       signal.routingIntent,
       connectedChannels,
+      signal.sourceChannel,
     );
 
     // Re-persist the decision if routing intent enforcement changed it,

package/src/prompts/templates/BOOTSTRAP.md

@@ -37,14 +37,16 @@ Onboarding has two phases. Phase 1 is about proving value. Phase 2 is about maki
 
 ### Phase 1: Prove It (Priority: HIGH)
 
-**Goal:** The user should be actively working on a meaningful task within the first few exchanges. They don't need to finish it immediately, but they should be on their way and thinking "oh, this thing is actually useful."
+**Goal:** Complete whatever task the user wants to do. Once they've gotten initial value, bridge to Phase 2. Phase 1 is done when the task is done, and the user is thinking "oh, this thing is actually useful."
 
 **Keep Phase 1 tasks small and fast.** The goal is to show value quickly, not to impress with depth. A quick file summary, a fast web lookup, a simple app or tool, a short piece of writing. Do NOT kick off long research tasks, deep multi-step pipelines, or anything that takes more than a minute or two. If the user asks for something heavyweight, acknowledge it and suggest a lighter first win instead: "That's a bigger one. Let me show you something quick first so you can see how I work, then we'll dig in." New users start with $5 of AI credits. The full onboarding should fit comfortably within that budget, so bias toward lighter tasks.
 
 After your opening message, one of these things will happen:
 
 **Path A: The user gives you a task or question.**
-Great. Do it. Do it well. This is your audition. While you work on their task, quietly observe what you can learn about them (name, interests, work context, communication style). Save what you learn to USER.md silently. After completing the task, transition naturally to Phase 2.
+Great. Do it. Do it well. This is your audition. While you work on their task, quietly observe what you can learn about them (name, interests, work context, communication style). Save what you learn to USER.md silently. Once the task is done, bridge to Phase 2 immediately — in that same response or the very next one. Do NOT wait for the user to ask for more. Do NOT treat "that's all" or "thanks" as a goodbye. Treat it as your cue to bridge.
+
+If the user's first message is vague (e.g. "I'm new here, can you help with that?"), you may ask one clarifying question to scope the task. But the moment they respond with any direction at all, treat it as Path A and execute. Do not keep probing.
 
 **Path B: The user asks "what can you do?" or seems unsure.**
 Don't dump a paragraph of capabilities. Instead, use the `ui_show` tool to show them a structured card. You MUST call the `ui_show` tool (not write prose or a list). Present the actions in the exact order shown below. Here is the input to pass to the `ui_show` tool:
@@ -74,11 +76,13 @@ Only fall back to a numbered list if `ui_show` is genuinely unavailable (voice o
 - **Vibe code an app:** Ask what kind of tool or app they want. Build it using the app builder skill. Make it look great.
 - **Photo or video:** Use the media processing or image studio skills. They can analyze a video, pull insights from a photo, or generate something new. Ask what they have and what they want to do with it.
 
+Once the task is complete, bridge to Phase 2 immediately — in that same response or the very next one. Do NOT wait for the user to ask for more. Do NOT treat "that's all" or "thanks" as a goodbye. Treat it as your cue to bridge.
+
 **Path C: The user wants to chat or explore.**
-That's fine. Roll with it. Be interesting. But steer toward action within 3-4 exchanges. You can weave in something like: "I'm enjoying this, but I'm itching to actually do something for you. Got anything I can sink my teeth into?"
+That's fine. Roll with it. Be interesting. But steer toward action within 3-4 exchanges. You can weave in something like: "I'm enjoying this, but I'm itching to actually do something for you. Got anything I can sink my teeth into?" At that point, follow Path A instructions.
 
 **Path D: The user immediately wants to set up your identity/name.**
-Great, skip to Phase 2. Some people want the personality game first. Let them lead.
+Great, skip to Phase 2. Some people want the personality game first. Let them lead. If you go down this path come back to Phase 1 after that.
 
 **Critical rule for Phase 1:** Whatever the user gives you, COMPLETE A TASK. Even a small one. Summarize something, look something up, build something quick. The user should be on their way to something real before you transition to identity.
 
@@ -196,6 +200,8 @@ Do it quietly. Don't tell the user which files you're editing or mention tool na
 
 When saving to `IDENTITY.md`, be specific about the tone, energy, and conversational style you discovered during onboarding. This file persists after onboarding, so everything about how you should come across needs to be captured there. Not just your name, but the full vibe: how you talk, how much energy you bring, whether you're blunt or gentle, funny or serious.
 
+When saving to `SOUL.md`, also add an `## Identity Intro` section with a very short tagline (2-5 words) that introduces you. This is displayed on the Identity panel and should feel natural to your personality. Examples: "It's [name].", "[name] here.", "[name], at your service." Write it as a single line under the heading (not a bullet list). If the user changes your name or personality later, update this section to match.
+
 ## Wrapping Up
 
 Once you've completed Phase 1 and made reasonable progress through Phase 2, you're done with onboarding. Use your best judgment on when the conversation has naturally moved past the bootstrap stage. There's no hard checklist. The goal is that the user feels set up and ready to work, not that every box is ticked.

package/src/prompts/templates/IDENTITY.md

@@ -2,13 +2,12 @@ _ Lines starting with _ are comments - they won't appear in the system prompt
 
 # IDENTITY.md
 
-This file is yours. Add sections, restructure it, make it reflect who you are. Name, Emoji, Role, Personality, and Home are parsed by the app - keep their `- **Label:**` format. Everything else is freeform.
+This file is yours. Add sections, restructure it, make it reflect who you are. Name, Emoji, Role, Personality are parsed by the app - keep their `- **Label:**` format. Everything else is freeform.
 
 - **Name:** _(not yet chosen)_
 - **Emoji:** _(not yet chosen)_
 - **Nature:** _(not yet established)_
 - **Personality:** _(not yet established)_
 - **Role:** _(not yet established)_
-- **Home:** Local (~/.vellum/workspace)
 
 ## Avatar

package/src/providers/anthropic/client.ts

@@ -530,7 +530,6 @@ export class AnthropicProvider implements Provider {
   private model: string;
   private useNativeWebSearch: boolean;
   private streamTimeoutMs: number;
-  private fastMode: boolean;
 
   constructor(
     apiKey: string,
@@ -542,9 +541,7 @@ export class AnthropicProvider implements Provider {
     } = {},
   ) {
     this.client = new Anthropic({ apiKey, baseURL: options.baseURL });
-    // Models ending in "-fast" use the beta fast-mode API
-    this.fastMode = model.endsWith("-fast");
-    this.model = this.fastMode ? model.slice(0, -"-fast".length) : model;
+    this.model = model;
     this.useNativeWebSearch = options.useNativeWebSearch ?? false;
     this.streamTimeoutMs = options.streamTimeoutMs ?? 300_000;
   }
@@ -799,18 +796,9 @@ export class AnthropicProvider implements Provider {
 
       let response: Anthropic.Message;
       try {
-        const stream: UnifiedStream = this.fastMode
-          ? (this.client.beta.messages.stream(
-              {
-                ...params,
-                betas: ["fast-mode-2026-02-01"],
-                speed: "fast",
-              } as Parameters<typeof this.client.beta.messages.stream>[0],
-              { signal: timeoutSignal },
-            ) as unknown as UnifiedStream)
-          : (this.client.messages.stream(params, {
-              signal: timeoutSignal,
-            }) as unknown as UnifiedStream);
+        const stream: UnifiedStream = this.client.messages.stream(params, {
+          signal: timeoutSignal,
+        }) as unknown as UnifiedStream;
 
         // Track whether we've seen a text content block so we can insert a
         // separator between consecutive text blocks in the same response.
@@ -961,7 +949,7 @@ export class AnthropicProvider implements Provider {
         content: response.content.map((block) =>
           this.fromAnthropicBlock(block),
         ),
-        model: this.fastMode ? `${response.model}-fast` : response.model,
+        model: response.model,
         usage: {
           inputTokens:
             response.usage.input_tokens +

package/src/runtime/access-request-helper.ts

@@ -200,10 +200,24 @@ export function notifyGuardianOfAccessRequest(
   });
 
   let vellumDeliveryId: string | null = null;
+  // When the access request originates from a text channel with
+  // notification delivery support (Slack, Telegram), route the guardian
+  // notification to that same channel only. Delivering on the macOS
+  // client as well is noisy and approving from there doesn't work
+  // because the desktop path lacks the channel delivery context needed
+  // to deliver the verification code. Phone is excluded because it is
+  // not a deliverable notification channel.
+  const TEXT_CHANNELS_WITH_DELIVERY: ReadonlySet<string> = new Set([
+    "slack",
+    "telegram",
+  ]);
+  const sameChannelOnly = TEXT_CHANNELS_WITH_DELIVERY.has(sourceChannel);
+
   void emitNotificationSignal({
     sourceEventName: "ingress.access_request",
     sourceChannel: sourceChannel as NotificationSourceChannel,
     sourceContextId: `access-req-${sourceChannel}-${actorExternalId}`,
+    ...(sameChannelOnly ? { routingIntent: "single_channel" as const } : {}),
     attentionHints: {
       requiresAction: true,
       urgency: "high",
@@ -258,7 +272,7 @@ export function notifyGuardianOfAccessRequest(
         applyDeliveryStatus(delivery.id, result);
       }
 
-      if (!vellumDeliveryId) {
+      if (!vellumDeliveryId && !sameChannelOnly) {
         const fallback = createCanonicalGuardianDelivery({
           requestId: canonicalRequest.id,
           destinationChannel: "vellum",

package/src/runtime/guardian-vellum-migration.ts

@@ -91,9 +91,7 @@ export function ensureVellumGuardianBinding(
  *
  * Returns true if healing occurred, false otherwise.
  */
-export function healGuardianBindingDrift(
-  incomingPrincipalId: string,
-): boolean {
+export function healGuardianBindingDrift(incomingPrincipalId: string): boolean {
   if (!incomingPrincipalId.startsWith("vellum-principal-")) {
     return false;
   }

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

@@ -12,6 +12,8 @@
  * No messages are persisted. `conversation.processing` is never set or checked.
  */
 
+import { existsSync, readFileSync } from "node:fs";
+
 import { buildToolDefinitions } from "../../daemon/conversation-tool-setup.js";
 import { getConversationByKey } from "../../memory/conversation-key-store.js";
 import { buildSystemPrompt } from "../../prompts/system-prompt.js";
@@ -21,13 +23,45 @@ import {
 } from "../../providers/provider-send-message.js";
 import { checkIngressForSecrets } from "../../security/secret-ingress.js";
 import { getLogger } from "../../util/logger.js";
+import { getWorkspacePromptPath } from "../../util/platform.js";
 import type { AuthContext } from "../auth/types.js";
 import { httpError } from "../http-errors.js";
 import type { RouteDefinition } from "../http-router.js";
 import type { SendMessageDeps } from "../http-types.js";
+import { getCachedIntro, setCachedIntro } from "./identity-intro-cache.js";
 
 const log = getLogger("btw-routes");
 
+/** Conversation key used by the client for identity intro generation. */
+const IDENTITY_INTRO_KEY = "identity-intro";
+
+/**
+ * Parse the `## Identity Intro` section from SOUL.md.
+ * Returns the first non-empty line under that heading, or null.
+ */
+function readSoulIdentityIntro(): string | null {
+  try {
+    const soulPath = getWorkspacePromptPath("SOUL.md");
+    if (!existsSync(soulPath)) return null;
+    const content = readFileSync(soulPath, "utf-8");
+
+    let inSection = false;
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (/^#+\s/.test(trimmed)) {
+        inSection = trimmed.toLowerCase().includes("identity intro");
+        continue;
+      }
+      if (inSection && trimmed.length > 0) {
+        return trimmed;
+      }
+    }
+  } catch {
+    // Fall through — no SOUL.md intro available
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Handler
 // ---------------------------------------------------------------------------
@@ -77,6 +111,43 @@ async function handleBtw(
     );
   }
 
+  // ----- Identity intro fast-path -----
+  // When the client requests the identity intro, check SOUL.md first (persisted
+  // during onboarding), then the LLM-generated cache. Only fall through to a
+  // live LLM call when neither source has a value.
+  if (conversationKey === IDENTITY_INTRO_KEY) {
+    const soulIntro = readSoulIdentityIntro();
+    const fastText = soulIntro ?? getCachedIntro()?.text;
+    if (fastText) {
+      log.debug(
+        soulIntro
+          ? "Returning SOUL.md identity intro"
+          : "Returning cached identity intro",
+      );
+      const encoder = new TextEncoder();
+      const stream = new ReadableStream({
+        start(controller) {
+          controller.enqueue(
+            encoder.encode(
+              `event: btw_text_delta\ndata: ${JSON.stringify({ text: fastText })}\n\n`,
+            ),
+          );
+          controller.enqueue(
+            encoder.encode(`event: btw_complete\ndata: {}\n\n`),
+          );
+          controller.close();
+        },
+      });
+      return new Response(stream, {
+        headers: {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          Connection: "keep-alive",
+        },
+      });
+    }
+  }
+
   // Look up an existing conversation — never create one.  BTW is ephemeral
   // (the file header promises "No messages are persisted"), so we must not
   // call getOrCreateConversation which would insert a DB row.  When no
@@ -116,7 +187,9 @@ async function handleBtw(
             ? conversation.systemPrompt
             : buildSystemPrompt({ excludeBootstrap: true });
 
+          const isIntroRequest = conversationKey === IDENTITY_INTRO_KEY;
           let textDeltaCount = 0;
+          let collectedText = "";
           await conversation.provider.sendMessage(
             messages,
             tools,
@@ -130,6 +203,7 @@ async function handleBtw(
               onEvent: (event) => {
                 if (event.type === "text_delta") {
                   textDeltaCount++;
+                  if (isIntroRequest) collectedText += event.text;
                   controller.enqueue(
                     encoder.encode(
                       `event: btw_text_delta\ndata: ${JSON.stringify({ text: event.text })}\n\n`,
@@ -148,6 +222,16 @@ async function handleBtw(
             );
           }
 
+          // Cache the generated identity intro for subsequent requests.
+          if (isIntroRequest && collectedText.trim()) {
+            try {
+              setCachedIntro(collectedText.trim());
+              log.debug("Cached identity intro text");
+            } catch {
+              // Non-fatal — next request will regenerate.
+            }
+          }
+
           controller.enqueue(
             encoder.encode(`event: btw_complete\ndata: {}\n\n`),
           );

package/src/runtime/routes/identity-intro-cache.ts

@@ -0,0 +1,105 @@
+/**
+ * Caching layer for the LLM-generated identity intro text.
+ *
+ * The intro (a short identity tagline) is generated via the
+ * /v1/btw endpoint and displayed on the Identity panel. To avoid redundant LLM
+ * calls, we cache the result for 4 hours with content-hash-based invalidation:
+ * when USER.md, IDENTITY.md, or SOUL.md change, the cache is busted.
+ *
+ * Storage uses the existing `memory_checkpoints` table (simple key-value store).
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+
+import {
+  getMemoryCheckpoint,
+  setMemoryCheckpoint,
+} from "../../memory/checkpoints.js";
+import { getWorkspacePromptPath } from "../../util/platform.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const CACHE_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours
+
+const CHECKPOINT_KEY_TEXT = "identity:intro:text";
+const CHECKPOINT_KEY_HASH = "identity:intro:content_hash";
+const CHECKPOINT_KEY_TIMESTAMP = "identity:intro:cached_at";
+
+/** Workspace files whose content influences the identity intro. */
+const IDENTITY_FILES = ["USER.md", "IDENTITY.md", "SOUL.md"] as const;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Read a workspace prompt file, returning empty string if missing. */
+function readWorkspaceFile(name: string): string {
+  try {
+    const path = getWorkspacePromptPath(name);
+    if (!existsSync(path)) return "";
+    return readFileSync(path, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+/** Compute a SHA-256 hex hash of the concatenated identity file contents. */
+export function computeIdentityContentHash(): string {
+  const combined = IDENTITY_FILES.map(readWorkspaceFile).join("\n---\n");
+  return createHash("sha256").update(combined).digest("hex");
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface CachedIntro {
+  text: string;
+}
+
+/**
+ * Retrieve the cached identity intro if it exists, is within the TTL window,
+ * and the identity files have not changed since it was generated.
+ *
+ * Returns `null` when the cache is missing, expired, or invalidated.
+ */
+export function getCachedIntro(): CachedIntro | null {
+  try {
+    const text = getMemoryCheckpoint(CHECKPOINT_KEY_TEXT);
+    const hash = getMemoryCheckpoint(CHECKPOINT_KEY_HASH);
+    const timestampStr = getMemoryCheckpoint(CHECKPOINT_KEY_TIMESTAMP);
+
+    if (!text || !hash || !timestampStr) return null;
+
+    // TTL check
+    const cachedAt = Number(timestampStr);
+    if (isNaN(cachedAt) || Date.now() - cachedAt > CACHE_TTL_MS) return null;
+
+    // Content-hash check — bust cache when identity files change
+    const currentHash = computeIdentityContentHash();
+    if (currentHash !== hash) return null;
+
+    return { text };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Store the generated identity intro text in the cache along with
+ * the current content hash and timestamp.
+ */
+export function setCachedIntro(text: string): void {
+  try {
+    const hash = computeIdentityContentHash();
+    const now = String(Date.now());
+    setMemoryCheckpoint(CHECKPOINT_KEY_TEXT, text);
+    setMemoryCheckpoint(CHECKPOINT_KEY_HASH, hash);
+    setMemoryCheckpoint(CHECKPOINT_KEY_TIMESTAMP, now);
+  } catch {
+    // Cache write failure is non-fatal — next request will regenerate.
+  }
+}

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

@@ -11,6 +11,7 @@ import { getBaseDataDir } from "../../config/env-registry.js";
 import { getWorkspacePromptPath, readLockfile } from "../../util/platform.js";
 import { httpError } from "../http-errors.js";
 import type { RouteDefinition } from "../http-router.js";
+import { getCachedIntro } from "./identity-intro-cache.js";
 
 interface DiskSpaceInfo {
   path: string;
@@ -233,6 +234,51 @@ export function handleGetIdentity(): Response {
   });
 }
 
+// ---------------------------------------------------------------------------
+// Identity intro cache
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the `## Identity Intro` section from SOUL.md.
+ * Returns the first non-empty line under that heading, or null.
+ */
+function readSoulIdentityIntro(): string | null {
+  try {
+    const soulPath = getWorkspacePromptPath("SOUL.md");
+    if (!existsSync(soulPath)) return null;
+    const content = readFileSync(soulPath, "utf-8");
+
+    let inSection = false;
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (/^#+\s/.test(trimmed)) {
+        inSection = trimmed.toLowerCase().includes("identity intro");
+        continue;
+      }
+      if (inSection && trimmed.length > 0) {
+        return trimmed;
+      }
+    }
+  } catch {
+    // Fall through to cache/fallback
+  }
+  return null;
+}
+
+export function handleGetIdentityIntro(): Response {
+  // Prefer SOUL.md persisted intro over LLM-generated cache
+  const soulIntro = readSoulIdentityIntro();
+  if (soulIntro) {
+    return Response.json({ text: soulIntro });
+  }
+
+  const cached = getCachedIntro();
+  if (!cached) {
+    return httpError("NOT_FOUND", "No cached identity intro available", 404);
+  }
+  return Response.json({ text: cached.text });
+}
+
 // ---------------------------------------------------------------------------
 // Route definitions
 // ---------------------------------------------------------------------------
@@ -249,5 +295,10 @@ export function identityRouteDefinitions(): RouteDefinition[] {
       method: "GET",
       handler: () => handleGetIdentity(),
     },
+    {
+      endpoint: "identity/intro",
+      method: "GET",
+      handler: () => handleGetIdentityIntro(),
+    },
   ];
 }

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

@@ -522,7 +522,7 @@ async function handleToolPermissionSimulate(body: {
     }
 
     return Response.json({
-      ok: true,
+      success: true,
       decision: result.decision,
       riskLevel,
       reason: result.reason,

package/src/security/encrypted-store.ts

@@ -104,8 +104,7 @@ export function _setStoreKeyPath(path: string | null): void {
 
 function getStoreKeyPath(): string {
   return (
-    storeKeyPathOverride ??
-    join(dirname(getStorePath()), STORE_KEY_FILENAME)
+    storeKeyPathOverride ?? join(dirname(getStorePath()), STORE_KEY_FILENAME)
   );
 }
 

package/src/skills/skill-memory.ts

@@ -17,8 +17,7 @@ const log = getLogger("skill-memory");
  * Truncated to 500 chars max (matching the limit used by memory item extraction).
  */
 export function buildCapabilityStatement(entry: CatalogSkill): string {
-  const displayName =
-    entry.metadata?.vellum?.["display-name"] ?? entry.name;
+  const displayName = entry.metadata?.vellum?.["display-name"] ?? entry.name;
   const activationHints = entry.metadata?.vellum?.["activation-hints"];
 
   let statement = `The "${displayName}" skill (${entry.id}) is available. ${entry.description}.`;
@@ -71,7 +70,10 @@ export function upsertSkillCapabilityMemory(
       .get();
 
     if (existing) {
-      if (existing.status === "active" && existing.fingerprint === fingerprint) {
+      if (
+        existing.status === "active" &&
+        existing.fingerprint === fingerprint
+      ) {
         // Same content — just touch lastSeenAt
         db.update(memoryItems)
           .set({ lastSeenAt: now })

package/src/telemetry/usage-telemetry-reporter.test.ts

@@ -89,6 +89,10 @@ mock.module("../util/logger.js", () => ({
     }),
 }));
 
+mock.module("../version.js", () => ({
+  APP_VERSION: "1.2.3-test",
+}));
+
 // ---------------------------------------------------------------------------
 // Production import (after mocks)
 // ---------------------------------------------------------------------------
@@ -370,8 +374,9 @@ describe("UsageTelemetryReporter", () => {
       (mockFetch.mock.calls[0] as [string, RequestInit])[1].body as string,
     );
 
-    // Top-level: installation_id and events array (no turn_events key)
+    // Top-level: installation_id, app_version, and events array (no turn_events key)
     expect(body.installation_id).toBe("test-device-id");
+    expect(body.app_version).toBe("1.2.3-test");
     expect(Array.isArray(body.events)).toBe(true);
     expect(body.events.length).toBe(1);
     expect(body.turn_events).toBeUndefined();

package/src/telemetry/usage-telemetry-reporter.ts

@@ -26,6 +26,7 @@ import { resolveManagedProxyContext } from "../providers/managed-proxy/context.j
 import { getExternalAssistantId } from "../runtime/auth/external-assistant-id.js";
 import { getDeviceId } from "../util/device-id.js";
 import { getLogger } from "../util/logger.js";
+import { APP_VERSION } from "../version.js";
 import type { TelemetryEvent } from "./types.js";
 
 const log = getLogger("usage-telemetry");
@@ -192,6 +193,7 @@ export class UsageTelemetryReporter {
       const payload = {
         installation_id: getDeviceId(),
         assistant_id: assistantId,
+        app_version: APP_VERSION,
         ...(organizationId ? { organization_id: organizationId } : {}),
         ...(userId ? { user_id: userId } : {}),
         events: typedEvents,

package/src/tools/filesystem/read.ts

@@ -61,7 +61,10 @@ class FileReadTool implements Tool {
     if (IMAGE_EXTENSIONS.has(ext)) {
       const pathCheck = sandboxPolicy(rawPath, context.workingDir);
       if (!pathCheck.ok) {
-        return { content: `Error: ${pathCheck.error}`, isError: true };
+        return {
+          content: `Error: ${pathCheck.error}. To read files outside the workspace, use the host_file_read tool instead.`,
+          isError: true,
+        };
       }
       return readImageFile(pathCheck.resolved);
     }
@@ -89,8 +92,16 @@ class FileReadTool implements Tool {
             content: `Error reading file "${rawPath}": ${error.message}`,
             isError: true,
           };
-        default:
-          return { content: `Error: ${error.message}`, isError: true };
+        default: {
+          const hint =
+            error.code === "PATH_OUT_OF_BOUNDS"
+              ? ". To read files outside the workspace, use the host_file_read tool instead."
+              : "";
+          return {
+            content: `Error: ${error.message}${hint}`,
+            isError: true,
+          };
+        }
       }
     }