typeclaw 0.10.0 → 0.11.0

package/src/tui/index.ts

@@ -44,6 +44,14 @@ export type TuiOptions = {
   onVersionMismatch?: (info: VersionMismatch) => void
 }
 
+// Outcome of a single `run()` cycle. The CLI's reconnect loop reads this to
+// decide whether to spin again or exit. `lostConnection` is true when the
+// WS closed AFTER the connected handshake without a deliberate /quit or
+// Ctrl+C — exactly the case a self-restart produces, and the only one
+// where a fresh connect can recover the session. Quit / Ctrl+C / pre-
+// handshake errors all resolve with `lostConnection: false`.
+export type TuiRunOutcome = { lostConnection: boolean }
+
 export function createTui({
   url,
   initialPrompt,
@@ -54,7 +62,7 @@ export function createTui({
   expectedVersion,
   onVersionMismatch,
 }: TuiOptions) {
-  async function run(): Promise<void> {
+  async function run(): Promise<TuiRunOutcome> {
     const terminal = createTerminal()
     const tui = new TUI(terminal)
     const displayUrl = redactUrl(url)
@@ -80,6 +88,8 @@ export function createTui({
       exit(1)
       throw err
     })
+
+    let userInitiatedShutdown = false
     const { sessionId, serverVersion } = handshake
     status.setText(colors.dim(`session: ${sessionId}`))
     tui.requestRender()
@@ -196,11 +206,11 @@ export function createTui({
       }
     })
 
-    const closed = new Promise<void>((resolve) => {
+    const closed = new Promise<boolean>((resolve) => {
       client.onClose(() => {
         appendHistory(new Text(colors.dim('disconnected'), 0, 0))
         tui.requestRender()
-        resolve()
+        resolve(!userInitiatedShutdown)
       })
     })
 
@@ -223,6 +233,7 @@ export function createTui({
     })
 
     const shutdown = (code: number) => {
+      userInitiatedShutdown = true
       tui.stop()
       client.close()
       exit(code)
@@ -268,13 +279,14 @@ export function createTui({
       // instead of leaking the command into the agent's chat context.
       if (isQuitCommand(initialPrompt)) {
         shutdown(0)
-        return
+        return { lostConnection: false }
       }
       await send(initialPrompt)
     }
 
-    await closed
+    const lostConnection = await closed
     tui.stop()
+    return { lostConnection }
   }
 
   return { run }

package/src/tunnels/index.ts

@@ -1,4 +1,5 @@
 export { createTunnelManager, type TunnelManager, type TunnelManagerOptions, type TunnelManagerLogger } from './manager'
+export { createCloudflareNamedProvider, type CloudflareNamedProviderOptions } from './providers/cloudflare-named'
 export { createCloudflareQuickProvider, type CloudflareQuickProviderOptions } from './providers/cloudflare-quick'
 export {
   type TunnelConfig,

package/src/tunnels/manager.ts

@@ -1,5 +1,6 @@
 import type { Stream } from '@/stream'
 
+import { createCloudflareNamedProvider } from './providers/cloudflare-named'
 import { createCloudflareQuickProvider } from './providers/cloudflare-quick'
 import { createExternalProvider } from './providers/external'
 import type { TunnelConfig, TunnelProviderHandle, TunnelState, TunnelUrlChangedPayload } from './types'
@@ -15,6 +16,11 @@ export type TunnelManagerOptions = {
   stream: Stream
   resolveChannelUpstreamPort?: (channelName: string) => number | null
   cloudflareQuickBinary?: string
+  cloudflareNamedBinary?: string
+  // Reads an env var by name. Defaults to `process.env[name]` in production.
+  // Parameterized so tests can drive the named-provider token path without
+  // poking global env and so the manager stays a pure function of its inputs.
+  resolveEnv?: (name: string) => string | undefined
   logger?: TunnelManagerLogger
 }
 
@@ -36,6 +42,7 @@ const consoleLogger: TunnelManagerLogger = {
 export function createTunnelManager(options: TunnelManagerOptions): TunnelManager {
   const logger = options.logger ?? consoleLogger
   const handles = new Map<string, TunnelProviderHandle>()
+  const resolveEnv = options.resolveEnv ?? ((name: string) => process.env[name])
 
   for (const config of options.tunnels) {
     const handle = buildProvider(
@@ -43,6 +50,8 @@ export function createTunnelManager(options: TunnelManagerOptions): TunnelManage
       options.resolveChannelUpstreamPort,
       (url) => publishUrlChange(options.stream, config, url, logger),
       options.cloudflareQuickBinary,
+      options.cloudflareNamedBinary,
+      resolveEnv,
     )
     handles.set(config.name, handle)
   }
@@ -92,6 +101,8 @@ function buildProvider(
   resolveChannelUpstreamPort: TunnelManagerOptions['resolveChannelUpstreamPort'],
   onUrlChange: (url: string) => void,
   cloudflareQuickBinary: string | undefined,
+  cloudflareNamedBinary: string | undefined,
+  resolveEnv: (name: string) => string | undefined,
 ): TunnelProviderHandle {
   switch (config.provider) {
     case 'external':
@@ -103,6 +114,13 @@ function buildProvider(
         onUrlChange,
         binary: cloudflareQuickBinary,
       })
+    case 'cloudflare-named':
+      return createCloudflareNamedProvider({
+        config,
+        onUrlChange,
+        resolveToken: () => (config.tokenEnv !== undefined ? resolveEnv(config.tokenEnv) : undefined),
+        binary: cloudflareNamedBinary,
+      })
   }
 }
 

package/src/tunnels/providers/cloudflare-named.ts

@@ -0,0 +1,224 @@
+import type { Unsubscribe } from '@/stream'
+
+import { createLogRing, type LogLineSubscriber, type LogRing } from '../log-ring'
+import type { TunnelConfig, TunnelProviderHandle, TunnelState } from '../types'
+
+const DEFAULT_BINARY = 'cloudflared'
+const DEFAULT_RESTART_BACKOFF_MS = [1_000, 2_000, 4_000, 10_000, 30_000]
+const DEFAULT_MAX_CONSECUTIVE_CRASHES = 10
+const DEFAULT_STOP_GRACE_MS = 5_000
+
+export type CloudflareNamedProviderOptions = {
+  config: TunnelConfig
+  onUrlChange: (url: string) => void
+  // Token resolver. Production wiring reads `process.env[config.tokenEnv]`;
+  // the resolver is parameterized so tests can inject a value without poking
+  // global env. Returning `undefined` (or empty string) at any call fails the
+  // start with a clear error pointing at the env-var name.
+  resolveToken: () => string | undefined
+  binary?: string
+  restartBackoffMs?: number[]
+  maxConsecutiveCrashes?: number
+  stopGraceMs?: number
+}
+
+export type CloudflareNamedProviderHandle = TunnelProviderHandle & {
+  tail: () => string[]
+  subscribeToLogs: (cb: LogLineSubscriber) => Unsubscribe
+}
+
+export function createCloudflareNamedProvider(options: CloudflareNamedProviderOptions): CloudflareNamedProviderHandle {
+  const { config, onUrlChange, resolveToken } = options
+  if (config.provider !== 'cloudflare-named') {
+    throw new Error(`createCloudflareNamedProvider: provider must be 'cloudflare-named', got '${config.provider}'`)
+  }
+  const hostname = config.hostname
+  if (hostname === undefined || hostname.trim() === '') {
+    throw new Error(`tunnel '${config.name}' (cloudflare-named): hostname is required`)
+  }
+  const tokenEnv = config.tokenEnv
+  if (tokenEnv === undefined || tokenEnv.trim() === '') {
+    throw new Error(`tunnel '${config.name}' (cloudflare-named): tokenEnv is required`)
+  }
+
+  const binary = options.binary ?? DEFAULT_BINARY
+  const restartBackoffMs = options.restartBackoffMs ?? DEFAULT_RESTART_BACKOFF_MS
+  const maxConsecutiveCrashes = options.maxConsecutiveCrashes ?? DEFAULT_MAX_CONSECUTIVE_CRASHES
+  const stopGraceMs = options.stopGraceMs ?? DEFAULT_STOP_GRACE_MS
+  const logs = createLogRing()
+  const state: TunnelState = {
+    name: config.name,
+    provider: 'cloudflare-named',
+    for: config.for,
+    url: null,
+    status: 'stopped',
+    lastUrlAt: null,
+    detail: '',
+  }
+
+  let started = false
+  let stopping = false
+  let proc: ReturnType<typeof Bun.spawn> | null = null
+  let retryTimer: ReturnType<typeof setTimeout> | null = null
+  let consecutiveCrashes = 0
+
+  async function launch(): Promise<void> {
+    if (!started || stopping) return
+
+    const token = resolveToken()
+    if (token === undefined || token.trim() === '') {
+      // Bad config rather than a transient process crash: the user-facing fix
+      // is editing `.env`, not waiting for backoff. Flip straight to
+      // permanently-failed so `tunnel status` makes the cause obvious and we
+      // don't waste retries spawning a cloudflared we know will reject the
+      // missing token.
+      state.status = 'permanently-failed'
+      state.detail = `env var ${tokenEnv} is unset or empty; set it in .env and restart`
+      return
+    }
+
+    state.status = 'starting'
+    state.detail = 'starting cloudflared'
+    const spawned = Bun.spawn([binary, 'tunnel', '--no-autoupdate', 'run', '--token', token], {
+      stdout: 'ignore',
+      stderr: 'pipe',
+    })
+    proc = spawned
+
+    // Mark healthy on the FIRST stderr line. cloudflared with a valid token
+    // prints registration progress to stderr within ~1s of start; a process
+    // that exits before printing anything is almost certainly a token/network
+    // failure. Healthy != "traffic flowing" — only Cloudflare's edge knows
+    // that — but it's the strongest signal available locally and matches the
+    // quick provider's "saw something on stderr" health model.
+    //
+    // Deliberately does NOT reset `consecutiveCrashes`. A process that prints
+    // one line of stderr then crashes is a tight crash loop (bad token,
+    // network down, cloudflared bug); the counter must trip the cap. The
+    // counter resets on operator action (`stop()` then `start()` again) or
+    // on `typeclaw restart`, not on stderr noise.
+    let sawFirstLine = false
+    void pumpStderr(spawned.stderr, logs, () => {
+      if (sawFirstLine) return
+      sawFirstLine = true
+      state.status = 'healthy'
+      state.detail = 'cloudflared started'
+    })
+
+    void spawned.exited.then((code) => {
+      if (proc !== spawned) return
+      proc = null
+      if (!started || stopping) return
+      handleExit(code)
+    })
+  }
+
+  function handleExit(code: number): void {
+    consecutiveCrashes += 1
+    if (consecutiveCrashes >= maxConsecutiveCrashes) {
+      state.status = 'permanently-failed'
+      state.detail = `cloudflared exited ${code}; retry cap reached after ${consecutiveCrashes} consecutive crashes`
+      return
+    }
+
+    state.status = 'unhealthy'
+    state.detail = `cloudflared exited ${code}; restarting`
+    const delay = restartBackoffMs[Math.min(consecutiveCrashes - 1, restartBackoffMs.length - 1)] ?? 30_000
+    retryTimer = setTimeout(() => {
+      retryTimer = null
+      void launch()
+    }, delay)
+  }
+
+  return {
+    async start(): Promise<void> {
+      if (started) return
+      started = true
+      stopping = false
+      consecutiveCrashes = 0
+      // The URL is known from config, not from cloudflared. Emit it
+      // synchronously so subscribers (channel adapters, tunnel-bridge) wire
+      // up immediately, regardless of whether cloudflared comes up healthy.
+      // For named tunnels, the URL is bound to the dashboard config — even
+      // if the local process is unhealthy, the hostname is the right value
+      // to surface in `tunnel-url-changed` events.
+      state.url = hostname
+      state.lastUrlAt = Date.now()
+      onUrlChange(hostname)
+      await launch()
+    },
+    async stop(): Promise<void> {
+      if (!started && proc === null) return
+      started = false
+      stopping = true
+      if (retryTimer !== null) {
+        clearTimeout(retryTimer)
+        retryTimer = null
+      }
+
+      const running = proc
+      proc = null
+      if (running !== null) {
+        running.kill('SIGTERM')
+        await Promise.race([
+          running.exited,
+          sleep(stopGraceMs).then(() => {
+            running.kill('SIGKILL')
+            return running.exited
+          }),
+        ])
+      }
+
+      stopping = false
+      state.status = 'stopped'
+      state.detail = ''
+    },
+    snapshot(): TunnelState {
+      return { ...state }
+    },
+    tail(): string[] {
+      return logs.snapshot()
+    },
+    subscribeToLogs(cb: LogLineSubscriber): Unsubscribe {
+      return logs.subscribe(cb)
+    },
+  }
+}
+
+async function pumpStderr(
+  stream: ReadableStream<Uint8Array> | null,
+  logs: LogRing,
+  onLine: (line: string) => void,
+): Promise<void> {
+  if (stream === null) return
+  const reader = stream.getReader()
+  const decoder = new TextDecoder()
+  let buffered = ''
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      buffered += decoder.decode(value, { stream: true })
+      let newlineIndex = buffered.indexOf('\n')
+      while (newlineIndex !== -1) {
+        const line = buffered.slice(0, newlineIndex).replace(/\r$/, '')
+        logs.append(line)
+        onLine(line)
+        buffered = buffered.slice(newlineIndex + 1)
+        newlineIndex = buffered.indexOf('\n')
+      }
+    }
+    buffered += decoder.decode()
+    if (buffered !== '') {
+      const line = buffered.replace(/\r$/, '')
+      logs.append(line)
+      onLine(line)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}

package/src/tunnels/types.ts

@@ -1,6 +1,6 @@
 import type { Unsubscribe } from '@/stream'
 
-export type TunnelProvider = 'external' | 'cloudflare-quick'
+export type TunnelProvider = 'external' | 'cloudflare-quick' | 'cloudflare-named'
 
 export type TunnelFor = { kind: 'channel'; name: string } | { kind: 'manual' }
 
@@ -10,6 +10,22 @@ export type TunnelConfig = {
   for: TunnelFor
   externalUrl?: string
   upstreamPort?: number
+  // cloudflare-named only: the public hostname configured in the Cloudflare
+  // dashboard (e.g. `https://agent.example.com`). typeclaw uses it verbatim
+  // for `tunnel-url-changed` events and CLI display; cloudflared itself
+  // learns the hostname → upstream mapping from the dashboard at runtime, so
+  // the value here must mirror what the user typed in `Public Hostname`. If
+  // the two drift, traffic stops flowing but typeclaw still reports the
+  // stale URL — there is no programmatic way to detect this without hitting
+  // Cloudflare's API, which we deliberately don't do.
+  hostname?: string
+  // cloudflare-named only: name of an env var (set in the agent's `.env`)
+  // that holds the tunnel token printed by the Cloudflare dashboard when the
+  // tunnel was created. The token itself never lives in typeclaw.json — only
+  // the env-var name does. The container reads `process.env[tokenEnv]` at
+  // tunnel start. Missing/empty values fail the start with a clear message
+  // pointing at the env var name.
+  tokenEnv?: string
 }
 
 export type TunnelStatus = 'stopped' | 'starting' | 'healthy' | 'unhealthy' | 'permanently-failed'

package/typeclaw.schema.json

@@ -26,12 +26,12 @@
               "openai/gpt-5.4-mini",
               "openai/gpt-5.4",
               "openai/gpt-5.5",
-              "anthropic/claude-haiku-4-5",
-              "anthropic/claude-sonnet-4-6",
-              "anthropic/claude-opus-4-7",
               "openai-codex/gpt-5.4-mini",
               "openai-codex/gpt-5.4",
               "openai-codex/gpt-5.5",
+              "anthropic/claude-haiku-4-5",
+              "anthropic/claude-sonnet-4-6",
+              "anthropic/claude-opus-4-7",
               "fireworks/accounts/fireworks/routers/kimi-k2p6-turbo",
               "zai/glm-4.5-air",
               "zai/glm-4.6",
@@ -53,12 +53,12 @@
                 "openai/gpt-5.4-mini",
                 "openai/gpt-5.4",
                 "openai/gpt-5.5",
-                "anthropic/claude-haiku-4-5",
-                "anthropic/claude-sonnet-4-6",
-                "anthropic/claude-opus-4-7",
                 "openai-codex/gpt-5.4-mini",
                 "openai-codex/gpt-5.4",
                 "openai-codex/gpt-5.5",
+                "anthropic/claude-haiku-4-5",
+                "anthropic/claude-sonnet-4-6",
+                "anthropic/claude-opus-4-7",
                 "fireworks/accounts/fireworks/routers/kimi-k2p6-turbo",
                 "zai/glm-4.5-air",
                 "zai/glm-4.6",
@@ -457,6 +457,8 @@
                 "discussion_comment.created",
                 "issues.opened",
                 "pull_request.opened",
+                "pull_request.review_requested",
+                "pull_request.review_request_removed",
                 "discussion.created",
                 "pull_request_review.submitted"
               ],
@@ -1186,7 +1188,8 @@
             "type": "string",
             "enum": [
               "external",
-              "cloudflare-quick"
+              "cloudflare-quick",
+              "cloudflare-named"
             ]
           },
           "for": {
@@ -1230,6 +1233,14 @@
             "type": "integer",
             "minimum": 1,
             "maximum": 65535
+          },
+          "hostname": {
+            "type": "string",
+            "format": "uri"
+          },
+          "tokenEnv": {
+            "type": "string",
+            "pattern": "^[A-Z_][A-Z0-9_]*$"
           }
         },
         "required": [
@@ -1278,6 +1289,7 @@
         "idleMs": 60000,
         "bufferBytes": 500000,
         "injectionBudgetBytes": 16384,
+        "minIdleDeltaLines": 3,
         "spawnTimeoutMs": 50000,
         "retrievalSpawnTimeoutMs": 30000
       },
@@ -1301,6 +1313,12 @@
           "minimum": 4096,
           "maximum": 9007199254740991
         },
+        "minIdleDeltaLines": {
+          "default": 3,
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
         "spawnTimeoutMs": {
           "default": 50000,
           "type": "integer",