@vellumai/assistant 0.11.2 → 0.11.3-dev.202608080427.92f668a

package/src/persistence/subagent-store.ts

@@ -4,14 +4,18 @@
  *
  * This module owns only the durable row shape and raw SQL. The mapping to and
  * from the manager's `SubagentState` lives in `SubagentManager`, keeping this
- * layer decoupled from the subagent domain types. The one domain function it
- * does reach for is `normalizeSubagentLabel`: label lookups have to fold
- * exactly the way the manager's in-memory index folds, and SQLite has no
- * equivalent (`lower()` is ASCII-only), so the comparison runs in JS against
- * the single shared normalizer rather than a SQL predicate that can drift.
+ * layer decoupled from the subagent domain types. It reaches into that domain
+ * for exactly two things, both to keep a SQL predicate from drifting away from
+ * the definition the manager uses: `normalizeSubagentLabel`, because label
+ * lookups have to fold the way the in-memory index folds and SQLite has no
+ * equivalent (`lower()` is ASCII-only), and `TERMINAL_STATUSES`, which decides
+ * which statuses a similarity scan reads as finished.
  */
 
-import { normalizeSubagentLabel } from "../subagent/types.js";
+import {
+  normalizeSubagentLabel,
+  TERMINAL_STATUSES,
+} from "../subagent/types.js";
 import { rawAll, rawGet, rawRun } from "./raw-query.js";
 
 /** A durable subagent lifecycle record (camelCase mirror of the row). */
@@ -299,6 +303,144 @@ export function getSubagentRecordsByParent(
   ).map(rowToRecord);
 }
 
+/**
+ * Rows the similarity scan reads before it stops. The scan is bounded so a
+ * long-lived assistant cannot turn every spawn into a full-table read; a
+ * truncated window can only under-count, which is the safe direction for a
+ * caller that rate-limits on the count.
+ */
+const RECENT_SPAWN_SCAN_LIMIT = 500;
+
+/**
+ * The status a run has to hold to count as a repeat of already-done work. A
+ * failed, aborted, or interrupted run left no answer behind, so spawning its
+ * objective again is recovery rather than repetition, and counting those runs
+ * would hold the retry that is exactly the right move.
+ */
+const REUSABLE_SPAWN_STATUS = "completed";
+
+/**
+ * Statuses the scan skips: the run ended without an answer, so it is neither
+ * work already done nor work still under way. Derived from the terminal set so
+ * a new terminal status cannot silently read as in flight.
+ */
+const DEAD_END_SPAWN_STATUSES: readonly string[] = [
+  ...TERMINAL_STATUSES,
+].filter((status) => status !== REUSABLE_SPAWN_STATUS);
+
+/**
+ * Fold an objective to the form two spawns are compared in: lowercased and
+ * whitespace-collapsed. Callers normalize the incoming objective with this same
+ * function, so both sides of the comparison are folded by one implementation.
+ *
+ * The whole objective is compared, never a prefix. Batch work routinely shares
+ * a long instruction preamble and diverges only in its tail (the file,
+ * component, or ticket each run targets), and comparing prefixes reads that
+ * batch as one objective repeated. Comparing in full costs only the re-run
+ * whose wording changed, which is a missed catch by an advisory guard, while a
+ * batch folded together holds work the caller genuinely meant to run. The
+ * runaway shape this guard exists for is a burst of the SAME objective, which
+ * folds identically either way, so full comparison gives up nothing on the
+ * case that matters and keeps a legitimate fan-out running.
+ *
+ * The separate `context` spawn argument is not part of the key: a subagent row
+ * does not carry it (context, prompts, and trust are deliberately left off the
+ * durable record), so two spawns with one objective and different contexts
+ * still fold together. That residue is bounded by the guard being advisory:
+ * the caller is told what already ran and spawns anyway if it meant to.
+ */
+export function normalizeSpawnObjective(objective: string): string {
+  return objective.toLowerCase().replace(/\s+/gu, " ").trim();
+}
+
+/** How runs matching one normalized objective are distributed in a scope. */
+export interface SimilarSpawnTally {
+  /** Runs that completed, so their answer exists and can be read. */
+  count: number;
+  /** Summed `estimated_cost` of the completed rows. */
+  estimatedCost: number;
+  /**
+   * Runs still under way (pending, running, or awaiting input). Kept apart
+   * from `count` because they have produced nothing to read yet: they are
+   * evidence of duplicated work in progress, not of an available answer.
+   */
+  inFlight: number;
+}
+
+/** The two scopes a repeat spawn is judged against. */
+export interface RecentSimilarSpawns {
+  /** Matches spawned under the same parent conversation. */
+  conversation: SimilarSpawnTally;
+  /** Matches anywhere in this assistant; the table holds one assistant's rows. */
+  assistant: SimilarSpawnTally;
+}
+
+/**
+ * Tally the runs since `sinceMs` (an epoch cutoff) whose objective folds to
+ * `normalizedObjective`, both under `parentConversationId` and assistant-wide,
+ * split by whether each run finished with an answer or is still under way.
+ *
+ * Runs that ended without an answer are left out entirely: spawning their
+ * objective again is recovery rather than repetition. Advisor rows are left out
+ * too: an advisor consult blocks its caller and is not rate-limited, so its
+ * history must not count against a background spawn.
+ *
+ * Both scopes come from one bounded scan because the assistant-wide set
+ * contains the conversation's, so a second query would read the same rows
+ * twice.
+ *
+ * Rows hold the raw objective, so the fold has to happen on the column too.
+ * It runs in JS rather than SQL: SQLite's `lower()` folds ASCII only and has no
+ * whitespace-collapsing function, so a SQL predicate would disagree with
+ * {@link normalizeSpawnObjective} on exactly the objectives (accented, oddly
+ * spaced) a re-run is most likely to differ by.
+ */
+export function countRecentSimilarSpawns(args: {
+  parentConversationId: string;
+  normalizedObjective: string;
+  sinceMs: number;
+}): RecentSimilarSpawns {
+  const rows = rawAll<{
+    parent_conversation_id: string;
+    objective: string;
+    status: string;
+    estimated_cost: number;
+  }>(
+    "subagent:countRecentSimilar",
+    `SELECT parent_conversation_id, objective, status, estimated_cost FROM subagents
+       WHERE created_at >= ? AND role <> 'advisor'
+         AND status NOT IN (${DEAD_END_SPAWN_STATUSES.map(() => "?").join(", ")})
+       ORDER BY created_at DESC
+       LIMIT ?`,
+    args.sinceMs,
+    ...DEAD_END_SPAWN_STATUSES,
+    RECENT_SPAWN_SCAN_LIMIT,
+  );
+
+  const tally: RecentSimilarSpawns = {
+    conversation: { count: 0, estimatedCost: 0, inFlight: 0 },
+    assistant: { count: 0, estimatedCost: 0, inFlight: 0 },
+  };
+  const add = (scope: SimilarSpawnTally, row: (typeof rows)[number]): void => {
+    if (row.status === REUSABLE_SPAWN_STATUS) {
+      scope.count += 1;
+      scope.estimatedCost += row.estimated_cost;
+    } else {
+      scope.inFlight += 1;
+    }
+  };
+  for (const row of rows) {
+    if (normalizeSpawnObjective(row.objective) !== args.normalizedObjective) {
+      continue;
+    }
+    add(tally.assistant, row);
+    if (row.parent_conversation_id === args.parentConversationId) {
+      add(tally.conversation, row);
+    }
+  }
+  return tally;
+}
+
 /**
  * Delete every subagent record spawned under `parentConversationId`. A row
  * lives as long as its parent conversation, and the TTL sweep drops a child's

package/src/platform/managed-speech.test.ts

@@ -75,6 +75,26 @@ describe("managedSpeechTranscribe", () => {
     expect(JSON.parse(init.body as string)).not.toHaveProperty("source");
   });
 
+  test("sends the spoken language when one is given", async () => {
+    // The platform forwards this to Deepgram, which otherwise decodes the
+    // audio as English rather than detecting its language.
+    await managedSpeechTranscribe({
+      audio: AUDIO,
+      mimeType: "audio/wav",
+      language: "multi",
+    });
+    const [, init] = mockClient!.fetch.mock.calls[0] as [string, RequestInit];
+    expect(JSON.parse(init.body as string).language).toBe("multi");
+  });
+
+  test("omits language when not provided", async () => {
+    // An absent field and an empty one are different requests upstream, and
+    // the empty one fails the platform serializer.
+    await managedSpeechTranscribe({ audio: AUDIO, mimeType: "audio/wav" });
+    const [, init] = mockClient!.fetch.mock.calls[0] as [string, RequestInit];
+    expect(JSON.parse(init.body as string)).not.toHaveProperty("language");
+  });
+
   test("returns unavailable when no platform client resolves", async () => {
     mockClient = null;
     const result = await managedSpeechTranscribe({

package/src/platform/managed-speech.ts

@@ -90,6 +90,14 @@ export async function managedSpeechTranscribe(input: {
   audio: Buffer;
   mimeType: string;
   source?: string;
+  /**
+   * Spoken language to decode: a BCP-47 code, or `"multi"` for nova-3
+   * code-switching. Omitted means the platform sends none, which Deepgram
+   * decodes as English rather than detecting the language. Older platform
+   * builds that predate the field ignore it, so sending one is safe before
+   * the platform side deploys.
+   */
+  language?: string;
   signal?: AbortSignal;
 }): Promise<ManagedSpeechResult<ManagedSpeechTranscription>> {
   const resolved = await resolveClient();
@@ -107,6 +115,7 @@ export async function managedSpeechTranscribe(input: {
         audioBase64: input.audio.toString("base64"),
         mimeType: input.mimeType,
         ...(input.source !== undefined ? { source: input.source } : {}),
+        ...(input.language ? { language: input.language } : {}),
       }),
       signal: input.signal,
     },

package/src/plugin-api/__tests__/oauth-callback-url-export.test.ts

@@ -0,0 +1,29 @@
+/**
+ * Guards that `resolveOauthCallbackUrl` reaches plugins.
+ *
+ * The shim written into `<workspaceDir>/node_modules/@vellumai/plugin-api`
+ * re-binds whatever `Object.keys()` finds on the plugin-api namespace, so an
+ * export missing from `index.ts` is missing from every installed plugin with
+ * no other signal than a plugin failing to import it.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { PLUGIN_API_EXPORTS } from "../../embedded/plugin-api.js";
+import * as pluginApi from "../index.js";
+
+describe("plugin-api OAuth callback export", () => {
+  test("is exported from the plugin-api surface", () => {
+    expect(typeof pluginApi.resolveOauthCallbackUrl).toEqual("function");
+  });
+
+  test("is carried into the generated shim's binding list", () => {
+    expect(PLUGIN_API_EXPORTS).toContain("resolveOauthCallbackUrl");
+  });
+
+  test("takes no arguments, so a plugin cannot vary the URI", () => {
+    // The value a Client ID Metadata Document publishes and the value the
+    // host later authorizes with have to be the same string.
+    expect(pluginApi.resolveOauthCallbackUrl.length).toEqual(0);
+  });
+});

package/src/plugin-api/index.ts

@@ -173,6 +173,23 @@ export {
   CredentialResolutionError,
   resolveCredential,
 } from "./resolve-credential.js";
+// Resolve the public URL a third party should deliver to for one of the
+// plugin's own ingress routes. Which URL is correct depends on how the
+// assistant is reachable (a managed platform callback route, or a configured
+// public ingress), and `ingress.publicBaseUrl` alone does not decide it. Uses
+// the same resolution as `webhooks register`, and registers the callback route
+// on the managed branches. The plugin defaults to the one in context.
+export { resolveWebhookUrl, type WebhookUrlOptions } from "./webhook-url.js";
+// Resolve the redirect URI an authorization server should send a user back
+// to after consent. One shared route serves every OAuth flow in the
+// assistant, demultiplexed by OAuth `state`, so this takes no arguments and
+// returns the same URL for every caller and every attempt. A plugin needs it
+// when it publishes something that has to name the redirect URI ahead of the
+// flow, such as a Client ID Metadata Document, whose `redirect_uris` an
+// authorization server matches exactly. Throws when no public ingress is
+// configured and the assistant is not connected to the platform, which is the
+// case where no URL would work.
+export { resolveOauthCallbackUrl } from "../inbound/oauth-callback-url.js";
 // Resolve a provider for a call site (optionally overriding the profile) so a
 // plugin can run inference through the workspace's configured profiles and
 // credentials — managed-proxy or BYOK — without supplying its own API key.
@@ -317,6 +334,7 @@ export {
   deleteConversation,
   getConversation,
   getConversationDirPath,
+  getConversationProcessingStartedAt,
   getMessages,
   hasLexicalTokens,
   isConversationProcessing,
@@ -337,21 +355,26 @@ export { synthesizeText, TtsSynthesisError } from "../tts/synthesize-text.js";
 export type { TtsSynthesisResult } from "../tts/types.js";
 // Streaming speech-to-text — open a live transcription session against the
 // assistant's globally configured STT provider stack. The plugin feeds audio
-// chunks via `sendAudio` and receives partial/final transcript events through
-// the `start(onEvent)` callback, closing with `stop`. `SttStreamServerEvent`
-// and its variants type the events handed to `onEvent`; `SttErrorCategory`
-// classifies `error` events; `SttProviderId` names the resolved session's
-// provider.
+// chunks via `sendAudio` and receives transcript and turn-boundary events
+// through the `start(onEvent)` callback, closing with `stop`.
+// `SttStreamServerEvent` types the events handed to `onEvent`; every member of
+// that union is exported alongside it so a plugin can name each variant in an
+// exhaustive switch. `SttErrorCategory` classifies `error` events;
+// `SttProviderId` names the resolved session's provider.
 export type {
   StreamingTranscriber,
   SttErrorCategory,
   SttProviderId,
   SttStreamServerClosedEvent,
+  SttStreamServerEagerTurnEndEvent,
   SttStreamServerErrorEvent,
   SttStreamServerEvent,
   SttStreamServerFinalEvent,
   SttStreamServerFinalizedEvent,
   SttStreamServerPartialEvent,
+  SttStreamServerTurnEndEvent,
+  SttStreamServerTurnResumedEvent,
+  SttStreamServerTurnStartEvent,
 } from "../stt/types.js";
 export { openTranscriptionSession } from "./transcription-session.js";
 // Conversation agent-loop turn — run a full conversation turn (persist user

package/src/plugin-api/webhook-url.ts

@@ -0,0 +1,151 @@
+/**
+ * Public URL resolution for a plugin's own ingress route.
+ *
+ * A plugin that receives third-party webhooks has to tell the vendor where to
+ * deliver. Which URL is correct depends on how the assistant is reachable:
+ * a platform pod and a platform-connected assistant are served through a
+ * managed callback route, while a self-hosted deployment is served through its
+ * configured public ingress. `ingress.publicBaseUrl` alone does not decide it,
+ * because on a platform-connected assistant that value holds the Velay tunnel
+ * address, which is not where plugin routes are served.
+ *
+ * `resolveCallbackUrl` owns that decision for every caller in the codebase
+ * (`webhooks register`, the Telegram webhook manager). This exposes it to
+ * plugins so there is one implementation rather than one per plugin.
+ */
+
+import { createHash } from "node:crypto";
+
+import { getConfig } from "../config/loader.js";
+import { resolveCallbackUrl } from "../inbound/platform-callback-registration.js";
+import { getPublicBaseUrl } from "../inbound/public-ingress-urls.js";
+import { getCurrentPluginName } from "../plugins/plugin-execution-context.js";
+
+/**
+ * The namespace the gateway serves plugin ingress under. Fixed here rather
+ * than supplied by the caller, so a plugin cannot claim another's routes.
+ */
+const PLUGIN_WEBHOOK_PREFIX = "webhooks/plugins";
+
+/** Plugin directory names usable as a URL path segment. */
+const SAFE_PLUGIN_NAME = /^[a-z0-9][a-z0-9._-]*$/i;
+
+/**
+ * Route paths the gateway serves, matching `IngressRouteSchema` in
+ * `gateway/src/channels/plugin-ingress.ts`: relative, free of query, fragment
+ * and whitespace, canonical under percent-decoding, and carrying no `.` or
+ * `..` segment.
+ *
+ * The two must agree. A path this rejects but the gateway serves is a route a
+ * plugin can install and then never resolve a URL for.
+ */
+function isServableRoutePath(value: string): boolean {
+  if (value.length === 0 || value.endsWith("/")) {
+    return false;
+  }
+  if (!/^[^/?#\s][^?#\s]*$/.test(value)) {
+    return false;
+  }
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+    return false;
+  }
+  if (decoded !== value) {
+    return false;
+  }
+  return !value.split("/").some((seg) => seg === "." || seg === "..");
+}
+
+export interface WebhookUrlOptions {
+  /**
+   * Route path within the plugin's namespace, such as `"events-photon"`.
+   * Relative, with no leading slash.
+   */
+  path: string;
+  /**
+   * Plugin whose namespace the route belongs to.
+   *
+   * Defaults to the plugin in context, which covers hooks and tools. Supply it
+   * explicitly from a plugin route handler, where no context is established.
+   */
+  plugin?: string;
+  /** Human-readable label for the platform's admin display. */
+  sourceIdentifier?: string;
+}
+
+/**
+ * Registration type for one route.
+ *
+ * The platform keys a callback route by type, so two routes of one plugin need
+ * two types or the second registration replaces the first. The slug keeps the
+ * type legible in the platform's admin display and the digest keeps it unique:
+ * `events-v1` and `events_v1` share a slug and differ here.
+ */
+function registrationType(plugin: string, route: string): string {
+  const slug = route.replace(/[^a-z0-9]+/gi, "_");
+  const digest = createHash("sha256").update(route).digest("hex").slice(0, 8);
+  return `plugin_${plugin}_${slug}_${digest}`;
+}
+
+/**
+ * Drop a trailing slash from a resolved callback URL.
+ *
+ * The platform appends one to the callback URLs it hands back, and a provider
+ * given `.../events-comms/` delivers to that spelling verbatim. The gateway
+ * matches a plugin route against its declared path, which may never end in a
+ * slash (see `IngressRouteSchema`), so the slash comes off once here rather
+ * than at each plugin that registers a URL.
+ *
+ * Only the path is ever trimmed: this resolver passes no query parameters, and
+ * a URL carrying one is left alone rather than truncated.
+ */
+function withoutTrailingSlash(url: string): string {
+  if (url.includes("?") || url.includes("#")) {
+    return url;
+  }
+  return url.replace(/\/+$/, "");
+}
+
+/**
+ * Resolve the public URL a third party should deliver to for `path`.
+ *
+ * On the managed branches this registers a callback route with the platform,
+ * which is idempotent and matches what `assistant webhooks register` does.
+ *
+ * @throws when the plugin cannot be determined, when `path` is not one the
+ *   gateway would serve, or when no ingress is configured and the assistant is
+ *   not connected to the platform. That last case has no URL that would work,
+ *   and a plausible one would produce a vendor registration that silently
+ *   receives nothing.
+ */
+export async function resolveWebhookUrl(
+  options: WebhookUrlOptions,
+): Promise<string> {
+  const { path, sourceIdentifier } = options;
+  const plugin = options.plugin ?? getCurrentPluginName();
+
+  if (plugin === undefined) {
+    throw new Error(
+      "No plugin is in context; pass `plugin` to resolve a webhook URL.",
+    );
+  }
+  if (!SAFE_PLUGIN_NAME.test(plugin)) {
+    throw new Error(`Invalid plugin name for a webhook URL: "${plugin}"`);
+  }
+  if (!isServableRoutePath(path)) {
+    throw new Error(`Invalid plugin webhook path: "${path}"`);
+  }
+
+  const callbackPath = `${PLUGIN_WEBHOOK_PREFIX}/${plugin}/${path}`;
+
+  const resolved = await resolveCallbackUrl(
+    () => `${getPublicBaseUrl(getConfig())}/${callbackPath}`,
+    callbackPath,
+    registrationType(plugin, path),
+    undefined,
+    sourceIdentifier,
+  );
+  return withoutTrailingSlash(resolved);
+}

package/src/plugins/__tests__/installed-plugin-dirs.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Enumeration of installed plugin directories, including the realpath
+ * containment boundary that keeps a symlinked root pointing outside the
+ * plugins directory out of the list.
+ */
+
+import {
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+
+import { getWorkspacePluginsDir } from "../../util/platform.js";
+import { listInstalledPluginDirs } from "../installed-plugin-dirs.js";
+
+const pluginsDir = getWorkspacePluginsDir();
+const outsideRoot = mkdtempSync(join(tmpdir(), "installed-plugin-dirs-"));
+
+afterAll(() => {
+  rmSync(outsideRoot, { recursive: true, force: true });
+  rmSync(pluginsDir, { recursive: true, force: true });
+});
+
+/** A directory carrying the `package.json` that marks it as an install. */
+function makePluginDir(parent: string, name: string): string {
+  const dir = join(parent, name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "package.json"),
+    JSON.stringify({ name, version: "1.0.0" }),
+  );
+  return dir;
+}
+
+beforeEach(() => {
+  rmSync(pluginsDir, { recursive: true, force: true });
+  mkdirSync(pluginsDir, { recursive: true });
+});
+
+describe("listInstalledPluginDirs", () => {
+  test("lists real plugin directories and skips dot entries", () => {
+    makePluginDir(pluginsDir, "alpha");
+    makePluginDir(pluginsDir, ".hidden");
+    mkdirSync(join(pluginsDir, "no-manifest"), { recursive: true });
+
+    expect(listInstalledPluginDirs().map((p) => p.name)).toEqual(["alpha"]);
+  });
+
+  test("skips a symlinked plugin root that points outside the plugins dir", () => {
+    const escapee = makePluginDir(outsideRoot, "escapee");
+    symlinkSync(escapee, join(pluginsDir, "escapee"));
+    makePluginDir(pluginsDir, "contained");
+
+    // The plugin loader refuses to import from a root that resolves outside
+    // the plugins directory, so enumeration must not report it as installed:
+    // a caller acting on this list would arm and run code the loader would
+    // never activate.
+    expect(listInstalledPluginDirs().map((p) => p.name)).toEqual(["contained"]);
+  });
+
+  test("skips a symlink that aliases the plugins directory itself", () => {
+    symlinkSync(pluginsDir, join(pluginsDir, "self"));
+
+    expect(listInstalledPluginDirs()).toEqual([]);
+  });
+
+  test("keeps a symlinked plugin root that stays inside the plugins dir", () => {
+    const real = makePluginDir(pluginsDir, "real");
+    symlinkSync(real, join(pluginsDir, "alias"));
+
+    expect(
+      listInstalledPluginDirs()
+        .map((p) => p.name)
+        .sort(),
+    ).toEqual(["alias", "real"]);
+  });
+});