typeclaw 0.16.0 → 0.18.0

package/auth.schema.json

@@ -213,11 +213,6 @@
                           }
                         }
                       ]
-                    },
-                    "installationId": {
-                      "type": "integer",
-                      "exclusiveMinimum": 0,
-                      "maximum": 9007199254740991
                     }
                   },
                   "required": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"
@@ -46,7 +46,7 @@
     "@mariozechner/pi-coding-agent": "^0.67.3",
     "@mariozechner/pi-tui": "^0.67.3",
     "@mozilla/readability": "^0.6.0",
-    "agent-messenger": "2.19.0",
+    "agent-messenger": "2.19.1",
     "cheerio": "^1.2.0",
     "citty": "^0.2.2",
     "cron-parser": "^5.5.0",

package/secrets.schema.json

@@ -213,11 +213,6 @@
                           }
                         }
                       ]
-                    },
-                    "installationId": {
-                      "type": "integer",
-                      "exclusiveMinimum": 0,
-                      "maximum": 9007199254740991
                     }
                   },
                   "required": [

package/src/agent/index.ts

@@ -9,7 +9,7 @@ import { loadMemory } from '@/bundled-plugins/memory/load-memory'
 import type { ChannelRouter } from '@/channels/router'
 import { getConfig, resolveModel, resolveProfile } from '@/config'
 import { defaultThinkingLevelForRef, providerForModelRef, type KnownModelRef } from '@/config/providers'
-import type { PermissionService } from '@/permissions'
+import type { PermissionService, RolesConfig } from '@/permissions'
 import type {
   BuiltinToolRef,
   HookBus,
@@ -50,6 +50,7 @@ import { createChannelFetchAttachmentTool } from './tools/channel-fetch-attachme
 import { createChannelHistoryTool } from './tools/channel-history'
 import { createChannelReplyTool } from './tools/channel-reply'
 import { createChannelSendTool } from './tools/channel-send'
+import { createGrantRoleTool } from './tools/grant-role'
 import { createRestartTool } from './tools/restart'
 import { createSkipResponseTool } from './tools/skip-response'
 import { createSpawnSubagentTool } from './tools/spawn-subagent'
@@ -141,6 +142,11 @@ export type CreateSessionOptions = {
   // prompt is not regenerated; see `typeclaw-permissions` skill for how the
   // agent should interpret the snapshot on later turns.
   permissions?: PermissionService
+  // Re-reads roles from disk for the grant_role tool's hot-reload after a match
+  // grant. Production threads a reload-then-read (reloadConfig + getConfig);
+  // must not be an in-memory snapshot or the grant reapplies stale roles.
+  // Omitted when no grant_role tool is wired (the tool requires permissions).
+  reloadRoles?: () => RolesConfig | undefined
   // Model profile name. Resolved against `config.models` to pick the concrete
   // model ref this session binds to. Unknown profile names fall back to
   // `default` with a one-time console warning. Omitted → `default`. Threaded
@@ -322,6 +328,12 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
               permissions: options.permissions,
               stream: options.stream,
             }),
+            ...buildRoleGrantTools({
+              agentDir: options.plugins?.agentDir,
+              getOrigin,
+              permissions: options.permissions,
+              reloadRoles: options.reloadRoles,
+            }),
           ]
   // Hook coverage for pi's builtin coding tools (read/bash/edit/write/grep/
   // find/ls) — pi 0.67.3 ignores `tools:` for implementation, so the only
@@ -577,6 +589,25 @@ export function buildSubagentOrchestrationTools(opts: {
   ]
 }
 
+export function buildRoleGrantTools(opts: {
+  agentDir: string | undefined
+  getOrigin: () => SessionOrigin | undefined
+  permissions: PermissionService | undefined
+  reloadRoles: (() => RolesConfig | undefined) | undefined
+}): ToolDefinition[] {
+  if (opts.agentDir === undefined || opts.permissions === undefined || opts.reloadRoles === undefined) {
+    return []
+  }
+  return [
+    createGrantRoleTool({
+      agentDir: opts.agentDir,
+      getOrigin: opts.getOrigin,
+      permissions: opts.permissions,
+      reloadRoles: opts.reloadRoles,
+    }),
+  ]
+}
+
 function wrapRegistryTools(
   plugins: PluginSessionWiring | undefined,
   getOrigin: () => SessionOrigin | undefined,

package/src/agent/session-origin.ts

@@ -111,11 +111,12 @@ function getPlatformInfo(adapter: AdapterId): PlatformInfo {
 // TUI is always `owner` by construction — annotating it would add noise to
 // every interactive session for zero new information.
 //
-// For channel sessions this is a session-creation snapshot. The router
-// re-resolves per-turn for tool gating, but the system prompt is not
-// regenerated mid-session; the role line is accurate at admission and the
-// `typeclaw-permissions` skill spells out how to interpret it on later
-// turns when a different speaker may have spoken last.
+// Channel origins do NOT render this concrete role. A channel session is
+// keyed by chat/thread, so the opener's role is wrong for every later
+// speaker and printing their permission list leaks it into shared context.
+// Channel origins render renderChannelRolePolicy() instead, and the
+// authoritative per-turn role rides in the non-cacheable `<your-role>`
+// turn anchor (renderTurnRoleAnchor in system-prompt.ts).
 export type SessionRoleContext = {
   role: string
   permissions: readonly string[]
@@ -128,21 +129,22 @@ export function renderSessionOrigin(
 ): string {
   switch (origin.kind) {
     case 'tui':
-      return withRoleContext(renderTuiOrigin(), roleContext)
+      return withRoleContext(renderTuiOrigin(), roleContext, origin.kind)
     case 'cron':
-      return withRoleContext(renderCronOrigin(origin), roleContext)
+      return withRoleContext(renderCronOrigin(origin), roleContext, origin.kind)
     case 'channel':
-      return withRoleContext(renderChannelOrigin(origin, now), roleContext)
+      return withRoleContext(renderChannelOrigin(origin, now), roleContext, origin.kind)
     case 'subagent':
-      return withRoleContext(renderSubagentOrigin(origin), roleContext)
+      return withRoleContext(renderSubagentOrigin(origin), roleContext, origin.kind)
     case 'system':
-      return withRoleContext(renderSystemOrigin(origin), roleContext)
+      return withRoleContext(renderSystemOrigin(origin), roleContext, origin.kind)
   }
 }
 
-function withRoleContext(block: string, ctx: SessionRoleContext | undefined): string {
+function withRoleContext(block: string, ctx: SessionRoleContext | undefined, kind: SessionOrigin['kind']): string {
   if (ctx === undefined) return block
-  return `${block}\n\n${renderRoleContext(ctx)}`
+  const roleBlock = kind === 'channel' ? renderChannelRolePolicy() : renderRoleContext(ctx)
+  return `${block}\n\n${roleBlock}`
 }
 
 function renderRoleContext(ctx: SessionRoleContext): string {
@@ -160,6 +162,30 @@ function renderRoleContext(ctx: SessionRoleContext): string {
   ].join('\n')
 }
 
+// Channel sessions are keyed by chat/thread, not by author: one session can see
+// many speakers with different roles. Rendering the opener's concrete role here
+// would (1) be wrong for every later speaker and (2) leak the opener's full
+// permission list into shared context. So channel origins get a cache-stable
+// policy instead of a resolved identity; the authoritative per-turn role rides
+// in the non-cacheable `<your-role>` turn anchor.
+function renderChannelRolePolicy(): string {
+  return [
+    '## Your role in this session',
+    '',
+    'This is a channel conversation that may include multiple speakers. Do not',
+    'assume one speaker’s role applies to later messages. For each user turn the',
+    'current speaker’s effective role is provided in the turn context as a',
+    '`<your-role>` tag; that per-turn role is authoritative for the current',
+    'message and overrides any role implied by session-opening context. An absent',
+    '`<your-role>` tag means the current speaker is the unconstrained default.',
+    '',
+    'Tool calls and channel admission are gated by the current speaker’s',
+    'permissions; a `blocked:` or "denied by permissions" message means that',
+    'speaker lacks the permission the guard wanted. See the',
+    '`typeclaw-permissions` skill for what each role can do.',
+  ].join('\n')
+}
+
 function renderTuiOrigin(): string {
   return [
     '## Session origin',
@@ -262,6 +288,22 @@ function renderChannelOrigin(
     'is a tool call. Plain-text output is invisible.',
   ]
 
+  // GitHub has no separate "chat" surface — channel_reply IS a public comment
+  // on this PR/issue. Without saying so, models default to the Slack-style
+  // two-surface split and post operator-facing meta-commentary ("Posted review
+  // result for PR #511") straight into the PR thread, where it reads absurdly.
+  if (origin.adapter === 'github') {
+    lines.push(
+      '',
+      '**`channel_reply` posts a public comment directly on this PR/issue.** It',
+      'is not a side-report to an operator — the reply lands in this exact',
+      'thread, read by everyone on the PR. Write the substance for that',
+      'audience: post the answer (or review summary) itself, never a status',
+      'line about having posted it elsewhere. A narrated "Posted review result',
+      'for PR #N: …" inside the PR is exactly the failure to avoid.',
+    )
+  }
+
   const conversationLine = renderConversationLine(origin)
   if (conversationLine !== null) lines.push('', conversationLine)
 

package/src/agent/system-prompt.ts

@@ -173,7 +173,7 @@ export function renderTurnTimeAnchor(now: Date = new Date()): string {
 // block for a TUI owner.
 export function renderTurnRoleAnchor(role: string): string | undefined {
   if (role === 'owner') return undefined
-  return `<your-role>${role}</your-role>`
+  return `<your-role authority="current-speaker">${role}</your-role> (authoritative for this message; overrides any role implied by the system prompt)`
 }
 
 // Compact replacement for DEFAULT_SYSTEM_PROMPT, used by non-interactive

package/src/agent/tools/grant-role.ts

@@ -0,0 +1,214 @@
+import { Type } from '@mariozechner/pi-ai'
+import { defineTool } from '@mariozechner/pi-coding-agent'
+
+import {
+  grantRole,
+  grantRolePermission,
+  isDmChannelOrigin,
+  parseMatchRule,
+  type PermissionService,
+  type RolesConfig,
+} from '@/permissions'
+
+import type { SessionOrigin } from '../session-origin'
+
+export type GrantRoleToolDetails =
+  | { ok: true; mode: 'match' | 'permission'; role: string; value: string; added: boolean; restartRequired: boolean }
+  | { ok: false; error: string }
+
+export type CreateGrantRoleToolOptions = {
+  agentDir: string
+  getOrigin: () => SessionOrigin | undefined
+  permissions: PermissionService
+  // Re-reads roles FROM DISK and returns the fresh set, for hot-reloading a
+  // match-grant after grantRole writes typeclaw.json. Must NOT read an
+  // in-memory config snapshot: grantRole writes the file directly, so a
+  // snapshot taken before the live config pointer is reloaded would be stale
+  // and replaceRoles would reapply the pre-grant table. Production wires this
+  // to reloadConfig(agentDir) + getConfig().roles, matching the config
+  // reloadable. A permission-grant is restart-required, so the reload has no
+  // runtime effect for it, but we reload anyway to keep a same-session
+  // subsequent match-grant reading a consistent table.
+  reloadRoles: () => RolesConfig | undefined
+}
+
+// Roles this tool may target, lowest to highest. `guest` is a valid target
+// (an operator opening guest channel.respond) but never a granter — the gate
+// below requires the caller to resolve to owner/trusted.
+const TIER_ORDER = ['guest', 'member', 'trusted', 'owner'] as const
+type TierRole = (typeof TIER_ORDER)[number]
+
+function tierOf(role: string): number {
+  return TIER_ORDER.indexOf(role as TierRole)
+}
+
+function isTierRole(role: string): role is TierRole {
+  return (TIER_ORDER as readonly string[]).includes(role)
+}
+
+// A single-principal turn carries only the principal's own first-party words:
+// the TUI (a human typing directly) or a 1:1 DM (principal + bot, no
+// third-party messages buffered in). A group/open channel turn always mixes in
+// other authors' messages, which is the confused-deputy surface that lets a
+// guest prompt-inject a trusted turn into rewriting the access-control table.
+// Role grants are confined to single-principal turns so that surface does not
+// exist.
+function isSinglePrincipalOrigin(origin: SessionOrigin | undefined): boolean {
+  if (origin === undefined) return false
+  if (origin.kind === 'tui') return true
+  if (origin.kind === 'channel') return isDmChannelOrigin(origin)
+  return false
+}
+
+export function createGrantRoleTool(options: CreateGrantRoleToolOptions) {
+  const { agentDir, getOrigin, permissions, reloadRoles } = options
+
+  return defineTool({
+    name: 'grant_role',
+    label: 'Grant Role',
+    description:
+      'Assign an author to a role (match grant) or give a role a capability (permission grant), by editing typeclaw.json#roles. ' +
+      'Use this to onboard a teammate ("respond to author U_X" → grant them member) or to open the agent to a wider audience ' +
+      '("let anyone in this channel message you" → grant guest channel.respond). ' +
+      'Only callable from the TUI or a 1:1 DM by an owner or trusted user — group-channel turns cannot use it. ' +
+      'Permission grants are restart-required: they land in typeclaw.json but take effect on the next `typeclaw restart`.',
+    parameters: Type.Object({
+      role: Type.Union(
+        [Type.Literal('owner'), Type.Literal('trusted'), Type.Literal('member'), Type.Literal('guest')],
+        {
+          description: 'The role to grant TO.',
+        },
+      ),
+      match: Type.Optional(
+        Type.String({
+          description:
+            'A match rule assigning an author/scope to the role, e.g. "slack:T0123 author:U_WIFE". ' +
+            'Provide exactly one of match or permission.',
+        }),
+      ),
+      permission: Type.Optional(
+        Type.String({
+          description:
+            'A capability to add to the role, e.g. "channel.respond". Provide exactly one of match or permission. ' +
+            'security.bypass.* permissions cannot be granted through this tool.',
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params): Promise<ToolReturn> {
+      const origin = getOrigin()
+
+      if (!isSinglePrincipalOrigin(origin)) {
+        return err(
+          'grant_role is only available from the TUI or a 1:1 DM. A group-channel turn cannot change roles, ' +
+            'because it mixes in other participants\u2019 messages (prompt-injection surface).',
+        )
+      }
+
+      const callerRole = permissions.resolveRole(origin)
+      if (callerRole !== 'owner' && callerRole !== 'trusted') {
+        return err(`grant_role denied: caller resolves to '${callerRole}'; only owner or trusted may grant roles.`)
+      }
+
+      const hasMatch = typeof params.match === 'string' && params.match.length > 0
+      const hasPermission = typeof params.permission === 'string' && params.permission.length > 0
+      if (hasMatch === hasPermission) {
+        return err('Provide exactly one of `match` or `permission`.')
+      }
+
+      if (!isTierRole(params.role)) {
+        return err(`Unknown target role '${params.role}'.`)
+      }
+
+      // Tier ceiling: a granter may not assign or empower a role ABOVE its own.
+      // owner(3) ≥ trusted(2) ≥ member(1) ≥ guest(0).
+      if (tierOf(params.role) > tierOf(callerRole)) {
+        return err(`grant_role denied: a ${callerRole} caller cannot grant the higher '${params.role}' role.`)
+      }
+
+      return hasMatch
+        ? grantMatch(params.role, params.match as string)
+        : grantPermission(callerRole, params.role, params.permission as string)
+    },
+  })
+
+  function grantMatch(role: string, matchRule: string): ToolReturn {
+    const parsed = parseMatchRule(matchRule)
+    if (!parsed.ok) {
+      return err(`Invalid match rule '${matchRule}': ${parsed.error}`)
+    }
+
+    const result = grantRole({ cwd: agentDir, roleName: role, matchRule })
+    if (!result.ok) return err(result.reason)
+
+    reload()
+    return ok('match', role, matchRule, result.added, false)
+  }
+
+  function grantPermission(callerRole: string, role: string, permission: string): ToolReturn {
+    // security.bypass.* defeats guards rather than enabling a feature; never
+    // grantable through an agent tool. It stays a deliberate hand-edit gated by
+    // the rolePromotion guard + an explicit ack.
+    if (permission.startsWith('security.bypass.')) {
+      return err(
+        `grant_role refuses to grant '${permission}': security.bypass.* permissions disable security guards and ` +
+          'must be set by hand-editing typeclaw.json (gated by the rolePromotion guard), not via this tool.',
+      )
+    }
+
+    // "Grant only what you hold": the caller cannot confer a capability it does
+    // not itself possess. Owner's resolved set is the expanded wildcard, so an
+    // owner can grant any non-bypass core permission; trusted is capped at its
+    // literal set.
+    const callerPerms = permissions.describe(getOrigin()).permissions
+    if (!callerPerms.includes(permission)) {
+      return err(
+        `grant_role denied: a ${callerRole} caller cannot grant '${permission}' because it does not hold that permission.`,
+      )
+    }
+
+    const result = grantRolePermission({ cwd: agentDir, roleName: role, permission })
+    if (!result.ok) return err(result.reason)
+
+    reload()
+    return ok('permission', role, permission, result.added, true)
+  }
+
+  function reload(): void {
+    try {
+      permissions.replaceRoles(reloadRoles())
+    } catch {
+      // Best-effort hot-reload of match-grants. A failure here does not undo
+      // the on-disk write; the next config reload / restart picks it up.
+    }
+  }
+}
+
+function ok(
+  mode: 'match' | 'permission',
+  role: string,
+  value: string,
+  added: boolean,
+  restartRequired: boolean,
+): ToolReturn {
+  const details: GrantRoleToolDetails = { ok: true, mode, role, value, added, restartRequired }
+  const note = added ? '' : ' (already on file)'
+  const restart = restartRequired
+    ? ' This permission grant is restart-required; run `typeclaw restart` for it to take effect.'
+    : ''
+  const text =
+    mode === 'match'
+      ? `Granted role '${role}' the match rule '${value}'${note}.${restart}`
+      : `Granted role '${role}' the permission '${value}'${note}.${restart}`
+  return { content: [{ type: 'text', text }], details }
+}
+
+function err(message: string): ToolReturn {
+  const details: GrantRoleToolDetails = { ok: false, error: message }
+  return { content: [{ type: 'text', text: message }], details }
+}
+
+type ToolReturn = {
+  content: { type: 'text'; text: string }[]
+  details: GrantRoleToolDetails
+}

package/src/channels/adapters/discord-bot-classify.ts

@@ -12,6 +12,7 @@ export type InboundDropReason =
   | 'self_author' // event.author.id === botUserId; we never route our own messages back to ourselves
   | 'empty_content' // SDK delivered content: '' — usually missing MessageContent intent
   | 'pre_connect' // bot identity is not known yet, so mention/self/reply classification cannot be trusted
+  | 'thread_created_system' // Discord's THREAD_CREATED system notice posted to the PARENT channel when a public thread is created from a message
 
 export type InboundClassification =
   | { kind: 'drop'; reason: InboundDropReason }
@@ -38,6 +39,10 @@ export function classifyInbound(
   const { text, attachments } = splitInbound(event)
   if (text === '') return { kind: 'drop', reason: 'empty_content' }
 
+  if (isThreadCreatedSystemMessage(event)) {
+    return { kind: 'drop', reason: 'thread_created_system' }
+  }
+
   const isDm = event.guild_id === undefined
   const workspace = isDm ? '@dm' : event.guild_id!
 
@@ -108,6 +113,24 @@ function isReplyToBot(event: DiscordGatewayMessageCreateEvent, botUserId: string
   return (event.mentions ?? []).some((m) => m.id === botUserId)
 }
 
+// Creating a public thread from a message fires TWO MESSAGE_CREATE events: a
+// THREAD_CREATED notice in the parent channel (content = thread name) and a
+// THREAD_STARTER_MESSAGE inside the thread. Each opens its own router session,
+// so the agent replies twice. The numeric Discord message type (18) that would
+// filter this cleanly is destroyed by the agent-messenger listener (it does
+// `{ ...d, type: t }`, overwriting `d.type` with the dispatch name), so we
+// fingerprint the notice by its reference instead: it points at a DIFFERENT
+// channel (the new thread) with no source `message_id`. The message_id-absent
+// check is load-bearing — it spares normal cross-channel replies and the
+// in-thread starter, both of which DO carry a message_id.
+function isThreadCreatedSystemMessage(event: DiscordGatewayMessageCreateEvent): boolean {
+  const ref = event.message_reference
+  if (ref?.channel_id === undefined) return false
+  if (ref.channel_id === event.channel_id) return false
+  if (ref.message_id !== undefined) return false
+  return ref.guild_id === undefined || event.guild_id === undefined || ref.guild_id === event.guild_id
+}
+
 type SplitInbound = { text: string; attachments: InboundAttachment[] }
 
 function splitInbound(event: DiscordGatewayMessageCreateEvent): SplitInbound {

package/src/channels/adapters/discord-bot.ts

@@ -763,6 +763,7 @@ function dropHint(reason: InboundDropReason): string {
       return ' (enable MESSAGE CONTENT INTENT in Discord Developer Portal and restart)'
     case 'pre_connect':
     case 'self_author':
+    case 'thread_created_system':
       return ''
   }
 }

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)
   }