typeclaw 0.17.0 → 0.19.0

package/src/channels/adapters/github/auth-app.ts

@@ -2,33 +2,43 @@ import { createPrivateKey } from 'node:crypto'
 
 import { resolveSecret, type Secret } from '@/secrets/resolve'
 
-import type { GithubAuthStrategy, GithubInstallationGrants, GithubSelfUser } from './auth'
+import type { GithubAuthContext, GithubAuthStrategy, GithubInstallationGrants, GithubSelfUser } from './auth'
 import { GITHUB_API_BASE, githubJsonHeaders, githubPublicHeaders } from './auth-pat'
 
+type TokenCacheEntry = { value: string; expiresAt: number }
+
 export class AppAuthStrategy implements GithubAuthStrategy {
   private readonly appId: number
   private readonly privateKeyPem: string
-  private readonly installationId: number | null
   private readonly fetchImpl: typeof fetch
-  private cachedToken: { value: string; expiresAt: number } | null = null
-  private resolvedInstallationId: number | null = null
+  // Keyed by installation id: a single App may span multiple owners, each a
+  // separate installation with its own short-lived token.
+  private readonly tokenCache = new Map<number, TokenCacheEntry>()
+  private readonly repoInstallationCache = new Map<string, number>()
+  private soleInstallationId: number | null = null
   private _selfUser: GithubSelfUser | null = null
 
-  constructor(options: { appId: number; privateKey: Secret; installationId?: number; fetchImpl?: typeof fetch }) {
+  constructor(options: { appId: number; privateKey: Secret; fetchImpl?: typeof fetch }) {
     const privateKeyPem = resolveSecret(options.privateKey, undefined, process.env)
     if (privateKeyPem === undefined || privateKeyPem.trim() === '') throw new Error('GitHub App private key is missing')
     this.appId = options.appId
     this.privateKeyPem = privateKeyPem
-    this.installationId = options.installationId ?? null
     this.fetchImpl = options.fetchImpl ?? fetch
   }
 
-  async token(): Promise<string> {
-    if (this.cachedToken && Date.now() < this.cachedToken.expiresAt - 5 * 60 * 1000) {
-      return this.cachedToken.value
-    }
+  async token(context?: GithubAuthContext): Promise<string> {
     const jwt = await this.mintJwt()
-    const installId = await this.resolveInstallationId(jwt)
+    const installId = await this.resolveInstallationId(jwt, context)
+    return this.installationToken(jwt, installId)
+  }
+
+  async authHeaders(context?: GithubAuthContext): Promise<HeadersInit> {
+    return githubJsonHeaders(await this.token(context))
+  }
+
+  private async installationToken(jwt: string, installId: number): Promise<string> {
+    const cached = this.tokenCache.get(installId)
+    if (cached && Date.now() < cached.expiresAt - 5 * 60 * 1000) return cached.value
     const response = await this.fetchImpl(`${GITHUB_API_BASE}/app/installations/${installId}/access_tokens`, {
       method: 'POST',
       headers: githubJsonHeaders(jwt),
@@ -37,14 +47,10 @@ export class AppAuthStrategy implements GithubAuthStrategy {
     const raw = (await response.json()) as { token?: unknown; expires_at?: unknown }
     if (typeof raw.token !== 'string') throw new Error('GitHub App token response missing token')
     const expiresAt = typeof raw.expires_at === 'string' ? Date.parse(raw.expires_at) : Date.now() + 60 * 60 * 1000
-    this.cachedToken = { value: raw.token, expiresAt }
+    this.tokenCache.set(installId, { value: raw.token, expiresAt })
     return raw.token
   }
 
-  async authHeaders(): Promise<HeadersInit> {
-    return githubJsonHeaders(await this.token())
-  }
-
   async getSelf(): Promise<GithubSelfUser> {
     if (this._selfUser) return this._selfUser
     const jwt = await this.mintJwt()
@@ -69,9 +75,9 @@ export class AppAuthStrategy implements GithubAuthStrategy {
     return this._selfUser
   }
 
-  async getInstallationGrants(): Promise<GithubInstallationGrants> {
+  async getInstallationGrants(context?: GithubAuthContext): Promise<GithubInstallationGrants> {
     const jwt = await this.mintJwt()
-    const installId = await this.resolveInstallationId(jwt)
+    const installId = await this.resolveInstallationId(jwt, context)
     const response = await this.fetchImpl(`${GITHUB_API_BASE}/app/installations/${installId}`, {
       headers: githubJsonHeaders(jwt),
     })
@@ -88,7 +94,8 @@ export class AppAuthStrategy implements GithubAuthStrategy {
   }
 
   async dispose(): Promise<void> {
-    this.cachedToken = null
+    this.tokenCache.clear()
+    this.repoInstallationCache.clear()
   }
 
   private async mintJwt(): Promise<string> {
@@ -107,25 +114,41 @@ export class AppAuthStrategy implements GithubAuthStrategy {
     return `${signingInput}.${base64url(Buffer.from(signature))}`
   }
 
-  private async resolveInstallationId(jwt: string): Promise<number> {
-    if (this.resolvedInstallationId !== null) return this.resolvedInstallationId
-    if (this.installationId !== null) {
-      this.resolvedInstallationId = this.installationId
-      return this.installationId
+  private async resolveInstallationId(jwt: string, context?: GithubAuthContext): Promise<number> {
+    if (context?.repoSlug !== undefined && context.repoSlug !== '') {
+      return this.resolveInstallationByEndpoint(jwt, `repos/${context.repoSlug}/installation`, context.repoSlug)
+    }
+    if (context?.owner !== undefined && context.owner !== '') {
+      return this.resolveInstallationByEndpoint(jwt, `orgs/${context.owner}/installation`, context.owner)
     }
+    if (this.soleInstallationId !== null) return this.soleInstallationId
     const response = await this.fetchImpl(`${GITHUB_API_BASE}/app/installations`, { headers: githubJsonHeaders(jwt) })
     if (!response.ok) throw new Error(`GitHub App installations fetch failed: ${response.status}`)
     const list = (await response.json()) as Array<{ id?: unknown }>
     if (list.length === 0) throw new Error('GitHub App has no installations')
     if (list.length > 1) {
       const ids = list.map((installation) => installation.id).join(', ')
-      throw new Error(`GitHub App has multiple installations (${ids}); set installationId in secrets.json`)
+      throw new Error(`GitHub App has multiple installations (${ids}); a repo must be specified to select one`)
     }
     const id = list[0]?.id
     if (typeof id !== 'number') throw new Error('GitHub App installation missing id')
-    this.resolvedInstallationId = id
+    this.soleInstallationId = id
     return id
   }
+
+  private async resolveInstallationByEndpoint(jwt: string, path: string, target: string): Promise<number> {
+    const cached = this.repoInstallationCache.get(target)
+    if (cached !== undefined) return cached
+    const response = await this.fetchImpl(`${GITHUB_API_BASE}/${path}`, { headers: githubJsonHeaders(jwt) })
+    if (response.status === 404) {
+      throw new Error(`GitHub App is not installed for ${target} or lacks access to that repository`)
+    }
+    if (!response.ok) throw new Error(`GitHub App installation lookup for ${target} failed: ${response.status}`)
+    const raw = (await response.json()) as { id?: unknown }
+    if (typeof raw.id !== 'number') throw new Error(`GitHub App installation for ${target} missing id`)
+    this.repoInstallationCache.set(target, raw.id)
+    return raw.id
+  }
 }
 
 function base64url(input: string | Buffer): string {

package/src/channels/adapters/github/auth-pat.ts

@@ -1,6 +1,6 @@
 import { resolveSecret, type Secret } from '@/secrets/resolve'
 
-import type { GithubAuthStrategy, GithubSelfUser } from './auth'
+import type { GithubAuthContext, GithubAuthStrategy, GithubSelfUser } from './auth'
 
 export const GITHUB_API_BASE = 'https://api.github.com'
 
@@ -15,11 +15,11 @@ export class PatAuthStrategy implements GithubAuthStrategy {
     this.fetchImpl = options.fetchImpl ?? fetch
   }
 
-  async token(): Promise<string> {
+  async token(_context?: GithubAuthContext): Promise<string> {
     return this._token
   }
 
-  async authHeaders(): Promise<HeadersInit> {
+  async authHeaders(_context?: GithubAuthContext): Promise<HeadersInit> {
     return githubJsonHeaders(this._token)
   }
 

package/src/channels/adapters/github/auth.ts

@@ -3,15 +3,30 @@ import type { GithubAppAuthBlock, GithubPatAuthBlock } from '@/secrets/schema'
 import { AppAuthStrategy } from './auth-app'
 import { PatAuthStrategy } from './auth-pat'
 
+// Repo identity threaded through every auth call so App auth can pick the
+// correct installation. `repoSlug` is the canonical input ("owner/name"); App
+// auth resolves it to an installation via GET /repos/{owner}/{repo}/installation
+// and caches the result. PAT auth ignores it entirely. Omitted context means
+// "no specific repo" — App auth then falls back to a single discoverable
+// installation (and errors if the App spans multiple installations).
+export type GithubAuthContext = {
+  repoSlug?: string
+  // Org login, for operations that aren't repo-scoped (e.g. team-membership
+  // lookups under GET /orgs/{org}/...). App auth resolves it to an
+  // installation via GET /orgs/{org}/installation. Ignored when repoSlug is set.
+  owner?: string
+}
+
 export type GithubAuthStrategy = {
-  token: () => Promise<string>
-  authHeaders: () => Promise<HeadersInit>
+  token: (context?: GithubAuthContext) => Promise<string>
+  authHeaders: (context?: GithubAuthContext) => Promise<HeadersInit>
   getSelf: () => Promise<GithubSelfUser>
   // App-only: returns the installation's granted-permissions map and declared
   // events so the adapter can preflight against the configured eventAllowlist
   // before any webhook arrives. PATs return access via token scopes, not an
-  // installation grant, so they leave this undefined.
-  getInstallationGrants?: () => Promise<GithubInstallationGrants>
+  // installation grant, so they leave this undefined. Context selects which
+  // installation to inspect when the App spans multiple owners.
+  getInstallationGrants?: (context?: GithubAuthContext) => Promise<GithubInstallationGrants>
   dispose: () => Promise<void>
 }
 
@@ -36,7 +51,6 @@ export function buildAuthStrategy(options: {
       return new AppAuthStrategy({
         appId: options.auth.appId,
         privateKey: options.auth.privateKey,
-        installationId: options.auth.installationId,
         fetchImpl: options.fetchImpl,
       })
   }

package/src/channels/adapters/github/channel-resolver.ts

@@ -1,10 +1,11 @@
 import type { ChannelNameResolver, ResolvedChannelNames } from '@/channels/types'
 
+import type { GithubAuthContext } from './auth'
 import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
 import { parseChat, parseRepo } from './outbound'
 
 export function createGithubChannelNameResolver(options: {
-  token: () => Promise<string>
+  token: (context?: GithubAuthContext) => Promise<string>
   fetchImpl?: typeof fetch
 }): ChannelNameResolver {
   const fetchImpl = options.fetchImpl ?? fetch
@@ -18,7 +19,7 @@ export function createGithubChannelNameResolver(options: {
     const path = chat.kind === 'issue' ? `issues/${chat.number}` : `pulls/${chat.number}`
     try {
       const response = await fetchImpl(`${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/${path}`, {
-        headers: githubJsonHeaders(await options.token()),
+        headers: githubJsonHeaders(await options.token({ repoSlug: key.workspace })),
       })
       if (!response.ok) return names
       const raw = (await response.json()) as { title?: string }

package/src/channels/adapters/github/history.ts

@@ -1,10 +1,11 @@
 import type { ChannelHistoryMessage, FetchHistoryArgs, FetchHistoryResult, HistoryCallback } from '@/channels/types'
 
+import type { GithubAuthContext } from './auth'
 import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
 import { parseChat, parseRepo } from './outbound'
 
 export function createGithubHistoryCallback(options: {
-  token: () => Promise<string>
+  token: (context?: GithubAuthContext) => Promise<string>
   workspaceForChat: (chat: string) => string | null
   fetchImpl?: typeof fetch
 }): HistoryCallback {
@@ -26,7 +27,7 @@ export function createGithubHistoryCallback(options: {
       const response = await fetchImpl(
         `${endpoint}?per_page=${Math.min(Math.max(args.limit, 1), 100)}&direction=desc${cursor}`,
         {
-          headers: githubJsonHeaders(await options.token()),
+          headers: githubJsonHeaders(await options.token({ repoSlug: workspace })),
         },
       )
       if (!response.ok) return { ok: false, error: `GitHub history ${response.status}` }

package/src/channels/adapters/github/inbound.ts

@@ -13,8 +13,8 @@ export type GithubWebhookHandlerOptions = {
   allowlist: () => readonly string[]
   selfId: () => string | null
   selfLogin: () => string | null
-  // Defaults to 'pat' when omitted. Only 'app' promotes an opened PR to a
-  // review request; see classifyOpenedAsReview for why.
+  // Defaults to 'pat' when omitted. In 'app' mode classifyReviewRequest also
+  // matches the App's decoy reviewer login; see resolveDecoyReviewerLogin.
   authType?: () => 'pat' | 'app'
   route: (message: InboundMessage) => void
   logger: GithubInboundLogger
@@ -178,17 +178,10 @@ export function classifyGithubInbound(
         number,
         base,
         selfLogin,
+        authType: options?.authType ?? 'pat',
         teamIsBotMember: options?.teamIsBotMember,
       })
     }
-    // A GitHub App cannot be added to a PR's requested_reviewers, so it never
-    // receives a review_requested event targeting itself. The opened event is
-    // the only signal it can act on, so in App mode an opened PR is promoted to
-    // a review request. A PAT-backed bot is a real user that can be requested,
-    // so it waits for the explicit request instead of reviewing every PR.
-    if (action === 'opened' && options?.authType === 'app') {
-      return classifyOpenedAsReview({ payload, pr, number, base, selfLogin })
-    }
     return buildInbound(
       { ...base, chat: `pr:${number}`, thread: null },
       pr.body,
@@ -242,23 +235,46 @@ type ReviewRequestInput = {
   number: number
   base: Pick<InboundMessage, 'adapter' | 'workspace' | 'isDm' | 'mentionsOthers' | 'replyToOtherMessageId'>
   selfLogin: string | null
+  authType: 'pat' | 'app'
   teamIsBotMember: boolean | undefined
 }
 
+// A GitHub App can never be a `requested_reviewer` — that field only holds
+// real user accounts, and the App actor (`slug[bot]`) is not one. The
+// supported workaround is a decoy user account named after the App that an
+// operator requests instead (see docs/content/docs/internals/github-decoy-reviewer.mdx).
+// Its login is, by convention, the App slug — i.e. `selfLogin` with the
+// `[bot]` suffix removed (`my-app[bot]` → `my-app`). This is the single seam
+// where that login is resolved: when the decoy account's real login diverges
+// from the slug, a future config field replaces this derivation without
+// touching the matcher. PAT auth has no decoy (the bot IS a real user that can
+// be requested directly), so it returns null.
+const BOT_LOGIN_SUFFIX = '[bot]'
+
+function resolveDecoyReviewerLogin(selfLogin: string, authType: 'pat' | 'app'): string | null {
+  if (authType !== 'app') return null
+  if (!selfLogin.endsWith(BOT_LOGIN_SUFFIX)) return null
+  const slug = selfLogin.slice(0, -BOT_LOGIN_SUFFIX.length)
+  return slug !== '' ? slug : null
+}
+
 function classifyReviewRequest(input: ReviewRequestInput): InboundMessage | null {
-  const { action, payload, pr, number, base, selfLogin, teamIsBotMember } = input
+  const { action, payload, pr, number, base, selfLogin, authType, teamIsBotMember } = input
   if (selfLogin === null) return null
+  const decoyLogin = resolveDecoyReviewerLogin(selfLogin, authType)
   const sender = readUser(payload.sender)
   if (sender === null) return null
-  // Self-loop guard: if the bot itself requested (or un-requested) the
+  // Self-loop guard: if the bot (or its decoy) requested/un-requested the
   // review, drop the event. The bot adding itself as a reviewer would
   // otherwise wake a fresh session every time it self-assigns.
-  if (sender.login === selfLogin) return null
+  if (sender.login === selfLogin || (decoyLogin !== null && sender.login === decoyLogin)) return null
 
   const requestedUser = readUser(payload.requested_reviewer)
   const requestedTeam = readReviewerTeam(payload.requested_team)
 
-  const isMeAsUser = requestedUser !== null && requestedUser.login === selfLogin
+  const isMeAsUser =
+    requestedUser !== null &&
+    (requestedUser.login === selfLogin || (decoyLogin !== null && requestedUser.login === decoyLogin))
   const isMyTeam = requestedTeam !== null && teamIsBotMember === true
   if (!isMeAsUser && !isMyTeam) return null
 
@@ -303,47 +319,6 @@ function classifyReviewRequest(input: ReviewRequestInput): InboundMessage | null
   }
 }
 
-type OpenedAsReviewInput = {
-  payload: Record<string, unknown>
-  pr: Record<string, unknown>
-  number: number
-  base: Pick<InboundMessage, 'adapter' | 'workspace' | 'isDm' | 'mentionsOthers' | 'replyToOtherMessageId'>
-  selfLogin: string | null
-}
-
-function classifyOpenedAsReview(input: OpenedAsReviewInput): InboundMessage | null {
-  const { payload, pr, number, base, selfLogin } = input
-  if (selfLogin === null) return null
-  const sender = readUser(payload.sender)
-  if (sender === null) return null
-  if (sender.login === selfLogin) return null
-
-  const title = readString(pr, 'title') ?? `#${number}`
-  const head = readString(readRecord(pr.head), 'ref')
-  const baseRef = readString(readRecord(pr.base), 'ref')
-  const branchSegment = head !== null && baseRef !== null ? ` Branch: ${head} → ${baseRef}.` : ''
-  const text =
-    `@${sender.login} requested your review on PR #${number}: "${title}".${branchSegment}` +
-    ' Please review the changes line-by-line and post your feedback.'
-
-  const updatedAt = readString(pr, 'updated_at') ?? ''
-  const prId = readNumber(pr, 'id') ?? number
-
-  return {
-    ...base,
-    chat: `pr:${number}`,
-    thread: null,
-    text,
-    externalMessageId: `pr-${prId}-opened-${updatedAt}`,
-    authorId: String(sender.id),
-    authorName: sender.login,
-    authorIsBot: sender.type === 'Bot',
-    isBotMention: true,
-    replyToBotMessageId: null,
-    ts: updatedAt !== '' ? Date.parse(updatedAt) || 0 : 0,
-  }
-}
-
 export type GithubReviewerTeam = { slug: string; id: number; org: string | null }
 
 export function readReviewerTeam(value: unknown): GithubReviewerTeam | null {