typeclaw 0.3.1 → 0.4.0

package/src/init/dockerfile.ts

@@ -56,6 +56,19 @@ export const CURL_IMPERSONATE_SHA256_ARM64 = '6766bc67fd3e8e2313875f32b36b5a3fab
 // the impersonation to whatever `curl_chrome` resolves to.
 export const CURL_IMPERSONATE_PROFILE = 'chrome136'
 
+// cloudflared powers `cloudflare-quick` tunnels. Pinned-version + per-arch
+// SHA256 mirrors the curl-impersonate pattern above: bumping requires updating
+// all three constants in the same commit, and the build fails loudly at
+// `sha256sum -c` if either hash is wrong for the version. To bump: pick a
+// release from https://github.com/cloudflare/cloudflared/releases, then
+//   curl -fsSLO .../cloudflared-linux-amd64 && shasum -a 256 cloudflared-linux-amd64
+// for each architecture. The version literal is the release tag exactly as it
+// appears on GitHub (no `v` prefix).
+export const CLOUDFLARED_VERSION = '2025.5.0'
+export const CLOUDFLARED_SHA256_AMD64 = 'a62266fd02041374f1fca0d85694aafdf7e26e171a314467356b471d4ebb2393'
+export const CLOUDFLARED_SHA256_ARM64 = '47e55e6eba2755239f641c2c4f89878643ac0d9eaa127a6c84a2cb43fa2e0f03'
+export const CLOUDFLARED_RELEASE_URL_BASE = 'https://github.com/cloudflare/cloudflared/releases/download'
+
 export const TYPECLAW_ENTRYPOINT_PATH = '/usr/local/bin/typeclaw-entrypoint'
 
 // IPv4 networks the container is forbidden to egress to when
@@ -283,9 +296,11 @@ RUN echo "${encoded}" | base64 -d > ${TYPECLAW_ENTRYPOINT_PATH} \\
 // names are the trixie-renamed variants from the 64-bit time_t ABI
 // transition; SONAMEs (libglib-2.0.so.0 etc.) are unchanged. Packages
 // without t64 here have no t64 sibling on trixie — verified against
-// packages.debian.org/trixie. Fonts are intentionally omitted: the
-// reported failure is launch-time linker errors, not rendering glyphs;
-// font packages (esp. fonts-noto-cjk) cost ~50MB+ for no launch impact.
+// packages.debian.org/trixie. Fonts are intentionally omitted from this
+// list: the failure these packages address is launch-time linker errors,
+// not rendering glyphs. CJK glyph rendering is a separate concern handled
+// by the `cjkFonts` toggle (see CJK_FONTS_PACKAGE / APT_FEATURES below),
+// which layers `fonts-noto-cjk` on top via the toggle apt install path.
 export const CHROME_RUNTIME_APT_PACKAGES_AMD64 = [
   'libasound2t64',
   'libatk-bridge2.0-0t64',
@@ -310,17 +325,26 @@ export const CHROME_RUNTIME_APT_PACKAGES_AMD64 = [
   'libxrandr2',
 ] as const
 
+// `fonts-noto-cjk` provides CJK glyphs for Chromium-rendered output
+// (screenshots, page.pdf()). Without it CJK text in agent-browser output
+// renders as `.notdef` tofu boxes. Treated as a toggle apt package (like
+// gh/tmux) rather than a base-image staple so users with `cjkFonts: false`
+// genuinely skip the ~56MB layer; baking into the base image would force
+// every GHCR-base user to ship the fonts regardless of their opt-out.
+export const CJK_FONTS_PACKAGE = 'fonts-noto-cjk'
+
 type AptFeature = {
   toAptArgs: (toggle: DockerfileFeatureToggle) => string[]
 }
 
-const APT_FEATURES: Record<'ffmpeg' | 'gh' | 'tmux' | 'python', AptFeature> = {
+const APT_FEATURES: Record<'ffmpeg' | 'gh' | 'tmux' | 'python' | 'cjkFonts', AptFeature> = {
   ffmpeg: { toAptArgs: (v) => singlePackageArgs('ffmpeg', v) },
   gh: { toAptArgs: (v) => singlePackageArgs('gh', v) },
   tmux: { toAptArgs: (v) => singlePackageArgs('tmux', v) },
   python: {
     toAptArgs: (v) => (v === true ? ['python3', 'python3-pip', 'python3-venv', 'python-is-python3'] : []),
   },
+  cjkFonts: { toAptArgs: (v) => (v === true ? [CJK_FONTS_PACKAGE] : []) },
 }
 
 export function buildDockerfile(
@@ -329,13 +353,14 @@ export function buildDockerfile(
 ): string {
   const toggleAptArgs = collectToggleAptArgs(config)
   const ghKeyringLayer = renderGhKeyringLayer(config.gh)
+  const cloudflaredLayer = renderCloudflaredLayer(config.cloudflared)
   const customLines = renderCustomDockerfileLines(config.append)
   const baseImageVersion = options.baseImageVersion ?? null
 
   const fromAndHeavyLayers =
     baseImageVersion !== null
-      ? renderVersionedHead(baseImageVersion, ghKeyringLayer, toggleAptArgs)
-      : renderInlineHead(ghKeyringLayer, toggleAptArgs)
+      ? renderVersionedHead(baseImageVersion, ghKeyringLayer, toggleAptArgs, cloudflaredLayer)
+      : renderInlineHead(ghKeyringLayer, toggleAptArgs, cloudflaredLayer)
 
   return `${BUILDKIT_HEADER}
 # AUTOGENERATED by typeclaw — do not edit.
@@ -377,7 +402,12 @@ CMD ["run"]
 // npm + `typeclaw start --build` immediately, instead of being blocked on a
 // fresh base-image release. The base image's copy is harmlessly overwritten
 // by this RUN — same path, same chmod.
-function renderVersionedHead(baseImageVersion: string, ghKeyringLayer: string, toggleAptArgs: string[]): string {
+function renderVersionedHead(
+  baseImageVersion: string,
+  ghKeyringLayer: string,
+  toggleAptArgs: string[],
+  cloudflaredLayer: string,
+): string {
   const toggleAptLayer = toggleAptArgs.length === 0 ? '' : `${renderToggleAptInstallLayer(toggleAptArgs)}\n\n`
   return `FROM ${GHCR_BASE_IMAGE_REPO}:${baseImageVersion}
 
@@ -385,7 +415,7 @@ WORKDIR /agent
 
 ARG TARGETARCH
 
-${ghKeyringLayer}${toggleAptLayer}${renderEntrypointShimLayer()}
+${ghKeyringLayer}${toggleAptLayer}${cloudflaredLayer}${renderEntrypointShimLayer()}
 
 `
 }
@@ -394,7 +424,7 @@ ${ghKeyringLayer}${toggleAptLayer}${renderEntrypointShimLayer()}
 // dev-mode runs (typeclaw installed via file: / link: spec) where the
 // matching :version GHCR tag does not yet exist, and by the test suite to
 // keep coverage of the full-stack layers independent of GHCR availability.
-function renderInlineHead(ghKeyringLayer: string, toggleAptArgs: string[]): string {
+function renderInlineHead(ghKeyringLayer: string, toggleAptArgs: string[], cloudflaredLayer: string): string {
   const baselineAndToggleArgs = [...BASELINE_APT_PACKAGES, ...toggleAptArgs]
   return `${FROM_AND_WORKDIR}
 
@@ -436,7 +466,23 @@ ${LAYER_4_AGENT_BROWSER_INSTALL}
 
 ${LAYER_5_CHROME_FOR_TESTING}
 
-${renderEntrypointShimLayer()}
+${cloudflaredLayer}${renderEntrypointShimLayer()}
+
+`
+}
+
+function renderCloudflaredLayer(enabled: boolean): string {
+  if (!enabled) return ''
+  return `# Layer 5.5 (optional): pinned cloudflared for cloudflare-quick tunnels.
+RUN ARCH_BIN="$(if [ "$TARGETARCH" = "arm64" ]; then echo arm64; else echo amd64; fi)" \
+ && ARCH_SHA="$(if [ "$TARGETARCH" = "arm64" ]; then echo ${CLOUDFLARED_SHA256_ARM64}; else echo ${CLOUDFLARED_SHA256_AMD64}; fi)" \
+ && cd /tmp \
+ && curl -fsSL -o cloudflared \
+      "${CLOUDFLARED_RELEASE_URL_BASE}/${CLOUDFLARED_VERSION}/cloudflared-linux-\${ARCH_BIN}" \
+ && echo "\${ARCH_SHA}  cloudflared" | sha256sum -c - \
+ && chmod +x cloudflared \
+ && mv cloudflared /usr/local/bin/cloudflared \
+ && /usr/local/bin/cloudflared --version > /dev/null
 
 `
 }
@@ -444,7 +490,7 @@ ${renderEntrypointShimLayer()}
 function renderToggleAptInstallLayer(toggleAptArgs: string[]): string {
   return `# Layer 1 (toggle apt install): packages requested via typeclaw.json
 # #docker.file toggles. Baseline + Chrome runtime libs are already in the
-# base image; this layer only adds gh/tmux/python/ffmpeg if enabled.
+# base image; this layer only adds gh/tmux/python/ffmpeg/cjkFonts if enabled.
 RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
     --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \\
     apt-get update \\
@@ -570,12 +616,12 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
     fi`
 
 function defaultConfig(): DockerfileConfig {
-  return { ffmpeg: false, gh: true, python: true, tmux: true, append: [] }
+  return { ffmpeg: false, gh: true, python: true, tmux: true, cjkFonts: true, cloudflared: true, append: [] }
 }
 
 function collectToggleAptArgs(config: DockerfileConfig): string[] {
   const args: string[] = []
-  for (const key of ['ffmpeg', 'gh', 'python', 'tmux'] as const) {
+  for (const key of ['ffmpeg', 'gh', 'python', 'tmux', 'cjkFonts'] as const) {
     args.push(...APT_FEATURES[key].toAptArgs(config[key]))
   }
   return args

package/src/init/ensure-deps.ts

@@ -15,24 +15,35 @@ export type EnsureDepsOptions = {
   cwd: string
   install?: InstallRunner
   detect?: (cwd: string) => Promise<readonly string[]>
+  // Skip the pre-install drift detection and run `bun install --force`
+  // unconditionally. Used by `typeclaw start --build` when the agent declares
+  // typeclaw via `file:` or `link:`: bun's file-dep cache otherwise treats
+  // unchanged name+version as a cache hit even after the source on disk has
+  // changed, so the post-install re-detect at the bottom (the silent-no-op
+  // guard) stays — `--force` does NOT excuse us from verifying the install
+  // actually populated the agent's node_modules/.
+  force?: boolean
 }
 
 export async function ensureDepsInstalled(options: EnsureDepsOptions): Promise<EnsureDepsResult> {
   const { cwd } = options
   const install = options.install ?? runBunInstall
   const detect = options.detect ?? detectMissingDeps
+  const force = options.force ?? false
 
-  const missing = await detect(cwd)
-  if (missing.length === 0) return { ok: true, installed: false }
+  const missing = force ? [] : await detect(cwd)
+  if (!force && missing.length === 0) return { ok: true, installed: false }
 
-  const result = await install(cwd)
+  const result = await install(cwd, { force })
   if (!result.ok) return { ok: false, reason: result.reason, missing }
 
   // Re-probe: `bun install` returns 0 even when a file:-linked dep's own
   // package.json is unreachable (it silently no-ops on the target). Without
   // this check, we'd proceed to `docker run` with a known-broken
   // node_modules/ and the agent would crash with a confusing in-container
-  // `Cannot find package 'x'`.
+  // `Cannot find package 'x'`. This guard remains under `force` too —
+  // --force bypasses the cache but does not guarantee the install actually
+  // landed every declared dep.
   const stillMissing = await detect(cwd)
   if (stillMissing.length > 0) {
     return {

package/src/init/github-webhook-install.ts

@@ -0,0 +1,109 @@
+import { buildAuthStrategy } from '@/channels/adapters/github/auth'
+import { applyManagedPath, buildManagedPath, resolveAgentId } from '@/channels/adapters/github/managed-path'
+import { registerGithubWebhooks, type WebhookRegistrationResult } from '@/channels/adapters/github/webhook-register'
+import { DEFAULT_GITHUB_EVENT_ALLOWLIST } from '@/channels/schema'
+
+import type { GithubInitCredentials } from './index'
+
+// Host-side webhook install for `typeclaw channel add github` (and the
+// init-time GitHub branch). The container-side adapter still re-runs this on
+// every start so a missing/rotated tunnel URL eventually catches up, but
+// doing it eagerly here means the user sees the install succeed at CLI
+// time — no more "I added the channel, why isn't GitHub delivering events?"
+// when the URL is already known (external provider, or a user-set
+// webhookUrl).
+//
+// Only fires when an effective webhook URL is known up front: external
+// tunnel provider, or an explicit `webhookUrl`. Cloudflare quick tunnels
+// don't resolve until cloudflared boots inside the container, so they
+// stay on the existing deferred (tunnel-bridge → restartAdapter) path.
+
+export type EagerGithubWebhookInstallOptions = {
+  webhookUrl: string
+  webhookSecret: string
+  repos: readonly string[]
+  events?: readonly string[]
+  auth: GithubInitCredentials['auth']
+  // Agent folder (or container name). Used to derive a stable webhook URL
+  // path marker so this eager-installed hook is recognizable to the
+  // container-side adapter on every subsequent start, even after the
+  // public URL's hostname rotates. Optional only because legacy direct
+  // callers (host-side init flows on stable user-set webhookUrls) may
+  // omit it; production wiring in src/init/index.ts always passes it.
+  agentDir?: string
+  fetchImpl?: typeof fetch
+}
+
+export type EagerGithubWebhookInstallResult = WebhookRegistrationResult | { error: string; repos: [] }
+
+export async function installGithubWebhooksEagerly(
+  options: EagerGithubWebhookInstallOptions,
+): Promise<EagerGithubWebhookInstallResult> {
+  if (options.repos.length === 0) return { repos: [] }
+
+  let strategy: ReturnType<typeof buildAuthStrategy>
+  try {
+    strategy = buildAuthStrategy({
+      auth: authToSecretBlock(options.auth),
+      ...(options.fetchImpl !== undefined ? { fetchImpl: options.fetchImpl } : {}),
+    })
+  } catch (err) {
+    return { error: describe(err), repos: [] }
+  }
+
+  const managedPath =
+    options.agentDir !== undefined ? buildManagedPath(resolveAgentId({ agentDir: options.agentDir })) : undefined
+  const webhookUrl = managedPath !== undefined ? applyManagedPath(options.webhookUrl, managedPath) : options.webhookUrl
+
+  try {
+    const result = await registerGithubWebhooks({
+      token: () => strategy.token(),
+      webhookUrl,
+      webhookSecret: options.webhookSecret,
+      repos: options.repos,
+      events: options.events ?? DEFAULT_GITHUB_EVENT_ALLOWLIST,
+      ...(managedPath !== undefined ? { managedPath } : {}),
+      ...(options.fetchImpl !== undefined ? { fetchImpl: options.fetchImpl } : {}),
+    })
+    return result
+  } finally {
+    // PatAuthStrategy.dispose() is a no-op and AppAuthStrategy clears its
+    // cached installation token. Either way, releasing it here keeps the
+    // host CLI from holding onto credentials longer than needed.
+    await strategy.dispose().catch(() => {})
+  }
+}
+
+// Bridge the wizard/CLI's plaintext credentials union into the Secret-wrapped
+// shape buildAuthStrategy expects. Plain strings are wrapped as `{ value }`
+// so the underlying PatAuthStrategy resolver doesn't try (and fail) to read
+// from process.env.
+function authToSecretBlock(auth: GithubInitCredentials['auth']) {
+  if (auth.type === 'pat') {
+    return { type: 'pat' as const, token: { value: auth.pat } }
+  }
+  return {
+    type: 'app' as const,
+    appId: auth.appId,
+    privateKey: { value: auth.privateKey },
+    ...(auth.installationId !== undefined ? { installationId: auth.installationId } : {}),
+  }
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
+export function formatEagerGithubWebhookInstallResult(result: EagerGithubWebhookInstallResult): string {
+  if ('error' in result) return `GitHub webhook install failed: ${result.error}`
+  const created = result.repos.filter((r) => r.action === 'created').length
+  const updated = result.repos.filter((r) => r.action === 'updated').length
+  const failed = result.repos.filter((r) => r.action === 'failed')
+  const parts: string[] = []
+  if (created > 0) parts.push(`${created} created`)
+  if (updated > 0) parts.push(`${updated} updated`)
+  if (failed.length > 0) parts.push(`${failed.length} failed`)
+  const summary = parts.length > 0 ? parts.join(', ') : 'no repos'
+  const tail = failed.length > 0 ? ` (${failed.map((f) => `${f.repo}: ${f.error}`).join('; ')})` : ''
+  return `GitHub webhooks: ${summary}.${tail}`
+}