typeclaw 0.3.1 → 0.5.0

package/src/channels/adapters/github/webhook-register.ts

@@ -0,0 +1,349 @@
+import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+
+export type RegisterGithubWebhooksOptions = {
+  token: () => Promise<string>
+  webhookUrl: string
+  webhookSecret: string
+  repos: readonly string[]
+  events: readonly string[]
+  // Stable, hostname-agnostic marker embedded in the webhook URL's path so
+  // hooks created by this agent in past runs can be recognized as ours even
+  // after the host part of the URL has rotated (e.g. cloudflare-quick tunnels
+  // mint a fresh `*.trycloudflare.com` on every container restart).
+  //
+  // When set, any hook whose `config.url` URL.pathname ends with this exact
+  // string is considered owned by this agent: at register time we PATCH the
+  // first such hook to the current URL and delete the rest as stale orphans.
+  //
+  // Convention: `/typeclaw/v1/github/<containerName>` — see
+  // `buildManagedPath` in `./managed-path.ts`. The path is appended onto
+  // tunnel-derived URLs by the adapter; user-set `webhookUrl` is kept
+  // verbatim (the operator is in control of their own URL — we trust them
+  // not to point two agents at the same URL).
+  //
+  // Omitted means the legacy URL-equality path is used (no orphan cleanup).
+  // The adapter always passes it in production; the option stays optional so
+  // direct unit-test calls can opt out of the cleanup logic.
+  managedPath?: string
+  // Opt-in legacy-orphan cleanup for hooks created before the marker existed.
+  // When set (e.g. `.trycloudflare.com`), the lister ALSO claims any hook
+  // whose URL host endsWith this suffix AND whose pathname is empty or `/`
+  // (unmarked = necessarily pre-fix). The adapter passes this only when the
+  // CURRENT effective URL itself lives on the same provider domain, so an
+  // agent on an external/self-hosted tunnel can never claim a colleague's
+  // cloudflare-quick hook. Hooks with a non-trivial path are still skipped
+  // unconditionally so a foreign service that happens to also use
+  // *.trycloudflare.com with its own path stays safe.
+  legacyProviderHostSuffix?: string
+  fetchImpl?: typeof fetch
+}
+
+export type WebhookRepoResult =
+  | { repo: string; action: 'created'; hookId: number }
+  | { repo: string; action: 'updated'; hookId: number; stalePruned: number }
+  | { repo: string; action: 'failed'; error: string }
+
+export type WebhookRegistrationResult = {
+  repos: WebhookRepoResult[]
+}
+
+export async function registerGithubWebhooks(
+  options: RegisterGithubWebhooksOptions,
+): Promise<WebhookRegistrationResult> {
+  const fetchImpl = options.fetchImpl ?? fetch
+  let token: string
+  try {
+    token = await options.token()
+  } catch (err) {
+    const error = describe(err)
+    return { repos: options.repos.map((repo) => ({ repo, action: 'failed' as const, error })) }
+  }
+  const repos: WebhookRepoResult[] = []
+  for (const repo of options.repos) {
+    repos.push(await registerOne(fetchImpl, token, repo, options))
+  }
+  return { repos }
+}
+
+export type DeregisterGithubWebhooksOptions = {
+  token: () => Promise<string>
+  hooks: ReadonlyArray<{ repo: string; hookId: number }>
+  fetchImpl?: typeof fetch
+}
+
+export type WebhookDeregistrationResult = {
+  hooks: Array<{ repo: string; hookId: number; action: 'deleted' | 'missing' | 'failed'; error?: string }>
+}
+
+export async function deregisterGithubWebhooks(
+  options: DeregisterGithubWebhooksOptions,
+): Promise<WebhookDeregistrationResult> {
+  const fetchImpl = options.fetchImpl ?? fetch
+  let token: string
+  try {
+    token = await options.token()
+  } catch (err) {
+    const error = describe(err)
+    return { hooks: options.hooks.map((h) => ({ ...h, action: 'failed', error })) }
+  }
+  const hooks: WebhookDeregistrationResult['hooks'] = []
+  for (const hook of options.hooks) {
+    hooks.push(await deleteOne(fetchImpl, token, hook))
+  }
+  return { hooks }
+}
+
+async function registerOne(
+  fetchImpl: typeof fetch,
+  token: string,
+  repo: string,
+  options: RegisterGithubWebhooksOptions,
+): Promise<WebhookRepoResult> {
+  const parsed = parseRepoSlug(repo)
+  if (parsed === null) {
+    return { repo, action: 'failed', error: `invalid repo slug: "${repo}" (expected owner/name)` }
+  }
+  try {
+    const owned = await findManagedHooks(
+      fetchImpl,
+      token,
+      parsed,
+      options.webhookUrl,
+      options.managedPath,
+      options.legacyProviderHostSuffix,
+    )
+    if (owned.length === 0) {
+      const hookId = await createHook(fetchImpl, token, parsed, options)
+      return { repo, action: 'created', hookId }
+    }
+    // Sort by id ascending so the canonical kept hook is deterministic
+    // (oldest = lowest id wins). This makes successive runs converge on the
+    // same hookId for the same repo, which is friendlier to anyone
+    // inspecting the repo's webhook list.
+    const [keep, ...stale] = owned.slice().sort((a, b) => a - b)
+    await updateHook(fetchImpl, token, parsed, keep!, options)
+    let stalePruned = 0
+    for (const id of stale) {
+      const ok = await tryDeleteHook(fetchImpl, token, parsed, id)
+      if (ok) stalePruned++
+    }
+    return { repo, action: 'updated', hookId: keep!, stalePruned }
+  } catch (err) {
+    return { repo, action: 'failed', error: describe(err) }
+  }
+}
+
+async function deleteOne(
+  fetchImpl: typeof fetch,
+  token: string,
+  hook: { repo: string; hookId: number },
+): Promise<WebhookDeregistrationResult['hooks'][number]> {
+  const parsed = parseRepoSlug(hook.repo)
+  if (parsed === null) {
+    return { ...hook, action: 'failed', error: `invalid repo slug: "${hook.repo}"` }
+  }
+  try {
+    const response = await fetchImpl(`${GITHUB_API_BASE}/repos/${parsed.owner}/${parsed.name}/hooks/${hook.hookId}`, {
+      method: 'DELETE',
+      headers: githubJsonHeaders(token),
+    })
+    if (response.status === 404) return { ...hook, action: 'missing' }
+    if (!response.ok) {
+      const body = await response.text().catch(() => '')
+      return {
+        ...hook,
+        action: 'failed',
+        error: `delete hook failed: ${response.status}${body !== '' ? ` ${body}` : ''}`,
+      }
+    }
+    return { ...hook, action: 'deleted' }
+  } catch (err) {
+    return { ...hook, action: 'failed', error: describe(err) }
+  }
+}
+
+// Best-effort stale-hook prune. We don't surface 404/403/etc. as a register
+// failure because the primary keep-hook is already updated; an inability to
+// delete a stale orphan is a soft warning at most. Caller counts successful
+// prunes for the log line.
+async function tryDeleteHook(fetchImpl: typeof fetch, token: string, repo: RepoSlug, hookId: number): Promise<boolean> {
+  try {
+    const response = await fetchImpl(`${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/hooks/${hookId}`, {
+      method: 'DELETE',
+      headers: githubJsonHeaders(token),
+    })
+    // 404 = already gone; treat as a successful prune for log-summary purposes
+    // (the orphan is no longer on the repo, which is what we wanted).
+    return response.ok || response.status === 404
+  } catch {
+    return false
+  }
+}
+
+type RepoSlug = { owner: string; name: string }
+
+function parseRepoSlug(slug: string): RepoSlug | null {
+  const parts = slug.split('/')
+  if (parts.length !== 2) return null
+  const [owner, name] = parts
+  if (!owner || !name) return null
+  if (!REPO_SEGMENT.test(owner) || !REPO_SEGMENT.test(name)) return null
+  return { owner, name }
+}
+
+const REPO_SEGMENT = /^[A-Za-z0-9._-]+$/
+
+// Returns the hookIds of every hook owned by this agent on `repo`, in the
+// order GitHub returned them. Ownership is the union of three rules:
+//
+//   1. `config.url === webhookUrl` — the live URL match. Covers the
+//      common case (user-set webhookUrl, or a tunnel URL that hasn't
+//      rotated since the last register).
+//
+//   2. `URL(config.url).pathname` ends with `managedPath` — the
+//      hostname-agnostic path-marker match. Covers hooks that THIS agent
+//      created in a previous run whose tunnel host has since rotated.
+//      Skipped when `managedPath` is omitted (legacy callers).
+//
+//   3. (Opt-in via `legacyProviderHostSuffix`) `URL(config.url).host` ends
+//      with the supplied suffix AND pathname is empty or `/`. Covers the
+//      pre-marker orphans the user reported in the bug. Tightly bounded:
+//      same provider domain only, unmarked hooks only.
+//
+// Hooks whose `config.url` isn't a parseable URL are ignored. Hooks
+// without an `id` are ignored.
+async function findManagedHooks(
+  fetchImpl: typeof fetch,
+  token: string,
+  repo: RepoSlug,
+  webhookUrl: string,
+  managedPath: string | undefined,
+  legacyProviderHostSuffix: string | undefined,
+): Promise<number[]> {
+  const response = await fetchImpl(`${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/hooks?per_page=100`, {
+    method: 'GET',
+    headers: githubJsonHeaders(token),
+  })
+  if (!response.ok) {
+    const body = await response.text().catch(() => '')
+    throw new Error(`list hooks failed: ${response.status}${body !== '' ? ` ${body}` : ''}`)
+  }
+  const hooks = (await response.json()) as Array<{ id?: unknown; config?: { url?: unknown } }>
+  const owned: number[] = []
+  for (const hook of hooks) {
+    if (typeof hook.id !== 'number') continue
+    const url = hook.config?.url
+    if (typeof url !== 'string') continue
+    if (url === webhookUrl) {
+      owned.push(hook.id)
+      continue
+    }
+    if (managedPath !== undefined && hookPathMatchesMarker(url, managedPath)) {
+      owned.push(hook.id)
+      continue
+    }
+    if (legacyProviderHostSuffix !== undefined && hookIsUnmarkedOnProvider(url, legacyProviderHostSuffix)) {
+      owned.push(hook.id)
+    }
+  }
+  return owned
+}
+
+function hookPathMatchesMarker(rawUrl: string, marker: string): boolean {
+  let parsed: URL
+  try {
+    parsed = new URL(rawUrl)
+  } catch {
+    return false
+  }
+  // Suffix match on pathname only (not the full URL). Rotating Cloudflare
+  // hostnames change `parsed.host`; the marker survives in `parsed.pathname`.
+  // Suffix (not equality) so a future reverse-proxy that prepends a path
+  // prefix doesn't break recognition.
+  return parsed.pathname === marker || parsed.pathname.endsWith(marker)
+}
+
+function hookIsUnmarkedOnProvider(rawUrl: string, hostSuffix: string): boolean {
+  let parsed: URL
+  try {
+    parsed = new URL(rawUrl)
+  } catch {
+    return false
+  }
+  // Empty pathname (rare, depends on URL parser) or root only. Anything
+  // with a real path is treated as user-controlled and left alone.
+  const unmarked = parsed.pathname === '' || parsed.pathname === '/'
+  // hostSuffix must start with a dot OR be the full host — guards against
+  // `foo.com` accidentally matching `evilfoo.com`.
+  const onProvider = parsed.host === hostSuffix || (hostSuffix.startsWith('.') && parsed.host.endsWith(hostSuffix))
+  return unmarked && onProvider
+}
+
+async function createHook(
+  fetchImpl: typeof fetch,
+  token: string,
+  repo: RepoSlug,
+  options: RegisterGithubWebhooksOptions,
+): Promise<number> {
+  const response = await fetchImpl(`${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/hooks`, {
+    method: 'POST',
+    headers: githubJsonHeaders(token),
+    body: JSON.stringify(buildHookPayload(options, { includeName: true })),
+  })
+  if (!response.ok) {
+    const body = await response.text().catch(() => '')
+    throw new Error(`create hook failed: ${response.status}${body !== '' ? ` ${body}` : ''}`)
+  }
+  const raw = (await response.json()) as { id?: unknown }
+  if (typeof raw.id !== 'number') throw new Error('create hook response missing id')
+  return raw.id
+}
+
+async function updateHook(
+  fetchImpl: typeof fetch,
+  token: string,
+  repo: RepoSlug,
+  hookId: number,
+  options: RegisterGithubWebhooksOptions,
+): Promise<void> {
+  const response = await fetchImpl(`${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/hooks/${hookId}`, {
+    method: 'PATCH',
+    headers: githubJsonHeaders(token),
+    body: JSON.stringify(buildHookPayload(options, { includeName: false })),
+  })
+  if (!response.ok) {
+    const body = await response.text().catch(() => '')
+    throw new Error(`update hook failed: ${response.status}${body !== '' ? ` ${body}` : ''}`)
+  }
+}
+
+function buildHookPayload(
+  options: RegisterGithubWebhooksOptions,
+  { includeName }: { includeName: boolean },
+): Record<string, unknown> {
+  const payload: Record<string, unknown> = {
+    active: true,
+    events: toCoarseEvents(options.events),
+    config: {
+      url: options.webhookUrl,
+      content_type: 'json',
+      secret: options.webhookSecret,
+      insecure_ssl: '0',
+    },
+  }
+  if (includeName) payload.name = 'web'
+  return payload
+}
+
+function toCoarseEvents(events: readonly string[]): string[] {
+  const seen = new Set<string>()
+  for (const e of events) {
+    const coarse = e.split('.')[0]
+    if (coarse && coarse.length > 0) seen.add(coarse)
+  }
+  return [...seen]
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}

package/src/channels/manager.ts

@@ -2,15 +2,23 @@ import { createHash } from 'node:crypto'
 import { join } from 'node:path'
 
 import type { PermissionService } from '@/permissions'
+import type { GithubSecretsBlock } from '@/secrets'
 import { SecretsKakaoCredentialStore } from '@/secrets/kakao-store'
 import { SecretsBackend } from '@/secrets/storage'
 
 import { createDiscordBotAdapter, type DiscordBotAdapter } from './adapters/discord-bot'
+import { createGithubAdapter, type GithubAdapter } from './adapters/github'
 import { createKakaotalkAdapter, type KakaotalkAdapter } from './adapters/kakaotalk'
 import { createSlackBotAdapter, type SlackBotAdapter } from './adapters/slack-bot'
 import { createTelegramBotAdapter, type TelegramBotAdapter } from './adapters/telegram-bot'
 import { createChannelRouter, type ChannelRouter, type ClaimHandler, type CreateSessionForChannel } from './router'
-import { ADAPTER_IDS, type AdapterId, type ChannelAdapterConfig, type ChannelsConfig } from './schema'
+import {
+  ADAPTER_IDS,
+  type AdapterId,
+  type ChannelAdapterConfig,
+  type ChannelsConfig,
+  type GithubAdapterConfig,
+} from './schema'
 
 export type ChannelManagerLogger = {
   info: (msg: string) => void
@@ -48,6 +56,7 @@ export type ChannelManagerOptions = {
   createSessionForChannel?: CreateSessionForChannel
   // Test seams: let fake adapters replace the real adapter wiring per id.
   createDiscordAdapter?: typeof createDiscordBotAdapter
+  createGithubAdapter?: typeof createGithubAdapter
   createKakaotalkAdapter?: typeof createKakaotalkAdapter
   createSlackAdapter?: typeof createSlackBotAdapter
   createTelegramAdapter?: typeof createTelegramBotAdapter
@@ -62,16 +71,24 @@ export type ChannelManagerOptions = {
   // code. Production wiring sets this from the role-claim subsystem (see
   // src/run/index.ts). Tests typically omit it.
   claimHandler?: ClaimHandler
+  tunnelUrlForChannel?: (channelName: string) => string | null
+  // Whether the user declared a `tunnels[]` entry bound to this channel.
+  // Lets channel-bound adapters distinguish "operator opted out of public
+  // webhook delivery" from "operator opted in but the tunnel never produced
+  // a URL" so error logs can be precise. Same shape as
+  // `tunnelUrlForChannel` for consistency. Optional for tests.
+  tunnelConfiguredForChannel?: (channelName: string) => boolean
 }
 
 export type ChannelManager = {
   router: ChannelRouter
   start: () => Promise<void>
   stop: () => Promise<void>
+  restartAdapter: (name: AdapterId) => Promise<void>
   reload: () => Promise<{ started: string[]; stopped: string[]; restartRequired: string[] }>
 }
 
-type AnyAdapter = DiscordBotAdapter | KakaotalkAdapter | SlackBotAdapter | TelegramBotAdapter
+type AnyAdapter = DiscordBotAdapter | GithubAdapter | KakaotalkAdapter | SlackBotAdapter | TelegramBotAdapter
 
 // Credential signature is the comparison key for credential-rotation
 // detection on reload. Discord and Telegram each use a single bot token;
@@ -98,14 +115,27 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
     ...(options.claimHandler ? { claimHandler: options.claimHandler } : {}),
   })
   const createDiscordAdapter = options.createDiscordAdapter ?? createDiscordBotAdapter
+  const createGithub = options.createGithubAdapter ?? createGithubAdapter
   const createKakaotalk = options.createKakaotalkAdapter ?? createKakaotalkAdapter
   const createSlackAdapter = options.createSlackAdapter ?? createSlackBotAdapter
   const createTelegramAdapter = options.createTelegramAdapter ?? createTelegramBotAdapter
 
   const live = new Map<AdapterId, AdapterEntry>()
+  const perAdapterSerial = new Map<AdapterId, Promise<unknown>>()
+
+  const runSerially = <T>(name: AdapterId, op: () => Promise<T>): Promise<T> => {
+    const prev = perAdapterSerial.get(name) ?? Promise.resolve()
+    const next = prev.then(op, op)
+    perAdapterSerial.set(
+      name,
+      next.catch(() => {}),
+    )
+    return next
+  }
 
   const buildCredentialSignature = (name: AdapterId): { signature: string; missing: string[] } => {
     if (name === 'kakaotalk') return buildKakaotalkSignature(options.agentDir)
+    if (name === 'github') return buildGithubSignature(options.agentDir)
     const requiredEnvs = TOKEN_ENV[name]
     const parts: string[] = []
     const missing: string[] = []
@@ -151,6 +181,19 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
         credentialsStore: createContainerKakaoCredentialStore(options.agentDir, env),
       })
     }
+    if (name === 'github') {
+      const secrets = readGithubSecrets(options.agentDir)
+      if (secrets === null) return null
+      return createGithub({
+        router,
+        configRef: () => (options.channelsConfigRef()[name] ?? cfg) as ChannelAdapterConfig & GithubAdapterConfig,
+        secrets,
+        agentDir: options.agentDir,
+        logger,
+        tunnelUrl: () => options.tunnelUrlForChannel?.('github') ?? null,
+        tunnelConfiguredForChannel: () => options.tunnelConfiguredForChannel?.('github') ?? false,
+      })
+    }
     if (name === 'telegram-bot') {
       const token = env.TELEGRAM_BOT_TOKEN
       if (token === undefined || token.trim() === '') return null
@@ -193,9 +236,9 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
   const stopAdapter = async (name: AdapterId): Promise<void> => {
     const entry = live.get(name)
     if (!entry) return
-    live.delete(name)
     try {
       await entry.adapter.stop()
+      live.delete(name)
       logger.info(`[channels] adapter "${name}" stopped`)
     } catch (err) {
       logger.error(`[channels] adapter "${name}" failed to stop: ${describe(err)}`)
@@ -209,15 +252,31 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
       const cfg = options.channelsConfigRef()
       for (const name of ADAPTER_IDS) {
         const adapterCfg = cfg[name]
-        if (adapterCfg !== undefined) await startAdapter(name, adapterCfg)
+        if (adapterCfg !== undefined) await runSerially(name, () => startAdapter(name, adapterCfg))
       }
     },
 
     async stop(): Promise<void> {
-      for (const name of Array.from(live.keys())) await stopAdapter(name)
+      for (const name of Array.from(live.keys())) await runSerially(name, () => stopAdapter(name))
       await router.stop()
     },
 
+    async restartAdapter(name: AdapterId): Promise<void> {
+      await runSerially(name, async () => {
+        if (!live.has(name)) {
+          logger.info(`[channels] restartAdapter('${name}'): adapter not live, skipping`)
+          return
+        }
+        const currentCfg = options.channelsConfigRef()[name]
+        if (currentCfg === undefined) {
+          logger.info(`[channels] restartAdapter('${name}'): adapter config missing, skipping`)
+          return
+        }
+        await stopAdapter(name)
+        await startAdapter(name, currentCfg)
+      })
+    },
+
     async reload(): Promise<{ started: string[]; stopped: string[]; restartRequired: string[] }> {
       const cfg = options.channelsConfigRef()
       const started: string[] = []
@@ -229,11 +288,11 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
         const current = live.get(name)
         if (desired === undefined || desired.enabled === false) {
           if (current) {
-            await stopAdapter(name)
+            await runSerially(name, () => stopAdapter(name))
             stopped.push(name)
           }
         } else if (!current) {
-          const ok = await startAdapter(name, desired)
+          const ok = await runSerially(name, () => startAdapter(name, desired))
           if (ok) started.push(name)
         } else {
           const { signature, missing } = buildCredentialSignature(name)
@@ -246,7 +305,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
             logger.warn(
               `[channels] adapter "${name}" missing credentials after reload (${missing.join(', ')}); stopping`,
             )
-            await stopAdapter(name)
+            await runSerially(name, () => stopAdapter(name))
             stopped.push(name)
           } else if (signature !== current.credentialSignature) {
             const reason = name === 'kakaotalk' ? 'credential rotation' : 'token rotation'
@@ -263,7 +322,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
 // Token-based adapters only. KakaoTalk's credentials live in
 // secrets.json#channels.kakaotalk, not in env, so it goes through
 // buildKakaotalkSignature instead.
-const TOKEN_ENV: Record<Exclude<AdapterId, 'kakaotalk'>, readonly string[]> = {
+const TOKEN_ENV: Record<Exclude<AdapterId, 'kakaotalk' | 'github'>, readonly string[]> = {
   'discord-bot': ['DISCORD_BOT_TOKEN'],
   'slack-bot': ['SLACK_BOT_TOKEN', 'SLACK_APP_TOKEN'],
   'telegram-bot': ['TELEGRAM_BOT_TOKEN'],
@@ -301,6 +360,32 @@ function buildKakaotalkSignature(agentDir: string): { signature: string; missing
   }
 }
 
+function buildGithubSignature(agentDir: string): { signature: string; missing: string[] } {
+  const block = readGithubSecrets(agentDir)
+  if (block === null) return { signature: '', missing: ['secrets.json#channels.github'] }
+  const digest = createHash('sha256').update(JSON.stringify(block)).digest('hex')
+  return { signature: `secrets.json#channels.github@sha256:${digest}`, missing: [] }
+}
+
+function readGithubSecrets(agentDir: string): GithubSecretsBlock | null {
+  const path = join(agentDir, 'secrets.json')
+  try {
+    const block = new SecretsBackend(path).tryReadChannelsSync()?.github
+    return isGithubSecretsBlock(block) ? block : null
+  } catch {
+    return null
+  }
+}
+
+function isGithubSecretsBlock(value: unknown): value is GithubSecretsBlock {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const record = value as Record<string, unknown>
+  const auth = record.auth
+  if (typeof auth !== 'object' || auth === null || Array.isArray(auth)) return false
+  const authType = (auth as Record<string, unknown>).type
+  return authType === 'pat' || authType === 'app'
+}
+
 function isKakaoCredentialBlock(value: unknown): value is { accounts: Record<string, unknown> } {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
   if (!('accounts' in value)) return false