@vellumai/assistant 0.6.2 → 0.6.4

package/src/credential-health/credential-health-service.ts

@@ -0,0 +1,366 @@
+/**
+ * Proactive credential health monitoring.
+ *
+ * Enumerates all active OAuth connections and validates each one for:
+ * - Token presence in secure storage
+ * - Token expiry (expired or expiring within the warning window)
+ * - Scope coverage (grantedScopes vs provider defaultScopes)
+ * - Liveness ping (for providers with a pingUrl)
+ *
+ * Designed to run during the heartbeat cycle. All checks are diagnostic —
+ * no token refresh or recovery is attempted.
+ */
+
+import {
+  isTokenExpired,
+  oauthConnectionAccessTokenPath,
+} from "@vellumai/credential-storage";
+
+import {
+  getProvider,
+  listActiveConnectionsByProvider,
+  listProviders,
+} from "../oauth/oauth-store.js";
+import { getSecureKeyAsync } from "../security/secure-keys.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("credential-health");
+
+/** 7 days in milliseconds — warn if token expires within this window. */
+const EXPIRY_WARNING_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Timeout for liveness pings. */
+const PING_TIMEOUT_MS = 5_000;
+
+// ── Types ─────────────────────────────────────────────────────────────
+
+export type CredentialHealthStatus =
+  | "healthy"
+  | "expiring"
+  | "expired"
+  | "missing_token"
+  | "missing_scopes"
+  | "revoked"
+  | "ping_failed";
+
+export interface CredentialHealthResult {
+  connectionId: string;
+  provider: string;
+  accountInfo: string | null;
+  status: CredentialHealthStatus;
+  details: string;
+  missingScopes: string[];
+  canAutoRecover: boolean;
+}
+
+export interface CredentialHealthReport {
+  checkedAt: number;
+  results: CredentialHealthResult[];
+  unhealthy: CredentialHealthResult[];
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+function safeJsonParse<T>(raw: string | null | undefined, fallback: T): T {
+  if (!raw) return fallback;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+function scopeDifference(required: string[], granted: string[]): string[] {
+  const grantedSet = new Set(granted);
+  return required.filter((s) => !grantedSet.has(s));
+}
+
+// ── Liveness ping ─────────────────────────────────────────────────────
+
+/** @internal Exposed for test injection. */
+export let _fetchFn: typeof fetch = fetch;
+
+/** @internal Test-only: override the fetch function used for pings. */
+export function _setFetchFn(fn: typeof fetch): void {
+  _fetchFn = fn;
+}
+
+async function pingProvider(
+  token: string,
+  pingUrl: string,
+  pingMethod: string | null,
+  pingHeaders: string | null,
+  pingBody: string | null,
+): Promise<{ ok: boolean; authError: boolean }> {
+  const method = pingMethod ?? "GET";
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${token}`,
+    ...safeJsonParse<Record<string, string>>(pingHeaders, {}),
+  };
+
+  const body =
+    method !== "GET" && pingBody
+      ? (typeof pingBody === "string" ? pingBody : JSON.stringify(pingBody))
+      : undefined;
+
+  try {
+    const response = await _fetchFn(pingUrl, {
+      method,
+      headers,
+      body,
+      signal: AbortSignal.timeout(PING_TIMEOUT_MS),
+    });
+
+    if (response.ok) return { ok: true, authError: false };
+    if (response.status === 401 || response.status === 403) {
+      return { ok: false, authError: true };
+    }
+    return { ok: false, authError: false };
+  } catch {
+    // Network error or timeout — treat as non-auth failure
+    return { ok: false, authError: false };
+  }
+}
+
+// ── Core check ────────────────────────────────────────────────────────
+
+interface CheckConnectionOpts {
+  connectionId: string;
+  provider: string;
+  accountInfo: string | null;
+  expiresAt: number | null;
+  hasRefreshToken: boolean;
+  grantedScopesRaw: string;
+  defaultScopesRaw: string;
+  pingUrl: string | null;
+  pingMethod: string | null;
+  pingHeaders: string | null;
+  pingBody: string | null;
+}
+
+async function checkConnection(
+  opts: CheckConnectionOpts,
+): Promise<CredentialHealthResult> {
+  const {
+    connectionId,
+    provider,
+    accountInfo,
+    expiresAt,
+    hasRefreshToken,
+    grantedScopesRaw,
+    defaultScopesRaw,
+    pingUrl,
+    pingMethod,
+    pingHeaders,
+    pingBody,
+  } = opts;
+
+  const base = { connectionId, provider, accountInfo, missingScopes: [] as string[] };
+
+  // 1. Check token presence
+  const token = await getSecureKeyAsync(
+    oauthConnectionAccessTokenPath(connectionId),
+  );
+  if (!token) {
+    return {
+      ...base,
+      status: "missing_token",
+      details: `No access token found for ${provider}. Re-authorization required.`,
+      canAutoRecover: false,
+    };
+  }
+
+  // 2. Check token expiry
+  if (isTokenExpired(expiresAt)) {
+    return {
+      ...base,
+      status: hasRefreshToken ? "expiring" : "expired",
+      details: hasRefreshToken
+        ? `Token for ${provider} is expired but has a refresh token — auto-recovery may work.`
+        : `Token for ${provider} is expired with no refresh token. Re-authorization required.`,
+      canAutoRecover: hasRefreshToken,
+    };
+  }
+
+  // Check if expiring within warning window (but not yet expired by the 5-min buffer)
+  if (expiresAt && Date.now() >= expiresAt - EXPIRY_WARNING_MS) {
+    // Token works now but will expire soon
+    if (!hasRefreshToken) {
+      return {
+        ...base,
+        status: "expiring",
+        details: `Token for ${provider} expires within 7 days and has no refresh token. Re-authorization will be needed soon.`,
+        canAutoRecover: false,
+      };
+    }
+    // Has refresh token — not an issue, auto-refresh will handle it
+  }
+
+  // 3. Check scope coverage
+  const grantedScopes = safeJsonParse<string[]>(grantedScopesRaw, []);
+  const defaultScopes = safeJsonParse<string[]>(defaultScopesRaw, []);
+  if (defaultScopes.length > 0 && grantedScopes.length > 0) {
+    const missing = scopeDifference(defaultScopes, grantedScopes);
+    if (missing.length > 0) {
+      return {
+        ...base,
+        status: "missing_scopes",
+        details: `${provider} is missing required scopes: ${missing.join(", ")}. Features may not work correctly.`,
+        missingScopes: missing,
+        canAutoRecover: false,
+      };
+    }
+  }
+
+  // 4. Liveness ping
+  if (pingUrl) {
+    const pingResult = await pingProvider(
+      token,
+      pingUrl,
+      pingMethod,
+      pingHeaders,
+      pingBody,
+    );
+    if (!pingResult.ok) {
+      if (pingResult.authError) {
+        return {
+          ...base,
+          status: "revoked",
+          details: `${provider} token was rejected (401/403). The token may have been revoked. Re-authorization required.`,
+          canAutoRecover: false,
+        };
+      }
+      // Non-auth ping failure — log but don't mark as critical.
+      // Could be a transient API issue.
+      log.debug(
+        { provider, connectionId },
+        "Credential ping failed with non-auth error",
+      );
+      return {
+        ...base,
+        status: "ping_failed",
+        details: `${provider} liveness check failed (non-auth error). This may be transient.`,
+        canAutoRecover: false,
+      };
+    }
+  }
+
+  return {
+    ...base,
+    status: "healthy",
+    details: `${provider} credential is healthy.`,
+    canAutoRecover: hasRefreshToken,
+  };
+}
+
+// ── Public API ────────────────────────────────────────────────────────
+
+/**
+ * Check the health of all active OAuth connections.
+ *
+ * Iterates every registered provider, looks up active connections, and
+ * validates each one. Returns a structured report with overall results
+ * and a filtered list of unhealthy credentials.
+ */
+export async function checkAllCredentials(): Promise<CredentialHealthReport> {
+  const checkedAt = Date.now();
+  const results: CredentialHealthResult[] = [];
+
+  let providers;
+  try {
+    providers = listProviders();
+  } catch (err) {
+    log.warn({ err }, "Failed to list OAuth providers");
+    return { checkedAt, results, unhealthy: [] };
+  }
+
+  for (const providerRow of providers) {
+    let connections;
+    try {
+      connections = listActiveConnectionsByProvider(providerRow.provider);
+    } catch (err) {
+      log.warn(
+        { err, provider: providerRow.provider },
+        "Failed to list connections for provider",
+      );
+      continue;
+    }
+
+    for (const conn of connections) {
+      try {
+        const result = await checkConnection({
+          connectionId: conn.id,
+          provider: conn.provider,
+          accountInfo: conn.accountInfo,
+          expiresAt: conn.expiresAt,
+          hasRefreshToken: !!conn.hasRefreshToken,
+          grantedScopesRaw: conn.grantedScopes,
+          defaultScopesRaw: providerRow.defaultScopes,
+          pingUrl: providerRow.pingUrl,
+          pingMethod: providerRow.pingMethod,
+          pingHeaders: providerRow.pingHeaders,
+          pingBody: providerRow.pingBody,
+        });
+        results.push(result);
+      } catch (err) {
+        log.warn(
+          { err, provider: conn.provider, connectionId: conn.id },
+          "Failed to check credential health",
+        );
+      }
+    }
+  }
+
+  const unhealthy = results.filter((r) => r.status !== "healthy");
+  if (unhealthy.length > 0) {
+    log.info(
+      {
+        total: results.length,
+        unhealthy: unhealthy.length,
+        providers: [...new Set(unhealthy.map((r) => r.provider))],
+      },
+      "Credential health check found issues",
+    );
+  } else {
+    log.debug({ total: results.length }, "All credentials healthy");
+  }
+
+  return { checkedAt, results, unhealthy };
+}
+
+/**
+ * Check credential health for a single provider. Returns the health
+ * result for the most recent active connection, or null if no connection
+ * exists.
+ *
+ * Used by the watcher engine for pre-poll gating.
+ */
+export async function checkCredentialForProvider(
+  provider: string,
+): Promise<CredentialHealthResult | null> {
+  let connections;
+  try {
+    connections = listActiveConnectionsByProvider(provider);
+  } catch {
+    return null;
+  }
+  if (connections.length === 0) return null;
+
+  const conn = connections[0]!;
+  const providerRow = getProvider(conn.provider);
+  if (!providerRow) return null;
+
+  return checkConnection({
+    connectionId: conn.id,
+    provider: conn.provider,
+    accountInfo: conn.accountInfo,
+    expiresAt: conn.expiresAt,
+    hasRefreshToken: !!conn.hasRefreshToken,
+    grantedScopesRaw: conn.grantedScopes,
+    defaultScopesRaw: providerRow.defaultScopes,
+    pingUrl: providerRow.pingUrl,
+    pingMethod: providerRow.pingMethod,
+    pingHeaders: providerRow.pingHeaders,
+    pingBody: providerRow.pingBody,
+  });
+}

package/src/daemon/__tests__/conversation-lifecycle-auto-analyze.test.ts

@@ -0,0 +1,324 @@
+/**
+ * Unit tests for the auto-analysis enqueue branch in `disposeConversation()`.
+ *
+ * `disposeConversation` fires two end-of-conversation enqueues for guardian
+ * conversations: the existing `graph_extract` job (memory extraction) and the
+ * new `conversation_analyze` job (auto-analysis loop, gated by the
+ * `auto-analyze` feature flag and source-type guard).
+ *
+ * We stub the downstream enqueue helpers and the side-effecting lifecycle
+ * deps (hook manager, notifier/skill cleanup, browser-screencast) so the test
+ * can invoke `disposeConversation` with a minimal `DisposeContext` and assert
+ * on the enqueue bookkeeping alone.
+ *
+ * Two recursion guards apply when the source conversation is itself an
+ * auto-analysis conversation:
+ *   1. `enqueueAutoAnalysisIfEnabled` short-circuits internally,
+ *      preventing the analyzer from analyzing its own output.
+ *   2. `disposeConversation` skips `graph_extract` directly via
+ *      `isAutoAnalysisConversation()`, mirroring the guard the indexer
+ *      applies on the per-message path. The analysis agent writes memory
+ *      directly via tools, so extracting its reflective musings would
+ *      double-write the graph.
+ * We stub both the helper and the guard so the test can simulate "flag
+ * enabled / flag disabled / source is auto-analysis" states.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+// ---------------------------------------------------------------------------
+// Mock state — reset between tests.
+// ---------------------------------------------------------------------------
+
+const memoryJobCalls: Array<{
+  type: string;
+  payload: Record<string, unknown>;
+}> = [];
+const autoAnalyzeCalls: Array<{
+  conversationId: string;
+  trigger: "batch" | "idle" | "lifecycle";
+}> = [];
+
+// Simulates the helper's "flag off / recursion guard" behavior by no-op-ing
+// when `autoAnalyzeEnabled` is false. When true, we record the call so the
+// test can assert the trigger and conversation id.
+let autoAnalyzeEnabled = true;
+
+// Tracks whether the conversation under test should be treated as an
+// auto-analysis source by `isAutoAnalysisConversation`. When true,
+// `disposeConversation` must skip the `graph_extract` enqueue.
+const autoAnalysisConversations = new Set<string>();
+
+mock.module("../../memory/auto-analysis-guard.js", () => ({
+  AUTO_ANALYSIS_SOURCE: "auto-analysis",
+  isAutoAnalysisConversation: (conversationId: string) =>
+    autoAnalysisConversations.has(conversationId),
+}));
+
+const realJobsStore = await import("../../memory/jobs-store.js");
+mock.module("../../memory/jobs-store.js", () => ({
+  ...realJobsStore,
+  enqueueMemoryJob: (type: string, payload: Record<string, unknown>) => {
+    memoryJobCalls.push({ type, payload });
+    return "job-id";
+  },
+}));
+
+mock.module("../../memory/auto-analysis-enqueue.js", () => ({
+  enqueueAutoAnalysisIfEnabled: (args: {
+    conversationId: string;
+    trigger: "batch" | "idle" | "lifecycle";
+  }) => {
+    if (!autoAnalyzeEnabled) return;
+    autoAnalyzeCalls.push(args);
+  },
+}));
+
+// Stub all side-effecting cleanup helpers that disposeConversation chains
+// into after the enqueue block. We assert on enqueue behavior only.
+mock.module("../../hooks/manager.js", () => ({
+  getHookManager: () => ({
+    trigger: () => undefined,
+  }),
+}));
+
+mock.module("../../tools/browser/browser-screencast.js", () => ({
+  unregisterConversationSender: () => {},
+}));
+
+mock.module("../conversation-notifiers.js", () => ({
+  unregisterCallNotifiers: () => {},
+  unregisterWatchNotifiers: () => {},
+}));
+
+mock.module("../conversation-skill-tools.js", () => ({
+  resetSkillToolProjection: () => {},
+}));
+
+// Dynamic import after mock.module calls so stubs take effect.
+const { disposeConversation } = await import("../conversation-lifecycle.js");
+type DisposeContext = import("../conversation-lifecycle.js").DisposeContext;
+type TrustClass =
+  import("../../runtime/actor-trust-resolver.js").TrustClass;
+
+// ---------------------------------------------------------------------------
+// Fixture builder — minimal DisposeContext satisfying the interface shape.
+// ---------------------------------------------------------------------------
+
+function makeDisposeContext(
+  overrides: {
+    conversationId?: string;
+    trustClass?: TrustClass;
+  } = {},
+): DisposeContext {
+  const eventBus = { dispose: () => {} };
+  const profiler = { clear: () => {} };
+  const abortController = { abort: () => {} };
+  const queue = {
+    clear: () => {},
+    [Symbol.iterator]: function* () {
+      // empty queue — no queued messages to cancel during disposal.
+    },
+  };
+  const prompter = { dispose: () => {} };
+  const secretPrompter = { dispose: () => {} };
+
+  const ctx = {
+    conversationId: overrides.conversationId ?? "conv-1",
+    processing: false,
+    abortController,
+    prompter,
+    secretPrompter,
+    pendingSurfaceActions: new Map(),
+    surfaceActionRequestIds: new Set<string>(),
+    surfaceState: new Map(),
+    accumulatedSurfaceState: new Map(),
+    queue,
+    eventBus,
+    skillProjectionState: new Map<string, string>(),
+    profiler,
+    messages: [],
+    surfaceUndoStacks: new Map<string, string[]>(),
+    currentTurnSurfaces: [] as Array<unknown>,
+    lastSurfaceAction: new Map<string, unknown>(),
+    workspaceTopLevelContext: null,
+    ...(overrides.trustClass
+      ? { trustContext: { trustClass: overrides.trustClass } }
+      : {}),
+    abort(): void {},
+  };
+
+  return ctx as unknown as DisposeContext;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("disposeConversation — auto-analysis enqueue", () => {
+  beforeEach(() => {
+    memoryJobCalls.length = 0;
+    autoAnalyzeCalls.length = 0;
+    autoAnalyzeEnabled = true;
+    autoAnalysisConversations.clear();
+  });
+
+  test("guardian conversation with auto-analyze ON — enqueues both graph_extract and conversation_analyze (via helper)", () => {
+    autoAnalyzeEnabled = true;
+    const ctx = makeDisposeContext({
+      conversationId: "conv-guardian",
+      trustClass: "guardian",
+    });
+
+    disposeConversation(ctx);
+
+    // graph_extract fires unchanged.
+    expect(memoryJobCalls).toHaveLength(1);
+    expect(memoryJobCalls[0]!.type).toBe("graph_extract");
+    expect(memoryJobCalls[0]!.payload).toMatchObject({
+      conversationId: "conv-guardian",
+    });
+
+    // Auto-analysis helper is invoked with trigger "lifecycle".
+    expect(autoAnalyzeCalls).toHaveLength(1);
+    expect(autoAnalyzeCalls[0]).toEqual({
+      conversationId: "conv-guardian",
+      trigger: "lifecycle",
+    });
+  });
+
+  test("untrusted conversation — enqueues neither graph_extract nor conversation_analyze", () => {
+    // `unknown` is the trust class used for untrusted actors. The disposal
+    // code short-circuits on `isUntrustedTrustClass()` so neither enqueue
+    // path should fire. This preserves the memory trust boundary.
+    const ctx = makeDisposeContext({
+      conversationId: "conv-untrusted",
+      trustClass: "unknown",
+    });
+
+    disposeConversation(ctx);
+
+    expect(memoryJobCalls).toHaveLength(0);
+    expect(autoAnalyzeCalls).toHaveLength(0);
+  });
+
+  test("auto-analysis conversation — neither graph_extract nor conversation_analyze is enqueued", () => {
+    // Two recursion guards apply when the source conversation is itself an
+    // auto-analysis conversation:
+    //   1. `disposeConversation` skips the `graph_extract` enqueue directly
+    //      via `isAutoAnalysisConversation()` — mirroring the indexer's
+    //      per-message guard. Without this, evicting an auto-analysis
+    //      conversation from the LRU would double-write the memory graph
+    //      because the analysis agent already writes memory via tools.
+    //   2. `enqueueAutoAnalysisIfEnabled` no-ops internally for
+    //      auto-analysis conversations (its own recursion guard). We
+    //      simulate that by flipping `autoAnalyzeEnabled` off.
+    autoAnalysisConversations.add("conv-auto");
+    autoAnalyzeEnabled = false;
+    const ctx = makeDisposeContext({
+      conversationId: "conv-auto",
+      trustClass: "guardian",
+    });
+
+    disposeConversation(ctx);
+
+    expect(memoryJobCalls).toHaveLength(0);
+    expect(autoAnalyzeCalls).toHaveLength(0);
+  });
+
+  test("auto-analyze flag OFF — helper no-ops, so only graph_extract is enqueued", () => {
+    // When the `auto-analyze` feature flag is disabled, the helper returns
+    // early without enqueuing. We simulate that by flipping the shared flag.
+    autoAnalyzeEnabled = false;
+    const ctx = makeDisposeContext({
+      conversationId: "conv-flag-off",
+      trustClass: "guardian",
+    });
+
+    disposeConversation(ctx);
+
+    expect(memoryJobCalls).toHaveLength(1);
+    expect(memoryJobCalls[0]!.type).toBe("graph_extract");
+    expect(autoAnalyzeCalls).toHaveLength(0);
+  });
+
+  test("isAutoAnalysisConversation throws — fails open, still enqueues graph_extract and continues disposal", () => {
+    // If the DB read inside `isAutoAnalysisConversation` throws (e.g. SQLite
+    // unavailable during teardown), disposal must not abort. We fail open:
+    // default to NOT skipping, so graph_extract still fires and the rest of
+    // the cleanup chain runs.
+    autoAnalyzeEnabled = true;
+
+    mock.module("../../memory/auto-analysis-guard.js", () => ({
+      AUTO_ANALYSIS_SOURCE: "auto-analysis",
+      isAutoAnalysisConversation: () => {
+        throw new Error("db closed");
+      },
+    }));
+
+    const ctx = makeDisposeContext({
+      conversationId: "conv-guard-throws",
+      trustClass: "guardian",
+    });
+
+    expect(() => disposeConversation(ctx)).not.toThrow();
+
+    // Fail-open: graph_extract fires even though the guard threw.
+    expect(memoryJobCalls).toHaveLength(1);
+    expect(memoryJobCalls[0]!.type).toBe("graph_extract");
+    // The auto-analyze helper also still runs (separate try/catch).
+    expect(autoAnalyzeCalls).toHaveLength(1);
+
+    // Restore the non-throwing stub for subsequent tests.
+    mock.module("../../memory/auto-analysis-guard.js", () => ({
+      AUTO_ANALYSIS_SOURCE: "auto-analysis",
+      isAutoAnalysisConversation: (conversationId: string) =>
+        autoAnalysisConversations.has(conversationId),
+    }));
+  });
+
+  test("helper throws — disposal continues (best-effort semantics)", () => {
+    // The try/catch around `enqueueAutoAnalysisIfEnabled` must swallow
+    // errors so a broken helper never blocks disposal. We verify by
+    // swapping in a throwing stub for a single call and confirming
+    // disposeConversation itself does not throw.
+    const originalEnabled = autoAnalyzeEnabled;
+    autoAnalyzeEnabled = true;
+
+    // Temporarily re-mock the helper to throw.
+    mock.module("../../memory/auto-analysis-enqueue.js", () => ({
+      enqueueAutoAnalysisIfEnabled: () => {
+        throw new Error("boom");
+      },
+    }));
+
+    const ctx = makeDisposeContext({
+      conversationId: "conv-throw",
+      trustClass: "guardian",
+    });
+
+    expect(() => disposeConversation(ctx)).not.toThrow();
+
+    // graph_extract still fired before the throw.
+    expect(memoryJobCalls).toHaveLength(1);
+
+    // Restore the non-throwing stub so other tests aren't affected.
+    mock.module("../../memory/auto-analysis-enqueue.js", () => ({
+      enqueueAutoAnalysisIfEnabled: (args: {
+        conversationId: string;
+        trigger: "batch" | "idle" | "lifecycle";
+      }) => {
+        if (!autoAnalyzeEnabled) return;
+        autoAnalyzeCalls.push(args);
+      },
+    }));
+    autoAnalyzeEnabled = originalEnabled;
+  });
+});