@vellumai/assistant 0.12.3 → 0.12.4-dev.202609231620.a15f321

package/src/plugins/defaults/memory/memory-retrospective-skill-card.ts

@@ -321,6 +321,11 @@ async function insertOrDeferSkillCard(
       metadata: { kind: SKILL_CARD_MESSAGE_KIND, automated: true },
       skipIndexing: true,
       clientMessageId: surfaceId,
+      // The card is what the pass learned about this conversation, not new
+      // activity in it, and a pass runs once the conversation has gone idle.
+      // That is exactly when the user has just marked it done, so a card that
+      // resurfaced would bounce fresh done chats back into the sidebar.
+      skipResurface: true,
     },
   );
   if (persisted.deduplicated) {

package/src/plugins/defaults/memory/skill-update-receipt-job.ts

@@ -0,0 +1,334 @@
+// ---------------------------------------------------------------------------
+// Memory retrospective: skill-update receipts.
+// ---------------------------------------------------------------------------
+//
+// A background pass can rewrite several managed skills within minutes. A
+// receipt collapses one such burst into one announcement: every rewrite is
+// appended to the one pending `skill_update_receipt` job
+// (`upsertSkillUpdateReceiptJob`), and this handler announces the burst once
+// it has settled, through `emitNotificationSignal`, the single entry point
+// every notification producer uses. The same shape as the skill card's
+// delivery job, keyed to a burst rather than to a run.
+//
+// Settled means every run that contributed an entry has finished (its fork
+// conversation is no longer processing, or is gone) and no entry has landed
+// for the quiet window. A burst that never goes quiet is announced at the
+// cap, measured from its earliest entry. Until then the handler re-upserts
+// the payload for a later check, the way the card defers until its run ends,
+// so no attempt counter accumulates.
+//
+// The pending-only match in the upsert is what makes a burst boundary
+// possible without a table of its own, and also what bounds it. The claimed
+// row's payload is frozen, so an entry landing during evaluation opens a
+// pending sibling; the handler checks for one right before announcing and,
+// if it finds one, merges its own entries into it and announces nothing,
+// leaving the sibling to carry the whole burst. Two windows stay open, and
+// both surface as a second bell row rather than a lost entry: an entry
+// landing between that check and the announcement's event row, and a
+// sibling claimed by another worker between the check and the merge, in
+// which case the merge opens a third row. Both are accepted.
+//
+// One announcement per row: the dedupe key is the row id, so a retry after a
+// crash past the event row meets the key and completes. A pipeline failure
+// before that is reported as retryable and the worker's own budget covers
+// it; a row that exhausts it loses its entries, as the per-update notice it
+// replaces would have.
+
+import {
+  getConversation,
+  isConversationProcessing,
+} from "@vellumai/plugin-api";
+
+import { emitNotificationSignal } from "../../../notifications/emit-signal.js";
+import {
+  hasPendingJobOfType,
+  type MemoryJob,
+  parseSkillUpdateReceiptPayload,
+  type SkillUpdateReceiptEntry,
+  type SkillUpdateReceiptJobPayload,
+  upsertSkillUpdateReceiptJob,
+} from "../../../persistence/jobs-store.js";
+import type { JobQueueResolution } from "../../types.js";
+import { getLogger } from "./logging.js";
+
+const log = getLogger("skill-update-receipt-job");
+
+/**
+ * How long a receipt stays open after its last entry before it is announced.
+ * Equal to the retrospective's default interval trigger, so runs a
+ * conversation's message count keeps triggering (at most every five minutes)
+ * chain into one receipt, while interval-driven runs of a slow conversation
+ * each get their own.
+ */
+export const SKILL_UPDATE_RECEIPT_QUIET_MS = 30 * 60 * 1000;
+
+/**
+ * The longest a receipt stays open, measured from its earliest entry. A
+ * burst that never goes quiet is announced at the cap and a later entry
+ * opens the next receipt.
+ */
+export const SKILL_UPDATE_RECEIPT_CAP_MS = 2 * 60 * 60 * 1000;
+
+/**
+ * How soon the handler looks again at a receipt whose contributing run is
+ * still live. The run's end is what it waits for, and a run is one wake, so a
+ * short cadence catches it without polling hard.
+ */
+export const SKILL_UPDATE_RECEIPT_LIVE_RUN_RECHECK_MS = 30_000;
+
+/**
+ * Record one rewrite on the open receipt and make sure a check is queued.
+ * Called by the scaffold tool after a background overwrite lands. Throws on
+ * a store failure; the caller logs it and lets the skill write stand.
+ */
+export function recordSkillUpdate(
+  entry: Omit<SkillUpdateReceiptEntry, "createdAt">,
+  now: number = Date.now(),
+): void {
+  upsertSkillUpdateReceiptJob(
+    {
+      firstEntryAt: now,
+      lastEntryAt: now,
+      entries: [{ ...entry, createdAt: now }],
+    },
+    now + SKILL_UPDATE_RECEIPT_QUIET_MS,
+  );
+}
+
+/** The dedupe key a receipt row is announced under. */
+export function skillUpdateReceiptDedupeKey(jobId: string): string {
+  return `skill-update-receipt:${jobId}`;
+}
+
+/**
+ * The `sourceContextId` a receipt is announced with. The home feed's "Go to
+ * Conversation" and the vellum delivery's body append both resolve it to a
+ * conversation, so a receipt whose rewrites all came from one conversation
+ * names it; one spanning several, or with a rewrite of unknown lineage,
+ * passes a sentinel that resolves to nothing, and the receipt's own entries
+ * carry the links.
+ */
+export function skillUpdateReceiptSourceContextId(
+  jobId: string,
+  entries: SkillUpdateReceiptEntry[],
+): string {
+  // An entry with no lineage counts as its own source: linking the whole
+  // receipt to the one known conversation would attribute that rewrite
+  // there too.
+  const sources = new Set(entries.map((entry) => entry.sourceConversationId));
+  const [only] = sources;
+  return sources.size === 1 && only ? only : `skill-update-receipt:${jobId}`;
+}
+
+/**
+ * The English fallback title and body, for a surface that renders the item
+ * as it arrived: a bundle without the receipt panel, a channel post, a
+ * banner. The web client derives its own title from the entries.
+ */
+export function composeSkillUpdateReceiptCopy(
+  entries: SkillUpdateReceiptEntry[],
+): { title: string; body: string } {
+  const skills = new Map<string, string>();
+  for (const entry of entries) {
+    skills.set(entry.skillId, entry.name);
+  }
+  const names = [...skills.values()];
+  const title =
+    names.length === 1
+      ? `Skill updated: ${names[0]}`
+      : `${names.length} skills updated`;
+  const body = entries
+    .map((entry) => `- ${entry.name}: ${entry.changeSummary}`)
+    .join("\n");
+  return { title, body };
+}
+
+export type SkillUpdateReceiptSealDecision =
+  | { seal: "quiet" | "cap" }
+  | { seal: null; nextCheckAt: number };
+
+/**
+ * Whether the receipt is due to be announced, and if not, when to look
+ * again. Pure, so the boundary can be asserted without a clock or a queue.
+ */
+export function decideSkillUpdateReceiptSeal(args: {
+  receipt: Pick<SkillUpdateReceiptJobPayload, "firstEntryAt" | "lastEntryAt">;
+  anyRunLive: boolean;
+  now: number;
+}): SkillUpdateReceiptSealDecision {
+  const capAt = args.receipt.firstEntryAt + SKILL_UPDATE_RECEIPT_CAP_MS;
+  if (args.now >= capAt) {
+    return { seal: "cap" };
+  }
+  const quietAt = args.receipt.lastEntryAt + SKILL_UPDATE_RECEIPT_QUIET_MS;
+  if (args.anyRunLive) {
+    return {
+      seal: null,
+      nextCheckAt: Math.min(
+        args.now + SKILL_UPDATE_RECEIPT_LIVE_RUN_RECHECK_MS,
+        capAt,
+      ),
+    };
+  }
+  if (args.now >= quietAt) {
+    return { seal: "quiet" };
+  }
+  return { seal: null, nextCheckAt: Math.min(quietAt, capAt) };
+}
+
+/**
+ * Whether the run that produced an entry has finished. A fork conversation
+ * that no longer exists counts as finished: superseded-fork GC deletes the
+ * row, and a run cannot be processing without one. Same reading as the
+ * skill card's gate.
+ */
+async function isRunFinished(runConversationId: string): Promise<boolean> {
+  const conversation = await getConversation(runConversationId);
+  if (!conversation) {
+    return true;
+  }
+  return !(await isConversationProcessing(runConversationId));
+}
+
+/**
+ * The entries whose source conversation still exists. An entry with no
+ * lineage has nothing to check and stays.
+ */
+async function dropEntriesOfDeletedSources(
+  entries: SkillUpdateReceiptEntry[],
+): Promise<SkillUpdateReceiptEntry[]> {
+  const sources = new Set(
+    entries.flatMap((entry) =>
+      entry.sourceConversationId ? [entry.sourceConversationId] : [],
+    ),
+  );
+  const gone = new Set<string>();
+  for (const source of sources) {
+    if (!(await getConversation(source))) {
+      gone.add(source);
+    }
+  }
+  return entries.filter(
+    (entry) =>
+      !entry.sourceConversationId || !gone.has(entry.sourceConversationId),
+  );
+}
+
+/**
+ * Job handler for `skill_update_receipt` (registered in `job-handlers.ts`).
+ * A malformed payload is dropped with a warning. A pipeline failure returns
+ * `retryable` so the worker's budget covers it.
+ */
+export async function skillUpdateReceiptJob(
+  job: MemoryJob,
+): Promise<JobQueueResolution | undefined> {
+  const payload = parseSkillUpdateReceiptPayload(job.payload);
+  if (!payload || payload.entries.length === 0) {
+    log.warn(
+      { jobId: job.id },
+      "skill-update receipt: dropping job with malformed or empty payload",
+    );
+    return undefined;
+  }
+
+  const runIds = [
+    ...new Set(payload.entries.map((entry) => entry.runConversationId)),
+  ];
+  let anyRunLive = false;
+  for (const runId of runIds) {
+    if (!(await isRunFinished(runId))) {
+      anyRunLive = true;
+      break;
+    }
+  }
+  const decision = decideSkillUpdateReceiptSeal({
+    receipt: payload,
+    anyRunLive,
+    now: Date.now(),
+  });
+  if (decision.seal === null) {
+    // Not settled. The claimed row completes and the payload moves to a
+    // pending row for the next check, merging with any entries that landed
+    // meanwhile.
+    upsertSkillUpdateReceiptJob(payload, decision.nextCheckAt);
+    return undefined;
+  }
+
+  if (hasPendingJobOfType("skill_update_receipt")) {
+    // An entry landed while this row was being evaluated and opened a
+    // sibling. The sibling carries the burst: merge into it and announce
+    // nothing, so the two rows do not become two bell rows.
+    upsertSkillUpdateReceiptJob(payload, Date.now());
+    log.info(
+      { jobId: job.id, entryCount: payload.entries.length },
+      "skill-update receipt: merged into the sibling that opened during evaluation",
+    );
+    return undefined;
+  }
+
+  // The claimed payload is a snapshot: a source conversation deleted while
+  // this row was evaluated was purged from pending rows only. Announce
+  // nothing distilled from a conversation that is gone.
+  const entries = await dropEntriesOfDeletedSources(payload.entries);
+  if (entries.length === 0) {
+    log.info(
+      { jobId: job.id },
+      "skill-update receipt: every entry's source conversation was deleted; nothing to announce",
+    );
+    return undefined;
+  }
+
+  const { title, body } = composeSkillUpdateReceiptCopy(entries);
+  const skillIds = new Set(entries.map((entry) => entry.skillId));
+  const [onlySkillId] = skillIds;
+  const result = await emitNotificationSignal({
+    // A tool's work reported after the fact, not the scheduler's:
+    // `home-feed-side-effect` derives `fromAssistant` from the channel.
+    sourceChannel: "assistant_tool",
+    sourceContextId: skillUpdateReceiptSourceContextId(job.id, entries),
+    sourceEventName: "activity.complete",
+    dedupeKey: skillUpdateReceiptDedupeKey(job.id),
+    contextPayload: {
+      summary: body,
+      title,
+      body,
+      // The typed list the receipt panel renders; the feed maps it onto the
+      // item and strips it from the free-form metadata.
+      updates: entries.map((entry) => ({
+        skillId: entry.skillId,
+        name: entry.name,
+        summary: entry.changeSummary,
+        ...(entry.sourceConversationId
+          ? { conversationId: entry.sourceConversationId }
+          : {}),
+      })),
+      // A receipt naming one skill links to it from the detail's footer the
+      // way a single-skill notification does.
+      ...(skillIds.size === 1 && onlySkillId ? { skillId: onlySkillId } : {}),
+    },
+    attentionHints: {
+      requiresAction: false,
+      urgency: "low",
+      isAsyncBackground: true,
+      visibleInSourceNow: false,
+    },
+  });
+  if (result.pipelineFailed) {
+    return {
+      queueResolution: "retryable",
+      errorMessage: `skill-update receipt announcement failed: ${result.reason}`,
+    };
+  }
+  log.info(
+    {
+      jobId: job.id,
+      sealedBy: decision.seal,
+      entryCount: entries.length,
+      skillCount: skillIds.size,
+      deduplicated: result.deduplicated,
+      dispatched: result.dispatched,
+    },
+    "skill-update receipt announced",
+  );
+  return undefined;
+}

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

@@ -34,7 +34,7 @@ export const DEFAULT_CARD_CHARS = 500;
  * only, so a missing product is not evidence it is unsupported.
  */
 export const SKILLS_INJECTION_CATALOG_HINT =
-  "Injected skills are only ones currently in the workspace. Run `assistant plugins search <name>` and `assistant skills search <name>` before concluding a given integration or skill is unsupported";
+  "These skill cards describe availability, not tool instructions. When skill_load is available, use it to load a skill's current instructions and input schemas before calling its tools; follow those schemas over remembered arguments. Injected skills are only ones currently in the workspace. Run `assistant plugins search <name>` and `assistant skills search <name>` before concluding a given integration or skill is unsupported";
 
 /**
  * Render the prose-style capability statement embedded into the unified

package/src/plugins/defaults/memory/tools.test.ts

@@ -451,6 +451,23 @@ describe("rememberTool definition", () => {
       finish_turn: { type: "boolean" },
     });
   });
+
+  test("says later capture is conditional and never covers scheduled work", () => {
+    const description = rememberTool.description;
+    expect(description).toContain("not guaranteed");
+    expect(description).toContain("never runs over scheduled work");
+    expect(description).toContain("save it now");
+    // A pass that reviews every conversation on a cadence is not what runs:
+    // the enqueue gate skips scheduled conversations.
+    expect(description).not.toContain("after each message-count");
+    expect(description).not.toContain("saves what you didn't capture");
+    // The provider reads the definition after JSON serialization, so the
+    // contract has to survive that round trip unchanged.
+    const serialized = z
+      .object({ description: z.string() })
+      .parse(JSON.parse(JSON.stringify(rememberTool)));
+    expect(serialized.description).toBe(description);
+  });
 });
 
 describe("rememberTool definition — page-hint guidance gating", () => {

package/src/plugins/defaults/memory/v3/__tests__/render-injection.test.ts

@@ -31,6 +31,9 @@ describe("renderInjectionBlockInner", () => {
     expect(inner).toContain("assistant plugins search <name>");
     expect(inner).toContain("assistant skills search <name>");
     expect(inner).toContain("currently in the workspace");
+    expect(inner).toContain("When skill_load is available, use it");
+    expect(inner).toContain("before calling its tools");
+    expect(inner).toContain("over remembered arguments");
     expect(inner.indexOf("# Skills")).toBeLessThan(inner.indexOf("# Skill:"));
     expect(inner.startsWith(`${V3_INJECTION_HEADER}\n\n# Skills\n`)).toBe(true);
   });

package/src/providers/__tests__/connection-model-compat.test.ts

@@ -57,6 +57,8 @@ describe("isConnectionCompatibleWithModel", () => {
   test("oauth_subscription connection is compatible with a Codex model", () => {
     const conn = { auth: oauthAuth };
     expect(isConnectionCompatibleWithModel(conn, "gpt-6-astra")).toBe(true);
+    expect(isConnectionCompatibleWithModel(conn, "gpt-6-sol")).toBe(true);
+    expect(isConnectionCompatibleWithModel(conn, "gpt-6-luna")).toBe(true);
     expect(isConnectionCompatibleWithModel(conn, "gpt-5.6-sol")).toBe(true);
     expect(isConnectionCompatibleWithModel(conn, "gpt-5.6-terra")).toBe(true);
     expect(isConnectionCompatibleWithModel(conn, "gpt-5.6-luna")).toBe(true);

package/src/providers/__tests__/search-provider-catalog.test.ts

@@ -104,4 +104,12 @@ describe("search-provider-catalog", () => {
     expect(tinyfish?.defaultApiBase).toBe("https://api.search.tinyfish.ai");
     expect(tinyfish?.envVar).toBe("TINYFISH_API_KEY");
   });
+
+  test("Exa is a keyed BYOK provider without a custom API base", () => {
+    const exa = getSearchProvider("exa");
+    expect(exa?.kind).toBe("byok");
+    expect(exa?.keyless).toBeUndefined();
+    expect(exa?.supportsApiBase).toBeUndefined();
+    expect(exa?.envVar).toBe("EXA_API_KEY");
+  });
 });

package/src/providers/anthropic/client.ts

@@ -1004,7 +1004,7 @@ export class AnthropicProvider implements Provider {
       const isHaiku = effectiveModel.includes("haiku");
       // Effort support is per-model: Haiku and Sonnet 4.5 reject the param (see isEffortSupported).
       const supportsEffort = isEffortSupported(effectiveModel);
-      // opus-4-7 / opus-4-8 / opus-5 and sonnet-5 reject `temperature`,
+      // opus-4-7 / opus-4-8 / opus-5 / opus-5-5 and sonnet-5 reject `temperature`,
       // `top_p`, and `top_k` with a 400 "`temperature`/`top_p` is deprecated
       // for this model" — model-wide, not effort-conditional (verified
       // 2026-06-23). opus-4-6 / sonnet-4-6 / haiku-4-5 still accept them.
@@ -1016,7 +1016,7 @@ export class AnthropicProvider implements Provider {
       // suffix is what matches.
       const deprecatesSamplingParams =
         /claude-opus-4-[78]\b/.test(effectiveModel) ||
-        /claude-opus-5\b/.test(effectiveModel) ||
+        /claude-opus-5(-5)?\b/.test(effectiveModel) ||
         /claude-sonnet-5\b/.test(effectiveModel) ||
         /claude-fable-/.test(effectiveModel);
       const mergedOutputConfig = {

package/src/providers/gemini/client.ts

@@ -16,6 +16,10 @@ import {
 } from "../content-block-size.js";
 import { fileBlockToProviderText } from "../file-block-text.js";
 import { unsignedThoughtSignatureFallback } from "../gemini-thought-signature.js";
+import {
+  isMalformedToolCallFinishReason,
+  malformedToolCallError,
+} from "../malformed-tool-call.js";
 import { base64Source, resolveMediaReferences } from "../media-resolve.js";
 import { PROVIDER_CATALOG } from "../model-catalog.js";
 import { recordProviderRequestDiagnostics } from "../request-diagnostics.js";
@@ -577,6 +581,18 @@ export class GeminiProvider implements Provider {
         cleanupTimeout();
       }
 
+      if (isMalformedToolCallFinishReason(finishReason)) {
+        log.warn(
+          {
+            model: responseModel,
+            finishReason,
+            streamedTextLength: fullText.length,
+          },
+          "Gemini response ended on a malformed tool call",
+        );
+        throw malformedToolCallError("gemini", finishReason);
+      }
+
       // Build content blocks
       const content: ContentBlock[] = [];
       if (fullText) {
@@ -649,7 +665,7 @@ export class GeminiProvider implements Provider {
           error.status,
           // Skip reason on caller-abort: abortReason already carries the intent
           // and short-circuits classification/retry (mirrors the Anthropic client).
-        abortReason
+          abortReason
             ? { abortReason, rawRequest: inspectableRequest }
             : {
                 reason: deriveGeminiReason(error),

package/src/providers/inference/auth.ts

@@ -176,6 +176,31 @@ export type ConnectionModel = z.infer<typeof ConnectionModelSchema>;
  * `models` list (openai-compatible endpoints have no fixed upstream, so the
  * user must supply both).
  */
+/**
+ * An openai-compatible connection whose endpoint is opencode.ai is an
+ * OpenCode connection: zen/go rejects requests without the session headers
+ * only the opencode adapter and probe send, so the generic adapter can never
+ * dispatch against it. Applied on create so the row is stored as provider
+ * "opencode" and every provider-keyed path treats it as one.
+ */
+export function normalizeConnectionProvider(
+  provider: string,
+  baseUrl: unknown,
+): string {
+  if (provider !== "openai-compatible" || typeof baseUrl !== "string") {
+    return provider;
+  }
+  let host: string;
+  try {
+    host = new URL(baseUrl).hostname.toLowerCase();
+  } catch {
+    return provider;
+  }
+  return host === "opencode.ai" || host.endsWith(".opencode.ai")
+    ? "opencode"
+    : provider;
+}
+
 export const PROVIDERS_REQUIRING_BASE_URL_AND_MODELS: ReadonlySet<string> =
   new Set(["openai-compatible"]);
 

package/src/providers/jev/ask.test.ts

@@ -0,0 +1,66 @@
+import { afterAll, describe, expect, mock, test } from "bun:test";
+
+import type { Provider } from "../types.js";
+
+let configured: {
+  provider: Provider;
+  configuredProviderName: string;
+  entryRouted: boolean;
+} | null = null;
+
+const actual = await import("../provider-send-message.js");
+mock.module("../provider-send-message.js", () => ({
+  ...actual,
+  resolveConfiguredProvider: async () => configured,
+}));
+
+const { resolveTypesafeProvider } = await import("./ask.js");
+
+afterAll(() => {
+  mock.restore();
+});
+
+function stub(name: string): Provider {
+  return {
+    name,
+    defaultModel: "jev-latest",
+    sendMessage: async () => {
+      throw new Error("not dispatched in this test");
+    },
+  } as unknown as Provider;
+}
+
+describe("resolveTypesafeProvider", () => {
+  test("a BYOK TypeSafe profile resolves", async () => {
+    configured = {
+      provider: stub("typesafe"),
+      configuredProviderName: "typesafe",
+      entryRouted: false,
+    };
+    expect((await resolveTypesafeProvider("voiceEscalationJudge"))?.name).toBe(
+      "typesafe",
+    );
+  });
+
+  test("a managed Jev profile resolves although it is configured as vellum", async () => {
+    configured = {
+      provider: stub("typesafe"),
+      configuredProviderName: "vellum",
+      entryRouted: false,
+    };
+    expect((await resolveTypesafeProvider("voiceEscalationJudge"))?.name).toBe(
+      "typesafe",
+    );
+  });
+
+  test("any other dispatched provider is unavailable", async () => {
+    configured = {
+      provider: stub("anthropic"),
+      configuredProviderName: "vellum",
+      entryRouted: false,
+    };
+    expect(await resolveTypesafeProvider("voiceEscalationJudge")).toBeNull();
+    configured = null;
+    expect(await resolveTypesafeProvider("voiceEscalationJudge")).toBeNull();
+  });
+});