@vellumai/assistant 0.11.1 → 0.11.2-staging.2

package/src/plugins/defaults/memory/substrate/skill-store.ts

@@ -24,6 +24,12 @@
 // case only the dense Qdrant write is deferred so the cache (and the v3 needle
 // lane it feeds) still reflects the current skills. An unexpected error in
 // another step leaves the prior cache intact (skills are best-effort).
+//
+// Always-candidate skills are pinned into the selector pool by catalog
+// declaration rather than by similarity, so their membership and their cards
+// are served from the local catalog before the first seed run completes —
+// `listAlwaysCandidateSkillSlugs` primes that fallback, and the seeded snapshot
+// replaces it as soon as it lands.
 
 import { listCatalogSkills, listInstalledSkills } from "@vellumai/plugin-api";
 
@@ -79,6 +85,30 @@ export function skillSlugFor(id: string): string {
  * successful re-seed so callers always see a consistent snapshot.
  */
 let entries: Map<string, SkillEntry> | null = null;
+
+/**
+ * Ids of the enabled skills that declared `always-candidate` in their
+ * frontmatter, captured from the same enumeration that builds {@link entries}
+ * and replaced with it. Reading it here rather than re-enumerating the catalog
+ * keeps the injection engines off the per-turn filesystem scan
+ * `listInstalledSkills` performs.
+ */
+let alwaysCandidateIds: ReadonlySet<string> = new Set<string>();
+
+/**
+ * Pre-seed view of the same enabled-skill cards, read straight from the local
+ * catalog by {@link ensureCatalogFallback}.
+ *
+ * Always-candidate membership is a static catalog fact, so the injection
+ * engines must not have to wait on Qdrant plus a configured embedding backend
+ * to learn it: on a freshly hatched assistant the first turn arrives before the
+ * boot seed finishes, and an empty pin set means the model never sees a pinned
+ * skill card. The fallback is built at most once and is dropped the moment a
+ * seed run installs the authoritative {@link entries} snapshot.
+ */
+let fallbackEntries: Map<string, SkillEntry> | null = null;
+let fallbackAlwaysCandidateIds: ReadonlySet<string> = new Set<string>();
+let fallbackLoad: Promise<void> | null = null;
 let requestedSeedGeneration = 0;
 let processedSeedGeneration = 0;
 let activeSeedDrain: Promise<void> | null = null;
@@ -105,11 +135,93 @@ const seedWaiters: Array<{ generation: number; resolve: () => void }> = [];
  */
 let legacyKindBackfillDone = false;
 
+interface InstalledSkillCards {
+  /** Every locally installed skill id, whatever its resolved state. */
+  installedIds: Set<string>;
+  /** Rendered capability cards for the enabled skills, in catalog order. */
+  cards: SkillEntry[];
+  /** The subset of {@link cards} whose skill declared `always-candidate`. */
+  alwaysCandidateIds: Set<string>;
+}
+
+/**
+ * Enumerate the installed skill catalog and render one capability card per
+ * enabled skill. Feature-flag gating is resolved host-side: gated skills arrive
+ * as `state: "unavailable"` and are dropped by the enabled filter, as are
+ * skills the user disabled.
+ *
+ * The single definition of "which skills are enabled and what does each card
+ * say": the seed run embeds these cards and caches them in {@link entries},
+ * and {@link ensureCatalogFallback} serves the same cards from the catalog
+ * before the first seed completes.
+ */
+async function buildInstalledSkillCards(): Promise<InstalledSkillCards> {
+  const installed = await listInstalledSkills();
+  const installedIds = new Set<string>(installed.map((s) => s.id));
+  const cards: SkillEntry[] = [];
+  const alwaysCandidateIds = new Set<string>();
+  for (const skill of installed) {
+    if (skill.state !== "enabled") {
+      continue;
+    }
+    const augmented = augmentMcpSetupDescription(skill);
+    // Always-candidate skills are pinned into the selector pool every turn, so
+    // they get a larger budget for a fuller, multi-mode capability statement.
+    const content = buildSkillContent(
+      augmented,
+      skill.alwaysCandidate ? ALWAYS_CANDIDATE_CARD_CHARS : undefined,
+    );
+    if (skill.alwaysCandidate) {
+      alwaysCandidateIds.add(skill.id);
+    }
+    cards.push({ id: skill.id, content });
+  }
+  return { installedIds, cards, alwaysCandidateIds };
+}
+
+/**
+ * Populate {@link fallbackEntries} from the local catalog when no seed run has
+ * installed {@link entries} yet. A no-op once either cache is present, so the
+ * per-turn cost after the first call is a resolved promise rather than the
+ * filesystem scan `listInstalledSkills` performs. Concurrent callers share one
+ * in-flight build; a failed build is not latched, so the next turn retries.
+ */
+async function ensureCatalogFallback(): Promise<void> {
+  if (entries || fallbackEntries) {
+    return;
+  }
+  const pending = (fallbackLoad ??= buildInstalledSkillCards()
+    .then(({ cards, alwaysCandidateIds: ids }) => {
+      // A seed that landed while this build was in flight is authoritative.
+      if (entries) {
+        return;
+      }
+      fallbackEntries = new Map(cards.map((card) => [card.id, card]));
+      fallbackAlwaysCandidateIds = ids;
+    })
+    .catch((err: unknown) => {
+      log.warn(
+        { err },
+        "Failed to enumerate the skill catalog for the pre-seed card fallback",
+      );
+    })
+    .finally(() => {
+      fallbackLoad = null;
+    }));
+  await pending;
+}
+
+/** The authoritative seeded snapshot, or the pre-seed catalog fallback. */
+function readableEntries(): Map<string, SkillEntry> | null {
+  return entries ?? fallbackEntries;
+}
+
 /**
  * Steps (per run):
  *   1. Enumerate the installed skill catalog with resolved states
- *      (`listInstalledSkills`). Feature-flag gating is resolved host-side:
- *      gated skills arrive as `state: "unavailable"` and are not seeded.
+ *      (`buildInstalledSkillCards`, over `listInstalledSkills`). Feature-flag
+ *      gating is resolved host-side: gated skills arrive as
+ *      `state: "unavailable"` and are not seeded.
  *   2. Build a `SkillEntry` per enabled skill, applying the mcp-setup
  *      augmentation and the prose-style content render (`buildSkillContent`,
  *      capped at 500 chars).
@@ -176,29 +288,17 @@ function resolveSeedWaiters(): void {
 async function runSeedV2SkillEntries(generation: number): Promise<void> {
   try {
     const config = getConfig();
-    const installed = await listInstalledSkills();
-    const enabled = installed.filter((s) => s.state === "enabled");
-
-    // Track every locally-installed skill id (regardless of enabled/disabled/
-    // unavailable state) so the catalog-seeding loop below treats them all as
-    // "installed" and never re-seeds a disabled skill from the remote catalog
-    // as if it were uninstalled.
-    const installedIds = new Set<string>(installed.map((s) => s.id));
-
-    // Build the input list, applying the mcp-setup description augmentation.
-    // Flag-gated skills arrive as `state: "unavailable"` and are excluded by
-    // the enabled filter.
-    const seeds: SkillEntry[] = [];
-    for (const skill of enabled) {
-      const augmented = augmentMcpSetupDescription(skill);
-      // Always-candidate skills are pinned into the selector pool every turn, so
-      // they get a larger budget for a fuller, multi-mode capability statement.
-      const content = buildSkillContent(
-        augmented,
-        skill.alwaysCandidate ? ALWAYS_CANDIDATE_CARD_CHARS : undefined,
-      );
-      seeds.push({ id: skill.id, content });
-    }
+
+    // `installedIds` tracks every locally-installed skill id (regardless of
+    // enabled/disabled/unavailable state) so the catalog-seeding loop below
+    // treats them all as "installed" and never re-seeds a disabled skill from
+    // the remote catalog as if it were uninstalled.
+    const {
+      installedIds,
+      cards,
+      alwaysCandidateIds: nextAlwaysCandidateIds,
+    } = await buildInstalledSkillCards();
+    const seeds: SkillEntry[] = [...cards];
 
     // Seed uninstalled catalog skills so their activation hints are
     // discoverable by intent. Track whether the catalog was available so we
@@ -366,6 +466,11 @@ async function runSeedV2SkillEntries(generation: number): Promise<void> {
     // observes the new skill set (skill entries share the unified concept-page
     // collection and surface in the same index).
     entries = nextEntries;
+    alwaysCandidateIds = nextAlwaysCandidateIds;
+    // The seeded snapshot supersedes the pre-seed catalog fallback, which also
+    // omits the uninstalled catalog skills this run embedded.
+    fallbackEntries = null;
+    fallbackAlwaysCandidateIds = new Set<string>();
     invalidatePageIndex();
 
     // Surface a dense-embed failure to `throwOnError` callers (the managed-
@@ -380,9 +485,11 @@ async function runSeedV2SkillEntries(generation: number): Promise<void> {
 }
 
 /**
- * Synchronous lookup of a previously-seeded `SkillEntry` by skill id. Returns
- * `null` when the cache has not yet been populated, when the id is unknown,
- * or when a prior seed run dropped the id (e.g. the skill was disabled).
+ * Synchronous lookup of a rendered `SkillEntry` by skill id, served from the
+ * seeded cache or — before the first seed completes — from the pre-seed
+ * catalog fallback {@link listAlwaysCandidateSkillSlugs} primes. Returns `null`
+ * when neither is populated, when the id is unknown, or when a prior seed run
+ * dropped the id (e.g. the skill was disabled).
  *
  * Accepts either a bare skill id (`example-skill`) or its unified-collection
  * slug (`skills/example-skill`) so render-side callers can pass through what
@@ -395,7 +502,7 @@ export function getSkillCapability(idOrSlug: string): SkillEntry | null {
   const id = idOrSlug.startsWith(SKILL_SLUG_PREFIX)
     ? idOrSlug.slice(SKILL_SLUG_PREFIX.length)
     : idOrSlug;
-  const entry = entries?.get(id);
+  const entry = readableEntries()?.get(id);
   return entry ? Object.freeze({ ...entry }) : null;
 }
 
@@ -423,9 +530,40 @@ export function listSkillEntries(): SkillEntry[] {
     .map((entry) => Object.freeze({ ...entry }));
 }
 
+/**
+ * Slugs of the enabled skills marked `always-candidate`, restricted to those
+ * whose card is renderable.
+ *
+ * Retrieval scores a skill by how closely the turn resembles its card, so a
+ * cross-cutting capability the user never names by hand never wins a candidate
+ * slot. These skills opt out of that: whether they apply is a judgment for the
+ * model, so the injection engines pin their cards instead of waiting for a
+ * similarity hit.
+ *
+ * Async because membership is a static catalog fact that must not depend on the
+ * embedding store: before the first seed run completes this reads the catalog
+ * directly (see {@link ensureCatalogFallback}), which also makes each pinned
+ * slug's card resolvable through {@link getSkillCapability} so the render path
+ * emits it instead of silently dropping the pin. Once a seed run lands, its
+ * snapshot is authoritative.
+ */
+export async function listAlwaysCandidateSkillSlugs(): Promise<string[]> {
+  await ensureCatalogFallback();
+  const available = readableEntries();
+  const ids = entries ? alwaysCandidateIds : fallbackAlwaysCandidateIds;
+  return [...ids]
+    .filter((id) => available?.has(id) === true)
+    .sort()
+    .map((id) => skillSlugFor(id));
+}
+
 /** @internal Test-only: clear the module-level cache. */
 export function _resetSkillStoreForTests(): void {
   entries = null;
+  alwaysCandidateIds = new Set<string>();
+  fallbackEntries = null;
+  fallbackAlwaysCandidateIds = new Set<string>();
+  fallbackLoad = null;
   requestedSeedGeneration = 0;
   processedSeedGeneration = 0;
   activeSeedDrain = null;

package/src/plugins/defaults/memory/v2/__tests__/injection.test.ts

@@ -129,6 +129,8 @@ mock.module("@qdrant/js-client-rest", () => ({
 const skillState = {
   /** id → SkillEntry consulted by `getSkillCapability`. */
   entries: new Map<string, SkillEntry>(),
+  /** Skill ids the store reports as `always-candidate`. */
+  alwaysCandidateIds: new Set<string>(),
 };
 
 mock.module("../../substrate/skill-store.js", () => ({
@@ -146,6 +148,11 @@ mock.module("../../substrate/skill-store.js", () => ({
   // time. Tests stage skill content via `skillState.entries`; expose them
   // here so the page-index loader sees a consistent view.
   listSkillEntries: () => Array.from(skillState.entries.values()),
+  listAlwaysCandidateSkillSlugs: () =>
+    [...skillState.alwaysCandidateIds]
+      .filter((id) => skillState.entries.has(id))
+      .sort()
+      .map((id) => `skills/${id}`),
 }));
 
 // ---------------------------------------------------------------------------
@@ -527,6 +534,7 @@ function resetState(): void {
   state.queryResponses.dense.length = 0;
   state.queryResponses.sparse.length = 0;
   skillState.entries.clear();
+  skillState.alwaysCandidateIds.clear();
   cliCommandState.entries.clear();
   telemetryState.recordCalls.length = 0;
   telemetryState.recordShouldThrow = false;
@@ -547,6 +555,13 @@ function stageSkills(entries: SkillEntry[]): void {
   }
 }
 
+/** Mark staged skill ids as `always-candidate` in the mocked store. */
+function stageAlwaysCandidates(ids: string[]): void {
+  for (const id of ids) {
+    skillState.alwaysCandidateIds.add(id);
+  }
+}
+
 /** Stage cli-command-store cache entries for the upcoming render. */
 function stageCliCommands(entries: CliCommandEntryStub[]): void {
   for (const entry of entries) {
@@ -980,6 +995,122 @@ describe("injectMemoryV2Block", () => {
     expect(skillIdx).toBeGreaterThan(headerIdx);
   });
 
+  // ---------------------------------------------------------------------------
+  // Always-candidate skills
+  // ---------------------------------------------------------------------------
+
+  test("pins an always-candidate skill card that retrieval never surfaced", async () => {
+    stageTurn([]);
+    stageSkills([
+      {
+        id: "visualize",
+        content:
+          'The "Visualize" skill (visualize) is available. Render a polished visual inline.',
+      },
+    ]);
+    stageAlwaysCandidates(["visualize"]);
+
+    const result = await injectMemoryV2Block({
+      conversationId: "conv-pin-1",
+      currentTurn: 1,
+      recentTurnPairs: [
+        { assistantMessage: "", userMessage: "How does DNS work?" },
+      ],
+      nowText: "Now",
+      messageId: "msg-1",
+      config: makeConfig(),
+    });
+
+    expect(result.toInject).toEqual(["skills/visualize"]);
+    expect(result.block).toContain("### Skills You Can Use");
+    expect(result.block).toContain(
+      'The "Visualize" skill (visualize) is available. Render a polished visual inline. → use skill_load to activate',
+    );
+  });
+
+  test("does not double-list a pinned skill retrieval also picked", async () => {
+    stageTurn([{ slug: "skills/visualize", denseScore: 0.9 }]);
+    stageSkills([
+      {
+        id: "visualize",
+        content:
+          'The "Visualize" skill (visualize) is available. Render a polished visual inline.',
+      },
+    ]);
+    stageAlwaysCandidates(["visualize"]);
+
+    const result = await injectMemoryV2Block({
+      conversationId: "conv-pin-2",
+      currentTurn: 1,
+      recentTurnPairs: [
+        { assistantMessage: "", userMessage: "Draw me a diagram" },
+      ],
+      nowText: "Now",
+      messageId: "msg-1",
+      config: makeConfig(),
+    });
+
+    expect(result.toInject).toEqual(["skills/visualize"]);
+    const first = result.block!.indexOf('The "Visualize" skill');
+    expect(first).toBeGreaterThan(-1);
+    expect(result.block!.indexOf('The "Visualize" skill', first + 1)).toBe(-1);
+  });
+
+  test("re-attaches a pinned skill only once across turns", async () => {
+    stageTurn([]);
+    stageSkills([
+      {
+        id: "visualize",
+        content:
+          'The "Visualize" skill (visualize) is available. Render a polished visual inline.',
+      },
+    ]);
+    stageAlwaysCandidates(["visualize"]);
+
+    const params = {
+      conversationId: "conv-pin-3",
+      recentTurnPairs: [
+        { assistantMessage: "", userMessage: "How does DNS work?" },
+      ],
+      nowText: "Now",
+      config: makeConfig(),
+    };
+    const first = await injectMemoryV2Block({
+      ...params,
+      currentTurn: 1,
+      messageId: "msg-1",
+    });
+    expect(first.toInject).toEqual(["skills/visualize"]);
+
+    stageTurn([]);
+    const second = await injectMemoryV2Block({
+      ...params,
+      currentTurn: 2,
+      messageId: "msg-2",
+    });
+    expect(second.toInject).toEqual([]);
+    expect(second.block).toBeNull();
+  });
+
+  test("does not pin an always-candidate skill missing from the store cache", async () => {
+    stageTurn([]);
+    stageAlwaysCandidates(["visualize"]);
+
+    const result = await injectMemoryV2Block({
+      conversationId: "conv-pin-4",
+      currentTurn: 1,
+      recentTurnPairs: [
+        { assistantMessage: "", userMessage: "How does DNS work?" },
+      ],
+      nowText: "Now",
+      messageId: "msg-1",
+      config: makeConfig(),
+    });
+
+    expect(result.toInject).toEqual([]);
+    expect(result.block).toBeNull();
+  });
+
   test("renders concept-page sections before the skills subsection in mixed blocks", async () => {
     // Concept page hit AND a skill — concept-page sections come first, then
     // the skills subsection.

package/src/plugins/defaults/memory/v2/__tests__/router.test.ts

@@ -73,6 +73,7 @@ mock.module("../../../../../util/logger.js", () => ({
 mock.module("../../substrate/skill-store.js", () => ({
   SKILL_SLUG_PREFIX: "skills/",
   listSkillEntries: () => skillState.entries,
+  listAlwaysCandidateSkillSlugs: () => [],
 }));
 
 // Stub `computeInjectionScores` so tier-2 tests can dictate scores

package/src/plugins/defaults/memory/v2/activation-log-store.ts

@@ -57,6 +57,9 @@ export interface MemoryV2ConceptRowRecord {
    *     A single-batch (no-tier carve-out) workspace produces `tier3:0`.
    *     The bucket index lets inspector queries attribute selections to
    *     specific hash-bucketed parallel calls.
+   *   - `always_candidate` — a skill pinned by its `always-candidate`
+   *     frontmatter rather than selected by activation or the router. Like
+   *     the router-mode tags it carries zeroed activation values.
    *   - `carry_over`  — router-mode row representing a slug carried over
    *     from `priorEverInjected` that the router did NOT re-pick on this
    *     turn. The cached attachment from a prior turn is still present
@@ -72,6 +75,7 @@ export interface MemoryV2ConceptRowRecord {
     | "ann_top50"
     | "both"
     | "router"
+    | "always_candidate"
     | "carry_over"
     | "tier1"
     | "tier2"

package/src/plugins/defaults/memory/v2/injection.ts

@@ -33,7 +33,11 @@ import {
 import { getEdgeIndex } from "../substrate/edge-index.js";
 import { getPageIndex } from "../substrate/page-index.js";
 import { readPage, renderPageContent } from "../substrate/page-store.js";
-import { getSkillCapability, isSkillSlug } from "../substrate/skill-store.js";
+import {
+  getSkillCapability,
+  isSkillSlug,
+  listAlwaysCandidateSkillSlugs,
+} from "../substrate/skill-store.js";
 import { spreadActivation } from "../substrate/spread.js";
 import type { ActivationState, EverInjectedEntry } from "../substrate/types.js";
 import {
@@ -316,6 +320,28 @@ export async function injectMemoryV2Block(
  * which this helper overwrites. `nextStateMap` is the activation
  * pipeline's sparse next-state; router-mode callers pass an empty map.
  */
+/**
+ * Telemetry row for a pinned always-candidate skill. Activation never scored
+ * it, so every score field is zero, matching the router-mode rows.
+ */
+function makePinnedSkillRow(slug: string): MemoryV2ConceptRowRecord {
+  return {
+    slug,
+    finalActivation: 0,
+    ownActivation: 0,
+    priorActivation: 0,
+    simUser: 0,
+    simAssistant: 0,
+    simNow: 0,
+    simUserRerankBoost: 0,
+    simAssistantRerankBoost: 0,
+    inRerankPool: false,
+    spreadContribution: 0,
+    source: "always_candidate",
+    status: "not_injected",
+  };
+}
+
 async function finalizeInjection(args: {
   workspaceDir: string;
   conversationId: string;
@@ -342,12 +368,32 @@ async function finalizeInjection(args: {
     currentTurn,
     messageId,
     priorEverInjected,
-    slugsToRender,
+    slugsToRender: selectedSlugs,
     telemetryRows,
     config,
     nextStateMap,
   } = args;
 
+  const everInjectedSet = new Set(priorEverInjected.map((entry) => entry.slug));
+
+  // Skills marked `always-candidate` are pinned rather than retrieved: their
+  // relevance is a judgment the model makes each turn, not a similarity the
+  // embedding finds, so activation and the router both leave them out. Attach
+  // them alongside whatever this turn selected, skipping any already carried by
+  // the cached prefix — v2 is append-only, so a card attached once stays
+  // visible until compaction evicts the turn and re-opens the slug.
+  const selectedSet = new Set(selectedSlugs);
+  const pinnedSlugs = (await listAlwaysCandidateSkillSlugs()).filter(
+    (slug) => !selectedSet.has(slug) && !everInjectedSet.has(slug),
+  );
+  const slugsToRender = [...selectedSlugs, ...pinnedSlugs];
+  const telemetrySlugSet = new Set(telemetryRows.map((row) => row.slug));
+  for (const slug of pinnedSlugs) {
+    if (!telemetrySlugSet.has(slug)) {
+      telemetryRows.push(makePinnedSkillRow(slug));
+    }
+  }
+
   // `mode` is `let` because the trailing try/finally promotes it to "errored"
   // when the render/telemetry path throws — we still want a log row written
   // (with whatever rows we managed to build) so silent failures are
@@ -377,7 +423,6 @@ async function finalizeInjection(args: {
         (isCliCommandSlug(slug) && !getCliCommandCapability(slug)),
     ),
   );
-  const everInjectedSet = new Set(priorEverInjected.map((entry) => entry.slug));
   const newlyInjected = slugsToRender.filter(
     (slug) => !everInjectedSet.has(slug) && !missingSyntheticSlugs.has(slug),
   );

package/src/plugins/defaults/memory/v2/rerank-local.ts

@@ -3,7 +3,11 @@ import { existsSync } from "node:fs";
 
 import type { RerankDtype } from "../../../../config/schemas/memory-v2.js";
 import { EmbeddingRuntimeManager } from "../../../../persistence/embeddings/embedding-runtime-manager.js";
-import { PromiseGuard, workerMemoryEnv } from "../host-utils.js";
+import {
+  PromiseGuard,
+  workerComputeEnv,
+  workerMemoryEnv,
+} from "../host-utils.js";
 import { getLogger } from "../logging.js";
 import { getEmbeddingModelsDir } from "../paths.js";
 
@@ -160,7 +164,7 @@ export class LocalRerankBackend {
         modelCacheDir,
         this.dtype,
       ],
-      env: workerMemoryEnv(),
+      env: { ...workerMemoryEnv(), ...workerComputeEnv() },
       stdin: "pipe",
       stdout: "pipe",
       stderr: "pipe",

package/src/plugins/defaults/memory/v3/__tests__/pool-select.test.ts

@@ -418,7 +418,7 @@ describe("selectPool — infrastructure failures throw", () => {
       source: "memory_v3",
       code: "PROVIDER_BILLING",
       userMessage:
-        "You've run out of credits. Add funds to continue using the assistant.",
+        "You're out of credits. Add credits in Settings → Billing to continue.",
       errorCategory: "credits_exhausted",
     });
   });

package/src/plugins/defaults/platform-hosted/routes/reengage.ts

@@ -182,7 +182,7 @@ export const POST = async (request: Request): Promise<Response> => {
       // Drafting a short email is latency-bound, not depth-bound, so run it on
       // the fast model rather than the balanced main-agent default. `inference`
       // is the general-purpose call site plugins use for exactly this — it
-      // resolves to the Speed (cost-optimized) profile — so we reuse it instead
+      // resolves to the Cost (cost-optimized) profile, so we reuse it instead
       // of teaching the daemon about a reengagement-specific call site.
       callSite: "inference",
       signal: request.signal,

package/src/plugins/defaults/turn-context/injectors.ts

@@ -35,6 +35,7 @@ const unifiedTurnContextInjector: Injector = {
       timestamp,
       interfaceName: ctx.interfaceName,
       clientOs: ctx.clientOs,
+      visibleApp: ctx.visibleApp,
       channelName: ctx.channelName,
       actorContext: ctx.actorContext,
       configuredUserTimezone: ctx.configuredUserTimezone,

package/src/plugins/defaults/turn-context/unified-turn-context.ts

@@ -19,6 +19,20 @@ export interface UnifiedTurnContextOptions {
   timestamp: string;
   interfaceName?: string;
   clientOs?: string;
+  /**
+   * App the user currently has open on screen. Rendered as the `visible_app:`
+   * line so unqualified references to "the app" resolve without a lookup.
+   */
+  visibleApp?: {
+    appId: string;
+    /** Opaque for workspace apps, so the readable handle travels alongside. */
+    name: string;
+    /** Directory stem: the handle a human would recognize the app by. */
+    slug: string;
+    sourceDir: string;
+    /** Set when the app is bundled by an installed plugin rather than built here. */
+    pluginName?: string;
+  } | null;
   channelName?: string;
   actorContext?: InboundActorContext | null;
   configuredUserTimezone?: string | null;
@@ -104,6 +118,18 @@ export function buildUnifiedTurnContextBlock(
   if (options.clientOs) {
     lines.push(`client_os: ${options.clientOs}`);
   }
+  if (options.visibleApp) {
+    const app = options.visibleApp;
+    // Plugin-bundled apps are owned by their plugin: their source is replaced
+    // on plugin update, so the model is told where it came from rather than
+    // treating it as an ordinary sandbox app to rewrite.
+    const provenance = app.pluginName
+      ? ` It is bundled by the "${sanitizeInlineContextValue(app.pluginName)}" plugin, not built in the sandbox.`
+      : "";
+    lines.push(
+      `visible_app: "${sanitizeInlineContextValue(app.name)}" (app_id: "${sanitizeInlineContextValue(app.appId)}", slug: "${sanitizeInlineContextValue(app.slug)}", source: "${sanitizeInlineContextValue(app.sourceDir)}"). The user has this app open on screen; unqualified references to "the app" mean this one. The app tools take the app_id.${provenance}`,
+    );
+  }
 
   // Actor identity and trust fields — only for non-guardian turns.
   if (options.actorContext) {

package/src/plugins/types.ts

@@ -153,6 +153,23 @@ export interface TurnContext {
    * transport interface.
    */
   readonly clientOs?: string;
+  /**
+   * The app the client has open on screen, resolved from the id the client
+   * reports with each message. Rendered as the `visible_app:` line so the
+   * assistant can resolve "the app" to what the user is looking at instead of
+   * guessing or asking. Absent when no app is in view.
+   */
+  readonly visibleApp?: {
+    /** Canonical id the app tools key off (an opaque UUID for workspace apps). */
+    appId: string;
+    name: string;
+    /** Directory stem: the readable handle for an otherwise opaque id. */
+    slug: string;
+    /** Absolute path of the app's source directory. */
+    sourceDir: string;
+    /** Owning plugin, when the app is plugin-bundled rather than sandbox-built. */
+    pluginName?: string;
+  } | null;
   /** Channel label gating response-discretion guidance in `<turn_context>`. */
   readonly channelName?: string;
   /**

package/src/prompts/templates/system-sections.ts

@@ -341,9 +341,9 @@ To share a workspace file, use a markdown link with the \`vellum://\` scheme:
 
 The path after \`workspace/\` is relative to your working directory. The file renders as a downloadable attachment. For host filesystem files, use \`vellum://host/absolute/path\`.
 
-Use the same link form when referencing a workspace file you are discussing — in the app, clicking the link lets the user open the file in the workspace browser or download it.
+Use the same link form to reference a file you are discussing: in the app, the link lets the user open or download it.
 
-Embed images/GIFs inline using standard markdown: \`![description](URL)\`.
+Embed images, audio, and video inline with \`![description](URL or vellum://workspace/path)\`. Reference every other file type, including PDFs and documents, as a plain link: \`[name](vellum://workspace/path)\`.
 `,
   },
   {