typeclaw 0.3.1 → 0.5.0

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

@@ -0,0 +1,370 @@
+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, options.secrets.auth.type)
+      }
+    },
+    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,
+  authType: 'pat' | 'app',
+): void {
+  const permissionFailures: Array<{ repo: string; status: number }> = []
+  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}`)
+      const status = parseListHooksPermissionStatus(r.error)
+      if (status !== null) permissionFailures.push({ repo: r.repo, status })
+    }
+  }
+  // One guidance block per start() (not per repo) so a 10-repo permission
+  // failure doesn't paste the same paragraph 10 times. The names below MUST
+  // match the current github.com UI labels — see comment in
+  // buildPermissionGuidance.
+  if (permissionFailures.length > 0) {
+    logger.warn(buildPermissionGuidance(authType, permissionFailures))
+  }
+}
+
+// Parses webhook-register errors of the shape `list hooks failed: <status> <body>`.
+// Returns the status code when it matches the two shapes GitHub emits for
+// missing access on the list-hooks endpoint:
+//   - 404 Not Found: the token cannot see the repo at all (private repo
+//     gated behind missing repository access — GitHub returns 404 instead of
+//     403 to avoid leaking the existence of private repos).
+//   - 403 Forbidden: the token sees the repo but lacks webhook-management
+//     permission, OR is blocked by an org SSO/SAML authorization gate.
+// Returns null for any other error (network, malformed slug, create-hook
+// failures, etc.) so the guidance only fires on the actual symptom.
+export function parseListHooksPermissionStatus(error: string): number | null {
+  const match = error.match(/^list hooks failed: (404|403)\b/)
+  if (match === null) return null
+  return Number(match[1])
+}
+
+// The labels below intentionally mirror github.com's current UI verbatim so a
+// user can grep their settings page for the exact string. If GitHub renames
+// any of these in a future redesign, update both here and the
+// `permissionGuidance` tests in lifecycle.test.ts.
+//
+//   Fine-grained PAT:
+//     Settings → Developer settings → Personal access tokens → Fine-grained tokens
+//     "Resource owner", "Repository access", "Repository permissions" → "Webhooks" → "Read and write", "Metadata" → "Read-only"
+//   GitHub App:
+//     Settings → Developer settings → GitHub Apps → <app> → Permissions & events
+//     "Repository permissions" → "Webhooks" → "Read and write"
+//     Install/configure on the org: <app settings> → Install App / Configure → "Repository access"
+//   Classic PAT (legacy, still supported by GitHub but we don't surface it in
+//     channel-add prompts):
+//     Settings → Developer settings → Personal access tokens (classic)
+//     Scope: "admin:repo_hook" (or full "repo" for private repositories)
+export function buildPermissionGuidance(
+  authType: 'pat' | 'app',
+  failures: ReadonlyArray<{ repo: string; status: number }>,
+): string {
+  const repoList = failures.map((f) => `${f.repo} (${f.status})`).join(', ')
+  const lines: string[] = [
+    `[github] webhook setup needs more access for: ${repoList}.`,
+    '  - 404 from GitHub means the token cannot see the repo (GitHub hides private repos behind 404 instead of 403).',
+    '  - 403 means the token sees the repo but lacks webhook permission, or is blocked by org SAML/SSO.',
+    '',
+  ]
+  if (authType === 'pat') {
+    lines.push(
+      '  Fix (fine-grained personal access token):',
+      '    1. Open https://github.com/settings/personal-access-tokens and edit the token TypeClaw is using.',
+      '    2. Under "Resource owner", select the org that owns the failing repos (e.g. the org in the slug above).',
+      '    3. Under "Repository access", choose "Only select repositories" and add every failing repo (or pick "All repositories").',
+      '    4. Under "Repository permissions", set "Webhooks" to "Read and write" and "Metadata" to "Read-only".',
+      '    5. Save. If the org enforces SAML SSO, click "Configure SSO" next to the token and authorize the org.',
+      '',
+      '  Or (classic personal access token): grant the "admin:repo_hook" scope (or "repo" for private repos),',
+      '  and on a SAML-protected org click "Authorize" next to the token.',
+    )
+  } else {
+    lines.push(
+      '  Fix (GitHub App):',
+      '    1. Open https://github.com/settings/apps and edit the app TypeClaw is using.',
+      '    2. Under "Permissions & events" → "Repository permissions", set "Webhooks" to "Read and write". Save.',
+      '    3. From the app page, click "Install App" (or "Configure" if already installed) and select the org that owns the failing repos.',
+      '    4. Under "Repository access", choose "Only select repositories" and add every failing repo (or pick "All repositories").',
+      '    5. If the app permissions changed in step 2, install owners must accept the updated permissions from the install page before the new access takes effect.',
+    )
+  }
+  return lines.join('\n')
+}
+
+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
+}

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

@@ -0,0 +1,35 @@
+import type { MembershipResolver, MembershipResolverResult } from '@/channels/membership'
+
+import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+import { parseRepo } from './outbound'
+
+export function createGithubMembershipResolver(options: {
+  token: () => Promise<string>
+  fetchImpl?: typeof fetch
+}): MembershipResolver {
+  const fetchImpl = options.fetchImpl ?? fetch
+  return async (key): Promise<MembershipResolverResult> => {
+    if (key.adapter !== 'github') return { kind: 'permanent' }
+    const repo = parseRepo(key.workspace)
+    if (repo === null) return { kind: 'permanent' }
+    try {
+      const response = await fetchImpl(
+        `${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/collaborators?per_page=100`,
+        {
+          headers: githubJsonHeaders(await options.token()),
+        },
+      )
+      if (!response.ok) return response.status >= 500 ? { kind: 'transient' } : { kind: 'permanent' }
+      const users = (await response.json()) as Array<{ type?: string }>
+      let bots = 0
+      let humans = 0
+      for (const user of users) {
+        if (user.type === 'Bot') bots++
+        else humans++
+      }
+      return { humans, bots, fetchedAt: Date.now(), truncated: users.length >= 100 }
+    } catch {
+      return { kind: 'transient' }
+    }
+  }
+}

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

@@ -0,0 +1,145 @@
+import type { OutboundCallback, OutboundMessage, SendResult } from '@/channels/types'
+
+import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+
+export type GithubOutboundLogger = { info: (m: string) => void; warn: (m: string) => void; error: (m: string) => void }
+
+export function createGithubOutboundCallback(deps: {
+  token: () => Promise<string>
+  logger: GithubOutboundLogger
+  fetchImpl?: typeof fetch
+}): OutboundCallback {
+  const fetchImpl = deps.fetchImpl ?? fetch
+  return async (msg: OutboundMessage): Promise<SendResult> => {
+    if (msg.adapter !== 'github') return { ok: false, error: `unknown adapter: ${msg.adapter}` }
+    if ((msg.attachments ?? []).length > 0) return { ok: false, error: 'github-bot-does-not-support-attachments' }
+    const body = msg.text ?? ''
+    if (body === '') return { ok: false, error: 'message has neither text nor attachments' }
+
+    const repo = parseRepo(msg.workspace)
+    if (repo === null) return { ok: false, error: `invalid GitHub workspace: ${msg.workspace}` }
+    const target = parseChat(msg.chat)
+    if (target === null) return { ok: false, error: `invalid GitHub chat: ${msg.chat}` }
+
+    if (target.kind === 'discussion') {
+      return await postDiscussionComment({ ...deps, fetchImpl, repo, discussionNumber: target.number, body })
+    }
+
+    const endpoint =
+      target.kind === 'pr' && msg.thread !== null && msg.thread !== undefined && msg.thread !== ''
+        ? `${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/pulls/${target.number}/comments/${encodeURIComponent(msg.thread)}/replies`
+        : `${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/issues/${target.number}/comments`
+    return await postJson(fetchImpl, await deps.token(), endpoint, { body })
+  }
+}
+
+async function postDiscussionComment(options: {
+  token: () => Promise<string>
+  fetchImpl: typeof fetch
+  repo: RepoRef
+  discussionNumber: number
+  body: string
+}): Promise<SendResult> {
+  const discussionId = await fetchDiscussionId(options)
+  if (!discussionId.ok) return discussionId
+  const mutation = `mutation($discussionId:ID!,$body:String!){addDiscussionComment(input:{discussionId:$discussionId,body:$body}){comment{id}}}`
+  return await postGraphql(options.fetchImpl, await options.token(), mutation, {
+    discussionId: discussionId.id,
+    body: options.body,
+  })
+}
+
+async function fetchDiscussionId(options: {
+  token: () => Promise<string>
+  fetchImpl: typeof fetch
+  repo: RepoRef
+  discussionNumber: number
+}): Promise<{ ok: true; id: string } | { ok: false; error: string }> {
+  const query = `query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){discussion(number:$number){id}}}`
+  const result = await graphql<{ repository?: { discussion?: { id?: string } | null } }>(
+    options.fetchImpl,
+    await options.token(),
+    query,
+    {
+      owner: options.repo.owner,
+      name: options.repo.name,
+      number: options.discussionNumber,
+    },
+  )
+  if (!result.ok) return result
+  const id = result.data.repository?.discussion?.id
+  return typeof id === 'string' && id !== '' ? { ok: true, id } : { ok: false, error: 'discussion not found' }
+}
+
+async function postGraphql(
+  fetchImpl: typeof fetch,
+  token: string,
+  query: string,
+  variables: Record<string, unknown>,
+): Promise<SendResult> {
+  const result = await graphql(fetchImpl, token, query, variables)
+  return result.ok ? { ok: true } : { ok: false, error: result.error }
+}
+
+async function graphql<T>(
+  fetchImpl: typeof fetch,
+  token: string,
+  query: string,
+  variables: Record<string, unknown>,
+): Promise<{ ok: true; data: T } | { ok: false; error: string }> {
+  try {
+    const response = await fetchImpl(`${GITHUB_API_BASE}/graphql`, {
+      method: 'POST',
+      headers: githubJsonHeaders(token),
+      body: JSON.stringify({ query, variables }),
+    })
+    const raw = (await response.json()) as { data?: T; errors?: Array<{ message?: string }> }
+    if (!response.ok || raw.errors !== undefined) {
+      return {
+        ok: false,
+        error: raw.errors?.map((e) => e.message ?? 'unknown').join('; ') ?? `HTTP ${response.status}`,
+      }
+    }
+    if (raw.data === undefined) return { ok: false, error: 'GraphQL response missing data' }
+    return { ok: true, data: raw.data }
+  } catch (err) {
+    return { ok: false, error: describe(err) }
+  }
+}
+
+async function postJson(fetchImpl: typeof fetch, token: string, url: string, payload: unknown): Promise<SendResult> {
+  try {
+    const response = await fetchImpl(url, {
+      method: 'POST',
+      headers: githubJsonHeaders(token),
+      body: JSON.stringify(payload),
+    })
+    if (response.ok) return { ok: true }
+    const text = await response.text().catch(() => '')
+    return { ok: false, error: `GitHub API ${response.status}${text !== '' ? `: ${text}` : ''}` }
+  } catch (err) {
+    return { ok: false, error: describe(err) }
+  }
+}
+
+type RepoRef = { owner: string; name: string }
+type ChatRef = { kind: 'issue' | 'pr' | 'discussion'; number: number }
+
+export function parseRepo(workspace: string): RepoRef | null {
+  const [owner, name, extra] = workspace.split('/')
+  if (!owner || !name || extra !== undefined) return null
+  return { owner, name }
+}
+
+export function parseChat(chat: string): ChatRef | null {
+  const [kind, rawNumber] = chat.split(':')
+  const number = Number(rawNumber)
+  if ((kind !== 'issue' && kind !== 'pr' && kind !== 'discussion') || !Number.isInteger(number) || number <= 0) {
+    return null
+  }
+  return { kind, number }
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}