refactor(bot): make callback continuation platform agnostic (#2949)

* refactor(bot): make callback continuation platform agnostic

* refactor(bot): require platform integration lookup

* Default to slack docs for now

* Clean up withBotPlatformAuthContext

* Cleaner logic

* Fix failing test expectations

Author: RSO

apps/web/src/app/api/internal/bot-session-callback/[botRequestId]/route.ts

@@ -10,6 +10,7 @@ import {
   formatConversationContextForPrompt,
 } from '@/lib/bot/conversation-context';
 import { buildPrSignature, getRequesterInfo } from '@/lib/bot/pr-signature';
+import { getBotDocumentationUrl } from '@/lib/bot/platform-helpers';
 import {
   linkBotRequestToSession,
   recordBotRequestCloudAgentSession,
@@ -41,7 +42,6 @@ import type { BotRequestStep } from '@kilocode/db/schema';
 import { ToolLoopAgent, generateText, stepCountIs, tool } from 'ai';
 import type { StepResult, ToolSet } from 'ai';
 import { Actions, Card, CardText, LinkButton, Section } from 'chat';
-import { ThreadImpl } from 'chat';
 import type { Author, Message, Thread } from 'chat';
 import { randomUUID } from 'crypto';
 
@@ -98,6 +98,7 @@ async function buildSystemPrompt(
   triggerMessage: { id: string }
 ) {
   const owner = ownerFromIntegration(platformIntegration);
+  const botDocumentationUrl = getBotDocumentationUrl(platformIntegration.platform);
 
   const [githubContext, gitlabContext, conversationContext] = await Promise.all([
     getGitHubRepositoryContext(owner),
@@ -113,7 +114,7 @@ async function buildSystemPrompt(
 - If the user's request is ambiguous, ask 1-2 clarifying questions instead of guessing.
 
 ## Answering questions about Kilo Bot
-- When users ask what you can do, how you work, or for general help, include a link to the Bot documentation: https://kilo.ai/docs/code-with-ai/platforms/slack
+- When users ask what you can do, how you work, or for general help, include a link to the Bot documentation: ${botDocumentationUrl}
 - Provide the docs link along with your answer so users can learn more.
 
 ## Context you may receive
@@ -359,17 +360,3 @@ This tool returns an acknowledgement immediately. The final Cloud Agent result w
     responseTimeMs: Date.now() - startedAt,
   };
 }
-
-export function createSyntheticThread(params: {
-  threadId: string;
-  adapterName: string;
-  channelId: string;
-  isDM: boolean;
-}): Thread {
-  return new ThreadImpl({
-    adapterName: params.adapterName,
-    id: params.threadId,
-    channelId: params.channelId,
-    isDM: params.isDM,
-  });
-}

apps/web/src/lib/bot/agent-runner.ts

@@ -89,7 +89,7 @@ export async function extractAndUploadImages(
     } catch (error) {
       console.error('[KiloBot] Failed to upload image attachment:', error);
       captureException(error, {
-        tags: { component: 'kilo-bot', op: 'upload-slack-image' },
+        tags: { component: 'kilo-bot', op: 'upload-bot-image' },
       });
     }
   }

apps/web/src/lib/bot/images.ts

@@ -0,0 +1,112 @@
+jest.mock('@/lib/bot', () => ({
+  bot: {
+    getAdapter: jest.fn(),
+    initialize: jest.fn(),
+    registerSingleton: jest.fn(),
+  },
+}));
+
+import { PLATFORM } from '@/lib/integrations/core/constants';
+import type { PlatformIntegration } from '@kilocode/db';
+import { withBotPlatformAuthContext } from './platform-auth-context';
+
+type MockBotModule = {
+  bot: {
+    getAdapter: jest.Mock;
+    initialize: jest.Mock;
+    registerSingleton: jest.Mock;
+  };
+};
+
+const mockBotModule: MockBotModule = jest.requireMock('@/lib/bot');
+let mockWithBotToken: jest.Mock;
+let mockGetInstallation: jest.Mock;
+
+function createPlatformIntegration(
+  overrides: Partial<PlatformIntegration> = {}
+): PlatformIntegration {
+  return {
+    id: 'pi_slack',
+    owned_by_user_id: 'user_1',
+    owned_by_organization_id: null,
+    created_by_user_id: null,
+    platform: PLATFORM.SLACK,
+    integration_type: 'oauth',
+    platform_installation_id: 'T123',
+    platform_account_id: 'T123',
+    platform_account_login: 'Test Workspace',
+    permissions: null,
+    integration_status: 'active',
+    scopes: null,
+    repository_access: null,
+    repositories: null,
+    repositories_synced_at: null,
+    metadata: { access_token: 'xoxb-current' },
+    kilo_requester_user_id: null,
+    platform_requester_account_id: null,
+    suspended_at: null,
+    suspended_by: null,
+    github_app_type: 'standard',
+    installed_at: '2026-01-01T00:00:00.000Z',
+    created_at: '2026-01-01T00:00:00.000Z',
+    updated_at: '2026-01-01T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+describe('withBotPlatformAuthContext', () => {
+  beforeEach(() => {
+    mockWithBotToken = jest.fn(async (_token, fn) => await fn());
+    mockGetInstallation = jest.fn();
+
+    mockBotModule.bot.getAdapter.mockReset();
+    mockBotModule.bot.initialize.mockReset();
+    mockBotModule.bot.registerSingleton.mockReset();
+
+    mockBotModule.bot.getAdapter.mockReturnValue({
+      getInstallation: mockGetInstallation,
+      withBotToken: mockWithBotToken,
+    });
+  });
+
+  it('wraps Slack callbacks with the installation bot token', async () => {
+    const fn = jest.fn(async () => 'result');
+    mockGetInstallation.mockResolvedValue({ botToken: 'xoxb-stored' });
+
+    const result = await withBotPlatformAuthContext(createPlatformIntegration(), fn);
+
+    expect(result).toBe('result');
+    expect(mockBotModule.bot.initialize).toHaveBeenCalledTimes(1);
+    expect(mockBotModule.bot.registerSingleton).toHaveBeenCalledTimes(1);
+    expect(mockBotModule.bot.getAdapter).toHaveBeenCalledWith(PLATFORM.SLACK);
+    expect(mockGetInstallation).toHaveBeenCalledWith('T123');
+    expect(mockWithBotToken).toHaveBeenCalledWith('xoxb-stored', expect.any(Function));
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('throws when Slack installation is missing', async () => {
+    mockGetInstallation.mockResolvedValue(null);
+
+    await expect(
+      withBotPlatformAuthContext(createPlatformIntegration({ metadata: {} }), async () => 'result')
+    ).rejects.toThrow('No Slack installation for platform integration pi_slack');
+  });
+
+  it('runs non-Slack callbacks directly', async () => {
+    const fn = jest.fn(async () => 'result');
+
+    const result = await withBotPlatformAuthContext(
+      createPlatformIntegration({
+        id: 'pi_discord',
+        platform: PLATFORM.DISCORD,
+        metadata: {},
+      }),
+      fn
+    );
+
+    expect(result).toBe('result');
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(mockBotModule.bot.getAdapter).not.toHaveBeenCalled();
+    expect(mockWithBotToken).not.toHaveBeenCalled();
+  });
+});

apps/web/src/lib/bot/platform-auth-context.test.ts

@@ -0,0 +1,25 @@
+import { bot } from '@/lib/bot';
+import { PLATFORM } from '@/lib/integrations/core/constants';
+import type { PlatformIntegration } from '@kilocode/db';
+
+export async function withBotPlatformAuthContext<T>(
+  platformIntegration: PlatformIntegration,
+  fn: () => Promise<T>
+): Promise<T> {
+  await bot.initialize();
+  bot.registerSingleton();
+
+  if (platformIntegration.platform === PLATFORM.SLACK) {
+    const slackAdapter = bot.getAdapter(PLATFORM.SLACK);
+    const installation = await slackAdapter.getInstallation(
+      platformIntegration.platform_account_id as string
+    );
+    if (!installation) {
+      throw new Error(`No Slack installation for platform integration ${platformIntegration.id}`);
+    }
+
+    return await slackAdapter.withBotToken(installation.botToken, fn);
+  }
+
+  return await fn();
+}

apps/web/src/lib/bot/platform-auth-context.ts

@@ -13,7 +13,12 @@ jest.mock('@/lib/drizzle', () => ({
 }));
 
 import { PLATFORM } from '@/lib/integrations/core/constants';
-import { getPlatformIntegration, getPlatformIntegrationByBotUserId } from './platform-helpers';
+import {
+  getBotDocumentationUrl,
+  getPlatformIntegration,
+  getPlatformIntegrationByBotUserId,
+  getPlatformIntegrationById,
+} from './platform-helpers';
 
 describe('platform helpers', () => {
   beforeEach(() => {
@@ -49,6 +54,27 @@ describe('platform helpers', () => {
     expect(result).toBeNull();
   });
 
+  it('returns the platform integration for a given id', async () => {
+    const integration = {
+      id: 'pi_slack',
+      platform: PLATFORM.SLACK,
+      platform_installation_id: 'T123',
+    };
+    mockLimit.mockResolvedValue([integration]);
+
+    const result = await getPlatformIntegrationById('pi_slack');
+
+    expect(result).toBe(integration);
+  });
+
+  it('throws when no platform integration exists for an id', async () => {
+    mockLimit.mockResolvedValue([]);
+
+    await expect(getPlatformIntegrationById('pi_missing')).rejects.toThrow(
+      'Could not find platform integration pi_missing'
+    );
+  });
+
   it('returns the platform integration for a bot user id', async () => {
     const integration = {
       id: 'pi_slack',
@@ -68,4 +94,13 @@ describe('platform helpers', () => {
     expect(result).toBeNull();
     expect(mockLimit).not.toHaveBeenCalled();
   });
+
+  it('returns platform-specific bot documentation URLs', () => {
+    expect(getBotDocumentationUrl(PLATFORM.SLACK)).toBe(
+      'https://kilo.ai/docs/code-with-ai/platforms/slack'
+    );
+    expect(getBotDocumentationUrl(PLATFORM.DISCORD)).toBe(
+      'https://kilo.ai/docs/code-with-ai/platforms/slack'
+    );
+  });
 });

apps/web/src/lib/bot/platform-helpers.test.ts

@@ -48,6 +48,20 @@ export async function getPlatformIntegration(identity: PlatformIdentity) {
   return integration ?? null;
 }
 
+export async function getPlatformIntegrationById(platformIntegrationId: string) {
+  const [integration] = await db
+    .select()
+    .from(platform_integrations)
+    .where(eq(platform_integrations.id, platformIntegrationId))
+    .limit(1);
+
+  if (!integration) {
+    throw new Error(`Could not find platform integration ${platformIntegrationId}`);
+  }
+
+  return integration;
+}
+
 export async function getPlatformIntegrationByBotUserId(
   platform: string,
   botUserId: string | undefined
@@ -67,3 +81,11 @@ export async function getPlatformIntegrationByBotUserId(
 
   return integration ?? null;
 }
+
+export function getBotDocumentationUrl(platform: string): string {
+  switch (platform) {
+    //TODO(remon): Update when we have specific docs pages for other platforms
+    default:
+      return 'https://kilo.ai/docs/code-with-ai/platforms/slack';
+  }
+}

apps/web/src/lib/bot/platform-helpers.ts

@@ -20,7 +20,7 @@ export async function processMessage({
 }) {
   const startedAt = Date.now();
 
-  // Extract and upload any image attachments from the Slack message to R2.
+  // Extract and upload any image attachments from the chat message to R2.
   // This runs before the agent loop so the images are ready when a Cloud Agent
   // session is spawned. Failures are non-fatal — we log and continue without images.
   let images: Awaited<ReturnType<typeof extractAndUploadImages>>;

apps/web/src/lib/bot/run.ts

@@ -32,6 +32,7 @@ import { insertTestUser } from '@/tests/helpers/user.helper';
 import type { User } from '@kilocode/db/schema';
 import type Stripe from 'stripe';
 import { KiloPassTier, KiloPassCadence } from '@/lib/kilo-pass/enums';
+import { differenceInCalendarMonths } from 'date-fns';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AnyMock = jest.Mock<(...args: any[]) => any>;
@@ -5062,11 +5063,9 @@ describe('enrollWithCredits', () => {
     expect(sub.payment_source).toBe('credits');
     expect(sub.commit_ends_at).not.toBeNull();
 
-    // commit_ends_at should be ~6 months from now
+    // commit_ends_at should be 6 calendar months from now.
     const commitEnd = new Date(sub.commit_ends_at!);
-    const diffDays = (commitEnd.getTime() - Date.now()) / 86_400_000;
-    expect(diffDays).toBeGreaterThanOrEqual(178);
-    expect(diffDays).toBeLessThanOrEqual(184);
+    expect(differenceInCalendarMonths(commitEnd, new Date())).toBe(6);
   });
 
   it('rejects enrollment when balance is insufficient', async () => {