typeclaw 0.3.1 → 0.4.0

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

@@ -0,0 +1,63 @@
+import type { ChannelHistoryMessage, FetchHistoryArgs, FetchHistoryResult, HistoryCallback } from '@/channels/types'
+
+import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+import { parseChat, parseRepo } from './outbound'
+
+export function createGithubHistoryCallback(options: {
+  token: () => Promise<string>
+  workspaceForChat: (chat: string) => string | null
+  fetchImpl?: typeof fetch
+}): HistoryCallback {
+  const fetchImpl = options.fetchImpl ?? fetch
+  return async (args: FetchHistoryArgs): Promise<FetchHistoryResult> => {
+    const workspace = options.workspaceForChat(args.chat)
+    if (workspace === null)
+      return { ok: false, error: 'github history unavailable until this chat receives an inbound' }
+    const repo = parseRepo(workspace)
+    const chat = parseChat(args.chat)
+    if (repo === null || chat === null) return { ok: false, error: 'invalid github history target' }
+    if (chat.kind === 'discussion') return { ok: false, error: 'github discussion history not supported yet' }
+    const endpoint =
+      chat.kind === 'pr' && args.thread !== null
+        ? `${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/pulls/${chat.number}/comments`
+        : `${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/issues/${chat.number}/comments`
+    try {
+      const cursor = args.cursor !== undefined && args.cursor !== '' ? `&page=${encodeURIComponent(args.cursor)}` : ''
+      const response = await fetchImpl(
+        `${endpoint}?per_page=${Math.min(Math.max(args.limit, 1), 100)}&direction=desc${cursor}`,
+        {
+          headers: githubJsonHeaders(await options.token()),
+        },
+      )
+      if (!response.ok) return { ok: false, error: `GitHub history ${response.status}` }
+      const raw = (await response.json()) as GithubComment[]
+      const link = response.headers.get('link') ?? ''
+      const nextCursor = /[?&]page=(\d+)[^>]*>; rel="next"/.exec(link)?.[1]
+      return nextCursor !== undefined
+        ? { ok: true, messages: raw.map(mapComment), nextCursor }
+        : { ok: true, messages: raw.map(mapComment) }
+    } catch (err) {
+      return { ok: false, error: err instanceof Error ? err.message : String(err) }
+    }
+  }
+}
+
+type GithubComment = {
+  id: number
+  body?: string
+  created_at?: string
+  user?: { id?: number; login?: string; type?: string }
+}
+
+function mapComment(comment: GithubComment): ChannelHistoryMessage {
+  const login = comment.user?.login ?? 'unknown'
+  return {
+    externalMessageId: String(comment.id),
+    authorId: String(comment.user?.id ?? login),
+    authorName: login,
+    text: comment.body ?? '',
+    ts: comment.created_at !== undefined ? Date.parse(comment.created_at) || 0 : 0,
+    isBot: comment.user?.type === 'Bot',
+    replyToBotMessageId: null,
+  }
+}

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

@@ -0,0 +1,286 @@
+import { createHmac, timingSafeEqual } from 'node:crypto'
+
+import type { InboundMessage } from '@/channels/types'
+
+import type { DeliveryDedup } from './dedup'
+import { isGithubEventAllowed } from './event-allowlist'
+
+export type GithubInboundLogger = { info: (m: string) => void; warn: (m: string) => void; error: (m: string) => void }
+
+export type GithubWebhookHandlerOptions = {
+  webhookSecret: string
+  dedup: DeliveryDedup
+  allowlist: () => readonly string[]
+  selfId: () => string | null
+  selfLogin: () => string | null
+  route: (message: InboundMessage) => void
+  logger: GithubInboundLogger
+}
+
+export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions): (req: Request) => Promise<Response> {
+  return async (req: Request): Promise<Response> => {
+    if (req.method !== 'POST') return new Response('method not allowed', { status: 405 })
+    const body = await req.text()
+    const signature = req.headers.get('x-hub-signature-256') ?? ''
+    if (!(await verifySignature(body, options.webhookSecret, signature))) {
+      options.logger.warn('[github] webhook rejected: bad signature')
+      return new Response('bad signature', { status: 401 })
+    }
+
+    const delivery = req.headers.get('x-github-delivery') ?? ''
+    if (delivery !== '' && options.dedup.has(delivery)) {
+      options.logger.info(`[github] duplicate delivery ignored id=${delivery}`)
+      return ok()
+    }
+
+    const event = req.headers.get('x-github-event') ?? ''
+    const payload = parseJson(body)
+    if (payload === null) return ok()
+    const action = readString(payload, 'action')
+    if (!isGithubEventAllowed(options.allowlist(), event, action)) return ok()
+
+    const selfId = options.selfId()
+    const author = readAuthor(payload)
+    if (selfId !== null && author !== null && String(author.id) === selfId) return ok()
+
+    const classified = classifyGithubInbound(event, payload, options.selfLogin())
+    if (classified === null) return ok()
+
+    if (delivery !== '') options.dedup.add(delivery)
+    options.route(classified)
+    return ok()
+  }
+}
+
+export async function verifySignature(body: string, secret: string, sigHeader: string): Promise<boolean> {
+  const expected = `sha256=${createHmac('sha256', secret).update(body).digest('hex')}`
+  const a = Buffer.from(expected)
+  const b = Buffer.from(sigHeader)
+  if (a.length !== b.length) return false
+  return timingSafeEqual(a, b)
+}
+
+export function classifyGithubInbound(
+  event: string,
+  payload: Record<string, unknown>,
+  selfLogin: string | null,
+): InboundMessage | null {
+  const repository = readRepository(payload)
+  if (repository === null) return null
+  const base = {
+    adapter: 'github' as const,
+    workspace: `${repository.owner}/${repository.name}`,
+    isDm: false,
+    mentionsOthers: false,
+    replyToOtherMessageId: null,
+  }
+
+  if (event === 'issue_comment') {
+    const issue = readRecord(payload.issue)
+    const comment = readRecord(payload.comment)
+    if (issue === null || comment === null) return null
+    const number = readNumber(issue, 'number')
+    const id = readNumber(comment, 'id')
+    if (number === null || id === null) return null
+    const isPullRequest = readRecord(issue.pull_request) !== null
+    const user = readUser(comment.user)
+    return buildInbound(
+      { ...base, chat: `${isPullRequest ? 'pr' : 'issue'}:${number}`, thread: null },
+      comment.body,
+      id,
+      user,
+      selfLogin,
+      comment.created_at,
+    )
+  }
+
+  if (event === 'pull_request_review_comment') {
+    const pr = readRecord(payload.pull_request)
+    const comment = readRecord(payload.comment)
+    if (pr === null || comment === null) return null
+    const number = readNumber(pr, 'number')
+    const id = readNumber(comment, 'id')
+    if (number === null || id === null) return null
+    const root = readNumber(comment, 'in_reply_to_id') ?? id
+    return buildInbound(
+      { ...base, chat: `pr:${number}`, thread: String(root) },
+      comment.body,
+      id,
+      readUser(comment.user),
+      selfLogin,
+      comment.created_at,
+    )
+  }
+
+  if (event === 'discussion_comment') {
+    const discussion = readRecord(payload.discussion)
+    const comment = readRecord(payload.comment)
+    if (discussion === null || comment === null) return null
+    const number = readNumber(discussion, 'number')
+    const id = readNumber(comment, 'id')
+    if (number === null || id === null) return null
+    return buildInbound(
+      { ...base, chat: `discussion:${number}`, thread: null },
+      comment.body,
+      id,
+      readUser(comment.user),
+      selfLogin,
+      comment.created_at,
+    )
+  }
+
+  if (event === 'issues') {
+    const issue = readRecord(payload.issue)
+    if (issue === null) return null
+    const number = readNumber(issue, 'number')
+    const id = readNumber(issue, 'id') ?? number
+    if (number === null || id === null) return null
+    return buildInbound(
+      { ...base, chat: `issue:${number}`, thread: null },
+      issue.body,
+      id,
+      readUser(issue.user),
+      selfLogin,
+      issue.created_at,
+    )
+  }
+
+  if (event === 'pull_request') {
+    const pr = readRecord(payload.pull_request)
+    if (pr === null) return null
+    const number = readNumber(pr, 'number')
+    const id = readNumber(pr, 'id') ?? number
+    if (number === null || id === null) return null
+    return buildInbound(
+      { ...base, chat: `pr:${number}`, thread: null },
+      pr.body,
+      id,
+      readUser(pr.user),
+      selfLogin,
+      pr.created_at,
+    )
+  }
+
+  if (event === 'pull_request_review') {
+    const pr = readRecord(payload.pull_request)
+    const review = readRecord(payload.review)
+    if (pr === null || review === null) return null
+    const number = readNumber(pr, 'number')
+    const id = readNumber(review, 'id')
+    if (number === null || id === null) return null
+    return buildInbound(
+      { ...base, chat: `pr:${number}`, thread: null },
+      review.body,
+      id,
+      readUser(review.user),
+      selfLogin,
+      review.submitted_at,
+    )
+  }
+
+  if (event === 'discussion') {
+    const discussion = readRecord(payload.discussion)
+    if (discussion === null) return null
+    const number = readNumber(discussion, 'number')
+    const id = readNumber(discussion, 'id') ?? number
+    if (number === null || id === null) return null
+    return buildInbound(
+      { ...base, chat: `discussion:${number}`, thread: null },
+      discussion.body,
+      id,
+      readUser(discussion.user),
+      selfLogin,
+      discussion.created_at,
+    )
+  }
+
+  return null
+}
+
+function buildInbound(
+  key: Pick<
+    InboundMessage,
+    'adapter' | 'workspace' | 'chat' | 'thread' | 'isDm' | 'mentionsOthers' | 'replyToOtherMessageId'
+  >,
+  rawText: unknown,
+  id: number,
+  user: GithubUser | null,
+  selfLogin: string | null,
+  rawTs: unknown,
+): InboundMessage | null {
+  if (user === null) return null
+  const text = typeof rawText === 'string' ? rawText : ''
+  return {
+    ...key,
+    text,
+    externalMessageId: String(id),
+    authorId: String(user.id),
+    authorName: user.login,
+    authorIsBot: user.type === 'Bot',
+    isBotMention: selfLogin !== null && text.includes(`@${selfLogin}`),
+    replyToBotMessageId: null,
+    ts: typeof rawTs === 'string' ? Date.parse(rawTs) || 0 : 0,
+  }
+}
+
+function readRepository(payload: Record<string, unknown>): { owner: string; name: string } | null {
+  const repository = readRecord(payload.repository)
+  const owner = readRecord(repository?.owner)
+  const ownerLogin = readString(owner, 'login')
+  const name = readString(repository, 'name')
+  if (ownerLogin === null || name === null) return null
+  return { owner: ownerLogin, name }
+}
+
+function readAuthor(payload: Record<string, unknown>): GithubUser | null {
+  const candidates = [payload.comment, payload.issue, payload.pull_request, payload.discussion, payload.review]
+  for (const candidate of candidates) {
+    const user = readUser(readRecord(candidate)?.user)
+    if (user !== null) return user
+  }
+  return null
+}
+
+type GithubUser = { login: string; id: number; type?: string }
+
+function readUser(value: unknown): GithubUser | null {
+  const user = readRecord(value)
+  const login = readString(user, 'login')
+  const id = readNumber(user, 'id')
+  if (login === null || id === null) return null
+  const type = readString(user, 'type') ?? undefined
+  return { login, id, ...(type !== undefined ? { type } : {}) }
+}
+
+function parseJson(body: string): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(body) as unknown
+    return readRecord(parsed)
+  } catch {
+    return null
+  }
+}
+
+function readRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null
+}
+
+function readString(obj: Record<string, unknown> | null, key: string): string | null {
+  const value = obj?.[key]
+  return typeof value === 'string' ? value : null
+}
+
+function readNumber(obj: Record<string, unknown> | null, key: string): number | null {
+  const value = obj?.[key]
+  return typeof value === 'number' && Number.isFinite(value) ? value : null
+}
+
+function ok(): Response {
+  return new Response('ok', { status: 200 })
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}

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

@@ -0,0 +1,286 @@
+import type { ChannelRouter } from '@/channels/router'
+import type { ChannelAdapterConfig, GithubAdapterConfig } from '@/channels/schema'
+import { resolveSecret } from '@/secrets/resolve'
+import type { GithubSecretsBlock } from '@/secrets/schema'
+
+import { buildAuthStrategy } from './auth'
+import { createGithubChannelNameResolver } from './channel-resolver'
+import { createDeliveryDedup } from './dedup'
+import { createGithubFetchAttachmentCallback } from './fetch-attachment'
+import { createGithubHistoryCallback } from './history'
+import { createGithubWebhookHandler } from './inbound'
+import { applyManagedPath, buildManagedPath, resolveAgentId } from './managed-path'
+import { createGithubMembershipResolver } from './membership'
+import { createGithubOutboundCallback } from './outbound'
+import { deregisterGithubWebhooks, registerGithubWebhooks, type WebhookRegistrationResult } from './webhook-register'
+
+export type GithubAdapterLogger = {
+  info: (m: string) => void
+  warn: (m: string) => void
+  error: (m: string) => void
+}
+
+export type GithubAdapterOptions = {
+  router: ChannelRouter
+  configRef: () => ChannelAdapterConfig & GithubAdapterConfig
+  secrets: GithubSecretsBlock
+  agentDir: string
+  logger?: GithubAdapterLogger
+  fetchImpl?: typeof fetch
+  httpListenImpl?: (port: number, handler: (req: Request) => Promise<Response>) => { stop: () => Promise<void> }
+  tunnelUrl?: () => string | null
+  // Whether a channel-bound tunnel exists in typeclaw.json#tunnels[] for the
+  // github channel. Used to distinguish "no tunnel configured (operator opted
+  // out)" from "tunnel configured but not producing a URL (something is
+  // wrong)" so the skip-registration log can be precise and actionable.
+  // Optional so tests that don't exercise the tunnel-status path can omit it.
+  tunnelConfiguredForChannel?: () => boolean
+}
+
+export type GithubAdapter = {
+  start: () => Promise<void>
+  stop: () => Promise<void>
+  isConnected: () => boolean
+}
+
+const consoleLogger: GithubAdapterLogger = {
+  info: (m) => console.log(m),
+  warn: (m) => console.warn(m),
+  error: (m) => console.error(m),
+}
+
+export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapter {
+  const logger = options.logger ?? consoleLogger
+  const fetchImpl = options.fetchImpl ?? fetch
+  const auth = buildAuthStrategy({ auth: options.secrets.auth, fetchImpl })
+  const webhookSecret = resolveSecret(options.secrets.webhookSecret, undefined, process.env)
+  if (webhookSecret === undefined || webhookSecret.trim() === '') throw new Error('GitHub webhookSecret is missing')
+
+  let server: { stop: () => Promise<void> } | null = null
+  let selfId: string | null = null
+  let selfLogin: string | null = null
+  let started = false
+  let managedHooks: ReadonlyArray<{ repo: string; hookId: number }> = []
+  const workspaceByChat = new Map<string, string>()
+
+  const rememberWorkspace = (workspace: string, chat: string): void => {
+    workspaceByChat.set(chat, workspace)
+  }
+
+  const tokenFn = async () => {
+    const t = await auth.token()
+    process.env.GH_TOKEN = t
+    return t
+  }
+  const outbound = createGithubOutboundCallback({ token: tokenFn, logger, fetchImpl })
+  const history = createGithubHistoryCallback({
+    token: tokenFn,
+    fetchImpl,
+    workspaceForChat: (chat) => workspaceByChat.get(chat) ?? null,
+  })
+  const membership = createGithubMembershipResolver({ token: tokenFn, fetchImpl })
+  const channelNameResolver = createGithubChannelNameResolver({ token: tokenFn, fetchImpl })
+  const fetchAttachment = createGithubFetchAttachmentCallback()
+  // No-op typing callback: GitHub has no typing indicator API.
+  const typing = async (): Promise<void> => {}
+  const dedup = createDeliveryDedup()
+  const handler = createGithubWebhookHandler({
+    webhookSecret,
+    dedup,
+    allowlist: () => options.configRef().eventAllowlist,
+    selfId: () => selfId,
+    selfLogin: () => selfLogin,
+    logger,
+    route: (message) => {
+      rememberWorkspace(message.workspace, message.chat)
+      // Ack-first: wrap in Promise.resolve so a synchronous throw inside
+      // router.route() cannot prevent the 200 response from being returned.
+      void Promise.resolve()
+        .then(() => options.router.route(message))
+        .catch((err: unknown) => {
+          logger.error(`[github] route failed: ${err instanceof Error ? err.message : String(err)}`)
+        })
+    },
+  })
+
+  return {
+    async start(): Promise<void> {
+      if (started) return
+      const self = await auth.getSelf()
+      selfId = String(self.id)
+      selfLogin = self.login
+      // Register all callbacks before binding the HTTP listener so the router
+      // is fully wired before any webhook can arrive.
+      options.router.registerOutbound('github', outbound)
+      options.router.registerTyping('github', typing)
+      options.router.registerHistory('github', history)
+      options.router.registerMembership('github', membership)
+      options.router.registerChannelNameResolver('github', channelNameResolver)
+      options.router.registerFetchAttachment('github', fetchAttachment)
+      try {
+        server = (options.httpListenImpl ?? listenWithBun)(options.configRef().webhookPort, handler)
+      } catch (err) {
+        // Listener failed — roll back all registrations so stop() is a no-op
+        // and the manager can report the failure cleanly.
+        options.router.unregisterOutbound('github', outbound)
+        options.router.unregisterTyping('github', typing)
+        options.router.unregisterHistory('github', history)
+        options.router.unregisterMembership('github', membership)
+        options.router.unregisterChannelNameResolver('github', channelNameResolver)
+        options.router.unregisterFetchAttachment('github', fetchAttachment)
+        await auth.dispose()
+        delete process.env.GH_TOKEN
+        selfId = null
+        selfLogin = null
+        throw err
+      }
+      // Seed GH_TOKEN so `gh` CLI calls in the container are pre-authenticated.
+      // tokenFn keeps it current on every adapter API call; App tokens refresh
+      // automatically when within 5 minutes of expiry.
+      process.env.GH_TOKEN = await auth.token()
+      started = true
+      logger.info(`[github] webhook listening on port ${options.configRef().webhookPort} as @${self.login}`)
+      // Repository webhook registration is best-effort: failures are logged
+      // per-repo, the adapter stays up. A misconfigured PAT or App that
+      // can't manage hooks must not prevent the adapter from accepting
+      // events for repos whose hooks are already registered.
+      const cfg = options.configRef()
+      const repos = cfg.repos ?? []
+      const tunnelUrl = options.tunnelUrl?.() ?? null
+      if (cfg.webhookUrl !== undefined && tunnelUrl !== null) {
+        logger.warn('[github] webhookUrl configured; ignoring tunnel URL for webhook registration')
+      }
+      const rawUrl = cfg.webhookUrl ?? tunnelUrl
+      const managedPath = buildManagedPath(
+        resolveAgentId({ containerName: process.env.TYPECLAW_CONTAINER_NAME, agentDir: options.agentDir }),
+      )
+      const effectiveUrl = rawUrl === null ? null : applyManagedPath(rawUrl, managedPath)
+      if (effectiveUrl === null) {
+        logSkippedRegistration(logger, {
+          tunnelConfigured: options.tunnelConfiguredForChannel?.() ?? false,
+          reposCount: repos.length,
+        })
+      } else if (repos.length > 0) {
+        const legacyProviderHostSuffix = detectLegacyProviderHostSuffix(effectiveUrl)
+        const registration = await registerGithubWebhooks({
+          token: tokenFn,
+          webhookUrl: effectiveUrl,
+          webhookSecret,
+          repos,
+          events: cfg.eventAllowlist,
+          managedPath,
+          ...(legacyProviderHostSuffix !== undefined ? { legacyProviderHostSuffix } : {}),
+          fetchImpl,
+        })
+        managedHooks = registration.repos.flatMap((r) =>
+          r.action === 'created' || r.action === 'updated' ? [{ repo: r.repo, hookId: r.hookId }] : [],
+        )
+        logRegistrationOutcome(logger, registration)
+      }
+    },
+    async stop(): Promise<void> {
+      if (!started) return
+      started = false
+      options.router.unregisterOutbound('github', outbound)
+      options.router.unregisterTyping('github', typing)
+      options.router.unregisterHistory('github', history)
+      options.router.unregisterMembership('github', membership)
+      options.router.unregisterChannelNameResolver('github', channelNameResolver)
+      options.router.unregisterFetchAttachment('github', fetchAttachment)
+      await server?.stop()
+      // Detach hooks AFTER closing the listener so any in-flight deliveries
+      // from GitHub no longer hit a live receiver while we're tearing down.
+      // The token call uses the still-live `auth` strategy; dispose() runs
+      // last to clear the cached App-installation token.
+      if (managedHooks.length > 0) {
+        const deregistration = await deregisterGithubWebhooks({
+          token: tokenFn,
+          hooks: managedHooks,
+          fetchImpl,
+        })
+        logDeregistrationOutcome(logger, deregistration)
+        managedHooks = []
+      }
+      await auth.dispose()
+      delete process.env.GH_TOKEN
+      server = null
+      selfId = null
+      selfLogin = null
+    },
+    isConnected(): boolean {
+      return started && selfLogin !== null
+    },
+  }
+}
+
+function listenWithBun(port: number, handler: (req: Request) => Promise<Response>): { stop: () => Promise<void> } {
+  const server = Bun.serve({ port, fetch: handler })
+  return { stop: async () => server.stop() }
+}
+
+function logSkippedRegistration(
+  logger: GithubAdapterLogger,
+  context: { tunnelConfigured: boolean; reposCount: number },
+): void {
+  if (context.reposCount === 0) {
+    logger.info('[github] no repos[] configured; webhook registration skipped')
+    return
+  }
+  if (context.tunnelConfigured) {
+    logger.warn(
+      '[github] webhook registration SKIPPED: a tunnel is configured for this channel but produced no URL yet. ' +
+        "Check `typeclaw tunnel status` for the tunnel's health (cloudflared binary missing, " +
+        'auth failure, network issue). Webhook delivery will not work until the tunnel produces a public URL.',
+    )
+    return
+  }
+  logger.warn(
+    '[github] webhook registration SKIPPED: no `channels.github.webhookUrl` set and no `tunnels[]` entry ' +
+      'binds a public URL to this channel. Add an entry to `tunnels[]` (e.g. `provider: "cloudflare-quick"`) ' +
+      'or set `channels.github.webhookUrl` to a public URL to enable webhook delivery.',
+  )
+}
+
+// Known tunnel-provider host suffixes whose hostnames rotate per container.
+// A pre-marker hook on one of these is unambiguously a typeclaw orphan from
+// this agent's prior runs (cloudflare-quick is per-container, the host
+// changes every restart, so a stale unmarked *.trycloudflare.com hook
+// pointing at a now-dead host cannot belong to any live service).
+// Extending: add the host suffix here AND verify that hooks on the new
+// provider always look unmarked (no operator-supplied path) before the
+// marker was introduced.
+const LEGACY_TUNNEL_PROVIDER_HOSTS: readonly string[] = ['.trycloudflare.com']
+
+function detectLegacyProviderHostSuffix(url: string): string | undefined {
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch {
+    return undefined
+  }
+  for (const suffix of LEGACY_TUNNEL_PROVIDER_HOSTS) {
+    if (parsed.host.endsWith(suffix)) return suffix
+  }
+  return undefined
+}
+
+function logRegistrationOutcome(logger: GithubAdapterLogger, result: WebhookRegistrationResult): void {
+  for (const r of result.repos) {
+    if (r.action === 'created') logger.info(`[github] registered webhook ${r.hookId} on ${r.repo}`)
+    else if (r.action === 'updated') {
+      const tail = r.stalePruned > 0 ? ` (pruned ${r.stalePruned} stale)` : ''
+      logger.info(`[github] updated webhook ${r.hookId} on ${r.repo}${tail}`)
+    } else logger.warn(`[github] webhook register failed for ${r.repo}: ${r.error}`)
+  }
+}
+
+function logDeregistrationOutcome(
+  logger: GithubAdapterLogger,
+  result: Awaited<ReturnType<typeof deregisterGithubWebhooks>>,
+): void {
+  for (const h of result.hooks) {
+    if (h.action === 'deleted') logger.info(`[github] detached webhook ${h.hookId} from ${h.repo}`)
+    else if (h.action === 'missing') logger.info(`[github] webhook ${h.hookId} on ${h.repo} already gone`)
+    else logger.warn(`[github] webhook detach failed for ${h.repo}#${h.hookId}: ${h.error ?? 'unknown error'}`)
+  }
+}

package/src/channels/adapters/github/managed-path.ts

@@ -0,0 +1,54 @@
+import { basename, resolve } from 'node:path'
+
+// `v1` is a schema version for the marker layout. Bumping it lets a future
+// change (e.g. embedding a per-repo nonce, switching to a different ownership
+// scheme) coexist with hooks created under earlier versions instead of
+// stranding them. `findManagedHooks` only treats the current version as ours;
+// a v2 rollout would need a one-shot pass that adopts v1 hooks before
+// retiring them.
+const MARKER_PREFIX = '/typeclaw/v1/github/'
+
+export function buildManagedPath(agentId: string): string {
+  const safe = sanitizeAgentId(agentId)
+  return `${MARKER_PREFIX}${safe}`
+}
+
+// `containerName` (TYPECLAW_CONTAINER_NAME) is the load-bearing identifier
+// inside the container; falls back to the agent folder basename for host-side
+// callers (e.g. eager webhook install at `typeclaw channel add github` time)
+// that don't have the env var set yet. Both resolve to the same string in
+// practice — see `containerNameFromCwd` in src/container/shared.ts.
+export function resolveAgentId(options: { containerName?: string; agentDir: string }): string {
+  const fromEnv = options.containerName?.trim()
+  if (fromEnv && fromEnv.length > 0) return fromEnv
+  return basename(resolve(options.agentDir))
+}
+
+// Append the marker path to a URL that's missing one. The cloudflare-quick
+// tunnel hands us `https://<random>.trycloudflare.com` with no path; we want
+// the marker visible in the resulting webhook URL so a future run of THIS
+// agent can recognize the hook as ours after the hostname rotates.
+//
+// If the URL already has a non-trivial path (user-set webhookUrl), it's
+// returned verbatim. We treat that as "operator owns this URL" — appending
+// our marker would silently change a user-configured webhook URL.
+export function applyManagedPath(rawUrl: string, managedPath: string): string {
+  let parsed: URL
+  try {
+    parsed = new URL(rawUrl)
+  } catch {
+    return rawUrl
+  }
+  if (parsed.pathname !== '' && parsed.pathname !== '/') return rawUrl
+  parsed.pathname = managedPath
+  return parsed.toString()
+}
+
+// `containerNameFromCwd` (src/container/shared.ts) clamps to [a-z0-9_.-];
+// applying the same conservative shape here keeps URL paths well-formed even
+// if a caller passes us an unsanitized identifier from somewhere else.
+function sanitizeAgentId(raw: string): string {
+  const trimmed = raw.trim().toLowerCase()
+  const cleaned = trimmed.replace(/[^a-z0-9_.-]+/g, '-').replace(/^-+|-+$/g, '')
+  return cleaned === '' ? 'agent' : cleaned
+}