@vellumai/assistant 0.4.35 → 0.4.37

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

@@ -47,7 +47,7 @@ export function handleListInvites(url: URL): Response {
 export async function handleCreateInvite(req: Request): Promise<Response> {
   const body = (await req.json()) as Record<string, unknown>;
 
-  const result = createIngressInvite({
+  const result = await createIngressInvite({
     sourceChannel: body.sourceChannel as string | undefined,
     note: body.note as string | undefined,
     maxUses: body.maxUses as number | undefined,

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

@@ -4,7 +4,11 @@ import {
   invalidateConfigCache,
 } from "../../config/loader.js";
 import { initializeProviders } from "../../providers/registry.js";
-import { deleteSecureKey, setSecureKey } from "../../security/secure-keys.js";
+import {
+  deleteSecureKeyAsync,
+  getSecureKeyAsync,
+  setSecureKeyAsync,
+} from "../../security/secure-keys.js";
 import {
   assertMetadataWritable,
   deleteCredentialMetadata,
@@ -48,7 +52,7 @@ export async function handleAddSecret(req: Request): Promise<Response> {
           400,
         );
       }
-      const stored = setSecureKey(name, value);
+      const stored = await setSecureKeyAsync(name, value);
       if (!stored) {
         return httpError(
           "INTERNAL_ERROR",
@@ -75,7 +79,7 @@ export async function handleAddSecret(req: Request): Promise<Response> {
       const service = name.slice(0, colonIdx);
       const field = name.slice(colonIdx + 1);
       const key = `credential:${service}:${field}`;
-      const stored = setSecureKey(key, value);
+      const stored = await setSecureKeyAsync(key, value);
       if (!stored) {
         return httpError(
           "INTERNAL_ERROR",
@@ -128,10 +132,20 @@ export async function handleDeleteSecret(req: Request): Promise<Response> {
           400,
         );
       }
-      const deleted = deleteSecureKey(name);
-      if (!deleted) {
+      // Check existence first — the broker always returns "deleted" even
+      // for keys that don't exist, so we need a pre-check for 404 semantics.
+      const existing = await getSecureKeyAsync(name);
+      if (existing === undefined) {
         return httpError("NOT_FOUND", `API key not found: ${name}`, 404);
       }
+      const deleteResult = await deleteSecureKeyAsync(name);
+      if (deleteResult === "error") {
+        return httpError(
+          "INTERNAL_ERROR",
+          `Failed to delete API key from secure storage: ${name}`,
+          500,
+        );
+      }
       invalidateConfigCache();
       initializeProviders(getConfig());
       log.info({ provider: name }, "API key deleted via HTTP");
@@ -151,10 +165,20 @@ export async function handleDeleteSecret(req: Request): Promise<Response> {
       const field = name.slice(colonIdx + 1);
       assertMetadataWritable();
       const key = `credential:${service}:${field}`;
-      const deleted = deleteSecureKey(key);
-      if (!deleted) {
+      // Check existence first — the broker always returns "deleted" even
+      // for keys that don't exist, so we need a pre-check for 404 semantics.
+      const existing = await getSecureKeyAsync(key);
+      if (existing === undefined) {
         return httpError("NOT_FOUND", `Credential not found: ${name}`, 404);
       }
+      const deleteResult = await deleteSecureKeyAsync(key);
+      if (deleteResult === "error") {
+        return httpError(
+          "INTERNAL_ERROR",
+          `Failed to delete credential from secure storage: ${name}`,
+          500,
+        );
+      }
       deleteCredentialMetadata(service, field);
       log.info({ service, field }, "Credential deleted via HTTP");
       return Response.json({ success: true, type, name });

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

@@ -148,6 +148,9 @@ function pruneAssistantPhoneNumbers(
  */
 export function handleGetTwilioConfig(): Response {
   const hasCredentials = hasTwilioCredentials();
+  const accountSid = hasCredentials
+    ? getSecureKey("credential:twilio:account_sid")
+    : undefined;
   const raw = loadRawConfig();
   const sms = (raw?.sms ?? {}) as Record<string, unknown>;
   const phoneNumber = (sms.phoneNumber as string) ?? "";
@@ -155,6 +158,7 @@ export function handleGetTwilioConfig(): Response {
   return Response.json({
     success: true,
     hasCredentials,
+    accountSid: accountSid || undefined,
     phoneNumber: phoneNumber || undefined,
   });
 }
@@ -235,7 +239,34 @@ export async function handleSetTwilioCredentials(
     });
   }
 
-  upsertCredentialMetadata("twilio", "account_sid", {});
+  upsertCredentialMetadata("twilio", "account_sid", {
+    injectionTemplates: [
+      {
+        hostPattern: "api.twilio.com",
+        injectionType: "header" as const,
+        headerName: "Authorization",
+        valuePrefix: "Basic ",
+        valueTransform: "base64" as const,
+        composeWith: {
+          service: "twilio",
+          field: "auth_token",
+          separator: ":",
+        },
+      },
+      {
+        hostPattern: "messaging.twilio.com",
+        injectionType: "header" as const,
+        headerName: "Authorization",
+        valuePrefix: "Basic ",
+        valueTransform: "base64" as const,
+        composeWith: {
+          service: "twilio",
+          field: "auth_token",
+          separator: ":",
+        },
+      },
+    ],
+  });
   upsertCredentialMetadata("twilio", "auth_token", {});
 
   return Response.json({ success: true, hasCredentials: true });

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

@@ -0,0 +1,114 @@
+/**
+ * Route handlers for usage and cost summary endpoints.
+ *
+ * GET /v1/usage/totals?from=&to=              — aggregate totals for a time range
+ * GET /v1/usage/daily?from=&to=               — per-day buckets for a time range
+ * GET /v1/usage/breakdown?from=&to=&groupBy=  — grouped breakdown (actor, provider, model)
+ */
+
+import {
+  getUsageDayBuckets,
+  getUsageGroupBreakdown,
+  getUsageTotals,
+} from "../../memory/llm-usage-store.js";
+import { httpError } from "../http-errors.js";
+import type { RouteDefinition } from "../http-router.js";
+
+const VALID_GROUP_BY = new Set(["actor", "provider", "model"]);
+
+/**
+ * Parse and validate the `from` and `to` epoch-millis query parameters.
+ * Returns the parsed range or an error Response.
+ */
+function parseTimeRange(url: URL): { from: number; to: number } | Response {
+  const fromRaw = url.searchParams.get("from");
+  const toRaw = url.searchParams.get("to");
+
+  if (!fromRaw || !toRaw) {
+    return httpError(
+      "BAD_REQUEST",
+      'Missing required query parameters: "from" and "to" (epoch milliseconds)',
+      400,
+    );
+  }
+
+  const from = Number(fromRaw);
+  const to = Number(toRaw);
+
+  if (!Number.isFinite(from) || !Number.isFinite(to)) {
+    return httpError(
+      "BAD_REQUEST",
+      '"from" and "to" must be valid numbers (epoch milliseconds)',
+      400,
+    );
+  }
+
+  if (from > to) {
+    return httpError(
+      "BAD_REQUEST",
+      '"from" must be less than or equal to "to"',
+      400,
+    );
+  }
+
+  return { from, to };
+}
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export function usageRouteDefinitions(): RouteDefinition[] {
+  return [
+    {
+      endpoint: "usage/totals",
+      method: "GET",
+      handler: ({ url }) => {
+        const range = parseTimeRange(url);
+        if (range instanceof Response) return range;
+        const totals = getUsageTotals(range);
+        return Response.json(totals);
+      },
+    },
+    {
+      endpoint: "usage/daily",
+      method: "GET",
+      handler: ({ url }) => {
+        const range = parseTimeRange(url);
+        if (range instanceof Response) return range;
+        const buckets = getUsageDayBuckets(range);
+        return Response.json({ buckets });
+      },
+    },
+    {
+      endpoint: "usage/breakdown",
+      method: "GET",
+      handler: ({ url }) => {
+        const range = parseTimeRange(url);
+        if (range instanceof Response) return range;
+
+        const groupBy = url.searchParams.get("groupBy");
+        if (!groupBy) {
+          return httpError(
+            "BAD_REQUEST",
+            'Missing required query parameter: "groupBy" (one of: actor, provider, model)',
+            400,
+          );
+        }
+        if (!VALID_GROUP_BY.has(groupBy)) {
+          return httpError(
+            "BAD_REQUEST",
+            `Invalid "groupBy" value: "${groupBy}". Must be one of: actor, provider, model`,
+            400,
+          );
+        }
+
+        const breakdown = getUsageGroupBreakdown(
+          range,
+          groupBy as "actor" | "provider" | "model",
+        );
+        return Response.json({ breakdown });
+      },
+    },
+  ];
+}

package/src/runtime/tool-grant-request-helper.ts

@@ -18,6 +18,7 @@ import {
   listCanonicalGuardianRequests,
 } from "../memory/canonical-guardian-store.js";
 import { emitNotificationSignal } from "../notifications/emit-signal.js";
+import type { NotificationSourceChannel } from "../notifications/signal.js";
 import { getLogger } from "../util/logger.js";
 import { getGuardianBinding } from "./channel-guardian-service.js";
 import { GUARDIAN_APPROVAL_TTL_MS } from "./routes/channel-route-shared.js";
@@ -144,7 +145,7 @@ export function createOrReuseToolGrantRequest(
   // pipeline is preserved.
   const signalPromise = emitNotificationSignal({
     sourceEventName: "guardian.question",
-    sourceChannel,
+    sourceChannel: sourceChannel as NotificationSourceChannel,
     sourceSessionId: conversationId,
     attentionHints: {
       requiresAction: true,

package/src/security/encrypted-store.ts

@@ -251,22 +251,26 @@ export function setKey(account: string, value: string): boolean {
   }
 }
 
+/** Result of a delete operation — distinguishes success, not-found, and error. */
+export type DeleteKeyResult = "deleted" | "not-found" | "error";
+
 /**
  * Delete a secret from the encrypted store.
- * Returns true on success, false if not found or on failure.
+ * Returns `"deleted"` on success, `"not-found"` if the key doesn't exist,
+ * or `"error"` on failure.
  */
-export function deleteKey(account: string): boolean {
+export function deleteKey(account: string): DeleteKeyResult {
   try {
     const store = readStore();
     if (!store || !Object.prototype.hasOwnProperty.call(store.entries, account))
-      return false;
+      return "not-found";
 
     delete store.entries[account];
     writeStore(store);
-    return true;
+    return "deleted";
   } catch (err) {
     log.debug({ err, account }, "Failed to delete from encrypted store");
-    return false;
+    return "error";
   }
 }
 

package/src/security/keychain-broker-client.ts

@@ -0,0 +1,393 @@
+/**
+ * TypeScript client for the keychain broker Unix domain socket protocol.
+ *
+ * The keychain broker runs inside the macOS app and exposes SecItem*
+ * operations over a newline-delimited JSON protocol on a UDS. This client
+ * provides a graceful-fallback interface: every public method returns a
+ * safe default on failure and never throws.
+ *
+ * Socket path: read from VELLUM_KEYCHAIN_BROKER_SOCKET env var.
+ * Auth token: read from ~/.vellum/protected/keychain-broker.token on first
+ * connection, cached for process lifetime.
+ */
+
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import type { Socket } from "node:net";
+import { createConnection } from "node:net";
+import { join } from "node:path";
+
+import { pathExists } from "../util/fs.js";
+import { getLogger } from "../util/logger.js";
+import { getRootDir } from "../util/platform.js";
+
+const log = getLogger("keychain-broker-client");
+
+const REQUEST_TIMEOUT_MS = 5_000;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Result of a `get()` call. `null` means broker error (caller should fall
+ *  back); `{ found: false }` means the key doesn't exist in the keychain. */
+export type BrokerGetResult = { found: boolean; value?: string } | null;
+
+export interface KeychainBrokerClient {
+  isAvailable(): boolean;
+  ping(): Promise<{ pong: boolean } | null>;
+  get(account: string): Promise<BrokerGetResult>;
+  set(account: string, value: string): Promise<boolean>;
+  del(account: string): Promise<boolean>;
+  list(): Promise<string[]>;
+}
+
+interface BrokerRequest {
+  v: number;
+  id: string;
+  method: string;
+  token: string;
+  params?: Record<string, unknown>;
+}
+
+interface BrokerResponse {
+  id: string;
+  ok: boolean;
+  result?: Record<string, unknown>;
+  error?: { code: string; message: string };
+}
+
+interface PendingRequest {
+  resolve: (response: BrokerResponse) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal state
+// ---------------------------------------------------------------------------
+
+function getTokenPath(): string {
+  return join(getRootDir(), "protected", "keychain-broker.token");
+}
+
+function getSocketPath(): string | undefined {
+  return process.env.VELLUM_KEYCHAIN_BROKER_SOCKET;
+}
+
+// ---------------------------------------------------------------------------
+// Client implementation
+// ---------------------------------------------------------------------------
+
+export function createBrokerClient(): KeychainBrokerClient {
+  let socket: Socket | null = null;
+  /** Promise that resolves when the in-flight connect() completes. */
+  let connectPromise: Promise<Socket> | null = null;
+  let permanentlyUnavailable = false;
+  /** Cached token string, or undefined if not yet successfully read. */
+  let cachedToken: string | undefined;
+  let hasTriedReconnect = false;
+
+  /** Buffer for incoming data — responses are newline-delimited JSON. */
+  let inBuffer = "";
+
+  const pending = new Map<string, PendingRequest>();
+
+  // -------------------------------------------------------------------------
+  // Token management
+  // -------------------------------------------------------------------------
+
+  function readToken(): string | null {
+    try {
+      const tokenPath = getTokenPath();
+      if (!pathExists(tokenPath)) return null;
+      return readFileSync(tokenPath, "utf-8").trim();
+    } catch {
+      return null;
+    }
+  }
+
+  function getToken(): string | null {
+    if (cachedToken !== undefined) return cachedToken;
+    const token = readToken();
+    // Only cache non-null results so we re-attempt on next call if the
+    // token file hasn't appeared yet (startup race).
+    if (token) cachedToken = token;
+    return token;
+  }
+
+  /** Re-read the token from disk (handles app restart with new token). */
+  function refreshToken(): string | null {
+    const token = readToken();
+    // Update the cache: set to the new value if found, clear if not so
+    // subsequent getToken() calls will re-read from disk.
+    cachedToken = token ?? undefined;
+    return token;
+  }
+
+  // -------------------------------------------------------------------------
+  // Socket lifecycle
+  // -------------------------------------------------------------------------
+
+  function handleData(chunk: Buffer | string): void {
+    inBuffer += chunk.toString();
+    let newlineIdx: number;
+    while ((newlineIdx = inBuffer.indexOf("\n")) !== -1) {
+      const line = inBuffer.slice(0, newlineIdx).trim();
+      inBuffer = inBuffer.slice(newlineIdx + 1);
+      if (!line) continue;
+
+      try {
+        const response = JSON.parse(line) as BrokerResponse;
+        const entry = pending.get(response.id);
+        if (entry) {
+          clearTimeout(entry.timer);
+          pending.delete(response.id);
+          entry.resolve(response);
+        }
+      } catch {
+        log.warn("Received malformed JSON from keychain broker");
+      }
+    }
+  }
+
+  function cleanupSocket(): void {
+    if (socket) {
+      socket.removeAllListeners();
+      socket.destroy();
+      socket = null;
+    }
+    inBuffer = "";
+    // Reject all pending requests
+    for (const [id, entry] of pending) {
+      clearTimeout(entry.timer);
+      entry.resolve({
+        id,
+        ok: false,
+        error: { code: "DISCONNECTED", message: "disconnected" },
+      });
+    }
+    pending.clear();
+  }
+
+  function connect(): Promise<Socket> {
+    return new Promise((resolve, reject) => {
+      const socketPath = getSocketPath();
+      if (!socketPath) {
+        reject(new Error("No socket path"));
+        return;
+      }
+
+      const sock = createConnection({ path: socketPath });
+
+      sock.on("connect", () => {
+        socket = sock;
+        hasTriedReconnect = false;
+        resolve(sock);
+      });
+
+      sock.on("error", (err) => {
+        log.warn({ err }, "Keychain broker socket error");
+        cleanupSocket();
+        reject(err);
+      });
+
+      sock.on("close", () => {
+        cleanupSocket();
+      });
+
+      sock.on("data", handleData);
+    });
+  }
+
+  async function ensureConnected(): Promise<Socket | null> {
+    if (permanentlyUnavailable) return null;
+    if (socket && !socket.destroyed) return socket;
+
+    // If a connect() is already in flight, wait for it instead of returning
+    // null — this prevents concurrent callers from silently failing.
+    if (connectPromise) {
+      try {
+        return await connectPromise;
+      } catch {
+        return null;
+      }
+    }
+
+    connectPromise = connect();
+    try {
+      const sock = await connectPromise;
+      return sock;
+    } catch {
+      // First connection failed — try once more
+      if (!hasTriedReconnect) {
+        hasTriedReconnect = true;
+        connectPromise = connect();
+        try {
+          return await connectPromise;
+        } catch {
+          // Reconnect also failed — mark unavailable
+          log.warn(
+            "Keychain broker reconnect failed, marking unavailable for this process",
+          );
+          permanentlyUnavailable = true;
+          return null;
+        } finally {
+          connectPromise = null;
+        }
+      }
+      permanentlyUnavailable = true;
+      return null;
+    } finally {
+      connectPromise = null;
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Request / response
+  // -------------------------------------------------------------------------
+
+  function sendRequest(request: BrokerRequest): Promise<BrokerResponse> {
+    return new Promise((resolve) => {
+      if (!socket || socket.destroyed) {
+        resolve({
+          id: request.id,
+          ok: false,
+          error: { code: "NOT_CONNECTED", message: "not connected" },
+        });
+        return;
+      }
+
+      const timer = setTimeout(() => {
+        pending.delete(request.id);
+        resolve({
+          id: request.id,
+          ok: false,
+          error: { code: "TIMEOUT", message: "timeout" },
+        });
+      }, REQUEST_TIMEOUT_MS);
+
+      pending.set(request.id, { resolve, timer });
+
+      const data = JSON.stringify(request) + "\n";
+      socket.write(data, (err) => {
+        if (err) {
+          clearTimeout(timer);
+          pending.delete(request.id);
+          resolve({
+            id: request.id,
+            ok: false,
+            error: { code: "WRITE_ERROR", message: "write error" },
+          });
+        }
+      });
+    });
+  }
+
+  async function doRequest(
+    method: string,
+    params: Record<string, unknown> = {},
+  ): Promise<BrokerResponse | null> {
+    const sock = await ensureConnected();
+    if (!sock) return null;
+
+    const token = getToken();
+    if (!token) return null;
+
+    const id = randomUUID();
+    const request: BrokerRequest = {
+      v: 1,
+      id,
+      method,
+      token,
+      ...(Object.keys(params).length > 0 ? { params } : {}),
+    };
+    const response = await sendRequest(request);
+
+    // On UNAUTHORIZED, re-read the token once and retry. This handles
+    // the case where the app restarted with a new token while the daemon
+    // is still running with the old cached one.
+    if (response.error?.code === "UNAUTHORIZED") {
+      const newToken = refreshToken();
+      if (!newToken || newToken === request.token) return response;
+
+      const retryRequest: BrokerRequest = {
+        ...request,
+        id: randomUUID(),
+        token: newToken,
+      };
+      return await sendRequest(retryRequest);
+    }
+
+    return response;
+  }
+
+  // -------------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------------
+
+  return {
+    isAvailable(): boolean {
+      if (permanentlyUnavailable) return false;
+      const socketPath = getSocketPath();
+      if (!socketPath) return false;
+      return pathExists(getTokenPath());
+    },
+
+    async ping(): Promise<{ pong: boolean } | null> {
+      try {
+        const response = await doRequest("broker.ping");
+        if (!response || !response.ok) return null;
+        return {
+          pong: !!(response.result as Record<string, unknown> | undefined)
+            ?.pong,
+        };
+      } catch {
+        return null;
+      }
+    },
+
+    async get(account: string): Promise<BrokerGetResult> {
+      try {
+        const response = await doRequest("key.get", { account });
+        if (!response) return null;
+        if (!response.ok) return null;
+        const result = response.result as
+          | { found?: boolean; value?: string }
+          | undefined;
+        if (!result) return null;
+        return { found: !!result.found, value: result.value };
+      } catch {
+        return null;
+      }
+    },
+
+    async set(account: string, value: string): Promise<boolean> {
+      try {
+        const response = await doRequest("key.set", { account, value });
+        return response?.ok === true;
+      } catch {
+        return false;
+      }
+    },
+
+    async del(account: string): Promise<boolean> {
+      try {
+        const response = await doRequest("key.delete", { account });
+        return response?.ok === true;
+      } catch {
+        return false;
+      }
+    },
+
+    async list(): Promise<string[]> {
+      try {
+        const response = await doRequest("key.list");
+        if (!response || !response.ok) return [];
+        const result = response.result as { accounts?: string[] } | undefined;
+        return result?.accounts ?? [];
+      } catch {
+        return [];
+      }
+    },
+  };
+}