@vellumai/assistant 0.11.3 → 0.11.4-dev.202608190019.b94dbf2

package/src/schedule/__tests__/plugin-schedule-reconciler.test.ts

@@ -45,9 +45,29 @@ mock.module("../../notifications/emit-signal.js", () => ({
   },
 }));
 
+/**
+ * Plugin directories the daemon has not activated. The reconciler arms only
+ * plugins this process brought up, and no test here runs the plugin loader, so
+ * the double answers "activated" unless a case says otherwise.
+ */
+const notActivatedDirs = new Set<string>();
+
+/** Every directory the reconciler put through the activation predicate. */
+const activationProbes: string[] = [];
+
+const realMtimeCache = await import("../../plugins/mtime-cache.js");
+mock.module("../../plugins/mtime-cache.js", () => ({
+  ...realMtimeCache,
+  isPluginDirActivated: (dir: string) => {
+    activationProbes.push(dir);
+    return !notActivatedDirs.has(dir);
+  },
+}));
+
 import { setOverridesForTesting } from "../../__tests__/feature-flag-test-helpers.js";
 import { getDb } from "../../persistence/db-connection.js";
 import { initializeDb } from "../../persistence/db-init.js";
+import { listInstalledPluginDirs } from "../../plugins/installed-plugin-dirs.js";
 import { getWorkspacePluginsDir } from "../../util/platform.js";
 import {
   reconcilePluginSchedules,
@@ -175,6 +195,8 @@ function resetReconcilerFixtures(): void {
   emittedSignals.length = 0;
   emitResultOverride = null;
   emitGate = null;
+  notActivatedDirs.clear();
+  activationProbes.length = 0;
   resetDefinitionErrorEmitGuardForTests();
 }
 
@@ -970,6 +992,65 @@ describe("reconcilePluginSchedules", () => {
     expect(payload.reason).toContain("no upcoming occurrences");
   });
 
+  test("a plugin the daemon never activated arms nothing", async () => {
+    // Everything the parser needs is on disk; only the activation is missing,
+    // which is what a directory dropped into the plugins root looks like.
+    const dir = writePlugin("news", digest());
+    notActivatedDirs.add(dir);
+
+    await reconcilePluginSchedules();
+
+    expect(listDeclaredSchedules()).toHaveLength(0);
+    expect(emittedSignals).toHaveLength(0);
+  });
+
+  test("a row disarms once its plugin is no longer activated", async () => {
+    const dir = writePlugin("news", digest());
+    await reconcilePluginSchedules();
+    const created = listDeclaredSchedules()[0]!;
+    expect(created.enabled).toBe(true);
+
+    notActivatedDirs.add(dir);
+    await reconcilePluginSchedules();
+
+    const row = listDeclaredSchedules()[0]!;
+    expect(row.id).toBe(created.id);
+    expect(row.enabled).toBe(false);
+  });
+
+  test("a plugin activated between passes arms on the second one", async () => {
+    const dir = writePlugin("news", digest());
+    notActivatedDirs.add(dir);
+    await reconcilePluginSchedules();
+    expect(listDeclaredSchedules()).toHaveLength(0);
+
+    notActivatedDirs.delete(dir);
+    await reconcilePluginSchedules();
+
+    const rows = listDeclaredSchedules();
+    expect(rows).toHaveLength(1);
+    expect(rows[0]!.sourceKey).toBe(DIGEST_KEY);
+    expect(rows[0]!.enabled).toBe(true);
+    // The row arms for the first time here, so it announces its arrival.
+    const declared = emittedSignals.filter(
+      (s) => s.sourceEventName === "schedule.declared",
+    );
+    expect(declared).toHaveLength(1);
+    expect(declared[0]!.sourceContextId).toBe(DIGEST_KEY);
+  });
+
+  test("the activation probe sees the directory string the walk yields", async () => {
+    // The predicate is keyed by directory path, so the enumeration the
+    // reconciler walks and the map the daemon activates into have to agree on
+    // the exact string. Both come from `listInstalledPluginDirs`.
+    const dir = writePlugin("news", digest());
+
+    await reconcilePluginSchedules();
+
+    expect(listInstalledPluginDirs().map((p) => p.dir)).toEqual([dir]);
+    expect(activationProbes).toEqual([dir]);
+  });
+
   test("a suppressed error emit still latches the day guard", async () => {
     writePlugin("news", brokenDigest());
     emitResultOverride = {

package/src/schedule/plugin-schedule-availability.ts

@@ -0,0 +1,58 @@
+/**
+ * Availability probe for a plugin-declared schedule's source.
+ *
+ * Composes the daemon's activation state with the on-disk declaration probe:
+ * did this process bring the plugin up, and is its declaration still
+ * sourceable.
+ *
+ * **This probe is only meaningful in the main daemon process.** Activation is
+ * tracked in an in-memory map that `bringUpPlugin` writes, so only the process
+ * that ran the plugin loader can answer for it. HTTP routes and the plugin
+ * schedule reconciler run there, so they may use this. Worker processes (the
+ * schedule worker in `schedule/worker.ts`, sidecar turn workers) activate no
+ * plugins, so their ledger is empty and every plugin would read as
+ * unactivated. Those paths call {@link declarationExistsOnDisk} directly.
+ *
+ * That split is safe because the reconciler owns arming and runs in the
+ * daemon: a plugin it has not activated never arms, and its sweep disarms the
+ * rows of a plugin that stops being activated within one pass. The window
+ * between those passes is the whole exposure of the worker-side disk-only
+ * probes.
+ *
+ * The composition lives here rather than in `./plugin-schedule-declarations.ts`
+ * because that parser is reachable from the plugin loader's own static graph
+ * and must stay free of daemon runtime state. `plugins/mtime-cache.ts` reaches
+ * the schedule side only through a dynamic import, so importing it here does
+ * not close a static cycle.
+ */
+
+import { join } from "node:path";
+
+import { isPluginDirActivated } from "../plugins/mtime-cache.js";
+import { getWorkspacePluginsDir } from "../util/platform.js";
+import { declarationExistsOnDisk } from "./plugin-schedule-declarations.js";
+
+/**
+ * True when the schedule behind `sourceKey`
+ * (`plugin:<pluginName>/<scheduleName>`) may run: the daemon activated the
+ * plugin, and {@link declarationExistsOnDisk} still finds the declaration.
+ *
+ * The activation half is what keeps a plugin directory dropped into the
+ * plugins root out of the scheduler. Such a directory has files the disk probe
+ * accepts, but no `init` has run for it, so its hooks and tools are not live
+ * and its schedules must not be either.
+ */
+export async function pluginScheduleSourceAvailable(
+  sourceKey: string,
+): Promise<boolean> {
+  const match = /^plugin:([^/]+)\/(.+)$/.exec(sourceKey);
+  if (!match) {
+    return false;
+  }
+  const [, pluginName] = match;
+  const pluginDir = join(getWorkspacePluginsDir(), pluginName!);
+  return (
+    isPluginDirActivated(pluginDir) &&
+    (await declarationExistsOnDisk(sourceKey))
+  );
+}

package/src/schedule/plugin-schedule-declarations.ts

@@ -30,7 +30,6 @@ import { z } from "zod";
 import { isPluginDisabled } from "../plugins/disabled-state.js";
 import { parsePluginManifest } from "../plugins/external-plugin-loader.js";
 import { isInsidePluginRoot } from "../plugins/installed-plugin-dirs.js";
-import { walkPluginTree } from "../plugins/plugin-tree-walk.js";
 import { FRONTMATTER_REGEX } from "../skills/frontmatter.js";
 import { getWorkspacePluginsDir } from "../util/platform.js";
 import {
@@ -77,9 +76,13 @@ export interface ScheduleDeclaration {
   scriptInvocation: string | null;
   config: PluginScheduleConfig;
   /**
-   * Stable sha256 over the declaration's file contents and their paths
-   * relative to `schedules/`. Any edit, addition, removal, or rename of a
-   * declaration file changes the hash.
+   * Stable sha256 over the declaration's `config.json` and its entrypoint,
+   * each hashed together with its path relative to `schedules/`. Nothing else
+   * under the declaration directory takes part. Helper scripts, and any state
+   * a script writes beside itself, do not change the stored row definition, so
+   * hashing them would report a definition change every time a stateful
+   * schedule runs. Scripts execute by path, so an edit to a helper takes
+   * effect without a definition change.
    */
   definitionHash: string;
 }
@@ -292,21 +295,6 @@ function hashDeclarationFiles(files: DeclarationFile[]): string {
   return hash.digest("hex");
 }
 
-/**
- * Collect every regular file under `dir` (recursively, dot entries and
- * symlinks skipped) with paths relative to the schedules/ root.
- */
-function collectDeclarationFiles(
-  dir: string,
-  relPrefix: string,
-): DeclarationFile[] {
-  const files: DeclarationFile[] = [];
-  walkPluginTree(dir, { excludeDotEntries: true }, (rel, abs) => {
-    files.push({ relPath: `${relPrefix}${rel}`, content: readFileSync(abs) });
-  });
-  return files;
-}
-
 function shellQuote(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -395,25 +383,24 @@ function parseDirectoryDeclaration(
   let message: string | null = null;
   let scriptInvocation: string | null = null;
   let mode: PluginScheduleMode;
+  let entrypointText: string;
   if (entrypoint === "index.md") {
-    const content = readFileSync(join(dirPath, "index.md"), "utf8");
-    if (FRONTMATTER_REGEX.test(content)) {
+    entrypointText = readFileSync(join(dirPath, "index.md"), "utf8");
+    if (FRONTMATTER_REGEX.test(entrypointText)) {
       return {
         error:
           "index.md must not contain frontmatter: directory-form config belongs in config.json",
       };
     }
-    message = content.trim();
+    message = entrypointText.trim();
     if (!message) {
       return { error: "prompt body is empty" };
     }
     mode = "execute";
   } else {
     const scriptPath = join(dirPath, "index.sh");
-    scriptInvocation = buildScriptInvocation(
-      scriptPath,
-      readFileSync(scriptPath, "utf8"),
-    );
+    entrypointText = readFileSync(scriptPath, "utf8");
+    scriptInvocation = buildScriptInvocation(scriptPath, entrypointText);
     mode = "script";
   }
 
@@ -422,7 +409,16 @@ function parseDirectoryDeclaration(
     message,
     scriptInvocation,
     config: configResult.config,
-    files: collectDeclarationFiles(dirPath, `${dirName}/`),
+    files: [
+      {
+        relPath: `${dirName}/config.json`,
+        content: Buffer.from(rawConfigText),
+      },
+      {
+        relPath: `${dirName}/${entrypoint}`,
+        content: Buffer.from(entrypointText),
+      },
+    ],
   };
 }
 

package/src/schedule/plugin-schedule-reconciler.ts

@@ -33,6 +33,7 @@ import type { AttentionHints } from "../notifications/signal.js";
 import { isPluginDisabled } from "../plugins/disabled-state.js";
 import { parsePluginManifest } from "../plugins/external-plugin-loader.js";
 import { listInstalledPluginDirs } from "../plugins/installed-plugin-dirs.js";
+import { isPluginDirActivated } from "../plugins/mtime-cache.js";
 import { getLogger } from "../util/logger.js";
 import {
   type DeclarationError,
@@ -264,9 +265,14 @@ function isCompletedRecurrence(
  * as the plugin source collector) and gather their schedule declarations.
  * Identity = the directory basename, mirroring `parsePluginManifest`.
  *
- * Disabled plugins and plugins without a `schedules/` directory are skipped
- * entirely; in particular, only schedule-declaring plugins pay the manifest
- * parse each pass. A schedule-declaring plugin whose manifest fails
+ * Disabled plugins, plugins this daemon has not activated
+ * ({@link isPluginDirActivated}), and plugins without a `schedules/` directory
+ * are skipped entirely; in particular, only schedule-declaring plugins pay the
+ * manifest parse each pass. The activation gate is what keeps a directory
+ * dropped into the plugins root out of the desired set: nothing has run its
+ * `init`, so its hooks and tools are not live and its schedules must not arm
+ * either. It joins the set on the pass after the boot scan or an imperative
+ * reconcile brings it up. A schedule-declaring plugin whose manifest fails
  * `parsePluginManifest` (unreadable or schema-invalid `package.json`) also
  * contributes nothing to the desired set: the runtime loader refuses to
  * bring such a plugin up, so its schedules must not stay armed either. Each
@@ -282,6 +288,9 @@ async function collectDesiredDeclarations(): Promise<CollectedDeclarations> {
     if (isPluginDisabled(name)) {
       continue;
     }
+    if (!isPluginDirActivated(dir)) {
+      continue;
+    }
     if (!existsSync(join(dir, "schedules"))) {
       continue;
     }

package/src/schedule/schedule-store.ts

@@ -840,7 +840,7 @@ export function listDeclaredSchedules(): ScheduleJob[] {
  * a null `lastRunAt` is a declared schedule inserted disabled, not an engine
  * latch, and stays re-armable.
  */
-function isEngineLatched(row: {
+export function isEngineLatched(row: {
   status: string;
   nextRunAt: number;
   lastRunAt: number | null;
@@ -1051,6 +1051,10 @@ export async function setUserEnabled(
     // again. The reconciler is the authority on the declaration set; this
     // probe only closes that fire-before-next-sweep window. The override
     // itself is still recorded, so it applies if the declaration returns.
+    // The probe is deliberately disk-only. A schedule tool calls this from a
+    // conversation turn, which can run in a sidecar worker process where the
+    // daemon's activation ledger is empty, so consulting activation here would
+    // refuse to re-arm anything. Activation stays the reconciler's call.
     if (value && !(await declarationExistsOnDisk(existing.sourceKey))) {
       logger.info(
         { scheduleId: id, sourceKey: existing.sourceKey },

package/src/schedule/scheduler.ts

@@ -529,10 +529,15 @@ export async function runDueSchedulesOnce(
 
     // Fire-time gate for plugin-sourced rows, covering every way the source
     // can go away under an armed row. `declarationExistsOnDisk` is the probe
-    // the run-now route and the enable path use, and it answers for all of
-    // them: a `.disabled` sentinel, a plugin directory a local uninstall
-    // removed, a manifest that no longer parses, and a declaration that is
-    // simply gone. Turning the feature flag off retires the whole surface.
+    // the enable path uses, and it answers for all of them: a `.disabled`
+    // sentinel, a plugin directory a local uninstall removed, a manifest that
+    // no longer parses, and a declaration that is simply gone. Turning the
+    // feature flag off retires the whole surface.
+    // The probe is deliberately disk-only. Schedule execution runs in the
+    // schedule worker process, which activates no plugins, so the daemon's
+    // in-memory activation ledger is empty here and reading it would skip
+    // every plugin schedule. Activation is gated where the daemon owns it: the
+    // reconciler decides what arms, and the run-now route refuses by hand.
     // The reconciler is what disarms the rows any of these own, and it runs
     // on its own schedule, so re-reading here is what makes the change take
     // effect immediately: a row still armed (or already claimed) at that

package/src/schedule/worker-control.ts

@@ -96,6 +96,7 @@ async function spawnScheduleWorkerProcessUncoalesced(
     return await spawnWorkerProcess({
       pidPath: getScheduleWorkerPidPath(),
       entry: new URL("./worker.ts", import.meta.url),
+      packagedEntry: "schedule",
       workerLabel: "Schedule worker",
       options: opts,
     });

package/src/schedule/worker.ts

@@ -16,6 +16,7 @@ import { writeFileSync } from "node:fs";
 import { getConfig } from "../config/loader.js";
 import { rehydratePlatformCredentials } from "../config/platform-rehydration.js";
 import { resetDb } from "../persistence/db-connection.js";
+import { registerWorkerPluginSurface } from "../plugins/worker-plugin-surface.js";
 import { disableStreamSeqStamping } from "../runtime/assistant-stream-state.js";
 import { initializeTools } from "../tools/registry.js";
 import { getLogger } from "../util/logger.js";
@@ -51,6 +52,11 @@ async function main(): Promise<void> {
   // rejected for both inference and background-wake requests.
   await rehydratePlatformCredentials();
 
+  // This process is the sole runner of schedule execution and hosts real agent
+  // conversations (wake, execute, and workflow modes), so it needs the default
+  // plugins' hooks and injectors just like the daemon.
+  registerWorkerPluginSurface();
+
   // Populate the tool registry (core built-ins + workspace tools). The daemon
   // does this at startup; this standalone process has to do it itself so
   // workflow schedules pass the core-tools readiness gate and agent-executed

package/src/security/oauth2.ts

@@ -273,20 +273,12 @@ async function runGatewayFlow(
 ): Promise<OAuth2FlowResult> {
   // Dynamic imports required here to avoid circular dependencies with
   // config/loader → security → oauth2 module chains.
-  const { loadConfig } = await import("../config/loader.js");
-  const { getOAuthCallbackUrl } =
-    await import("../inbound/public-ingress-urls.js");
-  const { resolveCallbackUrl } =
-    await import("../inbound/platform-callback-registration.js");
+  const { resolveOauthCallbackUrl } =
+    await import("../inbound/oauth-callback-url.js");
   const { registerPendingCallback } =
     await import("./oauth-callback-registry.js");
 
-  const appConfig = loadConfig();
-  const redirectUri = await resolveCallbackUrl(
-    () => getOAuthCallbackUrl(appConfig),
-    "webhooks/oauth/callback",
-    "oauth",
-  );
+  const redirectUri = await resolveOauthCallbackUrl();
 
   const codePromise = new Promise<string>((resolve, reject) => {
     registerPendingCallback(state, resolve, reject);
@@ -556,20 +548,12 @@ export async function prepareOAuth2Flow(
 
   // Dynamic imports required here to avoid circular dependencies with
   // config/loader → security → oauth2 module chains.
-  const { loadConfig } = await import("../config/loader.js");
-  const { getOAuthCallbackUrl } =
-    await import("../inbound/public-ingress-urls.js");
-  const { resolveCallbackUrl } =
-    await import("../inbound/platform-callback-registration.js");
+  const { resolveOauthCallbackUrl } =
+    await import("../inbound/oauth-callback-url.js");
   const { registerPendingCallback } =
     await import("./oauth-callback-registry.js");
 
-  const appConfig = loadConfig();
-  const redirectUri = await resolveCallbackUrl(
-    () => getOAuthCallbackUrl(appConfig),
-    "webhooks/oauth/callback",
-    "oauth",
-  );
+  const redirectUri = await resolveOauthCallbackUrl();
 
   const codeVerifier = generateCodeVerifier();
   const codeChallenge = generateCodeChallenge(codeVerifier);

package/src/stt/__tests__/daemon-batch-transcriber.test.ts

@@ -1,5 +1,6 @@
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
+import { batchBoundaryGapReason } from "../../providers/speech-to-text/provider-catalog.js";
 import { SttError } from "../types.js";
 
 // ---------------------------------------------------------------------------
@@ -620,3 +621,24 @@ describe("vellum factory case", () => {
     expect(createDaemonBatchTranscriber(null, "deepgram")).toBeNull();
   });
 });
+
+describe("deepgram-flux factory case", () => {
+  // The copy itself is pinned in provider-catalog.test.ts; what matters here
+  // is that the factory speaks with the catalog's voice rather than its own.
+  test("throws the catalog's streaming-only reason", () => {
+    expect(() =>
+      createDaemonBatchTranscriber("dg-test-key", "deepgram-flux"),
+    ).toThrow(batchBoundaryGapReason("deepgram-flux"));
+  });
+
+  test("marks the error user-facing so friendly copy does not overwrite it", () => {
+    try {
+      createDaemonBatchTranscriber("dg-test-key", "deepgram-flux");
+      throw new Error("expected the factory to throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(SttError);
+      expect((err as SttError).category).toBe("provider-error");
+      expect((err as SttError).userFacing).toBe(true);
+    }
+  });
+});

package/src/stt/__tests__/types.test.ts

@@ -2,10 +2,14 @@ import { describe, expect, test } from "bun:test";
 
 import type {
   SttStreamServerClosedEvent,
+  SttStreamServerEagerTurnEndEvent,
   SttStreamServerErrorEvent,
   SttStreamServerEvent,
   SttStreamServerFinalEvent,
   SttStreamServerPartialEvent,
+  SttStreamServerTurnEndEvent,
+  SttStreamServerTurnResumedEvent,
+  SttStreamServerTurnStartEvent,
 } from "../types.js";
 
 // ---------------------------------------------------------------------------
@@ -87,3 +91,93 @@ describe("SttStreamServerEvent types", () => {
     expect(_label).toBeUndefined();
   });
 });
+
+describe("turn-detection server events", () => {
+  test("turn-start event compiles and round-trips", () => {
+    const event: SttStreamServerTurnStartEvent = { type: "turn-start" };
+    const asUnion: SttStreamServerEvent = event;
+    expect(asUnion.type).toBe("turn-start");
+  });
+
+  test("eager-turn-end event carries the speculated transcript", () => {
+    const event: SttStreamServerEagerTurnEndEvent = {
+      type: "eager-turn-end",
+      text: "is this the end",
+    };
+    const asUnion: SttStreamServerEvent = event;
+    expect(asUnion.type).toBe("eager-turn-end");
+    expect(event.text).toBe("is this the end");
+  });
+
+  test("turn-resumed event compiles and round-trips", () => {
+    const event: SttStreamServerTurnResumedEvent = { type: "turn-resumed" };
+    const asUnion: SttStreamServerEvent = event;
+    expect(asUnion.type).toBe("turn-resumed");
+  });
+
+  test("turn-end event carries the committed transcript and optional confidence", () => {
+    const withoutConfidence: SttStreamServerTurnEndEvent = {
+      type: "turn-end",
+      text: "done speaking",
+    };
+    expect(withoutConfidence.confidence).toBeUndefined();
+
+    const event: SttStreamServerTurnEndEvent = {
+      type: "turn-end",
+      text: "done speaking",
+      confidence: 0.82,
+    };
+    const asUnion: SttStreamServerEvent = event;
+    expect(asUnion.type).toBe("turn-end");
+    expect(event.text).toBe("done speaking");
+    expect(event.confidence).toBe(0.82);
+  });
+
+  test("a consumer switch over every variant is exhaustive", () => {
+    // Fails to compile if a variant is added to SttStreamServerEvent
+    // without a case here, which is what forces consumers to be revisited.
+    const label = (event: SttStreamServerEvent): string => {
+      switch (event.type) {
+        case "partial":
+        case "final":
+        case "finalized":
+        case "error":
+        case "closed":
+          return "transcript";
+        case "turn-start":
+        case "eager-turn-end":
+        case "turn-resumed":
+        case "turn-end":
+          return "turn";
+        default: {
+          const _exhaustive: never = event;
+          return _exhaustive;
+        }
+      }
+    };
+
+    const events: SttStreamServerEvent[] = [
+      { type: "partial", text: "a" },
+      { type: "final", text: "a" },
+      { type: "finalized" },
+      { type: "error", category: "provider-error", message: "boom" },
+      { type: "closed" },
+      { type: "turn-start" },
+      { type: "eager-turn-end", text: "a" },
+      { type: "turn-resumed" },
+      { type: "turn-end", text: "a" },
+    ];
+
+    expect(events.map(label)).toEqual([
+      "transcript",
+      "transcript",
+      "transcript",
+      "transcript",
+      "transcript",
+      "turn",
+      "turn",
+      "turn",
+      "turn",
+    ]);
+  });
+});

package/src/stt/daemon-batch-transcriber.ts

@@ -13,6 +13,7 @@
  * - xAI (`xai`)
  */
 
+import { batchBoundaryGapReason } from "../providers/speech-to-text/provider-catalog.js";
 import type {
   BatchTranscriber,
   SttProviderId,
@@ -245,6 +246,9 @@ class VellumManagedBatchTranscriber implements BatchTranscriber {
  * language code), and the vellum managed path, whose platform proxy passes
  * it to Deepgram server-side. Whisper and Gemini auto-detect natively and
  * take no language parameter, so it is silently ignored for them.
+ *
+ * Throws an {@link SttError} for a provider with no batch endpoint at all,
+ * which no key can fix and `null` would understate.
  */
 export function createDaemonBatchTranscriber(
   apiKey: string | null | undefined,
@@ -268,6 +272,12 @@ export function createDaemonBatchTranscriber(
       return new GoogleGeminiBatchTranscriber(apiKey);
     case "xai":
       return new XAIBatchTranscriber(apiKey, language);
+    case "deepgram-flux":
+      // Same copy the resolver raises, so a direct factory caller and a
+      // config-driven one report the mismatch identically.
+      throw new SttError("provider-error", batchBoundaryGapReason(providerId), {
+        userFacing: true,
+      });
     default: {
       // Exhaustive check — compile error if a new SttProviderId is added
       // without a corresponding case here.

package/src/stt/stt-stream-session.ts

@@ -5,8 +5,11 @@
  * a client WebSocket connection and a provider-specific streaming adapter.
  * The orchestrator accepts client events (`audio`, `stop`), routes audio
  * frames to the resolved {@link StreamingTranscriber}, and emits normalized
- * server events (`partial`, `final`, `error`, `closed`) back over the same
- * WebSocket connection with per-session ordering guarantees.
+ * server events back over the same WebSocket connection with per-session
+ * ordering guarantees: transcripts (`partial`, `final`, `finalized`),
+ * turn boundaries from providers that detect them (`turn-start`,
+ * `eager-turn-end`, `turn-resumed`, `turn-end`), and termination
+ * (`error`, `closed`).
  *
  * Session lifecycle:
  * 1. Client opens a WebSocket to `/v1/stt/stream` with required `mimeType`
@@ -17,8 +20,9 @@
  *    `resolveStreamingTranscriber()` and starts the provider session.
  * 3. The client sends `audio` frames (binary or base64-encoded JSON) and
  *    a `stop` event when recording is complete.
- * 4. The provider emits `partial` and `final` transcript events which the
- *    orchestrator forwards to the client as JSON frames.
+ * 4. The provider emits transcript events, plus turn-boundary events when it
+ *    detects turns, and the orchestrator forwards each to the client as a
+ *    JSON frame.
  * 5. The session closes deterministically on client disconnect, `stop`
  *    event, idle timeout, or runtime shutdown.
  *