@vellumai/assistant 0.5.6 → 0.5.8

package/src/security/secure-keys.ts

@@ -1,15 +1,17 @@
 /**
- * Unified secure key storage — single-writer routing through CredentialBackend
+ * Unified secure key storage — single-backend routing through CredentialBackend
  * adapters.
  *
- * Backend selection (`resolveBackend`) is the single decision point:
- *   - Containerized (IS_CONTAINERIZED + CES_CREDENTIAL_URL set): CES HTTP client.
- *   - Production (VELLUM_DEV unset or "0"): keychain backend when available.
- *   - Dev mode (VELLUM_DEV=1): encrypted file store always.
+ * Backend selection (`resolveBackendAsync`) is the single async decision point:
+ *   1. CES RPC (primary) — injected via `setCesClient()`: delegates credential
+ *      operations to the CES process over stdio RPC. This is the default path
+ *      for all local modes (desktop app, dev, CLI).
+ *   2. CES HTTP — containerized mode (IS_CONTAINERIZED + CES_CREDENTIAL_URL):
+ *      delegates to the CES sidecar over HTTP. Used in Docker/managed mode.
+ *   3. Encrypted file store (fallback) — used when CES is unavailable.
  *
- * Writes go to exactly one backend (no dual-writing). Reads in keychain mode
- * fall back to the encrypted store for keys that haven't been migrated yet.
- * Deletes clean up both stores regardless of mode.
+ * All operations (reads, writes, lists, deletes) go to exactly one backend.
+ * There are no cross-backend fallbacks or merges.
  */
 
 import type {
@@ -19,15 +21,21 @@ import type {
 
 import providerEnvVarsRegistry from "../../../meta/provider-env-vars.json" with { type: "json" };
 import { getIsContainerized } from "../config/env-registry.js";
+import type { CesClient } from "../credential-execution/client.js";
 import { getLogger } from "../util/logger.js";
 import { createCesCredentialBackend } from "./ces-credential-client.js";
-import type { CredentialBackend, DeleteResult } from "./credential-backend.js";
-import {
-  createEncryptedStoreBackend,
-  createKeychainBackend,
+import { CesRpcCredentialBackend } from "./ces-rpc-credential-backend.js";
+import type {
+  CredentialBackend,
+  CredentialListResult,
+  DeleteResult,
 } from "./credential-backend.js";
+import { createEncryptedStoreBackend } from "./credential-backend.js";
 
-export type { DeleteResult } from "./credential-backend.js";
+export type {
+  CredentialListResult,
+  DeleteResult,
+} from "./credential-backend.js";
 
 /**
  * Re-export shared-package secure-key abstractions so downstream consumers
@@ -36,15 +44,24 @@ export type { DeleteResult } from "./credential-backend.js";
  */
 export type { SecureKeyBackend, SecureKeyDeleteResult };
 
+export interface SecureKeyResult {
+  value: string | undefined;
+  unreachable: boolean;
+}
+
 const log = getLogger("secure-keys");
 
-let _keychain: CredentialBackend | undefined;
+let _cesClient: CesClient | undefined;
 let _encryptedStore: CredentialBackend | undefined;
 let _resolvedBackend: CredentialBackend | undefined;
+let _resolvePromise: Promise<CredentialBackend> | undefined;
 
-function getKeychainBackend(): CredentialBackend {
-  if (!_keychain) _keychain = createKeychainBackend();
-  return _keychain;
+/** Inject a CES RPC client for credential routing. Resets the resolved backend. */
+export function setCesClient(client: CesClient | undefined): void {
+  _cesClient = client;
+  // Reset resolved backend so next call picks up CES
+  _resolvedBackend = undefined;
+  _resolvePromise = undefined;
 }
 
 function getEncryptedStoreBackend(): CredentialBackend {
@@ -53,101 +70,98 @@ function getEncryptedStoreBackend(): CredentialBackend {
 }
 
 /**
- * Resolve the primary credential backend for this process.
+ * Resolve the primary credential backend for this process (async).
  *
  * Priority:
- *   1. Containerized + CES_CREDENTIAL_URL → CES HTTP client (skip keychain
- *      and encrypted store entirely — the sidecar owns credential storage).
- *   2. Production (VELLUM_DEV unset or "0") → keychain when available.
- *   3. Dev mode (VELLUM_DEV=1) → encrypted file store always.
+ *   1. CES RPC client → primary path for all local modes.
+ *   2. Containerized + CES_CREDENTIAL_URL → CES HTTP client (Docker/managed).
+ *   3. Encrypted file store → fallback when CES is unavailable.
  *
  * Once resolved, the backend does not change during the process lifetime.
  * Call `_resetBackend()` in tests to clear the cached resolution.
  */
-function resolveBackend(): CredentialBackend {
-  if (!_resolvedBackend) {
-    if (getIsContainerized() && process.env.CES_CREDENTIAL_URL) {
-      const ces = createCesCredentialBackend();
-      if (ces.isAvailable()) {
-        _resolvedBackend = ces;
-      } else {
-        log.warn(
-          "CES_CREDENTIAL_URL is set but CES backend is not available — " +
-            "falling back to local credential store",
-        );
-      }
+async function resolveBackendAsync(): Promise<CredentialBackend> {
+  if (_resolvedBackend) return _resolvedBackend;
+  if (!_resolvePromise) {
+    _resolvePromise = doResolveBackend();
+  }
+  return _resolvePromise;
+}
+
+async function doResolveBackend(): Promise<CredentialBackend> {
+  // 1. CES RPC — primary credential backend for all local modes
+  if (_cesClient) {
+    const cesRpc = new CesRpcCredentialBackend(_cesClient);
+    if (cesRpc.isAvailable()) {
+      _resolvedBackend = cesRpc;
+      return cesRpc;
     }
+    log.warn(
+      "CES RPC client is set but not ready — falling back to local credential store",
+    );
+  }
 
-    if (!_resolvedBackend) {
-      if (
-        process.env.VELLUM_DEV !== "1" &&
-        getKeychainBackend().isAvailable()
-      ) {
-        _resolvedBackend = getKeychainBackend();
-      } else {
-        _resolvedBackend = getEncryptedStoreBackend();
-      }
+  // 2. CES HTTP — containerized / Docker / managed mode
+  if (getIsContainerized() && process.env.CES_CREDENTIAL_URL) {
+    const ces = createCesCredentialBackend();
+    if (ces.isAvailable()) {
+      _resolvedBackend = ces;
+      return ces;
     }
+    log.warn(
+      "CES_CREDENTIAL_URL is set but CES backend is not available — " +
+        "falling back to local credential store",
+    );
   }
+
+  // 3. Encrypted file store — fallback when CES is unavailable
+  _resolvedBackend = getEncryptedStoreBackend();
   return _resolvedBackend;
 }
 
 /**
- * List all account names across both backends (async).
+ * List all account names from the resolved backend (async).
  *
- * In CES mode, only the CES backend is queried — there are no local stores.
- *
- * When the primary backend is the keychain, this merges keys from the keychain
- * and the encrypted store (for legacy keys that haven't been migrated). The
- * result is deduplicated. When the primary backend is already the encrypted
- * store, only that store is queried.
+ * Queries exactly one backend — no cross-store merge.
  */
-export async function listSecureKeysAsync(): Promise<string[]> {
-  const backend = resolveBackend();
-  const primaryKeys = await backend.list();
-
-  // CES mode — the sidecar is the single source of truth, no local merge.
-  if (backend.name === "ces-http") return primaryKeys;
-
-  // If primary backend is NOT the encrypted store, also check
-  // the encrypted store for legacy keys that haven't been migrated.
-  if (backend !== getEncryptedStoreBackend()) {
-    const encKeys = await getEncryptedStoreBackend().list();
-    const merged = new Set([...primaryKeys, ...encKeys]);
-    return Array.from(merged);
-  }
-
-  return primaryKeys;
+export async function listSecureKeysAsync(): Promise<CredentialListResult> {
+  const backend = await resolveBackendAsync();
+  return backend.list();
 }
 
 // ---------------------------------------------------------------------------
-// Async CRUD — single-writer routing
+// Async CRUD — single-backend routing
 // ---------------------------------------------------------------------------
 
 /**
- * Retrieve a secret from secure storage. Reads from the primary backend
- * first. In CES mode, the sidecar is the single source of truth — no
- * local fallback. In local mode, if the primary backend is the keychain,
- * falls back to the encrypted store for legacy keys that haven't been
- * migrated.
+ * Retrieve a secret from secure storage with richer result metadata.
+ *
+ * Returns both the value (if found) and whether the backend was
+ * unreachable. Callers that need to distinguish "not found" from
+ * "backend down" should use this instead of `getSecureKeyAsync`.
+ *
+ * Reads from exactly one backend — no cross-store fallback.
  */
-export async function getSecureKeyAsync(
+export async function getSecureKeyResultAsync(
   account: string,
-): Promise<string | undefined> {
-  const backend = resolveBackend();
+): Promise<SecureKeyResult> {
+  const backend = await resolveBackendAsync();
   const result = await backend.get(account);
-  if (result != null) return result;
-
-  // CES mode — no local fallback.
-  if (backend.name === "ces-http") return undefined;
-
-  // Legacy fallback: if primary backend is NOT the encrypted store,
-  // check the encrypted store for keys that haven't been migrated.
-  if (backend !== getEncryptedStoreBackend()) {
-    return await getEncryptedStoreBackend().get(account);
+  if (result.value != null) {
+    return { value: result.value, unreachable: false };
   }
+  return { value: undefined, unreachable: result.unreachable };
+}
 
-  return undefined;
+/**
+ * Retrieve a secret from secure storage. Convenience wrapper over
+ * `getSecureKeyResultAsync` that returns only the value.
+ */
+export async function getSecureKeyAsync(
+  account: string,
+): Promise<string | undefined> {
+  const result = await getSecureKeyResultAsync(account);
+  return result.value;
 }
 
 /**
@@ -158,7 +172,7 @@ export async function setSecureKeyAsync(
   account: string,
   value: string,
 ): Promise<boolean> {
-  const backend = resolveBackend();
+  const backend = await resolveBackendAsync();
   const ok = await backend.set(account, value);
   if (!ok) {
     log.warn(
@@ -172,38 +186,13 @@ export async function setSecureKeyAsync(
 /**
  * Delete a secret from secure storage.
  *
- * In containerized mode with CES, deletion is routed exclusively through the
- * CES backend — there are no local stores to clean up.
- *
- * In local mode, always attempts deletion on both the keychain backend (if
- * available) and the encrypted store backend, regardless of routing mode.
- * This cleans up legacy data from both stores.
+ * Deletes from exactly one backend — no cross-store cleanup.
  */
 export async function deleteSecureKeyAsync(
   account: string,
 ): Promise<DeleteResult> {
-  const backend = resolveBackend();
-
-  // In CES mode, the sidecar is the only store — no local cleanup needed.
-  if (backend.name === "ces-http") {
-    return backend.delete(account);
-  }
-
-  const keychain = getKeychainBackend();
-  const enc = getEncryptedStoreBackend();
-
-  let keychainResult: DeleteResult = "not-found";
-  if (keychain.isAvailable()) {
-    keychainResult = await keychain.delete(account);
-  }
-
-  const encResult = await enc.delete(account);
-
-  // Return "error" if either errored
-  if (keychainResult === "error" || encResult === "error") return "error";
-  // Return "deleted" if either deleted
-  if (keychainResult === "deleted" || encResult === "deleted") return "deleted";
-  return "not-found";
+  const backend = await resolveBackendAsync();
+  return backend.delete(account);
 }
 
 // ---------------------------------------------------------------------------
@@ -261,9 +250,18 @@ export async function getMaskedProviderKey(
 // Test helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Return the name of the currently resolved credential backend.
+ * Useful for diagnostic messages when credential operations fail.
+ */
+export function getActiveBackendName(): string {
+  return _resolvedBackend?.name ?? "none";
+}
+
 /** @internal Test-only: reset the cached backends so they're re-created. */
 export function _resetBackend(): void {
-  _keychain = undefined;
+  _cesClient = undefined;
   _encryptedStore = undefined;
   _resolvedBackend = undefined;
+  _resolvePromise = undefined;
 }

package/src/skills/catalog-install.ts

@@ -13,12 +13,9 @@ import { homedir } from "node:os";
 import { dirname, join, posix, resolve, sep } from "node:path";
 import { gunzipSync } from "node:zlib";
 
+import { getPlatformBaseUrl } from "../config/env.js";
 import { getLogger } from "../util/logger.js";
-import {
-  getWorkspaceConfigPath,
-  getWorkspaceSkillsDir,
-  readPlatformToken,
-} from "../util/platform.js";
+import { getWorkspaceSkillsDir, readPlatformToken } from "../util/platform.js";
 import { deleteSkillCapabilityMemory } from "./skill-memory.js";
 
 const log = getLogger("catalog-install");
@@ -70,31 +67,6 @@ export function getRepoSkillsDir(): string | undefined {
 
 // ─── Platform API ────────────────────────────────────────────────────────────
 
-function getConfigPlatformUrl(): string | undefined {
-  try {
-    const configPath = getWorkspaceConfigPath();
-    if (!existsSync(configPath)) return undefined;
-    const raw = JSON.parse(readFileSync(configPath, "utf-8")) as Record<
-      string,
-      unknown
-    >;
-    const platform = raw.platform as Record<string, unknown> | undefined;
-    const baseUrl = platform?.baseUrl;
-    if (typeof baseUrl === "string" && baseUrl.trim()) return baseUrl.trim();
-  } catch {
-    // ignore
-  }
-  return undefined;
-}
-
-function getPlatformUrl(): string {
-  return (
-    process.env.VELLUM_PLATFORM_URL ??
-    getConfigPlatformUrl() ??
-    "https://platform.vellum.ai"
-  );
-}
-
 function buildHeaders(): Record<string, string> {
   const headers: Record<string, string> = {};
   const token = readPlatformToken();
@@ -107,7 +79,8 @@ function buildHeaders(): Record<string, string> {
 // ─── Catalog operations ──────────────────────────────────────────────────────
 
 export async function fetchCatalog(): Promise<CatalogSkill[]> {
-  const url = `${getPlatformUrl()}/v1/skills/`;
+  const platformUrl = getPlatformBaseUrl();
+  const url = `${platformUrl}/v1/skills/`;
   const response = await fetch(url, {
     headers: buildHeaders(),
     signal: AbortSignal.timeout(10000),
@@ -214,7 +187,8 @@ export async function fetchAndExtractSkill(
   skillId: string,
   destDir: string,
 ): Promise<void> {
-  const url = `${getPlatformUrl()}/v1/skills/${encodeURIComponent(skillId)}/`;
+  const platformUrl = getPlatformBaseUrl();
+  const url = `${platformUrl}/v1/skills/${encodeURIComponent(skillId)}/`;
   const response = await fetch(url, {
     headers: buildHeaders(),
     signal: AbortSignal.timeout(15000),

package/src/skills/skill-memory.ts

@@ -123,6 +123,7 @@ export function upsertSkillCapabilityMemory(
         confidence,
         importance,
         fingerprint,
+        sourceType: "extraction",
         scopeId,
         firstSeenAt: now,
         lastSeenAt: now,

package/src/subagent/manager.ts

@@ -18,7 +18,7 @@ import {
 import type { ServerMessage } from "../daemon/message-protocol.js";
 import { bootstrapConversation } from "../memory/conversation-bootstrap.js";
 import { RateLimitProvider } from "../providers/ratelimit.js";
-import { getFailoverProvider } from "../providers/registry.js";
+import { getProvider } from "../providers/registry.js";
 import { getLogger } from "../util/logger.js";
 import { getSandboxWorkingDir } from "../util/platform.js";
 import {
@@ -129,10 +129,7 @@ export class SubagentManager {
 
     // ── Build conversation dependencies ─────────────────────────────
     const appConfig = getConfig();
-    let provider = getFailoverProvider(
-      appConfig.services.inference.provider,
-      appConfig.providerOrder,
-    );
+    let provider = getProvider(appConfig.services.inference.provider);
     const { rateLimit } = appConfig;
     if (rateLimit.maxRequestsPerMinute > 0) {
       provider = new RateLimitProvider(

package/src/telemetry/usage-telemetry-reporter.ts

@@ -140,7 +140,7 @@ export class UsageTelemetryReporter {
 
       // Resolve auth context — skip flush when neither auth mode is viable
       const client = await VellumPlatformClient.create();
-      if (!client && !getTelemetryAppToken()) {
+      if (!client && (!getTelemetryAppToken() || !getTelemetryPlatformUrl())) {
         return;
       }
 
@@ -203,7 +203,9 @@ export class UsageTelemetryReporter {
       if (client) {
         resp = await client.fetch(TELEMETRY_PATH, fetchInit);
       } else {
-        const url = `${getTelemetryPlatformUrl()}${TELEMETRY_PATH}`;
+        const platformUrl = getTelemetryPlatformUrl();
+        if (!platformUrl) return;
+        const url = `${platformUrl}${TELEMETRY_PATH}`;
         resp = await fetch(url, {
           ...fetchInit,
           headers: {

package/src/tools/acp/spawn.ts

@@ -1,7 +1,68 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
 import { getAcpSessionManager } from "../../acp/index.js";
 import { getConfig } from "../../config/loader.js";
+import { getLogger } from "../../util/logger.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
+const execFileAsync = promisify(execFile);
+const log = getLogger("acp:spawn");
+
+/** Cache so we only check once per process lifetime. */
+let adapterVersionChecked = false;
+
+interface AdapterVersionInfo {
+  outdated: true;
+  installed: string;
+  latest: string;
+}
+
+/**
+ * Checks if the globally-installed claude-agent-acp adapter is outdated.
+ * Runs at most once per process lifetime. Does NOT auto-update — returns
+ * version info so the caller can ask the user first.
+ */
+async function checkAdapterVersion(
+  command: string,
+): Promise<AdapterVersionInfo | null> {
+  if (adapterVersionChecked || command !== "claude-agent-acp") {
+    return null;
+  }
+
+  try {
+    const { stdout: installedRaw } = await execFileAsync("npm", [
+      "ls",
+      "-g",
+      "--json",
+      "@zed-industries/claude-agent-acp",
+    ]);
+    const { stdout: latestRaw } = await execFileAsync("npm", [
+      "view",
+      "@zed-industries/claude-agent-acp",
+      "version",
+    ]);
+
+    const installed =
+      JSON.parse(installedRaw)?.dependencies?.[
+        "@zed-industries/claude-agent-acp"
+      ]?.version;
+    const latest = latestRaw.trim();
+
+    adapterVersionChecked = true;
+
+    if (!installed || !latest || installed === latest) {
+      return null;
+    }
+
+    log.info({ installed, latest }, "claude-agent-acp is outdated");
+    return { outdated: true, installed, latest };
+  } catch (err) {
+    log.warn({ err }, "Failed to check claude-agent-acp version");
+    return null;
+  }
+}
+
 export async function executeAcpSpawn(
   input: Record<string, unknown>,
   context: ToolContext,
@@ -37,6 +98,17 @@ export async function executeAcpSpawn(
     };
   }
 
+  // Check if the ACP adapter is outdated before spawning
+  const versionInfo = await checkAdapterVersion(agentConfig.command);
+  if (versionInfo) {
+    return {
+      content:
+        `claude-agent-acp is outdated (installed: ${versionInfo.installed}, latest: ${versionInfo.latest}). ` +
+        `Ask the user if they'd like to update. If yes, run: npm install -g @zed-industries/claude-agent-acp@${versionInfo.latest} — then retry acp_spawn.`,
+      isError: true,
+    };
+  }
+
   try {
     const manager = getAcpSessionManager();
     const cwd = (input.cwd as string) || context.workingDir;
@@ -64,7 +136,12 @@ export async function executeAcpSpawn(
       isError: false,
     };
   } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
+    const msg =
+      err instanceof Error
+        ? err.message
+        : typeof err === "object" && err !== undefined
+          ? JSON.stringify(err)
+          : String(err);
     return { content: `Failed to spawn ACP agent: ${msg}`, isError: true };
   }
 }

package/src/tools/calls/call-start.ts

@@ -46,6 +46,7 @@ export async function executeCallStart(
       | "assistant_number"
       | "user_number"
       | undefined,
+    skipDisclosure: input.skip_disclosure === true,
   });
 
   if (!result.ok) {

package/src/tools/credentials/vault.ts

@@ -400,8 +400,9 @@ class CredentialStoreTool implements Tool {
         const credIdSuffix = metadata
           ? ` (credential_id: ${metadata.credentialId})`
           : "";
+        const retrieveHint = ` Retrieve with: \`assistant credentials reveal --service ${service} --field ${field}\``;
         return {
-          content: `Stored credential for ${service}/${field}.${credIdSuffix}${
+          content: `Stored credential for ${service}/${field}.${credIdSuffix}${retrieveHint}${
             slackChannelResult
               ? formatSlackChannelStatus(slackChannelResult)
               : ""
@@ -428,7 +429,7 @@ class CredentialStoreTool implements Tool {
         // (e.g. keychain) and the encrypted store (legacy keys).
         let secureKeySet: Set<string> | undefined;
         try {
-          secureKeySet = new Set(await listSecureKeysAsync());
+          secureKeySet = new Set((await listSecureKeysAsync()).accounts);
         } catch (err) {
           log.error(
             { err },
@@ -810,8 +811,9 @@ class CredentialStoreTool implements Tool {
         const promptCredIdSuffix = promptMeta
           ? ` (credential_id: ${promptMeta.credentialId})`
           : "";
+        const promptRetrieveHint = ` Retrieve with: \`assistant credentials reveal --service ${service} --field ${field}\``;
         return {
-          content: `Credential stored for ${service}/${field}.${promptCredIdSuffix}${
+          content: `Credential stored for ${service}/${field}.${promptCredIdSuffix}${promptRetrieveHint}${
             slackChannelResult
               ? formatSlackChannelStatus(slackChannelResult)
               : ""

package/src/tools/executor.ts

@@ -183,10 +183,6 @@ export class ToolExecutor {
         );
         // Buffer so the shell's own timeout fires first and handles cleanup
         toolTimeoutMs = (shellTimeoutSec + 5) * 1000;
-      } else if (name === "claude_code") {
-        // Claude Code spawns a subprocess that manages its own turn limits
-        // (maxTurns). Give it a generous timeout so it isn't killed mid-task.
-        toolTimeoutMs = 10 * 60 * 1000; // 10 minutes
       } else {
         const rawTimeoutSec = getConfig().timeouts.toolExecutionTimeoutSec;
         toolTimeoutMs = safeTimeoutMs(rawTimeoutSec);

package/src/tools/memory/definitions.ts

@@ -46,9 +46,10 @@ const memoryManageProperties = {
       "decision",
       "constraint",
       "event",
+      "journal",
     ],
     description:
-      'Category of the memory item (required for save). Use "constraint" for mistakes, gotchas, discoveries, and working solutions - write as advice to your future self.',
+      'Category of the memory item (required for save). Use "constraint" for mistakes, gotchas, discoveries, and working solutions - write as advice to your future self. Use "journal" for journal-style memories — experiential snapshots, upcoming events, things to carry forward.',
   },
   subject: {
     type: "string" as const,
@@ -59,7 +60,7 @@ const memoryManageProperties = {
 export const memoryManageDefinition: ToolDefinition = {
   name: "memory_manage",
   description:
-    "Save, update, or delete memory items. Memory does not survive session restarts - if you want to remember something, save it now. Use 'save' for new information worth remembering (facts, preferences, mistakes, discoveries, gotchas), 'update' to correct existing items, 'delete' to remove outdated items. When a user says 'remember this', save immediately. For user profile or personality changes, update workspace files (USER.md, SOUL.md) instead.",
+    "Save, update, or delete memory items. If you want to remember something, save it now. Use 'save' for new information worth remembering (facts, preferences, mistakes, discoveries, gotchas), 'update' to correct existing items, 'delete' to remove outdated items. When a user says 'remember this', save immediately. Be proactive: if you learn something important that may be useful in the future, always call this tool — don't just say or hope you'll remember it. This is not a substitute for updating workspace files when relevant - do both.",
   input_schema: {
     type: "object",
     properties: memoryManageProperties,