@vellumai/assistant 0.5.10 → 0.5.12

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/integration-status.ts

@@ -15,12 +15,12 @@ const INTEGRATION_PROBES: IntegrationProbe[] = [
   {
     name: "Gmail",
     category: "email",
-    isConnected: () => isProviderConnected("integration:google"),
+    isConnected: () => isProviderConnected("google"),
   },
   {
     name: "Slack",
     category: "messaging",
-    isConnected: () => isProviderConnected("integration:slack"),
+    isConnected: () => isProviderConnected("slack"),
   },
   {
     name: "Twilio",

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/ces-rpc-credential-backend.ts

@@ -30,11 +30,13 @@ export class CesRpcCredentialBackend implements CredentialBackend {
   }
 
   async get(account: string): Promise<CredentialGetResult> {
+    if (!this.isAvailable()) {
+      return { value: undefined, unreachable: true };
+    }
     try {
-      const result = await this.client.call(
-        CesRpcMethod.GetCredential,
-        { account },
-      );
+      const result = await this.client.call(CesRpcMethod.GetCredential, {
+        account,
+      });
       return {
         value: result.found ? result.value : undefined,
         unreachable: false,
@@ -46,11 +48,12 @@ export class CesRpcCredentialBackend implements CredentialBackend {
   }
 
   async set(account: string, value: string): Promise<boolean> {
+    if (!this.isAvailable()) return false;
     try {
-      const result = await this.client.call(
-        CesRpcMethod.SetCredential,
-        { account, value },
-      );
+      const result = await this.client.call(CesRpcMethod.SetCredential, {
+        account,
+        value,
+      });
       return result.ok;
     } catch (err) {
       log.warn({ err, account }, "CES RPC credential set failed");
@@ -59,11 +62,11 @@ export class CesRpcCredentialBackend implements CredentialBackend {
   }
 
   async delete(account: string): Promise<DeleteResult> {
+    if (!this.isAvailable()) return "error";
     try {
-      const result = await this.client.call(
-        CesRpcMethod.DeleteCredential,
-        { account },
-      );
+      const result = await this.client.call(CesRpcMethod.DeleteCredential, {
+        account,
+      });
       return result.result;
     } catch (err) {
       log.warn({ err, account }, "CES RPC credential delete failed");
@@ -72,11 +75,11 @@ export class CesRpcCredentialBackend implements CredentialBackend {
   }
 
   async list(): Promise<CredentialListResult> {
+    if (!this.isAvailable()) {
+      return { accounts: [], unreachable: true };
+    }
     try {
-      const result = await this.client.call(
-        CesRpcMethod.ListCredentials,
-        {},
-      );
+      const result = await this.client.call(CesRpcMethod.ListCredentials, {});
       return { accounts: result.accounts, unreachable: false };
     } catch (err) {
       log.warn({ err }, "CES RPC credential list failed");

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/oauth-completion-page.ts

@@ -0,0 +1,153 @@
+/**
+ * Shared HTML rendering for OAuth completion pages shown in the browser
+ * after a loopback/redirect OAuth flow completes.
+ */
+
+export function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+function formatProviderName(provider: string): string {
+  // Capitalize first letter of each word, handle common acronyms
+  return provider
+    .split(/[-_]/)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}
+
+export function renderOAuthCompletionPage(
+  message: string,
+  success: boolean,
+  provider?: string,
+): string {
+  const displayProvider = provider ? formatProviderName(provider) : "";
+  const title = success
+    ? displayProvider
+      ? `Connected to ${escapeHtml(displayProvider)}`
+      : "Authorization Successful"
+    : "Authorization Failed";
+  const subtitle = success
+    ? "You can close this tab and return to your assistant."
+    : escapeHtml(message);
+
+  const checkmarkSvg = `<svg class="icon" viewBox="0 0 56 56" fill="none" xmlns="http://www.w3.org/2000/svg">
+      <circle cx="28" cy="28" r="28" fill="var(--positive-bg)"/>
+      <path class="check" d="M17 28.5L24.5 36L39 21" stroke="var(--positive-fg)" stroke-width="3.5" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
+    </svg>`;
+
+  const errorSvg = `<svg class="icon" viewBox="0 0 56 56" fill="none" xmlns="http://www.w3.org/2000/svg">
+      <circle cx="28" cy="28" r="28" fill="var(--negative-bg)"/>
+      <path class="cross cross-1" d="M20 20L36 36" stroke="var(--negative-fg)" stroke-width="3.5" stroke-linecap="round" fill="none"/>
+      <path class="cross cross-2" d="M36 20L20 36" stroke="var(--negative-fg)" stroke-width="3.5" stroke-linecap="round" fill="none"/>
+    </svg>`;
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHtml(title)}</title>
+  <style>
+    :root {
+      --surface: #F5F3EB;
+      --surface-card: #FFFFFF;
+      --card-border: #E8E6DA;
+      --text-primary: #2A2A28;
+      --text-secondary: #4A4A46;
+      --text-tertiary: #A1A096;
+      --positive-bg: #D4DFD0;
+      --positive-fg: #516748;
+      --negative-bg: #F7DAC9;
+      --negative-fg: #DA491A;
+      --shadow: 0 1px 3px rgba(0,0,0,0.04), 0 4px 12px rgba(0,0,0,0.06);
+      --font: -apple-system, BlinkMacSystemFont, "SF Pro Text", "Helvetica Neue", sans-serif;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --surface: #1A1A18;
+        --surface-card: #2A2A28;
+        --card-border: #3A3A37;
+        --text-primary: #F5F3EB;
+        --text-secondary: #BDB9A9;
+        --text-tertiary: #6B6B65;
+        --positive-bg: #1A2316;
+        --positive-fg: #7A8B6F;
+        --negative-bg: #4E281D;
+        --negative-fg: #E86B40;
+        --shadow: 0 1px 3px rgba(0,0,0,0.2), 0 4px 12px rgba(0,0,0,0.3);
+      }
+    }
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: var(--font);
+      background: var(--surface);
+      color: var(--text-primary);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      min-height: 100vh;
+      -webkit-font-smoothing: antialiased;
+    }
+    .card {
+      text-align: center;
+      padding: 48px 40px 40px;
+      background: var(--surface-card);
+      border: 1px solid var(--card-border);
+      border-radius: 16px;
+      box-shadow: var(--shadow);
+      max-width: 380px;
+      width: 100%;
+      opacity: 0;
+      transform: translateY(8px) scale(0.98);
+      animation: cardIn 0.5s cubic-bezier(0.16, 1, 0.3, 1) 0.1s forwards;
+    }
+    @keyframes cardIn {
+      to { opacity: 1; transform: translateY(0) scale(1); }
+    }
+    .icon {
+      width: 56px;
+      height: 56px;
+      margin-bottom: 20px;
+    }
+    .check {
+      stroke-dasharray: 32;
+      stroke-dashoffset: 32;
+      animation: draw 0.4s ease-out 0.45s forwards;
+    }
+    .cross {
+      stroke-dasharray: 22;
+      stroke-dashoffset: 22;
+    }
+    .cross-1 { animation: draw 0.3s ease-out 0.45s forwards; }
+    .cross-2 { animation: draw 0.3s ease-out 0.55s forwards; }
+    @keyframes draw {
+      to { stroke-dashoffset: 0; }
+    }
+    h1 {
+      font-size: 18px;
+      font-weight: 600;
+      letter-spacing: -0.2px;
+      color: var(--text-primary);
+      margin-bottom: 6px;
+    }
+    p {
+      font-size: 13px;
+      line-height: 1.5;
+      color: var(--text-secondary);
+    }
+  </style>
+</head>
+<body>
+  <div class="card">
+    ${success ? checkmarkSvg : errorSvg}
+    <h1>${escapeHtml(title)}</h1>
+    <p>${subtitle}</p>
+  </div>
+</body>
+</html>`;
+}

package/src/security/oauth2.ts

@@ -20,6 +20,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { createServer, type Server } from "node:http";
 
 import { getLogger } from "../util/logger.js";
+import { renderOAuthCompletionPage as renderLoopbackPage } from "./oauth-completion-page.js";
 
 const log = getLogger("oauth2");
 
@@ -289,6 +290,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 +308,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 +322,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 +332,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 +346,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,10 +354,13 @@ function startLoopbackServerAndWaitForCode(
         return;
       }
 
+      log.info(
+        "oauth2 loopback: authorization code received, exchanging for tokens",
+      );
       res.writeHead(200, { "Content-Type": "text/html" });
       res.end(
         renderLoopbackPage(
-          "Authorization successful! You can close this tab.",
+          "You can close this tab and return to your assistant.",
           true,
         ),
       );
@@ -347,6 +370,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 +386,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 +412,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();
@@ -388,21 +434,6 @@ function startLoopbackServerAndWaitForCode(
   });
 }
 
-function escapeHtml(s: string): string {
-  return s
-    .replace(/&/g, "&")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&#39;");
-}
-
-function renderLoopbackPage(message: string, success: boolean): string {
-  const title = success ? "Authorization Successful" : "Authorization Failed";
-  const color = success ? "#4CAF50" : "#f44336";
-  return `<!DOCTYPE html><html><head><title>${escapeHtml(title)}</title><style>body{font-family:system-ui,sans-serif;display:flex;justify-content:center;align-items:center;min-height:100vh;margin:0;background:#f5f5f5}div{text-align:center;padding:2rem;background:white;border-radius:8px;box-shadow:0 2px 4px rgba(0,0,0,0.1)}h1{color:${color}}</style></head><body><div><h1>${escapeHtml(title)}</h1><p>${escapeHtml(message)}</p></div></body></html>`;
-}
-
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -595,7 +626,7 @@ function startLoopbackServerForPreparedFlow(
       res.writeHead(200, { "Content-Type": "text/html" });
       res.end(
         renderLoopbackPage(
-          "Authorization successful! You can close this tab.",
+          "You can close this tab and return to your assistant.",
           true,
         ),
       );
@@ -687,6 +718,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(