@vellumai/assistant 0.11.2 → 0.11.3-staging.2

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/index.ts

@@ -173,6 +173,13 @@ 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 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 +324,7 @@ export {
   deleteConversation,
   getConversation,
   getConversationDirPath,
+  getConversationProcessingStartedAt,
   getMessages,
   hasLexicalTokens,
   isConversationProcessing,

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"]);
+  });
+});

package/src/plugins/__tests__/source-fingerprint.test.ts

@@ -7,6 +7,7 @@
 import {
   mkdirSync,
   mkdtempSync,
+  realpathSync,
   renameSync,
   rmSync,
   symlinkSync,
@@ -20,7 +21,10 @@ import { afterAll, describe, expect, test } from "bun:test";
 
 import { snapshotPluginSource } from "../source-fingerprint.js";
 
-const root = mkdtempSync(join(tmpdir(), "source-fingerprint-"));
+// Resolved: snapshots report realpaths, and the platform temp directory can
+// itself sit behind a link, so an unresolved fixture root would make every
+// fixture path an alias of itself.
+const root = realpathSync(mkdtempSync(join(tmpdir(), "source-fingerprint-")));
 
 afterAll(() => {
   rmSync(root, { recursive: true, force: true });

package/src/plugins/collect-source-versions.ts

@@ -12,13 +12,11 @@
  * causes a spurious reload.
  */
 
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 
-import {
-  getWorkspaceHooksDir,
-  getWorkspacePluginsDir,
-} from "../util/platform.js";
+import { getWorkspaceHooksDir } from "../util/platform.js";
+import { listInstalledPluginDirs } from "./installed-plugin-dirs.js";
 import { snapshotPluginSource } from "./source-fingerprint.js";
 import type { PluginSourceVersion } from "./source-versions.js";
 
@@ -33,28 +31,7 @@ import type { PluginSourceVersion } from "./source-versions.js";
 export function collectSourceVersions(): Record<string, PluginSourceVersion> {
   const out: Record<string, PluginSourceVersion> = {};
 
-  const pluginsDir = getWorkspacePluginsDir();
-  let entries: string[] = [];
-  try {
-    entries = readdirSync(pluginsDir);
-  } catch {
-    // No plugins directory yet — nothing to watch there.
-  }
-  for (const entry of entries) {
-    if (entry.startsWith(".")) {
-      continue;
-    }
-    const dir = join(pluginsDir, entry);
-    try {
-      if (!statSync(dir).isDirectory()) {
-        continue;
-      }
-    } catch {
-      continue;
-    }
-    if (!existsSync(join(dir, "package.json"))) {
-      continue;
-    }
+  for (const { dir } of listInstalledPluginDirs()) {
     const snapshot = snapshotPluginSource(dir);
     out[dir] = {
       fingerprint: snapshot.fingerprint,

package/src/plugins/defaults/exploration-drift/hooks/post-tool-use.ts

@@ -4,7 +4,7 @@
  * the user, or the model re-issuing the exact same call — surface a notice
  * via `additionalContext` that coaches it to (a) give the user a brief
  * progress summary and (b) delegate the rest of the investigation to an
- * `investigator` subagent instead of continuing inline.
+ * `researcher` subagent instead of continuing inline.
  *
  * Motivation: a root-cause request investigated inline ran 167 sequential
  * bash calls in a single turn with no user-facing text, overflowed the
@@ -48,7 +48,7 @@
  * all observe identical history and compute the same streak). Entries are
  * dropped when the streak restarts.
  *
- * Subagent conversations are exempt: an investigator is *supposed* to dig at
+ * Subagent conversations are exempt: a researcher is *supposed* to dig at
  * length, and subagents cannot nest (`SUBAGENT_LIMITS.maxDepth`), so the
  * delegation advice would be wrong there. Subagents run under the
  * `subagentSpawn` call site, so the exemption is a cheap `ctx.callSite` read.
@@ -66,7 +66,7 @@ import type {
  * provider-only context, never to the user.
  */
 export const EXPLORATION_DRIFT_NUDGE_TEXT =
-  "<system_notice>You have made a long unbroken run of exploration tool calls (shell/file reads) without sending the user any text. Do two things now: (1) send the user a brief summary of what you have found so far — do not keep working silently; (2) if you are tracing a root cause or exploring code/logs at length, stop exploring inline and delegate the remainder to a subagent: call subagent_spawn with role 'investigator' and a precise objective. It will investigate in its own context window and return a compact root-cause report. Continuing inline floods this conversation's context and risks losing your findings before you can report them.</system_notice>";
+  "<system_notice>You have made a long unbroken run of exploration tool calls (shell/file reads) without sending the user any text. Do two things now: (1) send the user a brief summary of what you have found so far, do not keep working silently; (2) if you are tracing a root cause or exploring code/logs at length, stop exploring inline and delegate the remainder to a subagent: call subagent_spawn with role 'researcher' and a precise objective. It will investigate in its own context window and return a compact root-cause report. Continuing inline floods this conversation's context and risks losing your findings before you can report them.</system_notice>";
 
 /**
  * Canonical loop notice, parameterized on the repeated call. Firmer than the
@@ -77,7 +77,7 @@ export function explorationLoopNudgeText(
   toolName: string,
   repeatCount: number,
 ): string {
-  return `<system_notice>You have issued this exact ${toolName} call ${repeatCount} times in the current run of exploration tool calls. Repeating an identical read-only call yields no new information — you are likely stuck. Do two things now: (1) send the user a brief summary of what you have found so far and what you are still missing — do not keep working silently; (2) stop exploring inline and delegate the remaining investigation to a subagent: call subagent_spawn with role 'investigator' and a precise objective that includes what you have already checked and ruled out. It will investigate in its own context window and return a compact root-cause report. Do not re-issue this call again.</system_notice>`;
+  return `<system_notice>You have issued this exact ${toolName} call ${repeatCount} times in the current run of exploration tool calls. Repeating an identical read-only call yields no new information, you are likely stuck. Do two things now: (1) send the user a brief summary of what you have found so far and what you are still missing, do not keep working silently; (2) stop exploring inline and delegate the remaining investigation to a subagent: call subagent_spawn with role 'researcher' and a precise objective that includes what you have already checked and ruled out. It will investigate in its own context window and return a compact root-cause report. Do not re-issue this call again.</system_notice>`;
 }
 
 /**
@@ -308,7 +308,7 @@ const postToolUse: HookFunction<PostToolUseContext> = async (ctx) => {
       trigger: loopNudge ? "loop" : "long-dig",
       ...(loopNudge ? { repeatCount: loopRepeatCount } : {}),
     },
-    "Exploration drift detected — nudging summary + investigator delegation",
+    "Exploration drift detected: nudging summary + researcher delegation",
   );
   ctx.additionalContext = ctx.additionalContext
     ? `${ctx.additionalContext}\n${nudgeText}`

package/src/plugins/defaults/exploration-drift/package.json

@@ -1,7 +1,7 @@
 {
   "name": "default-exploration-drift",
   "version": "1.0.0",
-  "description": "First-party default plugin contributing a post-tool-use hook that nudges the model to summarize and delegate to an investigator subagent when a turn accumulates a long run of exploration tool calls, or (on loop-prone models) re-issues an identical exploration call.",
+  "description": "First-party default plugin contributing a post-tool-use hook that nudges the model to summarize and delegate to a researcher subagent when a turn accumulates a long run of exploration tool calls, or (on loop-prone models) re-issues an identical exploration call.",
   "private": true,
   "license": "MIT",
   "type": "module",

package/src/plugins/defaults/image-recovery/hooks/post-model-call.ts

@@ -44,7 +44,7 @@ const postModelCall: HookFunction<PostModelCallContext> = async (ctx) => {
     isRecoverableImageError(ctx.error.message) &&
     !isImageRecoveryAttempted(ctx.conversationId)
   ) {
-    const { messages, changed } = recoverUnsendableImages(ctx.messages);
+    const { messages, changed } = await recoverUnsendableImages(ctx.messages);
     // A rejection can be classified as recoverable yet leave nothing to fix —
     // e.g. a media-type mismatch on a format the sniffer cannot identify. Retrying
     // an unchanged history would resend the identical rejected image and surface a
@@ -59,7 +59,9 @@ const postModelCall: HookFunction<PostModelCallContext> = async (ctx) => {
     // turns, so a persistence failure must never abort the retry that is about
     // to run — log it and continue with the in-memory recovery.
     try {
-      const rewritten = persistUnsendableImageDowngrades(ctx.conversationId);
+      const rewritten = await persistUnsendableImageDowngrades(
+        ctx.conversationId,
+      );
       if (rewritten > 0) {
         ctx.logger.info(
           { plugin: "image-recovery", rewritten },