@vellumai/assistant 0.3.5 → 0.3.6

package/src/watcher/provider-types.ts

@@ -34,15 +34,35 @@ export interface WatcherProvider {
   /**
    * Fetch new events since the given watermark.
    * Returns new items and an updated watermark.
+   *
+   * `watcherKey` is the unique watcher instance ID (e.g. the DB row UUID).
+   * Providers that maintain per-watcher in-process state (like the Linear
+   * issue-state cache) must key that state by `watcherKey` — not just
+   * `credentialService` — so that multiple watchers sharing the same
+   * credential maintain independent baselines.
    */
   fetchNew(
     credentialService: string,
     watermark: string | null,
     config: Record<string, unknown>,
+    watcherKey: string,
   ): Promise<FetchResult>;
 
   /**
    * Get the initial watermark (start from "now" so we don't replay history).
    */
   getInitialWatermark(credentialService: string): Promise<string>;
+
+  /**
+   * Release any in-process state held for a watcher instance.
+   * Called only when a watcher is truly deleted so that providers with
+   * per-watcher caches (e.g. the Linear issue-state map) can evict the
+   * stale entry and prevent unbounded memory growth.
+   *
+   * Must NOT be called on circuit-breaker auto-disable — that path is
+   * reversible, and clearing state would cause missed events on re-enable.
+   *
+   * Optional — providers with no per-watcher state need not implement this.
+   */
+  cleanup?(watcherKey: string): void;
 }

package/src/watcher/providers/github.ts

@@ -0,0 +1,156 @@
+/**
+ * GitHub watcher provider — polls for new PRs, issues, and review requests.
+ *
+ * Uses the GitHub Notifications API (`GET /notifications`) with a timestamp
+ * watermark. On first poll, captures the current time as the watermark so we
+ * start from "now" and don't replay historical notifications.
+ *
+ * The credential service expects a GitHub Personal Access Token (or fine-grained
+ * token) stored under `integration:github`. The token needs at minimum the
+ * `notifications` scope (classic) or Notification read permission (fine-grained).
+ */
+
+import { withValidToken } from '../../security/token-manager.js';
+import { truncate } from '../../util/truncate.js';
+import type { WatcherProvider, WatcherItem, FetchResult } from '../provider-types.js';
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('watcher:github');
+
+const GITHUB_API_BASE = 'https://api.github.com';
+
+// ── API types ──────────────────────────────────────────────────────────────────
+
+interface GitHubNotification {
+  id: string;
+  reason: string; // 'assign', 'author', 'comment', 'mention', 'review_requested', 'subscribed', etc.
+  unread: boolean;
+  updated_at: string;
+  subject: {
+    title: string;
+    url: string | null;
+    latest_comment_url: string | null;
+    type: 'Issue' | 'PullRequest' | 'Release' | 'Commit' | string;
+  };
+  repository: {
+    full_name: string;
+    html_url: string;
+  };
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+/** Map a GitHub notification reason to a watcher event type. */
+function reasonToEventType(reason: string, subjectType: string): string {
+  if (reason === 'review_requested') return 'github_review_requested';
+  if (reason === 'assign') return subjectType === 'Issue' ? 'github_issue_assigned' : 'github_pr_assigned';
+  if (reason === 'mention') return 'github_mention';
+  if (subjectType === 'PullRequest') return 'github_pr_activity';
+  return 'github_notification';
+}
+
+function notificationToItem(n: GitHubNotification): WatcherItem {
+  const eventType = reasonToEventType(n.reason, n.subject.type);
+  const repoName = n.repository.full_name;
+  const title = n.subject.title;
+  const subjectType = n.subject.type;
+
+  return {
+    externalId: n.id,
+    eventType,
+    summary: `GitHub ${subjectType} in ${repoName}: ${truncate(title, 80)}`,
+    payload: {
+      id: n.id,
+      reason: n.reason,
+      subjectType: n.subject.type,
+      title,
+      subjectUrl: n.subject.url,
+      repoFullName: repoName,
+      repoHtmlUrl: n.repository.html_url,
+      updatedAt: n.updated_at,
+    },
+    timestamp: new Date(n.updated_at).getTime(),
+  };
+}
+
+/** Fetch a single page of notifications since a timestamp. */
+async function fetchNotificationsPage(
+  token: string,
+  since: string,
+  page: number,
+): Promise<{ items: GitHubNotification[]; hasMore: boolean }> {
+  const params = new URLSearchParams({
+    all: 'false', // only unread
+    since,
+    per_page: '50',
+    page: String(page),
+  });
+
+  const resp = await fetch(`${GITHUB_API_BASE}/notifications?${params}`, {
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: 'application/vnd.github+json',
+      'X-GitHub-Api-Version': '2022-11-28',
+    },
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => '');
+    throw new Error(`GitHub Notifications API ${resp.status}: ${body}`);
+  }
+
+  const items = (await resp.json()) as GitHubNotification[];
+  // GitHub returns 50 per page; if we got a full page there may be more
+  const hasMore = items.length === 50;
+  return { items, hasMore };
+}
+
+// ── Provider ───────────────────────────────────────────────────────────────────
+
+export const githubProvider: WatcherProvider = {
+  id: 'github',
+  displayName: 'GitHub',
+  requiredCredentialService: 'integration:github',
+
+  async getInitialWatermark(_credentialService: string): Promise<string> {
+    // Start from "now" so we don't replay all existing notifications
+    return new Date().toISOString();
+  },
+
+  async fetchNew(
+    credentialService: string,
+    watermark: string | null,
+    _config: Record<string, unknown>,
+    _watcherKey: string,
+  ): Promise<FetchResult> {
+    return withValidToken(credentialService, async (token) => {
+      const since = watermark ?? new Date().toISOString();
+      const items: WatcherItem[] = [];
+      let page = 1;
+
+      while (true) {
+        const { items: pageItems, hasMore } = await fetchNotificationsPage(token, since, page);
+
+        for (const n of pageItems) {
+          // Only surface notifications for reasons that warrant attention
+          const relevantReasons = new Set([
+            'assign', 'mention', 'review_requested', 'team_mention',
+          ]);
+          if (!relevantReasons.has(n.reason)) continue;
+
+          items.push(notificationToItem(n));
+        }
+
+        if (!hasMore) break;
+        page++;
+      }
+
+      // New watermark: the time just before we fetched so we don't miss events
+      // that arrive between poll cycles.
+      const newWatermark = new Date().toISOString();
+
+      log.info({ count: items.length, watermark: newWatermark }, 'GitHub: fetched new notifications');
+      return { items, watermark: newWatermark };
+    });
+  },
+};

package/src/watcher/providers/gmail.ts

@@ -113,6 +113,7 @@ export const gmailProvider: WatcherProvider = {
     credentialService: string,
     watermark: string | null,
     _config: Record<string, unknown>,
+    _watcherKey: string,
   ): Promise<FetchResult> {
     return withValidToken(credentialService, async (token) => {
       if (!watermark) {

package/src/watcher/providers/google-calendar.ts

@@ -139,6 +139,7 @@ export const googleCalendarProvider: WatcherProvider = {
     credentialService: string,
     watermark: string | null,
     _config: Record<string, unknown>,
+    _watcherKey: string,
   ): Promise<FetchResult> {
     return withValidToken(credentialService, async (token) => {
       if (!watermark) {

package/src/watcher/providers/linear.ts

@@ -0,0 +1,460 @@
+/**
+ * Linear watcher provider — polls for assigned issues, status changes, and @mentions.
+ *
+ * Uses the Linear GraphQL API with a timestamp watermark. On first poll, captures
+ * the current time as the watermark so we start from "now" and don't replay history.
+ *
+ * The watermark is an ISO 8601 timestamp string used in the `updatedAt_gte` filter.
+ * We query notifications (which cover assignments and mentions) and issue status changes
+ * for issues assigned to the authenticated user.
+ *
+ * The credential service expects a Linear API key (personal or OAuth access token)
+ * stored under `integration:linear`. The token only needs read access to notifications
+ * and issues.
+ */
+
+import { withValidToken } from '../../security/token-manager.js';
+import { truncate } from '../../util/truncate.js';
+import type { WatcherProvider, WatcherItem, FetchResult } from '../provider-types.js';
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('watcher:linear');
+
+const LINEAR_GRAPHQL_URL = 'https://api.linear.app/graphql';
+
+// ── GraphQL response types ────────────────────────────────────────────────────
+
+interface LinearNotification {
+  id: string;
+  type: string;
+  createdAt: string;
+  updatedAt: string;
+  issue?: {
+    id: string;
+    identifier: string;
+    title: string;
+    url: string;
+    state?: {
+      id: string;
+      name: string;
+      type: string;
+    };
+    assignee?: {
+      id: string;
+      name: string;
+      email: string;
+    };
+    team?: {
+      id: string;
+      name: string;
+    };
+  };
+  comment?: {
+    id: string;
+    body: string;
+  };
+}
+
+interface LinearIssue {
+  id: string;
+  identifier: string;
+  title: string;
+  url: string;
+  updatedAt: string;
+  state: {
+    id: string;
+    name: string;
+    type: string;
+  };
+  team: {
+    id: string;
+    name: string;
+  };
+  assignee?: {
+    id: string;
+    name: string;
+  };
+}
+
+interface LinearViewer {
+  id: string;
+  name: string;
+  email: string;
+}
+
+// ── GraphQL helpers ───────────────────────────────────────────────────────────
+
+async function graphql<T>(token: string, query: string, variables?: Record<string, unknown>): Promise<T> {
+  const resp = await fetch(LINEAR_GRAPHQL_URL, {
+    method: 'POST',
+    headers: {
+      // Linear accepts both personal API keys and OAuth tokens; the Bearer scheme
+      // is required for all token types per Linear's API docs.
+      'Authorization': `Bearer ${token}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ query, variables }),
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => '');
+    throw new Error(`Linear API ${resp.status}: ${body}`);
+  }
+
+  const result = await resp.json() as { data?: T; errors?: Array<{ message: string }> };
+
+  if (result.errors?.length) {
+    throw new Error(`Linear GraphQL errors: ${result.errors.map((e) => e.message).join(', ')}`);
+  }
+
+  if (!result.data) {
+    throw new Error('Linear API returned no data');
+  }
+
+  return result.data;
+}
+
+/** Fetch the authenticated user's ID and name. */
+async function fetchViewer(token: string): Promise<LinearViewer> {
+  const data = await graphql<{ viewer: LinearViewer }>(token, `
+    query {
+      viewer {
+        id
+        name
+        email
+      }
+    }
+  `);
+  return data.viewer;
+}
+
+/**
+ * Fetch all notifications since a given ISO timestamp, paginating until
+ * `pageInfo.hasNextPage` is false so we never miss events when 50+ arrive
+ * between polls.
+ */
+async function fetchNotifications(
+  token: string,
+  since: string,
+): Promise<LinearNotification[]> {
+  const allNodes: LinearNotification[] = [];
+  let cursor: string | null = null;
+
+  type NotificationsResponse = {
+    notifications: { nodes: LinearNotification[]; pageInfo: { hasNextPage: boolean; endCursor: string } };
+  };
+
+  do {
+    const data: NotificationsResponse = await graphql<NotificationsResponse>(token, `
+      query FetchNotifications($after: DateTime, $cursor: String) {
+        notifications(
+          filter: { updatedAt: { gte: $after } }
+          orderBy: updatedAt
+          first: 50
+          after: $cursor
+        ) {
+          nodes {
+            id
+            type
+            createdAt
+            updatedAt
+            ... on IssueNotification {
+              issue {
+                id
+                identifier
+                title
+                url
+                state {
+                  id
+                  name
+                  type
+                }
+                assignee {
+                  id
+                  name
+                  email
+                }
+                team {
+                  id
+                  name
+                }
+              }
+            }
+            ... on IssueCommentMentionNotification {
+              issue {
+                id
+                identifier
+                title
+                url
+                team {
+                  id
+                  name
+                }
+              }
+              comment {
+                id
+                body
+              }
+            }
+          }
+          pageInfo {
+            hasNextPage
+            endCursor
+          }
+        }
+      }
+    `, { after: since, cursor });
+
+    allNodes.push(...data.notifications.nodes);
+    cursor = data.notifications.pageInfo.hasNextPage ? data.notifications.pageInfo.endCursor : null;
+  } while (cursor != null);
+
+  return allNodes;
+}
+
+/**
+ * Fetch all assigned issues updated since the watermark, paginating until
+ * `pageInfo.hasNextPage` is false so updates beyond the first 50 aren't skipped.
+ */
+async function fetchAssignedIssueUpdates(
+  token: string,
+  viewerId: string,
+  since: string,
+): Promise<LinearIssue[]> {
+  const allNodes: LinearIssue[] = [];
+  let cursor: string | null = null;
+
+  type IssuesResponse = {
+    issues: { nodes: LinearIssue[]; pageInfo: { hasNextPage: boolean; endCursor: string } };
+  };
+
+  do {
+    const data: IssuesResponse = await graphql<IssuesResponse>(token, `
+      query FetchAssignedIssues($assigneeId: ID, $after: DateTime, $cursor: String) {
+        issues(
+          filter: {
+            assignee: { id: { eq: $assigneeId } }
+            updatedAt: { gte: $after }
+          }
+          orderBy: updatedAt
+          first: 50
+          after: $cursor
+        ) {
+          nodes {
+            id
+            identifier
+            title
+            url
+            updatedAt
+            state {
+              id
+              name
+              type
+            }
+            team {
+              id
+              name
+            }
+            assignee {
+              id
+              name
+            }
+          }
+          pageInfo {
+            hasNextPage
+            endCursor
+          }
+        }
+      }
+    `, { assigneeId: viewerId, after: since, cursor });
+
+    allNodes.push(...data.issues.nodes);
+    cursor = data.issues.pageInfo.hasNextPage ? data.issues.pageInfo.endCursor : null;
+  } while (cursor != null);
+
+  return allNodes;
+}
+
+// ── Issue state tracking ──────────────────────────────────────────────────────
+
+/**
+ * Tracks the last known state ID per issue, scoped by watcher instance key
+ * (the watcher's DB UUID) so that multiple Linear watchers in the same process
+ * — even when they share the same `credentialService` string — maintain
+ * completely independent baselines.
+ *
+ * Keying by `credentialService` alone is insufficient: `runWatchersOnce` polls
+ * watchers sequentially, so watcher-1 would write its post-poll state into the
+ * shared map, and watcher-2 would then see already-updated IDs and silently
+ * skip emitting valid transitions. Outer key: watcherKey; inner key: issue ID.
+ *
+ * In-memory only; resets on daemon restart, which is acceptable — the first
+ * poll after restart will seed the map without emitting false-positive events.
+ */
+const knownIssueStateIdsByWatcher = new Map<string, Map<string, string>>();
+
+/** Get (or lazily create) the per-watcher state map. */
+function getStateCache(watcherKey: string): Map<string, string> {
+  let cache = knownIssueStateIdsByWatcher.get(watcherKey);
+  if (!cache) {
+    cache = new Map<string, string>();
+    knownIssueStateIdsByWatcher.set(watcherKey, cache);
+  }
+  return cache;
+}
+
+/**
+ * Evict the state cache for a watcher that has been deleted or permanently
+ * disabled. Prevents unbounded growth of `knownIssueStateIdsByWatcher` in
+ * environments that create and delete watchers frequently (watcher churn).
+ */
+export function clearLinearStateCache(watcherKey: string): void {
+  knownIssueStateIdsByWatcher.delete(watcherKey);
+}
+
+// ── Event type mapping ────────────────────────────────────────────────────────
+
+/**
+ * Map a Linear notification type to a watcher event type.
+ * Linear notification types include: issueAssignedToYou, issueMentionedYou,
+ * issueCommentMentionedYou, issueStatusChanged, etc.
+ */
+function notificationTypeToEventType(type: string): string {
+  if (type === 'issueAssignedToYou') return 'linear_issue_assigned';
+  if (type === 'issueMentionedYou') return 'linear_mention';
+  if (type === 'issueCommentMentionedYou') return 'linear_comment_mention';
+  if (type === 'issueStatusChanged') return 'linear_status_changed';
+  return 'linear_notification';
+}
+
+function notificationToItem(n: LinearNotification): WatcherItem {
+  const eventType = notificationTypeToEventType(n.type);
+  const issue = n.issue;
+  const teamName = issue?.team?.name ?? 'Unknown Team';
+  const issueRef = issue ? `${issue.identifier}: ${truncate(issue.title, 60)}` : 'Unknown issue';
+
+  const summary = eventType === 'linear_comment_mention' && n.comment
+    ? `Linear @mention in ${teamName} / ${issueRef}: ${truncate(n.comment.body, 80)}`
+    : `Linear ${n.type.replace(/([A-Z])/g, ' $1').trim()} in ${teamName} / ${issueRef}`;
+
+  return {
+    externalId: n.id,
+    eventType,
+    summary,
+    payload: {
+      notificationId: n.id,
+      type: n.type,
+      issueId: issue?.id,
+      issueIdentifier: issue?.identifier,
+      issueTitle: issue?.title,
+      issueUrl: issue?.url,
+      issueStateName: issue?.state?.name,
+      issueStateType: issue?.state?.type,
+      teamName,
+      commentBody: n.comment?.body,
+      updatedAt: n.updatedAt,
+    },
+    timestamp: new Date(n.updatedAt).getTime(),
+  };
+}
+
+function issueToStatusChangeItem(issue: LinearIssue, previousStateId: string): WatcherItem {
+  // Composite key encodes both the old and new state so re-polling the same
+  // transition doesn't generate a duplicate event via the dedup layer.
+  const externalId = `status_change:${issue.id}:${previousStateId}→${issue.state.id}`;
+  const teamName = issue.team?.name ?? 'Unknown Team';
+
+  return {
+    externalId,
+    eventType: 'linear_status_changed',
+    summary: `Linear status → ${issue.state.name} in ${teamName} / ${issue.identifier}: ${truncate(issue.title, 60)}`,
+    payload: {
+      issueId: issue.id,
+      issueIdentifier: issue.identifier,
+      issueTitle: issue.title,
+      issueUrl: issue.url,
+      stateName: issue.state.name,
+      stateType: issue.state.type,
+      teamName,
+      updatedAt: issue.updatedAt,
+    },
+    timestamp: new Date(issue.updatedAt).getTime(),
+  };
+}
+
+// ── Provider ──────────────────────────────────────────────────────────────────
+
+export const linearProvider: WatcherProvider = {
+  id: 'linear',
+  displayName: 'Linear',
+  requiredCredentialService: 'integration:linear',
+
+  async getInitialWatermark(_credentialService: string): Promise<string> {
+    // Start from "now" so we don't replay all existing notifications
+    return new Date().toISOString();
+  },
+
+  cleanup(watcherKey: string): void {
+    clearLinearStateCache(watcherKey);
+  },
+
+  async fetchNew(
+    credentialService: string,
+    watermark: string | null,
+    _config: Record<string, unknown>,
+    watcherKey: string,
+  ): Promise<FetchResult> {
+    return withValidToken(credentialService, async (token) => {
+      const since = watermark ?? new Date().toISOString();
+
+      // Resolve the authenticated viewer's ID once per poll for the assigned-issues query
+      const viewer = await fetchViewer(token);
+
+      // Fetch notifications (assignments, mentions, status changes via notification feed)
+      const notifications = await fetchNotifications(token, since);
+
+      // Only surface notification types that warrant attention
+      const relevantTypes = new Set([
+        'issueAssignedToYou',
+        'issueMentionedYou',
+        'issueCommentMentionedYou',
+        'issueStatusChanged',
+      ]);
+
+      const items: WatcherItem[] = [];
+
+      for (const n of notifications) {
+        if (!relevantTypes.has(n.type)) continue;
+        items.push(notificationToItem(n));
+      }
+
+      // Also poll assigned issues directly for status changes not covered by
+      // notifications (e.g., bulk team updates). We only emit an event when the
+      // state ID differs from what we recorded on the previous poll — any other
+      // field update (title, description, etc.) does not constitute a status change.
+      // On first sight of an issue we seed the map without emitting, so we don't
+      // fire false-positive events after a daemon restart.
+      const assignedIssues = await fetchAssignedIssueUpdates(token, viewer.id, since);
+      // Scope the state cache by watcherKey (the watcher's DB UUID) rather than
+      // credentialService so that multiple Linear watchers sharing the same credential
+      // maintain independent baselines and cannot clobber each other's state.
+      const stateCache = getStateCache(watcherKey);
+      for (const issue of assignedIssues) {
+        const previousStateId = stateCache.get(issue.id);
+        if (previousStateId !== undefined && previousStateId !== issue.state.id) {
+          items.push(issueToStatusChangeItem(issue, previousStateId));
+        }
+        // Always update the map so the next poll has an accurate baseline.
+        stateCache.set(issue.id, issue.state.id);
+      }
+
+      const newWatermark = new Date().toISOString();
+      log.info(
+        { count: items.length, viewer: viewer.name, watermark: newWatermark },
+        'Linear: fetched new notifications',
+      );
+
+      return { items, watermark: newWatermark };
+    });
+  },
+};

package/src/watcher/providers/slack.ts

@@ -49,6 +49,7 @@ export const slackProvider: WatcherProvider = {
     credentialService: string,
     watermark: string | null,
     _config: Record<string, unknown>,
+    _watcherKey: string,
   ): Promise<FetchResult> {
     return withValidToken(credentialService, async (token) => {
       if (!watermark) {

package/src/work-items/work-item-runner.ts

@@ -89,7 +89,7 @@ export function runWorkItemInBackground(workItemId: string): RunWorkItemResult {
 
   // Resolve required tools
   let requiredTools: string[];
-  if (workItem.requiredTools !== null && workItem.requiredTools !== undefined) {
+  if (workItem.requiredTools != null) {
     requiredTools = sanitizeToolList(JSON.parse(workItem.requiredTools));
   } else {
     requiredTools = task.requiredTools

package/src/workspace/git-service.ts

@@ -651,7 +651,7 @@ export class WorkspaceGitService {
       return;
     }
 
-    const state = currentBranch === null ? 'detached HEAD' : `branch '${currentBranch}'`;
+    const state = currentBranch == null ? 'detached HEAD' : `branch '${currentBranch}'`;
     log.warn(
       { workspaceDir: this.workspaceDir, currentBranch },
       `Workspace repo is on ${state}; auto-switching to main`,