@vellumai/assistant 0.11.3 → 0.11.4-staging.1

package/src/cli/commands/memory/memory-v3.ts

@@ -25,6 +25,7 @@ import type {
   MemoryEvalTallyResult,
 } from "../../../plugins/defaults/memory/src/memory-eval-routes.js";
 import type {
+  GateStatsResponse,
   MemoryV3BackfillSectionsResult,
   MemoryV3RebuildIndexResult,
 } from "../../../plugins/defaults/memory/src/memory-v3-routes.js";
@@ -52,6 +53,36 @@ function collectRepeatable(value: string, acc: string[]): string[] {
   return [...acc, value];
 }
 
+/** Render gate-stats as a human-readable table. */
+function formatGateStats(r: GateStatsResponse): string {
+  const lines: string[] = [
+    `Gate-stats (last ${r.lookbackDays} day${r.lookbackDays === 1 ? "" : "s"}, ${r.totalRuns} run${r.totalRuns === 1 ? "" : "s"})`,
+    "",
+    `Bucket     Total  Scored  Passed  ScoredPassRate  Top reasons`,
+  ];
+  for (const b of r.buckets) {
+    const rate =
+      b.scoredPassRate !== null
+        ? `${(b.scoredPassRate * 100).toFixed(1)}%`
+        : "n/a";
+    const topReasons = Object.entries(b.reasons)
+      .sort(([, a], [, bv]) => (bv as number) - (a as number))
+      .slice(0, 3)
+      .map(([k, v]) => `${k}: ${v}`)
+      .join(", ");
+    lines.push(
+      `${b.pageCountRange.padEnd(10)} ${String(b.total).padStart(5)}  ${String(b.scored).padStart(6)}  ${String(b.passed).padStart(6)}  ${rate.padStart(14)}  ${topReasons}`,
+    );
+  }
+  if (r.unknownPageCount.total > 0) {
+    lines.push("");
+    lines.push(
+      `Unknown page count: ${r.unknownPageCount.total} total, ${r.unknownPageCount.passed} passed`,
+    );
+  }
+  return lines.join("\n");
+}
+
 /**
  * Read the `turn` ids from a prior run's `key.json` or `packets.json` (both are
  * arrays of objects carrying a `turn` field). Used to pin `--turns-file` so a
@@ -271,4 +302,37 @@ export function registerMemoryV3Command(memory: Command): void {
       log.info(formatTally(payload));
     },
   );
+
+  // ── gate-stats ────────────────────────────────────────────────────────
+  // Reads the telemetry DB directly — no daemon required.
+
+  subcommand(v3, "gate-stats").action(
+    async (opts: { lookbackDays: string; json?: boolean }) => {
+      const lookbackDays = Number(opts.lookbackDays);
+      const [{ handleMemoryV3GateStats }, { getTelemetrySqlite }] =
+        await Promise.all([
+          import("../../../plugins/defaults/memory/src/memory-v3-routes.js"),
+          import("../../../persistence/db-connection.js"),
+        ]);
+      let payload;
+      try {
+        payload = handleMemoryV3GateStats(
+          Number.isFinite(lookbackDays) ? lookbackDays : 30,
+          getTelemetrySqlite(),
+        );
+      } catch (err) {
+        log.error(
+          "Failed to read gate stats: %s",
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exitCode = 1;
+        return;
+      }
+      if (opts.json === true) {
+        log.info(JSON.stringify(payload, null, 2));
+        return;
+      }
+      log.info(formatGateStats(payload));
+    },
+  );
 }

package/src/cli/commands/stt.help.ts

@@ -1,7 +1,31 @@
-/** Declarative help for the `assistant stt` command. */
+/**
+ * Declarative help for the `assistant stt` command.
+ *
+ * The advertised provider list is derived from the STT provider catalog, the
+ * single source of truth for which providers exist and which boundaries they
+ * serve, so the help cannot drift from what the daemon actually accepts.
+ */
 
+// provider-catalog is an execution-free data leaf (a literal map behind
+// type-only imports, no adapter or credential graph), consumed synchronously
+// to derive this module's constant. Pure data from pure data, so a lazy
+// `import()` has nothing to defer.
+// eslint-disable-next-line cli/no-daemon-internals
+import {
+  listProviderIds,
+  supportsBoundary,
+} from "../../providers/speech-to-text/provider-catalog.js";
 import type { CliCommandHelp } from "../lib/cli-command-help.js";
 
+/**
+ * `stt transcribe` runs the `daemon-batch` boundary, so streaming-only
+ * providers are omitted: naming one would advertise a configuration that
+ * fails on every file.
+ */
+const batchProviders = listProviderIds()
+  .filter((id) => supportsBoundary(id, "daemon-batch"))
+  .join(", ");
+
 export const sttHelp: CliCommandHelp = {
   name: "stt",
   description: "Speech-to-text operations",
@@ -11,7 +35,8 @@ audio and video files. The provider is set via:
 
   $ assistant config set services.stt.provider <provider>
 
-Supported providers: openai-whisper, deepgram, google-gemini, xai.
+Supported providers: ${batchProviders}.
+Streaming-only providers serve live speech and cannot transcribe files.
 
 Examples:
   $ assistant stt transcribe --file /path/to/meeting.wav

package/src/cli/lib/__tests__/upgrade-plugin.test.ts

@@ -32,6 +32,7 @@ import { computeFingerprint } from "../plugin-fingerprint.js";
 import { PluginNotInstalledError } from "../uninstall-plugin.js";
 import {
   PluginMergeBaselineError,
+  PluginNotCuratedError,
   PluginNotUpgradableError,
   upgradePlugin,
 } from "../upgrade-plugin.js";
@@ -574,6 +575,44 @@ describe("upgradePlugin — direct GitHub-URL installs", () => {
     expect(calls[0]?.[0]).toBe("ls-remote");
   });
 
+  test("marketplaceOnly refuses the direct path instead of following the ref", async () => {
+    // GIVEN a direct install tracking `main` at SHA_A, absent from the
+    // marketplace, whose branch has advanced to SHA_B
+    installCopy(pluginsDir, "level-up", { commit: SHA_A, ref: "main" });
+    const fetch = makeFetch({ manifest: undefined });
+    const calls: string[][] = [];
+    const runGit = directGitRunner({ main: SHA_B }, SHA_B, { calls });
+
+    // WHEN a caller that only accepts a curated pin asks for the upgrade
+    const upgrade = upgradePlugin(
+      { name: "level-up", marketplaceOnly: true },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN it is refused, and the mutable ref is never even resolved
+    await expect(upgrade).rejects.toThrow(PluginNotCuratedError);
+    expect(calls).toEqual([]);
+    // AND the install stays exactly where it was
+    expect(sidecarCommit(pluginsDir, "level-up")).toBe(SHA_A);
+  });
+
+  test("marketplaceOnly still upgrades a plugin the catalog claims", async () => {
+    // GIVEN an install the marketplace pins at SHA_B
+    installCopy(pluginsDir, "level-up", { commit: SHA_A });
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    const runGit = fakeGitRunner(SHA_B);
+
+    // WHEN the same curated-only caller asks for the upgrade
+    const result = await upgradePlugin(
+      { name: "level-up", marketplaceOnly: true },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN the flag is inert: the curated pin is taken as usual
+    expect(result.outcome).toBe("upgraded");
+    expect(result.toCommit).toBe(SHA_B);
+  });
+
   test("is a no-op when the recorded branch still points at the installed commit", async () => {
     // GIVEN a direct install tracking `main` at SHA_A
     installCopy(pluginsDir, "level-up", { commit: SHA_A, ref: "main" });

package/src/cli/lib/bundled-marketplace.json

@@ -422,6 +422,19 @@
       "license": "MIT",
       "icon": "✈️"
     },
+    {
+      "name": "unabyss",
+      "source": {
+        "source": "github",
+        "repo": "Unabyss/unabyss-vellum",
+        "ref": "9f0bb0753dad09dace8578e242961bc2da912af3"
+      },
+      "description": "Personal and company context from Unabyss, available to your agent through the Unabyss MCP server.",
+      "category": "memory",
+      "homepage": "https://unabyss.com",
+      "license": "MIT",
+      "icon": "🌊"
+    },
     {
       "name": "vellum-client-qa",
       "source": {

package/src/cli/lib/upgrade-plugin.ts

@@ -17,6 +17,11 @@
  * verbatim, with no curated adapter overlay, exactly as the original untrusted
  * install was (see {@link directUpgrade}).
  *
+ * Because that target is a mutable ref, taking it means running whatever
+ * upstream pushed since, which is a choice only a human should make. A caller
+ * with nobody in the loop passes `marketplaceOnly` to rule it out: the direct
+ * path then throws {@link PluginNotCuratedError} instead of advancing.
+ *
  * This is deliberately a distinct operation from install: `install` is
  * first-time materialization (and errors on an existing install unless
  * `--force` is passed), whereas `upgrade` moves an existing install forward.
@@ -114,6 +119,20 @@ export interface UpgradePluginOptions {
    * {@link DEFAULT_PLUGIN_UPGRADE_STRATEGY}.
    */
   readonly strategy?: PluginUpgradeStrategy;
+  /**
+   * Refuse to advance an install the marketplace does not claim, instead of
+   * falling back to {@link directUpgrade}.
+   *
+   * A direct install's upgrade target is a mutable upstream ref, so taking it
+   * means fetching and executing whatever was pushed since. Callers with
+   * nobody in the loop (the unattended auto-update sweep) set this so that
+   * outcome is impossible for them, and it is enforced here rather than by the
+   * caller's own pre-check: the catalog is fetched again inside this call, so
+   * an entry that disappears in between would otherwise silently reroute a
+   * curated upgrade into a direct one. Defaults to false, which is what an
+   * interactive `assistant plugins upgrade` wants.
+   */
+  readonly marketplaceOnly?: boolean;
 }
 
 /** Dependencies injected by the caller. */
@@ -208,6 +227,23 @@ export class PluginNotUpgradableError extends Error {
   }
 }
 
+/**
+ * A `marketplaceOnly` upgrade was requested for an install the marketplace does
+ * not claim, so the only revision available is a mutable upstream ref the
+ * caller refuses to take.
+ *
+ * Distinct from {@link PluginNotUpgradableError}: the install *can* be
+ * upgraded, just not without a human choosing to accept unreviewed code.
+ */
+export class PluginNotCuratedError extends Error {
+  constructor(readonly pluginName: string) {
+    super(
+      `Plugin "${pluginName}" cannot be upgraded automatically: it has no marketplace entry, so its only upgrade target is a mutable upstream ref. Run 'assistant plugins upgrade ${pluginName}' to move it deliberately.`,
+    );
+    this.name = "PluginNotCuratedError";
+  }
+}
+
 /**
  * A merge strategy (`ours`/`theirs`) was requested but the install-time
  * baseline needed for a three-way merge cannot be reconstructed.
@@ -244,6 +280,8 @@ function pluginTarget(name: string, deps: UpgradePluginDeps): string {
  * Throws {@link PluginNotInstalledError} when no copy is installed,
  * {@link PluginNotUpgradableError} when the install is neither in the
  * marketplace nor carries a recorded GitHub source to advance,
+ * {@link PluginNotCuratedError} when `marketplaceOnly` was requested for an
+ * install the marketplace does not claim,
  * {@link PluginMergeBaselineError} when a merge strategy is requested but the
  * install-time baseline cannot be reconstructed,
  * {@link PluginSourceUnavailableError} when the marketplace catalog or the
@@ -302,6 +340,10 @@ export async function upgradePlugin(
           "it has no marketplace entry and no installed copy to upgrade",
         );
       }
+      if (opts.marketplaceOnly) {
+        // The caller only accepts a curated pin, and this install has none.
+        throw new PluginNotCuratedError(name);
+      }
       return directUpgrade({ name, local, dryRun, strategy }, deps);
     }
     case "remote-unavailable":

package/src/config/__tests__/default-profile-catalog.test.ts

@@ -7,6 +7,7 @@ import {
   CODE_DEFAULT_PROFILE_ENTRIES,
   getEffectiveProfile,
   getEffectiveProfiles,
+  getEffectiveProfilesForProvider,
   PROFILE_IMPLS,
   resolveDefaultProfileForProvider,
 } from "../default-profile-catalog.js";
@@ -22,6 +23,7 @@ import {
 import {
   type DefaultProviderConfig,
   type LLMCallSite,
+  LLMCallSiteEnum,
   LLMSchema,
   type ProfileEntry,
 } from "../schemas/llm.js";
@@ -245,7 +247,10 @@ describe("resolver integration", () => {
       },
     });
     const body = CODE_DEFAULT_PROFILE_ENTRIES["latency-optimized"]!;
-    for (const callSite of ["voiceFrontDoor", "voiceFrontDecision"] as const) {
+    for (const callSite of [
+      "voiceFrontDoor",
+      "voiceProgressNarration",
+    ] as const) {
       const resolved = resolveCallSiteConfig(callSite, llm);
       expect(resolved.model).toBe(body.model as string);
       expect(resolved.model).not.toBe("claude-opus-4-6");
@@ -265,6 +270,12 @@ describe("resolver integration", () => {
 });
 
 describe("schema validation", () => {
+  test("voiceFrontDoor is the only front callsite", () => {
+    expect(
+      LLMCallSiteEnum.options.filter((callSite) => callSite.includes("Front")),
+    ).toEqual(["voiceFrontDoor"]);
+  });
+
   test("always-available default names are valid references; os-beta only when materialized", () => {
     expect(() => LLMSchema.parse({ activeProfile: "balanced" })).not.toThrow();
     expect(() =>
@@ -323,7 +334,7 @@ describe("resolveDefaultProfileForProvider", () => {
         expect(typeof entry?.model).toBe("string");
         expect(entry?.provider).toBeDefined();
         // Identity columns stamp no connection; BYOK columns always do.
-        if (entry?.provider === "vellum") {
+        if (entry?.provider === "vellum" || entry?.provider === "chatgpt") {
           expect(entry?.provider_connection).toBeUndefined();
         } else {
           expect(entry?.provider_connection).toBeDefined();
@@ -333,6 +344,27 @@ describe("resolveDefaultProfileForProvider", () => {
     }
   });
 
+  test("the chatgpt column resolves Codex-pinned models with no connection stamp", () => {
+    const byKey: Record<string, string> = {
+      balanced: "gpt-5.6-luna",
+      "quality-optimized": "gpt-5.6-sol",
+      "cost-optimized": "gpt-5.6-luna",
+      "latency-optimized": "gpt-5.6-luna",
+    };
+    const effective = getEffectiveProfilesForProvider(undefined, dp("chatgpt"));
+    for (const [key, model] of Object.entries(byKey)) {
+      const entry = effective[key];
+      expect(entry?.provider).toBe("chatgpt");
+      expect(entry?.model).toBe(model);
+      expect(entry?.provider_connection).toBeUndefined();
+      expect(entry?.source).toBe("managed");
+    }
+    // Cost and Speed both opt fully out of reasoning.
+    expect(effective["cost-optimized"]?.effort).toBe("none");
+    expect(effective["latency-optimized"]?.effort).toBe("none");
+    expect(effective.balanced?.thinking?.enabled).toBe(true);
+  });
+
   test("a provider without a named matrix column materializes from the shared BYOK templates", () => {
     const entry = resolveDefaultProfileForProvider(
       undefined,

package/src/config/__tests__/default-provider.test.ts

@@ -157,6 +157,12 @@ describe("resolveDefaultConnectionName", () => {
     );
   });
 
+  test("chatgpt resolves to the canonical subscription connection name", () => {
+    expect(resolveDefaultConnectionName({ provider: "chatgpt" })).toBe(
+      "chatgpt-subscription",
+    );
+  });
+
   test("every other provider resolves to its personal connection", () => {
     expect(resolveDefaultConnectionName({ provider: "anthropic" })).toBe(
       "anthropic-personal",
@@ -221,7 +227,6 @@ describe("getDefaultProvider / setDefaultProvider", () => {
   test("setDefaultProvider validates the provider before writing", () => {
     expect(() =>
       setDefaultProvider({
-        // @ts-expect-error deliberately invalid for the test
         provider: "not-a-provider",
       }),
     ).toThrow();

package/src/config/__tests__/profile-materialization.test.ts

@@ -1,4 +1,17 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, mock, test } from "bun:test";
+
+// Entry-name folds are gated on the named row existing with an agreeing
+// kind, so the tests control the row store directly.
+const connectionRows = new Map<string, { name: string; provider: string }>([
+  ["anthropic-personal", { name: "anthropic-personal", provider: "anthropic" }],
+]);
+mock.module("../../persistence/db-connection.js", () => ({
+  getDb: () => ({}),
+}));
+mock.module("../../providers/inference/connections.js", () => ({
+  getConnection: (_db: unknown, name: string) =>
+    connectionRows.get(name) ?? null,
+}));
 
 import { VELLUM_MANAGED_CONNECTION_NAME } from "../../providers/vellum-model-routing.js";
 import { completeCustomProfile } from "../profile-materialization.js";
@@ -28,8 +41,10 @@ describe("completeCustomProfile", () => {
       model: "claude-fable-5",
     });
     expect(completed.model).toBe("claude-fable-5");
-    expect(completed.provider).toBe("anthropic");
-    expect(completed.provider_connection).toBe("anthropic-personal");
+    // The default's explicit binding is inherited IN the provider value
+    // (the entries-model representation), never as a stamped binding.
+    expect(completed.provider).toBe("anthropic-personal");
+    expect(completed.provider_connection).toBeUndefined();
     expect(completed.maxTokens).toBe(64000);
     expect(completed.effort).toBe("max");
     expect(completed.speed).toBe("standard");
@@ -78,12 +93,12 @@ describe("completeCustomProfile", () => {
     expect(completed.contextWindow?.overflowRecovery?.enabled).toBe(true);
   });
 
-  test("keeps the inherited provider when it serves the profile's model", () => {
+  test("inherits the default's binding as the entry name when the provider serves the model", () => {
     const completed = completeCustomProfile(fullDefault, {
       model: "claude-fable-5",
     });
-    expect(completed.provider).toBe("anthropic");
-    expect(completed.provider_connection).toBe("anthropic-personal");
+    expect(completed.provider).toBe("anthropic-personal");
+    expect(completed.provider_connection).toBeUndefined();
   });
 
   test("stamps the catalog owner for a model the default provider does not serve, and drops the default's connection", () => {
@@ -123,36 +138,77 @@ describe("completeCustomProfile", () => {
     expect(completed.provider_connection).toBeUndefined();
   });
 
-  test("inherits the vellum managed connection across a provider change, but only onto managed-routable providers", () => {
+  test("a managed default's binding becomes the routing identity, never a stamped field", () => {
     const managedDefault = LLMConfigBase.parse({
       ...fullDefault,
       provider_connection: VELLUM_MANAGED_CONNECTION_NAME,
     });
     const implied = completeCustomProfile(managedDefault, { model: "gpt-5.5" });
-    expect(implied.provider).toBe("openai");
-    expect(implied.provider_connection).toBe(VELLUM_MANAGED_CONNECTION_NAME);
+    expect(implied.provider).toBe("vellum");
+    expect(implied.provider_connection).toBeUndefined();
 
     const explicit = completeCustomProfile(managedDefault, {
       provider: "openai",
       model: "gpt-5.4",
     });
-    expect(explicit.provider_connection).toBe(VELLUM_MANAGED_CONNECTION_NAME);
+    expect(explicit.provider).toBe("vellum");
+    expect(explicit.provider_connection).toBeUndefined();
+  });
 
-    // The vellum connection can't route a non-managed provider; baking it in
-    // would fail dispatch's mismatch path instead of auto-resolving.
-    const nonRoutable = completeCustomProfile(managedDefault, {
-      provider: "openrouter",
-      model: "minimax/minimax-m3",
+  test("inherits the binding as the entry name even for a model unknown to the catalog", () => {
+    const completed = completeCustomProfile(fullDefault, {
+      model: "totally-custom-model",
     });
-    expect(nonRoutable.provider_connection).toBeUndefined();
+    expect(completed.provider).toBe("anthropic-personal");
+    expect(completed.provider_connection).toBeUndefined();
   });
 
-  test("keeps the inherited provider for a model unknown to the catalog", () => {
-    const completed = completeCustomProfile(fullDefault, {
+  test("a dangling default binding passes through as the legacy field", () => {
+    const dangling = LLMConfigBase.parse({
+      ...fullDefault,
+      provider_connection: "deleted-row",
+    });
+    const completed = completeCustomProfile(dangling, {
+      model: "claude-fable-5",
+    });
+    // Folding an unverifiable binding would hide it from the collapse
+    // migration's dangling recovery; the legacy field keeps it visible.
+    expect(completed.provider).toBe("anthropic");
+    expect(completed.provider_connection).toBe("deleted-row");
+  });
+
+  test("a kind-disagreeing default binding passes through as the legacy field", () => {
+    connectionRows.set("mislabeled", {
+      name: "mislabeled",
+      provider: "openai",
+    });
+    try {
+      const mismatched = LLMConfigBase.parse({
+        ...fullDefault,
+        provider_connection: "mislabeled",
+      });
+      const completed = completeCustomProfile(mismatched, {
+        model: "claude-fable-5",
+      });
+      expect(completed.provider).toBe("anthropic");
+      expect(completed.provider_connection).toBe("mislabeled");
+    } finally {
+      connectionRows.delete("mislabeled");
+    }
+  });
+
+  test("a managed default binding is not inherited when the identity cannot serve the model", () => {
+    const managedDefault = LLMConfigBase.parse({
+      ...fullDefault,
+      provider_connection: VELLUM_MANAGED_CONNECTION_NAME,
+    });
+    const completed = completeCustomProfile(managedDefault, {
       model: "totally-custom-model",
     });
+    // Dispatch auto-resolves by vendor instead of pinning an unservable
+    // managed route.
     expect(completed.provider).toBe("anthropic");
-    expect(completed.provider_connection).toBe("anthropic-personal");
+    expect(completed.provider_connection).toBeUndefined();
   });
 
   test("passes mix profiles through untouched", () => {

package/src/config/bundled-skills/acp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: acp
-description: Spawn external coding agents via the Agent Client Protocol (ACP)
+description: Set up, authenticate, and run external coding agents (Claude Code, Codex) via the Agent Client Protocol
 compatibility: "Designed for Vellum personal assistants"
 metadata:
   emoji: "🔗"
@@ -8,13 +8,12 @@ metadata:
     display-name: "ACP"
     category: "development"
     activation-hints:
-      - "User asks to use Claude Code or Codex to do something"
-      - "User wants to delegate a coding task to Claude Code, Codex, or another ACP agent"
-      - "User wants to hand a coding task to another agent and check on it later"
-      - "User wants to spawn an external coding agent that runs autonomously and streams results back"
-      - "User mentions ACP, claude-agent-acp, codex-acp, or running multiple coding agents in parallel"
+      - "User wants to set up, install, configure, authenticate, or connect Claude Code or Codex"
+      - "User asks to use Claude Code or Codex, or delegate a coding task to an ACP agent"
+      - "User wants an agent to work autonomously and report back later"
+      - "User mentions ACP, claude-agent-acp, or codex-acp"
     avoid-when:
-      - "Task is small enough to do inline with the assistant's own tools - no need for an external agent"
+      - "The task is small enough to do inline"
 ---
 
 ACP agent orchestration - spawn external coding agents (Claude Code, Codex) to work on tasks via the Agent Client Protocol. Each agent runs as its own subprocess speaking ACP over stdio and streams results back into the conversation.

package/src/config/bundled-skills/document-editor/SKILL.md

@@ -33,9 +33,9 @@ Write and edit long-form documents using the built-in rich text editor. Document
 
 This is the default path when the user asks you to write something.
 
-1. **Create the document**: Call `document_create` with a title (inferred from the request). Call the tool immediately, not after conversational preamble.
+1. **Create the document**: Call `document_create` with a title (inferred from the request). Call the tool immediately, not after conversational preamble. Anything you pass as `initial_content` is saved right then, so the first `document_update` must start with the next chunk rather than repeating it.
 2. **Write content in Markdown**: Use proper structure (`#` for titles, `##` for sections), **bold**, _italic_, code blocks, tables, lists, blockquotes as appropriate.
-3. **CRITICAL - Stream content in chunks**: Call `document_update` MULTIPLE times, not just once. Break content into logical chunks (paragraphs, sections, or every 200-300 words). Call `document_update` with `mode: "append"` for EACH chunk separately. When you are streaming into the document you just created, `surface_id` is optional — omit it and pass only `content`, and the update targets that document. The user experiences real-time content appearing as you write.
+3. **CRITICAL - Stream content in chunks**: Call `document_update` MULTIPLE times, not just once. Break content into logical chunks (paragraphs, sections, or every 200-300 words). Call `document_update` with `mode: "append"` for EACH chunk separately. Each append carries ONLY that chunk: content already in the document is committed, and resending it would print it twice. When you are streaming into the document you just created, `surface_id` is optional: omit it and pass only `content`, and the update targets that document. The user experiences real-time content appearing as you write.
 
 ### Recovering from a failed update
 

package/src/config/bundled-skills/document-editor/TOOLS.json

@@ -33,7 +33,7 @@
           },
           "initial_content": {
             "type": "string",
-            "description": "Initial Markdown content to populate the editor (optional)"
+            "description": "Initial Markdown content to populate the editor (optional). It is saved as soon as the document is created, so the first document_update append must start with the NEXT chunk, never with this text again."
           }
         }
       },
@@ -54,7 +54,7 @@
           },
           "content": {
             "type": "string",
-            "description": "Markdown content to set or append"
+            "description": "Markdown content to set or append. In append mode, send only the new chunk: whatever is already in the document, including document_create's initial_content, is committed and must not be resent."
           },
           "mode": {
             "type": "string",

package/src/config/bundled-skills/media-processing/services/preprocess.ts

@@ -19,6 +19,7 @@ import {
   updateProcessingStage,
 } from "../../../../persistence/media-store.js";
 import { resolveBatchTranscriber } from "../../../../providers/speech-to-text/resolve.js";
+import type { BatchTranscriber } from "../../../../stt/types.js";
 import { silentlyWithLog } from "../../../../util/silently.js";
 import {
   FFMPEG_PALETTE_TIMEOUT_MS,
@@ -459,10 +460,19 @@ export async function preprocessForAsset(
     const allFramePaths: string[] = [];
 
     // Resolve the STT transcriber once for all segments to avoid repeated
-    // credential lookups in the per-segment loop.
-    const transcriber = options.includeAudio
-      ? await resolveBatchTranscriber()
-      : null;
+    // credential lookups in the per-segment loop. A resolver failure degrades
+    // to transcript-less segments like an absent provider does, reporting the
+    // reason on the progress stream rather than killing the whole run.
+    let transcriber: BatchTranscriber | null = null;
+    if (options.includeAudio) {
+      try {
+        transcriber = await resolveBatchTranscriber();
+      } catch (err) {
+        onProgress?.(
+          `Audio transcription unavailable: ${(err as Error).message}\n`,
+        );
+      }
+    }
 
     const scaleFilter = `scale='if(gt(iw,ih),-1,${config.shortEdge})':'if(gt(iw,ih),${config.shortEdge},-1)'`;
 

package/src/config/bundled-skills/settings/TOOLS.json

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "voice_config_update",
-      "description": "Update a voice configuration setting. Use tts_provider / stt_provider to switch the active TTS / STT provider. Provider \"vellum\" is Vellum-managed speech (billed to your organization; requires a Vellum platform connection via 'assistant platform connect'); any other provider uses the user's own API key. Valid TTS providers come from the provider catalog (vellum, elevenlabs, fish-audio, deepgram, xai); valid STT providers: vellum, deepgram, google-gemini, openai-whisper, xai. Use tts_voice_id to change the voice; it targets whichever TTS provider is currently active. For elevenlabs, pass an ElevenLabs voice ID. For vellum (managed), pass a managed voice model ID: this may be an ElevenLabs voice ID (managed speech serves the same ElevenLabs voices) or a Deepgram Aura model ID (e.g. aura-2-thalia-en); only rate-carded voices synthesize, so prefer models from the managed catalog (daemon route GET tts/managed-voices, also used by the web voice picker). For deepgram, pass a Deepgram Aura model ID. Use fish_audio_reference_id for Fish Audio voice reference. Use stt_language to set the spoken language for speech recognition: one of the 50 base language codes on the verified Deepgram nova-3 monolingual roster (e.g. en, es, hi, ta, zh, ko), or \"multi\" for code-switching mid-sentence across its 10-language roster (English, Spanish, French, German, Hindi, Russian, Portuguese, Japanese, Italian, Dutch; e.g. Hinglish); plain language names like \"tamil\" or \"multilingual\" are accepted and normalized. Accepted values follow the configured STT provider: vellum-managed and deepgram accept the full roster plus \"multi\"; xai accepts only the 10 multilingual-roster codes (en, es, fr, de, hi, ru, pt, ja, it, nl) and rejects \"multi\" and the extended codes (both are verified for Deepgram nova-3 only); google-gemini / openai-whisper auto-detect natively, so the value persists but is ignored while they are active. Deepgram uses the same API key for TTS and STT. Changes persist to services.stt / services.tts config and take effect immediately.",
+      "description": "Update a voice configuration setting. Use tts_provider / stt_provider to switch the active TTS / STT provider. Provider \"vellum\" is Vellum-managed speech (billed to your organization; requires a Vellum platform connection via 'assistant platform connect'); any other provider uses the user's own API key. Valid TTS providers come from the provider catalog (vellum, elevenlabs, fish-audio, deepgram, xai); valid STT providers: vellum, deepgram, deepgram-flux, google-gemini, openai-whisper, xai. deepgram-flux is streaming-only: it serves live speech (voice mode, dictation) but cannot transcribe audio files or voice messages, so do not recommend it when the user wants file transcription. Use tts_voice_id to change the voice; it targets whichever TTS provider is currently active. For elevenlabs, pass an ElevenLabs voice ID. For vellum (managed), pass a managed voice model ID: this may be an ElevenLabs voice ID (managed speech serves the same ElevenLabs voices) or a Deepgram Aura model ID (e.g. aura-2-thalia-en); only rate-carded voices synthesize, so prefer models from the managed catalog (assistant route GET tts/managed-voices, also used by the web voice picker). For deepgram, pass a Deepgram Aura model ID. Use fish_audio_reference_id for Fish Audio voice reference. Use stt_language to set the spoken language for speech recognition: one of the 50 base language codes on the verified Deepgram nova-3 monolingual roster (e.g. en, es, hi, ta, zh, ko), or \"multi\" for code-switching mid-sentence across its 10-language roster (English, Spanish, French, German, Hindi, Russian, Portuguese, Japanese, Italian, Dutch; e.g. Hinglish); plain language names like \"tamil\" or \"multilingual\" are accepted and normalized. Accepted values follow the configured STT provider: vellum-managed and deepgram accept the full roster plus \"multi\"; xai accepts only the 10 multilingual-roster codes (en, es, fr, de, hi, ru, pt, ja, it, nl) and rejects \"multi\" and the extended codes (both are verified for Deepgram nova-3 only); google-gemini / openai-whisper auto-detect natively and deepgram-flux runs an English-only model, so the value persists but is ignored while they are active. Deepgram uses the same API key for TTS and STT, and deepgram-flux shares it too. Changes persist to services.stt / services.tts config and take effect immediately.",
       "category": "system",
       "risk": "low",
       "input_schema": {
@@ -20,10 +20,10 @@
               "tts_provider",
               "tts_voice_id"
             ],
-            "description": "The voice setting to change. tts_provider / stt_provider select the active provider for each service (\"vellum\" = Vellum-managed speech; anything else = the user's own API key). tts_voice_id sets the voice for the currently active TTS provider (ElevenLabs voice ID for elevenlabs; a managed voice model ID for vellum, meaning an ElevenLabs voice ID or a Deepgram Aura model ID like aura-2-thalia-en; a Deepgram Aura model ID for deepgram; voice ID for xai). fish_audio_reference_id sets the Fish Audio voice reference. stt_language sets the spoken language for speech recognition (vellum-managed/deepgram: the full roster plus \"multi\"; xai: only the 10 multilingual-roster codes, with \"multi\" and the extended codes rejected; google-gemini and openai-whisper auto-detect and ignore it). Deepgram shares one API key across TTS and STT."
+            "description": "The voice setting to change. tts_provider / stt_provider select the active provider for each service (\"vellum\" = Vellum-managed speech; anything else = the user's own API key). tts_voice_id sets the voice for the currently active TTS provider (ElevenLabs voice ID for elevenlabs; a managed voice model ID for vellum, meaning an ElevenLabs voice ID or a Deepgram Aura model ID like aura-2-thalia-en; a Deepgram Aura model ID for deepgram; voice ID for xai). fish_audio_reference_id sets the Fish Audio voice reference. stt_language sets the spoken language for speech recognition (vellum-managed/deepgram: the full roster plus \"multi\"; xai: only the 10 multilingual-roster codes, with \"multi\" and the extended codes rejected; google-gemini and openai-whisper auto-detect and ignore it; deepgram-flux is English-only and ignores it). Deepgram shares one API key across TTS and STT, and deepgram-flux uses that same key."
           },
           "value": {
-            "description": "The new value for the setting. For tts_provider: one of vellum, elevenlabs, fish-audio, deepgram, xai. For stt_provider: one of vellum, deepgram, google-gemini, openai-whisper, xai. For tts_voice_id: a voice ID for the active TTS provider: an alphanumeric ElevenLabs voice ID (elevenlabs), a managed voice model ID which may be an ElevenLabs voice ID or a Deepgram Aura model ID like aura-2-thalia-en (vellum), or a Deepgram Aura model ID (deepgram). For fish_audio_reference_id: a Fish Audio voice reference ID. For stt_language: one of the 50 base codes on the nova-3 monolingual roster (e.g. en, es, hi, ta, zh, ko), or multi (code-switching across its 10-language roster); language names like \"hindi\", \"tamil\", or \"multilingual\" are also accepted and normalized; when the configured STT provider is xai, only the 10 multilingual-roster codes (en, es, fr, de, hi, ru, pt, ja, it, nl) are accepted. For conversation_timeout: seconds (5, 10, 15, 30, or 60). For activation_key: key identifier string."
+            "description": "The new value for the setting. For tts_provider: one of vellum, elevenlabs, fish-audio, deepgram, xai. For stt_provider: one of vellum, deepgram, deepgram-flux, google-gemini, openai-whisper, xai; deepgram-flux serves live speech only and cannot transcribe files. For tts_voice_id: a voice ID for the active TTS provider: an alphanumeric ElevenLabs voice ID (elevenlabs), a managed voice model ID which may be an ElevenLabs voice ID or a Deepgram Aura model ID like aura-2-thalia-en (vellum), or a Deepgram Aura model ID (deepgram). For fish_audio_reference_id: a Fish Audio voice reference ID. For stt_language: one of the 50 base codes on the nova-3 monolingual roster (e.g. en, es, hi, ta, zh, ko), or multi (code-switching across its 10-language roster); language names like \"hindi\", \"tamil\", or \"multilingual\" are also accepted and normalized; when the configured STT provider is xai, only the 10 multilingual-roster codes (en, es, fr, de, hi, ru, pt, ja, it, nl) are accepted. For conversation_timeout: seconds (5, 10, 15, 30, or 60). For activation_key: key identifier string."
           }
         }
       },