typeclaw 0.3.1 → 0.4.0

package/README.md

@@ -35,6 +35,7 @@ TypeClaw is the agent I wanted to use:
 - 🔄 **Hot reload** — change `typeclaw.json`, `typeclaw reload` — no restart for most fields
 - 🔁 **Self-restart** — the agent can bounce its own container when it updates itself
 - 🌐 **Auto port-forward** — dev servers inside the container appear on `localhost`, even loopback-only ones
+- 🌍 **Public tunnels** — Cloudflare Quick (zero signup) or bring-your-own external URL; the agent self-registers GitHub webhooks at the resulting public URL
 - 🎼 **Compose** — orchestrate multiple agents across multiple folders
 
 ### 🌱 Self-improving, in detail
@@ -68,20 +69,23 @@ That's it. The agent is now alive, listening on a websocket, ready to receive pr
 
 ## CLI
 
-| Command                             | Purpose                                                                            |
-| ----------------------------------- | ---------------------------------------------------------------------------------- |
-| `typeclaw init`                     | Scaffold a new agent folder                                                        |
-| `typeclaw start`                    | Build and run the container                                                        |
-| `typeclaw stop`                     | Stop the container                                                                 |
-| `typeclaw restart`                  | `stop` then `start`                                                                |
-| `typeclaw status`                   | Show container + daemon registration state                                         |
-| `typeclaw logs`                     | Stream container stdout/stderr with local timestamps; `-f` to follow               |
-| `typeclaw tui`                      | Attach a terminal UI over the agent's websocket                                    |
-| `typeclaw shell`                    | Open a shell inside the running container                                          |
-| `typeclaw reload`                   | Push a live config reload to the running agent                                     |
-| `typeclaw compose`                  | Orchestrate multiple agents                                                        |
-| `typeclaw channel add <kind>`       | Wire a new channel adapter (Slack, Discord, Telegram, KakaoTalk)                   |
-| `typeclaw channel reauth kakaotalk` | Re-authenticate KakaoTalk after a stale-token 401 or to rotate the stored password |
+| Command                             | Purpose                                                                             |
+| ----------------------------------- | ----------------------------------------------------------------------------------- |
+| `typeclaw init`                     | Scaffold a new agent folder                                                         |
+| `typeclaw start`                    | Build and run the container                                                         |
+| `typeclaw stop`                     | Stop the container                                                                  |
+| `typeclaw restart`                  | `stop` then `start`                                                                 |
+| `typeclaw status`                   | Show container + daemon registration state                                          |
+| `typeclaw logs`                     | Stream container stdout/stderr with local timestamps; `-f` to follow                |
+| `typeclaw tui`                      | Attach a terminal UI over the agent's websocket                                     |
+| `typeclaw shell`                    | Open a shell inside the running container                                           |
+| `typeclaw reload`                   | Push a live config reload to the running agent                                      |
+| `typeclaw compose`                  | Orchestrate multiple agents                                                         |
+| `typeclaw cron list`                | List every cron job registered in the running agent (user `cron.json` + plugins)    |
+| `typeclaw channel add <kind>`       | Wire a new channel adapter (Slack, Discord, Telegram, KakaoTalk, GitHub)            |
+| `typeclaw channel set <kind>`       | Rotate the credentials of an already-configured channel (bot/app tokens, PAT, etc.) |
+| `typeclaw channel reauth kakaotalk` | Re-authenticate KakaoTalk after a stale-token 401 or to rotate the stored password  |
+| `typeclaw tunnel ...`               | Add/list/status/remove public tunnels and inspect tunnel logs                       |
 
 ## Configuration
 
@@ -107,7 +111,8 @@ my-agent/
 - `plugins` — list of plugin module specifiers
 - `channels` — `slack-bot` / `discord-bot` config
 - `portForward` — allow/deny list for auto port forwarding (default: `*`)
-- `dockerfile` — toggles for `gh`, `python`, `tmux`, `ffmpeg`, plus `append` lines
+- `tunnels` — declare public URLs for inbound webhooks and ad-hoc exposure (`cloudflare-quick` or `external`)
+- `dockerfile` — toggles for `gh`, `python`, `tmux`, `ffmpeg`, `cjkFonts`, plus `append` lines
 - `memory` — idle window and dreaming schedule for the memory plugin
 
 `Dockerfile` and `.gitignore` are owned by TypeClaw and rewritten on every `start` — edit `src/init/dockerfile.ts` and re-run `start --build` to ship template changes.

package/auth.schema.json

@@ -142,6 +142,119 @@
             }
           }
         },
+        "github": {
+          "type": "object",
+          "properties": {
+            "auth": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "pat"
+                    },
+                    "token": {
+                      "anyOf": [
+                        {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        {
+                          "type": "object",
+                          "properties": {
+                            "value": {
+                              "type": "string",
+                              "minLength": 1
+                            },
+                            "env": {
+                              "type": "string",
+                              "minLength": 1
+                            }
+                          }
+                        }
+                      ]
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "token"
+                  ]
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "app"
+                    },
+                    "appId": {
+                      "type": "integer",
+                      "exclusiveMinimum": 0,
+                      "maximum": 9007199254740991
+                    },
+                    "privateKey": {
+                      "anyOf": [
+                        {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        {
+                          "type": "object",
+                          "properties": {
+                            "value": {
+                              "type": "string",
+                              "minLength": 1
+                            },
+                            "env": {
+                              "type": "string",
+                              "minLength": 1
+                            }
+                          }
+                        }
+                      ]
+                    },
+                    "installationId": {
+                      "type": "integer",
+                      "exclusiveMinimum": 0,
+                      "maximum": 9007199254740991
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "appId",
+                    "privateKey"
+                  ]
+                }
+              ]
+            },
+            "webhookSecret": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "minLength": 1
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "value": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "env": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
+                }
+              ]
+            }
+          },
+          "required": [
+            "auth",
+            "webhookSecret"
+          ]
+        },
         "telegram-bot": {
           "type": "object",
           "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/secrets.schema.json

@@ -142,6 +142,119 @@
             }
           }
         },
+        "github": {
+          "type": "object",
+          "properties": {
+            "auth": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "pat"
+                    },
+                    "token": {
+                      "anyOf": [
+                        {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        {
+                          "type": "object",
+                          "properties": {
+                            "value": {
+                              "type": "string",
+                              "minLength": 1
+                            },
+                            "env": {
+                              "type": "string",
+                              "minLength": 1
+                            }
+                          }
+                        }
+                      ]
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "token"
+                  ]
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "app"
+                    },
+                    "appId": {
+                      "type": "integer",
+                      "exclusiveMinimum": 0,
+                      "maximum": 9007199254740991
+                    },
+                    "privateKey": {
+                      "anyOf": [
+                        {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        {
+                          "type": "object",
+                          "properties": {
+                            "value": {
+                              "type": "string",
+                              "minLength": 1
+                            },
+                            "env": {
+                              "type": "string",
+                              "minLength": 1
+                            }
+                          }
+                        }
+                      ]
+                    },
+                    "installationId": {
+                      "type": "integer",
+                      "exclusiveMinimum": 0,
+                      "maximum": 9007199254740991
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "appId",
+                    "privateKey"
+                  ]
+                }
+              ]
+            },
+            "webhookSecret": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "minLength": 1
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "value": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "env": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
+                }
+              ]
+            }
+          },
+          "required": [
+            "auth",
+            "webhookSecret"
+          ]
+        },
         "telegram-bot": {
           "type": "object",
           "properties": {

package/src/agent/session-meta.ts

@@ -8,7 +8,7 @@ export type SessionMetaPayload = {
 
 export type MinimalSessionOrigin =
   | { kind: 'tui' }
-  | { kind: 'cron'; jobId: string; jobKind: 'prompt' | 'exec' | 'subagent' }
+  | { kind: 'cron'; jobId: string; jobKind: 'prompt' | 'exec' | 'subagent' | 'handler' }
   | { kind: 'channel'; adapter: string; workspace: string; chat: string; thread: string | null }
   | { kind: 'subagent'; subagent: string; parentSessionId: string }
 

package/src/agent/session-origin.ts

@@ -25,7 +25,7 @@ export type SessionOrigin =
   | {
       kind: 'cron'
       jobId: string
-      jobKind: 'prompt' | 'exec' | 'subagent'
+      jobKind: 'prompt' | 'exec' | 'subagent' | 'handler'
       scheduledByRole?: string
       scheduledByOrigin?: SessionOrigin | { kind: 'config-file' }
     }
@@ -78,6 +78,7 @@ type PlatformInfo = {
 const PLATFORM_INFO: Record<AdapterId, PlatformInfo> = {
   'slack-bot': { displayName: 'Slack', mentionMode: 'angle-id' },
   'discord-bot': { displayName: 'Discord', mentionMode: 'angle-id' },
+  github: { displayName: 'GitHub', mentionMode: 'at-username' },
   'telegram-bot': { displayName: 'Telegram', mentionMode: 'at-username' },
   kakaotalk: { displayName: 'KakaoTalk', mentionMode: 'alias' },
 }
@@ -150,7 +151,7 @@ function renderTuiOrigin(): string {
   ].join('\n')
 }
 
-function renderCronOrigin(origin: { jobId: string; jobKind: 'prompt' | 'exec' | 'subagent' }): string {
+function renderCronOrigin(origin: { jobId: string; jobKind: 'prompt' | 'exec' | 'subagent' | 'handler' }): string {
   return [
     '## Session origin',
     '',

package/src/bundled-plugins/security/index.ts

@@ -25,8 +25,9 @@ export { SECURITY_PERMISSIONS, type SecurityPermission } from './permissions'
 // it's the only carrier.
 const BYPASS_ROLE_HINT = {
   [SECURITY_PERMISSIONS.bypassSecretExfilBash]: 'owner and trusted have it by default',
-  [SECURITY_PERMISSIONS.bypassGitExfil]: 'only owner has it by default',
-  [SECURITY_PERMISSIONS.bypassGitRemoteTainted]: 'only owner has it by default',
+  [SECURITY_PERMISSIONS.bypassGitExfil]: 'owner and trusted have it by default',
+  [SECURITY_PERMISSIONS.bypassGitRemoteTainted]:
+    'only owner has it by default (trusted intentionally does not, so the two-step taint defense still fires)',
   [SECURITY_PERMISSIONS.bypassSecretExfilRead]: 'only owner has it by default',
   [SECURITY_PERMISSIONS.bypassSsrf]: 'only owner has it by default',
   [SECURITY_PERMISSIONS.bypassSessionSearchSecrets]: 'only owner has it by default',

package/src/channels/adapters/github/auth-app.ts

@@ -0,0 +1,120 @@
+import { resolveSecret, type Secret } from '@/secrets/resolve'
+
+import type { GithubAuthStrategy, GithubSelfUser } from './auth'
+import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+
+export class AppAuthStrategy implements GithubAuthStrategy {
+  private readonly appId: number
+  private readonly privateKeyPem: string
+  private readonly installationId: number | null
+  private readonly fetchImpl: typeof fetch
+  private cachedToken: { value: string; expiresAt: number } | null = null
+  private resolvedInstallationId: number | null = null
+  private _selfUser: GithubSelfUser | null = null
+
+  constructor(options: { appId: number; privateKey: Secret; installationId?: number; fetchImpl?: typeof fetch }) {
+    const privateKeyPem = resolveSecret(options.privateKey, undefined, process.env)
+    if (privateKeyPem === undefined || privateKeyPem.trim() === '') throw new Error('GitHub App private key is missing')
+    this.appId = options.appId
+    this.privateKeyPem = privateKeyPem
+    this.installationId = options.installationId ?? null
+    this.fetchImpl = options.fetchImpl ?? fetch
+  }
+
+  async token(): Promise<string> {
+    if (this.cachedToken && Date.now() < this.cachedToken.expiresAt - 5 * 60 * 1000) {
+      return this.cachedToken.value
+    }
+    const jwt = await this.mintJwt()
+    const installId = await this.resolveInstallationId(jwt)
+    const response = await this.fetchImpl(`${GITHUB_API_BASE}/app/installations/${installId}/access_tokens`, {
+      method: 'POST',
+      headers: githubJsonHeaders(jwt),
+    })
+    if (!response.ok) throw new Error(`GitHub App token mint failed: ${response.status}`)
+    const raw = (await response.json()) as { token?: unknown; expires_at?: unknown }
+    if (typeof raw.token !== 'string') throw new Error('GitHub App token response missing token')
+    const expiresAt = typeof raw.expires_at === 'string' ? Date.parse(raw.expires_at) : Date.now() + 60 * 60 * 1000
+    this.cachedToken = { value: raw.token, expiresAt }
+    return raw.token
+  }
+
+  async authHeaders(): Promise<HeadersInit> {
+    return githubJsonHeaders(await this.token())
+  }
+
+  async getSelf(): Promise<GithubSelfUser> {
+    if (this._selfUser) return this._selfUser
+    const jwt = await this.mintJwt()
+    const appResponse = await this.fetchImpl(`${GITHUB_API_BASE}/app`, { headers: githubJsonHeaders(jwt) })
+    if (!appResponse.ok) throw new Error(`GitHub App preflight failed: ${appResponse.status}`)
+    const app = (await appResponse.json()) as { slug?: unknown }
+    if (typeof app.slug !== 'string') throw new Error('GitHub /app response missing slug')
+
+    const botLogin = `${app.slug}[bot]`
+    const userResponse = await this.fetchImpl(`${GITHUB_API_BASE}/users/${encodeURIComponent(botLogin)}`, {
+      headers: githubJsonHeaders(jwt),
+    })
+    if (!userResponse.ok) throw new Error(`GitHub bot user lookup failed: ${userResponse.status}`)
+    const user = (await userResponse.json()) as { id?: unknown; login?: unknown }
+    if (typeof user.id !== 'number' || typeof user.login !== 'string') {
+      throw new Error('GitHub bot user response missing id/login')
+    }
+    this._selfUser = { id: user.id, login: user.login }
+    return this._selfUser
+  }
+
+  async dispose(): Promise<void> {
+    this.cachedToken = null
+  }
+
+  private async mintJwt(): Promise<string> {
+    const now = Math.floor(Date.now() / 1000)
+    const iat = now - 60
+    const exp = iat + 600
+    const header = base64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }))
+    const payload = base64url(JSON.stringify({ iat, exp, iss: this.appId }))
+    const signingInput = `${header}.${payload}`
+    const key = await importRsaPrivateKey(this.privateKeyPem)
+    const signature = await crypto.subtle.sign(
+      { name: 'RSASSA-PKCS1-v1_5' },
+      key,
+      new TextEncoder().encode(signingInput),
+    )
+    return `${signingInput}.${base64url(Buffer.from(signature))}`
+  }
+
+  private async resolveInstallationId(jwt: string): Promise<number> {
+    if (this.resolvedInstallationId !== null) return this.resolvedInstallationId
+    if (this.installationId !== null) {
+      this.resolvedInstallationId = this.installationId
+      return this.installationId
+    }
+    const response = await this.fetchImpl(`${GITHUB_API_BASE}/app/installations`, { headers: githubJsonHeaders(jwt) })
+    if (!response.ok) throw new Error(`GitHub App installations fetch failed: ${response.status}`)
+    const list = (await response.json()) as Array<{ id?: unknown }>
+    if (list.length === 0) throw new Error('GitHub App has no installations')
+    if (list.length > 1) {
+      const ids = list.map((installation) => installation.id).join(', ')
+      throw new Error(`GitHub App has multiple installations (${ids}); set installationId in secrets.json`)
+    }
+    const id = list[0]?.id
+    if (typeof id !== 'number') throw new Error('GitHub App installation missing id')
+    this.resolvedInstallationId = id
+    return id
+  }
+}
+
+function base64url(input: string | Buffer): string {
+  const buf = typeof input === 'string' ? Buffer.from(input) : input
+  return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')
+}
+
+async function importRsaPrivateKey(pem: string): Promise<CryptoKey> {
+  const b64 = pem
+    .replace(/-----BEGIN [^-]+-----/, '')
+    .replace(/-----END [^-]+-----/, '')
+    .replace(/\s/g, '')
+  const der = Buffer.from(b64, 'base64')
+  return await crypto.subtle.importKey('pkcs8', der, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['sign'])
+}

package/src/channels/adapters/github/auth-pat.ts

@@ -0,0 +1,50 @@
+import { resolveSecret, type Secret } from '@/secrets/resolve'
+
+import type { GithubAuthStrategy, GithubSelfUser } from './auth'
+
+export const GITHUB_API_BASE = 'https://api.github.com'
+
+export class PatAuthStrategy implements GithubAuthStrategy {
+  private readonly _token: string
+  private readonly fetchImpl: typeof fetch
+
+  constructor(options: { token: Secret; fetchImpl?: typeof fetch }) {
+    const token = resolveSecret(options.token, undefined, process.env)
+    if (token === undefined || token.trim() === '') throw new Error('GitHub PAT token is missing')
+    this._token = token
+    this.fetchImpl = options.fetchImpl ?? fetch
+  }
+
+  async token(): Promise<string> {
+    return this._token
+  }
+
+  async authHeaders(): Promise<HeadersInit> {
+    return githubJsonHeaders(this._token)
+  }
+
+  async getSelf(): Promise<GithubSelfUser> {
+    const response = await this.fetchImpl(`${GITHUB_API_BASE}/user`, { headers: await this.authHeaders() })
+    if (!response.ok) {
+      const body = await response.text().catch(() => '')
+      throw new Error(`GitHub PAT authentication failed: ${response.status}${body !== '' ? ` ${body}` : ''}`)
+    }
+    const raw = (await response.json()) as { login?: unknown; id?: unknown }
+    if (typeof raw.login !== 'string' || typeof raw.id !== 'number') {
+      throw new Error('GitHub /user response did not include login/id')
+    }
+    return { login: raw.login, id: raw.id }
+  }
+
+  async dispose(): Promise<void> {}
+}
+
+export function githubJsonHeaders(token: string): HeadersInit {
+  return {
+    Authorization: `Bearer ${token}`,
+    Accept: 'application/vnd.github+json',
+    'Content-Type': 'application/json',
+    'X-GitHub-Api-Version': '2022-11-28',
+    'User-Agent': 'typeclaw-github-channel',
+  }
+}

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

@@ -0,0 +1,33 @@
+import type { GithubAppAuthBlock, GithubPatAuthBlock } from '@/secrets/schema'
+
+import { AppAuthStrategy } from './auth-app'
+import { PatAuthStrategy } from './auth-pat'
+
+export type GithubAuthStrategy = {
+  token: () => Promise<string>
+  authHeaders: () => Promise<HeadersInit>
+  getSelf: () => Promise<GithubSelfUser>
+  dispose: () => Promise<void>
+}
+
+export type GithubSelfUser = {
+  login: string
+  id: number
+}
+
+export function buildAuthStrategy(options: {
+  auth: GithubPatAuthBlock | GithubAppAuthBlock
+  fetchImpl?: typeof fetch
+}): GithubAuthStrategy {
+  switch (options.auth.type) {
+    case 'pat':
+      return new PatAuthStrategy({ token: options.auth.token, fetchImpl: options.fetchImpl })
+    case 'app':
+      return new AppAuthStrategy({
+        appId: options.auth.appId,
+        privateKey: options.auth.privateKey,
+        installationId: options.auth.installationId,
+        fetchImpl: options.fetchImpl,
+      })
+  }
+}

package/src/channels/adapters/github/channel-resolver.ts

@@ -0,0 +1,30 @@
+import type { ChannelNameResolver, ResolvedChannelNames } from '@/channels/types'
+
+import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+import { parseChat, parseRepo } from './outbound'
+
+export function createGithubChannelNameResolver(options: {
+  token: () => Promise<string>
+  fetchImpl?: typeof fetch
+}): ChannelNameResolver {
+  const fetchImpl = options.fetchImpl ?? fetch
+  return async (key): Promise<ResolvedChannelNames> => {
+    if (key.adapter !== 'github') return {}
+    const repo = parseRepo(key.workspace)
+    const chat = parseChat(key.chat)
+    if (repo === null || chat === null) return {}
+    const names: ResolvedChannelNames = { workspaceName: key.workspace }
+    if (chat.kind === 'discussion') return names
+    const path = chat.kind === 'issue' ? `issues/${chat.number}` : `pulls/${chat.number}`
+    try {
+      const response = await fetchImpl(`${GITHUB_API_BASE}/repos/${repo.owner}/${repo.name}/${path}`, {
+        headers: githubJsonHeaders(await options.token()),
+      })
+      if (!response.ok) return names
+      const raw = (await response.json()) as { title?: string }
+      return raw.title !== undefined ? { ...names, chatName: raw.title } : names
+    } catch {
+      return names
+    }
+  }
+}

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

@@ -0,0 +1,26 @@
+export type DeliveryDedup = {
+  has: (deliveryId: string) => boolean
+  add: (deliveryId: string) => void
+  size: () => number
+}
+
+export function createDeliveryDedup(limit = 1000): DeliveryDedup {
+  const seen = new Map<string, true>()
+  return {
+    has(deliveryId: string): boolean {
+      return seen.has(deliveryId)
+    },
+    add(deliveryId: string): void {
+      if (seen.has(deliveryId)) seen.delete(deliveryId)
+      seen.set(deliveryId, true)
+      while (seen.size > limit) {
+        const oldest = seen.keys().next().value
+        if (oldest === undefined) break
+        seen.delete(oldest)
+      }
+    },
+    size(): number {
+      return seen.size
+    },
+  }
+}

package/src/channels/adapters/github/event-allowlist.ts

@@ -0,0 +1,8 @@
+export function githubEventKey(event: string, action: unknown): string {
+  return typeof action === 'string' && action.length > 0 ? `${event}.${action}` : event
+}
+
+export function isGithubEventAllowed(allowlist: readonly string[], event: string, action: unknown): boolean {
+  const key = githubEventKey(event, action)
+  return allowlist.includes(key) || allowlist.includes(event)
+}

package/src/channels/adapters/github/fetch-attachment.ts

@@ -0,0 +1,5 @@
+import type { FetchAttachmentCallback } from '@/channels/types'
+
+export function createGithubFetchAttachmentCallback(): FetchAttachmentCallback {
+  return async () => ({ ok: false, error: 'github-bot-does-not-support-attachments' })
+}