@vellumai/assistant 0.10.7 → 0.10.8-dev.202607102228.5945895

package/src/security/secure-keys.ts

@@ -4,12 +4,17 @@
  *
  * 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 local modes and the managed bootstrap handshake path.
+ *      operations to the CES process over Unix socket RPC. This is the default
+ *      path for the daemon (which calls startCes() at boot) and for non-daemon
+ *      processes that lazily connect via the CES_LOCAL_SOCKET path (see below).
  *   2. CES HTTP — containerized mode (IS_CONTAINERIZED + CES_CREDENTIAL_URL):
  *      delegates to the CES sidecar over HTTP. Used in Docker/managed mode,
  *      including failover when the bootstrap RPC transport dies later.
- *   3. Encrypted file store (fallback) — used when CES is unavailable.
+ *   3. Lazy CES RPC connect — non-daemon processes (workers, CLI subprocesses)
+ *      that inherit CES_LOCAL_SOCKET but never call startCes(). On first
+ *      credential resolution, a direct CES connection is established and
+ *      cached. On failure, falls through to the encrypted file store.
+ *   4. Encrypted file store (fallback) — used when CES is unavailable.
  *
  * All operations (reads, writes, lists, deletes) go to exactly one backend.
  * There are no cross-store fallbacks or merges. The only transport failover is
@@ -27,7 +32,14 @@ import type {
 } from "@vellumai/credential-storage";
 
 import { getIsContainerized } from "../config/env-registry.js";
-import type { CesClient } from "../credential-execution/client.js";
+import {
+  type CesClient,
+  createCesClient,
+} from "../credential-execution/client.js";
+import {
+  CesUnavailableError,
+  createCesProcessManager,
+} from "../credential-execution/process-manager.js";
 import { getAnyProviderEnvVar } from "../providers/provider-env-vars.js";
 import { getLogger } from "../util/logger.js";
 import { getProtectedDir } from "../util/platform.js";
@@ -65,6 +77,17 @@ let _encryptedStore: CredentialBackend | undefined;
 let _resolvedBackend: CredentialBackend | undefined;
 let _resolvePromise: Promise<CredentialBackend> | undefined;
 
+/**
+ * In-flight lazy CES connection promise for non-daemon processes.
+ *
+ * Workers and CLI subprocesses inherit CES_LOCAL_SOCKET but never call
+ * startCes(). When they hit resolveBackendAsync() with no _cesClient and
+ * no _cesReconnect (daemon-only), this promise memoizes a direct CES
+ * connection attempt so concurrent credential reads in the same process
+ * share a single connect+handshake rather than racing.
+ */
+let _lazyConnectPromise: Promise<CesClient | undefined> | undefined;
+
 /**
  * Optional callback that attempts to re-establish a CES connection when
  * the current transport dies. Set by lifecycle.ts after initial CES startup.
@@ -147,7 +170,9 @@ export function setCesReconnect(
 }
 
 function getEncryptedStoreBackend(): CredentialBackend {
-  if (!_encryptedStore) {_encryptedStore = createEncryptedStoreBackend();}
+  if (!_encryptedStore) {
+    _encryptedStore = createEncryptedStoreBackend();
+  }
   return _encryptedStore;
 }
 
@@ -184,7 +209,9 @@ function getEncryptedStoreBackend(): CredentialBackend {
  *
  * Call `_resetBackend()` in tests to clear the cached resolution.
  */
-async function resolveBackendAsync(): Promise<CredentialBackend> {
+async function resolveBackendAsync(
+  options: { forceReconnect?: boolean } = {},
+): Promise<CredentialBackend> {
   if (_resolvedBackend) {
     if (!_resolvedBackend.isAvailable()) {
       const cesHttpFallback = tryFailoverToCesHttpBackend(_resolvedBackend);
@@ -192,8 +219,14 @@ async function resolveBackendAsync(): Promise<CredentialBackend> {
         return cesHttpFallback;
       }
 
-      // Backend is no longer reachable — attempt CES reconnection.
-      const reconnected = await attemptCesReconnection();
+      // Backend is no longer reachable — attempt CES reconnection. Mutating
+      // ops pass `forceReconnect` to bypass the cooldown: writes are rare,
+      // and refusing the reconnect turns a transient transport blip into a
+      // silently dropped credential (reads degrade gracefully via env-var
+      // and dead-backend fallbacks; writes have no fallback).
+      const reconnected = await attemptCesReconnection({
+        ignoreCooldown: options.forceReconnect,
+      });
       if (reconnected) {
         // setCesClient() cleared the cache — fall through to re-resolve
         // with the fresh client.
@@ -215,7 +248,11 @@ async function resolveBackendAsync(): Promise<CredentialBackend> {
       // - We're on ces-http but an operation returned unreachable (HTTP
       //   endpoint is actually down even though isAvailable() returned true,
       //   since it only checks env vars, not actual connectivity).
-      const reconnected = await attemptCesReconnection();
+      // Mutating ops bypass the cooldown here too, so a write during the
+      // window lands on CES rather than on a fallback CES never sees.
+      const reconnected = await attemptCesReconnection({
+        ignoreCooldown: options.forceReconnect,
+      });
       if (reconnected) {
         // setCesClient() cleared the cache — fall through to re-resolve.
       } else {
@@ -235,13 +272,17 @@ async function resolveBackendAsync(): Promise<CredentialBackend> {
 function tryFailoverToCesHttpBackend(
   backend: CredentialBackend,
 ): CredentialBackend | undefined {
-  if (backend.name !== "ces-rpc") {return undefined;}
+  if (backend.name !== "ces-rpc") {
+    return undefined;
+  }
   if (!getIsContainerized() || !process.env.CES_CREDENTIAL_URL) {
     return undefined;
   }
 
   const cesHttp = createCesCredentialBackend();
-  if (!cesHttp.isAvailable()) {return undefined;}
+  if (!cesHttp.isAvailable()) {
+    return undefined;
+  }
 
   _resolvedBackend = cesHttp;
   _resolvePromise = undefined;
@@ -258,14 +299,20 @@ function tryFailoverToCesHttpBackend(
  *
  * Concurrent callers share the same in-flight reconnection attempt to avoid
  * racing on the same process manager. A timestamp cooldown prevents rapid
- * back-to-back attempts after completion.
+ * back-to-back attempts after completion; `ignoreCooldown` bypasses it for
+ * callers (credential writes) where a refused attempt loses data. The
+ * in-flight dedup and reentrancy guard still apply either way.
  *
  * Exported so the proactive reconnect loop in ces-runtime.ts can trigger
  * reconnection immediately on transport close, reusing the same dedup +
  * cooldown machinery as the lazy (credential-op-triggered) path.
  */
-export async function attemptCesReconnection(): Promise<boolean> {
-  if (!_cesReconnect) {return false;}
+export async function attemptCesReconnection(
+  options: { ignoreCooldown?: boolean } = {},
+): Promise<boolean> {
+  if (!_cesReconnect) {
+    return false;
+  }
 
   // Reentrancy guard. A nested credential read from inside the reconnect
   // callback must not `await` our own in-flight promise — that would
@@ -274,13 +321,22 @@ export async function attemptCesReconnection(): Promise<boolean> {
   // dead-backend response) without blocking. Concurrent callers on other
   // async chains don't see the ALS store, so they still share the
   // in-flight promise normally.
-  if (_reconnectContext.getStore()) {return false;}
+  if (_reconnectContext.getStore()) {
+    return false;
+  }
 
   // If a reconnection is already in flight, share it.
-  if (_reconnectInFlight) {return _reconnectInFlight;}
+  if (_reconnectInFlight) {
+    return _reconnectInFlight;
+  }
 
   // Cooldown — don't retry immediately after a completed attempt.
-  if (Date.now() - _lastReconnectAttempt < RECONNECT_COOLDOWN_MS) {return false;}
+  if (
+    !options.ignoreCooldown &&
+    Date.now() - _lastReconnectAttempt < RECONNECT_COOLDOWN_MS
+  ) {
+    return false;
+  }
 
   _lastReconnectAttempt = Date.now();
   log.warn("Credential backend unavailable — attempting CES reconnection");
@@ -307,6 +363,93 @@ export async function attemptCesReconnection(): Promise<boolean> {
   }
 }
 
+/**
+ * Lazily connect to a CES sibling socket from a non-daemon process.
+ *
+ * Workers and CLI subprocesses inherit CES_LOCAL_SOCKET from the daemon's
+ * environment but never call startCes(). This function establishes a direct
+ * CES connection on first credential resolution, memoizing the in-flight
+ * promise so concurrent callers share a single connect+handshake.
+ *
+ * On success, the client is injected via setCesClient() so subsequent
+ * resolveBackendAsync() calls take the fast CES RPC path (step 1). A
+ * reconnect callback is also registered so the lazy connection can heal
+ * if the transport drops mid-process.
+ *
+ * Returns undefined on any failure (socket not found, handshake rejected,
+ * timeout) so the caller falls through to the encrypted file store.
+ */
+async function tryLazyCesConnect(): Promise<CesClient | undefined> {
+  if (_lazyConnectPromise) {
+    return _lazyConnectPromise;
+  }
+
+  _lazyConnectPromise = (async () => {
+    try {
+      const pm = createCesProcessManager({});
+      const transport = await pm.start();
+      const client = createCesClient(transport);
+      const { accepted, reason } = await client.handshake();
+      if (!accepted) {
+        log.warn(
+          { reason },
+          "Lazy CES connection handshake rejected — falling back to encrypted file store",
+        );
+        client.close();
+        await pm.stop().catch(() => {});
+        return undefined;
+      }
+      log.info(
+        "Lazy CES connection established — credential operations routed through CES RPC",
+      );
+      setCesClient(client);
+      // Register a reconnect callback so the lazy connection self-heals
+      // if the transport drops, mirroring the daemon's proactive reconnect.
+      setCesReconnect(async () => {
+        try {
+          await pm.stop();
+          const newTransport = await pm.start();
+          const newClient = createCesClient(newTransport);
+          const { accepted: ok } = await newClient.handshake();
+          if (ok) {
+            log.info("Lazy CES reconnection successful");
+            return newClient;
+          }
+          newClient.close();
+          await pm.stop().catch(() => {});
+          return undefined;
+        } catch (err) {
+          log.warn(
+            { error: err instanceof Error ? err.message : String(err) },
+            "Lazy CES reconnection failed",
+          );
+          return undefined;
+        }
+      });
+      return client;
+    } catch (err) {
+      if (err instanceof CesUnavailableError) {
+        log.info(
+          { reason: err.message },
+          "CES socket not reachable for lazy connect — falling back to encrypted file store",
+        );
+      } else {
+        log.warn(
+          { error: err instanceof Error ? err.message : String(err) },
+          "Lazy CES connection failed — falling back to encrypted file store",
+        );
+      }
+      return undefined;
+    }
+  })();
+
+  try {
+    return await _lazyConnectPromise;
+  } finally {
+    _lazyConnectPromise = undefined;
+  }
+}
+
 async function doResolveBackend(): Promise<CredentialBackend> {
   // 1. CES RPC — primary credential backend for all local modes
   if (_cesClient) {
@@ -333,6 +476,24 @@ async function doResolveBackend(): Promise<CredentialBackend> {
     );
   }
 
+  // 2.5. Lazy CES RPC connect — non-daemon processes (workers, CLI
+  //      subprocesses) inherit CES_LOCAL_SOCKET but never call startCes().
+  //      When the daemon's setCesReconnect() is NOT registered, attempt a
+  //      direct connection to the CES sibling socket. On success, inject
+  //      the client via setCesClient() and re-resolve through the CES RPC
+  //      path. On failure, fall through to the encrypted file store.
+  if (!_cesClient && !_cesReconnect && process.env.CES_LOCAL_SOCKET) {
+    const lazyClient = await tryLazyCesConnect();
+    if (lazyClient) {
+      const cesRpc = new CesRpcCredentialBackend(lazyClient);
+      if (cesRpc.isAvailable()) {
+        _resolvedBackend = cesRpc;
+        return cesRpc;
+      }
+    }
+    // Lazy connect failed — fall through to encrypted file store.
+  }
+
   // 3. Encrypted file store — fallback when CES is unavailable
   _resolvedBackend = getEncryptedStoreBackend();
   return _resolvedBackend;
@@ -450,14 +611,16 @@ export async function getSecureKeyAsync(
 
 /**
  * Store a secret in secure storage. Writes to exactly one backend —
- * no dual-writing.
+ * no dual-writing. Forces a CES reconnection when the backend is dead —
+ * callers (e.g. the post-login platform credential push) do not retry a
+ * failed write.
  */
 export async function setSecureKeyAsync(
   account: string,
   value: string,
 ): Promise<boolean> {
   return withCredentialTimeout(async () => {
-    const backend = await resolveBackendAsync();
+    const backend = await resolveBackendAsync({ forceReconnect: true });
     const ok = await backend.set(account, value);
     if (!ok) {
       log.warn(
@@ -481,7 +644,7 @@ export async function deleteSecureKeyAsync(
   account: string,
 ): Promise<DeleteResult> {
   return withCredentialTimeout(async () => {
-    const backend = await resolveBackendAsync();
+    const backend = await resolveBackendAsync({ forceReconnect: true });
     const result = await backend.delete(account);
     if (result === "deleted") {
       log.info({ account, backend: backend.name }, "Credential deleted");
@@ -502,7 +665,7 @@ export async function bulkSetSecureKeysAsync(
 ): Promise<Array<{ account: string; ok: boolean }>> {
   return withCredentialTimeout(
     async () => {
-      const backend = await resolveBackendAsync();
+      const backend = await resolveBackendAsync({ forceReconnect: true });
       let results: Array<{ account: string; ok: boolean }>;
       if (backend.bulkSet) {
         results = await backend.bulkSet(credentials);
@@ -514,7 +677,9 @@ export async function bulkSetSecureKeysAsync(
         let anyFailed = false;
         for (const { account, value } of credentials) {
           const ok = await backend.set(account, value);
-          if (!ok) {anyFailed = true;}
+          if (!ok) {
+            anyFailed = true;
+          }
           results.push({ account, ok });
         }
         updateCesHttpReachability(backend, anyFailed);
@@ -558,7 +723,9 @@ export async function getProviderKeyAsync(
   const stored =
     (await getSecureKeyAsync(credentialKey(provider, "api_key"))) ??
     (await getSecureKeyAsync(provider));
-  if (stored) {return stored;}
+  if (stored) {
+    return stored;
+  }
   const envVar = getAnyProviderEnvVar(provider);
   return envVar ? process.env[envVar] : undefined;
 }
@@ -576,7 +743,9 @@ export async function getMaskedProviderKey(
   provider: string,
 ): Promise<string | null> {
   const key = await getProviderKeyAsync(provider);
-  if (!key || key.length === 0) {return null;}
+  if (!key || key.length === 0) {
+    return null;
+  }
   const minHidden = 3;
   const maxVisible = Math.max(1, key.length - minHidden);
   const prefixLen = Math.min(10, maxVisible);
@@ -621,31 +790,34 @@ export type BackendInfo =
  * visible.
  */
 export function getActiveBackendInfoAsync(): Promise<BackendInfo> {
-  return withCredentialTimeout(async () => {
-    const backend = await resolveBackendAsync();
-    if (backend.name === "encrypted-store") {
-      const protectedDir = getProtectedDir();
-      const storePath = join(protectedDir, "keys.enc");
-      const storeKeyPath = join(protectedDir, "store.key");
-      return {
-        backend: "encrypted-store" as const,
-        storePath,
-        storeKeyPath,
-        storeExists: existsSync(storePath),
-        storeKeyExists: existsSync(storeKeyPath),
-      };
-    }
-    if (backend.name === "ces-rpc") {
-      return { backend: "ces-rpc" as const, ready: backend.isAvailable() };
-    }
-    if (backend.name === "ces-http") {
-      return {
-        backend: "ces-http" as const,
-        url: process.env.CES_CREDENTIAL_URL ?? "",
-      };
-    }
-    return { backend: "none" as const };
-  }, { backend: "none" as const });
+  return withCredentialTimeout(
+    async () => {
+      const backend = await resolveBackendAsync();
+      if (backend.name === "encrypted-store") {
+        const protectedDir = getProtectedDir();
+        const storePath = join(protectedDir, "keys.enc");
+        const storeKeyPath = join(protectedDir, "store.key");
+        return {
+          backend: "encrypted-store" as const,
+          storePath,
+          storeKeyPath,
+          storeExists: existsSync(storePath),
+          storeKeyExists: existsSync(storeKeyPath),
+        };
+      }
+      if (backend.name === "ces-rpc") {
+        return { backend: "ces-rpc" as const, ready: backend.isAvailable() };
+      }
+      if (backend.name === "ces-http") {
+        return {
+          backend: "ces-http" as const,
+          url: process.env.CES_CREDENTIAL_URL ?? "",
+        };
+      }
+      return { backend: "none" as const };
+    },
+    { backend: "none" as const },
+  );
 }
 
 /** @internal Test-only: reset the cached backends so they're re-created. */
@@ -659,4 +831,5 @@ export function _resetBackend(): void {
   _lastReconnectAttempt = 0;
   _reconnectInFlight = undefined;
   _cesHttpUnreachable = false;
+  _lazyConnectPromise = undefined;
 }

package/src/sequence/engine.ts

@@ -35,7 +35,9 @@ const STEP_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes per step
 export async function runSequencesOnce(): Promise<number> {
   const now = Date.now();
   const claimed = claimDueEnrollments(now, BATCH_SIZE);
-  if (claimed.length === 0) return 0;
+  if (claimed.length === 0) {
+    return 0;
+  }
 
   let processed = 0;
   for (const enrollment of claimed) {
@@ -202,8 +204,9 @@ async function processEnrollment(
   // null so it won't be re-claimed. The approval/send flow is responsible
   // for advancing the enrollment once the draft is approved.
   if (step.requireApproval) {
-    if (extractedConversationId)
+    if (extractedConversationId) {
       updateEnrollmentConversationId(enrollment.id, extractedConversationId);
+    }
     log.info(
       {
         enrollmentId: enrollment.id,
@@ -322,8 +325,10 @@ function extractThreadIdFromConversation(
     // is the one we want.
     for (let i = msgs.length - 1; i >= 0; i--) {
       const msg = msgs[i];
-      const threadId = extractThreadIdFromContent(msg.content);
-      if (threadId) return threadId;
+      const threadId = extractThreadIdFromContent(JSON.stringify(msg.content));
+      if (threadId) {
+        return threadId;
+      }
     }
   } catch (err) {
     log.warn(
@@ -338,11 +343,15 @@ function extractThreadIdFromConversation(
 function extractThreadIdFromContent(content: string): string | null {
   // Pattern 1: JSON field like "threadId": "..." or "thread_id": "..."
   const jsonMatch = content.match(/"(?:threadId|thread_id)"\s*:\s*"([^"]+)"/);
-  if (jsonMatch) return jsonMatch[1];
+  if (jsonMatch) {
+    return jsonMatch[1];
+  }
 
   // Pattern 2: Prose like "Thread ID: <id>" (from tool result text)
   const proseMatch = content.match(/[Tt]hread\s+(?:ID|id):\s*(\S+)/);
-  if (proseMatch) return proseMatch[1];
+  if (proseMatch) {
+    return proseMatch[1];
+  }
 
   return null;
 }

package/src/signals/user-message.ts

@@ -14,6 +14,8 @@
 import { readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { v7 as uuidv7 } from "uuid";
+
 import { getOrCreateConversation } from "../daemon/conversation-store.js";
 import { supersedePendingInteractionsOnEnqueue } from "../daemon/handlers/conversations.js";
 import type { UserMessageAttachment } from "../daemon/message-types/shared.js";
@@ -118,7 +120,7 @@ async function dispatchUserMessage(params: {
         }
       }
     }
-    const requestId = crypto.randomUUID();
+    const requestId = uuidv7();
     const resolvedChannel = resolveTurnChannel(params.sourceChannel);
     const resolvedInterface = resolveTurnInterface(params.sourceInterface);
     const result = conversation.enqueueMessage({

package/src/skills/available-skills.ts

@@ -0,0 +1,134 @@
+import { getConfig } from "../config/loader.js";
+import type { SkillSource } from "../config/skills.js";
+import type { SkillInstallMeta } from "./install-meta.js";
+
+/**
+ * Plugin-facing read API over the skill surface: the locally installed
+ * catalog with resolved enablement states, and the remote skill catalog —
+ * each composed host-side (catalog load + install-state resolution +
+ * feature-flag gating + install-meta read), so callers hold no host config
+ * and perform no flag checks of their own.
+ *
+ * The underlying skill and flag modules are loaded via dynamic `import()`
+ * inside each function so that importing this module — which every
+ * `@vellumai/plugin-api` consumer does transitively — does not eagerly pull
+ * the catalog/flag import graph. An eager pull would force those modules'
+ * named exports to resolve at instantiation, which breaks the intentional
+ * partial module mocks in tests.
+ */
+
+/** One skill as seen by a plugin: capability fields plus resolved state. */
+export interface ResolvedSkillEntry {
+  id: string;
+  displayName: string;
+  description: string;
+  /** Compact routing cues declared in frontmatter / catalog metadata. */
+  activationHints?: string[];
+  /** Conditions under which the skill should not be loaded. */
+  avoidWhen?: string[];
+  /** True when the skill is pinned into the memory selector pool every turn. */
+  alwaysCandidate?: boolean;
+  /** True for locally installed skills; false for remote catalog entries. */
+  installed: boolean;
+  /** Where the installed skill comes from. Unset for remote catalog entries. */
+  source?: SkillSource;
+  /**
+   * Resolved availability:
+   * - `enabled` / `disabled` — installed, per config and source defaults.
+   * - `unavailable` — gated off (feature flag disabled, or a bundled skill
+   *   excluded by the `allowBundled` allowlist). Present so callers can still
+   *   enumerate the full id universe.
+   * - `available` — a remote catalog entry that is not locally installed.
+   */
+  state: "enabled" | "disabled" | "unavailable" | "available";
+  /**
+   * Install metadata for user-installed skills (`managed` / `workspace` /
+   * `extra` sources): `null` when the directory has no install-meta file,
+   * unset for sources that never carry one (bundled, plugin, remote).
+   */
+  installMeta?: SkillInstallMeta | null;
+}
+
+/**
+ * The locally installed skill catalog with resolved states. Includes every
+ * catalog entry — skills dropped by flag gating or the bundled allowlist are
+ * reported with `state: "unavailable"` rather than omitted, so the returned
+ * ids are the complete installed universe.
+ */
+export async function listInstalledSkills(): Promise<ResolvedSkillEntry[]> {
+  const [{ loadSkillCatalog }, { resolveSkillStates }, { readInstallMeta }] =
+    await Promise.all([
+      import("../config/skills.js"),
+      import("../config/skill-state.js"),
+      import("./install-meta.js"),
+    ]);
+  const catalog = loadSkillCatalog();
+  const stateById = new Map(
+    resolveSkillStates(catalog, getConfig()).map((r) => [
+      r.summary.id,
+      r.state,
+    ]),
+  );
+  return catalog.map((summary) => {
+    const entry: ResolvedSkillEntry = {
+      id: summary.id,
+      displayName: summary.displayName,
+      description: summary.description,
+      activationHints: summary.activationHints,
+      avoidWhen: summary.avoidWhen,
+      alwaysCandidate: summary.alwaysCandidate,
+      installed: true,
+      source: summary.source,
+      state: stateById.get(summary.id) ?? "unavailable",
+    };
+    if (
+      summary.source === "managed" ||
+      summary.source === "workspace" ||
+      summary.source === "extra"
+    ) {
+      entry.installMeta = readInstallMeta(summary.directoryPath);
+    }
+    return entry;
+  });
+}
+
+/**
+ * The remote skill catalog, fetched via the shared catalog cache. Entries
+ * whose declared feature flag is disabled are reported with
+ * `state: "unavailable"`; all others are `state: "available"`. Not deduplicated
+ * against the installed catalog — callers that merge the two lists filter by
+ * installed ids themselves.
+ *
+ * A fetch failure never rejects: the underlying cache degrades through its
+ * fallback chain (stale cache → bundled local catalog → empty) and this
+ * returns whatever that yields. An empty result therefore means "could not
+ * enumerate the catalog" as much as "the catalog is empty" — callers must
+ * gate destructive reconciliation (pruning against the catalog id set) on a
+ * non-empty result. Unexpected errors from the catalog read propagate.
+ */
+export async function listCatalogSkills(): Promise<ResolvedSkillEntry[]> {
+  const [{ getCatalog }, { isAssistantFeatureFlagEnabled }] = await Promise.all(
+    [
+      import("./catalog-cache.js"),
+      import("../config/assistant-feature-flags.js"),
+    ],
+  );
+  const catalog = await getCatalog();
+  const config = getConfig();
+  return catalog.map((entry) => {
+    const flagKey = entry.metadata?.vellum?.["feature-flag"];
+    const gated =
+      typeof flagKey === "string" &&
+      flagKey.length > 0 &&
+      !isAssistantFeatureFlagEnabled(flagKey, config);
+    return {
+      id: entry.id,
+      displayName: entry.metadata?.vellum?.["display-name"] ?? entry.name,
+      description: entry.description,
+      activationHints: entry.metadata?.vellum?.["activation-hints"],
+      avoidWhen: entry.metadata?.vellum?.["avoid-when"],
+      installed: false,
+      state: gated ? "unavailable" : "available",
+    };
+  });
+}

package/src/skills/install-meta.ts

@@ -29,6 +29,14 @@ export interface SkillInstallMeta {
   // skills are eligible for the usage-based prune; "user" and untagged skills
   // are protected. Set by install/scaffold callers, never defaulted here.
   author?: "assistant" | "user";
+  // Conversation whose trace the retrospective distilled this skill from (the
+  // fork's parent). The durable lineage record for retrospective-authored
+  // skills.
+  sourceConversationId?: string;
+  // Retrospective background (fork) conversation that authored this skill.
+  // That conversation is GC'd once superseded, so this id is a debugging
+  // breadcrumb only — `sourceConversationId` is the durable lineage.
+  retrospectiveConversationId?: string;
   // Day-granularity stamp of the last time the skill was loaded (ISO 8601).
   // Stamped by `touchSkillLastUsed` on the managed-skill activation path; the
   // usage-based prune reads its date portion as the last-used signal.

package/src/skills/managed-store.ts

@@ -217,6 +217,10 @@ interface CreateManagedSkillParams {
   version?: string;
   contactId?: string;
   author?: "assistant" | "user";
+  // Conversation lineage for retrospective-authored skills — see the field
+  // docs on `SkillInstallMeta` (install-meta.ts).
+  sourceConversationId?: string;
+  retrospectiveConversationId?: string;
   files?: Array<{ path: string; content: string }>;
 }
 
@@ -315,6 +319,12 @@ export function createManagedSkill(
     ...(params.version ? { version: params.version } : {}),
     ...(params.contactId ? { installedBy: params.contactId } : {}),
     ...(params.author ? { author: params.author } : {}),
+    ...(params.sourceConversationId
+      ? { sourceConversationId: params.sourceConversationId }
+      : {}),
+    ...(params.retrospectiveConversationId
+      ? { retrospectiveConversationId: params.retrospectiveConversationId }
+      : {}),
   });
 
   // Clean up legacy version.json if present (superseded by install-meta.json)