@vellumai/assistant 0.4.55 → 0.4.57

package/src/credential-execution/managed-catalog.ts

@@ -0,0 +1,155 @@
+/**
+ * Managed CES credential catalog.
+ *
+ * Discovers platform-managed OAuth connections by calling the platform's CES
+ * catalog endpoint. Returns displayable descriptors with exact
+ * `platform_oauth:<connection_id>` handles suitable for CES tools.
+ *
+ * This module never reveals token values — it only surfaces handle references
+ * and non-secret metadata (provider, account info, scopes, status).
+ */
+
+import { platformOAuthHandle } from "@vellumai/ces-contracts";
+
+import { getPlatformAssistantId } from "../config/env.js";
+import { resolveManagedProxyContext } from "../providers/managed-proxy/context.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("managed-catalog");
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface ManagedCredentialDescriptor {
+  /** CES handle string (e.g. `platform_oauth:conn_abc123`). */
+  handle: string;
+  /** Source of the credential — always `"platform"` for managed entries. */
+  source: "platform";
+  /** Provider key on the platform (e.g. `google`, `slack`). */
+  provider: string;
+  /** Platform-assigned connection identifier. */
+  connectionId: string;
+  /** Human-readable account info (e.g. email), if available. */
+  accountInfo: string | null;
+  /** Granted OAuth scopes, if reported by the platform. */
+  grantedScopes: string[];
+  /** Connection status as reported by the platform (e.g. `active`, `expired`). */
+  status: string;
+}
+
+// ---------------------------------------------------------------------------
+// Platform response shape (non-secret subset)
+// ---------------------------------------------------------------------------
+
+/**
+ * Shape of a single connection entry in the platform catalog response.
+ * Only non-secret fields are parsed; token values are never included.
+ *
+ * Field names match the platform's ManagedConnectionCatalogEntrySerializer:
+ *   handle, connection_id, provider, account_label, scopes_granted, status
+ */
+interface PlatformCatalogEntry {
+  handle: string;
+  connection_id: string;
+  provider: string;
+  account_label?: string | null;
+  scopes_granted?: string[];
+  status?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface FetchManagedCatalogResult {
+  ok: boolean;
+  descriptors: ManagedCredentialDescriptor[];
+  error?: string;
+}
+
+/**
+ * Fetch the managed credential catalog from the platform.
+ *
+ * Requires managed proxy prerequisites (platform base URL + assistant API key).
+ * Returns an empty list with `ok: true` when prerequisites are missing —
+ * callers should not treat a missing platform as an error.
+ *
+ * Errors from the platform are captured and returned as `ok: false` with an
+ * error message that never contains secret material.
+ */
+export async function fetchManagedCatalog(): Promise<FetchManagedCatalogResult> {
+  const ctx = await resolveManagedProxyContext();
+
+  if (!ctx.enabled) {
+    return { ok: true, descriptors: [] };
+  }
+
+  const assistantId = getPlatformAssistantId();
+  if (!assistantId) {
+    log.warn("PLATFORM_ASSISTANT_ID not set; cannot fetch managed catalog");
+    return { ok: true, descriptors: [] };
+  }
+
+  const url = `${ctx.platformBaseUrl}/v1/assistants/${encodeURIComponent(assistantId)}/oauth/managed/catalog/`;
+
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: `Api-Key ${ctx.assistantApiKey}`,
+        Accept: "application/json",
+      },
+    });
+
+    if (!response.ok) {
+      const statusText = response.statusText || `HTTP ${response.status}`;
+      log.warn(
+        `Platform CES catalog returned ${response.status}: ${statusText}`,
+      );
+      return {
+        ok: false,
+        descriptors: [],
+        error: `Platform CES catalog request failed (${response.status})`,
+      };
+    }
+
+    // The platform returns a flat JSON array of catalog entries
+    // (serialized with many=True), not a wrapper object.
+    const body = (await response.json()) as PlatformCatalogEntry[];
+
+    if (!Array.isArray(body)) {
+      return {
+        ok: false,
+        descriptors: [],
+        error: "Platform CES catalog returned unexpected response format",
+      };
+    }
+
+    const descriptors: ManagedCredentialDescriptor[] = body.map((entry) => ({
+      handle: platformOAuthHandle(entry.connection_id),
+      source: "platform" as const,
+      provider: entry.provider,
+      connectionId: entry.connection_id,
+      accountInfo: entry.account_label ?? null,
+      grantedScopes: entry.scopes_granted ?? [],
+      status: entry.status ?? "unknown",
+    }));
+
+    return { ok: true, descriptors };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    // Ensure the error message does not leak secrets — strip any URL params
+    // that might contain tokens (defensive, since we use Api-Key header).
+    const safeMessage = message.replace(
+      /Api-Key\s+\S+/gi,
+      "Api-Key [REDACTED]",
+    );
+    log.warn(`Failed to fetch managed CES catalog: ${safeMessage}`);
+    return {
+      ok: false,
+      descriptors: [],
+      error: `Failed to fetch managed CES catalog: ${safeMessage}`,
+    };
+  }
+}

package/src/credential-execution/process-manager.ts

@@ -0,0 +1,451 @@
+/**
+ * CES process manager.
+ *
+ * Manages the CES child process lifecycle for local mode, and creates
+ * transport connections for managed sidecar mode.
+ *
+ * Local mode: Spawns the `credential-executor` binary as a child process
+ * and creates a stdio-based CesTransport for the RPC client. The manager
+ * owns the process lifecycle (start, health monitoring, graceful shutdown).
+ *
+ * Managed mode: Connects to the CES sidecar's bootstrap Unix socket and
+ * creates a socket-based CesTransport. The CES sidecar manages its own
+ * lifecycle; the process manager only manages the transport connection.
+ *
+ * Feature-flag gate: Managed sidecar mode is controlled by the
+ * `ces-managed-sidecar` feature flag (checked via the required
+ * AssistantConfig). When the flag is off, the process manager skips
+ * managed discovery even in containerized environments, ensuring
+ * rollback safety.
+ *
+ * Managed env contract:
+ * - CES_BOOTSTRAP_SOCKET  — Path to the bootstrap Unix socket (shared emptyDir)
+ * - /assistant-data-ro     — Assistant data mounted read-only into the CES sidecar
+ * - /ces-data              — CES private data directory (separate PVC)
+ * - CES_HEALTH_PORT        — Health check port exposed by the CES sidecar
+ */
+
+import { createConnection, type Socket } from "node:net";
+import { StringDecoder } from "node:string_decoder";
+
+import type { Subprocess } from "bun";
+
+import type { AssistantConfig } from "../config/schema.js";
+import { getLogger } from "../util/logger.js";
+import type { CesTransport } from "./client.js";
+import {
+  discoverCes,
+  discoverLocalCes,
+  type DiscoveryResult,
+  type LocalDiscoverySuccess,
+  type ManagedDiscoverySuccess,
+} from "./executable-discovery.js";
+import { isCesManagedSidecarEnabled } from "./feature-gates.js";
+
+const log = getLogger("ces-process-manager");
+
+const SHUTDOWN_GRACE_MS = 5_000;
+const SOCKET_CONNECT_TIMEOUT_MS = 5_000;
+
+// ---------------------------------------------------------------------------
+// Well-known managed env paths
+// ---------------------------------------------------------------------------
+
+/**
+ * Read-only mount point where the CES sidecar can read assistant data.
+ * This is the assistant-data PVC mounted into the CES container as read-only.
+ */
+export const CES_ASSISTANT_DATA_READONLY_MOUNT = "/assistant-data-ro";
+
+/**
+ * Private data directory for the CES sidecar (separate PVC).
+ * CES stores grants, audit logs, and credential material here.
+ */
+export const CES_PRIVATE_DATA_DIR = "/ces-data";
+
+// ---------------------------------------------------------------------------
+// Process manager configuration
+// ---------------------------------------------------------------------------
+
+export interface CesProcessManagerConfig {
+  /**
+   * Assistant configuration for feature-flag checks.
+   * The managed sidecar path is gated behind the `ces-managed-sidecar`
+   * feature flag via this config.  When omitted (e.g. CLI / admin
+   * callers), managed mode is allowed unconditionally.
+   */
+  assistantConfig?: AssistantConfig;
+}
+
+// ---------------------------------------------------------------------------
+// Process manager state
+// ---------------------------------------------------------------------------
+
+export interface CesProcessManager {
+  /**
+   * Start the CES process (local) or connect to the sidecar (managed).
+   * Returns a CesTransport ready for use with createCesClient().
+   *
+   * When the `ces-managed-sidecar` feature flag is off, managed mode
+   * is skipped even in containerized environments — the process manager
+   * falls back to local discovery.
+   *
+   * Throws if CES is unavailable.
+   */
+  start(): Promise<CesTransport>;
+
+  /** Gracefully stop the CES process (local) or disconnect (managed). */
+  stop(): Promise<void>;
+
+  /**
+   * Force-stop the CES process even if start() hasn't finished yet.
+   * Unlike stop(), this works regardless of the `running` state — it kills
+   * any child process or destroys any managed socket immediately.
+   */
+  forceStop(): Promise<void>;
+
+  /** The discovery result from the last start() call, or null if not started. */
+  getDiscoveryResult(): DiscoveryResult | null;
+
+  /** Whether the process manager is currently running. */
+  isRunning(): boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createCesProcessManager(
+  config: CesProcessManagerConfig,
+): CesProcessManager {
+  let childProcess: Subprocess | null = null;
+  let managedSocket: Socket | null = null;
+  let discoveryResult: DiscoveryResult | null = null;
+  let running = false;
+
+  return {
+    async start(): Promise<CesTransport> {
+      if (running) {
+        throw new Error("CES process manager is already running");
+      }
+
+      // Feature-flag gate: when the managed sidecar flag is off, skip
+      // managed discovery entirely. This ensures rollback safety —
+      // disabling the flag leaves existing non-agent platform consumers
+      // intact.
+      const managedAllowed = config.assistantConfig
+        ? isCesManagedSidecarEnabled(config.assistantConfig)
+        : true; // No config → allow managed mode unconditionally (CLI/admin callers)
+
+      if (managedAllowed) {
+        discoveryResult = await discoverCes();
+      } else {
+        log.info(
+          "CES managed sidecar feature flag is off — skipping managed discovery, falling back to local",
+        );
+        discoveryResult = discoverLocalCes();
+      }
+
+      if (discoveryResult.mode === "unavailable") {
+        throw new CesUnavailableError(discoveryResult.reason);
+      }
+
+      if (discoveryResult.mode === "local") {
+        const transport = await startLocalProcess(discoveryResult);
+        running = true;
+        return transport;
+      }
+
+      // managed mode
+      const transport = await connectManagedSocket(discoveryResult);
+      running = true;
+      return transport;
+    },
+
+    async stop(): Promise<void> {
+      if (!running) return;
+
+      if (childProcess) {
+        await stopLocalProcess(childProcess);
+        childProcess = null;
+      }
+
+      if (managedSocket) {
+        managedSocket.destroy();
+        managedSocket = null;
+      }
+
+      running = false;
+      log.info("CES process manager stopped");
+    },
+
+    async forceStop(): Promise<void> {
+      if (childProcess) {
+        childProcess.kill("SIGKILL");
+        await childProcess.exited.catch(() => {});
+        childProcess = null;
+      }
+
+      if (managedSocket) {
+        managedSocket.destroy();
+        managedSocket = null;
+      }
+
+      running = false;
+      log.info("CES process manager force-stopped");
+    },
+
+    getDiscoveryResult(): DiscoveryResult | null {
+      return discoveryResult;
+    },
+
+    isRunning(): boolean {
+      return running;
+    },
+  };
+
+  // -------------------------------------------------------------------------
+  // Local mode — child process over stdio
+  // -------------------------------------------------------------------------
+
+  async function startLocalProcess(
+    discovery: LocalDiscoverySuccess,
+  ): Promise<CesTransport> {
+    log.info(
+      { executable: discovery.executablePath },
+      "Spawning CES child process",
+    );
+
+    const proc = Bun.spawn({
+      cmd: [discovery.executablePath],
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "ignore",
+      env: {
+        ...process.env,
+        // Signal to CES that it was launched by the assistant
+        CES_LAUNCHED_BY: "assistant",
+      },
+    });
+
+    childProcess = proc;
+
+    log.info({ pid: proc.pid }, "CES child process started");
+
+    return createStdioTransport(proc);
+  }
+
+  // -------------------------------------------------------------------------
+  // Managed mode — Unix socket connection
+  // -------------------------------------------------------------------------
+
+  async function connectManagedSocket(
+    discovery: ManagedDiscoverySuccess,
+  ): Promise<CesTransport> {
+    log.info(
+      { socketPath: discovery.socketPath },
+      "Connecting to managed CES sidecar",
+    );
+
+    const socket = await connectWithTimeout(
+      discovery.socketPath,
+      SOCKET_CONNECT_TIMEOUT_MS,
+    );
+    managedSocket = socket;
+
+    log.info("Connected to managed CES sidecar");
+
+    return createSocketTransport(socket);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Stdio transport (local mode)
+// ---------------------------------------------------------------------------
+
+function createStdioTransport(proc: Subprocess): CesTransport {
+  const messageHandlers: Array<(message: string) => void> = [];
+  let buffer = "";
+  let alive = true;
+
+  // Read stdout line by line — narrow past `number` union arm from Subprocess type
+  if (proc.stdout && typeof proc.stdout !== "number") {
+    const reader = proc.stdout.getReader();
+    const decoder = new TextDecoder();
+
+    void (async () => {
+      try {
+        while (true) {
+          const { value, done } = await reader.read();
+          if (done) break;
+
+          buffer += decoder.decode(value, { stream: true });
+          let newlineIdx: number;
+          while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+            const line = buffer.slice(0, newlineIdx).trim();
+            buffer = buffer.slice(newlineIdx + 1);
+            if (line) {
+              for (const handler of messageHandlers) {
+                handler(line);
+              }
+            }
+          }
+        }
+      } catch {
+        // Process ended
+      } finally {
+        alive = false;
+      }
+    })();
+  }
+
+  // Track process exit
+  proc.exited.then(() => {
+    alive = false;
+  });
+
+  return {
+    write(line: string): void {
+      if (!alive || !proc.stdin || typeof proc.stdin === "number") {
+        throw new Error("CES stdio transport is not alive");
+      }
+      proc.stdin.write(line + "\n");
+    },
+
+    onMessage(handler: (message: string) => void): void {
+      messageHandlers.push(handler);
+    },
+
+    isAlive(): boolean {
+      return alive;
+    },
+
+    close(): void {
+      alive = false;
+      if (proc.stdin && typeof proc.stdin !== "number") {
+        proc.stdin.end();
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Socket transport (managed mode)
+// ---------------------------------------------------------------------------
+
+function createSocketTransport(socket: Socket): CesTransport {
+  const messageHandlers: Array<(message: string) => void> = [];
+  let buffer = "";
+  let alive = true;
+
+  const decoder = new StringDecoder("utf8");
+
+  socket.on("data", (chunk: Buffer | string) => {
+    buffer += typeof chunk === "string" ? chunk : decoder.write(chunk);
+    let newlineIdx: number;
+    while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, newlineIdx).trim();
+      buffer = buffer.slice(newlineIdx + 1);
+      if (line) {
+        for (const handler of messageHandlers) {
+          handler(line);
+        }
+      }
+    }
+  });
+
+  socket.on("close", () => {
+    alive = false;
+  });
+
+  socket.on("error", (err) => {
+    log.warn({ err }, "CES socket transport error");
+    alive = false;
+  });
+
+  return {
+    write(line: string): void {
+      if (!alive || socket.destroyed) {
+        throw new Error("CES socket transport is not alive");
+      }
+      socket.write(line + "\n");
+    },
+
+    onMessage(handler: (message: string) => void): void {
+      messageHandlers.push(handler);
+    },
+
+    isAlive(): boolean {
+      return alive && !socket.destroyed;
+    },
+
+    close(): void {
+      alive = false;
+      socket.destroy();
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function stopLocalProcess(proc: Subprocess): Promise<void> {
+  log.info({ pid: proc.pid }, "Stopping CES child process");
+  proc.kill("SIGTERM");
+
+  const graceful = await Promise.race([
+    proc.exited.then(() => true),
+    new Promise<false>((resolve) =>
+      setTimeout(() => resolve(false), SHUTDOWN_GRACE_MS),
+    ),
+  ]);
+
+  if (!graceful) {
+    log.warn("CES child process did not exit gracefully, sending SIGKILL");
+    proc.kill("SIGKILL");
+    await proc.exited;
+  }
+
+  log.info("CES child process stopped");
+}
+
+function connectWithTimeout(
+  socketPath: string,
+  timeoutMs: number,
+): Promise<Socket> {
+  return new Promise<Socket>((resolve, reject) => {
+    const socket = createConnection({ path: socketPath });
+
+    const timer = setTimeout(() => {
+      socket.destroy();
+      reject(
+        new Error(
+          `Connection to CES socket at ${socketPath} timed out after ${timeoutMs}ms`,
+        ),
+      );
+    }, timeoutMs);
+
+    socket.on("connect", () => {
+      clearTimeout(timer);
+      resolve(socket);
+    });
+
+    socket.on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Error types
+// ---------------------------------------------------------------------------
+
+/** CES is not available in the current deployment (executable or socket missing). */
+export class CesUnavailableError extends Error {
+  constructor(reason: string) {
+    super(`CES is unavailable: ${reason}`);
+    this.name = "CesUnavailableError";
+  }
+}

package/src/daemon/approval-generators.ts

@@ -46,15 +46,15 @@ const APPROVAL_CONVERSATION_TOOL_SCHEMA = {
           "keep_pending",
           "approve_once",
           "approve_10m",
-          "approve_thread",
+          "approve_conversation",
           "approve_always",
           "reject",
         ],
         description:
           "The decision: keep_pending if the user is asking questions or unclear, " +
           "approve_once to approve this single request, approve_10m to approve all " +
-          "requests for 10 minutes, approve_thread to approve all requests in this " +
-          "thread, approve_always to approve this tool permanently, reject to deny the request.",
+          "requests for 10 minutes, approve_conversation to approve all requests in this " +
+          "conversation, approve_always to approve this tool permanently, reject to deny the request.",
       },
       replyText: {
         type: "string",
@@ -75,7 +75,7 @@ const VALID_DISPOSITIONS: ReadonlySet<string> = new Set([
   "keep_pending",
   "approve_once",
   "approve_10m",
-  "approve_thread",
+  "approve_conversation",
   "approve_always",
   "reject",
 ]);
@@ -91,7 +91,10 @@ export function createApprovalCopyGenerator(): ApprovalCopyGenerator {
     const config = loadConfig();
     let provider;
     try {
-      provider = getFailoverProvider(config.provider, config.providerOrder);
+      provider = getFailoverProvider(
+        config.services.inference.provider,
+        config.providerOrder,
+      );
     } catch {
       return null;
     }
@@ -142,10 +145,13 @@ export function createApprovalCopyGenerator(): ApprovalCopyGenerator {
 export function createApprovalConversationGenerator(): ApprovalConversationGenerator {
   return async (context) => {
     const config = loadConfig();
-    if (!listProviders().includes(config.provider)) {
+    if (!listProviders().includes(config.services.inference.provider)) {
       throw new Error("No provider available for approval conversation");
     }
-    const provider = getFailoverProvider(config.provider, config.providerOrder);
+    const provider = getFailoverProvider(
+      config.services.inference.provider,
+      config.providerOrder,
+    );
 
     const pendingDescription = context.pendingApprovals
       .map((p) => `- Request ${p.requestId}: tool "${p.toolName}"`)

package/src/daemon/assistant-attachments.ts

@@ -17,8 +17,8 @@ import {
 // Constants
 // ---------------------------------------------------------------------------
 
-/** Maximum size in bytes for a single assistant attachment (20 MB). */
-export const MAX_ASSISTANT_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+/** Maximum size in bytes for a single assistant attachment (100 MB). */
+export const MAX_ASSISTANT_ATTACHMENT_BYTES = 100 * 1024 * 1024;
 
 // ---------------------------------------------------------------------------
 // Types
@@ -455,7 +455,7 @@ export type ApproveHostRead = (filePath: string) => Promise<boolean>;
  * Resolve a host directive to a draft attachment.
  *
  * Requires an absolute path. Before reading, calls the `approve` callback
- * so the session layer can gate access via the user-facing permission prompt.
+ * so the conversation layer can gate access via the user-facing permission prompt.
  */
 export async function resolveHostDirective(
   directive: DirectiveRequest,