typeclaw 0.3.1 → 0.4.0

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

package/src/channels/schema.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod'
 
-export const ADAPTER_IDS = ['discord-bot', 'kakaotalk', 'slack-bot', 'telegram-bot'] as const
+export const ADAPTER_IDS = ['discord-bot', 'github', 'kakaotalk', 'slack-bot', 'telegram-bot'] as const
 
 export type AdapterId = (typeof ADAPTER_IDS)[number]
 
@@ -99,6 +99,33 @@ const adapterSchema = z.object({
   enabled: z.boolean().default(true),
 })
 
+export const DEFAULT_GITHUB_EVENT_ALLOWLIST = [
+  'issue_comment.created',
+  'pull_request_review_comment.created',
+  'discussion_comment.created',
+  'issues.opened',
+  'pull_request.opened',
+  'discussion.created',
+  'pull_request_review.submitted',
+] as const
+
+const githubChannelSchema = adapterSchema.extend({
+  // Optional now (PR 2): when omitted and a `tunnels[]` entry with
+  // `for: { kind: 'channel', name: 'github' }` exists, the runtime resolves
+  // the URL from the tunnel manager via the adapter's `tunnelUrl` callback.
+  // The github adapter skips webhook registration when no effective URL is available.
+  webhookUrl: z.string().url().optional(),
+  webhookPort: z.number().int().positive().default(8975),
+  eventAllowlist: z.array(z.string()).default([...DEFAULT_GITHUB_EVENT_ALLOWLIST]),
+  // Repositories whose webhooks the adapter manages. Each entry is an
+  // `owner/name` slug. On adapter start(), TypeClaw registers a webhook
+  // pointing at webhookUrl for every repo here (idempotent: existing hooks
+  // at the same URL are updated). On stop(), every hook TypeClaw created
+  // this session is deleted so a restart with a different webhookUrl (e.g.
+  // a tunnel reassigning a URL) doesn't leave orphaned hooks on GitHub.
+  repos: z.array(z.string()).default([]),
+})
+
 // KakaoTalk uses the same shape as every other adapter. There used to be an
 // `autoMarkRead` opt-in here; the adapter now fires a LOCO NOTIREAD ack on
 // every inbound MSG event unconditionally (see kakaotalk.ts) so the sender's
@@ -112,6 +139,7 @@ const adapterSchema = z.object({
 export const channelsSchema = z
   .object({
     'discord-bot': adapterSchema.optional(),
+    github: githubChannelSchema.optional(),
     kakaotalk: adapterSchema.optional(),
     'slack-bot': adapterSchema.optional(),
     'telegram-bot': adapterSchema.optional(),
@@ -120,4 +148,6 @@ export const channelsSchema = z
 
 export type EngagementConfig = z.infer<typeof engagementSchema>
 export type ChannelAdapterConfig = z.infer<typeof adapterSchema>
+type ParsedGithubAdapterConfig = z.infer<typeof githubChannelSchema>
+export type GithubAdapterConfig = ParsedGithubAdapterConfig
 export type ChannelsConfig = z.infer<typeof channelsSchema>

package/src/channels/tunnel-bridge.ts

@@ -0,0 +1,51 @@
+import type { Stream } from '@/stream'
+import { isTunnelUrlChangedPayload } from '@/tunnels'
+
+import type { AdapterId } from './schema'
+
+export type TunnelBridgeLogger = {
+  info: (msg: string) => void
+  warn: (msg: string) => void
+  error: (msg: string) => void
+}
+
+export type TunnelBridgeChannelManager = {
+  restartAdapter: (name: AdapterId) => Promise<void>
+}
+
+export type TunnelBridgeOptions = {
+  stream: Stream
+  channelManager: TunnelBridgeChannelManager
+  logger?: TunnelBridgeLogger
+}
+
+export type TunnelBridge = {
+  stop: () => void
+}
+
+const consoleLogger: TunnelBridgeLogger = {
+  info: (msg) => console.log(msg),
+  warn: (msg) => console.warn(msg),
+  error: (msg) => console.error(msg),
+}
+
+export function createTunnelBridge(options: TunnelBridgeOptions): TunnelBridge {
+  const logger = options.logger ?? consoleLogger
+  // Subscribe synchronously; run/index.ts must create this bridge before
+  // tunnelManager.start() so an initial provider URL broadcast cannot be missed.
+  const unsubscribe = options.stream.subscribe({ target: { kind: 'broadcast' } }, (msg) => {
+    const payload = msg.payload
+    if (!isTunnelUrlChangedPayload(payload)) return
+    if (payload.for.kind !== 'channel') return
+    const name = (payload.for as { name?: unknown }).name
+    if (typeof name !== 'string') return
+    logger.info(`[tunnels] ${name} URL → restarting adapter`)
+    void options.channelManager.restartAdapter(name as AdapterId).catch((err: unknown) => {
+      logger.error(`[tunnels] failed to restart ${name} adapter: ${err instanceof Error ? err.message : String(err)}`)
+    })
+  })
+
+  return {
+    stop: unsubscribe,
+  }
+}

package/src/cli/builtins.ts

@@ -0,0 +1,28 @@
+// Single source of truth for the top-level `typeclaw` subcommands that the
+// CLI dispatches via citty. Plugin commands MUST NOT shadow these names.
+// `src/cli/index.ts` consumes this for argv interception; `src/plugin/registry.ts`
+// consumes it to reject plugin commands that collide.
+export const BUILTIN_COMMAND_NAMES = [
+  'init',
+  'run',
+  'tui',
+  'start',
+  'stop',
+  'restart',
+  'status',
+  'reload',
+  'logs',
+  'shell',
+  'compose',
+  'channel',
+  'cron',
+  'tunnel',
+  'role',
+  'provider',
+  'model',
+  'doctor',
+  'usage',
+  '_hostd',
+] as const
+
+export type BuiltinCommandName = (typeof BUILTIN_COMMAND_NAMES)[number]