@shipfox/api-integration-jira 12.0.0 → 12.1.0

package/src/db/installations.ts

@@ -1,6 +1,6 @@
 import {isUniqueViolation} from '@shipfox/node-drizzle';
 import {pgClient, withPostgresSession} from '@shipfox/node-postgres';
-import {eq, sql} from 'drizzle-orm';
+import {and, asc, eq, lte, sql} from 'drizzle-orm';
 import {
   JiraConnectionAlreadyLinkedError,
   JiraInstallationAlreadyLinkedError,
@@ -11,17 +11,16 @@ import {jiraInstallations, toJiraInstallation} from './schema/installations.js';
 
 export type JiraInstallationLock = <T>(lockKey: string, fn: () => Promise<T>) => Promise<T>;
 
-const JIRA_INSTALLATION_LOCK_RETRY_DELAY_MS = 100;
-const JIRA_INSTALLATION_LOCK_MAX_RETRY_DELAY_MS = 1_000;
-const JIRA_INSTALLATION_LOCK_TIMEOUT_MS = 30_000;
+const JIRA_ADVISORY_LOCK_RETRY_DELAY_MS = 100;
+const JIRA_ADVISORY_LOCK_MAX_RETRY_DELAY_MS = 1_000;
+const JIRA_ADVISORY_LOCK_TIMEOUT_MS = 30_000;
 
-export async function withJiraInstallationLock<T>(lockKey: string, fn: () => Promise<T>) {
-  const advisoryKey = `jira-installation:${lockKey}`;
-  const deadline = Date.now() + JIRA_INSTALLATION_LOCK_TIMEOUT_MS;
-  let retryDelayMs = JIRA_INSTALLATION_LOCK_RETRY_DELAY_MS;
+type JiraAdvisoryLockAttempt<T> = {acquired: true; value: T} | {acquired: false};
 
-  while (true) {
-    const attempt = await withPostgresSession(async (client) => {
+export function withJiraInstallationLock<T>(lockKey: string, fn: () => Promise<T>) {
+  const advisoryKey = `jira-installation:${lockKey}`;
+  return withJiraAdvisoryLockWait(`Jira installation lock: ${lockKey}`, () =>
+    withPostgresSession(async (client) => {
       const lock = await client.query<{acquired: boolean}>(
         'SELECT pg_try_advisory_lock(hashtext($1)) AS acquired',
         [advisoryKey],
@@ -33,15 +32,8 @@ export async function withJiraInstallationLock<T>(lockKey: string, fn: () => Pro
       } finally {
         await client.query('SELECT pg_advisory_unlock(hashtext($1))', [advisoryKey]);
       }
-    });
-
-    if (attempt.acquired) return attempt.value;
-    if (Date.now() >= deadline) {
-      throw new Error(`Timed out waiting for Jira installation lock: ${lockKey}`);
-    }
-    await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
-    retryDelayMs = Math.min(retryDelayMs * 2, JIRA_INSTALLATION_LOCK_MAX_RETRY_DELAY_MS);
-  }
+    }),
+  );
 }
 
 export type JiraInstallationStatus = 'installed' | 'revoked';
@@ -58,6 +50,8 @@ export interface JiraInstallation {
   webhookExpiresAt: Date | null;
   status: JiraInstallationStatus;
   tokenExpiresAt: Date | null;
+  refreshTokenLastUsedAt: Date;
+  refreshTokenLastAttemptedAt: Date;
   createdAt: Date;
   updatedAt: Date;
 }
@@ -73,6 +67,8 @@ export interface UpsertJiraInstallationParams {
   webhookExpiresAt?: Date | null | undefined;
   status: JiraInstallationStatus;
   tokenExpiresAt?: Date | null | undefined;
+  refreshTokenLastUsedAt?: Date | undefined;
+  refreshTokenLastAttemptedAt?: Date | undefined;
 }
 
 export interface UpdateJiraInstallationTokenExpiryParams {
@@ -111,6 +107,8 @@ export async function upsertJiraInstallation(
         webhookExpiresAt: params.webhookExpiresAt ?? null,
         status: params.status,
         tokenExpiresAt: params.tokenExpiresAt ?? null,
+        refreshTokenLastUsedAt: params.refreshTokenLastUsedAt ?? now,
+        refreshTokenLastAttemptedAt: params.refreshTokenLastAttemptedAt ?? now,
       })
       .onConflictDoUpdate({
         target: jiraInstallations.connectionId,
@@ -127,6 +125,8 @@ export async function upsertJiraInstallation(
             : {webhookExpiresAt: params.webhookExpiresAt}),
           status: params.status,
           tokenExpiresAt: params.tokenExpiresAt ?? null,
+          refreshTokenLastUsedAt: params.refreshTokenLastUsedAt ?? now,
+          refreshTokenLastAttemptedAt: params.refreshTokenLastAttemptedAt ?? now,
           updatedAt: now,
         },
       })
@@ -164,18 +164,53 @@ export async function updateJiraInstallationTokenExpiry(
   options: {tx?: unknown} = {},
 ): Promise<JiraInstallation | undefined> {
   const executor = (options.tx ?? db()) as JiraDb | JiraTx;
+  const now = new Date();
   const [row] = await executor
     .update(jiraInstallations)
     .set({
       tokenExpiresAt: params.tokenExpiresAt,
+      refreshTokenLastUsedAt: now,
+      refreshTokenLastAttemptedAt: now,
       ...(params.scopes === undefined ? {} : {scopes: params.scopes}),
-      updatedAt: new Date(),
+      updatedAt: now,
     })
     .where(eq(jiraInstallations.connectionId, params.connectionId))
     .returning();
   return row ? toJiraInstallation(row) : undefined;
 }
 
+export async function markJiraInstallationTokenRefreshAttempt(
+  connectionId: string,
+  options: {tx?: unknown} = {},
+): Promise<JiraInstallation | undefined> {
+  const executor = (options.tx ?? db()) as JiraDb | JiraTx;
+  const [row] = await executor
+    .update(jiraInstallations)
+    .set({refreshTokenLastAttemptedAt: new Date()})
+    .where(eq(jiraInstallations.connectionId, connectionId))
+    .returning();
+  return row ? toJiraInstallation(row) : undefined;
+}
+
+export async function listJiraInstallationsDueForTokenRefresh(
+  params: {before: Date; limit?: number | undefined},
+  options: {tx?: unknown} = {},
+): Promise<JiraInstallation[]> {
+  const executor = (options.tx ?? db()) as JiraDb | JiraTx;
+  const rows = await executor
+    .select()
+    .from(jiraInstallations)
+    .where(
+      and(
+        eq(jiraInstallations.status, 'installed'),
+        lte(jiraInstallations.refreshTokenLastUsedAt, params.before),
+      ),
+    )
+    .orderBy(asc(jiraInstallations.refreshTokenLastAttemptedAt))
+    .limit(params.limit ?? 100);
+  return rows.map(toJiraInstallation);
+}
+
 export async function updateJiraInstallationWebhook(
   params: UpdateJiraInstallationWebhookParams,
   options: {tx?: unknown} = {},
@@ -204,7 +239,7 @@ export async function deleteJiraInstallationByConnectionId(
   return (result.rowCount ?? 0) > 0;
 }
 
-export type JiraRefreshLockResult<T> = {acquired: true; value: T} | {acquired: false};
+export type JiraRefreshLockResult<T> = JiraAdvisoryLockAttempt<T>;
 
 export function withJiraRefreshLock<T>(
   connectionId: string,
@@ -213,6 +248,15 @@ export function withJiraRefreshLock<T>(
   return withJiraRefreshLockClient(connectionId, fn);
 }
 
+export function withJiraRefreshLockAndWait<T>(
+  connectionId: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return withJiraAdvisoryLockWait(`Jira refresh lock: ${connectionId}`, () =>
+    withJiraRefreshLock(connectionId, fn),
+  );
+}
+
 export function withJiraWebhookRegistrationLock<T>(
   lockKey: string,
   fn: (tx?: unknown) => Promise<T>,
@@ -243,6 +287,22 @@ async function withJiraRefreshLockClient<T>(
   }
 }
 
+async function withJiraAdvisoryLockWait<T>(
+  lockDescription: string,
+  attemptLock: () => Promise<JiraAdvisoryLockAttempt<T>>,
+): Promise<T> {
+  const deadline = Date.now() + JIRA_ADVISORY_LOCK_TIMEOUT_MS;
+  let retryDelayMs = JIRA_ADVISORY_LOCK_RETRY_DELAY_MS;
+
+  while (true) {
+    const attempt = await attemptLock();
+    if (attempt.acquired) return attempt.value;
+    if (Date.now() >= deadline) throw new Error(`Timed out waiting for ${lockDescription}`);
+    await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+    retryDelayMs = Math.min(retryDelayMs * 2, JIRA_ADVISORY_LOCK_MAX_RETRY_DELAY_MS);
+  }
+}
+
 export async function getJiraInstallationByConnectionId(
   connectionId: string,
   options: {tx?: unknown} = {},

package/src/db/schema/installations.ts

@@ -1,5 +1,5 @@
 import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
-import {jsonb, text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
+import {index, jsonb, text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
 import type {JiraInstallation} from '#db/installations.js';
 import {pgTable} from './common.js';
 
@@ -17,12 +17,30 @@ export const jiraInstallations = pgTable(
     webhookExpiresAt: timestamp('webhook_expires_at', {withTimezone: true}),
     status: text('status').notNull().$type<JiraInstallation['status']>(),
     tokenExpiresAt: timestamp('token_expires_at', {withTimezone: true}),
+    refreshTokenLastUsedAt: timestamp('refresh_token_last_used_at', {
+      withTimezone: true,
+    })
+      .notNull()
+      .defaultNow(),
+    refreshTokenLastAttemptedAt: timestamp('refresh_token_last_attempted_at', {
+      withTimezone: true,
+    })
+      .notNull()
+      .defaultNow(),
     createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
     updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
   },
   (table) => [
     uniqueIndex('integrations_jira_installations_connection_unique').on(table.connectionId),
     uniqueIndex('integrations_jira_installations_cloud_id_unique').on(table.cloudId),
+    index('integrations_jira_installations_token_refresh_due_idx').on(
+      table.status,
+      table.refreshTokenLastUsedAt,
+    ),
+    index('integrations_jira_installations_token_refresh_attempt_idx').on(
+      table.status,
+      table.refreshTokenLastAttemptedAt,
+    ),
   ],
 );
 
@@ -42,6 +60,8 @@ export function toJiraInstallation(row: JiraInstallationDb): JiraInstallation {
     webhookExpiresAt: row.webhookExpiresAt,
     status: row.status,
     tokenExpiresAt: row.tokenExpiresAt,
+    refreshTokenLastUsedAt: row.refreshTokenLastUsedAt,
+    refreshTokenLastAttemptedAt: row.refreshTokenLastAttemptedAt,
     createdAt: row.createdAt,
     updatedAt: row.updatedAt,
   };

package/src/index.test.ts

@@ -1,4 +1,6 @@
+import {createOutboxRegistry} from '@shipfox/node-module';
 import {createJiraIntegrationProvider} from '#index.js';
+import {createJiraMaintenanceWorker} from '#temporal/worker.js';
 
 describe('createJiraIntegrationProvider', () => {
   it('creates the Jira provider', () => {
@@ -12,6 +14,16 @@ describe('createJiraIntegrationProvider', () => {
     });
   });
 
+  it('mounts the in-process agent-tools adapter and advertises its capability', () => {
+    const getAccessToken = vi.fn().mockResolvedValue('access-token');
+    const provider = createJiraIntegrationProvider({
+      agentTools: {tokenStore: {getAccessToken}},
+    });
+
+    expect(provider.adapters.agent_tools).toBeDefined();
+    expect(provider.routes).toEqual([]);
+  });
+
   it('rejects incomplete receiver wiring instead of mounting registration without a receiver', () => {
     expect(() =>
       createJiraIntegrationProvider({
@@ -20,3 +32,25 @@ describe('createJiraIntegrationProvider', () => {
     ).toThrow('requires all webhook receiver dependencies');
   });
 });
+
+describe('createJiraMaintenanceWorker', () => {
+  it('describes the Jira proactive token refresh worker', () => {
+    const worker = createJiraMaintenanceWorker({
+      tokenStore: {getAccessToken: vi.fn()},
+      resolveConnection: vi.fn(),
+    });
+
+    expect(worker.taskQueue).toBe('integrations-jira-maintenance');
+    expect(worker.workflowsPath.endsWith('dist/temporal/workflows/index.js')).toBe(true);
+    expect(Object.keys(worker.activities({outboxRegistry: createOutboxRegistry()}))).toContain(
+      'refreshJiraTokensActivity',
+    );
+    expect(worker.workflows).toEqual([
+      {
+        name: 'refreshJiraTokensCron',
+        id: 'jira-refresh-tokens',
+        cronSchedule: '0 */6 * * *',
+      },
+    ]);
+  });
+});

package/src/index.ts

@@ -1,6 +1,13 @@
 import {JIRA_PROVIDER} from '@shipfox/api-integration-jira-dto';
-import {createJiraApiClient, type JiraApiClient} from '#api/client.js';
+import {
+  createJiraAgentToolsClient,
+  createJiraApiClient,
+  type JiraAgentToolsClient,
+  type JiraApiClient,
+} from '#api/client.js';
 import {config} from '#config.js';
+import {JiraAgentToolsProvider} from '#core/agent-tools-provider.js';
+import type {JiraTokenStore} from '#core/tokens.js';
 import {createJiraWebhookProcessor} from '#core/webhook-processor.js';
 import {registerJiraWebhook} from '#core/webhook-registration.js';
 import {closeDb, db} from '#db/db.js';
@@ -21,17 +28,38 @@ const TRAILING_SLASHES_RE = /\/+$/;
 export type {JiraProvider} from '@shipfox/api-integration-jira-dto';
 export type {
   JiraAccessibleResource,
+  JiraAgentToolHttpMethod,
+  JiraAgentToolQueryValue,
+  JiraAgentToolRequest,
+  JiraAgentToolResponse,
+  JiraAgentToolsClient,
   JiraApiClient,
   JiraAuthorization,
   JiraDynamicWebhookRegistration,
   JiraIdentity,
 } from '#api/client.js';
 export {
+  createJiraAgentToolsClient,
   createJiraApiClient,
   JIRA_DYNAMIC_WEBHOOK_EVENTS,
   JIRA_DYNAMIC_WEBHOOK_JQL,
   mapJiraError,
 } from '#api/client.js';
+export type {
+  JiraAgentToolCatalogEntry,
+  JiraAgentToolId,
+  JiraAgentToolRequiredScope,
+} from '#core/agent-tools.js';
+export {
+  jiraAgentToolCatalog,
+  jiraAgentToolSelectionCatalog,
+  jiraPlainTextToAdf,
+} from '#core/agent-tools.js';
+export type {
+  JiraAgentToolsProviderOptions,
+  JiraToolCallResult,
+} from '#core/agent-tools-provider.js';
+export {JiraAgentToolsProvider} from '#core/agent-tools-provider.js';
 export type {DisconnectJiraInstallationParams} from '#core/disconnect.js';
 export {disconnectJiraInstallation} from '#core/disconnect.js';
 export {
@@ -92,6 +120,7 @@ export {
   getJiraInstallationByCloudId,
   getJiraInstallationByConnectionId,
   getJiraInstallationByWebhookId,
+  listJiraInstallationsDueForTokenRefresh,
   markJiraInstallationRevoked,
   updateJiraInstallationTokenExpiry,
   updateJiraInstallationWebhook,
@@ -101,10 +130,17 @@ export {
 } from '#db/installations.js';
 export type {CreateJiraWebhookRoutesOptions} from '#presentation/routes/webhooks.js';
 export {createJiraWebhookRoutes} from '#presentation/routes/webhooks.js';
+export {createJiraMaintenanceWorker} from '#temporal/worker.js';
 export {closeDb, config, db, migrationsPath};
 
 export interface CreateJiraIntegrationProviderOptions {
   jira?: JiraApiClient | undefined;
+  agentTools?:
+    | {
+        tokenStore: Pick<JiraTokenStore, 'getAccessToken'>;
+        jira?: JiraAgentToolsClient | undefined;
+      }
+    | undefined;
   getJiraInstallationByConnectionId?: typeof getJiraInstallationByConnectionId | undefined;
   routes?: JiraIntegrationProviderRoutesOptions | undefined;
 }
@@ -119,6 +155,14 @@ export function createJiraIntegrationProvider(options: CreateJiraIntegrationProv
   const jira = options.jira ?? createJiraApiClient();
   const getInstallationByConnectionId =
     options.getJiraInstallationByConnectionId ?? getJiraInstallationByConnectionId;
+  const adapters = options.agentTools
+    ? {
+        agent_tools: new JiraAgentToolsProvider({
+          jira: options.agentTools.jira ?? createJiraAgentToolsClient(),
+          tokenStore: options.agentTools.tokenStore,
+        }),
+      }
+    : {};
   const webhookOptions = toJiraWebhookOptions(options.routes);
   const webhookProcessor = webhookOptions ? createJiraWebhookProcessor(webhookOptions) : undefined;
   const webhookRoutes = webhookOptions
@@ -136,7 +180,7 @@ export function createJiraIntegrationProvider(options: CreateJiraIntegrationProv
     ? [
         createJiraIntegrationRoutes({
           jira,
-          connectionCapabilities: [],
+          connectionCapabilities: adapters.agent_tools ? ['agent_tools'] : [],
           ...options.routes,
           registerJiraWebhook: (input) =>
             registerJiraWebhook({
@@ -162,7 +206,7 @@ export function createJiraIntegrationProvider(options: CreateJiraIntegrationProv
   return {
     provider: JIRA_PROVIDER,
     displayName: 'Jira',
-    adapters: {},
+    adapters,
     async connectionExternalUrl(connection: {id: string}): Promise<string | undefined> {
       return (await getInstallationByConnectionId(connection.id))?.siteUrl;
     },

package/src/temporal/activities/index.ts

@@ -0,0 +1,5 @@
+export {
+  type CreateJiraMaintenanceActivitiesOptions,
+  createJiraMaintenanceActivities,
+  type JiraTokenRefreshActivityResult,
+} from './refresh-jira-tokens.js';

package/src/temporal/activities/refresh-jira-tokens.test.ts

@@ -0,0 +1,156 @@
+import type {JiraInstallation} from '#db/installations.js';
+import {JIRA_REFRESH_TOKEN_PROACTIVE_REFRESH_AFTER_MS} from '#temporal/constants.js';
+import {createJiraMaintenanceActivities} from './index.js';
+
+function installation(connectionId: string): JiraInstallation {
+  const now = new Date('2026-01-01T00:00:00.000Z');
+  return {
+    id: crypto.randomUUID(),
+    connectionId,
+    cloudId: crypto.randomUUID(),
+    siteUrl: 'https://acme.atlassian.net',
+    siteName: 'Acme',
+    authorizingAccountId: crypto.randomUUID(),
+    scopes: ['offline_access'],
+    webhookIds: [],
+    webhookExpiresAt: null,
+    status: 'installed',
+    tokenExpiresAt: now,
+    refreshTokenLastUsedAt: now,
+    refreshTokenLastAttemptedAt: now,
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+describe('Jira proactive token refresh activity', () => {
+  it('force-refreshes due active connections and skips inactive ones', async () => {
+    const activeConnectionId = crypto.randomUUID();
+    const inactiveConnectionId = crypto.randomUUID();
+    const failedConnectionId = crypto.randomUUID();
+    const installations = [
+      installation(activeConnectionId),
+      installation(inactiveConnectionId),
+      installation(failedConnectionId),
+    ];
+    const listInstallations = vi.fn().mockResolvedValue(installations);
+    const resolveConnection = vi
+      .fn()
+      .mockImplementation(async (connectionId: string) =>
+        connectionId === activeConnectionId
+          ? {lifecycleStatus: 'active'}
+          : connectionId === failedConnectionId
+            ? {lifecycleStatus: 'active'}
+            : {lifecycleStatus: 'error'},
+      );
+    const getAccessToken = vi.fn().mockImplementation(({connectionId}: {connectionId: string}) => {
+      if (connectionId === failedConnectionId) throw new Error('refresh failed');
+      return 'fresh-access-token';
+    });
+    const heartbeat = vi.fn();
+    const markAttempted = vi.fn().mockResolvedValue(undefined);
+    const now = new Date('2026-08-04T00:00:00.000Z');
+    const activities = createJiraMaintenanceActivities({
+      tokenStore: {getAccessToken},
+      resolveConnection,
+      listInstallations,
+      markAttempted,
+      now: () => now,
+      heartbeat,
+    });
+
+    const result = await activities.refreshJiraTokensActivity();
+
+    expect(listInstallations).toHaveBeenCalledWith({
+      before: new Date(now.getTime() - JIRA_REFRESH_TOKEN_PROACTIVE_REFRESH_AFTER_MS),
+      limit: 20,
+    });
+    expect(getAccessToken).toHaveBeenCalledWith({
+      connectionId: activeConnectionId,
+      forceRefresh: true,
+    });
+    expect(getAccessToken).toHaveBeenCalledTimes(2);
+    expect(heartbeat).toHaveBeenCalledTimes(6);
+    expect(markAttempted).toHaveBeenCalledTimes(3);
+    expect(result).toEqual({refreshed: 1, skipped: 1, failed: 1});
+  });
+
+  it('heartbeats while a token refresh is in flight', async () => {
+    vi.useFakeTimers();
+    try {
+      const connectionId = crypto.randomUUID();
+      let resolveToken!: (value: string | PromiseLike<string>) => void;
+      const getAccessToken = vi.fn(
+        () =>
+          new Promise<string>((resolve) => {
+            resolveToken = resolve;
+          }),
+      );
+      const heartbeat = vi.fn();
+      const activities = createJiraMaintenanceActivities({
+        tokenStore: {getAccessToken},
+        resolveConnection: vi.fn().mockResolvedValue({lifecycleStatus: 'active'}),
+        listInstallations: vi.fn().mockResolvedValue([installation(connectionId)]),
+        markAttempted: vi.fn().mockResolvedValue(undefined),
+        heartbeat,
+      });
+
+      const result = activities.refreshJiraTokensActivity();
+      await vi.waitFor(() => expect(getAccessToken).toHaveBeenCalledOnce());
+      const heartbeatCountBeforeRefresh = heartbeat.mock.calls.length;
+
+      await vi.advanceTimersByTimeAsync(30_000);
+
+      expect(heartbeat.mock.calls.length).toBeGreaterThan(heartbeatCountBeforeRefresh);
+      resolveToken('fresh-access-token');
+      await expect(result).resolves.toEqual({refreshed: 1, skipped: 0, failed: 0});
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('counts an attempt failure and continues with the next installation', async () => {
+    const failedConnectionId = crypto.randomUUID();
+    const activeConnectionId = crypto.randomUUID();
+    const installations = [installation(failedConnectionId), installation(activeConnectionId)];
+    const activities = createJiraMaintenanceActivities({
+      tokenStore: {getAccessToken: vi.fn().mockResolvedValue('fresh-access-token')},
+      resolveConnection: vi.fn().mockResolvedValue({lifecycleStatus: 'active'}),
+      listInstallations: vi.fn().mockResolvedValue(installations),
+      markAttempted: vi
+        .fn()
+        .mockRejectedValueOnce(new Error('attempt write failed'))
+        .mockResolvedValue(undefined),
+      heartbeat: vi.fn(),
+    });
+
+    const result = await activities.refreshJiraTokensActivity();
+
+    expect(result).toEqual({refreshed: 1, skipped: 0, failed: 1});
+  });
+
+  it('counts a connection lookup failure and continues with the next installation', async () => {
+    const failedConnectionId = crypto.randomUUID();
+    const activeConnectionId = crypto.randomUUID();
+    const getAccessToken = vi.fn().mockResolvedValue('fresh-access-token');
+    const activities = createJiraMaintenanceActivities({
+      tokenStore: {getAccessToken},
+      resolveConnection: vi
+        .fn()
+        .mockRejectedValueOnce(new Error('connection lookup failed'))
+        .mockResolvedValue({lifecycleStatus: 'active'}),
+      listInstallations: vi
+        .fn()
+        .mockResolvedValue([installation(failedConnectionId), installation(activeConnectionId)]),
+      markAttempted: vi.fn().mockResolvedValue(undefined),
+    });
+
+    const result = await activities.refreshJiraTokensActivity();
+
+    expect(getAccessToken).toHaveBeenCalledWith({
+      connectionId: activeConnectionId,
+      forceRefresh: true,
+    });
+    expect(result).toEqual({refreshed: 1, skipped: 0, failed: 1});
+  });
+});

package/src/temporal/activities/refresh-jira-tokens.ts

@@ -0,0 +1,88 @@
+import type {IntegrationConnection} from '@shipfox/api-integration-spi';
+import {logger} from '@shipfox/node-opentelemetry';
+import type {JiraTokenStore} from '#core/tokens.js';
+import {
+  type JiraInstallation,
+  listJiraInstallationsDueForTokenRefresh,
+  markJiraInstallationTokenRefreshAttempt,
+} from '#db/installations.js';
+import {
+  JIRA_REFRESH_TOKEN_PROACTIVE_REFRESH_AFTER_MS,
+  JIRA_REFRESH_TOKEN_SWEEP_BATCH_SIZE,
+} from '#temporal/constants.js';
+
+const JIRA_REFRESH_TOKEN_HEARTBEAT_INTERVAL_MS = 15_000;
+
+export interface JiraTokenRefreshActivityResult {
+  refreshed: number;
+  skipped: number;
+  failed: number;
+}
+
+export interface CreateJiraMaintenanceActivitiesOptions {
+  tokenStore: Pick<JiraTokenStore, 'getAccessToken'>;
+  resolveConnection(
+    connectionId: string,
+  ): Promise<Pick<IntegrationConnection, 'lifecycleStatus'> | undefined>;
+  listInstallations?: typeof listJiraInstallationsDueForTokenRefresh | undefined;
+  markAttempted?: typeof markJiraInstallationTokenRefreshAttempt | undefined;
+  now?: (() => Date) | undefined;
+  heartbeat?: (() => void) | undefined;
+}
+
+export function createJiraMaintenanceActivities(options: CreateJiraMaintenanceActivitiesOptions) {
+  const listInstallations = options.listInstallations ?? listJiraInstallationsDueForTokenRefresh;
+  const markAttempted = options.markAttempted ?? markJiraInstallationTokenRefreshAttempt;
+  const now = options.now ?? (() => new Date());
+  const heartbeat = options.heartbeat ?? (() => undefined);
+
+  return {
+    async refreshJiraTokensActivity(): Promise<JiraTokenRefreshActivityResult> {
+      const before = new Date(now().getTime() - JIRA_REFRESH_TOKEN_PROACTIVE_REFRESH_AFTER_MS);
+      const installations = await listInstallations({
+        before,
+        limit: JIRA_REFRESH_TOKEN_SWEEP_BATCH_SIZE,
+      });
+      let refreshed = 0;
+      let skipped = 0;
+      let failed = 0;
+
+      for (const installation of installations) {
+        const heartbeatInterval = setInterval(heartbeat, JIRA_REFRESH_TOKEN_HEARTBEAT_INTERVAL_MS);
+        try {
+          heartbeat();
+          await markAttempted(installation.connectionId);
+          const connection = await options.resolveConnection(installation.connectionId);
+          if (connection?.lifecycleStatus !== 'active') {
+            skipped += 1;
+            continue;
+          }
+
+          await options.tokenStore.getAccessToken({
+            connectionId: installation.connectionId,
+            forceRefresh: true,
+          });
+          refreshed += 1;
+        } catch (error) {
+          failed += 1;
+          logRefreshFailure(installation, error);
+        } finally {
+          clearInterval(heartbeatInterval);
+          heartbeat();
+        }
+      }
+
+      return {refreshed, skipped, failed};
+    },
+  };
+}
+
+function logRefreshFailure(installation: JiraInstallation, error: unknown): void {
+  logger().warn(
+    {
+      connectionId: installation.connectionId,
+      err: error,
+    },
+    'Jira proactive token refresh failed',
+  );
+}

package/src/temporal/constants.ts

@@ -0,0 +1,8 @@
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+export const JIRA_REFRESH_TOKEN_IDLE_WINDOW_MS = 90 * MS_PER_DAY;
+export const JIRA_REFRESH_TOKEN_REFRESH_LEAD_TIME_MS = 14 * MS_PER_DAY;
+export const JIRA_REFRESH_TOKEN_PROACTIVE_REFRESH_AFTER_MS =
+  JIRA_REFRESH_TOKEN_IDLE_WINDOW_MS - JIRA_REFRESH_TOKEN_REFRESH_LEAD_TIME_MS;
+export const JIRA_REFRESH_TOKEN_SWEEP_BATCH_SIZE = 20;
+export const JIRA_MAINTENANCE_TASK_QUEUE = 'integrations-jira-maintenance';