@vellumai/assistant 0.11.0 → 0.11.1-staging.2

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

@@ -35,8 +35,18 @@ const BRAVE_API_URL = `https://api.search.brave.com${BRAVE_SEARCH_PATH}`;
 const PERPLEXITY_API_URL = "https://api.perplexity.ai/chat/completions";
 const TAVILY_API_URL = "https://api.tavily.com/search";
 const FIRECRAWL_API_URL = "https://api.firecrawl.dev/v2/search";
-
-type WebSearchProvider = "perplexity" | "brave" | "tavily" | "firecrawl";
+// Keenable is keyless by default: the public path needs no key (rate-limited);
+// a key switches to the authenticated path and lifts the cap.
+const KEENABLE_API_BASE_URL = "https://api.keenable.ai";
+const KEENABLE_PUBLIC_SEARCH_PATH = "/v1/search/public";
+const KEENABLE_KEYED_SEARCH_PATH = "/v1/search";
+
+type WebSearchProvider =
+  | "perplexity"
+  | "brave"
+  | "tavily"
+  | "firecrawl"
+  | "keenable";
 
 /**
  * Arguments passed to every {@link WebSearchAdapter}. The full superset is
@@ -67,6 +77,12 @@ interface WebSearchAdapter {
    * configured provider has no key and we try other BYOK providers.
    */
   readonly fallbackOrder: number;
+  /**
+   * Provider that runs without a stored key (keyless by default; an optional
+   * key only lifts rate limits). When true, the dispatcher executes it even
+   * with an empty API key instead of erroring on a missing key.
+   */
+  readonly keyless?: boolean;
   /** Execute one search against the provider's API. */
   execute(args: WebSearchAdapterArgs): Promise<ToolExecutionResult>;
 }
@@ -129,6 +145,19 @@ interface FirecrawlSearchResponse {
   warning?: string | null;
 }
 
+interface KeenableSearchResult {
+  title?: string;
+  url?: string;
+  description?: string;
+  published_at?: string;
+  acquired_at?: string;
+}
+
+interface KeenableSearchResponse {
+  query?: string;
+  results?: KeenableSearchResult[];
+}
+
 function getWebSearchProvider(): WebSearchProvider {
   const config = getConfig();
   const configured = config.services["web-search"].provider ?? "perplexity";
@@ -459,6 +488,79 @@ function firecrawlTbsForFreshness(
   }
 }
 
+function formatKeenableResults(
+  data: KeenableSearchResponse,
+  query: string,
+): string {
+  const results = data.results ?? [];
+  if (results.length === 0) {
+    return `No results found for "${query}".`;
+  }
+
+  const lines: string[] = [`Web search results for "${query}":\n`];
+  for (let i = 0; i < results.length; i++) {
+    const r = results[i];
+    const title = r.title?.trim() || r.url?.trim() || "Untitled result";
+    lines.push(`${i + 1}. ${title}`);
+    if (r.url) {
+      lines.push(`   URL: ${r.url}`);
+    }
+    if (r.description) {
+      lines.push(`   ${r.description}`);
+    }
+    if (r.published_at) {
+      lines.push(`   Published: ${r.published_at}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+function buildKeenableMetadata(
+  data: KeenableSearchResponse,
+  query: string,
+  durationMs: number,
+): WebSearchMetadata {
+  const results = data.results ?? [];
+  const items: WebSearchResultItem[] = results.map((r, i) => {
+    const url = r.url ?? "";
+    const domain = extractDomain(url);
+    return {
+      rank: i + 1,
+      title: r.title?.trim() || url.trim() || "Untitled result",
+      url,
+      domain,
+      faviconUrl: faviconUrlForDomain(domain),
+      snippet: r.description,
+    };
+  });
+  return {
+    query,
+    provider: "keenable",
+    resultCount: items.length,
+    durationMs,
+    results: items,
+  };
+}
+
+/**
+ * Map the tool's `freshness` window onto a Keenable `published_after` date
+ * (YYYY-MM-DD). Keenable filters by absolute publication date rather than a
+ * relative window, so we subtract the window from `now`. Returns `undefined`
+ * for an unrecognized value so the request omits the filter.
+ */
+function keenablePublishedAfterForFreshness(
+  freshness: string | undefined,
+): string | undefined {
+  const days: Record<string, number> = { pd: 1, pw: 7, pm: 30, py: 365 };
+  const window = freshness ? days[freshness] : undefined;
+  if (window === undefined) {
+    return undefined;
+  }
+  const since = new Date(Date.now() - window * 24 * 60 * 60 * 1000);
+  return since.toISOString().slice(0, 10);
+}
+
 function errorResult(
   query: string,
   provider: WebSearchProvider,
@@ -489,7 +591,9 @@ function errorResult(
  * The body must NEVER reach user-facing `content`/`errorMessage`.
  */
 function rawBodyDetail(body: unknown): { message: string } | undefined {
-  if (body == null) return undefined;
+  if (body == null) {
+    return undefined;
+  }
   const text = typeof body === "string" ? body : safeStringifyBody(body);
   const trimmed = text.trim();
   return trimmed ? { message: trimmed } : undefined;
@@ -1056,6 +1160,115 @@ async function executeFirecrawlSearch(
   );
 }
 
+async function executeKeenableSearch(
+  query: string,
+  count: number,
+  freshness: string | undefined,
+  apiKey: string,
+  signal?: AbortSignal,
+): Promise<ToolExecutionResult> {
+  // Keyless by default; a configured key switches to the authenticated path.
+  const trimmedKey = apiKey.trim();
+  const path = trimmedKey
+    ? KEENABLE_KEYED_SEARCH_PATH
+    : KEENABLE_PUBLIC_SEARCH_PATH;
+  const url = `${KEENABLE_API_BASE_URL}${path}`;
+
+  const body: Record<string, unknown> = { query, mode: "pro" };
+  const publishedAfter = keenablePublishedAfterForFreshness(freshness);
+  if (publishedAfter) {
+    body.published_after = publishedAfter;
+  }
+
+  const startedAt = Date.now();
+
+  for (let attempt = 0; attempt <= DEFAULT_MAX_RETRIES; attempt++) {
+    let response: Response;
+    try {
+      const headers: Record<string, string> = {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "X-Keenable-Title": "Vellum Assistant",
+      };
+      if (trimmedKey) {
+        headers["X-API-Key"] = trimmedKey;
+      }
+      response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal,
+      });
+    } catch (err) {
+      return networkFailureResult(query, "keenable", startedAt, err, signal);
+    }
+
+    if (response.ok) {
+      const data = (await response.json()) as KeenableSearchResponse;
+      // Honor the requested result count client-side (the API returns a fixed set).
+      if (data.results && data.results.length > count) {
+        data.results = data.results.slice(0, count);
+      }
+      const durationMs = Date.now() - startedAt;
+      return {
+        content:
+          wrapUntrustedContent(formatKeenableResults(data, query), {
+            source: "search",
+            sourceDetail: "keenable",
+          }) + CITATION_INSTRUCTION,
+        isError: false,
+        activityMetadata: {
+          webSearch: buildKeenableMetadata(data, query, durationMs),
+        },
+      };
+    }
+
+    const bodyText = await response.text();
+
+    if (response.status === 401 || response.status === 403) {
+      return errorResult(
+        query,
+        "keenable",
+        startedAt,
+        "Invalid or expired Keenable API key",
+      );
+    }
+
+    if (response.status === 429 && attempt < DEFAULT_MAX_RETRIES) {
+      const delayMs = getHttpRetryDelay(
+        response,
+        attempt,
+        DEFAULT_BASE_DELAY_MS,
+      );
+      log.warn(
+        { attempt: attempt + 1, delayMs },
+        "Keenable Search rate limited, retrying",
+      );
+      await sleep(delayMs);
+      continue;
+    }
+
+    log.warn({ status: response.status }, "Keenable Search API error");
+    return backendFailureResult(
+      query,
+      "keenable",
+      startedAt,
+      { statusCode: response.status, error: rawBodyDetail(bodyText) },
+      response.status === 429
+        ? "Keenable Search rate limit exceeded after retries. Try again shortly."
+        : `Keenable Search API returned status ${response.status}`,
+    );
+  }
+
+  return backendFailureResult(
+    query,
+    "keenable",
+    startedAt,
+    { statusCode: 429 },
+    "Keenable Search rate limit exceeded after retries. Try again shortly.",
+  );
+}
+
 // ----------------------------------------------------------------------------
 // Adapter registry
 //
@@ -1105,6 +1318,15 @@ const firecrawlSearchAdapter: WebSearchAdapter = {
     executeFirecrawlSearch(query, count, freshness, apiKey, signal),
 };
 
+const keenableSearchAdapter: WebSearchAdapter = {
+  id: "keenable",
+  providerKeyName: "keenable",
+  fallbackOrder: 5,
+  keyless: true,
+  execute: ({ query, count, freshness, apiKey, signal }) =>
+    executeKeenableSearch(query, count, freshness, apiKey, signal),
+};
+
 /**
  * All built-in web-search adapters keyed by provider id. The
  * `Record<WebSearchProvider, ...>` shape forces TypeScript to flag any
@@ -1115,6 +1337,7 @@ const WEB_SEARCH_ADAPTERS: Record<WebSearchProvider, WebSearchAdapter> = {
   brave: braveSearchAdapter,
   tavily: tavilySearchAdapter,
   firecrawl: firecrawlSearchAdapter,
+  keenable: keenableSearchAdapter,
 };
 
 /**
@@ -1146,7 +1369,7 @@ export const webSearchTool = {
       count: {
         type: "number",
         description:
-          "Number of results to return (1-20, default 10). Used with Brave, Tavily, and Firecrawl providers.",
+          "Number of results to return (1-20, default 10). Used with Brave, Tavily, Firecrawl, and Keenable providers.",
       },
       offset: {
         type: "number",
@@ -1156,7 +1379,7 @@ export const webSearchTool = {
       freshness: {
         type: "string",
         description:
-          'Filter by recency: "pd" (past day), "pw" (past week), "pm" (past month), "py" (past year). Used with Brave, Tavily, and Firecrawl providers.',
+          'Filter by recency: "pd" (past day), "pw" (past week), "pm" (past month), "py" (past year). Used with Brave, Tavily, Firecrawl, and Keenable providers.',
       },
     },
     required: ["query"],
@@ -1221,14 +1444,18 @@ export const webSearchTool = {
     let provider = getWebSearchProvider();
     let apiKey = await getApiKey(provider);
 
-    // Fallback: if the configured provider has no key, try other BYOK search
+    // A keyless provider (e.g. Keenable) runs without a stored key, so skip the
+    // missing-key fallback/error entirely and execute it as configured.
+    // Fallback: if a key-based provider has no key, try other BYOK search
     // providers in a stable order. This preserves existing installs that only
     // configured one search-provider key while still allowing new providers to
     // be selected explicitly.
-    if (!apiKey) {
+    if (!apiKey && !WEB_SEARCH_ADAPTERS[provider].keyless) {
       for (const fallback of fallbackProvidersFor(provider)) {
         const fallbackKey = await getApiKey(fallback);
-        if (!fallbackKey) continue;
+        if (!fallbackKey) {
+          continue;
+        }
         log.info(
           { from: provider, to: fallback },
           "Configured web search provider has no API key, falling back",
@@ -1257,7 +1484,7 @@ export const webSearchTool = {
           query,
           provider,
           startedAt,
-          "No web search API key configured. Set it via `keys set perplexity <key>`, `keys set brave <key>`, `keys set tavily <key>`, or `keys set firecrawl <key>`, or configure it from the Settings page under API Keys.",
+          "No web search API key configured. Set it via `keys set perplexity <key>`, `keys set brave <key>`, `keys set tavily <key>`, or `keys set firecrawl <key>`, or configure it from the Settings page under API Keys. Or switch the web-search provider to Keenable, which works without a key.",
         );
       }
     }
@@ -1270,7 +1497,7 @@ export const webSearchTool = {
         count,
         offset,
         freshness,
-        apiKey,
+        apiKey: apiKey ?? "",
         signal: context.signal,
       });
     } catch (err) {

package/src/tools/schedule/create.ts

@@ -20,6 +20,7 @@ import {
   CapabilityManifestSchema,
   resolveCapabilities as resolveWorkflowCapabilities,
 } from "../../workflows/capabilities.js";
+import { resolveGroupReference } from "../conversation-groups/group_shared.js";
 import {
   invalidToolInputResult,
   nullAsOmitted,
@@ -73,6 +74,7 @@ export const scheduleCreateInputSchema = z.looseObject({
   retry_backoff_ms: nullAsOmitted(z.int()),
   timeout_ms: z.int().optional(),
   inference_profile: z.string().optional(),
+  group: nullAsOmitted(z.string()),
 });
 
 export async function executeScheduleCreate(
@@ -131,6 +133,18 @@ export async function executeScheduleCreate(
     }
   }
 
+  // Sidebar group for run conversations; null = default system:scheduled.
+  let groupId: string | null = null;
+  let groupName: string | null = null;
+  if (parsed.group !== undefined) {
+    const resolvedGroup = resolveGroupReference(parsed.group);
+    if ("error" in resolvedGroup) {
+      return { content: `Error: ${resolvedGroup.error}`, isError: true };
+    }
+    groupId = resolvedGroup.group.id;
+    groupName = resolvedGroup.group.name;
+  }
+
   if (!name) {
     return {
       content: "Error: name is required and must be a string",
@@ -261,6 +275,7 @@ export async function executeScheduleCreate(
         workflowArgs,
         capabilities,
         inferenceProfile,
+        groupId,
         createdFromConversationId: context.conversationId,
       });
 
@@ -277,6 +292,7 @@ export async function executeScheduleCreate(
           ...(job.inferenceProfile
             ? [`  Inference profile: ${job.inferenceProfile}`]
             : []),
+          ...(groupName ? [`  Conversation group: ${groupName}`] : []),
           `  Fire at: ${fireDate}`,
           `  Enabled: ${job.enabled}`,
           `  Status: ${job.status}`,
@@ -352,6 +368,7 @@ export async function executeScheduleCreate(
       workflowArgs,
       capabilities,
       inferenceProfile,
+      groupId,
       createdFromConversationId: context.conversationId,
     });
 
@@ -375,6 +392,7 @@ export async function executeScheduleCreate(
         ...(job.inferenceProfile
           ? [`  Inference profile: ${job.inferenceProfile}`]
           : []),
+        ...(groupName ? [`  Conversation group: ${groupName}`] : []),
         `  Schedule: ${scheduleDescription}${
           job.timezone ? ` (${job.timezone})` : ""
         }`,

package/src/tools/schedule/update.ts

@@ -19,6 +19,7 @@ import {
   getSchedule,
   updateSchedule,
 } from "../../schedule/schedule-store.js";
+import { resolveGroupReference } from "../conversation-groups/group_shared.js";
 import {
   invalidToolInputResult,
   nullAsOmitted,
@@ -44,8 +45,8 @@ const VALID_ROUTING_INTENTS: RoutingIntent[] = [
  *   preprocessing that would silently turn an explicit update into a no-op.
  * - `timezone` and `script` are nullable at runtime though advertised as
  *   plain strings: `updateSchedule` persists null as "clear this field".
- * - `timeout_ms` / `inference_profile` advertise null (it reverts to the
- *   default); the executor's bespoke handling stays.
+ * - `timeout_ms` / `inference_profile` / `group` advertise null (it reverts
+ *   to the default); the executor's bespoke handling stays.
  * - `mode`, `routing_intent`, `workflow_name`, and `workflow_args` are
  *   deliberately UNDECLARED (loose passthrough): the first two keep bespoke
  *   `VALID_*` errors; `workflow_name` has bespoke coercion semantics in the
@@ -68,6 +69,7 @@ export const scheduleUpdateInputSchema = z.looseObject({
   retry_backoff_ms: z.int().optional(),
   timeout_ms: z.int().nullable().optional(),
   inference_profile: z.string().nullable().optional(),
+  group: z.string().nullable().optional(),
 });
 
 export async function executeScheduleUpdate(
@@ -217,6 +219,21 @@ export async function executeScheduleUpdate(
     }
   }
 
+  // Sidebar group for run conversations (null clears it, reverting to the
+  // default system:scheduled). Applies to conversations created by future
+  // runs; existing conversations stay where they are.
+  if (parsed.group !== undefined) {
+    if (parsed.group === null) {
+      updates.groupId = null;
+    } else {
+      const resolvedGroup = resolveGroupReference(parsed.group);
+      if ("error" in resolvedGroup) {
+        return { content: `Error: ${resolvedGroup.error}`, isError: true };
+      }
+      updates.groupId = resolvedGroup.group.id;
+    }
+  }
+
   // Script execution timeout override (null clears it, reverting to default)
   if (parsed.timeout_ms !== undefined) {
     if (parsed.timeout_ms === null) {

package/src/tools/sensitive-output-placeholders.ts

@@ -90,8 +90,12 @@ export function extractAndSanitize(content: string): SanitizeResult {
     const kind = match[1];
     const value = match[2];
 
-    if (!value || value.trim().length === 0) continue;
-    if (!VALID_KINDS.has(kind)) continue;
+    if (!value || value.trim().length === 0) {
+      continue;
+    }
+    if (!VALID_KINDS.has(kind)) {
+      continue;
+    }
 
     const typedKind = kind as SensitiveOutputKind;
     if (!seenValues.has(value)) {
@@ -129,7 +133,9 @@ export function applySubstitutions(
   text: string,
   substitutionMap: ReadonlyMap<string, string>,
 ): string {
-  if (substitutionMap.size === 0) return text;
+  if (substitutionMap.size === 0) {
+    return text;
+  }
 
   let result = text;
   for (const [placeholder, value] of substitutionMap) {
@@ -192,7 +198,9 @@ export function applyStreamingSubstitution(
         break;
       }
     }
-    if (pendingStart !== resolved.length) break;
+    if (pendingStart !== resolved.length) {
+      break;
+    }
   }
 
   return {
@@ -204,7 +212,9 @@ export function applyStreamingSubstitution(
 function getMaxPlaceholderLength(map: ReadonlyMap<string, string>): number {
   let max = 0;
   for (const key of map.keys()) {
-    if (key.length > max) max = key.length;
+    if (key.length > max) {
+      max = key.length;
+    }
   }
   return max;
 }

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

@@ -324,7 +324,11 @@ export class FileSystemOps {
 // ---------------------------------------------------------------------------
 
 function formatSize(bytes: number): string {
-  if (bytes < 1024) return `${bytes} B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  }
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }

package/src/tools/shared/filesystem/image-read.ts

@@ -20,7 +20,9 @@ const MAX_SOURCE_SIZE_BYTES = 100 * 1024 * 1024; // 100 MB — pre-optimization
  * Returns the MIME type, or null if unrecognised.
  */
 export function detectMediaType(buf: Buffer): string | null {
-  if (buf.length < 12) return null;
+  if (buf.length < 12) {
+    return null;
+  }
 
   // JPEG: FF D8 FF
   if (buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {

package/src/tools/shared/filesystem/size-guard.ts

@@ -4,8 +4,12 @@ import { statSync } from "node:fs";
 export const MAX_FILE_SIZE_BYTES = 100 * 1024 * 1024;
 
 function formatBytes(bytes: number): string {
-  if (bytes < 1024) return `${bytes} B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  }
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
 

package/src/tools/skills/execute.ts

@@ -25,7 +25,9 @@ const SKILL_EXECUTE_ENVELOPE_KEYS = new Set(["tool", "input", "activity"]);
 export function recoverSkillExecuteEnvelope(
   envelope: Record<string, unknown>,
 ): Record<string, unknown> {
-  if (!isUnparseableToolArgs(envelope)) return envelope;
+  if (!isUnparseableToolArgs(envelope)) {
+    return envelope;
+  }
   try {
     const parsed: unknown = JSON.parse(envelope._raw);
     if (
@@ -73,7 +75,9 @@ export function resolveSkillExecuteInput(
     // A populated object is the well-formed case. An empty object falls
     // through to sibling rescue: the model may have nested nothing yet placed
     // the real parameters at the top level.
-    if (Object.keys(obj).length > 0) return obj;
+    if (Object.keys(obj).length > 0) {
+      return obj;
+    }
   } else if (typeof raw === "string" && raw.trim()) {
     try {
       const parsed: unknown = JSON.parse(raw);
@@ -92,7 +96,9 @@ export function resolveSkillExecuteInput(
       // the bare string onto it rather than discarding content the model
       // actually produced.
       const field = soleRequiredStringField(innerSchema);
-      if (field) return { [field]: raw };
+      if (field) {
+        return { [field]: raw };
+      }
     }
   }
 
@@ -101,7 +107,9 @@ export function resolveSkillExecuteInput(
       ([key]) => !SKILL_EXECUTE_ENVELOPE_KEYS.has(key),
     ),
   );
-  if (Object.keys(siblings).length > 0) return siblings;
+  if (Object.keys(siblings).length > 0) {
+    return siblings;
+  }
 
   return {};
 }
@@ -113,15 +121,21 @@ export function resolveSkillExecuteInput(
  * one field it can unambiguously belong to.
  */
 function soleRequiredStringField(innerSchema: unknown): string | null {
-  if (innerSchema == null || typeof innerSchema !== "object") return null;
+  if (innerSchema == null || typeof innerSchema !== "object") {
+    return null;
+  }
   const schema = innerSchema as {
     required?: unknown;
     properties?: Record<string, { type?: unknown } | undefined>;
   };
   const required = Array.isArray(schema.required) ? schema.required : [];
-  if (required.length !== 1) return null;
+  if (required.length !== 1) {
+    return null;
+  }
   const field = required[0];
-  if (typeof field !== "string") return null;
+  if (typeof field !== "string") {
+    return null;
+  }
   return schema.properties?.[field]?.type === "string" ? field : null;
 }
 
@@ -146,7 +160,9 @@ export function augmentSkillExecuteError(
   resolvedInput: Record<string, unknown>,
   result: ToolExecutionResult,
 ): ToolExecutionResult {
-  if (!result.isError || Object.keys(resolvedInput).length > 0) return result;
+  if (!result.isError || Object.keys(resolvedInput).length > 0) {
+    return result;
+  }
 
   const guidance =
     `\n\nThis skill_execute call carried no parameters for "${toolName}". ` +

package/src/tools/skills/find-similar-skills.ts

@@ -103,11 +103,15 @@ export async function executeFindSimilarSkills(
   const enriched: EnrichedHit[] = [];
   for (const hit of hits) {
     const skill = byId.get(hit.skillId);
-    if (!skill) continue;
+    if (!skill) {
+      continue;
+    }
     // Defense in depth: the scoped catalog already excludes out-of-scope plugin
     // skills, but re-check so a shortlist source that ignores the catalog seam
     // still cannot leak one.
-    if (outOfScope(skill)) continue;
+    if (outOfScope(skill)) {
+      continue;
+    }
     enriched.push({
       skill_id: hit.skillId,
       name: skill.name,