Skip to content

Open source file-system and knowledge based agent template. Build AI agents that stay up to date with your knowledge base

up

Hugo Richardfd6797a360c2
diff --git a/apps/chat/server/api/sandbox/shell.post.ts b/apps/chat/server/api/sandbox/shell.post.ts
new file mode 100644
index 0000000..375e6ef
--- /dev/null
+++ b/apps/chat/server/api/sandbox/shell.post.ts
@@ -0,0 +1,96 @@
+import { z } from 'zod'
+import { useLogger } from 'evlog'
+import { getOrCreateSandbox } from '../../utils/sandbox/manager'
+
+const bodySchema = z.object({
+ command: z.string({ error: 'command is required' }).min(1, 'command cannot be empty').max(2000),
+ sessionId: z.string().optional(),
+})
+
+// Commands that could be dangerous
+const BLOCKED_PATTERNS = [
+ /\brm\s+-rf?\b/i,
+ /\brmdir\b/i,
+ /\bmkdir\b/i,
+ /\btouch\b/i,
+ /\bchmod\b/i,
+ /\bchown\b/i,
+ /\bsudo\b/i,
+ /\bcurl\b/i,
+ /\bwget\b/i,
+ /\bnc\b/i,
+ /\bssh\b/i,
+ /\bgit\b/i,
+ />\s*\//, // redirect to absolute path
+ /\bdd\b/i,
+ /\bkill\b/i,
+ /\bpkill\b/i,
+]
+
+/**
+ * POST /api/sandbox/shell
+ * Run a shell command in the sandbox.
+ *
+ * Body:
+ * - command: string - Shell command to execute
+ * - sessionId: string - Optional session ID for sandbox reuse
+ */
+export default defineEventHandler(async (event) => {
+ const requestLog = useLogger(event)
+ const body = await readValidatedBody(event, bodySchema.parse)
+
+ // Check for blocked patterns
+ for (const pattern of BLOCKED_PATTERNS) {
+ if (pattern.test(body.command)) {
+ throw createError({
+ statusCode: 400,
+ message: 'Command contains blocked pattern',
+ })
+ }
+ }
+
+ requestLog.set({ command: body.command.slice(0, 100) })
+
+ // Get or create sandbox
+ const sandboxStart = Date.now()
+ const { sandbox, sessionId } = await getOrCreateSandbox(body.sessionId)
+ const sandboxMs = Date.now() - sandboxStart
+
+ requestLog.set({ sandboxMs, sandboxId: sandbox.sandboxId, sessionId })
+
+ // Execute command
+ const execStart = Date.now()
+ const result = await sandbox.runCommand({
+ cmd: 'bash',
+ args: ['-c', body.command],
+ cwd: '/vercel/sandbox',
+ })
+
+ const stdout = await result.stdout()
+ const stderr = await result.stderr()
+ const { exitCode } = result
+ const execMs = Date.now() - execStart
+
+ // Limit output size to prevent token explosion
+ const MAX_OUTPUT = 50000 // ~50KB
+ const truncatedStdout = stdout.length > MAX_OUTPUT
+ ? `${stdout.slice(0, MAX_OUTPUT)}\n... (truncated, ${stdout.length} total chars)`
+ : stdout
+ const truncatedStderr = stderr.length > MAX_OUTPUT
+ ? `${stderr.slice(0, MAX_OUTPUT)}\n... (truncated, ${stderr.length} total chars)`
+ : stderr
+
+ requestLog.set({
+ execMs,
+ exitCode,
+ stdoutLen: stdout.length,
+ stderrLen: stderr.length,
+ })
+
+ return {
+ sessionId,
+ stdout: truncatedStdout,
+ stderr: truncatedStderr,
+ exitCode,
+ }
+})
diff --git a/apps/chat/server/utils/sandbox/manager.ts b/apps/chat/server/utils/sandbox/manager.ts
index 065aeda..718bc6a 100644
--- a/apps/chat/server/utils/sandbox/manager.ts
+++ b/apps/chat/server/utils/sandbox/manager.ts
@@ -265,7 +265,14 @@ export async function read(
return filteredFiles
}
-/** Searches for query and returns matches with full file contents */
+/**
+ * Searches for query and returns matches with context snippets.
+ *
+ * Optimizations:
+ * 1. Occurrence-based ranking - files with more matches are more relevant
+ * 2. Limited file reads - only top 3 most relevant files
+ * 3. Context snippets - only lines around matches, not full files
+ */
export async function searchAndRead(
sandbox: Sandbox,
query: string,
@@ -274,11 +281,116 @@ export async function searchAndRead(
// Search for matches
const matches = await search(sandbox, query, limit)
- // Get unique file paths
- const uniquePaths = [...new Set(matches.map(m => m.path))]
+ if (matches.length === 0) {
+ return { matches: [], files: [] }
+ }
+
+ // Count occurrences per file and rank by relevance
+ const fileOccurrences = new Map<string, number>()
+ for (const match of matches) {
+ fileOccurrences.set(match.path, (fileOccurrences.get(match.path) || 0) + 1)
+ }
+
+ // Sort files by occurrence count (most relevant first)
+ const rankedFiles = [...fileOccurrences.entries()]
+ .sort((a, b) => b[1] - a[1])
+ .map(([path]) => path)
+
+ // Only read top 3 most relevant files (to avoid context explosion)
+ const topFiles = rankedFiles.slice(0, 3)
- // Read the unique files
- const files = await read(sandbox, uniquePaths)
+ log.info('sandbox', `Ranked ${rankedFiles.length} files, reading top ${topFiles.length}`)
+
+ // Read files with context snippets instead of full content
+ const files = await readWithContext(sandbox, topFiles, matches)
return { matches, files }
}
+
+/**
+ * Read files but only include lines around matches (context snippets).
+ * This prevents context explosion from large files.
+ */
+async function readWithContext(
+ sandbox: Sandbox,
+ paths: string[],
+ matches: SearchResult[],
+ contextLines: number = 10,
+): Promise<FileContent[]> {
+ const startTime = Date.now()
+
+ const files = await Promise.all(paths.map(async (path) => {
+ try {
+ const buffer = await sandbox.readFileToBuffer({
+ path,
+ cwd: '/vercel/sandbox',
+ })
+
+ if (!buffer) {
+ return null
+ }
+
+ const fullContent = buffer.toString('utf-8')
+ const lines = fullContent.split('\n')
+
+ // Get line numbers with matches in this file
+ const matchLines = matches
+ .filter(m => m.path === path)
+ .map(m => m.lineNumber)
+
+ // Build a set of lines to include (match lines + context)
+ const linesToInclude = new Set<number>()
+ for (const lineNum of matchLines) {
+ for (let i = Math.max(1, lineNum - contextLines); i <= Math.min(lines.length, lineNum + contextLines); i++) {
+ linesToInclude.add(i)
+ }
+ }
+
+ // Build content with only relevant lines
+ // Group consecutive lines into snippets
+ const sortedLines = [...linesToInclude].sort((a, b) => a - b)
+ const snippets: string[] = []
+ let currentSnippet: string[] = []
+ let lastLine = -1
+
+ for (const lineNum of sortedLines) {
+ if (lastLine !== -1 && lineNum > lastLine + 1) {
+ // Gap in lines - save current snippet and start new one
+ if (currentSnippet.length > 0) {
+ snippets.push(currentSnippet.join('\n'))
+ currentSnippet = []
+ }
+ snippets.push('...')
+ }
+
+ const lineContent = lines[lineNum - 1] // 0-indexed
+ if (lineContent !== undefined) {
+ currentSnippet.push(`${lineNum}: ${lineContent}`)
+ }
+ lastLine = lineNum
+ }
+
+ // Don't forget the last snippet
+ if (currentSnippet.length > 0) {
+ snippets.push(currentSnippet.join('\n'))
+ }
+
+ const contextContent = snippets.join('\n')
+
+ return {
+ path,
+ content: contextContent,
+ matchCount: matchLines.length,
+ totalLines: lines.length,
+ }
+ } catch {
+ return null
+ }
+ }))
+
+ const filteredFiles: FileContent[] = files.filter((f) => f !== null)
+ const readMs = Date.now() - startTime
+
+ log.info('sandbox', `Read ${filteredFiles.length} files with context (${readMs}ms)`)
+ return filteredFiles
+}
diff --git a/apps/chat/server/utils/sandbox/types.ts b/apps/chat/server/utils/sandbox/types.ts
index 9da3a42..24ac7e8 100644
--- a/apps/chat/server/utils/sandbox/types.ts
+++ b/apps/chat/server/utils/sandbox/types.ts
@@ -31,11 +31,15 @@ export interface SearchResult {
}
/**
- * File content with path
+ * File content with path and optional metadata
*/
export interface FileContent {
path: string
content: string
+ /** Number of matches in this file (for context snippets) */
+ matchCount?: number
+ /** Total lines in the file (for context snippets) */
+ totalLines?: number
}
/**
diff --git a/apps/github-bot/server/api/webhook.post.ts b/apps/github-bot/server/api/webhook.post.ts
new file mode 100644
index 0000000..e2bbaf7
--- /dev/null
+++ b/apps/github-bot/server/api/webhook.post.ts
@@ -0,0 +1,16 @@
+import { log } from 'evlog'
+import { useGitHubChat } from '../utils/chat'
+
+export default defineEventHandler(async (event) => {
+ const chat = useGitHubChat()
+ const request = toWebRequest(event)
+
+ try {
+ await chat.webhooks?.github?.(request)
+ }
+ catch (error) {
+ log.error('github-bot', `Webhook error: ${error instanceof Error ? error.message : 'Unknown'}`)
+ }
+
+ return { ok: true }
+})
diff --git a/apps/github-bot/server/utils/adapter.ts b/apps/github-bot/server/utils/adapter.ts
index 8a02071..da068d4 100644
--- a/apps/github-bot/server/utils/adapter.ts
+++ b/apps/github-bot/server/utils/adapter.ts
@@ -1,22 +1,7 @@
-/**
- * GitHubAdapter - Platform adapter for GitHub issue comments
- *
- * This adapter demonstrates how to implement chat-sdk's Adapter interface
- * for a new platform. It handles:
- * - Webhook signature verification (HMAC-SHA256)
- * - Issue comment parsing and posting
- * - Thread ID encoding/decoding
- * - Markdown format conversion (GitHub Flavored Markdown)
- *
- * Thread ID format: github:{owner}/{repo}:issue:{number}
- * Example: github:nuxt/nuxt:issue:12345
- */
-
-import { createHmac, createSign, timingSafeEqual } from 'node:crypto'
+import { createHmac, timingSafeEqual } from 'node:crypto'
import type {
Adapter,
AdapterPostableMessage,
- Author,
ChatInstance,
EmojiValue,
FetchOptions,
@@ -27,196 +12,16 @@ import type {
WebhookOptions,
} from 'chat'
import { Message, NotImplementedError } from 'chat'
+import { createGitHubAuth, type GitHubAuth } from './auth'
import { GitHubFormatConverter } from './markdown'
-
-// ============================================================================
-// GitHub App JWT Token Generation
-// ============================================================================
-
-/**
- * Generate a JWT for GitHub App authentication.
- * The JWT is used to authenticate as the GitHub App itself.
- */
-function generateAppJWT(appId: string, privateKey: string): string {
- const now = Math.floor(Date.now() / 1000)
- const payload = {
- iat: now - 60, // Issued 60 seconds ago to account for clock drift
- exp: now + 600, // Expires in 10 minutes (max allowed by GitHub)
- iss: appId,
- }
-
- // Create JWT header
- const header = { alg: 'RS256', typ: 'JWT' }
- const headerB64 = Buffer.from(JSON.stringify(header)).toString('base64url')
- const payloadB64 = Buffer.from(JSON.stringify(payload)).toString('base64url')
-
- // Sign with RSA-SHA256
- const signatureInput = `${headerB64}.${payloadB64}`
- const sign = createSign('RSA-SHA256')
- sign.update(signatureInput)
- const signature = sign.sign(privateKey, 'base64url')
-
- return `${headerB64}.${payloadB64}.${signature}`
-}
-
-/**
- * Cache for installation tokens.
- * Key: installation ID, Value: { token, expiresAt }
- */
-const tokenCache = new Map<number, { token: string, expiresAt: Date }>()
-
-/**
- * Get an installation access token for a GitHub App.
- * Caches tokens and refreshes them when expired.
- */
-async function getInstallationToken(
- appId: string,
- privateKey: string,
- installationId: number,
-): Promise<string> {
- // Check cache
- const cached = tokenCache.get(installationId)
- if (cached && cached.expiresAt > new Date(Date.now() + 60000)) {
- // Token is still valid for at least 1 minute
- return cached.token
- }
-
- // Generate new token
- const jwt = generateAppJWT(appId, privateKey)
-
- const response = await fetch(
- `https://api.github.com/app/installations/${installationId}/access_tokens`,
- {
- method: 'POST',
- headers: {
- 'Authorization': `Bearer ${jwt}`,
- 'Accept': 'application/vnd.github.v3+json',
- 'X-GitHub-Api-Version': '2022-11-28',
- },
- },
- )
-
- if (!response.ok) {
- const error = await response.text()
- throw new Error(`Failed to get installation token: ${response.status} ${error}`)
- }
-
- const data = await response.json() as { token: string, expires_at: string }
-
- // Cache the token
- tokenCache.set(installationId, {
- token: data.token,
- expiresAt: new Date(data.expires_at),
- })
-
- return data.token
-}
-
-/**
- * Get installation ID for a repository.
- */
-async function getInstallationId(
- appId: string,
- privateKey: string,
- owner: string,
- repo: string,
-): Promise<number> {
- const jwt = generateAppJWT(appId, privateKey)
-
- const response = await fetch(
- `https://api.github.com/repos/${owner}/${repo}/installation`,
- {
- headers: {
- 'Authorization': `Bearer ${jwt}`,
- 'Accept': 'application/vnd.github.v3+json',
- 'X-GitHub-Api-Version': '2022-11-28',
- },
- },
- )
-
- if (!response.ok) {
- const error = await response.text()
- throw new Error(`Failed to get installation: ${response.status} ${error}`)
- }
-
- const data = await response.json() as { id: number }
- return data.id
-}
-
-/** Cache for installation IDs (repo -> installation ID) */
-const installationIdCache = new Map<string, number>()
-
-// ============================================================================
-// Types
-// ============================================================================
-
-/** GitHub-specific thread ID components */
-export interface GitHubThreadId {
- owner: string
- repo: string
- issueNumber: number
-}
-
-/** GitHub issue comment (raw message format) */
-export interface GitHubComment {
- id: number
- node_id: string
- body: string
- user: {
- id: number
- login: string
- avatar_url: string
- type: string // "User" or "Bot"
- }
- created_at: string
- updated_at: string
- html_url: string
- issue_url: string
-}
-
-/** GitHub webhook payload for issue_comment event */
-interface GitHubIssueCommentPayload {
- action: 'created' | 'edited' | 'deleted'
- issue: {
- number: number
- title: string
- state: string
- user: {
- id: number
- login: string
- }
- }
- comment: GitHubComment
- repository: {
- id: number
- name: string
- full_name: string
- owner: {
- login: string
- }
- }
- sender: {
- id: number
- login: string
- type: string
- }
-}
-
-/** Configuration for GitHubAdapter */
-export interface GitHubAdapterConfig {
- /** Bot username (without @) */
- userName: string
- /** GitHub webhook secret for signature verification */
- webhookSecret: string
- /** GitHub App ID */
- appId: string
- /** GitHub App private key (PEM format) */
- appPrivateKey: string
-}
-
-// ============================================================================
-// Adapter Implementation
-// ============================================================================
+import type {
+ GitHubAdapterConfig,
+ GitHubComment,
+ GitHubIssueCommentPayload,
+ GitHubIssuesPayload,
+ GitHubThreadId,
+ IssueContext,
+} from './types'
export class GitHubAdapter implements Adapter<GitHubThreadId, GitHubComment> {
@@ -225,116 +30,119 @@ export class GitHubAdapter implements Adapter<GitHubThreadId, GitHubComment> {
private chat!: ChatInstance
private webhookSecret: string
- private appId: string
- private appPrivateKey: string
+ private auth: GitHubAuth
private formatConverter: GitHubFormatConverter
constructor(config: GitHubAdapterConfig) {
this.userName = config.userName
this.webhookSecret = config.webhookSecret
- this.appId = config.appId
- this.appPrivateKey = config.appPrivateKey
+ this.auth = createGitHubAuth(config.appId, config.appPrivateKey)
this.formatConverter = new GitHubFormatConverter()
}
- /**
- * Get an access token for a specific repository.
- * Uses the GitHub App credentials to generate an installation token.
- */
- private async getToken(owner: string, repo: string): Promise<string> {
- const cacheKey = `${owner}/${repo}`
-
- // Get installation ID (cached)
- let installationId = installationIdCache.get(cacheKey)
- if (!installationId) {
- installationId = await getInstallationId(this.appId, this.appPrivateKey, owner, repo)
- installationIdCache.set(cacheKey, installationId)
- }
-
- // Get installation token (cached)
- return getInstallationToken(this.appId, this.appPrivateKey, installationId)
+ private getToken(owner: string, repo: string): Promise<string> {
+ return this.auth.getToken(owner, repo)
}
- /**
- * Called when Chat instance is created.
- * Store reference for calling processMessage.
- */
async initialize(chat: ChatInstance): Promise<void> {
this.chat = chat
}
- // ==========================================================================
- // Webhook Handling
- // ==========================================================================
-
- /**
- * Handle incoming GitHub webhook requests.
- * Verifies signature, parses payload, and dispatches to chat handlers.
- */
- async handleWebhook(
- request: Request,
- options?: WebhookOptions,
- ): Promise<Response> {
+ async handleWebhook(request: Request, options?: WebhookOptions): Promise<Response> {
const body = await request.text()
- // Verify webhook signature
const signature = request.headers.get('X-Hub-Signature-256')
if (!this.verifySignature(body, signature)) {
return new Response('Invalid signature', { status: 401 })
}
- // Check event type
const event = request.headers.get('X-GitHub-Event')
+
if (event === 'ping') {
return new Response('pong', { status: 200 })
}
- if (event !== 'issue_comment') {
- // Ignore other events for now
- return new Response('OK', { status: 200 })
+ if (event === 'issue_comment') {
+ return this.handleIssueComment(body, options)
}
+ if (event === 'issues') {
+ return this.handleIssueEvent(body, options)
+ }
+
+ return new Response('OK', { status: 200 })
+ }
+
+ private handleIssueComment(body: string, options?: WebhookOptions): Response {
const payload = JSON.parse(body) as GitHubIssueCommentPayload
- // Only handle new comments
if (payload.action !== 'created') {
return new Response('OK', { status: 200 })
}
- // Ignore bot's own comments to prevent loops
- // For GitHub Apps, the username is "app-slug[bot]"
const botUserName = `${this.userName}[bot]`
if (payload.comment.user.login === this.userName || payload.comment.user.login === botUserName) {
return new Response('OK', { status: 200 })
}
- // Build thread ID
const threadId = this.encodeThreadId({
owner: payload.repository.owner.login,
repo: payload.repository.name,
issueNumber: payload.issue.number,
})
- // Parse message and dispatch to handlers
const message = this.parseMessage(payload.comment)
+ this.chat.processMessage(this, threadId, message, options)
+
+ return new Response('OK', { status: 200 })
+ }
+
+ private handleIssueEvent(body: string, options?: WebhookOptions): Response {
+ const payload = JSON.parse(body) as GitHubIssuesPayload
+
+ if (payload.action !== 'opened') {
+ return new Response('OK', { status: 200 })
+ }
+
+ const botUserName = `${this.userName}[bot]`
+ if (payload.issue.user.login === this.userName || payload.issue.user.login === botUserName) {
+ return new Response('OK', { status: 200 })
+ }
+
+ const threadId = this.encodeThreadId({
+ owner: payload.repository.owner.login,
+ repo: payload.repository.name,
+ issueNumber: payload.issue.number,
+ })
- // Process message (handles mention detection, handler routing, etc.)
+ const virtualComment = {
+ id: `issue:${payload.issue.number}` as unknown as number,
+ node_id: `issue_${payload.issue.id}`,
+ body: `${payload.issue.title}\n\n${payload.issue.body || ''}`,
+ user: {
+ id: payload.issue.user.id,
+ login: payload.issue.user.login,
+ avatar_url: payload.issue.user.avatar_url,
+ type: 'User',
+ },
+ created_at: payload.issue.created_at,
+ updated_at: payload.issue.updated_at,
+ html_url: payload.issue.html_url,
+ issue_url: payload.issue.html_url,
+ } as GitHubComment
+
+ const message = this.parseMessage(virtualComment)
this.chat.processMessage(this, threadId, message, options)
return new Response('OK', { status: 200 })
}
- /**
- * Verify GitHub webhook signature using HMAC-SHA256.
- */
private verifySignature(body: string, signature: string | null): boolean {
if (!signature || !this.webhookSecret) {
return false
}
- const expected
- = `sha256=${
- createHmac('sha256', this.webhookSecret).update(body).digest('hex')}`
+ const expected = `sha256=${createHmac('sha256', this.webhookSecret).update(body).digest('hex')}`
try {
return timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
@@ -343,17 +151,7 @@ export class GitHubAdapter implements Adapter<GitHubThreadId, GitHubComment> {
}
}
- // ==========================================================================
- // Message Operations
- // ==========================================================================
-
- /**
- * Post a comment to a GitHub issue.
- */
- async postMessage(
- threadId: string,
- message: AdapterPostableMessage,
- ): Promise<RawMessage<GitHubComment>> {
+ async postMessage(threadId: string, message: AdapterPostableMessage): Promise<RawMessage<GitHubComment>> {
const { owner, repo, issueNumber } = this.decodeThreadId(threadId)
const body = this.renderPostable(message)
const token = await this.getToken(owner, repo)
@@ -378,21 +176,10 @@ export class GitHubAdapter implements Adapter<GitHubThreadId, GitHubComment> {
}
const data = (await response.json()) as GitHubComment
- return {
- id: String(data.id),
- threadId,
- raw: data,
- }
+ return { id: String(data.id), threadId, raw: data }
}
- /**
- * Edit an existing comment.
- */
- async editMessage(
- threadId: string,
- messageId: string,
- message: AdapterPostableMessage,
- ): Promise<RawMessage<GitHubComment>> {
+ async editMessage(threadId: string, messageId: string, message: AdapterPostableMessage): Promise<RawMessage<GitHubComment>> {
const { owner, repo } = this.decodeThreadId(threadId)
const body = this.renderPostable(message)
const token = await this.getToken(owner, repo)
@@ -417,16 +204,9 @@ export class GitHubAdapter implements Adapter<GitHubThreadId, GitHubComment> {
}
const data = (await response.json()) as GitHubComment
- return {
- id: String(data.id),
- threadId,
- raw: data,
- }
+ return { id: String(data.id), threadId, raw: data }
}
- /**
- * Delete a comment.
- */
async deleteMessage(threadId: string, messageId: string): Promise<void> {
const { owner, repo } = this.decodeThreadId(threadId)
const token = await this.getToken(owner, repo)
@@ -449,36 +229,26 @@ export class GitHubAdapter implements Adapter<GitHubThreadId, GitHubComment> {
}
}
- // ==========================================================================
- // Reactions
- // ==========================================================================
-
- /**
- * Add a reaction to a comment.
- * GitHub supports: +1, -1, laugh, confused, heart, hooray, rocket, eyes
- */
- async addReaction(
- threadId: string,
- messageId: string,
- emoji: EmojiValue | string,
- ): Promise<void> {
- const { owner, repo } = this.decodeThreadId(threadId)
+ async addReaction(threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void> {
+ const { owner, repo, issueNumber } = this.decodeThreadId(threadId)
const reaction = this.emojiToGitHubReaction(emoji)
const token = await this.getToken(owner, repo)
- const response = await fetch(
- `https://api.github.com/repos/${owner}/${repo}/issues/comments/${messageId}/reactions`,
- {
- method: 'POST',
- headers: {
- 'Authorization': `Bearer ${token}`,
- 'Accept': 'application/vnd.github.v3+json',
- 'Content-Type': 'application/json',
- 'X-GitHub-Api-Version': '2022-11-28',
- },
- body: JSON.stringify({ content: reaction }),
+ const isIssue = messageId.startsWith('issue:')
+ const url = isIssue
+ ? `https://api.github.com/repos/${owner}/${repo}/issues/${issueNumber}/reactions`
+ : `https://api.github.com/repos/${owner}/${repo}/issues/comments/${messageId}/reactions`
+
+ const response = await fetch(url, {
+ method: 'POST',
+ headers: {
+ 'Authorization': `Bearer ${token}`,
+ 'Accept': 'application/vnd.github.v3+json',
+ 'Content-Type': 'application/json',
+ 'X-GitHub-Api-Version': '2022-11-28',
},
- )
+ body: JSON.stringify({ content: reaction }),
+ })
if (!response.ok) {
const error = await response.text()
@@ -486,34 +256,25 @@ export class GitHubAdapter implements Adapter<GitHubThreadId, GitHubComment> {
}
}
- /**
- * Remove a reaction from a comment.
- * Note: GitHub requires the reaction ID, so we need to list reactions first.
- */
- async removeReaction(
- threadId: string,
- messageId: string,
- emoji: EmojiValue | string,
- ): Promise<void> {
- const { owner, repo } = this.decodeThreadId(threadId)
+ async removeReaction(threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void> {
+ const { owner, repo, issueNumber } = this.decodeThreadId(threadId)
const reaction = this.emojiToGitHubReaction(emoji)
const token = await this.getToken(owner, repo)
- // First, list reactions to find our reaction ID
- const listResponse = await fetch(
- `https://api.github.com/repos/${owner}/${repo}/issues/comments/${messageId}/reactions`,
- {
- headers: {
- 'Authorization': `Bearer ${token}`,
- 'Accept': 'application/vnd.github.v3+json',
- 'X-GitHub-Api-Version': '2022-11-28',
- },
+ const isIssue = messageId.startsWith('issue:')
+ const baseUrl = isIssue
+ ? `https://api.github.com/repos/${owner}/${repo}/issues/${issueNumber}/reactions`
+ : `https://api.github.com/repos/${owner}/${repo}/issues/comments/${messageId}/reactions`
+
+ const listResponse = await fetch(baseUrl, {
+ headers: {
+ 'Authorization': `Bearer ${token}`,
+ 'Accept': 'application/vnd.github.v3+json',
+ 'X-GitHub-Api-Version': '2022-11-28',
},
- )
+ })
- if (!listResponse.ok) {
- return // Silently fail if we can't list reactions
- }
+ if (!listResponse.ok) return
const reactions = (await listResponse.json()) as Array<{
id: number
@@ -521,37 +282,25 @@ export class GitHubAdapter implements Adapter<GitHubThreadId, GitHubComment> {
user: { login: string }
}>
- // Find our reaction (by bot username and emoji type)
- // Note: For GitHub Apps, the username is "app-name[bot]"
const botUserName = `${this.userName}[bot]`
const ourReaction = reactions.find(
r => r.content === reaction && (r.user.login === this.userName || r.user.login === botUserName),
)
- if (!ourReaction) {
- return // Reaction not found
- }
+ if (!ourReaction) return
- // Delete the reaction
- await fetch(
- `https://api.github.com/repos/${owner}/${repo}/issues/comments/${messageId}/reactions/${ourReaction.id}`,
- {
- method: 'DELETE',
- headers: {
- 'Authorization': `Bearer ${token}`,
- 'Accept': 'application/vnd.github.v3+json',
- 'X-GitHub-Api-Version': '2022-11-28',
- },
+ await fetch(`${baseUrl}/${ourReaction.id}`, {
+ method: 'DELETE',
+ headers: {
+ 'Authorization': `Bearer ${token}`,
+ 'Accept': 'application/vnd.github.v3+json',
+ 'X-GitHub-Api-Version': '2022-11-28',
},
- )
+ })
}
- /**
- * Convert chat-sdk emoji to GitHub reaction string.
- */
private emojiToGitHubReaction(emoji: EmojiValue | string): string {
const name = typeof emoji === 'string' ? emoji : emoji.name
-
const mapping: Record<string, string> = {
thumbs_up: '+1',
thumbs_down: '-1',
@@ -561,49 +310,21 @@ export class GitHubAdapter implements Adapter<GitHubThreadId, GitHubComment> {
party: 'hooray',
rocket: 'rocket',
eyes: 'eyes',
- // Default to eyes for unknown emoji
}
-
return mapping[name] || 'eyes'
}
- // ==========================================================================
- // Typing Indicator
- // ==========================================================================
-
- /**
- * GitHub doesn't support typing indicators.
- * We use a reaction as a workaround (eyes emoji).
- */
- async startTyping(_threadId: string): Promise<void> {
- // GitHub doesn't have typing indicators
- // Could potentially add/remove a reaction as visual feedback
- }
+ async startTyping(): Promise<void> {}
- // ==========================================================================
- // Fetch Operations
- // ==========================================================================
-
- /**
- * Fetch comments from an issue.
- */
- async fetchMessages(
- threadId: string,
- options?: FetchOptions,
- ): Promise<FetchResult<GitHubComment>> {
+ async fetchMessages(threadId: string, options?: FetchOptions): Promise<FetchResult<GitHubComment>> {
const { owner, repo, issueNumber } = this.decodeThreadId(threadId)
const limit = options?.limit || 30
const direction = options?.direction || 'backward'
- // GitHub uses page-based pagination
let url = `https://api.github.com/repos/${owner}/${repo}/issues/${issueNumber}/comments?per_page=${limit}`
-
if (options?.cursor) {
url += `&page=${options.cursor}`
}
-
- // GitHub sorts ascending by default (oldest first)
- // For backward (most recent), we'd need to calculate the last page
url += '&sort=created&direction=asc'
const token = await this.getToken(owner, repo)
@@ -623,7 +344,6 @@ export class GitHubAdapter implements Adapter<GitHubThreadId, GitHubComment> {
const comments = (await response.json()) as GitHubComment[]
- // Parse Link header for pagination
const linkHeader = response.headers.get('Link')
let nextCursor: string | undefined
@@ -636,20 +356,13 @@ export class GitHubAdapter implements Adapter<GitHubThreadId, GitHubComment> {
const messages = comments.map(comment => this.parseMessage(comment))
- // Reverse if backward direction to get most recent first
if (direction === 'backward') {
messages.reverse()
}
- return {
- messages,
- nextCursor,
- }
+ return { messages, nextCursor }
}
- /**
- * Fetch thread (issue) metadata.
- */
async fetchThread(threadId: string): Promise<ThreadInfo> {
const { owner, repo, issueNumber } = this.decodeThreadId(threadId)
const token = await this.getToken(owner, repo)
@@ -690,28 +403,10 @@ export class GitHubAdapter implements Adapter<GitHubThreadId, GitHubComment> {
}
}
- /**
- * Fetch full issue context for AI agent.
- * Includes title, body, labels, and recent comments.
- */
- async fetchIssueContext(threadId: string): Promise<{
- number: number
- title: string
- body: string | null
- labels: string[]
- state: string
- owner: string
- repo: string
- previousComments?: Array<{
- author: string
- body: string
- isBot: boolean
- }>
- }> {
+ async fetchIssueContext(threadId: string): Promise<IssueContext> {
const { owner, repo, issueNumber } = this.decodeThreadId(threadId)
const token = await this.getToken(owner, repo)
- // Fetch issue details
const issueResponse = await fetch(
`https://api.github.com/repos/${owner}/${repo}/issues/${issueNumber}`,
{
@@ -736,7 +431,6 @@ export class GitHubAdapter implements Adapter<GitHubThreadId, GitHubComment> {
labels: Array<{ name: string }>
}
- // Fetch recent comments for context
const commentsResponse = await fetch(
`https://api.github.com/repos/${owner}/${repo}/issues/${issueNumber}/comments?per_page=10&sort=created&direction=desc`,
{
@@ -774,23 +468,11 @@ export class GitHubAdapter implements Adapter<GitHubThreadId, GitHubComment> {
}
}
- // ==========================================================================
- // Thread ID Encoding
- // ==========================================================================
-
- /**
- * Encode platform data into a thread ID string.
- * Format: github:{owner}/{repo}:issue:{number}
- */
encodeThreadId(data: GitHubThreadId): string {
return `github:${data.owner}/${data.repo}:issue:${data.issueNumber}`
}
- /**
- * Decode thread ID string back to platform data.
- */
decodeThreadId(threadId: string): GitHubThreadId {
- // Format: github:{owner}/{repo}:issue:{number}
const match = threadId.match(/^github:([^/]+)\/([^:]+):issue:(\d+)$/)
if (!match || !match[1] || !match[2] || !match[3]) {
throw new Error(`Invalid GitHub thread ID: ${threadId}`)
@@ -803,17 +485,10 @@ export class GitHubAdapter implements Adapter<GitHubThreadId, GitHubComment> {
}
}
- // ==========================================================================
- // Message Parsing & Formatting
- // ==========================================================================
-
- /**
- * Parse a GitHub comment into a normalized Message.
- */
parseMessage(raw: GitHubComment): Message<GitHubComment> {
return new Message<GitHubComment>({
id: String(raw.id),
- threadId: '', // Will be set by caller
+ threadId: '',
text: raw.body,
formatted: this.formatConverter.toAst(raw.body),
raw,
@@ -822,62 +497,32 @@ export class GitHubAdapter implements Adapter<GitHubThreadId, GitHubComment> {
userName: raw.user.login,
fullName: raw.user.login,
isBot: raw.user.type === 'Bot',
- // For GitHub Apps, the username is "app-slug[bot]"
isMe: raw.user.login === this.userName || raw.user.login === `${this.userName}[bot]`,
},
metadata: {
dateSent: new Date(raw.created_at),
edited: raw.created_at !== raw.updated_at,
- editedAt:
- raw.created_at !== raw.updated_at
- ? new Date(raw.updated_at)
- : undefined,
+ editedAt: raw.created_at !== raw.updated_at ? new Date(raw.updated_at) : undefined,
},
- attachments: [], // GitHub comments can have inline images but we don't extract them
+ attachments: [],
})
}
- /**
- * Render formatted content to GitHub Flavored Markdown.
- */
renderFormatted(content: FormattedContent): string {
return this.formatConverter.fromAst(content)
}
- /**
- * Render a postable message to a string.
- */
private renderPostable(message: AdapterPostableMessage): string {
- if (typeof message === 'string') {
- return message
- }
-
- if ('raw' in message) {
- return message.raw
- }
-
- if ('markdown' in message) {
- return message.markdown
- }
-
- if ('ast' in message) {
- return this.formatConverter.fromAst(message.ast)
- }
-
- if ('card' in message) {
- // GitHub doesn't support rich cards, render as markdown
- throw new NotImplementedError('Cards are not supported on GitHub')
- }
-
- // CardElement directly
+ if (typeof message === 'string') return message
+ if ('raw' in message) return message.raw
+ if ('markdown' in message) return message.markdown
+ if ('ast' in message) return this.formatConverter.fromAst(message.ast)
+ if ('card' in message) throw new NotImplementedError('Cards are not supported on GitHub')
throw new NotImplementedError('Cards are not supported on GitHub')
}
}
-/**
- * Create a new GitHubAdapter instance.
- */
export function createGitHubAdapter(config: GitHubAdapterConfig): GitHubAdapter {
return new GitHubAdapter(config)
}
diff --git a/apps/github-bot/server/utils/ai.ts b/apps/github-bot/server/utils/ai.ts
index cabbac7..6d55acf 100644
--- a/apps/github-bot/server/utils/ai.ts
+++ b/apps/github-bot/server/utils/ai.ts
@@ -1,244 +1,158 @@
-/**
- * AI Agent for GitHub Bot
- *
- * Uses AI SDK's generateText with Savoir SDK tools to answer questions
- * by searching and reading documentation iteratively.
- */
-
-import { ToolLoopAgent, stepCountIs } from 'ai'
-import { gateway } from '@ai-sdk/gateway'
+import { ToolLoopAgent } from 'ai'
+import { log } from 'evlog'
import { createSavoir } from '@savoir/sdk'
+import type { IssueContext } from './types'
-/**
- * Issue context for the AI agent
- */
-export interface IssueContext {
- /** Issue number */
- number: number
- /** Issue title */
- title: string
- /** Issue body/description */
- body: string | null
- /** Issue labels */
- labels: string[]
- /** Issue state (open/closed) */
- state: string
- /** Repository owner */
- owner: string
- /** Repository name */
- repo: string
- /** Previous comments in the thread (for context) */
- previousComments?: Array<{
- author: string
- body: string
- isBot: boolean
- }>
-}
-
-/**
- * Generate an AI response using the Savoir SDK tools.
- *
- * This function:
- * 1. Creates a Savoir client with documentation tools
- * 2. Uses the AI SDK to generate a response with tool calling
- * 3. The agent can search and read documentation iteratively
- *
- * @param question - The user's question/message
- * @param context - Full context from the GitHub issue
- * @returns A markdown-formatted response
- */
export async function generateAIResponse(
question: string,
context?: IssueContext,
): Promise<string> {
const config = useRuntimeConfig()
- // Check if Savoir API is configured
if (!config.savoir.apiUrl) {
- return formatNoConfigResponse()
+ return `Hello! I'm the documentation bot, but I'm not fully configured yet.
+
+Please set the following environment variables:
+- \`NUXT_SAVOIR_API_URL\` - URL of the Savoir chat API
+- \`NUXT_SAVOIR_API_KEY\` - API key (if required)
+
+Once configured, I'll be able to search the documentation and help answer your questions!`
}
+ const startTime = Date.now()
+ let stepCount = 0
+ let totalInputTokens = 0
+ let totalOutputTokens = 0
+ let toolCallCount = 0
+
try {
- console.log('[ai] Creating Savoir SDK instance...')
+ log.info('github-bot', `Starting agent for issue #${context?.number || 'unknown'}`)
- // Create Savoir SDK instance with tools
const savoir = createSavoir({
apiUrl: config.savoir.apiUrl,
apiKey: config.savoir.apiKey || undefined,
onToolCall: (info) => {
- console.log(`[ai] Tool ${info.toolName} called:`, info.args)
+ if (info.state === 'loading') {
+ log.info('github-bot', `bash: ${JSON.stringify(info.args).slice(0, 150)}`)
+ }
},
})
- // Build the system prompt with context
- const systemPrompt = buildSystemPrompt(context)
-
- // Build the user message
- const userMessage = buildUserMessage(question, context)
-
- console.log('[ai] Creating ToolLoopAgent...')
- console.log('[ai] User message:', userMessage.slice(0, 200))
-
- // Create agent with ToolLoopAgent
const agent = new ToolLoopAgent({
model: 'google/gemini-3-flash',
- instructions: systemPrompt,
- tools: savoir.tools as any,
- onStepFinish: ({ usage, finishReason, toolCalls }) => {
- console.log('[ai] Step completed:', {
- inputTokens: usage.inputTokens,
- outputTokens: usage.outputTokens,
- finishReason,
- toolsUsed: toolCalls?.map(tc => tc.toolName),
- })
+ instructions: buildSystemPrompt(context),
+ tools: { bash: savoir.tools.bash } as any,
+ onStepFinish: ({ usage, toolCalls }) => {
+ stepCount++
+ totalInputTokens += usage.inputTokens || 0
+ totalOutputTokens += usage.outputTokens || 0
+ toolCallCount += toolCalls?.length || 0
},
})
- // Generate response
const result = await agent.generate({
- prompt: userMessage,
+ prompt: buildUserMessage(question, context),
})
- console.log('[ai] Response generated:', result.text?.slice(0, 100))
+ const durationMs = Date.now() - startTime
+ log.info('github-bot', `Response generated (${durationMs}ms, ${stepCount} steps, ${toolCallCount} commands)`)
+ log.info('github-bot', `Tokens: ${totalInputTokens} in / ${totalOutputTokens} out`)
- // Return the generated response
if (!result.text) {
- return formatNoResultsResponse(question)
+ return `I searched the documentation but couldn't generate a helpful response for:
+
+> ${question}
+
+**Suggestions:**
+- Try rephrasing your question with different keywords
+- Check the official documentation directly
+- Open a discussion for more complex questions`
}
return result.text
- } catch (error) {
- console.error('[ai] Error generating response:', error)
- return formatErrorResponse(question, error)
+ }
+ catch (error) {
+ const durationMs = Date.now() - startTime
+ const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+ log.error('github-bot', `Agent failed after ${durationMs}ms: ${errorMessage}`)
+
+ return `Sorry, I encountered an error while processing your question:
+
+> ${question}
+
+<details>
+<summary>Error details</summary>
+
+\`\`\`
+${errorMessage}
+\`\`\`
+</details>
+
+Please try again later or open a discussion if this persists.`
}
}
-/**
- * Build the system prompt for the AI agent.
- */
function buildSystemPrompt(context?: IssueContext): string {
- const basePrompt = `You are a helpful documentation assistant for the Savoir project.
-Your role is to help users by searching and reading the project documentation.
-
-## Your Capabilities
-- You have access to documentation search tools
-- You can read specific files from the documentation
-- You should search for relevant information before answering
-
-## Guidelines
-- Always search the documentation first to find accurate information
-- If you find relevant documentation, cite the source file
-- Be concise but thorough in your answers
-- Use markdown formatting for better readability
-- If you can't find specific information, say so honestly
-- Suggest related topics or alternative approaches when helpful
-
-## Response Format
-- Use clear headings and bullet points when appropriate
-- Include code examples if they help explain concepts
-- Link to relevant documentation sections when possible`
+ const basePrompt = `You are a documentation assistant with bash access to a sandbox containing docs (markdown, JSON, YAML).
+
+## Speed is Important
+Minimize the number of commands. Chain commands with \`&&\` when possible.
+
+## Sandbox Structure
+Sources: \`docs/nuxt/\`, \`docs/nuxt-content/\`, \`docs/nuxt-ui/\`, \`docs/nuxt-hub/\`, \`docs/nuxt-image/\`, \`docs/nuxt-studio/\`
+
+## Efficient Pattern
+Do this in ONE command:
+\`\`\`bash
+grep -rl "term" docs/ --include="*.md" | head -5 && cat $(grep -rl "term" docs/ --include="*.md" | head -1)
+\`\`\`
+
+Or explore and search together:
+\`\`\`bash
+ls docs/ && grep -rl "keyword" docs/ --include="*.md" | head -10
+\`\`\`
+
+## Tips
+- Chain commands with \`&&\` to reduce round-trips
+- Use \`head -80\` for large files
+- 2-3 well-targeted commands is better than 10 exploratory ones
+
+## Response
+- Be concise and helpful
+- Include code examples
+- Use markdown`
if (context) {
return `${basePrompt}
-## Current Context
-You are responding to an issue in the repository: ${context.owner}/${context.repo}
-Issue #${context.number}: "${context.title}"
-Issue state: ${context.state}
-${context.labels.length > 0 ? `Labels: ${context.labels.join(', ')}` : ''}`
+Issue #${context.number}: "${context.title}" in ${context.owner}/${context.repo}`
}
return basePrompt
}
-/**
- * Build the user message with full context.
- */
function buildUserMessage(question: string, context?: IssueContext): string {
- // Clean the question (remove bot mentions)
- const cleanQuestion = question
- .replace(/@[\w-]+(\[bot\])?/gi, '')
- .trim()
-
- let message = cleanQuestion
+ const cleanQuestion = question.replace(/@[\w-]+(\[bot\])?/gi, '').trim()
+ const parts: string[] = []
- // Add issue context if available
if (context) {
- const parts: string[] = []
-
- // Add issue description if present and different from the question
- if (context.body && context.body !== cleanQuestion) {
- parts.push(`**Issue Description:**\n${context.body}`)
+ if (context.body) {
+ parts.push(`**Issue description:**\n${context.body.slice(0, 1000)}`)
}
- // Add previous comments for conversation context
- if (context.previousComments && context.previousComments.length > 0) {
- const relevantComments = context.previousComments
- .filter(c => !c.isBot) // Only human comments
- .slice(-3) // Last 3 comments
+ if (context.previousComments?.length) {
+ const relevant = context.previousComments
+ .filter(c => !c.isBot)
+ .slice(-2)
+ .map(c => `@${c.author}: ${c.body.slice(0, 200)}`)
- if (relevantComments.length > 0) {
- parts.push('**Previous Discussion:**')
- for (const comment of relevantComments) {
- parts.push(`- @${comment.author}: ${comment.body.slice(0, 200)}${comment.body.length > 200 ? '...' : ''}`)
- }
+ if (relevant.length) {
+ parts.push(`**Previous comments:**\n${relevant.join('\n')}`)
}
}
-
- if (parts.length > 0) {
- message = `${parts.join('\n\n')}\n\n**Current Question:**\n${cleanQuestion}`
- }
}
- return message
-}
-
-/**
- * Format response when no configuration is set.
- */
-function formatNoConfigResponse(): string {
- return `👋 Hello! I'm the documentation bot, but I'm not fully configured yet.
-
-Please set the following environment variables:
-- \`NUXT_SAVOIR_API_URL\` - URL of the Savoir chat API
-- \`NUXT_SAVOIR_API_KEY\` - API key (if required)
-
-Once configured, I'll be able to search the documentation and help answer your questions!`
-}
-
-/**
- * Format response when no results are found.
- */
-function formatNoResultsResponse(question: string): string {
- return `I searched the documentation but couldn't generate a helpful response for:
-
-> ${question}
-
-**Suggestions:**
-- Try rephrasing your question with different keywords
-- Check the official documentation directly
-- Open a discussion for more complex questions
-
-I'm continuously learning and improving! 🚀`
-}
-
-/**
- * Format error response.
- */
-function formatErrorResponse(question: string, error: unknown): string {
- const errorMessage = error instanceof Error ? error.message : 'Unknown error'
-
- return `Sorry, I encountered an error while processing your question:
-
-> ${question}
+ parts.push(`**Question:**\n${cleanQuestion || context?.title || 'How can I help?'}`)
-<details>
-<summary>Error details</summary>
-
-\`\`\`
-${errorMessage}
-\`\`\`
-</details>
-
-Please try again later or open a discussion if this persists.`
+ return parts.join('\n\n')
}
diff --git a/apps/github-bot/server/utils/auth.ts b/apps/github-bot/server/utils/auth.ts
new file mode 100644
index 0000000..4b6e750
--- /dev/null
+++ b/apps/github-bot/server/utils/auth.ts
@@ -0,0 +1,111 @@
+import { createSign } from 'node:crypto'
+
+const tokenCache = new Map<number, { token: string, expiresAt: Date }>()
+const installationIdCache = new Map<string, number>()
+
+function generateAppJWT(appId: string, privateKey: string): string {
+ const now = Math.floor(Date.now() / 1000)
+ const payload = {
+ iat: now - 60,
+ exp: now + 600,
+ iss: appId,
+ }
+
+ const header = { alg: 'RS256', typ: 'JWT' }
+ const headerB64 = Buffer.from(JSON.stringify(header)).toString('base64url')
+ const payloadB64 = Buffer.from(JSON.stringify(payload)).toString('base64url')
+
+ const signatureInput = `${headerB64}.${payloadB64}`
+ const sign = createSign('RSA-SHA256')
+ sign.update(signatureInput)
+ const signature = sign.sign(privateKey, 'base64url')
+
+ return `${headerB64}.${payloadB64}.${signature}`
+}
+
+async function getInstallationId(
+ appId: string,
+ privateKey: string,
+ owner: string,
+ repo: string,
+): Promise<number> {
+ const jwt = generateAppJWT(appId, privateKey)
+
+ const response = await fetch(
+ `https://api.github.com/repos/${owner}/${repo}/installation`,
+ {
+ headers: {
+ 'Authorization': `Bearer ${jwt}`,
+ 'Accept': 'application/vnd.github.v3+json',
+ 'X-GitHub-Api-Version': '2022-11-28',
+ },
+ },
+ )
+
+ if (!response.ok) {
+ const error = await response.text()
+ throw new Error(`Failed to get installation: ${response.status} ${error}`)
+ }
+
+ const data = await response.json() as { id: number }
+ return data.id
+}
+
+async function getInstallationToken(
+ appId: string,
+ privateKey: string,
+ installationId: number,
+): Promise<string> {
+ const cached = tokenCache.get(installationId)
+ if (cached && cached.expiresAt > new Date(Date.now() + 60000)) {
+ return cached.token
+ }
+
+ const jwt = generateAppJWT(appId, privateKey)
+
+ const response = await fetch(
+ `https://api.github.com/app/installations/${installationId}/access_tokens`,
+ {
+ method: 'POST',
+ headers: {
+ 'Authorization': `Bearer ${jwt}`,
+ 'Accept': 'application/vnd.github.v3+json',
+ 'X-GitHub-Api-Version': '2022-11-28',
+ },
+ },
+ )
+
+ if (!response.ok) {
+ const error = await response.text()
+ throw new Error(`Failed to get installation token: ${response.status} ${error}`)
+ }
+
+ const data = await response.json() as { token: string, expires_at: string }
+
+ tokenCache.set(installationId, {
+ token: data.token,
+ expiresAt: new Date(data.expires_at),
+ })
+
+ return data.token
+}
+
+export interface GitHubAuth {
+ getToken: (owner: string, repo: string) => Promise<string>
+}
+
+export function createGitHubAuth(appId: string, privateKey: string): GitHubAuth {
+ return {
+ async getToken(owner: string, repo: string): Promise<string> {
+ const cacheKey = `${owner}/${repo}`
+
+ let installationId = installationIdCache.get(cacheKey)
+ if (!installationId) {
+ installationId = await getInstallationId(appId, privateKey, owner, repo)
+ installationIdCache.set(cacheKey, installationId)
+ }
+
+ return getInstallationToken(appId, privateKey, installationId)
+ },
+ }
+}
diff --git a/apps/github-bot/server/utils/chat.ts b/apps/github-bot/server/utils/chat.ts
index afdd70c..60ccf38 100644
--- a/apps/github-bot/server/utils/chat.ts
+++ b/apps/github-bot/server/utils/chat.ts
@@ -1,28 +1,12 @@
-/**
- * GitHub Chat Instance
- *
- * This module creates and configures the chat-sdk Chat instance
- * with the GitHub adapter and message handlers.
- *
- * The singleton pattern ensures we reuse the same instance across requests.
- */
-
import { Chat } from 'chat'
+import { log } from 'evlog'
import { createGitHubAdapter, type GitHubAdapter } from './adapter'
-import { generateAIResponse, type IssueContext } from './ai'
+import { generateAIResponse } from './ai'
import { KVStateAdapter } from './state-kv'
+import type { IssueContext } from './types'
let chatInstance: Chat | null = null
-/**
- * Get or create the GitHub Chat instance.
- *
- * This is a singleton - the same instance is reused across all requests.
- * The Chat instance is configured with:
- * - GitHubAdapter for handling GitHub webhooks
- * - KVStateAdapter for persistent state (subscriptions, locks)
- * - Message handlers for processing mentions
- */
export function useGitHubChat(): Chat {
if (chatInstance) {
return chatInstance
@@ -30,21 +14,17 @@ export function useGitHubChat(): Chat {
const config = useRuntimeConfig()
- // Validate required config
if (!config.github.webhookSecret) {
throw new Error('NUXT_GITHUB_WEBHOOK_SECRET is required')
}
- // Extract bot username from trigger (remove @ prefix)
const botTrigger = config.public.botTrigger as string
const botUserName = botTrigger.replace('@', '')
- // Validate GitHub App credentials
if (!config.github.appId || !config.github.appPrivateKey) {
throw new Error('NUXT_GITHUB_APP_ID and NUXT_GITHUB_APP_PRIVATE_KEY are required')
}
- // Create the Chat instance
chatInstance = new Chat({
userName: botUserName,
adapters: {
@@ -59,78 +39,39 @@ export function useGitHubChat(): Chat {
logger: 'info',
})
- // ==========================================================================
- // Message Handlers
- // ==========================================================================
-
- /**
- * Handle @mentions in unsubscribed threads.
- *
- * This is the main entry point for the bot. When someone mentions
- * the bot in an issue comment, we:
- * 1. Add an "eyes" reaction to show we're processing
- * 2. Search the documentation for relevant content
- * 3. Generate an AI response
- * 4. Post the response as a comment
- * 5. Update reactions to show completion
- */
chatInstance.onNewMention(async (thread, message) => {
- const logger = console
-
- logger.info(`[github-bot] New mention from @${message.author.userName}`)
- logger.info(`[github-bot] Message: ${message.text.slice(0, 100)}...`)
-
try {
- // Add "eyes" reaction to indicate we're processing
const adapter = thread.adapter as GitHubAdapter
await adapter.addReaction(thread.id, message.id, 'eyes')
- // Fetch full issue context for the AI agent
let issueContext: IssueContext | undefined
try {
issueContext = await adapter.fetchIssueContext(thread.id)
- logger.info(`[github-bot] Fetched issue context: "${issueContext.title}"`)
- } catch (err) {
- logger.warn(`[github-bot] Could not fetch issue context:`, err)
+ }
+ catch {
+ // Continue without issue context
}
- // Generate AI response with full context
const response = await generateAIResponse(message.text, issueContext)
- // Post the response
await thread.post({ markdown: response })
- // Update reactions: remove eyes, add checkmark
await adapter.removeReaction(thread.id, message.id, 'eyes')
await adapter.addReaction(thread.id, message.id, 'thumbs_up')
+ }
+ catch (error) {
+ log.error('github-bot', `Error: ${error instanceof Error ? error.message : 'Unknown'}`)
- logger.info(`[github-bot] Response posted successfully`)
- } catch (error) {
- logger.error(`[github-bot] Error processing message:`, error)
-
- // Try to post an error message
try {
await thread.post({
markdown: `Sorry, I encountered an error while processing your request. Please try again later.\n\n<details>\n<summary>Error details</summary>\n\n\`\`\`\n${error instanceof Error ? error.message : 'Unknown error'}\n\`\`\`\n</details>`,
})
- } catch {
+ }
+ catch {
// Ignore error posting failure
}
}
})
- /**
- * Handle messages in subscribed threads (optional).
- *
- * If you want the bot to continue responding in a thread after
- * the initial mention, you can subscribe to the thread and handle
- * follow-up messages here.
- *
- * For now, we don't subscribe - each interaction requires a new @mention.
- */
- // chatInstance.onSubscribedMessage(async (thread, message) => {
- // // Handle follow-up messages in subscribed threads
- // });
-
return chatInstance
}
diff --git a/apps/github-bot/server/utils/markdown.ts b/apps/github-bot/server/utils/markdown.ts
index 1fbc411..e249c27 100644
--- a/apps/github-bot/server/utils/markdown.ts
+++ b/apps/github-bot/server/utils/markdown.ts
@@ -1,40 +1,11 @@
-/**
- * GitHubFormatConverter - Markdown format converter for GitHub
- *
- * Converts between GitHub Flavored Markdown (GFM) and mdast AST.
- * GFM is very close to standard markdown, so we use the standard
- * mdast utilities with GFM extensions.
- */
-
import type { Root } from 'mdast'
import { fromMarkdown } from 'mdast-util-from-markdown'
import { gfmFromMarkdown, gfmToMarkdown } from 'mdast-util-gfm'
import { toMarkdown } from 'mdast-util-to-markdown'
import { gfm } from 'micromark-extension-gfm'
-/**
- * Format converter for GitHub Flavored Markdown.
- *
- * GFM adds the following extensions to standard markdown:
- * - Autolinks (URLs and emails)
- * - Strikethrough (~~text~~)
- * - Tables
- * - Task lists (- [ ] / - [x])
- */
export class GitHubFormatConverter {
- /**
- * Parse GitHub Flavored Markdown to mdast AST.
- *
- * @param text - The GFM text to parse
- * @returns The mdast AST
- *
- * @example
- * ```typescript
- * const ast = converter.toAst("Hello **world**");
- * // { type: "root", children: [{ type: "paragraph", ... }] }
- * ```
- */
toAst(text: string): Root {
return fromMarkdown(text, {
extensions: [gfm()],
@@ -42,48 +13,10 @@ export class GitHubFormatConverter {
})
}
- /**
- * Convert mdast AST back to GitHub Flavored Markdown.
- *
- * @param ast - The mdast AST to convert
- * @returns The GFM text
- *
- * @example
- * ```typescript
- * const text = converter.fromAst(ast);
- * // "Hello **world**"
- * ```
- */
fromAst(ast: Root): string {
return toMarkdown(ast, {
extensions: [gfmToMarkdown()],
})
}
- /**
- * Extract plain text from markdown, stripping all formatting.
- *
- * @param text - The markdown text
- * @returns Plain text without formatting
- */
- toPlainText(text: string): string {
- const ast = this.toAst(text)
- return this.extractText(ast)
- }
-
- /**
- * Recursively extract text content from an AST node.
- */
- private extractText(node: Root | Root['children'][number]): string {
- if ('value' in node && typeof node.value === 'string') {
- return node.value
- }
-
- if ('children' in node && Array.isArray(node.children)) {
- return node.children.map(child => this.extractText(child)).join('')
- }
-
- return ''
- }
-
}
diff --git a/apps/github-bot/server/utils/state-kv.ts b/apps/github-bot/server/utils/state-kv.ts
index 312f26f..0cd2000 100644
--- a/apps/github-bot/server/utils/state-kv.ts
+++ b/apps/github-bot/server/utils/state-kv.ts
@@ -1,66 +1,26 @@
-/**
- * KVStateAdapter - StateAdapter implementation using NuxtHub KV
- *
- * This adapter demonstrates how to implement chat-sdk's StateAdapter interface
- * using NuxtHub's KV storage instead of Redis.
- *
- * Key prefixes:
- * - chat:sub:{threadId} - Thread subscriptions
- * - chat:lock:{threadId} - Distributed locks
- * - chat:cache:{key} - General cache
- */
-
import type { Lock, StateAdapter } from 'chat'
import { kv } from 'hub:kv'
export class KVStateAdapter implements StateAdapter {
- private connected = false
-
- /**
- * Connect to the state backend.
- * For KV, this is a no-op since KV is always available.
- */
- async connect(): Promise<void> {
- this.connected = true
- }
-
- /**
- * Disconnect from the state backend.
- */
- async disconnect(): Promise<void> {
- this.connected = false
- }
+
+ async connect(): Promise<void> {}
- // =========================================================================
- // Subscriptions
- // =========================================================================
+
+ async disconnect(): Promise<void> {}
- /**
- * Subscribe to a thread. Subscribed threads will receive all messages
- * via onSubscribedMessage handlers.
- */
async subscribe(threadId: string): Promise<void> {
await kv.set(`chat:sub:${threadId}`, true)
}
- /**
- * Unsubscribe from a thread.
- */
async unsubscribe(threadId: string): Promise<void> {
await kv.del(`chat:sub:${threadId}`)
}
- /**
- * Check if a thread is subscribed.
- */
async isSubscribed(threadId: string): Promise<boolean> {
return await kv.has(`chat:sub:${threadId}`)
}
- /**
- * List all subscriptions, optionally filtered by adapter name.
- */
async *listSubscriptions(adapterName?: string): AsyncIterable<string> {
const keys = await kv.keys('chat:sub:')
for (const key of keys) {
@@ -71,51 +31,33 @@ export class KVStateAdapter implements StateAdapter {
}
}
- // =========================================================================
- // Distributed Locking
- // =========================================================================
-
- /**
- * Acquire a lock on a thread. Returns null if already locked.
- * Used to prevent concurrent message processing on the same thread.
- */
async acquireLock(threadId: string, ttlMs: number): Promise<Lock | null> {
const key = `chat:lock:${threadId}`
const existing = await kv.get<Lock>(key)
- // Check if lock exists and hasn't expired
if (existing && existing.expiresAt > Date.now()) {
return null
}
- // Create new lock
const lock: Lock = {
threadId,
token: `kv_${Date.now()}_${Math.random().toString(36).slice(2)}`,
expiresAt: Date.now() + ttlMs,
}
- // Store with TTL (NuxtHub KV uses seconds)
await kv.set(key, lock, { ttl: Math.ceil(ttlMs / 1000) })
return lock
}
- /**
- * Release a lock. Only the lock owner (matching token) can release.
- */
async releaseLock(lock: Lock): Promise<void> {
const key = `chat:lock:${lock.threadId}`
const existing = await kv.get<Lock>(key)
- // Only delete if token matches (we own the lock)
if (existing && existing.token === lock.token) {
await kv.del(key)
}
}
- /**
- * Extend a lock's TTL. Returns false if lock expired or token doesn't match.
- */
async extendLock(lock: Lock, ttlMs: number): Promise<boolean> {
const key = `chat:lock:${lock.threadId}`
const existing = await kv.get<Lock>(key)
@@ -125,48 +67,26 @@ export class KVStateAdapter implements StateAdapter {
}
if (existing.expiresAt < Date.now()) {
- // Lock has already expired
await kv.del(key)
return false
}
- // Extend the lock
existing.expiresAt = Date.now() + ttlMs
await kv.set(key, existing, { ttl: Math.ceil(ttlMs / 1000) })
return true
}
- // =========================================================================
- // Cache
- // =========================================================================
-
- /**
- * Get a cached value by key.
- */
async get<T = unknown>(key: string): Promise<T | null> {
return await kv.get<T>(`chat:cache:${key}`)
}
- /**
- * Set a cached value with optional TTL in milliseconds.
- */
- async set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<void> {
+ async set(key: string, value: unknown, ttlMs?: number): Promise<void> {
const opts = ttlMs ? { ttl: Math.ceil(ttlMs / 1000) } : undefined
- await kv.set(`chat:cache:${key}`, value, opts)
+ await kv.set(`chat:cache:${key}`, value as string, opts)
}
- /**
- * Delete a cached value.
- */
async delete(key: string): Promise<void> {
await kv.del(`chat:cache:${key}`)
}
}
-
-/**
- * Create a new KVStateAdapter instance.
- */
-export function createKVState(): KVStateAdapter {
- return new KVStateAdapter()
-}
diff --git a/apps/github-bot/server/utils/types.ts b/apps/github-bot/server/utils/types.ts
new file mode 100644
index 0000000..dcdfc00
--- /dev/null
+++ b/apps/github-bot/server/utils/types.ts
@@ -0,0 +1,104 @@
+export interface GitHubThreadId {
+ owner: string
+ repo: string
+ issueNumber: number
+}
+
+export interface GitHubComment {
+ id: number
+ node_id: string
+ body: string
+ user: {
+ id: number
+ login: string
+ avatar_url: string
+ type: string
+ }
+ created_at: string
+ updated_at: string
+ html_url: string
+ issue_url: string
+}
+
+export interface GitHubIssueCommentPayload {
+ action: 'created' | 'edited' | 'deleted'
+ issue: {
+ number: number
+ title: string
+ state: string
+ body: string | null
+ user: {
+ id: number
+ login: string
+ }
+ }
+ comment: GitHubComment
+ repository: {
+ id: number
+ name: string
+ full_name: string
+ owner: {
+ login: string
+ }
+ }
+ sender: {
+ id: number
+ login: string
+ type: string
+ }
+}
+
+export interface GitHubIssuesPayload {
+ action: 'opened' | 'edited' | 'deleted' | 'closed' | 'reopened' | 'labeled' | 'unlabeled' | 'assigned' | 'unassigned'
+ issue: {
+ id: number
+ number: number
+ title: string
+ state: string
+ body: string | null
+ user: {
+ id: number
+ login: string
+ avatar_url: string
+ }
+ labels: Array<{ name: string }>
+ created_at: string
+ updated_at: string
+ html_url: string
+ }
+ repository: {
+ id: number
+ name: string
+ full_name: string
+ owner: {
+ login: string
+ }
+ }
+ sender: {
+ id: number
+ login: string
+ type: string
+ }
+}
+
+export interface GitHubAdapterConfig {
+ userName: string
+ webhookSecret: string
+ appId: string
+ appPrivateKey: string
+}
+
+export interface IssueContext {
+ number: number
+ title: string
+ body: string | null
+ labels: string[]
+ state: string
+ owner: string
+ repo: string
+ previousComments?: Array<{
+ author: string
+ body: string
+ isBot: boolean
+ }>
+}
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index 1e0834a..86b09bc 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -1,8 +1,7 @@
import { createError } from 'evlog'
import type {
- ReadResponse,
SavoirConfig,
- SearchAndReadResponse,
+ ShellResponse,
SnapshotResponse,
SourcesResponse,
SyncOptions,
@@ -141,24 +140,11 @@ export class SavoirClient {
}
/**
- * Search for content and return matching files
+ * Run a bash command in the sandbox
*/
- async searchAndRead(
- query: string,
- limit: number = 20,
- ): Promise<SearchAndReadResponse> {
- return await this.post<SearchAndReadResponse>('/api/sandbox/search-and-read', {
- query,
- limit,
- })
- }
-
- /**
- * Read specific files by path
- */
- async read(paths: string[]): Promise<ReadResponse> {
- return await this.post<ReadResponse>('/api/sandbox/read', {
- paths,
+ async bash(command: string): Promise<ShellResponse> {
+ return await this.post<ShellResponse>('/api/sandbox/shell', {
+ command,
})
}
diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts
index 0ca563b..de99b0c 100644
--- a/packages/sdk/src/index.ts
+++ b/packages/sdk/src/index.ts
@@ -1,8 +1,8 @@
import { SavoirClient } from './client'
-import { createReadTool, createSearchAndReadTool } from './tools'
+import { createBashTool } from './tools'
import type { SavoirConfig, ToolCallCallback } from './types'
-export type { SavoirConfig, SearchResult, FileContent, SearchAndReadResponse, ReadResponse, SyncOptions, SyncResponse, SnapshotResponse, GitHubSource, YouTubeSource, SourcesResponse, SyncSourceResponse, ToolCallInfo, ToolCallCallback, ToolCallState } from './types'
+export type { SavoirConfig, ShellResponse, SyncOptions, SyncResponse, SnapshotResponse, GitHubSource, YouTubeSource, SourcesResponse, SyncSourceResponse, ToolCallInfo, ToolCallCallback, ToolCallState } from './types'
export { SavoirError, NetworkError } from './errors'
export { SavoirClient } from './client'
@@ -19,8 +19,8 @@ export interface Savoir {
* AI SDK tools
*/
tools: {
- search_and_read: ReturnType<typeof createSearchAndReadTool>
- read: ReturnType<typeof createReadTool>
+ /** Execute bash commands in the sandbox */
+ bash: ReturnType<typeof createBashTool>
}
/**
@@ -65,8 +65,7 @@ export function createSavoir(config: SavoirConfig): Savoir {
return {
client,
tools: {
- search_and_read: createSearchAndReadTool(client, onToolCall),
- read: createReadTool(client, onToolCall),
+ bash: createBashTool(client, onToolCall),
},
getSessionId: () => client.getSessionId(),
setSessionId: (sessionId: string) => client.setSessionId(sessionId),
diff --git a/packages/sdk/src/tools/index.ts b/packages/sdk/src/tools/index.ts
index 0b1989e..96f5848 100644
--- a/packages/sdk/src/tools/index.ts
+++ b/packages/sdk/src/tools/index.ts
@@ -1,2 +1 @@
-export { createSearchAndReadTool } from './search-and-read'
-export { createReadTool } from './read'
+export { createBashTool } from './shell'
diff --git a/packages/sdk/src/tools/read.ts b/packages/sdk/src/tools/read.ts
deleted file mode 100644
index 73671d0..0000000
--- a/packages/sdk/src/tools/read.ts
+++ /dev/null
@@ -1,44 +0,0 @@
-import { tool } from 'ai'
-import { z } from 'zod'
-import type { SavoirClient } from '../client'
-import type { ToolCallCallback } from '../types'
-
-/**
- * Create the read tool for AI SDK
- */
-export function createReadTool(client: SavoirClient, onToolCall?: ToolCallCallback) {
- return tool({
- description: `Read specific documentation files by their paths.
-Use this tool when you know the exact file paths you want to read.
-Returns the full content of each requested file.`,
- inputSchema: z.object({
- paths: z.array(z.string()).min(1).max(50).describe('Array of file paths to read'),
- }),
- onInputAvailable: ({ toolCallId, input }) => {
- onToolCall?.({
- toolCallId,
- toolName: 'read',
- args: input,
- state: 'loading',
- })
- },
- execute: async ({ paths }, { toolCallId }) => {
- const result = await client.read(paths)
-
- onToolCall?.({
- toolCallId,
- toolName: 'read',
- args: { paths },
- state: 'done',
- })
-
- return {
- fileCount: result.files.length,
- files: result.files.map(f => ({
- path: f.path,
- content: f.content,
- })),
- }
- },
- })
-}
diff --git a/packages/sdk/src/tools/search-and-read.ts b/packages/sdk/src/tools/search-and-read.ts
deleted file mode 100644
index 9165da5..0000000
--- a/packages/sdk/src/tools/search-and-read.ts
+++ /dev/null
@@ -1,51 +0,0 @@
-import { tool } from 'ai'
-import { z } from 'zod'
-import type { SavoirClient } from '../client'
-import type { ToolCallCallback } from '../types'
-
-/**
- * Create the searchAndRead tool for AI SDK
- */
-export function createSearchAndReadTool(client: SavoirClient, onToolCall?: ToolCallCallback) {
- return tool({
- description: `Search the documentation for content matching a query and return the full file contents.
-Use this tool to find relevant documentation about a topic.
-Returns both the matching lines with context and the complete file contents for deeper understanding.`,
- inputSchema: z.object({
- query: z.string().describe('The search query (supports regex patterns)'),
- limit: z.number().int().min(1).max(100).default(20).describe('Maximum number of results to return'),
- }),
- onInputAvailable: ({ toolCallId, input }) => {
- onToolCall?.({
- toolCallId,
- toolName: 'search_and_read',
- args: input,
- state: 'loading',
- })
- },
- execute: async ({ query, limit }, { toolCallId }) => {
- const result = await client.searchAndRead(query, limit)
-
- onToolCall?.({
- toolCallId,
- toolName: 'search_and_read',
- args: { query, limit },
- state: 'done',
- })
-
- return {
- matchCount: result.matches.length,
- fileCount: result.files.length,
- matches: result.matches.map(m => ({
- path: m.path,
- line: m.lineNumber,
- content: m.content,
- })),
- files: result.files.map(f => ({
- path: f.path,
- content: f.content,
- })),
- }
- },
- })
-}
diff --git a/packages/sdk/src/tools/shell.ts b/packages/sdk/src/tools/shell.ts
new file mode 100644
index 0000000..361abca
--- /dev/null
+++ b/packages/sdk/src/tools/shell.ts
@@ -0,0 +1,41 @@
+import { tool } from 'ai'
+import { z } from 'zod'
+import type { SavoirClient } from '../client'
+import type { ToolCallCallback } from '../types'
+
+/**
+ * Create the bash tool for AI SDK - runs commands in the sandbox
+ */
+export function createBashTool(client: SavoirClient, onToolCall?: ToolCallCallback) {
+ return tool({
+ description: `Execute a bash command in the documentation sandbox.
+Use standard Unix commands to explore and read files.`,
+ inputSchema: z.object({
+ command: z.string().describe('Bash command to execute'),
+ }),
+ onInputAvailable: ({ toolCallId, input }) => {
+ onToolCall?.({
+ toolCallId,
+ toolName: 'bash',
+ args: input,
+ state: 'loading',
+ })
+ },
+ execute: async ({ command }, { toolCallId }) => {
+ const result = await client.bash(command)
+
+ onToolCall?.({
+ toolCallId,
+ toolName: 'bash',
+ args: { command },
+ state: 'done',
+ })
+
+ return {
+ stdout: result.stdout,
+ stderr: result.stderr,
+ exitCode: result.exitCode,
+ }
+ },
+ })
+}
diff --git a/packages/sdk/src/types.ts b/packages/sdk/src/types.ts
index 4cc314a..3be55cb 100644
--- a/packages/sdk/src/types.ts
+++ b/packages/sdk/src/types.ts
@@ -57,10 +57,15 @@ export interface SearchResult {
/**
* File content from the Savoir API
+ * When from search-and-read, contains context snippets around matches
*/
export interface FileContent {
path: string
content: string
+ /** Number of matches in this file (for context snippets) */
+ matchCount?: number
+ /** Total lines in the file (for context snippets) */
+ totalLines?: number
}
/**
@@ -80,6 +85,16 @@ export interface ReadResponse {
files: FileContent[]
}
+/**
+ * Response from the shell endpoint
+ */
+export interface ShellResponse {
+ sessionId: string
+ stdout: string
+ stderr: string
+ exitCode: number
+}
+
/**
* Error response from the Savoir API
*/