@vellumai/assistant 0.11.4 → 0.11.5-staging.2

package/src/tools/credentials/store.ts

@@ -0,0 +1,168 @@
+/**
+ * Credential write path. The single sequence every "store a credential"
+ * caller runs.
+ *
+ * Storing a credential is not one write: the plaintext goes to the secure
+ * backend, the value is scrubbed from recent transcripts, the metadata record
+ * is upserted, and manual-token providers reconcile their connection row.
+ * Order matters (see {@link storeCredentialValue}), so the sequence lives here
+ * rather than being re-typed per entry point. The `credentials/set` route and
+ * the plugin-facing {@link ../../plugin-api/store-credential.storeCredential}
+ * both compose it.
+ *
+ * The transcript scrub and the connection sync are imported lazily, at the
+ * point of use. Both pull heavy graphs behind them (the scrub reaches the
+ * conversation database and registry; the sync reaches the OAuth store), and
+ * this module sits under `@vellumai/plugin-api`, so a static edge would drag
+ * that machinery into every plugin-api consumer for a write most of them never
+ * perform.
+ *
+ * Callers own their own transport-level argument validation and error mapping;
+ * this module throws {@link InvalidCredentialInputError} for a value it will
+ * not store and {@link CredentialStorageError} when the secure backend write
+ * fails.
+ */
+
+import {
+  ACP_SERVICE,
+  assertAcpCredentialFormat,
+} from "../../acp/acp-credentials.js";
+import { credentialKey } from "../../security/credential-key.js";
+import { normalizeSecretValue } from "../../security/secret-normalize.js";
+import {
+  getActiveBackendName,
+  setSecureKeyAsync,
+} from "../../security/secure-keys.js";
+import { getLogger } from "../../util/logger.js";
+import {
+  assertMetadataWritable,
+  upsertCredentialMetadata,
+} from "./metadata-store.js";
+import type { CredentialInjectionTemplate } from "./policy-types.js";
+
+const log = getLogger("credential-store");
+
+/** Raised for a value the store refuses before writing anything. */
+export class InvalidCredentialInputError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidCredentialInputError";
+  }
+}
+
+/** Raised when the secure backend write itself fails. */
+export class CredentialStorageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CredentialStorageError";
+  }
+}
+
+export interface StoreCredentialValueInput {
+  service: string;
+  field: string;
+  /** Plaintext value. Edge whitespace is trimmed before storage. */
+  value: string;
+  /** Human-friendly alias shown in credential listings. */
+  alias?: string;
+  /** What the credential is for, surfaced to the agent. */
+  usageDescription?: string;
+  allowedTools?: string[];
+  allowedDomains?: string[];
+  injectionTemplates?: CredentialInjectionTemplate[];
+  /**
+   * Skip the retroactive transcript scrub. Set it only when the plaintext
+   * provably never transited a conversation (a token minted by an OAuth
+   * refresh, say), since the scrub is a bounded but real sweep of recent
+   * history.
+   */
+  skipTranscriptScrub?: boolean;
+}
+
+export interface StoredCredential {
+  credentialId: string;
+  service: string;
+  field: string;
+}
+
+/**
+ * Store a credential's plaintext and reconcile everything that hangs off it.
+ *
+ * The order is load-bearing:
+ * 1. Validate the value (and the ACP format guard) so a rejected write leaves
+ *    no side effects.
+ * 2. Fail early when credential metadata is not writable.
+ * 3. Write the plaintext to the secure backend.
+ * 4. Scrub the value from recent transcripts. This runs BEFORE the metadata
+ *    upsert and the connection sync, because those can throw and a
+ *    stored-but-unscrubbed secret must not depend on them succeeding. The
+ *    credential IS stored at this point, so the scrub is best-effort hygiene
+ *    and stays invisible to the caller.
+ * 5. Upsert metadata and reconcile the manual-token connection row.
+ *
+ * @throws {InvalidCredentialInputError} when the value is empty or malformed
+ *   for its service.
+ * @throws {CredentialStorageError} when the secure backend rejects the write.
+ */
+export async function storeCredentialValue(
+  input: StoreCredentialValueInput,
+): Promise<StoredCredential> {
+  const { service, field } = input;
+
+  const value = normalizeSecretValue(input.value);
+  if (value.length === 0) {
+    throw new InvalidCredentialInputError("value is required");
+  }
+
+  // Reject an Anthropic API key pasted into the ACP OAuth-token field (a 401
+  // footgun) before it reaches storage.
+  if (service === ACP_SERVICE) {
+    assertAcpCredentialFormat(field, value);
+  }
+
+  assertMetadataWritable();
+
+  const stored = await setSecureKeyAsync(credentialKey(service, field), value);
+  if (!stored) {
+    throw new CredentialStorageError(
+      `Failed to store credential in secure storage (backend: ${getActiveBackendName()})`,
+    );
+  }
+
+  // The stored plaintext may already sit in recent transcripts: the user
+  // message that pasted it, the persisted tool_use input, the tool result
+  // echoing the command. This is the scrub seam, not setSecureKeyAsync, which
+  // also fires on OAuth refresh rotations and MCP header writes whose values
+  // never transited a transcript.
+  if (!input.skipTranscriptScrub) {
+    const { isNonSecretPlatformField, scrubStoredCredentialFromTranscripts } =
+      await import("../../daemon/credential-transcript-scrub.js");
+    if (!isNonSecretPlatformField(service, field)) {
+      try {
+        const scrubbed = await scrubStoredCredentialFromTranscripts(value);
+        log.info(
+          { service, field, ...scrubbed },
+          "Credential stored; scrubbed value from recent transcripts",
+        );
+      } catch (err) {
+        log.warn(
+          { err, service, field },
+          "Credential stored, but transcript scrub failed",
+        );
+      }
+    }
+  }
+
+  const metadata = upsertCredentialMetadata(service, field, {
+    alias: input.alias,
+    usageDescription: input.usageDescription,
+    allowedTools: input.allowedTools,
+    allowedDomains: input.allowedDomains,
+    injectionTemplates: input.injectionTemplates,
+  });
+  const { syncManualTokenConnection } =
+    await import("../../oauth/manual-token-connection.js");
+  await syncManualTokenConnection(service);
+
+  return { credentialId: metadata.credentialId, service, field };
+}

package/src/tools/credentials/tool-policy.ts

@@ -5,6 +5,8 @@
  * based on the credential's allowed tools list.
  */
 
+import type { CredentialMetadata } from "./metadata-store.js";
+
 /**
  * Canonical capability key for browser-based credential fills.
  *
@@ -64,3 +66,68 @@ export function isToolAllowed(
     (allowed) => resolveCanonical(allowed) === canonical,
   );
 }
+
+/**
+ * Remediation for a credential whose allowed_tools list is empty. Points at
+ * `credentials prompt` (not inline `credentials set`, which agent shells
+ * refuse): the secure prompt re-collects the value and sets allowed_tools.
+ */
+const NO_TOOLS_ALLOWED_REMEDIATION =
+  "No tools are currently allowed - grant access via `assistant credentials prompt --service <service> --field <field> --label <label> --allowed-tools <tools>` (re-collects the value securely and sets allowed_tools).";
+
+/** Denial reason for a tool that is not in a credential's allowed_tools list. */
+export function toolNotAllowedReason(
+  toolName: string,
+  service: string,
+  field: string,
+  allowedTools: string[] | undefined,
+): string {
+  const tools = allowedTools ?? [];
+  return (
+    `Tool "${toolName}" is not allowed to use credential ${service}/${field}. ` +
+    (tools.length === 0
+      ? NO_TOOLS_ALLOWED_REMEDIATION
+      : `Allowed tools: ${tools.join(", ")}.`)
+  );
+}
+
+/**
+ * Evaluate the policy that gates server-side use of a credential.
+ *
+ * Pure: it inspects only the metadata it is handed, performs no store reads,
+ * and has no side effects. Returns the denial reason, or `undefined` when the
+ * tool may read the credential server-side.
+ *
+ * Domain-restricted credentials are scoped to browser fills on those domains,
+ * so they are refused here even when the tool itself is allowed.
+ */
+export function serverUseDenialReason(
+  metadata: CredentialMetadata | undefined,
+  toolName: string,
+  service: string,
+  field: string,
+): string | undefined {
+  if (!metadata) {
+    return `No credential found for ${service}/${field}`;
+  }
+
+  if (!isToolAllowed(toolName, metadata.allowedTools)) {
+    return toolNotAllowedReason(
+      toolName,
+      service,
+      field,
+      metadata.allowedTools,
+    );
+  }
+
+  const serverDomains = metadata.allowedDomains ?? [];
+  if (serverDomains.length > 0) {
+    return (
+      `Credential ${service}/${field} has domain restrictions ` +
+      `(${serverDomains.join(", ")}) and cannot be used server-side. ` +
+      "Remove domain restrictions or use a separate credential without domain policy."
+    );
+  }
+
+  return undefined;
+}

package/src/tools/executor.ts

@@ -1,9 +1,21 @@
 import { readFile } from "node:fs/promises";
 
+import type {
+  RiskAllowlistOption,
+  RiskDirectoryScopeOption,
+  RiskPatternScopeOption,
+} from "@vellumai/gateway-client";
+
 import { getConfig } from "../config/loader.js";
+import {
+  classifyRisk,
+  type RiskClassificationWithMeta,
+} from "../permissions/checker.js";
 import { PermissionPrompter } from "../permissions/prompter.js";
-import { RiskLevel } from "../permissions/types.js";
-import { runInPluginContext } from "../plugins/plugin-execution-context.js";
+import {
+  runInPluginContext,
+  runOutsidePluginContext,
+} from "../plugins/plugin-execution-context.js";
 import { TokenExpiredError } from "../security/token-manager.js";
 import {
   recordToolError,
@@ -30,6 +42,7 @@ import { MAX_FILE_SIZE_BYTES } from "./shared/filesystem/size-guard.js";
 import { ToolApprovalHandler } from "./tool-approval-handler.js";
 import { resolveToolInvocationAlias } from "./tool-name-aliases.js";
 import { recordToolCompletion } from "./tool-profiler.js";
+import { RISK_LEVEL_UNCLASSIFIED } from "./tool-types.js";
 import { type ToolContext, type ToolExecutionResult } from "./types.js";
 
 export class ToolExecutor {
@@ -60,18 +73,34 @@ export class ToolExecutor {
   ): Promise<ToolExecutionResult> {
     const startTime = Date.now();
     let decision = "allow";
-    let riskLevel: string = RiskLevel.Low;
+    // The invocation's one classification, taken before the gates so every
+    // audit row this call can produce (gate denial, gate error, grant-consumed
+    // execution, permission decision) records the risk of what the model asked
+    // for, then handed down to `checkPermission`. A classification that does
+    // not complete (aborted, gateway unreachable) is recorded as such rather
+    // than as a level; the permission check still requires one and fails
+    // closed on its own.
+    let classification: RiskClassificationWithMeta | undefined;
+    try {
+      classification = await classifyRisk(
+        name,
+        input,
+        context.workingDir,
+        undefined,
+        undefined,
+        context.signal,
+      );
+    } catch {
+      // Stays undefined; the audit row records RISK_LEVEL_UNCLASSIFIED.
+    }
+    let riskLevel: string = classification?.level ?? RISK_LEVEL_UNCLASSIFIED;
     let permRiskMeta:
       | {
           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;
         }
       | undefined;
@@ -106,6 +135,11 @@ export class ToolExecutor {
     // consumed; substitute the parsed value (with `.catch()` recoveries
     // applied) so validation and execution see the same input.
     if (gateResult.parsedInput) {
+      // The permission decision is about the input that runs, so a parse that
+      // reshaped it (a `.catch()` recovery) gets its own classification.
+      if (!Bun.deepEquals(input, gateResult.parsedInput)) {
+        classification = undefined;
+      }
       input = gateResult.parsedInput;
     }
 
@@ -189,6 +223,7 @@ export class ToolExecutor {
           context,
           startTime,
           computePreviewDiff,
+          classification,
         );
 
         riskLevel = permResult.riskLevel;
@@ -235,15 +270,18 @@ export class ToolExecutor {
       const execContext = context;
 
       // Mark the owning plugin as in context (via AsyncLocalStorage) so host
-      // APIs the tool reaches — e.g. resolveCredential — can scope to it. The
+      // APIs the tool reaches, e.g. resolveCredential, can scope to it. The
       // context must be established around the `execute()` call itself so the
-      // returned promise carries the binding across its awaits. Non-plugin
-      // tools (default/skill/mcp/workspace) establish no context.
+      // returned promise carries the binding across its awaits. A non-plugin
+      // tool (default/skill/mcp/workspace) runs with the context explicitly
+      // cleared rather than merely unset: the turn may have been started by a
+      // plugin (a route handler calling `runConversationTurn`), and this tool
+      // is host code that must not inherit that plugin's identity.
       const owner = getToolOwner(name);
       const execPromise =
         owner?.kind === "plugin"
           ? runInPluginContext(owner.id, () => tool.execute(input, execContext))
-          : tool.execute(input, execContext);
+          : runOutsidePluginContext(() => tool.execute(input, execContext));
 
       let execResult: ToolExecutionResult = await executeWithTimeout(
         execPromise,
@@ -295,7 +333,7 @@ export class ToolExecutor {
         safeResult.isError,
       );
 
-      // Merge risk metadata from the classifier assessment cache onto the
+      // Merge the classification's risk metadata onto the
       // tool result so downstream consumers (AgentEvent → handleToolResult →
       // ToolResult SSE message) can forward it to the client.
       if (permRiskMeta) {

package/src/tools/network/__tests__/web-search.test.ts

@@ -797,7 +797,8 @@ describe("web_search tool", () => {
             {
               title: "Keenable Result 1",
               url: "https://example.com/keenable-1",
-              description: "First Keenable result",
+              description: "",
+              snippet: "First Keenable result",
             },
           ],
         }),
@@ -814,6 +815,45 @@ describe("web_search tool", () => {
     expect(result.content).toContain("https://example.com/keenable-1");
   });
 
+  test("Keenable reads the page text from snippet, capped", async () => {
+    seedWebSearch("your-own", "keenable");
+    globalThis.fetch = (async () => {
+      return new Response(
+        JSON.stringify({
+          results: [
+            {
+              title: "Wrapped",
+              url: "https://example.com/wrapped",
+              description: "",
+              snippet: "line one\n\nline two",
+            },
+            {
+              title: "Long",
+              url: "https://example.com/long",
+              description: "",
+              snippet: "word ".repeat(400),
+            },
+            {
+              title: "Meta only",
+              url: "https://example.com/meta",
+              description: "only a meta description",
+            },
+          ],
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as any;
+
+    const result = await execute({ query: "test" });
+    expect(result.content).toContain("line one line two");
+    expect(result.content).toContain("only a meta description");
+    const longLine = String(result.content)
+      .split("\n")
+      .find((line) => line.trim().startsWith("word"));
+    expect(longLine?.trim().length).toBeLessThanOrEqual(500);
+    expect(longLine?.trim().length).toBeGreaterThan(490);
+  });
+
   test("Keenable uses the authenticated endpoint when a key is set", async () => {
     seedWebSearch("your-own", "keenable");
     mockKeenableSecureKey = "keen_test";

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/network/web-search.ts

@@ -148,7 +148,10 @@ interface FirecrawlSearchResponse {
 interface KeenableSearchResult {
   title?: string;
   url?: string;
+  /** The page's meta description. Empty for most pages; see keenableSnippet. */
   description?: string;
+  /** The page text. This is what carries content on a Keenable result. */
+  snippet?: string;
   published_at?: string;
   acquired_at?: string;
 }
@@ -488,6 +491,20 @@ function firecrawlTbsForFreshness(
   }
 }
 
+/** Characters of page text kept per result. Keenable returns the whole page on
+ * every search result, an order of magnitude more than the other providers here
+ * return, so it is capped to keep one search from filling the context. */
+const KEENABLE_SNIPPET_MAX_LENGTH = 500;
+
+/** Keenable sends both `snippet` and `description` on every result: `snippet`
+ * carries the page text and `description` is the page's meta description, which
+ * is empty for most pages. `||` rather than `??`, since the empty description is
+ * present rather than nullish. */
+function keenableSnippet(result: KeenableSearchResult): string {
+  const text = result.snippet || result.description || "";
+  return text.replace(/\s+/g, " ").trim().slice(0, KEENABLE_SNIPPET_MAX_LENGTH);
+}
+
 function formatKeenableResults(
   data: KeenableSearchResponse,
   query: string,
@@ -505,8 +522,9 @@ function formatKeenableResults(
     if (r.url) {
       lines.push(`   URL: ${r.url}`);
     }
-    if (r.description) {
-      lines.push(`   ${r.description}`);
+    const snippet = keenableSnippet(r);
+    if (snippet) {
+      lines.push(`   ${snippet}`);
     }
     if (r.published_at) {
       lines.push(`   Published: ${r.published_at}`);
@@ -531,7 +549,7 @@ function buildKeenableMetadata(
       url,
       domain,
       faviconUrl: faviconUrlForDomain(domain),
-      snippet: r.description,
+      snippet: keenableSnippet(r),
     };
   });
   return {