@vellumai/assistant 0.12.2-staging.4 → 0.12.2-staging.6

package/src/live-voice/protocol.ts

@@ -166,6 +166,16 @@ export interface LiveVoiceClientStartFrame {
    * has never heard of.
    */
   readonly sessionControls?: readonly LiveVoiceSessionControl[];
+  /**
+   * This client sends a fresh `sight_frame` right after it carries out a look
+   * control, with timing reason `look`, whether or not a share or the camera
+   * was already running. The session answers the look from that frame on a
+   * turn of its own, so the reply that asked for the look only acknowledges it.
+   *
+   * Absent means false: a client that predates the field sends no such frame,
+   * and a session waiting on one would promise a look that never comes.
+   */
+  readonly lookFrames?: boolean;
 }
 
 const LIVE_VOICE_SESSION_CONTROLS = [
@@ -1269,6 +1279,15 @@ function validateStartFrame(
     );
   }
 
+  if ("lookFrames" in value && typeof value.lookFrames !== "boolean") {
+    return protocolError(
+      "invalid_field",
+      "start frame field lookFrames must be a boolean",
+      "lookFrames",
+      "start",
+    );
+  }
+
   if ("textInput" in value && typeof value.textInput !== "boolean") {
     return protocolError(
       "invalid_field",
@@ -1308,6 +1327,7 @@ function validateStartFrame(
         : {}),
       ...(value.textInput === true ? { textInput: true } : {}),
       ...(sessionControls.length > 0 ? { sessionControls } : {}),
+      ...(value.lookFrames === true ? { lookFrames: true } : {}),
     },
   };
 }

package/src/live-voice/session-controls.ts

@@ -8,6 +8,7 @@ import {
   NORMAL_UPDATES_MARKER,
   parseTerminalSessionControl,
   type SessionControlRequest,
+  TASK_STOP_MARKER,
 } from "../calls/voice-control-protocol.js";
 import type { VoiceProgressConfig } from "../config/schemas/voice.js";
 import type { LiveVoiceSessionControl } from "./protocol.js";
@@ -33,10 +34,61 @@ const CLIENT_CONTROL_LINES: Record<LiveVoiceSessionControl, string> = {
   mute: `- To mute their microphone (for example "mute for 30 seconds" or "mute yourself, I need to take this"), confirm in a few words, then end your reply with [MUTE:<seconds>] when they gave a duration or ${MUTE_MARKER} when they did not. While muted you cannot hear them, so mention they can unmute from the call controls unless the mute is timed.`,
 };
 
+/**
+ * The look lines for a client that declared `lookFrames`: one that sends a
+ * fresh frame the moment it carries out a look, which the session answers on
+ * a turn of its own (see {@link LOOK_FRAME_REASON}). The reply that asks for
+ * the look is therefore only the acknowledgement, and asking to look again is
+ * how the model gets a current view of a share that is already running.
+ */
+const LOOK_FRAME_CONTROL_LINES: Partial<
+  Record<LiveVoiceSessionControl, string>
+> = {
+  look_screen: `- To look at their screen (for example "take a look at my screen", or "can you see it now?" after something on it changed), say in a few words that you are taking a look, then end your reply with ${LOOK_SCREEN_MARKER}. Use it even when their screen is already shared with you, to see it as it is now. You get a fresh view right after you finish speaking and answer from that, so do not describe the screen yet and do not ask them to say anything more.`,
+  look_camera: `- To look through their camera (for example "look at this" or "can you see this?" while they hold something up), say in a few words that you are taking a look, then end your reply with ${LOOK_CAMERA_MARKER}. Use it even when the camera is already on, to see what it shows now. You get a fresh view right after you finish speaking and answer from that, so do not describe it yet and do not ask them to say anything more.`,
+};
+
+/**
+ * The `reason` a client's sight frame timing carries when the frame is the
+ * fresh view it took for a look control. Only a client that declared
+ * `lookFrames` sends one, and the session answers the look from it.
+ */
+export const LOOK_FRAME_REASON = "look";
+
+/** The controls that end in a fresh frame the session answers from. */
+export type LookSessionControl = Extract<
+  LiveVoiceSessionControl,
+  "look_screen" | "look_camera"
+>;
+
+export function isLookSessionControl(
+  action: string,
+): action is LookSessionControl {
+  return action === "look_screen" || action === "look_camera";
+}
+
+/**
+ * The persisted `content` of the turn that answers a look. Hidden: there is no
+ * user utterance behind the turn, and the instruction rides the control prompt
+ * ({@link lookFollowUpNote}).
+ */
+export const LOOK_FOLLOW_UP_CONTENT = "(fresh view taken; answer from it now)";
+
+/**
+ * Appended to the control prompt of the turn that answers a look: the reply
+ * that asked for it only acknowledged, and the frame it asked for has landed.
+ */
+export function lookFollowUpNote(action: LookSessionControl): string {
+  const what = action === "look_screen" ? "their screen" : "their camera";
+  return `You just took a fresh look at ${what}, and the newest image in the conversation is what it shows right now. Answer what they wanted you to look at, out loud, in a few spoken sentences. If the image does not show what they meant, say briefly what you do see and ask. You have already said you were taking a look, so do not say it again and do not end with a look marker.`;
+}
+
 // Always taught: narration is the session's own, so no client has to be able
 // to carry it out.
 const UPDATES_LINE = `- To hear fewer spoken progress updates while you work (for example "don't give me updates so often"), confirm that you will only check in now and then and will tell them when it is done, then end your reply with ${FEWER_UPDATES_MARKER}. If they later want regular updates back, confirm and end with ${NORMAL_UPDATES_MARKER}.`;
 
+const TASK_STOP_LINE = `- To abandon the unfinished task while keeping the call open (for example "stop that" or "never mind about that task"), confirm briefly, then end your reply with ${TASK_STOP_MARKER}. Use this only when they want the task abandoned, not when they interrupt with a question or correction.`;
+
 /**
  * The control-prompt block that teaches the session controls: the ones the
  * client declared plus the progress-update cadence. Every leg gets it,
@@ -49,12 +101,18 @@ const UPDATES_LINE = `- To hear fewer spoken progress updates while you work (fo
 export function sessionControlTeaching(
   controls: readonly LiveVoiceSessionControl[],
   leg: { frontDoor?: boolean },
+  client: { lookFrames?: boolean; unfinishedTaskPending?: boolean } = {},
 ): string {
+  const lines =
+    client.lookFrames === true
+      ? { ...CLIENT_CONTROL_LINES, ...LOOK_FRAME_CONTROL_LINES }
+      : CLIENT_CONTROL_LINES;
   return [
     "The user can also control this call by asking you. Only when they clearly ask:",
-    ...controls.map((control) => CLIENT_CONTROL_LINES[control]),
+    ...controls.map((control) => lines[control]),
     ...lookGuidance(controls),
     UPDATES_LINE,
+    ...(client.unfinishedTaskPending === true ? [TASK_STOP_LINE] : []),
     `The marker must be the very last thing in your reply. It is never spoken and does nothing anywhere else.${leg.frontDoor === true ? "" : " Never emit any other bracketed marker."}`,
   ].join("\n");
 }
@@ -83,7 +141,7 @@ function lookGuidance(controls: readonly LiveVoiceSessionControl[]): string[] {
 /** A session control the client carries out, sent as a `session_control` frame. */
 export type ClientSessionControlRequest = Exclude<
   SessionControlRequest,
-  { action: "updates" }
+  { action: "updates" } | { action: "task_stop" }
 >;
 
 /**
@@ -100,7 +158,7 @@ export function requestedSessionControl(
   if (request === null) {
     return null;
   }
-  if (request.action === "updates") {
+  if (request.action === "updates" || request.action === "task_stop") {
     return request;
   }
   return controls.includes(request.action) ? request : null;

package/src/monitoring/plugin-auto-update.ts

@@ -155,6 +155,12 @@ function tracksCuratedSource(inspection: PluginInspection): boolean {
   if (!remote) {
     return false;
   }
+  if (source.kind === "local") {
+    return remote.kind === "local" && source.path === remote.path;
+  }
+  if (remote.kind === "local") {
+    return false;
+  }
   return (
     `${source.owner}/${source.repo}`.toLowerCase() ===
       remote.repo.toLowerCase() && (source.path ?? "") === remote.path

package/src/plugins/defaults/memory/__tests__/memory-retrospective-prompt.test.ts

@@ -115,6 +115,21 @@ For everything else in your review window, use the \`remember\` tool on facts, p
     expect(out).toContain(
       "\n---\n\nIf your review window contains a PROCEDURE you actually carried out",
     );
+    // A refinement overwrites the whole file and the pass has no other read
+    // path to the skill, so the instruction has to point at `current`.
+    expect(out).toContain(
+      "rewriting `body_markdown` from `current.body_markdown` plus what you actually observed in the trace",
+    );
+    // Hints are the retrieval signal; a refinement carries them forward
+    // rather than regenerating them from one trace.
+    expect(out).toContain(
+      "restate `current.activation_hints` (revised only if the procedure's triggers changed",
+    );
+    // The store keeps omitted frontmatter on an overwrite, so the pass is told
+    // to leave unchanged fields out rather than restate them from memory.
+    expect(out).toContain(
+      "an omitted field keeps its current value and an empty one clears it",
+    );
     // An UPDATE is announced by a notice whose only account of the change is
     // what the pass passes here, so the instruction has to ask for it.
     expect(out).toContain(

package/src/plugins/defaults/memory/memory-retrospective-prompt.ts

@@ -223,7 +223,7 @@ If your review window contains a PROCEDURE you actually carried out — a sequen
 
 When you do capture a procedure:
 
-1. Deduplicate against existing skills first. Call \`find_similar_skills\` with the procedure's goal as its \`goal\` argument. Each hit carries a \`source\` (bundled, managed, plugin, workspace, or extra), and a managed hit also carries \`author\` (\`"assistant"\` if you authored it, \`"user"\` if a person did, omitted if untagged). You may only overwrite or refine a skill YOU authored: a hit with \`source: "managed"\` AND \`author: "assistant"\`. ANY other hit means the procedure is ALREADY COVERED: a non-managed source (bundled, plugin, workspace, or extra), OR a managed skill that is NOT \`author: "assistant"\` (a person wrote it, or it is untagged). For an ALREADY COVERED hit do not \`overwrite\` it, do not shadow it by creating a skill with its \`skill_id\`, and do not create a near-duplicate. Skip it. Only when a returned skill is one of your own (\`source: "managed"\`, \`author: "assistant"\`) and is the SAME procedure, UPDATE it: call \`scaffold_managed_skill\` with that \`skill_id\` and \`overwrite: true\`, rewriting \`body_markdown\` from what you actually observed in the trace, and pass \`change_summary\` (the update is rejected without it): one or two short sentences (under 200 characters) for the person who reads the "Skill updated" notice, naming what you changed and what in the trace prompted it (for example "Added the retry after an expired session and the export endpoint that held steady."). The notice shows nothing else about the change, so name the concrete step, value, or gotcha rather than saying the skill was refined. Only CREATE a new skill (fresh \`skill_id\`) when no existing skill of any source covers the procedure. Bias strongly toward reusing or refining your own skills over spawning near-duplicates.
+1. Deduplicate against existing skills first. Call \`find_similar_skills\` with the procedure's goal as its \`goal\` argument. Each hit carries a \`source\` (bundled, managed, plugin, workspace, or extra), and a managed hit also carries \`author\` (\`"assistant"\` if you authored it, \`"user"\` if a person did, omitted if untagged). You may only overwrite or refine a skill YOU authored: a hit with \`source: "managed"\` AND \`author: "assistant"\`. ANY other hit means the procedure is ALREADY COVERED: a non-managed source (bundled, plugin, workspace, or extra), OR a managed skill that is NOT \`author: "assistant"\` (a person wrote it, or it is untagged). For an ALREADY COVERED hit do not \`overwrite\` it, do not shadow it by creating a skill with its \`skill_id\`, and do not create a near-duplicate. Skip it. Only when a returned skill is one of your own (\`source: "managed"\`, \`author: "assistant"\`) and is the SAME procedure, UPDATE it. Such a hit carries \`current\`: the skill as it is now, in \`scaffold_managed_skill\`'s own argument names. Call \`scaffold_managed_skill\` with that \`skill_id\` and \`overwrite: true\`, rewriting \`body_markdown\` from \`current.body_markdown\` plus what you actually observed in the trace (keep the steps the trace did not contradict; correct or add the ones it did), restate \`current.activation_hints\` (revised only if the procedure's triggers changed; they are the skill's retrieval signal, not something to regenerate) and leave out any other \`current\` field you are not changing (\`emoji\`, \`category\`, \`includes\`, \`avoid_when\`): an omitted field keeps its current value and an empty one clears it, and pass \`change_summary\` (the update is rejected without it): one or two short sentences (under 200 characters) for the person who reads the "Skill updated" notice, naming what you changed and what in the trace prompted it (for example "Added the retry after an expired session and the export endpoint that held steady."). The notice shows nothing else about the change, so name the concrete step, value, or gotcha rather than saying the skill was refined. Only CREATE a new skill (fresh \`skill_id\`) when no existing skill of any source covers the procedure. Bias strongly toward reusing or refining your own skills over spawning near-duplicates.
 
 2. Capture procedure-scoped knowledge alongside the body. Failure modes, gotchas, and cached values you observed in the trace (error signatures and how you recovered, preconditions, IDs/paths/endpoints that held steady) belong in companion files passed via \`scaffold_managed_skill\`'s \`files\` input (for example \`references/failure-modes.md\`), and the SKILL.md body should reference them so a future load surfaces them.
 

package/src/runtime/routes/__tests__/plugins-routes.test.ts

@@ -1082,6 +1082,64 @@ describe("GET /v1/plugins/search", () => {
     expect("icon" in byName.get("plain-plugin")!).toBe(false);
   });
 
+  test("preserves a bundled MCP package source and integration metadata", async () => {
+    getCatalogSpy.mockImplementation(async (ref) =>
+      catalog(ref, [
+        {
+          name: "fathom",
+          path: "local:plugins/mcp-catalog/fathom@1.0.0",
+          description: "Search meeting transcripts.",
+          category: null,
+          integration: {
+            kind: "mcp",
+            displayName: "Fathom",
+            documentationUrl: "https://example.com/fathom/docs",
+            verifiedAt: "2026-09-15",
+            verification: "documentation-only",
+            setup: {
+              mode: "oauth",
+              instructions: "Connect your Fathom account.",
+            },
+            logo: "fathom.png",
+          },
+          source: {
+            kind: "local",
+            path: "plugins/mcp-catalog/fathom",
+            version: "1.0.0",
+          },
+        },
+      ]),
+    );
+
+    const result = await invokeSearch({ queryParams: { q: "fathom" } });
+
+    expect(result.matches).toEqual([
+      {
+        name: "fathom",
+        path: "local:plugins/mcp-catalog/fathom@1.0.0",
+        description: "Search meeting transcripts.",
+        category: null,
+        integration: {
+          kind: "mcp",
+          displayName: "Fathom",
+          documentationUrl: "https://example.com/fathom/docs",
+          verifiedAt: "2026-09-15",
+          verification: "documentation-only",
+          setup: {
+            mode: "oauth",
+            instructions: "Connect your Fathom account.",
+          },
+          logo: "fathom.png",
+        },
+        source: {
+          kind: "local",
+          path: "plugins/mcp-catalog/fathom",
+          version: "1.0.0",
+        },
+      },
+    ]);
+  });
+
   test("normalizes match categories to the Skills taxonomy (`developer` → `development`, `hobby` → null)", async () => {
     getCatalogSpy.mockImplementation(async (ref) =>
       catalog(ref, [
@@ -1607,6 +1665,50 @@ describe("POST /v1/plugins/install", () => {
     }
   });
 
+  test("installs a bundled package from the exact catalog source", async () => {
+    getCatalogSpy.mockImplementation(async (ref) =>
+      catalog(ref, [
+        {
+          name: "fathom",
+          path: "local:plugins/mcp-catalog/fathom@1.0.0",
+          category: null,
+          source: {
+            kind: "local",
+            path: "plugins/mcp-catalog/fathom",
+            version: "1.0.0",
+          },
+        },
+      ]),
+    );
+    installSpy.mockImplementation(async (opts) => ({
+      name: opts.name,
+      target: `/workspace/.vellum/plugins/${opts.name}`,
+      fileCount: 2,
+      ref: "1.0.0",
+      commit: null,
+      committedAt: null,
+    }));
+
+    const result = await invokeInstall({ body: { name: "fathom" } });
+
+    expect(installSpy.mock.calls[0]?.[0]).toEqual({
+      name: "fathom",
+      force: undefined,
+      trustedSource: {
+        kind: "local",
+        path: "plugins/mcp-catalog/fathom",
+        version: "1.0.0",
+      },
+    });
+    expect(result).toEqual({
+      ok: true,
+      name: "fathom",
+      target: "/workspace/.vellum/plugins/fathom",
+      fileCount: 2,
+      ref: "1.0.0",
+    });
+  });
+
   test("publishes sync_changed(plugins:list) on a successful install", async () => {
     installSpy.mockImplementation(async (opts) => trustedInstallResult(opts));
 

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

@@ -2,7 +2,7 @@
  * Route handlers for the assistant plugins surface.
  *
  * GET    /v1/plugins          — list installed plugins under `<workspaceDir>/plugins/`.
- * GET    /v1/plugins/search   — search the canonical GitHub catalog of installable plugins.
+ * GET    /v1/plugins/search   - search the reviewed catalog of installable plugins.
  * GET    /v1/plugins/:name    — resolve a single plugin's detail view (metadata + README).
  * POST   /v1/plugins/install  — install a plugin by name from the canonical source.
  * DELETE /v1/plugins/:name    — uninstall a plugin from `<workspaceDir>/plugins/<name>/`.
@@ -192,30 +192,47 @@ const pluginsListResponseSchema = z.object({
 });
 
 const pluginMatchSourceSchema = z
-  .object({
-    kind: z.literal("github"),
-    repo: z
-      .string()
-      .describe("`owner/repo` of the external plugin repository."),
-    path: z
-      .string()
-      .optional()
-      .describe(
-        "Directory within the repo, when the plugin is not at the root.",
-      ),
-    ref: z.string().describe("Pinned git ref the plugin is fetched from."),
-  })
-  .describe("Origin of the match: a whitelisted external plugin repository.");
+  .discriminatedUnion("kind", [
+    z.object({
+      kind: z.literal("github"),
+      repo: z
+        .string()
+        .describe("`owner/repo` of the external plugin repository."),
+      path: z
+        .string()
+        .optional()
+        .describe(
+          "Directory within the repo, when the plugin is not at the root.",
+        ),
+      ref: z.string().describe("Pinned git ref the plugin is fetched from."),
+    }),
+    z.object({
+      kind: z.literal("local"),
+      path: z.string().describe("Package key in the assistant bundle."),
+      version: z.string().describe("Bundled package version."),
+    }),
+  ])
+  .describe("Reviewed source of the marketplace entry.");
+
+const mcpPluginIntegrationSchema = z.object({
+  kind: z.literal("mcp"),
+  displayName: z.string(),
+  documentationUrl: z.string(),
+  verifiedAt: z.string(),
+  verification: z.literal("documentation-only"),
+  setup: z.object({
+    mode: z.enum(["oauth", "manual"]),
+    instructions: z.string(),
+  }),
+  logo: z.string(),
+  oauthProvider: z.string().optional(),
+});
 
 const pluginSearchMatchSchema = z.object({
   name: z
     .string()
     .describe("Install name. Matches `assistant plugins install <name>`."),
-  path: z
-    .string()
-    .describe(
-      "Human-readable origin: a `github:owner/repo@ref` locator for the external plugin.",
-    ),
+  path: z.string().describe("Human-readable catalog origin locator."),
   description: z
     .string()
     .optional()
@@ -232,6 +249,7 @@ const pluginSearchMatchSchema = z.object({
     .describe(
       "Marketplace category slug (Skills taxonomy); null when the entry declares none.",
     ),
+  integration: mcpPluginIntegrationSchema.optional(),
   source: pluginMatchSourceSchema,
 });
 
@@ -418,22 +436,20 @@ const fingerprintComparisonSchema = z
   );
 
 const installMetaSourceSchema = z
-  .object({
-    kind: z.string().describe("Source kind. Only `github` is written today."),
-    owner: z.string(),
-    repo: z.string(),
-    path: z
-      .string()
-      .optional()
-      .describe(
-        "Repo-relative directory holding the plugin root; absent = repo root.",
-      ),
-    ref: z
-      .string()
-      .describe(
-        "Ref the install resolved through (the pinned commit SHA for marketplace installs).",
-      ),
-  })
+  .discriminatedUnion("kind", [
+    z.object({
+      kind: z.literal("github"),
+      owner: z.string(),
+      repo: z.string(),
+      path: z.string().optional(),
+      ref: z.string(),
+    }),
+    z.object({
+      kind: z.literal("local"),
+      path: z.string(),
+      version: z.string(),
+    }),
+  ])
   .describe(
     "Source coordinates recorded in the install-time provenance sidecar.",
   );
@@ -489,6 +505,7 @@ const pluginLocalInfoSchema = z
 
 const pluginRemoteInfoSchema = z
   .object({
+    kind: z.literal("local").optional(),
     repo: z
       .string()
       .describe("`owner/repo` of the external plugin repository."),
@@ -517,6 +534,7 @@ const pluginRemoteInfoSchema = z
       .describe(
         "Ref of the canonical repo the marketplace manifest was read from.",
       ),
+    version: z.string().optional().describe("Bundled package version."),
   })
   .describe("The marketplace's current pin and advertised metadata.");
 
@@ -870,7 +888,8 @@ interface PluginMatchView {
   description?: string;
   icon?: string;
   category: string | null;
-  source: { kind: "github"; repo: string; path?: string; ref: string };
+  integration?: PluginSearchMatch["integration"];
+  source: PluginSearchMatch["source"];
 }
 
 /**
@@ -886,12 +905,7 @@ function projectMatch(
     name: m.name,
     path: m.path,
     category: normalizeMarketplaceCategory(m.category, validSlugs),
-    source: {
-      kind: "github",
-      repo: m.source.repo,
-      ref: m.source.ref,
-      ...(m.source.path !== undefined ? { path: m.source.path } : {}),
-    },
+    source: { ...m.source },
   };
   if (m.description !== undefined) {
     view.description = m.description;
@@ -899,6 +913,9 @@ function projectMatch(
   if (m.icon !== undefined) {
     view.icon = m.icon;
   }
+  if (m.integration !== undefined) {
+    view.integration = m.integration;
+  }
   return view;
 }
 
@@ -1276,12 +1293,15 @@ async function handleInstallPlugin({ body = {}, headers }: RouteHandlerArgs) {
         {
           name,
           force,
-          trustedSource: {
-            owner: source.owner,
-            repo: source.repo,
-            rootPath: source.path,
-            ref: source.ref,
-          },
+          trustedSource:
+            source.kind === "local"
+              ? source
+              : {
+                  owner: source.owner,
+                  repo: source.repo,
+                  rootPath: source.path,
+                  ref: source.ref,
+                },
         },
         { fetch: globalThis.fetch.bind(globalThis) },
       );