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

package/src/tools/host-filesystem/read.ts

@@ -11,13 +11,14 @@ import {
   readAudioFile,
 } from "../shared/filesystem/audio-read.js";
 import {
-  DEFAULT_READ_LINE_LIMIT,
   FileSystemOps,
+  READ_CHAR_BUDGET,
 } from "../shared/filesystem/file-ops-service.js";
 import {
   IMAGE_EXTENSIONS,
   readImageFile,
 } from "../shared/filesystem/image-read.js";
+import { legacyReadArgsError } from "../shared/filesystem/legacy-read-args.js";
 import { hostPolicy } from "../shared/filesystem/path-policy.js";
 import {
   invalidToolInputResult,
@@ -32,9 +33,9 @@ import type {
 /**
  * Model-input schema, the single source for both runtime validation (via
  * `TOOL_INPUT_SCHEMAS`) and the advertised `input_schema` below — mirrors
- * `filesystem/read.ts`. `offset`/`limit` catch to `undefined` so a
- * non-numeric value falls back to the default line window instead of failing
- * the call; `target_client_id` catches so a non-string (or empty) value means
+ * `filesystem/read.ts`. `start_index`/`max_chars` catch to `undefined` so a
+ * non-numeric value falls back to the default character window instead of
+ * failing the call; `target_client_id` catches so a non-string (or empty) value means
  * "untargeted".
  */
 export const hostFileReadInputSchema = z.looseObject({
@@ -44,14 +45,16 @@ export const hostFileReadInputSchema = z.looseObject({
     .describe(
       "Absolute path on the guardian's device, which is a separate filesystem from your workspace, to read.",
     ),
-  offset: z
+  start_index: z
     .number()
-    .describe("Line number to start reading from (1-indexed)")
+    .describe("Character to start reading from (0-indexed). Text files only.")
     .optional()
     .catch(undefined),
-  limit: z
+  max_chars: z
     .number()
-    .describe("Maximum number of lines to read (defaults to 2000)")
+    .describe(
+      "Maximum number of characters to read. Defaults to 20000, which is also the ceiling. Text files only.",
+    )
     .optional()
     .catch(undefined),
   target_client_id: z
@@ -66,7 +69,7 @@ export const hostFileReadInputSchema = z.looseObject({
 export const hostFileReadTool = {
   name: "host_file_read",
   description:
-    "Read the contents of a file on your guardian's device, including images (JPEG, PNG, GIF, WebP) and audio (MP3, WAV, OGG, FLAC, AAC, M4A). Text reads return the first 2000 lines unless you pass `limit`; when a read stops short the result says so, and `offset` pages on from there. For files on your own machine, use file_read instead.",
+    "Read the contents of a file on your guardian's device, including images (JPEG, PNG, GIF, WebP) and audio (MP3, WAV, OGG, FLAC, AAC, M4A). Text reads return the first 20000 characters unless you pass `max_chars`; when a read stops short the result says so, and `start_index` pages on from there. For files on your own machine, use file_read instead.",
   category: "host-filesystem",
   executionTarget: "host",
   defaultRiskLevel: RiskLevel.Medium,
@@ -81,12 +84,12 @@ export const hostFileReadTool = {
     if (!parsed.success) {
       return invalidToolInputResult("host_file_read", parsed.error);
     }
-    const { path: rawPath, offset } = parsed.data;
+    const { path: rawPath, start_index: startIndex } = parsed.data;
     // Resolve the default here rather than leaving it to the read, so the
     // proxied branch below is bounded by the same window as the local one. A
-    // proxied read that sent no limit would stream a whole host file across
+    // proxied read that sent no budget would stream a whole host file across
     // the bridge before anything could trim it.
-    const limit = parsed.data.limit ?? DEFAULT_READ_LINE_LIMIT;
+    const maxChars = parsed.data.max_chars ?? READ_CHAR_BUDGET;
 
     const targetClientId =
       parsed.data.target_client_id !== ""
@@ -153,8 +156,8 @@ export const hostFileReadTool = {
         {
           operation: "read",
           path: rawPath,
-          offset,
-          limit,
+          startIndex,
+          maxChars,
           targetClientId,
         },
         context.conversationId,
@@ -181,9 +184,18 @@ export const hostFileReadTool = {
       return readAudioFile(pathCheck.resolved);
     }
 
+    const legacyArgs = legacyReadArgsError("host_file_read", input);
+    if (legacyArgs !== undefined) {
+      return { content: legacyArgs, isError: true };
+    }
+
     const ops = new FileSystemOps(hostPolicy);
 
-    const result = await ops.readFileSafe({ path: rawPath, offset, limit });
+    const result = await ops.readFileSafe({
+      path: rawPath,
+      startIndex,
+      maxChars,
+    });
 
     if (!result.ok) {
       const { error } = result;

package/src/tools/network/url-safety.ts

@@ -1,23 +1,16 @@
 import { lookup } from "node:dns/promises";
 
-export type ResolveHostAddresses = (hostname: string) => Promise<string[]>;
+import {
+  looksLikeHostPortShorthand,
+  looksLikePathOnlyInput,
+} from "@vellumai/service-contracts/url-normalization";
 
-export function looksLikeHostPortShorthand(value: string): boolean {
-  if (/^\[[0-9a-fA-F:.%]+\]:\d+(?:[/?#]|$)/.test(value)) {
-    return true;
-  }
-  return /^[^/?#@\s:]+:\d+(?:[/?#]|$)/.test(value);
-}
+export type ResolveHostAddresses = (hostname: string) => Promise<string[]>;
 
-export function looksLikePathOnlyInput(value: string): boolean {
-  return (
-    value.startsWith("/") ||
-    value.startsWith("./") ||
-    value.startsWith("../") ||
-    value.startsWith("?") ||
-    value.startsWith("#")
-  );
-}
+// The URL input-shape predicates are defined once, beside the canonicalizer
+// the gateway builds trust-rule patterns with, so what counts as a `host:port`
+// or a path here is what counts there. Re-exported for existing consumers.
+export { looksLikeHostPortShorthand, looksLikePathOnlyInput };
 
 export function parseUrl(input: unknown): URL | null {
   if (typeof input !== "string") {

package/src/tools/permission-checker.ts

@@ -1,13 +1,18 @@
+import type {
+  RiskAllowlistOption,
+  RiskDirectoryScopeOption,
+  RiskPatternScopeOption,
+} from "@vellumai/gateway-client";
+
 import { getIsContainerized } from "../config/env-registry.js";
 import { mapApprovalProvenance } from "../permissions/approval-provenance.js";
 import { buildChannelPermissionCellQuery } from "../permissions/channel-permission-query.js";
 import {
   check,
   classifyRisk,
-  generateAllowlistOptions,
   generateScopeOptions,
-  getCachedAssessment,
   isDynamicSkillLoadInvocation,
+  type RiskClassificationWithMeta,
 } from "../permissions/checker.js";
 import { getAutoApproveThreshold } from "../permissions/gateway-threshold-reader.js";
 import type { PermissionPrompter } from "../permissions/prompter.js";
@@ -37,19 +42,15 @@ export type PermissionDecision =
       decision: string;
       riskLevel: string;
       wasPrompted?: boolean;
-      /** ID of the trust rule that matched this invocation (if any). Always set when a rule matched, even for non-classifier tools where riskMeta is absent. */
+      /** ID of the trust rule that matched this invocation (if any). */
       matchedTrustRuleId?: string;
-      /** Risk metadata from the classifier assessment cache (when available). */
-      riskMeta?: {
+      /** Risk metadata from the invocation's classification. */
+      riskMeta: {
         riskLevel: string;
         riskReason: string;
-        riskScopeOptions: Array<{ pattern: string; label: string }>;
-        riskAllowlistOptions?: Array<{
-          label: string;
-          description: string;
-          pattern: string;
-        }>;
-        riskDirectoryScopeOptions?: Array<{ scope: string; label: string }>;
+        riskScopeOptions: RiskPatternScopeOption[];
+        riskAllowlistOptions?: RiskAllowlistOption[];
+        riskDirectoryScopeOptions?: RiskDirectoryScopeOption[];
         isContainerized?: boolean;
       };
       approvalMode?: ApprovalMode;
@@ -61,19 +62,15 @@ export type PermissionDecision =
       decision: string;
       riskLevel: string;
       content: string;
-      /** ID of the trust rule that matched this invocation (if any). Always set when a rule matched, even for non-classifier tools where riskMeta is absent. */
+      /** ID of the trust rule that matched this invocation (if any). */
       matchedTrustRuleId?: string;
-      /** Risk metadata from the classifier assessment cache (when available). */
-      riskMeta?: {
+      /** Risk metadata from the invocation's classification. */
+      riskMeta: {
         riskLevel: string;
         riskReason: string;
-        riskScopeOptions: Array<{ pattern: string; label: string }>;
-        riskAllowlistOptions?: Array<{
-          label: string;
-          description: string;
-          pattern: string;
-        }>;
-        riskDirectoryScopeOptions?: Array<{ scope: string; label: string }>;
+        riskScopeOptions: RiskPatternScopeOption[];
+        riskAllowlistOptions?: RiskAllowlistOption[];
+        riskDirectoryScopeOptions?: RiskDirectoryScopeOption[];
         isContainerized?: boolean;
       };
       approvalMode?: ApprovalMode;
@@ -89,10 +86,13 @@ export class PermissionChecker {
   }
 
   /**
-   * Run risk classification, trust rule evaluation, and (if needed) user
-   * prompting for a tool invocation. Returns whether the tool is allowed
-   * to execute, along with the decision string and risk level for lifecycle
-   * event reporting.
+   * Run trust rule evaluation and (if needed) user prompting for a tool
+   * invocation. Returns whether the tool is allowed to execute, along with
+   * the decision string and risk level for lifecycle event reporting.
+   *
+   * `classification` is the invocation's gateway classification when the
+   * executor already holds it (it classifies once, before its gates); absent
+   * that, the same input is classified here.
    */
   async checkPermission(
     name: string,
@@ -113,10 +113,11 @@ export class PermissionChecker {
         }
       | undefined
     >,
+    classification?: RiskClassificationWithMeta,
   ): Promise<PermissionDecision> {
     // Sandbox/host routing for the prompt comes from the tool's manifest.
     const executionTarget = resolveExecutionTarget(tool);
-    const { level: risk, reason: riskReason } = await classifyRisk(
+    classification ??= await classifyRisk(
       name,
       input,
       context.workingDir,
@@ -124,26 +125,19 @@ export class PermissionChecker {
       undefined,
       context.signal,
     );
+    const { level: risk, reason: riskReason } = classification;
     const riskLevel: string = risk;
 
-    // Look up the cached assessment to extract risk metadata for the tool result.
-    // This is populated by classifyRisk() for classifier-backed tools (bash, file, web, skill).
-    // For tools without classifiers (e.g. MCP tools), the cache returns undefined.
-    const cachedAssessment = getCachedAssessment(name, input);
-    const riskMeta = cachedAssessment
-      ? {
-          riskLevel: cachedAssessment.riskLevel,
-          riskReason: cachedAssessment.reason,
-          // Display ladder (regex patterns — internal only, not for save).
-          riskScopeOptions: cachedAssessment.scopeOptions,
-          // Save ladder (Minimatch globs — what the gateway matches against).
-          // Populated for classifiers that produce allowlist options
-          // (bash, file, skill); undefined otherwise.
-          riskAllowlistOptions: cachedAssessment.allowlistOptions,
-          riskDirectoryScopeOptions: cachedAssessment.directoryScopeOptions,
-          isContainerized: getIsContainerized(),
-        }
-      : undefined;
+    const riskMeta = {
+      riskLevel: classification.level,
+      riskReason: classification.reason,
+      // Display ladder: bash only, internal, never persisted as a rule.
+      riskScopeOptions: classification.scopeOptions,
+      // Save ladder: the patterns the gateway matches a rule by, exactly.
+      riskAllowlistOptions: classification.allowlistOptions,
+      riskDirectoryScopeOptions: classification.directoryScopeOptions,
+      isContainerized: getIsContainerized(),
+    };
 
     // Wrap the rest of permission evaluation so that any exception
     // carries the classified risk level back to the caller. Without
@@ -158,6 +152,7 @@ export class PermissionChecker {
         policyContext,
         undefined,
         context.signal,
+        classification,
       );
 
       // Every threshold read for this invocation must consult the same
@@ -240,7 +235,7 @@ export class PermissionChecker {
       if (
         context.isInteractive === false &&
         isDynamicSkillLoadInvocation(name, input) &&
-        getCachedAssessment(name, input)?.matchType !== "user_rule"
+        classification.matchType !== "user_rule"
       ) {
         log.info(
           { toolName: name, riskLevel },
@@ -385,11 +380,7 @@ export class PermissionChecker {
           context.workingDir,
         );
         const promptOptions = {
-          allowlistOptions: await generateAllowlistOptions(
-            name,
-            input,
-            context.signal,
-          ),
+          allowlistOptions: classification.allowlistOptions ?? [],
           scopeOptions: generateScopeOptions(context.workingDir, name),
           persistentDecisionsAllowed: !context.requireFreshApproval,
         };
@@ -410,7 +401,7 @@ export class PermissionChecker {
           context.toolUseId,
           riskReason,
           getIsContainerized(),
-          cachedAssessment?.directoryScopeOptions,
+          classification.directoryScopeOptions,
         );
 
         const decision = response.decision;

package/src/tools/registry.ts

@@ -431,7 +431,8 @@ export function unregisterPluginTools(pluginName: string): void {
  * {@link import("../plugins/mtime-cache.js").getActiveUserPluginTools} and diffs
  * the result into the registry: plugins that vanished are unregistered, new
  * plugins register, and a plugin whose per-tool source mtimes moved is
- * re-registered. Mirrors how hooks resolve through `getUserHookEntriesFor`.
+ * re-registered. Mirrors how hooks resolve through `getUserHookEntriesFor`
+ * in `hooks/registry.ts`.
  *
  * This is a pure read of the plugin cache — it does NOT reconcile the cache
  * against the source-versions sentinel, so it never activates a plugin or runs

package/src/tools/shared/filesystem/file-ops-service.ts

@@ -78,26 +78,55 @@ function pathError(
 }
 
 /**
- * Lines returned by a read that names no `limit`. Without a default the read
- * returns the whole file, and a file-read result is honored in full for the
- * rest of the turn (see `isSpoolEligible` in `context/tool-result-spool.ts`),
- * so one unbounded read of a large file rides every subsequent LLM call in
- * that turn. The cap bounds that; `offset`/`limit` page past it, and
- * {@link truncationNotice} tells the model when it is looking at a window
- * rather than the whole file.
+ * Characters returned by a read that names no `max_chars`. Stays under
+ * `THRESHOLD_CHARS` in `context/post-turn-tool-result-truncation.ts`, which
+ * spools any larger tool result to disk and replaces it inline with a short
+ * stub, so a default read returns content rather than a stub.
  */
-export const DEFAULT_READ_LINE_LIMIT = 2000;
+export const READ_CHAR_BUDGET = 20_000;
 
 /**
- * Trailing marker appended when a read stops short of the last line. Silent
- * truncation is the failure mode worth avoiding: a model that cannot tell a
- * window from a whole file reasons about code it never saw.
+ * Trailing marker appended when a read stops short of the end of the file. A
+ * model that cannot tell a window from a whole file reasons about code it
+ * never saw.
  */
 function truncationNotice(
-  lastLineReturned: number,
-  totalLines: number,
+  start: number,
+  end: number,
+  totalChars: number,
 ): string {
-  return `\n\n[Truncated: showing through line ${lastLineReturned} of ${totalLines}. Read on with offset=${lastLineReturned + 1}, or pass an explicit limit.]`;
+  return `\n\n[Truncated: characters ${start}-${end} of ${totalChars}. Read on with start_index=${end}.]`;
+}
+
+const isHighSurrogate = (code: number): boolean =>
+  code >= 0xd800 && code <= 0xdbff;
+const isLowSurrogate = (code: number): boolean =>
+  code >= 0xdc00 && code <= 0xdfff;
+
+/**
+ * Character window that never splits a surrogate pair. A split leaves a lone
+ * half at each edge, and each encodes to U+FFFD, so the character is lost from
+ * both this window and the next one paged in after it.
+ */
+export function surrogateSafeWindow(
+  total: number,
+  charCodeAt: (index: number) => number,
+  requestedStart: number,
+  maxChars: number,
+): { start: number; end: number } {
+  let start = Math.max(0, Math.min(requestedStart, total));
+  if (start > 0 && start < total && isLowSurrogate(charCodeAt(start))) {
+    start -= 1;
+  }
+
+  let end = Math.min(total, start + maxChars);
+  if (end > start && end < total && isHighSurrogate(charCodeAt(end - 1))) {
+    // Backing off would empty a one-character window, which stalls paging on
+    // the same offset, so take the whole pair instead.
+    end = end - 1 > start ? end - 1 : Math.min(total, end + 1);
+  }
+
+  return { start, end };
 }
 
 export class FileSystemOps {
@@ -139,28 +168,27 @@ export class FileSystemOps {
 
     try {
       const raw = await readFile(filePath, "utf-8");
-      const lines = raw.split("\n");
-
-      const offset = (input.offset ?? 1) - 1;
-      const start = Math.max(0, offset);
-      const limit = input.limit ?? DEFAULT_READ_LINE_LIMIT;
-      const selected = lines.slice(start, offset + limit);
-
-      const numbered = selected
-        .map((line, i) => {
-          const lineNum = offset + i + 1;
-          return `${String(lineNum).padStart(6)}  ${line}`;
-        })
-        .join("\n");
-
-      // Only when the window stops before the last line. An empty window means
-      // the caller paged past the end or asked for nothing, which is not a
-      // truncated read.
-      const lastLineReturned = start + selected.length;
+
+      // A ceiling, not just a default: a larger window would be spooled to
+      // disk and replaced with a stub, returning less than this.
+      const maxChars = Math.min(
+        READ_CHAR_BUDGET,
+        Math.max(0, input.maxChars ?? READ_CHAR_BUDGET),
+      );
+      const { start, end } = surrogateSafeWindow(
+        raw.length,
+        (i) => raw.charCodeAt(i),
+        input.startIndex ?? 0,
+        maxChars,
+      );
+      const window = raw.slice(start, end);
+
+      // An empty window means the caller paged past the end or asked for
+      // nothing, which is not a truncated read.
       const content =
-        selected.length > 0 && lastLineReturned < lines.length
-          ? numbered + truncationNotice(lastLineReturned, lines.length)
-          : numbered;
+        window.length > 0 && end < raw.length
+          ? window + truncationNotice(start, end, raw.length)
+          : window;
 
       return { ok: true, value: { content } };
     } catch (err) {

package/src/tools/shared/filesystem/legacy-read-args.ts

@@ -0,0 +1,22 @@
+/**
+ * Guard for callers still passing the line-based `offset`/`limit` read
+ * arguments. The tool schemas are loose, so those keys parse and are then
+ * dropped, which would silently serve the start of the file to a caller that
+ * asked to page into the middle of it.
+ *
+ * There is no safe translation: `offset` counted lines and `start_index`
+ * counts characters, so mapping one onto the other would read the wrong
+ * region rather than fail. Naming the rename lets the caller correct itself.
+ */
+export function legacyReadArgsError(
+  toolName: string,
+  input: Record<string, unknown>,
+): string | undefined {
+  const usesLegacy = input.offset !== undefined || input.limit !== undefined;
+  const usesCurrent =
+    input.start_index !== undefined || input.max_chars !== undefined;
+  if (!usesLegacy || usesCurrent) {
+    return undefined;
+  }
+  return `Error: ${toolName} no longer takes \`offset\`/\`limit\` (lines). Use \`start_index\` (0-indexed characters) and \`max_chars\` instead.`;
+}

package/src/tools/shared/filesystem/types.ts

@@ -6,14 +6,14 @@ import type { FsError } from "./errors.js";
 
 export interface ReadInput {
   path: string;
-  /** 1-indexed line number to start reading from. */
-  offset?: number;
-  /** Maximum number of lines to read. */
-  limit?: number;
+  /** 0-indexed character to start reading from. */
+  startIndex?: number;
+  /** Maximum number of characters to read. */
+  maxChars?: number;
 }
 
 export interface ReadOutput {
-  /** The (possibly line-numbered) file content. */
+  /** The character window, with a truncation notice when it stops short. */
   content: string;
 }
 

package/src/tools/skills/scaffold-managed.ts

@@ -28,10 +28,20 @@ function sanitizeFrontmatterValue(value: string): string {
 }
 
 /**
- * Validate + normalize an optional string-array input (sanitize, drop blanks,
- * dedupe). Returns `{ error }` on the first invalid element, or `{ value }`
- * holding the normalized array (undefined when empty). Shared by the
- * includes / activation_hints / avoid_when inputs so they behave identically.
+ * Self-correcting error for a scaffold call with no activation hints. Matches
+ * the shape of the schema validator's required-field error, which is what a
+ * call through the registered tool hits first; this covers direct callers and
+ * an explicit empty list, which the schema's presence check accepts.
+ */
+const MISSING_ACTIVATION_HINTS =
+  'activation_hints is required: pass 1-4 short trigger phrases stating the intent this skill serves (for example "user asks to deploy staging") so it can be found later by intent, not just by name.';
+
+/**
+ * Validate + normalize a string-array input (sanitize, drop blanks, dedupe).
+ * Returns `{ error }` on the first invalid element, or `{ value }` holding
+ * the normalized array (undefined when absent or empty). Shared by the
+ * includes / activation_hints / avoid_when inputs so they behave identically;
+ * whether an absent value is acceptable is the caller's call.
  * Each element goes through sanitizeFrontmatterValue: activation_hints /
  * avoid_when are concatenated verbatim into capability memory text (see
  * buildSkillContent), so an embedded newline could otherwise smuggle an extra
@@ -184,9 +194,9 @@ export async function executeScaffoldManagedSkill(
     };
   }
 
-  // Validate and normalize the optional string-array inputs. `includes` lists
-  // child skill IDs; activation_hints / avoid_when become the skill's
-  // "Use when:" / "Avoid when:" retrieval signal in memory.
+  // Validate and normalize the string-array inputs. `includes` lists child
+  // skill IDs; activation_hints / avoid_when become the skill's "Use when:" /
+  // "Avoid when:" retrieval signal in memory.
   const includesResult = normalizeOptionalStringArray(
     input.includes,
     "includes",
@@ -204,6 +214,14 @@ export async function executeScaffoldManagedSkill(
     return { content: `Error: ${activationHintsResult.error}`, isError: true };
   }
   const activationHints = activationHintsResult.value;
+  // Hints are the skill's "Use when:" retrieval text, and scaffolding rewrites
+  // the whole SKILL.md, so a write without them leaves (or strips) none.
+  if (!activationHints) {
+    return {
+      content: `Error: ${MISSING_ACTIVATION_HINTS}`,
+      isError: true,
+    };
+  }
 
   const avoidWhenResult = normalizeOptionalStringArray(
     input.avoid_when,