@vellumai/assistant 0.11.3 → 0.11.4-staging.1

package/src/runtime/routes/user-route-dispatcher.ts

@@ -27,9 +27,12 @@
  * shows no route depends on it.
  *
  * Modules are lazily loaded on first request and cached by file path +
- * mtime. When a file changes on disk, the next request reloads it via
- * Bun's dynamic `import()` with a cache-busting query parameter. A request
- * whose file does not exist 404s — nothing is registered ahead of time.
+ * mtime. When a file changes on disk, the next request evicts the whole
+ * source tree that file belongs to (plugin root, or the workspace
+ * `routes/` directory) and re-imports the entry. Cache-busting only the
+ * entry file would re-bind it to stale helpers still in Bun's registry.
+ * A request whose file does not exist 404s. Nothing is registered ahead
+ * of time.
  */
 
 import { statSync } from "node:fs";
@@ -46,6 +49,11 @@ import {
   buildDeprecatedRouteContext,
   type UserRouteContext,
 } from "./deprecated-route-context.js";
+import {
+  evictRouteSourceTree,
+  importRouteModule,
+  routeSourceRoot,
+} from "./user-route-import.js";
 import {
   resolveHandlerFile,
   resolveRouteLocation,
@@ -134,7 +142,7 @@ export class UserRouteDispatcher {
       ? resolveHandlerFile(location.routesDir, location.subPath)
       : null;
 
-    if (!filePath) {
+    if (!location || !filePath) {
       return httpError(
         "NOT_FOUND",
         `No route handler found for /x/${routePath}`,
@@ -146,7 +154,7 @@ export class UserRouteDispatcher {
       return this.dispatchViaHost(filePath, routePath, request);
     }
 
-    const mod = await this.loadModule(filePath);
+    const mod = await this.loadModule(filePath, location.routesDir);
     const method = request.method as HttpMethod;
     const handler = mod.handlers[method];
 
@@ -231,11 +239,15 @@ export class UserRouteDispatcher {
   /**
    * Load a handler module, using the mtime-based cache when possible.
    *
-   * On cache miss or stale mtime, the module is re-imported via Bun's
-   * dynamic `import()` with a cache-busting query parameter derived
-   * from the file's current mtime.
+   * On cache miss or stale mtime, every source file in the handler's tree
+   * is evicted first so a new entry cannot import a helper that is still
+   * the pre-upgrade module. Then the entry is re-imported with an mtime
+   * query parameter.
    */
-  private async loadModule(filePath: string): Promise<CachedModule> {
+  private async loadModule(
+    filePath: string,
+    routesDir: string,
+  ): Promise<CachedModule> {
     const stat = statSync(filePath);
     const mtimeMs = stat.mtimeMs;
 
@@ -244,11 +256,11 @@ export class UserRouteDispatcher {
       return cached;
     }
 
-    // Cache-bust Bun's module cache by appending mtime as a query param.
-    const mod = (await import(`${filePath}?t=${mtimeMs}`)) as Record<
-      string,
-      unknown
-    >;
+    const sourceRoot = routeSourceRoot(routesDir);
+    evictRouteSourceTree(sourceRoot);
+    this.dropCachedModulesUnder(sourceRoot);
+
+    const mod = await importRouteModule(filePath);
 
     const handlers: Partial<Record<HttpMethod, RouteHandler>> = {};
     for (const method of HTTP_METHODS) {
@@ -271,6 +283,19 @@ export class UserRouteDispatcher {
     return entry;
   }
 
+  /**
+   * Drop every cached handler under `sourceRoot`. Sibling routes must not
+   * keep closures over the helpers we just evicted.
+   */
+  private dropCachedModulesUnder(sourceRoot: string): void {
+    const prefix = sourceRoot.endsWith("/") ? sourceRoot : `${sourceRoot}/`;
+    for (const path of this.moduleCache.keys()) {
+      if (path === sourceRoot || path.startsWith(prefix)) {
+        this.moduleCache.delete(path);
+      }
+    }
+  }
+
   /**
    * Execute a handler function with a per-request timeout and error boundary.
    */

package/src/runtime/routes/user-route-import.ts

@@ -0,0 +1,108 @@
+/**
+ * Import a user/plugin route module so its helpers match the files on disk.
+ *
+ * Bun caches every imported helper independently. Cache-busting only the
+ * entry file (`import(file?t=mtime)`) re-binds it to whatever helpers are
+ * already in the registry. That is how a new route that imports a new export
+ * from `src/http.ts` 500s with "Export named 'requireNumber' not found" while
+ * `/frame` (still on the old http.ts surface) keeps answering 200.
+ *
+ * Hooks and tools already treat the whole plugin directory as the reload
+ * unit (`plugins/source-fingerprint.ts`). Routes must do the same: when the
+ * entry file's mtime moves, evict every source file in that tree before the
+ * next import, so the new entry cannot pair with a stale helper.
+ */
+
+import { statSync } from "node:fs";
+import { dirname, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { snapshotPluginSource } from "../../plugins/source-fingerprint.js";
+import { evictModule } from "../../plugins/surface-import.js";
+import { getWorkspaceRoutesDir } from "../../util/platform.js";
+
+/**
+ * Directory whose source files must stay mutually consistent with this
+ * handler. An installed or default plugin uses the plugin root (so `src/`
+ * helpers evict with `routes/`). Workspace routes use the workspace
+ * `routes/` directory.
+ */
+export function routeSourceRoot(routesDir: string): string {
+  if (routesDir === getWorkspaceRoutesDir()) {
+    return routesDir;
+  }
+  return dirname(routesDir);
+}
+
+/**
+ * Infer the source root from a handler path when the caller has no
+ * {@link routeSourceRoot} (the route-host worker only sees `filePath`).
+ */
+export function sourceRootForHandler(filePath: string): string {
+  const marker = `${sep}routes${sep}`;
+  const idx = filePath.lastIndexOf(marker);
+  if (idx !== -1) {
+    return filePath.slice(0, idx);
+  }
+  return dirname(filePath);
+}
+
+/**
+ * Drop every source module under `sourceRoot` from the runtime registry,
+ * including query-string aliases (`file.ts?t=mtime`) the dispatcher uses to
+ * cache-bust the entry file.
+ */
+export function evictRouteSourceTree(sourceRoot: string): void {
+  const { evictionPaths } = snapshotPluginSource(sourceRoot);
+  for (const path of evictionPaths) {
+    evictModule(path);
+  }
+  evictRegistryAliases(sourceRoot);
+}
+
+function evictRegistryAliases(sourceRoot: string): void {
+  const prefix = sourceRoot.endsWith("/") ? sourceRoot : `${sourceRoot}/`;
+  const fileUrlPrefix = pathToFileURL(prefix).href;
+  for (const key of Object.keys(require.cache)) {
+    if (!keyBelongsToTree(key, sourceRoot, prefix, fileUrlPrefix)) {
+      continue;
+    }
+    delete require.cache[key];
+  }
+}
+
+function keyBelongsToTree(
+  key: string,
+  sourceRoot: string,
+  prefix: string,
+  fileUrlPrefix: string,
+): boolean {
+  const bare = key.split("?")[0] ?? key;
+  if (bare.includes("/node_modules/") || bare.includes("/node_modules?")) {
+    return false;
+  }
+  if (
+    bare === sourceRoot ||
+    bare.startsWith(prefix) ||
+    bare.startsWith(fileUrlPrefix)
+  ) {
+    return true;
+  }
+  if (bare.startsWith("file:")) {
+    try {
+      const asPath = fileURLToPath(bare);
+      return asPath === sourceRoot || asPath.startsWith(prefix);
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+/** Dynamic-import a handler, cache-busted by the file's current mtime. */
+export async function importRouteModule(
+  filePath: string,
+): Promise<Record<string, unknown>> {
+  const mtimeMs = statSync(filePath).mtimeMs;
+  return (await import(`${filePath}?t=${mtimeMs}`)) as Record<string, unknown>;
+}

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.
  *

package/src/stt/types.ts

@@ -23,6 +23,11 @@
 export type SttProviderId =
   | "openai-whisper"
   | "deepgram"
+  /**
+   * Deepgram's Flux conversational speech model. Shares the `deepgram`
+   * credential and is streaming-only: Flux has no batch endpoint.
+   */
+  | "deepgram-flux"
   | "google-gemini"
   | "xai"
   | "vellum";
@@ -65,6 +70,26 @@ export type ConversationStreamingMode =
   | "incremental-batch"
   | "none";
 
+/**
+ * Turn-detection support mode.
+ *
+ * Describes whether a provider decides end-of-turn itself, in-band with the
+ * audio it is already transcribing, rather than leaving the boundary to the
+ * session's local silence timer and front-door hold verdict.
+ *
+ * - `"provider"`: the provider emits turn lifecycle events (`turn-start`,
+ *   `turn-end`) on its transcript stream, and a live-voice session may let
+ *   those events commit the turn.
+ * - `"none"`: the provider transcribes only; the local silence boundary owns
+ *   end-of-turn.
+ *
+ * A provider declaring `"provider"` should number its turns: the staleness
+ * check prefers the turn index carried on the event, and degrades to the
+ * session's local VAD generation counter when one is absent, which understates
+ * the recorded latency for a turn the caller resumed and stopped again.
+ */
+export type SttTurnDetectionMode = "provider" | "none";
+
 // ---------------------------------------------------------------------------
 // Boundary identifier
 // ---------------------------------------------------------------------------
@@ -245,6 +270,10 @@ export type SttStreamServerEvent =
   | SttStreamServerPartialEvent
   | SttStreamServerFinalEvent
   | SttStreamServerFinalizedEvent
+  | SttStreamServerTurnStartEvent
+  | SttStreamServerEagerTurnEndEvent
+  | SttStreamServerTurnResumedEvent
+  | SttStreamServerTurnEndEvent
   | SttStreamServerErrorEvent
   | SttStreamServerClosedEvent;
 
@@ -314,6 +343,80 @@ export interface SttStreamServerFinalizedEvent {
   readonly type: "finalized";
 }
 
+// ---------------------------------------------------------------------------
+// Turn-detection events
+//
+// Consumers that ignore these keep committing transcripts from `final`
+// exactly as they do without a turn-detecting provider.
+// ---------------------------------------------------------------------------
+
+/**
+ * The provider's turn model detected the start of a user turn.
+ *
+ * Emitted only by providers with model-integrated turn detection; providers
+ * without it never emit these.
+ */
+export interface SttStreamServerTurnStartEvent {
+  readonly type: "turn-start";
+  /**
+   * Provider's index for the turn being opened, monotonically increasing
+   * within a stream. Undefined when the provider does not number its turns.
+   */
+  readonly turnIndex?: number;
+}
+
+/**
+ * The provider's turn model speculates the user has finished, ahead of its
+ * committed end-of-turn decision. A {@link SttStreamServerTurnResumedEvent}
+ * retracts the speculation; a {@link SttStreamServerTurnEndEvent} confirms it.
+ *
+ * Emitted only by providers with model-integrated turn detection; providers
+ * without it never emit these.
+ */
+export interface SttStreamServerEagerTurnEndEvent {
+  readonly type: "eager-turn-end";
+  /** Transcript text as of the speculated turn end. */
+  readonly text: string;
+}
+
+/**
+ * The user kept speaking after an {@link SttStreamServerEagerTurnEndEvent},
+ * retracting the speculated turn end.
+ *
+ * Emitted only by providers with model-integrated turn detection; providers
+ * without it never emit these.
+ */
+export interface SttStreamServerTurnResumedEvent {
+  readonly type: "turn-resumed";
+}
+
+/**
+ * The provider's turn model committed an end of turn: the user has finished
+ * speaking and a reply can be dispatched.
+ *
+ * Emitted only by providers with model-integrated turn detection; providers
+ * without it never emit these.
+ */
+export interface SttStreamServerTurnEndEvent {
+  readonly type: "turn-end";
+  /** Committed transcript text for the completed turn. */
+  readonly text: string;
+  /**
+   * Provider-emitted end-of-turn confidence in [0, 1]. Undefined when the
+   * provider does not surface a score.
+   */
+  readonly confidence?: number;
+  /**
+   * Provider's index for the turn being closed, matching the
+   * {@link SttStreamServerTurnStartEvent} that opened it. A consumer can
+   * compare it against the newest turn it has seen opened to tell an
+   * end-of-turn for the turn still in progress from one the provider has
+   * already superseded. Undefined when the provider does not number its
+   * turns.
+   */
+  readonly turnIndex?: number;
+}
+
 /** An error occurred during streaming transcription. */
 export interface SttStreamServerErrorEvent {
   readonly type: "error";

package/src/subagent/manager.ts

@@ -705,9 +705,7 @@ export class SubagentManager {
     // Inherit the parent's *turn* trust ahead of its conversation-level slot:
     // the slot holds whichever actor sent most recently, so a spawn during one
     // actor's turn would otherwise run under another's privileges.
-    const parentTurnTrust =
-      parentConversation?.currentTurnTrustContext ??
-      parentConversation?.trustContext;
+    const parentTurnTrust = parentConversation?.getTurnOrRestingTrust();
     if (config.trustContext) {
       conversation.setTrustContext({ ...config.trustContext });
     } else if (parentTurnTrust) {

package/src/subagent/types.ts

@@ -483,12 +483,13 @@ export const SUBAGENT_ROLE_REGISTRY: Record<SubagentRole, SubagentRoleConfig> =
       skillIds: [],
       systemPromptPreamble: [
         "You are a research subagent with read-only access: search the web, read and search files, and recall memories. There is no shell, and you cannot write or edit files.",
-        // `file_read` takes no default line limit and its results are exempt
-        // from result-time spooling, so a full body rides every LLM call until
-        // the turn ends. Telling the role to read whole files makes that the
-        // default shape of a research turn, and this role now covers the
-        // traffic three roles used to. The anti-slicing intent stays: one pass
-        // over the range that is needed rather than many small ones.
+        // `file_read` returns the first DEFAULT_READ_LINE_LIMIT (2000) lines
+        // unless a limit is passed, with a truncation notice naming the resume
+        // offset, and oversized results spool to .tool-results/ like any other
+        // tool's (only re-reads of spooled content stay inline). So a ranged
+        // read is both the cheap shape and the one that avoids a spool
+        // round-trip. The anti-slicing intent stays: one pass over the range
+        // that is needed rather than many small ones.
         "Working method: use code_search to search file contents across directories, file_list to enumerate paths, and file_read to read files and logs. Prefer broad code_search queries across a directory over one-symbol-at-a-time queries, and read the range you need in one pass rather than many small slices.",
         "Send notify_parent (urgency 'important') as soon as each finding is confirmed, so progress survives interruption.",
         "Your final message is the deliverable: a compact report that answers the objective, gives the evidence behind each claim (file:line references, URLs, or quotes), and names what you could not determine. For a root-cause investigation, use the sections Symptom, Root cause, Evidence, Suggested fix, Open questions.",