@vellumai/credential-executor 0.10.5 → 0.10.6-dev.202607062043.72bc40b

package/node_modules/@vellumai/service-contracts/src/__tests__/ingress.test.ts

@@ -5,10 +5,8 @@ import {
   normalizePublicBaseUrl,
 } from "../ingress.js";
 import {
-  buildTwilioConnectActionUrl,
   buildTwilioMediaStreamUrl,
   buildTwilioPhoneNumberWebhookUrls,
-  buildTwilioRelayUrl,
   buildTwilioVoiceWebhookUrl,
   resolveTwilioPublicBaseUrl,
 } from "../twilio-ingress.js";
@@ -90,12 +88,6 @@ describe("Twilio ingress helpers", () => {
     expect(buildTwilioVoiceWebhookUrl("https://example.test", "call-123")).toBe(
       "https://example.test/webhooks/twilio/voice?callSessionId=call-123",
     );
-    expect(buildTwilioConnectActionUrl("https://example.test")).toBe(
-      "https://example.test/webhooks/twilio/connect-action",
-    );
-    expect(buildTwilioRelayUrl("https://example.test")).toBe(
-      "wss://example.test/webhooks/twilio/relay",
-    );
     expect(buildTwilioMediaStreamUrl("http://example.test")).toBe(
       "ws://example.test/webhooks/twilio/media-stream",
     );

package/node_modules/@vellumai/service-contracts/src/twilio-ingress.ts

@@ -2,9 +2,6 @@ import { normalizePublicBaseUrl } from "./ingress.js";
 
 export const TWILIO_VOICE_WEBHOOK_PATH = "/webhooks/twilio/voice";
 export const TWILIO_STATUS_WEBHOOK_PATH = "/webhooks/twilio/status";
-export const TWILIO_CONNECT_ACTION_WEBHOOK_PATH =
-  "/webhooks/twilio/connect-action";
-export const TWILIO_RELAY_WEBHOOK_PATH = "/webhooks/twilio/relay";
 export const TWILIO_MEDIA_STREAM_WEBHOOK_PATH = "/webhooks/twilio/media-stream";
 
 /**
@@ -13,9 +10,9 @@ export const TWILIO_MEDIA_STREAM_WEBHOOK_PATH = "/webhooks/twilio/media-stream";
  * with the actual public URL (from Velay registration, config, or the
  * `X-Vellum-Ingress-URL` header) before returning TwiML to Twilio.
  *
- * The placeholder uses `https://` so that `buildTwilioRelayUrl` /
- * `buildTwilioMediaStreamUrl` can apply the standard `http→ws` scheme
- * conversion, producing `wss://__VELLUM_PUBLIC_BASE_URL__/…` in the output.
+ * The placeholder uses `https://` so that `buildTwilioMediaStreamUrl` can
+ * apply the standard `http→ws` scheme conversion, producing
+ * `wss://__VELLUM_PUBLIC_BASE_URL__/…` in the output.
  */
 export const TWILIO_PUBLIC_BASE_URL_PLACEHOLDER =
   "https://__VELLUM_PUBLIC_BASE_URL__";
@@ -58,14 +55,6 @@ export function buildTwilioStatusWebhookUrl(baseUrl: string): string {
   return `${baseUrl}${TWILIO_STATUS_WEBHOOK_PATH}`;
 }
 
-export function buildTwilioConnectActionUrl(baseUrl: string): string {
-  return `${baseUrl}${TWILIO_CONNECT_ACTION_WEBHOOK_PATH}`;
-}
-
-export function buildTwilioRelayUrl(baseUrl: string): string {
-  return `${toTwilioWebSocketBaseUrl(baseUrl)}${TWILIO_RELAY_WEBHOOK_PATH}`;
-}
-
 export function buildTwilioMediaStreamUrl(baseUrl: string): string {
   return `${toTwilioWebSocketBaseUrl(baseUrl)}${TWILIO_MEDIA_STREAM_WEBHOOK_PATH}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/credential-executor",
-  "version": "0.10.5",
+  "version": "0.10.6-dev.202607062043.72bc40b",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/local-standalone.test.ts

@@ -0,0 +1,233 @@
+/**
+ * Local CES standalone-sibling test (real entrypoint subprocess).
+ *
+ * Spawns the actual `main.ts` entrypoint with `CES_STANDALONE=1` and **stdin
+ * closed** — the way the CLI launches the sibling (the `CES_STANDALONE`
+ * opt-in) — and verifies that CES:
+ *
+ *   1. binds its Unix socket and serves RPC despite having no stdio parent
+ *      (lifecycle anchored to SIGTERM, not stdin), and
+ *   2. survives a client disconnecting, and
+ *   3. shuts down on SIGTERM.
+ *
+ * Local mode has no TCP health server, so this runs without binding a TCP port.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { createConnection, type Socket } from "node:net";
+import { existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+import {
+  CES_PROTOCOL_VERSION,
+  CesRpcMethod,
+  type HandshakeAck,
+  type RpcEnvelope,
+  type ListCredentialsResponse,
+} from "@vellumai/service-contracts/credential-rpc";
+
+import type { Subprocess } from "bun";
+
+function delay(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+async function waitForSocket(
+  socketPath: string,
+  timeoutMs = 10_000,
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (existsSync(socketPath)) return;
+    await delay(50);
+  }
+  throw new Error(`Standalone CES socket did not appear within ${timeoutMs}ms`);
+}
+
+function connectToSocket(
+  socketPath: string,
+  { maxRetries = 40, baseDelayMs = 25 } = {},
+): Promise<Socket> {
+  return new Promise((resolveConn, reject) => {
+    let attempt = 0;
+    const tryConnect = () => {
+      const sock = createConnection(socketPath, () => {
+        sock.removeAllListeners("error");
+        resolveConn(sock);
+      });
+      sock.on("error", (err: NodeJS.ErrnoException) => {
+        sock.destroy();
+        attempt++;
+        if (
+          attempt < maxRetries &&
+          (err.code === "ENOENT" || err.code === "ECONNREFUSED")
+        ) {
+          setTimeout(tryConnect, baseDelayMs);
+        } else {
+          reject(err);
+        }
+      });
+    };
+    tryConnect();
+  });
+}
+
+/** Read one newline-delimited JSON message from the socket. */
+function readOne<T>(sock: Socket, timeoutMs = 5_000): Promise<T> {
+  return new Promise((resolveMsg, reject) => {
+    let buffer = "";
+    const timer = setTimeout(() => {
+      sock.removeAllListeners("data");
+      reject(new Error("Timed out waiting for a message"));
+    }, timeoutMs);
+    const onData = (chunk: Buffer) => {
+      buffer += chunk.toString("utf-8");
+      const idx = buffer.indexOf("\n");
+      if (idx === -1) return;
+      clearTimeout(timer);
+      sock.removeListener("data", onData);
+      try {
+        resolveMsg(JSON.parse(buffer.slice(0, idx).trim()) as T);
+      } catch (err) {
+        reject(err as Error);
+      }
+    };
+    sock.on("data", onData);
+    sock.on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+async function handshake(
+  sock: Socket,
+  sessionId: string,
+): Promise<HandshakeAck> {
+  sock.write(
+    JSON.stringify({
+      type: "handshake_request",
+      protocolVersion: CES_PROTOCOL_VERSION,
+      sessionId,
+    }) + "\n",
+  );
+  return readOne<HandshakeAck>(sock);
+}
+
+let tmpDir: string | undefined;
+let proc: Subprocess | undefined;
+
+afterEach(async () => {
+  if (proc) {
+    proc.kill("SIGTERM");
+    await Promise.race([proc.exited, delay(3_000)]);
+    proc = undefined;
+  }
+  if (tmpDir) {
+    try {
+      rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+      /* ok */
+    }
+    tmpDir = undefined;
+  }
+});
+
+describe("local CES standalone sibling (real entrypoint)", () => {
+  test("serves over a socket with no stdio parent, survives disconnect, exits on SIGTERM", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "ces-standalone-"));
+    const socketPath = join(tmpDir, "ces.sock");
+    const securityDir = join(tmpDir, "protected");
+    const workspaceDir = join(tmpDir, "workspace");
+    mkdirSync(securityDir, { recursive: true });
+    mkdirSync(workspaceDir, { recursive: true });
+
+    const localMain = resolve(__dirname, "..", "main.ts");
+
+    // CES_STANDALONE=1 + stdin closed is how the CLI launches the sibling.
+    proc = Bun.spawn({
+      cmd: [process.execPath, localMain],
+      env: {
+        ...process.env,
+        CES_STANDALONE: "1",
+        CES_LOCAL_SOCKET: socketPath,
+        CREDENTIAL_SECURITY_DIR: securityDir,
+        VELLUM_WORKSPACE_DIR: workspaceDir,
+      },
+      stdin: "ignore",
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+
+    await waitForSocket(socketPath);
+    expect(proc.killed).toBe(false);
+
+    // First client: handshake + a real RPC.
+    const first = await connectToSocket(socketPath);
+    const ack1 = await handshake(first, "sibling-1");
+    expect(ack1.accepted).toBe(true);
+
+    first.write(
+      JSON.stringify({
+        type: "rpc",
+        id: "rpc-1",
+        kind: "request",
+        method: CesRpcMethod.ListCredentials,
+        payload: {},
+        timestamp: new Date().toISOString(),
+      }) + "\n",
+    );
+    const rpcResp = await readOne<RpcEnvelope & { type: "rpc" }>(first);
+    expect((rpcResp.payload as ListCredentialsResponse).accounts).toEqual([]);
+
+    // Disconnect — CES must stay up.
+    first.destroy();
+    await delay(200);
+    expect(proc.killed).toBe(false);
+
+    // Reconnect proves it survived.
+    const second = await connectToSocket(socketPath);
+    const ack2 = await handshake(second, "sibling-2");
+    expect(ack2.accepted).toBe(true);
+    second.destroy();
+
+    // SIGTERM shuts it down.
+    proc.kill("SIGTERM");
+    const exited = await Promise.race([
+      proc.exited.then(() => true),
+      delay(5_000).then(() => false),
+    ]);
+    expect(exited).toBe(true);
+  }, 30_000);
+
+  test("without CES_STANDALONE, exits when stdin closes (stdio child)", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "ces-stdio-"));
+    const securityDir = join(tmpDir, "protected");
+    const workspaceDir = join(tmpDir, "workspace");
+    mkdirSync(securityDir, { recursive: true });
+    mkdirSync(workspaceDir, { recursive: true });
+
+    const localMain = resolve(__dirname, "..", "main.ts");
+
+    // Default mode: stdin "ignore" EOFs immediately, so the stdio server's
+    // input stream ends and CES shuts down on its own — the today behavior.
+    proc = Bun.spawn({
+      cmd: [process.execPath, localMain],
+      env: {
+        ...process.env,
+        CREDENTIAL_SECURITY_DIR: securityDir,
+        VELLUM_WORKSPACE_DIR: workspaceDir,
+      },
+      stdin: "ignore",
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+
+    const exited = await Promise.race([
+      proc.exited.then(() => true),
+      delay(10_000).then(() => false),
+    ]);
+    expect(exited).toBe(true);
+  }, 20_000);
+});

package/src/__tests__/transport.test.ts

@@ -23,7 +23,11 @@ import {
   type RpcEnvelope,
 } from "@vellumai/service-contracts/credential-rpc";
 
-import { getCesDataRoot, getBootstrapSocketPath, getHealthPort } from "../paths.js";
+import {
+  getCesDataRoot,
+  getBootstrapSocketPath,
+  getHealthPort,
+} from "../paths.js";
 import { CesRpcServer, type RpcHandlerRegistry } from "../server.js";
 
 // ---------------------------------------------------------------------------
@@ -104,7 +108,16 @@ function createTestServer(handlers: RpcHandlerRegistry = {}) {
     return JSON.parse(lines[lines.length - 1]) as RpcEnvelope;
   }
 
-  return { server, input, output, send, collectOutputLines, handshake, rpc, logs };
+  return {
+    server,
+    input,
+    output,
+    send,
+    collectOutputLines,
+    handshake,
+    rpc,
+    logs,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -194,15 +207,15 @@ describe("health probes", () => {
 // ---------------------------------------------------------------------------
 
 describe("local entrypoint transport isolation", () => {
-  test("main.ts uses process.stdin/stdout, not TCP listeners", () => {
+  test("main.ts serves over stdio or a Unix socket, never a TCP listener", () => {
     const src = readFileSync(resolve(__dirname, "..", "main.ts"), "utf-8");
-    // Uses stdin/stdout for transport
+    // Serves the stdio-child transport (default mode).
     expect(src).toMatch(/process\.stdin/);
     expect(src).toMatch(/process\.stdout/);
-    // Does not open any TCP or Unix socket listener
+    // Standalone mode (CES_STANDALONE=1) listens on a Unix socket path only —
+    // never a numeric TCP port — and never opens an HTTP server.
     expect(src).not.toMatch(/Bun\.serve\(/);
-    expect(src).not.toMatch(/createServer\(/);
-    expect(src).not.toMatch(/\.listen\(/);
+    expect(src).not.toMatch(/\.listen\(\d+/);
   });
 
   test("main.ts logs to stderr, not stdout (avoids polluting transport)", () => {
@@ -310,9 +323,10 @@ describe("CesRpcServer", () => {
 
     const resp = await rpc("nonexistent_method", {});
     expect(resp.kind).toBe("response");
-    expect((resp.payload as { success: boolean; error: { code: string } }).error.code).toBe(
-      "METHOD_NOT_FOUND",
-    );
+    expect(
+      (resp.payload as { success: boolean; error: { code: string } }).error
+        .code,
+    ).toBe("METHOD_NOT_FOUND");
 
     server.close();
     input.end();
@@ -332,7 +346,10 @@ describe("CesRpcServer", () => {
 
     const resp = await rpc("fail_method", {});
     expect(resp.kind).toBe("response");
-    const payload = resp.payload as { success: boolean; error: { code: string; message: string } };
+    const payload = resp.payload as {
+      success: boolean;
+      error: { code: string; message: string };
+    };
     expect(payload.error.code).toBe("HANDLER_ERROR");
     expect(payload.error.message).toMatch(/Intentional test failure/);
 

package/src/main.ts

@@ -1,27 +1,28 @@
 #!/usr/bin/env bun
 /**
- * Local CES entrypoint.
+ * Local CES entrypoint. Two run modes:
  *
- * In local mode the assistant spawns CES as a child process and communicates
- * over stdin/stdout using newline-delimited JSON. This entrypoint:
+ * - **stdio child (default):** the assistant spawns CES as a child process and
+ *   communicates over stdin/stdout. CES shuts down when stdin closes (parent
+ *   exit) or on SIGTERM. This is today's behavior.
  *
- * 1. Ensures the CES-private data directories exist.
- * 2. Starts the RPC server on process.stdin / process.stdout.
- * 3. Shuts down cleanly when stdin closes (parent exit) or SIGTERM arrives.
+ * - **standalone sibling (`CES_STANDALONE=1`):** CES is launched independently
+ *   by the CLI (the opt-in), serves RPC over a
+ *   Unix socket (`getLocalSocketPath()`), and runs until SIGTERM — no stdio.
+ *   This is the direction local CES is converging on; the socket-serving here
+ *   is temporary scaffolding to be folded into a single unified CES entrypoint.
  *
- * Local mode never opens a TCP listener or Unix socket. All communication
- * flows through the inherited stdio file descriptors, which are automatically
- * closed when the parent process exits.
- *
- * The stdio transport ensures that shell subprocesses spawned by CES
- * (e.g. for `run_authenticated_command`) do not accidentally inherit the
- * command channel — Bun's `Bun.spawn` defaults to "pipe" for stdio on
- * child processes, so CES's own stdin/stdout are not leaked to subprocesses.
+ * Local mode never opens a TCP listener. Neither the stdio transport nor the
+ * Unix socket's listening fd is inherited by shell subprocesses spawned by CES
+ * (e.g. for `run_authenticated_command`): Bun's `Bun.spawn` defaults to "pipe"
+ * for stdio, and the listening socket is not passed to those subprocesses.
  */
 
-import { mkdirSync } from "node:fs";
+import { mkdirSync, unlinkSync } from "node:fs";
+import { createServer as createNetServer, type Socket } from "node:net";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { Readable, Writable } from "node:stream";
 
 import {
   CES_PROTOCOL_VERSION,
@@ -52,6 +53,7 @@ import {
   getCesGrantsDir,
   getCesLogDir,
   getCesToolStoreDir,
+  getLocalSocketPath,
 } from "./paths.js";
 import {
   buildHandlersWithHttp,
@@ -122,9 +124,7 @@ function getSecurityDir(): string {
 // Build RPC handler registry
 // ---------------------------------------------------------------------------
 
-function buildHandlers(
-  secureKeyBackend: SecureKeyBackend,
-): RpcHandlerRegistry {
+function buildHandlers(secureKeyBackend: SecureKeyBackend): RpcHandlerRegistry {
   // -- Grant stores ----------------------------------------------------------
   const persistentGrantStore = new PersistentGrantStore(
     getCesGrantsDir("local"),
@@ -350,14 +350,103 @@ function buildHandlers(
 // Main
 // ---------------------------------------------------------------------------
 
+/**
+ * Serve RPC over a Unix socket for standalone-sibling mode.
+ *
+ * Binds the socket, accepts connections concurrently (each served by its own
+ * CesRpcServer over the shared handler registry), and unlinks the socket when
+ * the signal aborts. Temporary scaffolding — this serving path will be folded
+ * into a single unified CES entrypoint shared with the managed sidecar.
+ */
+function serveStandaloneSocket(opts: {
+  socketPath: string;
+  handlers: RpcHandlerRegistry;
+  signal: AbortSignal;
+  logger: Pick<Console, "log" | "warn" | "error">;
+  log: ReturnType<typeof getLogger>;
+}): void {
+  const { socketPath, handlers, signal, logger, log } = opts;
+
+  mkdirSync(dirname(socketPath), { recursive: true });
+  try {
+    unlinkSync(socketPath);
+  } catch {
+    // stale or absent — fine
+  }
+
+  const netServer = createNetServer();
+
+  netServer.on("error", (err) => {
+    log.warn({ err }, "CES standalone socket server error");
+  });
+
+  netServer.on("connection", (socket: Socket) => {
+    const readable = new Readable({ read() {} });
+    const writable = new Writable({
+      write(chunk, _encoding, callback) {
+        if (socket.writable) {
+          socket.write(chunk, callback);
+        } else {
+          callback(new Error("Socket no longer writable"));
+        }
+      },
+    });
+    socket.on("data", (chunk) => readable.push(chunk));
+    socket.on("end", () => readable.push(null));
+    socket.on("error", (err) => {
+      readable.destroy(err);
+      writable.destroy(err);
+    });
+
+    const server = new CesRpcServer({
+      input: readable,
+      output: writable,
+      handlers,
+      logger,
+      signal,
+      onApiKeyUpdate: () => {},
+    });
+    void server.serve().catch((err) => {
+      server.close();
+      log.warn(
+        { err },
+        "CES standalone connection ended with a transport error",
+      );
+    });
+  });
+
+  netServer.listen(socketPath, () => {
+    log.info(`CES standalone socket listening at ${socketPath}`);
+  });
+
+  signal.addEventListener(
+    "abort",
+    () => {
+      netServer.close();
+      try {
+        unlinkSync(socketPath);
+      } catch {
+        // already removed
+      }
+    },
+    { once: true },
+  );
+}
+
 async function main(): Promise<void> {
   ensureDataDirs();
 
   initLogger({ dir: getCesLogDir(), retentionDays: 30 });
   const log = getLogger("main");
 
+  // `CES_STANDALONE=1` runs CES as an independent, CLI-launched sibling over a
+  // Unix socket; otherwise CES is the assistant's stdio child, as today.
+  const standalone = process.env["CES_STANDALONE"] === "1";
+
   log.info(
-    `Starting CES v${CES_PROTOCOL_VERSION} (local mode, stdio transport)`,
+    `Starting CES v${CES_PROTOCOL_VERSION} (local mode, ${
+      standalone ? "standalone socket" : "stdio"
+    } transport)`,
   );
 
   const controller = new AbortController();
@@ -390,15 +479,42 @@ async function main(): Promise<void> {
   const handlers = buildHandlers(secureKeyBackend);
 
   const rpcLog = getLogger("rpc");
+  const rpcLogger = {
+    log: (msg: string, ...args: unknown[]) => rpcLog.info({ args }, msg),
+    warn: (msg: string, ...args: unknown[]) => rpcLog.warn({ args }, msg),
+    error: (msg: string, ...args: unknown[]) => rpcLog.error({ args }, msg),
+  };
+
+  if (standalone) {
+    // Serve over a Unix socket and run until a shutdown signal — no stdio
+    // parent to anchor the lifecycle.
+    serveStandaloneSocket({
+      socketPath: getLocalSocketPath(),
+      handlers,
+      signal: controller.signal,
+      logger: rpcLogger,
+      log,
+    });
+    await new Promise<void>((resolve) => {
+      if (controller.signal.aborted) {
+        resolve();
+        return;
+      }
+      controller.signal.addEventListener("abort", () => resolve(), {
+        once: true,
+      });
+    });
+    log.info("Server stopped.");
+    return;
+  }
+
+  // Default: serve the spawning assistant over stdio. stdin closing (parent
+  // exit) or SIGTERM shuts CES down.
   const server = new CesRpcServer({
     input: process.stdin,
     output: process.stdout,
     handlers,
-    logger: {
-      log: (msg: string, ...args: unknown[]) => rpcLog.info({ args }, msg),
-      warn: (msg: string, ...args: unknown[]) => rpcLog.warn({ args }, msg),
-      error: (msg: string, ...args: unknown[]) => rpcLog.error({ args }, msg),
-    },
+    logger: rpcLogger,
     signal: controller.signal,
     // Local mode reads API keys from env/store directly — no-op handler so
     // update_managed_credential is still registered and returns success.

package/src/paths.ts

@@ -140,6 +140,33 @@ export function getBootstrapSocketPath(): string {
   );
 }
 
+// ---------------------------------------------------------------------------
+// Local-mode standalone socket (temporary — CES_STANDALONE)
+// ---------------------------------------------------------------------------
+
+/** Default local-mode CES socket filename (under the local data root). */
+const LOCAL_SOCKET_NAME = "ces.sock";
+
+/**
+ * Return the path to the local-mode CES Unix socket.
+ *
+ * Used when local CES runs as a standalone sibling (`CES_STANDALONE=1`, the
+ * CLI-launched opt-in) rather than as the assistant's stdio
+ * child. The socket lives under the CES-private local data root, whose
+ * directory permissions are the access boundary.
+ *
+ * Priority:
+ * 1. `CES_LOCAL_SOCKET` env var (full file path override; the CLI sets this
+ *    when launching the sibling).
+ * 2. Default: `<localDataRoot>/ces.sock`.
+ */
+export function getLocalSocketPath(): string {
+  return (
+    process.env["CES_LOCAL_SOCKET"] ??
+    join(getCesDataRoot("local"), LOCAL_SOCKET_NAME)
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Health port (managed mode only)
 // ---------------------------------------------------------------------------