@vellumai/assistant 0.12.2-staging.5 → 0.12.2-staging.7

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";
@@ -86,6 +87,8 @@ export function lookFollowUpNote(action: LookSessionControl): string {
 // 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,
@@ -98,7 +101,7 @@ 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 } = {},
+  client: { lookFrames?: boolean; unfinishedTaskPending?: boolean } = {},
 ): string {
   const lines =
     client.lookFrames === true
@@ -109,6 +112,7 @@ export function sessionControlTeaching(
     ...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");
 }
@@ -137,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" }
 >;
 
 /**
@@ -154,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/messaging/provider-message-metadata.ts

@@ -30,9 +30,9 @@ import { CHANNEL_IDS } from "../channels/types.js";
  * The schema passes through what it does not name, so a provider carries its
  * own fields (Slack's file markers and timezone labels) on this same object
  * and validates them with its own schema. This is how `SourceMetadataSchema`
- * already carries `slackBotMentioned` and the email fields on the wire: one
- * object per row, no per-provider sub-envelope, and no second copy of
- * anything named here.
+ * carries `botMentioned` and the email fields on the wire: one object per
+ * row, no per-provider sub-envelope, and no second copy of anything named
+ * here.
  */
 
 const providerReactionMetadataSchema = z.object({

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/notifications/__tests__/copy-composer.test.ts

@@ -503,6 +503,76 @@ describe("composeFallbackCopy plugin schedule templates", () => {
   });
 });
 
+// ── activity.complete rendering ───────────────────────────────────────
+
+describe("activity.complete copy", () => {
+  function completeSignal(
+    contextPayload: Record<string, unknown>,
+  ): NotificationSignal {
+    return makeSignal({
+      sourceEventName: "activity.complete",
+      contextPayload,
+    });
+  }
+
+  test("a producer-authored title survives the fallback path", () => {
+    // The home feed reads the payload title first; the popup must say the
+    // same thing when the classifier was unreachable.
+    const copy = composeFallbackCopy(
+      completeSignal({
+        title: "Skill updated: Weekly Report Export",
+        summary: "Added the retry after an expired session.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.title).toBe("Skill updated: Weekly Report Export");
+    expect(copy.vellum?.body).toBe("Added the retry after an expired session.");
+  });
+
+  test("the pass-through's requestedTitle is honored when no title is set", () => {
+    const copy = composeFallbackCopy(
+      completeSignal({
+        requestedTitle: "Nightly export finished",
+        summary: "Wrote 12 files to the reports folder.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.title).toBe("Nightly export finished");
+  });
+
+  test("without an authored title the headline is the summary's first sentence", () => {
+    const copy = composeFallbackCopy(
+      completeSignal({
+        summary:
+          "Added the retry after an expired session. Dropped the login step.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.title).toBe(
+      "Added the retry after an expired session.",
+    );
+  });
+
+  test("an authored title the normalizer rejects falls back to the derived one", () => {
+    const copy = composeFallbackCopy(
+      completeSignal({
+        title: "Skill\nupdated",
+        summary: "Added the retry after an expired session.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.title).toBe(
+      "Added the retry after an expired session.",
+    );
+  });
+
+  test("neither a title nor a summary still says something happened", () => {
+    const copy = composeFallbackCopy(completeSignal({}), CHANNELS);
+    expect(copy.vellum?.title).toBe("Activity complete");
+    expect(copy.vellum?.body).toBe("An activity has completed");
+  });
+});
+
 // ── deriveTitle ───────────────────────────────────────────────────────
 
 describe("deriveTitle", () => {

package/src/notifications/copy-composer.ts

@@ -346,14 +346,22 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
 
   // Titled by what was done rather than by the kind of event: the summary's
   // first sentence is the outcome ("Finished the fuel-system diagnostic app"),
-  // which is what a reader scanning the bell wants to see. A summary without
-  // one still gets a title that says something happened.
+  // which is what a reader scanning the bell wants to see. A producer that
+  // names its subject in the payload keeps that name here, read in the same
+  // order the home feed reads it, so the headline is the same whether or not
+  // the classifier ran. A summary with neither still gets a title that says
+  // something happened.
   "activity.complete": (payload) => {
     const summary = nonEmpty(
       typeof payload.summary === "string" ? payload.summary : undefined,
     );
+    const authored = normalizeTitle(
+      readPayloadString(payload, "title") ??
+        readPayloadString(payload, "requestedTitle") ??
+        "",
+    );
     return {
-      title: summary ? deriveTitle(summary) : "Activity complete",
+      title: authored || (summary ? deriveTitle(summary) : "Activity complete"),
       body: summary ?? "An activity has completed",
     };
   },

package/src/persistence/conversation-plugin-facade.ts

@@ -1,3 +1,4 @@
+import type { ToolDefinition } from "../providers/types.js";
 import type {
   AddMessageOptions,
   ConversationRow,
@@ -52,6 +53,18 @@ export async function getMessages(
   return fn(conversationId);
 }
 
+/**
+ * The tool definitions the conversation's most recent live turn sent to the
+ * provider, or `null` when none has been recorded.
+ */
+export async function getConversationToolSurface(
+  conversationId: string,
+): Promise<ToolDefinition[] | null> {
+  const { getConversationToolSurface: fn } =
+    await import("./conversation-tool-surface.js");
+  return fn(conversationId);
+}
+
 /** Whether the conversation currently has a turn in flight. */
 export async function isConversationProcessing(id: string): Promise<boolean> {
   const { isConversationProcessing: fn } =

package/src/persistence/conversation-tool-surface.ts

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+
+import { eq, sql } from "drizzle-orm";
+
+import type { ToolDefinition } from "../providers/types.js";
+import { getDb } from "./db-connection.js";
+import { conversationToolSurfaces } from "./schema/index.js";
+
+/**
+ * Per-conversation record of the tool definitions the most recent live turn
+ * sent to the provider (`conversation_tool_surfaces`).
+ *
+ * The provider prompt cache is a byte-exact prefix match over
+ * `tools -> system -> messages`, so a background wake that forks a
+ * conversation can only reuse the source's cached prefix by sending the SAME
+ * tools array. Re-deriving the array on the fork cannot guarantee that: the
+ * fork may run in another process (a different tool registry), with no
+ * connected clients (different host-tool gates), or under a presence the
+ * persisted message stamps do not encode. Recording the resolved array and
+ * replaying it verbatim can.
+ */
+
+/** Content hash of the serialized tools array. */
+export function hashConversationToolSurface(
+  tools: readonly ToolDefinition[],
+): string {
+  return hashToolsJson(JSON.stringify(tools));
+}
+
+function hashToolsJson(toolsJson: string): string {
+  return createHash("sha256").update(toolsJson).digest("hex").slice(0, 32);
+}
+
+/**
+ * Persist `tools` as the conversation's current wire tool surface and return
+ * its hash. `knownHash` is the hash the caller last recorded for this
+ * conversation (undefined when it has recorded nothing this process
+ * lifetime): a matching hash skips the statement outright. Otherwise the
+ * upsert only rewrites a row whose stored hash differs, so a conversation
+ * reloaded from disk never rewrites an unchanged surface either.
+ */
+export function recordConversationToolSurface(
+  conversationId: string,
+  tools: readonly ToolDefinition[],
+  knownHash?: string,
+): string {
+  const toolsJson = JSON.stringify(tools);
+  const toolsHash = hashToolsJson(toolsJson);
+  if (knownHash === toolsHash) {
+    return toolsHash;
+  }
+  const updatedAt = Date.now();
+  getDb()
+    .insert(conversationToolSurfaces)
+    .values({ conversationId, toolsJson, toolsHash, updatedAt })
+    .onConflictDoUpdate({
+      target: conversationToolSurfaces.conversationId,
+      set: { toolsJson, toolsHash, updatedAt },
+      setWhere: sql`${conversationToolSurfaces.toolsHash} <> excluded.tools_hash`,
+    })
+    .run();
+  return toolsHash;
+}
+
+/**
+ * The tool definitions the conversation's most recent live turn sent, or
+ * `null` when no turn has recorded one (or the stored JSON is unreadable).
+ */
+export function getConversationToolSurface(
+  conversationId: string,
+): ToolDefinition[] | null {
+  const row = getDb()
+    .select({ toolsJson: conversationToolSurfaces.toolsJson })
+    .from(conversationToolSurfaces)
+    .where(eq(conversationToolSurfaces.conversationId, conversationId))
+    .get();
+  if (!row) {
+    return null;
+  }
+  try {
+    const parsed: unknown = JSON.parse(row.toolsJson);
+    return Array.isArray(parsed) ? (parsed as ToolDefinition[]) : null;
+  } catch {
+    return null;
+  }
+}

package/src/persistence/migrations/378-create-conversation-tool-surfaces.test.ts

@@ -0,0 +1,78 @@
+import { Database } from "bun:sqlite";
+import { describe, expect, test } from "bun:test";
+
+import { drizzle } from "drizzle-orm/bun-sqlite";
+
+import * as schema from "../schema.js";
+import { migrateCreateConversationToolSurfaces } from "./378-create-conversation-tool-surfaces.js";
+
+function createTestDb() {
+  const sqlite = new Database(":memory:");
+  sqlite.run("PRAGMA foreign_keys = ON");
+  // Only the parent table the FK points at.
+  sqlite.run(/*sql*/ `CREATE TABLE conversations (id TEXT PRIMARY KEY)`);
+  return { sqlite, db: drizzle(sqlite, { schema }) };
+}
+
+function tableDdl(sqlite: Database): string | undefined {
+  const row = sqlite
+    .query(
+      `SELECT sql FROM sqlite_master WHERE type='table' AND name='conversation_tool_surfaces'`,
+    )
+    .get() as { sql: string } | null;
+  return row?.sql;
+}
+
+function insertSurface(sqlite: Database, conversationId: string): void {
+  sqlite
+    .query(
+      /*sql*/ `INSERT INTO conversation_tool_surfaces (conversation_id, tools_json, tools_hash, updated_at) VALUES (?, ?, ?, ?)`,
+    )
+    .run(conversationId, "[]", "hash", 1);
+}
+
+function surfaceCount(sqlite: Database): number {
+  const row = sqlite
+    .query(`SELECT COUNT(*) AS n FROM conversation_tool_surfaces`)
+    .get() as { n: number };
+  return row.n;
+}
+
+describe("migration 378: conversation_tool_surfaces", () => {
+  test("creates the table keyed by conversation with a cascading FK", () => {
+    const { sqlite, db } = createTestDb();
+    expect(tableDdl(sqlite)).toBeUndefined();
+
+    migrateCreateConversationToolSurfaces(db);
+
+    const ddl = tableDdl(sqlite);
+    expect(ddl).toContain("conversation_id TEXT PRIMARY KEY");
+    expect(ddl).toContain("REFERENCES conversations(id) ON DELETE CASCADE");
+    expect(ddl).toContain("tools_json TEXT NOT NULL");
+    expect(ddl).toContain("tools_hash TEXT NOT NULL");
+    expect(ddl).toContain("updated_at INTEGER NOT NULL");
+  });
+
+  test("deleting a conversation cascades to its surface row", () => {
+    const { sqlite, db } = createTestDb();
+    migrateCreateConversationToolSurfaces(db);
+    sqlite.query(`INSERT INTO conversations (id) VALUES (?)`).run("conv-1");
+    insertSurface(sqlite, "conv-1");
+    expect(surfaceCount(sqlite)).toBe(1);
+
+    sqlite.query(`DELETE FROM conversations WHERE id = ?`).run("conv-1");
+
+    expect(surfaceCount(sqlite)).toBe(0);
+  });
+
+  test("is idempotent: a second run keeps the table and its rows", () => {
+    const { sqlite, db } = createTestDb();
+    migrateCreateConversationToolSurfaces(db);
+    sqlite.query(`INSERT INTO conversations (id) VALUES (?)`).run("conv-1");
+    insertSurface(sqlite, "conv-1");
+
+    expect(() => migrateCreateConversationToolSurfaces(db)).not.toThrow();
+
+    expect(surfaceCount(sqlite)).toBe(1);
+  });
+});

package/src/persistence/migrations/378-create-conversation-tool-surfaces.ts

@@ -0,0 +1,29 @@
+import type { DrizzleDb } from "../db-connection.js";
+
+const TABLE = "conversation_tool_surfaces";
+
+/**
+ * Create `conversation_tool_surfaces`: one row per conversation holding the
+ * tool definitions its most recent live turn sent to the provider, keyed by
+ * conversation with a content hash so an unchanged surface is never rewritten.
+ *
+ * Its own table rather than a column on `conversations` because the payload
+ * is a JSON array of every tool definition (tens of kilobytes) that only fork
+ * wakes read, while `conversations` rows are read whole on every hot path.
+ * The row cascades with its conversation, so a deleted conversation leaves
+ * no surface behind.
+ *
+ * Idempotent via IF NOT EXISTS.
+ */
+export function migrateCreateConversationToolSurfaces(
+  database: DrizzleDb,
+): void {
+  database.run(
+    `CREATE TABLE IF NOT EXISTS ${TABLE} (
+       conversation_id TEXT PRIMARY KEY REFERENCES conversations(id) ON DELETE CASCADE,
+       tools_json TEXT NOT NULL,
+       tools_hash TEXT NOT NULL,
+       updated_at INTEGER NOT NULL
+     )`,
+  );
+}

package/src/persistence/schema/conversation-tool-surfaces.ts

@@ -0,0 +1,22 @@
+import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+
+import { conversations } from "./conversations.js";
+
+/**
+ * The tool definitions a conversation's most recent live turn sent to the
+ * provider, serialized exactly as resolved. Written by the per-turn tool
+ * resolver when the array changes; read by fork wakes that replay it so their
+ * provider prompt-cache prefix matches the source's live turns. Cascades with
+ * its conversation.
+ */
+export const conversationToolSurfaces = sqliteTable(
+  "conversation_tool_surfaces",
+  {
+    conversationId: text("conversation_id")
+      .primaryKey()
+      .references(() => conversations.id, { onDelete: "cascade" }),
+    toolsJson: text("tools_json").notNull(),
+    toolsHash: text("tools_hash").notNull(),
+    updatedAt: integer("updated_at").notNull(),
+  },
+);

package/src/persistence/schema/index.ts

@@ -5,6 +5,7 @@ export * from "./calls.js";
 export * from "./contacts.js";
 export * from "./conversation-groups.js";
 export * from "./conversation-starters.js";
+export * from "./conversation-tool-surfaces.js";
 export * from "./conversations.js";
 export * from "./documents.js";
 export * from "./guardian.js";

package/src/persistence/steps.ts

@@ -485,6 +485,7 @@ import { migrateChannelInboundMessageIdIndex } from "./migrations/374-channel-in
 import { migrateCreateChannelOutboundPosts } from "./migrations/375-create-channel-outbound-posts.js";
 import { migrateNotificationDeliveriesCanonicalMessageId } from "./migrations/376-notification-deliveries-canonical-message-id.js";
 import { migrateAddSubagentBudgetStopReason } from "./migrations/377-add-subagent-budget-stop-reason.js";
+import { migrateCreateConversationToolSurfaces } from "./migrations/378-create-conversation-tool-surfaces.js";
 import type { MigrationStep } from "./migrations/run-migrations.js";
 
 export const migrationSteps: MigrationStep[] = [
@@ -1611,4 +1612,5 @@ export const migrationSteps: MigrationStep[] = [
     // this as a no-op.
     dependsOn: ["migrateCreateSubagentsTable"],
   },
+  migrateCreateConversationToolSurfaces,
 ];

package/src/plugin-api/conversation-turn.ts

@@ -284,13 +284,20 @@ export async function runConversationTurn(
   const { resolveChannelCapabilities } =
     await import("../daemon/conversation-runtime-assembly.js");
 
-  // Plugin-driven turns run as the guardian: plugins are installed by the
-  // guardian, so their conversations inherit guardian trust. This lets the
-  // existing non-interactive auto-approve machinery handle tool permissions
-  // (the conversation is already non-interactive via `isInteractive: false`
-  // below) without requiring a client to approve prompts.
+  // Channel-addressed turns are inbound: the gateway classifies the sender
+  // and the turn runs only if that actor clears the channel admission floor.
+  // Internal plugin jobs (no channel address) use guardian trust because they
+  // are assistant-owned work, not an external sender.
   const { INTERNAL_GUARDIAN_TRUST_CONTEXT } =
     await import("../daemon/trust-context.js");
+  const { resolvePluginChannelTurnTrust } =
+    await import("./plugin-channel-turn-trust.js");
+  const { prepareChannelInboundContent } =
+    await import("../runtime/routes/inbound-stages/inbound-content-prep.js");
+
+  const trustContext = options.channel
+    ? await resolvePluginChannelTurnTrust(options.channel)
+    : INTERNAL_GUARDIAN_TRUST_CONTEXT;
 
   // A channel address resolves through the same binding an inbound message
   // uses, so a turn addressed by chat lands in that chat's conversation
@@ -311,7 +318,7 @@ export async function runConversationTurn(
     ? !channelConversation.created
     : getConversation(conversationId) != null;
   const conversation = await getOrCreateConversation(conversationId, {
-    trustContext: INTERNAL_GUARDIAN_TRUST_CONTEXT,
+    trustContext,
     ...(options.conversationType
       ? { conversationType: options.conversationType }
       : {}),
@@ -336,10 +343,23 @@ export async function runConversationTurn(
 
   // Convert ContentBlock[] input to the text + attachments shape the
   // conversation's processMessage path expects.
-  const { text, attachments } = extractContentAndAttachments(
+  const { text: rawText, attachments } = extractContentAndAttachments(
     options.content,
     resolveMediaSourceData,
   );
+  const inboundContent = options.channel
+    ? prepareChannelInboundContent({
+        trimmedContent: rawText,
+        trustClass: trustContext.trustClass,
+        sourceChannel: options.channel.sourceChannel,
+        requesterIdentifier:
+          options.channel.username ??
+          options.channel.externalUserId ??
+          undefined,
+      })
+    : { content: rawText, displayContent: undefined };
+  const text = inboundContent.content;
+  const displayContent = inboundContent.displayContent;
 
   // The channel this turn speaks on. Runtime assembly reads the per-turn
   // context first and falls back to the conversation's `originChannel`, then
@@ -409,6 +429,8 @@ export async function runConversationTurn(
       requestId,
       isInteractive: false,
       metadata,
+      trustContext,
+      ...(displayContent ? { displayContent } : {}),
     });
     if (enqueueResult.rejected) {
       throw new Error(
@@ -432,6 +454,8 @@ export async function runConversationTurn(
     onEvent,
     isInteractive: false,
     metadata,
+    trustContext,
+    ...(displayContent ? { displayContent } : {}),
     ...(options.callSite ? { callSite: options.callSite } : {}),
   });
 

package/src/plugin-api/index.ts

@@ -286,6 +286,11 @@ export {
 // writes files under the workspace (e.g. its own `plugins/<name>/data/`
 // directory) resolves them against this instead of hardcoding a base path.
 export { getWorkspaceDir } from "../util/platform.js";
+// `String.prototype.slice` that never cuts a UTF-16 surrogate pair in half.
+// Any text a plugin truncates by character budget and hands to a model must
+// go through this: an orphaned half is invalid UTF-16 that strict provider
+// parsers reject.
+export { safeStringSlice } from "../util/unicode.js";
 // Declarative help for the top-level `assistant` CLI commands that have adopted
 // the static-help split. Plugins (e.g. the memory capability indexer) read this
 // to embed CLI command capabilities without importing the CLI action graph.
@@ -359,7 +364,8 @@ export {
   stringifyMessageContent,
 } from "../persistence/message-content.js";
 // Conversation history — reads and writes on the host conversation store
-// (rows, message history, processing state, disk-view paths) plus the lexical
+// (rows, message history, processing state, the recorded wire tool surface,
+// disk-view paths) plus the lexical
 // message-search surface. Every operation takes explicit parameters; nothing
 // is resolved from config. Async because the facade loads the DB store graph
 // lazily on first call.
@@ -371,6 +377,7 @@ export {
   getConversation,
   getConversationDirPath,
   getConversationProcessingStartedAt,
+  getConversationToolSurface,
   getMessages,
   hasLexicalTokens,
   isConversationProcessing,
@@ -438,6 +445,7 @@ export type {
   RunConversationTurnResult,
 } from "./conversation-turn.js";
 export { runConversationTurn } from "./conversation-turn.js";
+export { PluginTurnNotAdmittedError } from "./plugin-channel-turn-trust.js";
 // Live voice — drive a single client's real-time voice session (STT → agent
 // turn → TTS, with server-VAD turn-taking, pauses, and barge-in) over a
 // transport the plugin owns. The plugin brings only a `send` callback (e.g.