@vellumai/assistant 0.5.11 → 0.5.13

package/Dockerfile

@@ -38,22 +38,55 @@ WORKDIR /app/assistant
 
 # Install runtime dependencies for Playwright and tree-sitter
 RUN apt-get update && apt-get install -y \
-    curl \
-    unzip \
+    bubblewrap \
     ca-certificates \
-    python3 \
-    libnss3 \
-    libfreetype6 \
-    libharfbuzz0b \
+    curl \
+    ffmpeg \
     fonts-freefont-ttf \
-    make \
     g++ \
     git \
-    sudo \
     htop \
-    procps \
     jq \
+    libasound2 \
+    libatk-bridge2.0-0 \
+    libatk1.0-0 \
+    libatspi2.0-0 \
+    libcairo2 \
+    libcups2 \
+    libdrm2 \
+    libfreetype6 \
+    libgbm1 \
+    libharfbuzz0b \
+    libnspr4 \
+    libnss3 \
+    libpango-1.0-0 \
+    libpangocairo-1.0-0 \
+    libx11-6 \
+    libx11-xcb1 \
+    libxcb-dri3-0 \
+    libxcb1 \
+    libxcomposite1 \
+    libxdamage1 \
+    libxext6 \
+    libxfixes3 \
+    libxi6 \
+    libxkbcommon0 \
+    libxrandr2 \
+    libxrender1 \
+    libxshmfence1 \
+    libxtst6 \
+    lsof \
+    make \
+    openssl \
+    procps \
+    python3 \
+    sqlite3 \
+    sudo \
+    unzip \
     uuid-runtime \
+    vim \
+    xclip \
+    xdg-utils \
     && rm -rf /var/lib/apt/lists/*
 
 # Copy bun binary from builder instead of re-installing

package/docs/architecture/integrations.md

@@ -144,7 +144,7 @@ sequenceDiagram
 
     Note over UI,API: Tool Execution Flow
     Tool->>TokenMgr: withValidToken("gmail", callback)
-    TokenMgr->>Store: getConnectionByProvider("integration:google")
+    TokenMgr->>Store: getConnectionByProvider("google")
     TokenMgr->>Vault: getSecureKeyAsync("oauth_connection/{conn.id}/access_token")
     TokenMgr->>Store: check oauth_connections.expires_at
     alt Token expired
@@ -196,32 +196,33 @@ sequenceDiagram
 | `assistant/src/watcher/providers/gmail.ts`       | Gmail watcher using History API                                                                    |
 | `assistant/src/watcher/providers/github.ts`      | GitHub watcher for PRs, issues, review requests, and mentions                                      |
 | `assistant/src/watcher/providers/linear.ts`      | Linear watcher for assigned issues, status changes, and @mentions                                  |
-| `assistant/src/oauth/provider-behaviors.ts`      | Provider behavior registry: identity verifiers, setup metadata, injection templates                |
+| `assistant/src/oauth/seed-providers.ts`          | Provider seed data: injection templates, identity config, setup metadata (seeded to DB on startup) |
 | `assistant/src/oauth/connect-orchestrator.ts`    | Shared OAuth connect orchestrator: profile resolution, scope policy, flow execution, token storage |
 | `assistant/src/oauth/scope-policy.ts`            | Deterministic scope resolution and policy enforcement                                              |
-| `assistant/src/oauth/connect-types.ts`           | Shared types: `OAuthProviderBehavior`, `OAuthScopePolicy`, `OAuthConnectResult`                    |
+| `assistant/src/oauth/connect-types.ts`           | Shared types: `OAuthScopePolicy`, `OAuthConnectResult`                                             |
 | `assistant/src/oauth/token-persistence.ts`       | Token storage helper: persists tokens, metadata, and runs post-connect hooks                       |
 | `assistant/src/daemon/handlers/oauth-connect.ts` | Generic OAuth connect handler (`oauth_connect_start` / `oauth_connect_result`)                     |
 
 ---
 
-## OAuth Extensibility — Provider Behaviors, Scope Policy, and Connect Orchestrator
+## OAuth Extensibility — DB-Driven Provider Config, Scope Policy, and Connect Orchestrator
 
-The OAuth extensibility layer makes adding a new OAuth provider a declarative operation. Protocol fields (auth URLs, token URLs, scopes, scope policy) are stored in the `oauth_providers` database table, while behavioral fields (identity verifiers, setup metadata, injection templates) live in the **provider behavior registry**. The shared **connect orchestrator** handles the full flow from provider resolution through token storage.
+The OAuth extensibility layer makes adding a new OAuth provider a fully declarative operation. All provider configuration — protocol fields (auth URLs, token URLs, scopes, scope policy), behavioral fields (identity verification, injection templates, setup metadata), and display metadata — is stored in the `oauth_providers` SQLite table and seeded on startup via `seed-providers.ts`. The shared **connect orchestrator** handles the full flow from provider resolution through token storage.
 
-### Provider Behavior Registry
+### Provider Configuration (DB-Driven)
 
-`assistant/src/oauth/provider-behaviors.ts` contains the `PROVIDER_BEHAVIORS` map — a registry of behavioral aspects for well-known OAuth providers. Each behavior (`OAuthProviderBehavior`) declares:
+All provider config lives in the `oauth_providers` table. Built-in providers are seeded on every startup by `assistant/src/oauth/seed-providers.ts`, which upserts rows from the `PROVIDER_SEED_DATA` constant. Custom providers can be registered via the CLI (`assistant oauth providers register`).
 
-| Field                | Purpose                                                                                                |
-| -------------------- | ------------------------------------------------------------------------------------------------------ |
-| `identityVerifier`   | Async function that fetches human-readable account info (e.g. `@username`, email) after token exchange |
-| `setup`              | Optional metadata for the generic OAuth setup skill (display name, dashboard URL, app type)            |
-| `injectionTemplates` | Auto-applied credential injection rules for the script proxy                                           |
+Each provider row includes:
 
-Protocol fields (`authUrl`, `tokenUrl`, `defaultScopes`, `scopePolicy`, `callbackTransport`) are stored in the `oauth_providers` database table rather than in code.
-
-Registered providers: `integration:google`, `integration:slack`, `integration:notion`. Short aliases (e.g. `gmail`, `slack`) are resolved via `resolveService()`.
+| Column group              | Fields                                                                                                                           | Purpose                                                                                |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| **Protocol**              | `authUrl`, `tokenUrl`, `tokenEndpointAuthMethod`, `callbackTransport`, `extraParams`, `loopbackPort`                             | OAuth2 flow parameters                                                                 |
+| **Scopes**                | `defaultScopes`, `scopePolicy`                                                                                                   | Deterministic scope resolution (user-customizable, preserved across seed restarts)     |
+| **Identity verification** | `identityUrl`, `identityMethod`, `identityHeaders`, `identityBody`, `identityResponsePaths`, `identityFormat`, `identityOkField` | Data-driven identity verifier fetches human-readable account info after token exchange |
+| **Injection templates**   | `injectionTemplates`                                                                                                             | Auto-applied credential injection rules for the script proxy                           |
+| **Setup metadata**        | `displayName`, `description`, `dashboardUrl`, `appType`, `setupNotes`, `requiresClientSecret`                                    | Metadata for the generic OAuth setup skill                                             |
+| **Ping config**           | `pingUrl`, `pingMethod`, `pingHeaders`, `pingBody`                                                                               | Health-check endpoint for `assistant oauth ping`                                       |
 
 ### Scope Policy Engine
 
@@ -240,12 +241,12 @@ Returns `{ ok: true, scopes }` or `{ ok: false, error, allowedScopes }`.
 
 `assistant/src/oauth/connect-orchestrator.ts` exports `orchestrateOAuthConnect(options)`, which runs the full OAuth2 flow:
 
-1. **Resolve service** — alias expansion via `resolveService()`.
-2. **Load behavior** — `getProviderBehavior()` from the registry; load protocol fields from the `oauth_providers` DB table.
+1. **Receive canonical provider name** — the orchestrator receives the canonical provider name directly (e.g. `google`, `slack`).
+2. **Load provider row** — reads all config from the `oauth_providers` DB table.
 3. **Compute scopes** — `resolveScopes()` with scope policy enforcement.
 4. **Build OAuth config** — assemble protocol-level config from the DB provider row.
 5. **Run flow** — interactive (opens browser, blocks until completion) or deferred (returns auth URL for the caller to deliver).
-6. **Verify identity** — runs the profile's `identityVerifier` if defined.
+6. **Verify identity** — runs the generic data-driven identity verifier using the provider row's identity columns.
 7. **Store tokens** — `storeOAuth2Tokens()` persists access/refresh tokens, client credentials, and metadata.
 
 Result is a discriminated union: `{ success, deferred, grantedScopes, accountInfo }` or `{ success: false, error }`.
@@ -263,24 +264,25 @@ This replaces provider-specific handlers — any provider in the registry can be
 
 ### Adding a New OAuth Provider
 
-1. **Register protocol fields** in the `oauth_providers` database table (via CLI or migration):
-   - Set `authUrl`, `tokenUrl`, `defaultScopes`, `scopePolicy`, and `callbackTransport`.
-2. **Optional: declare behavioral fields** in `PROVIDER_BEHAVIORS` (`oauth/provider-behaviors.ts`):
-   - Add an `identityVerifier` — an async function that fetches the user's account info from the provider's API.
-   - Add `setup` metadata — `displayName`, `dashboardUrl`, `appType` enable the generic OAuth setup skill to guide users through app creation.
-   - Add `injectionTemplates` — for providers whose tokens should be auto-injected by the script proxy.
+1. **Add seed data** to `PROVIDER_SEED_DATA` in `assistant/src/oauth/seed-providers.ts`:
+   - Set protocol fields: `authUrl`, `tokenUrl`, `defaultScopes`, `scopePolicy`, `callbackTransport`.
+   - Set identity verification: `identityUrl`, `identityMethod`, `identityHeaders`, `identityResponsePaths`, `identityFormat`.
+   - Set injection templates: `injectionTemplates` for providers whose tokens should be auto-injected by the script proxy.
+   - Set setup metadata: `displayName`, `dashboardUrl`, `appType` enable the generic OAuth setup skill to guide users through app creation.
+2. **Alternatively, register dynamically** via the CLI: `assistant oauth providers register <key> --auth-url ... --token-url ...`.
 3. **No handler code needed** — the generic `oauth_connect_start` handler and the connect orchestrator handle the flow automatically.
 
 ### Key Source Files
 
-| File                                             | Role                                                                             |
-| ------------------------------------------------ | -------------------------------------------------------------------------------- |
-| `assistant/src/oauth/provider-behaviors.ts`      | Provider behavior registry and alias resolution                                  |
-| `assistant/src/oauth/scope-policy.ts`            | Scope resolution and policy enforcement (pure, no I/O)                           |
-| `assistant/src/oauth/connect-orchestrator.ts`    | Shared connect orchestrator (profile → scopes → flow → tokens)                   |
-| `assistant/src/oauth/connect-types.ts`           | Shared types (`OAuthProviderBehavior`, `OAuthScopePolicy`, `OAuthConnectResult`) |
-| `assistant/src/oauth/token-persistence.ts`       | Token storage: credential store writes, metadata upsert, post-connect hooks      |
-| `assistant/src/daemon/handlers/oauth-connect.ts` | Generic `oauth_connect_start` / `oauth_connect_result` handler                   |
+| File                                             | Role                                                                        |
+| ------------------------------------------------ | --------------------------------------------------------------------------- |
+| `assistant/src/oauth/seed-providers.ts`          | Provider seed data and startup seeding                                      |
+| `assistant/src/oauth/scope-policy.ts`            | Scope resolution and policy enforcement (pure, no I/O)                      |
+| `assistant/src/oauth/connect-orchestrator.ts`    | Shared connect orchestrator (profile → scopes → flow → tokens)              |
+| `assistant/src/oauth/connect-types.ts`           | Shared types (`OAuthScopePolicy`, `OAuthConnectResult`)                     |
+| `assistant/src/oauth/token-persistence.ts`       | Token storage: credential store writes, metadata upsert, post-connect hooks |
+| `assistant/src/oauth/identity-verifier.ts`       | Generic data-driven identity verifier (reads config from provider DB row)   |
+| `assistant/src/daemon/handlers/oauth-connect.ts` | Generic `oauth_connect_start` / `oauth_connect_result` handler              |
 
 ---
 

package/node_modules/@vellumai/ces-contracts/src/__tests__/grants.test.ts

@@ -71,19 +71,19 @@ describe("handles", () => {
 
   describe("localOAuthHandle", () => {
     test("constructs the expected format", () => {
-      expect(localOAuthHandle("integration:google", "conn-123")).toBe(
-        "local_oauth:integration:google/conn-123",
+      expect(localOAuthHandle("google", "conn-123")).toBe(
+        "local_oauth:google/conn-123",
       );
     });
 
-    test("roundtrips with integration: prefix in providerKey", () => {
-      const raw = localOAuthHandle("integration:slack", "conn-abc");
+    test("roundtrips through parseHandle", () => {
+      const raw = localOAuthHandle("slack", "conn-abc");
       const result = parseHandle(raw);
       expect(result.ok).toBe(true);
       if (!result.ok) return;
       expect(result.handle.type).toBe(HandleType.LocalOAuth);
       if (result.handle.type !== HandleType.LocalOAuth) return;
-      expect(result.handle.providerKey).toBe("integration:slack");
+      expect(result.handle.providerKey).toBe("slack");
       expect(result.handle.connectionId).toBe("conn-abc");
     });
   });
@@ -133,7 +133,7 @@ describe("handles", () => {
     });
 
     test("rejects local_oauth with no slash", () => {
-      const result = parseHandle("local_oauth:integration:google");
+      const result = parseHandle("local_oauth:google");
       expect(result.ok).toBe(false);
     });
 
@@ -150,7 +150,7 @@ describe("handles", () => {
       ).not.toThrow();
       expect(() =>
         CredentialHandleSchema.parse(
-          "local_oauth:integration:google/conn-1",
+          "local_oauth:google/conn-1",
         ),
       ).not.toThrow();
       expect(() =>

package/node_modules/@vellumai/ces-contracts/src/handles.ts

@@ -13,7 +13,7 @@
  *
  * 2. **Local OAuth** — references a locally persisted OAuth connection.
  *    Format: `local_oauth:<providerKey>/<connectionId>` where providerKey
- *    uses the existing `integration:*` keys (e.g. `integration:google`).
+ *    is the bare provider name (e.g. `google`).
  *
  * 3. **Managed OAuth** — references an OAuth connection managed by the
  *    platform. Format: `platform_oauth:<connectionId>` where connectionId
@@ -50,7 +50,7 @@ export interface LocalStaticHandle {
 
 export interface LocalOAuthHandle {
   type: typeof HandleType.LocalOAuth;
-  /** Provider key (e.g. "integration:google", "integration:slack"). */
+  /** Provider key (e.g. "google", "slack"). */
   providerKey: string;
   /** Connection identifier. */
   connectionId: string;
@@ -146,8 +146,9 @@ export function parseHandle(raw: string): ParseHandleResult {
     }
 
     case HandleType.LocalOAuth: {
-      // providerKey may itself contain a colon (e.g. "integration:google"),
-      // so we split on the *last* "/" to separate providerKey from connectionId.
+      // providerKey is typically a bare name (e.g. "google"), but legacy handles
+      // may contain a colon (e.g. "integration:google"), so we split on the
+      // *last* "/" to separate providerKey from connectionId.
       const lastSlashIdx = rest.lastIndexOf("/");
       if (
         lastSlashIdx === -1 ||

package/node_modules/@vellumai/ces-contracts/src/index.ts

@@ -33,6 +33,13 @@ export const HandshakeRequestSchema = z.object({
    * can use it for platform credential materialisation.
    */
   assistantApiKey: z.string().optional(),
+  /**
+   * Optional platform assistant ID passed from the assistant runtime.
+   * In managed (sidecar) mode with warm pools, the PLATFORM_ASSISTANT_ID
+   * env var may not be set at CES startup. The assistant forwards it here
+   * so CES can use it for platform credential materialisation.
+   */
+  assistantId: z.string().optional(),
 });
 export type HandshakeRequest = z.infer<typeof HandshakeRequestSchema>;
 

package/node_modules/@vellumai/ces-contracts/src/rpc.ts

@@ -422,6 +422,11 @@ export type ListAuditRecordsResponse = z.infer<
 export const UpdateManagedCredentialSchema = z.object({
   /** The assistant API key to push to CES for platform credential materialization. */
   assistantApiKey: z.string(), // nosemgrep: not-a-secret
+  /**
+   * Optional platform assistant ID. In warm-pool mode the ID may not be
+   * available at CES startup; the assistant pushes it here once provisioned.
+   */
+  assistantId: z.string().optional(),
 });
 export type UpdateManagedCredential = z.infer<
   typeof UpdateManagedCredentialSchema

package/node_modules/@vellumai/credential-storage/src/index.ts

@@ -98,7 +98,7 @@ export interface SecureKeyBackend {
 export interface OAuthConnectionRecord {
   /** Unique identifier for this connection. */
   id: string;
-  /** Provider key (e.g. "integration:google", "integration:slack"). */
+  /** Provider key (e.g. "google", "slack"). */
   providerKey: string;
   /** Account identifier (e.g. email address). */
   accountInfo: string | null;

package/openapi.yaml

@@ -3,7 +3,7 @@
 openapi: 3.0.0
 info:
   title: Vellum Assistant API
-  version: 0.5.10
+  version: 0.5.12
   description: Auto-generated OpenAPI specification for the Vellum Assistant runtime HTTP server.
 servers:
   - url: http://127.0.0.1:7821
@@ -3197,11 +3197,14 @@ paths:
                   requestId:
                     type: string
                   reason:
+                    description: Decline reason (present only when applied is false)
+                    type: string
+                  replyText:
+                    description: Resolver reply text for the guardian (e.g. verification code)
                     type: string
                 required:
                   - applied
                   - requestId
-                  - reason
                 additionalProperties: false
       requestBody:
         required: true
@@ -4210,13 +4213,17 @@ paths:
                     type: array
                     items: {}
                     description: Array of message objects
-                  interfaceFiles:
-                    type: array
-                    items: {}
-                    description: Interface file paths with modification timestamps
+                  hasMore:
+                    description: Whether older messages exist beyond this page
+                    type: boolean
+                  oldestTimestamp:
+                    description: Timestamp of the oldest message in this page (ms since epoch)
+                    type: number
+                  oldestMessageId:
+                    description: ID of the oldest message in this page
+                    type: string
                 required:
                   - messages
-                  - interfaceFiles
                 additionalProperties: false
     post:
       operationId: messages_post
@@ -5526,7 +5533,7 @@ paths:
     get:
       operationId: skills_get
       summary: List all skills
-      description: Return all installed skills.
+      description: Return all installed skills. Pass ?include=catalog to also include available catalog skills.
       tags:
         - skills
       responses:
@@ -5539,11 +5546,82 @@ paths:
                 properties:
                   skills:
                     type: array
-                    items: {}
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                        name:
+                          type: string
+                        description:
+                          type: string
+                        emoji:
+                          type: string
+                        homepage:
+                          type: string
+                        source:
+                          type: string
+                          enum:
+                            - bundled
+                            - managed
+                            - workspace
+                            - clawhub
+                            - extra
+                            - catalog
+                        state:
+                          type: string
+                          enum:
+                            - enabled
+                            - disabled
+                        installStatus:
+                          type: string
+                          enum:
+                            - bundled
+                            - installed
+                            - available
+                        updateAvailable:
+                          type: boolean
+                        provenance:
+                          type: object
+                          properties:
+                            kind:
+                              type: string
+                              enum:
+                                - first-party
+                                - third-party
+                                - local
+                            provider:
+                              type: string
+                            originId:
+                              type: string
+                            sourceUrl:
+                              type: string
+                          required:
+                            - kind
+                          additionalProperties: false
+                      required:
+                        - id
+                        - name
+                        - description
+                        - source
+                        - state
+                        - installStatus
+                        - updateAvailable
+                        - provenance
+                      additionalProperties: false
                     description: Skill objects
                 required:
                   - skills
                 additionalProperties: false
+      parameters:
+        - name: include
+          in: query
+          required: false
+          schema:
+            type: string
+            enum:
+              - catalog
+          description: Optional inclusion flag. Use 'catalog' to merge available Vellum catalog skills into the response.
     post:
       operationId: skills_post
       summary: Create skill

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.5.11",
+  "version": "0.5.13",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/catalog-cache.test.ts

@@ -0,0 +1,164 @@
+/**
+ * Unit tests for the catalog cache (catalog-cache.ts).
+ *
+ * Validates TTL-based caching, re-fetch after expiry, stale-cache fallback
+ * on fetch failure, and explicit cache invalidation.
+ */
+
+import { afterEach, describe, expect, mock, test } from "bun:test";
+
+import type { CatalogSkill } from "../skills/catalog-install.js";
+
+// ---------------------------------------------------------------------------
+// Mocks — must be defined before importing the module under test
+// ---------------------------------------------------------------------------
+
+// Suppress logger output
+mock.module("../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+let mockRepoSkillsDir: string | undefined = undefined;
+let mockFetchCatalogResult: CatalogSkill[] = [];
+let mockFetchCatalogError: Error | null = null;
+let fetchCatalogCallCount = 0;
+let readLocalCatalogCallCount = 0;
+
+mock.module("../skills/catalog-install.js", () => ({
+  getRepoSkillsDir: () => mockRepoSkillsDir,
+  readLocalCatalog: (_dir: string) => {
+    readLocalCatalogCallCount++;
+    return mockFetchCatalogResult;
+  },
+  fetchCatalog: async () => {
+    fetchCatalogCallCount++;
+    if (mockFetchCatalogError) {
+      throw mockFetchCatalogError;
+    }
+    return mockFetchCatalogResult;
+  },
+}));
+
+// ---------------------------------------------------------------------------
+// Imports (after mocks)
+// ---------------------------------------------------------------------------
+
+import { getCatalog, invalidateCatalogCache } from "../skills/catalog-cache.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const sampleCatalog: CatalogSkill[] = [
+  { id: "web-search", name: "Web Search", description: "Search the web" },
+  { id: "browser", name: "Browser", description: "Browse the web" },
+];
+
+const updatedCatalog: CatalogSkill[] = [
+  { id: "web-search", name: "Web Search v2", description: "Updated search" },
+];
+
+function resetState(): void {
+  invalidateCatalogCache();
+  mockRepoSkillsDir = undefined;
+  mockFetchCatalogResult = [];
+  mockFetchCatalogError = null;
+  fetchCatalogCallCount = 0;
+  readLocalCatalogCallCount = 0;
+}
+
+afterEach(resetState);
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("getCatalog", () => {
+  test("returns cached value within TTL without re-fetching", async () => {
+    mockFetchCatalogResult = sampleCatalog;
+
+    const first = await getCatalog();
+    expect(first).toEqual(sampleCatalog);
+    expect(fetchCatalogCallCount).toBe(1);
+
+    // Second call should use cache
+    const second = await getCatalog();
+    expect(second).toEqual(sampleCatalog);
+    expect(fetchCatalogCallCount).toBe(1); // no additional fetch
+  });
+
+  test("re-fetches after TTL expires", async () => {
+    mockFetchCatalogResult = sampleCatalog;
+
+    const first = await getCatalog();
+    expect(first).toEqual(sampleCatalog);
+    expect(fetchCatalogCallCount).toBe(1);
+
+    // Simulate TTL expiry by manipulating Date.now
+    const originalNow = Date.now;
+    Date.now = () => originalNow() + 5 * 60 * 1000 + 1;
+
+    try {
+      mockFetchCatalogResult = updatedCatalog;
+      const second = await getCatalog();
+      expect(second).toEqual(updatedCatalog);
+      expect(fetchCatalogCallCount).toBe(2);
+    } finally {
+      Date.now = originalNow;
+    }
+  });
+
+  test("falls back to stale cache on fetch failure", async () => {
+    mockFetchCatalogResult = sampleCatalog;
+
+    // Populate cache
+    const first = await getCatalog();
+    expect(first).toEqual(sampleCatalog);
+
+    // Expire cache and make fetch fail
+    const originalNow = Date.now;
+    Date.now = () => originalNow() + 5 * 60 * 1000 + 1;
+
+    try {
+      mockFetchCatalogError = new Error("Network timeout");
+      const fallback = await getCatalog();
+      expect(fallback).toEqual(sampleCatalog); // stale cache
+    } finally {
+      Date.now = originalNow;
+    }
+  });
+
+  test("returns empty array on fetch failure with no stale cache", async () => {
+    mockFetchCatalogError = new Error("Network timeout");
+
+    const result = await getCatalog();
+    expect(result).toEqual([]);
+  });
+
+  test("invalidateCatalogCache forces re-fetch", async () => {
+    mockFetchCatalogResult = sampleCatalog;
+
+    await getCatalog();
+    expect(fetchCatalogCallCount).toBe(1);
+
+    invalidateCatalogCache();
+
+    mockFetchCatalogResult = updatedCatalog;
+    const refreshed = await getCatalog();
+    expect(refreshed).toEqual(updatedCatalog);
+    expect(fetchCatalogCallCount).toBe(2);
+  });
+
+  test("uses local catalog when repoSkillsDir is set", async () => {
+    mockRepoSkillsDir = "/mock/repo/skills";
+    mockFetchCatalogResult = sampleCatalog;
+
+    const result = await getCatalog();
+    expect(result).toEqual(sampleCatalog);
+    expect(readLocalCatalogCallCount).toBe(1);
+    expect(fetchCatalogCallCount).toBe(0); // no remote fetch
+  });
+});