@vellumai/assistant 0.5.9 → 0.5.11

package/src/runtime/routes/workspace-commit-routes.ts

@@ -7,6 +7,8 @@
  * the same pattern as other gateway-forwarded control-plane endpoints.
  */
 
+import { z } from "zod";
+
 import { getWorkspaceDir } from "../../util/platform.js";
 import { getWorkspaceGitService } from "../../workspace/git-service.js";
 import { httpError } from "../http-errors.js";
@@ -17,6 +19,16 @@ export function workspaceCommitRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "admin/workspace-commit",
       method: "POST",
+      summary: "Commit workspace changes",
+      description:
+        "Create a git commit in the workspace directory with all pending changes.",
+      tags: ["admin"],
+      requestBody: z.object({
+        message: z.string().describe("Commit message"),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
       handler: async ({ req }) => {
         let body: unknown;
         try {

package/src/runtime/routes/workspace-routes.ts

@@ -16,6 +16,8 @@ import {
 } from "node:fs";
 import { basename, dirname, join } from "node:path";
 
+import { z } from "zod";
+
 import { getWorkspaceDir } from "../../util/platform.js";
 import { httpError } from "../http-errors.js";
 import type { RouteContext, RouteDefinition } from "../http-router.js";
@@ -382,36 +384,136 @@ export function workspaceRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "workspace/tree",
       method: "GET",
+      summary: "List workspace directory",
+      description: "Return directory entries for a workspace path.",
+      tags: ["workspace"],
+      queryParams: [
+        {
+          name: "path",
+          schema: { type: "string" },
+          description: "Relative path (default root)",
+        },
+        {
+          name: "showHidden",
+          schema: { type: "string" },
+          description: "Include dotfiles (true/false)",
+        },
+      ],
+      responseBody: z.object({
+        path: z.string(),
+        entries: z.array(z.unknown()).describe("Directory entry objects"),
+      }),
       handler: (ctx) => handleWorkspaceTree(ctx),
     },
     {
       endpoint: "workspace/file/content",
       method: "GET",
+      summary: "Get workspace file content",
+      description: "Return raw file bytes with HTTP range support.",
+      tags: ["workspace"],
+      queryParams: [
+        {
+          name: "path",
+          schema: { type: "string" },
+          description: "Relative file path (required)",
+        },
+        {
+          name: "showHidden",
+          schema: { type: "string" },
+          description: "Allow hidden files (true/false)",
+        },
+      ],
       handler: (ctx) => handleWorkspaceFileContent(ctx),
     },
     {
       endpoint: "workspace/file",
       method: "GET",
+      summary: "Get workspace file metadata",
+      description:
+        "Return file metadata and inline text content (if small enough).",
+      tags: ["workspace"],
+      queryParams: [
+        {
+          name: "path",
+          schema: { type: "string" },
+          description: "Relative file path (required)",
+        },
+        {
+          name: "showHidden",
+          schema: { type: "string" },
+          description: "Allow hidden files (true/false)",
+        },
+      ],
+      responseBody: z.object({
+        path: z.string(),
+        name: z.string(),
+        size: z.number(),
+        mimeType: z.string(),
+        modifiedAt: z.string(),
+        content: z.string().describe("Inline text content or null"),
+        isBinary: z.boolean(),
+      }),
       handler: (ctx) => handleWorkspaceFile(ctx),
     },
     {
       endpoint: "workspace/write",
       method: "POST",
+      summary: "Write workspace file",
+      description: "Create or overwrite a file in the workspace.",
+      tags: ["workspace"],
+      requestBody: z.object({
+        path: z.string().describe("Relative file path"),
+        content: z.string().describe("File content").optional(),
+        encoding: z
+          .string()
+          .describe("Content encoding (base64 or utf-8)")
+          .optional(),
+      }),
+      responseBody: z.object({
+        path: z.string(),
+        size: z.number(),
+      }),
       handler: (ctx) => handleWorkspaceWrite(ctx),
     },
     {
       endpoint: "workspace/mkdir",
       method: "POST",
+      summary: "Create workspace directory",
+      description: "Create directories recursively in the workspace.",
+      tags: ["workspace"],
+      requestBody: z.object({
+        path: z.string().describe("Relative directory path"),
+      }),
+      responseBody: z.object({
+        path: z.string(),
+      }),
       handler: (ctx) => handleWorkspaceMkdir(ctx),
     },
     {
       endpoint: "workspace/rename",
       method: "POST",
+      summary: "Rename workspace entry",
+      description: "Rename or move a file or directory in the workspace.",
+      tags: ["workspace"],
+      requestBody: z.object({
+        oldPath: z.string().describe("Current relative path"),
+        newPath: z.string().describe("New relative path"),
+      }),
+      responseBody: z.object({
+        oldPath: z.string(),
+        newPath: z.string(),
+      }),
       handler: (ctx) => handleWorkspaceRename(ctx),
     },
     {
       endpoint: "workspace/delete",
       method: "POST",
+      summary: "Delete workspace entry",
+      description: "Delete a file or directory from the workspace.",
+      tags: ["workspace"],
+      requestBody: z.object({
+        path: z.string().describe("Relative path to delete"),
+      }),
       handler: (ctx) => handleWorkspaceDelete(ctx),
     },
   ];

package/src/schedule/scheduler.ts

@@ -188,7 +188,7 @@ async function runScheduleOnce(
         );
         const { runTask } = await import("../tasks/task-runner.js");
         const result = await runTask(
-          { taskId, workingDir: process.cwd(), source: "schedule" },
+          { taskId, workingDir: process.cwd(), source: "schedule", scheduleJobId: job.id },
           processMessage as (
             conversationId: string,
             message: string,
@@ -196,6 +196,12 @@ async function runScheduleOnce(
           ) => Promise<void>,
         );
 
+        onScheduleConversationCreated?.({
+          conversationId: result.conversationId,
+          scheduleJobId: job.id,
+          title: result.status === "failed" ? `${job.name}: Error` : job.name,
+        });
+
         // Track the schedule run using the task's conversation
         const runId = createScheduleRun(job.id, result.conversationId);
         if (result.status === "failed") {

package/src/security/AGENTS.md

@@ -0,0 +1,7 @@
+# Security — Agent Instructions
+
+## Integration API Key Patterns
+
+When adding a new third-party integration, check whether the service uses a recognizable API key prefix (e.g., `lin_api_`, `sk-ant-`, `ghp_`). If it does, add a corresponding entry to `PREFIX_PATTERNS` in `secret-patterns.ts`. This is the single source of truth for prefix-based secret detection — ingress blocking, tool output scanning, and log redaction all consume this list.
+
+OAuth-only services with opaque access tokens (no fixed prefix) do not need a pattern.

package/src/security/credential-backend.ts

@@ -30,7 +30,7 @@ export interface CredentialListResult {
 // ---------------------------------------------------------------------------
 
 export interface CredentialBackend {
-  /** Human-readable name for logging (e.g. "keychain", "encrypted-store"). */
+  /** Human-readable name for logging (e.g. "encrypted-store"). */
   readonly name: string;
 
   /** Whether this backend is currently reachable. Sync and cheap. */

package/src/security/encrypted-store.ts

@@ -1,5 +1,5 @@
 /**
- * Encrypted-at-rest key storage -- fallback for systems without OS keychain.
+ * Encrypted-at-rest key storage.
  *
  * v2 stores use a cryptographically random 32-byte `store.key` file as the
  * AES-256-GCM key directly (no key derivation). The key file lives alongside
@@ -8,7 +8,7 @@
  * v1 stores (legacy) derived the AES key from machine-specific entropy via
  * PBKDF2. Existing v1 stores are automatically migrated to v2 on first access.
  *
- * Provides the same get/set/delete interface as `keychain.ts`.
+ * Provides the standard get/set/delete credential storage interface.
  */
 
 import {
@@ -418,7 +418,7 @@ function decrypt(entry: EncryptedEntry, key: Buffer): string {
 }
 
 // ---------------------------------------------------------------------------
-// Public API -- matches keychain.ts interface
+// Public API
 // ---------------------------------------------------------------------------
 
 /**

package/src/security/oauth2.ts

@@ -289,6 +289,15 @@ function startLoopbackServerAndWaitForCode(
     let boundRedirectUri = "";
 
     const server: Server = createServer((req, res) => {
+      log.info(
+        {
+          method: req.method,
+          path: new URL(req.url ?? "/", "http://127.0.0.1").pathname,
+          settled,
+        },
+        "oauth2 loopback: received request",
+      );
+
       if (settled) {
         res.writeHead(400, { "Content-Type": "text/html" });
         res.end(renderLoopbackPage("Authorization already completed", false));
@@ -298,6 +307,10 @@ function startLoopbackServerAndWaitForCode(
       const url = new URL(req.url ?? "/", `http://127.0.0.1`);
 
       if (url.pathname !== LOOPBACK_CALLBACK_PATH) {
+        log.info(
+          { pathname: url.pathname },
+          "oauth2 loopback: non-callback path, returning 404",
+        );
         res.writeHead(404, { "Content-Type": "text/plain" });
         res.end("Not found");
         return;
@@ -308,6 +321,7 @@ function startLoopbackServerAndWaitForCode(
       const error = url.searchParams.get("error");
 
       if (callbackState !== state) {
+        log.warn("oauth2 loopback: state mismatch in callback");
         res.writeHead(400, { "Content-Type": "text/html" });
         res.end(renderLoopbackPage("Invalid state parameter", false));
         return;
@@ -317,6 +331,10 @@ function startLoopbackServerAndWaitForCode(
 
       if (error) {
         const errorDesc = url.searchParams.get("error_description") ?? error;
+        log.error(
+          { error, errorDesc },
+          "oauth2 loopback: authorization denied by user/provider",
+        );
         res.writeHead(200, { "Content-Type": "text/html" });
         res.end(
           renderLoopbackPage(`Authorization failed: ${errorDesc}`, false),
@@ -327,6 +345,7 @@ function startLoopbackServerAndWaitForCode(
       }
 
       if (!code) {
+        log.error("oauth2 loopback: callback missing authorization code");
         res.writeHead(400, { "Content-Type": "text/html" });
         res.end(renderLoopbackPage("Missing authorization code", false));
         cleanup();
@@ -334,6 +353,9 @@ function startLoopbackServerAndWaitForCode(
         return;
       }
 
+      log.info(
+        "oauth2 loopback: authorization code received, exchanging for tokens",
+      );
       res.writeHead(200, { "Content-Type": "text/html" });
       res.end(
         renderLoopbackPage(
@@ -347,6 +369,10 @@ function startLoopbackServerAndWaitForCode(
 
     const timeout = setTimeout(() => {
       if (!settled) {
+        log.warn(
+          { timeoutMs: LOOPBACK_TIMEOUT_MS, state },
+          "oauth2 loopback: callback timed out — no authorization code received",
+        );
         settled = true;
         cleanup();
         reject(new Error("OAuth2 loopback callback timed out"));
@@ -359,10 +385,20 @@ function startLoopbackServerAndWaitForCode(
       server.close();
     }
 
+    log.info(
+      { requestedPort: loopbackPort ?? "random" },
+      "oauth2 loopback: binding server",
+    );
+
     server.listen(loopbackPort ?? 0, "localhost", () => {
       const addr = server.address() as { port: number };
       boundRedirectUri = `http://localhost:${addr.port}${LOOPBACK_CALLBACK_PATH}`;
 
+      log.info(
+        { port: addr.port, redirectUri: boundRedirectUri },
+        "oauth2 loopback: server listening",
+      );
+
       const authParams = new URLSearchParams({
         ...config.extraParams,
         client_id: config.clientId,
@@ -375,10 +411,19 @@ function startLoopbackServerAndWaitForCode(
       });
 
       const authUrl = `${config.authUrl}?${authParams}`;
+      log.info(
+        { authUrlLength: authUrl.length, state },
+        "oauth2 loopback: built auth URL, calling openUrl callback",
+      );
       callbacks.openUrl(authUrl);
+      log.info("oauth2 loopback: openUrl callback returned");
     });
 
     server.on("error", (err) => {
+      log.error(
+        { err: err.message, loopbackPort },
+        "oauth2 loopback: server error",
+      );
       if (!settled) {
         settled = true;
         cleanup();
@@ -687,6 +732,16 @@ export async function startOAuth2Flow(
   const transport =
     options?.callbackTransport ?? (hasPublicUrl ? "gateway" : "loopback");
 
+  log.info(
+    {
+      transport,
+      hasPublicUrl,
+      explicitTransport: options?.callbackTransport,
+      loopbackPort: options?.loopbackPort,
+    },
+    "startOAuth2Flow: resolved transport",
+  );
+
   if (transport === "gateway") {
     if (!hasPublicUrl) {
       throw new Error(

package/src/security/secret-ingress.ts

@@ -0,0 +1,174 @@
+/**
+ * Ingress secret detection for user messages.
+ *
+ * Consumes `PREFIX_PATTERNS` from `secret-patterns.ts` — the single source
+ * of truth for prefix-based secret detection.  This module intentionally
+ * does NOT import `scanText()` or any entropy/encoding logic to avoid
+ * false positives on legitimate user input.
+ */
+
+import { getConfig } from "../config/loader.js";
+import { isAllowlisted } from "./secret-allowlist.js";
+import { PREFIX_PATTERNS } from "./secret-patterns.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface IngressCheckResult {
+  blocked: boolean;
+  detectedTypes: string[];
+  userNotice?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Placeholder detection (inline — not imported from secret-scanner.ts)
+// ---------------------------------------------------------------------------
+
+const KNOWN_PLACEHOLDERS = new Set([
+  "your-api-key-here",
+  "your_api_key_here",
+  "insert-your-key-here",
+  "insert_your_key_here",
+  "replace-with-your-key",
+  "replace_with_your_key",
+  "xxx",
+  "xxxxxxxx",
+  "test",
+  "example",
+  "sample",
+  "demo",
+  "placeholder",
+  "changeme",
+  "CHANGEME",
+  "TODO",
+  "FIXME",
+  "your-token-here",
+  "your_token_here",
+  "my-api-key",
+  "my_api_key",
+]);
+
+const PLACEHOLDER_PREFIXES = [
+  "sk-test-",
+  "sk_test_",
+  "fake_",
+  "fake-",
+  "dummy_",
+  "dummy-",
+  "test_",
+  "test-",
+  "example_",
+  "example-",
+  "sample_",
+  "sample-",
+  "mock_",
+  "mock-",
+];
+
+/**
+ * Check if the text immediately before a matched value indicates
+ * a placeholder context (e.g. "fake_", "test_").
+ */
+function isPlaceholderContext(preContext: string): boolean {
+  const lower = preContext.toLowerCase();
+  for (const prefix of PLACEHOLDER_PREFIXES) {
+    if (lower.endsWith(prefix)) return true;
+  }
+  return false;
+}
+
+/**
+ * Check if a matched value is a placeholder/test value that should not
+ * trigger blocking.
+ */
+function isPlaceholder(value: string): boolean {
+  const lower = value.toLowerCase();
+
+  // Known placeholder values
+  if (KNOWN_PLACEHOLDERS.has(lower)) return true;
+
+  // Placeholder prefixes
+  for (const prefix of PLACEHOLDER_PREFIXES) {
+    if (lower.startsWith(prefix)) return true;
+  }
+
+  // Repeated characters in the variable portion (e.g. "AKIA" + "X" x 16)
+  // Strip known prefixes to isolate the variable part
+  const variablePart = value
+    .replace(
+      /^(?:AKIA|gh[pousr]_|github_pat_|glpat-|sk_live_|rk_live_|xoxb-|xoxp-|xapp-|sk-ant-|sk-proj-|sk-or-v1-|AIza|GOCSPX-|SK|SG\.|npm_|pypi-|key-|lin_api_|ntn_|fw_|pplx-|-----BEGIN [A-Z ]*PRIVATE KEY-----)/,
+      "",
+    )
+    .replace(/[^A-Za-z0-9]/g, "");
+  if (variablePart.length >= 8) {
+    const firstChar = variablePart[0];
+    if (variablePart.split("").every((c) => c === firstChar)) return true;
+  }
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Check user message content for high-confidence secret patterns.
+ *
+ * Returns `{ blocked: true, detectedTypes, userNotice }` if secrets are
+ * found and blocking is enabled, otherwise `{ blocked: false }`.
+ */
+export function checkIngressForSecrets(content: string): IngressCheckResult {
+  const config = getConfig();
+  const secretDetection = config?.secretDetection;
+
+  // Bail if secret detection config is missing or entirely disabled
+  if (!secretDetection?.enabled) {
+    return { blocked: false, detectedTypes: [] };
+  }
+
+  // Bail if ingress blocking is disabled
+  if (!secretDetection.blockIngress) {
+    return { blocked: false, detectedTypes: [] };
+  }
+
+  const detectedTypes: string[] = [];
+
+  for (const { label, regex } of PREFIX_PATTERNS) {
+    // Use a global version to find all matches
+    const globalRegex = new RegExp(regex.source, "g");
+    let match: RegExpExecArray | null;
+
+    while ((match = globalRegex.exec(content)) !== null) {
+      const value = match[0];
+
+      // Skip placeholders and test values (check both the match and
+      // a small window before it for placeholder prefixes like "fake_")
+      const contextStart = Math.max(0, match.index - 10);
+      const preContext = content.slice(contextStart, match.index);
+      if (isPlaceholder(value) || isPlaceholderContext(preContext)) continue;
+
+      // Skip user-allowlisted values
+      if (isAllowlisted(value)) continue;
+
+      if (!detectedTypes.includes(label)) {
+        detectedTypes.push(label);
+      }
+    }
+  }
+
+  if (detectedTypes.length === 0) {
+    return { blocked: false, detectedTypes: [] };
+  }
+
+  return {
+    blocked: true,
+    detectedTypes,
+    userNotice:
+      `Message blocked: detected ` +
+      `${detectedTypes.length === 1 ? "a potential credential" : "potential credentials"} ` +
+      `(${detectedTypes.join(", ")}). ` +
+      `Use the secure credential prompt to provide sensitive values safely.`,
+  };
+}

package/src/security/secret-patterns.ts

@@ -0,0 +1,133 @@
+/**
+ * Shared prefix-based secret patterns — the single source of truth.
+ *
+ * Ingress blocking, tool output scanning, and log redaction all consume
+ * this list.  When adding a new integration, add its API key pattern here.
+ *
+ * This module is intentionally data-only: no imports, no entropy logic,
+ * no config — safe for hot-path consumers like log serializers.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SecretPrefixPattern {
+  /** Human-readable label shown in block notices and redaction tags. */
+  label: string;
+  /**
+   * Regex that matches the token value.  Must NOT include the `g` flag or
+   * capture groups — consumers add those as needed.
+   */
+  regex: RegExp;
+}
+
+// ---------------------------------------------------------------------------
+// Prefix patterns
+// ---------------------------------------------------------------------------
+
+/**
+ * High-confidence, prefix-based secret patterns.
+ *
+ * Each entry matches a known API key / token format by its distinctive
+ * prefix.  Patterns that require surrounding context (entropy analysis,
+ * keyword proximity, URL structure) do NOT belong here — they stay in
+ * `secret-scanner.ts` as scanner-only patterns.
+ *
+ * **When adding a new third-party integration, add its API key pattern
+ * here.**  If the service uses only opaque OAuth access tokens (no fixed
+ * prefix), no pattern is needed.
+ */
+export const PREFIX_PATTERNS: SecretPrefixPattern[] = [
+  // -- AWS --
+  { label: "AWS Access Key", regex: /AKIA[0-9A-Z]{16}/ },
+
+  // -- GitHub --
+  { label: "GitHub Token", regex: /gh[pousr]_[A-Za-z0-9_]{36,}/ },
+  { label: "GitHub Fine-Grained PAT", regex: /github_pat_[A-Za-z0-9_]{22,}/ },
+
+  // -- GitLab --
+  { label: "GitLab Token", regex: /glpat-[A-Za-z0-9\-_]{20,}/ },
+
+  // -- Stripe --
+  { label: "Stripe Secret Key", regex: /sk_live_[A-Za-z0-9]{24,}/ },
+  { label: "Stripe Restricted Key", regex: /rk_live_[A-Za-z0-9]{24,}/ },
+
+  // -- Slack --
+  {
+    label: "Slack Bot Token",
+    regex: /xoxb-[0-9]{10,}-[0-9]{10,}-[A-Za-z0-9]{24,}/,
+  },
+  {
+    label: "Slack User Token",
+    regex: /xoxp-[0-9]{10,}-[0-9]{10,}-[0-9]{10,}-[a-f0-9]{32}/,
+  },
+  {
+    label: "Slack App Token",
+    regex: /xapp-[0-9]+-[A-Za-z0-9]+-[0-9]+-[A-Za-z0-9]+/,
+  },
+
+  // -- Telegram --
+  {
+    label: "Telegram Bot Token",
+    // Format: <bot_id>:<secret> where bot_id is 8–10 digits, secret is 35 chars
+    regex: /[0-9]{8,10}:[A-Za-z0-9_-]{35}/,
+  },
+
+  // -- Anthropic --
+  { label: "Anthropic API Key", regex: /sk-ant-[A-Za-z0-9\-_]{80,}/ },
+
+  // -- OpenAI --
+  {
+    label: "OpenAI API Key",
+    regex: /sk-[A-Za-z0-9]{20}T3BlbkFJ[A-Za-z0-9]{20}/,
+  },
+  { label: "OpenAI Project Key", regex: /sk-proj-[A-Za-z0-9\-_]{40,}/ },
+
+  // -- Google --
+  { label: "Google API Key", regex: /AIza[A-Za-z0-9\-_]{35}/ },
+  {
+    label: "Google OAuth Client Secret",
+    regex: /GOCSPX-[A-Za-z0-9\-_]{28}/,
+  },
+
+  // -- Twilio --
+  { label: "Twilio API Key", regex: /SK[0-9a-f]{32}/ },
+
+  // -- SendGrid --
+  {
+    label: "SendGrid API Key",
+    regex: /SG\.[A-Za-z0-9\-_]{22}\.[A-Za-z0-9\-_]{43}/,
+  },
+
+  // -- Mailgun --
+  { label: "Mailgun API Key", regex: /key-[A-Za-z0-9]{32}/ },
+
+  // -- npm --
+  { label: "npm Token", regex: /npm_[A-Za-z0-9]{36}/ },
+
+  // -- PyPI --
+  { label: "PyPI API Token", regex: /pypi-[A-Za-z0-9\-_]{50,}/ },
+
+  // -- Private keys --
+  {
+    label: "Private Key",
+    regex:
+      /-----BEGIN (?:RSA |DSA |EC |OPENSSH |PGP )?PRIVATE KEY(?:\s+BLOCK)?-----/,
+  },
+
+  // -- Linear --
+  { label: "Linear API Key", regex: /lin_api_[A-Za-z0-9]{32,}/ },
+
+  // -- Notion --
+  { label: "Notion Integration Token", regex: /ntn_[A-Za-z0-9]{40,}/ },
+
+  // -- OpenRouter --
+  { label: "OpenRouter API Key", regex: /sk-or-v1-[A-Za-z0-9\-_]{40,}/ },
+
+  // -- Fireworks --
+  { label: "Fireworks API Key", regex: /fw_[A-Za-z0-9]{32,}/ },
+
+  // -- Perplexity --
+  { label: "Perplexity API Key", regex: /pplx-[A-Za-z0-9]{40,}/ },
+];