typeclaw 0.3.1 → 0.5.0

package/src/tui/index.ts

@@ -1,5 +1,7 @@
 import { Editor, Key, Markdown, matchesKey, ProcessTerminal, type Terminal, Text, TUI } from '@mariozechner/pi-tui'
 
+import { parseCommand } from '@/commands'
+
 import { createClient as createClientDefault, type Client } from './client'
 import { formatQueuePanel, formatToolEnd, formatToolStart, formatUserPromptHistory } from './format'
 import { colors, editorTheme, markdownTheme } from './theme'
@@ -9,6 +11,23 @@ export type TerminalFactory = () => Terminal
 
 const DEFAULT_HANDSHAKE_TIMEOUT_MS = 30_000
 
+// Bare slash-command names (no leading `/`) the TUI intercepts client-side and
+// turns into a clean process exit. The hatching ritual tells the agent to point
+// users at `/quit` (see src/init/hatching.ts); without an intercept the literal
+// text would be shipped to the LLM as a chat message. Grammar (case-insensitive,
+// whitespace-tolerant, `//foo` escapes to a literal prompt) comes from
+// `parseCommand` in src/commands so channel and TUI slash commands stay
+// consistent. Arguments after the name disqualify the match: `/quit me a story`
+// is a real prompt, not a command.
+const QUIT_COMMAND_NAMES: ReadonlySet<string> = new Set(['quit', 'exit'])
+
+function isQuitCommand(text: string): boolean {
+  const parsed = parseCommand(text)
+  return parsed !== null && parsed.args.length === 0 && QUIT_COMMAND_NAMES.has(parsed.name)
+}
+
+export type VersionMismatch = { expected: string; actual: string }
+
 export type TuiOptions = {
   url: string
   initialPrompt?: string
@@ -16,6 +35,13 @@ export type TuiOptions = {
   createTerminal?: TerminalFactory
   handshakeTimeoutMs?: number
   exit?: (code: number) => void
+  // Locally-known typeclaw version the host CLI is running. When provided
+  // and the connected frame's serverVersion is defined and differs,
+  // onVersionMismatch is invoked AND a yellow warning line is rendered
+  // into the TUI history. The container-side local TUI omits this so no
+  // mismatch check fires when client and server are guaranteed in lockstep.
+  expectedVersion?: string
+  onVersionMismatch?: (info: VersionMismatch) => void
 }
 
 export function createTui({
@@ -25,6 +51,8 @@ export function createTui({
   createTerminal = () => new ProcessTerminal(),
   handshakeTimeoutMs = DEFAULT_HANDSHAKE_TIMEOUT_MS,
   exit = process.exit.bind(process),
+  expectedVersion,
+  onVersionMismatch,
 }: TuiOptions) {
   async function run(): Promise<void> {
     const terminal = createTerminal()
@@ -44,7 +72,7 @@ export function createTui({
       throw err
     })
 
-    const sessionId = await waitForConnected(client, displayUrl, handshakeTimeoutMs).catch((err) => {
+    const handshake = await waitForConnected(client, displayUrl, handshakeTimeoutMs).catch((err) => {
       status.setText(colors.red(`connection error: ${err instanceof Error ? err.message : String(err)}`))
       tui.requestRender()
       client.close()
@@ -52,6 +80,7 @@ export function createTui({
       exit(1)
       throw err
     })
+    const { sessionId, serverVersion } = handshake
     status.setText(colors.dim(`session: ${sessionId}`))
     tui.requestRender()
 
@@ -193,14 +222,18 @@ export function createTui({
       return undefined
     })
 
+    const shutdown = (code: number) => {
+      tui.stop()
+      client.close()
+      exit(code)
+    }
+
     // Ctrl+C exits cleanly. In raw mode the kernel does NOT generate SIGINT,
     // so we must intercept the \x03 byte ourselves. The Editor would otherwise
     // swallow it. tui.stop() restores raw-mode/cursor/echo before we exit.
     tui.addInputListener((data) => {
       if (matchesKey(data, Key.ctrl('c'))) {
-        tui.stop()
-        client.close()
-        exit(0)
+        shutdown(0)
         return { consume: true }
       }
       return undefined
@@ -208,6 +241,10 @@ export function createTui({
 
     editor.onSubmit = (text) => {
       if (text.trim().length === 0) return
+      if (isQuitCommand(text)) {
+        shutdown(0)
+        return
+      }
       editor.setText('')
       editor.addToHistory(text)
       tui.requestRender()
@@ -217,7 +254,22 @@ export function createTui({
     tui.setFocus(editor)
     tui.requestRender()
 
+    if (expectedVersion !== undefined && serverVersion !== undefined && serverVersion !== expectedVersion) {
+      const mismatch: VersionMismatch = { expected: expectedVersion, actual: serverVersion }
+      const warning = formatVersionMismatchWarning(mismatch)
+      appendHistory(new Text(colors.yellow(warning), 0, 0))
+      tui.requestRender()
+      onVersionMismatch?.(mismatch)
+    }
+
     if (initialPrompt) {
+      // initialPrompt bypasses editor.onSubmit, so the quit intercept above
+      // would never run. Guard the same way so `typeclaw tui /quit` exits
+      // instead of leaking the command into the agent's chat context.
+      if (isQuitCommand(initialPrompt)) {
+        shutdown(0)
+        return
+      }
       await send(initialPrompt)
     }
 
@@ -238,8 +290,12 @@ function redactUrl(url: string): string {
   }
 }
 
-async function waitForConnected(client: Client, url: string, timeoutMs: number): Promise<string> {
-  return await new Promise<string>((resolve, reject) => {
+async function waitForConnected(
+  client: Client,
+  url: string,
+  timeoutMs: number,
+): Promise<{ sessionId: string; serverVersion?: string }> {
+  return await new Promise<{ sessionId: string; serverVersion?: string }>((resolve, reject) => {
     const timer = setTimeout(() => {
       cleanup()
       reject(new Error(`timed out waiting for connected message from ${url} after ${timeoutMs}ms`))
@@ -253,7 +309,10 @@ async function waitForConnected(client: Client, url: string, timeoutMs: number):
       client.onMessage((msg) => {
         if (msg.type === 'connected') {
           cleanup()
-          resolve(msg.sessionId)
+          resolve({
+            sessionId: msg.sessionId,
+            ...(msg.serverVersion !== undefined ? { serverVersion: msg.serverVersion } : {}),
+          })
         }
         if (msg.type === 'error') {
           cleanup()
@@ -275,3 +334,7 @@ async function waitForConnected(client: Client, url: string, timeoutMs: number):
     )
   })
 }
+
+export function formatVersionMismatchWarning({ expected, actual }: VersionMismatch): string {
+  return `WARN: host CLI is v${expected}, agent container is v${actual}. Some commands may hang or fail. Try \`typeclaw restart --build\`.`
+}

package/src/tunnels/__fixtures__/cloudflared-quick-stderr.txt

@@ -0,0 +1,11 @@
+# Fixture source: cloudflare/cloudflared cmd/cloudflared/tunnel/quick_tunnel.go
+# RunQuickTunnel logs the disclaimer, "Requesting new quick Tunnel on trycloudflare.com...",
+# then AsciiBox(...) lines containing the resolved https://<subdomain>.trycloudflare.com URL.
+# Reference fetched from:
+# https://raw.githubusercontent.com/cloudflare/cloudflared/master/cmd/cloudflared/tunnel/quick_tunnel.go
+2026-01-01T00:00:00Z INF Thank you for trying Cloudflare Tunnel. Doing so, without a Cloudflare account, is a quick way to experiment and try it out. However, be aware that these account-less Tunnels have no uptime guarantee, are subject to the Cloudflare Online Services Terms of Use (https://www.cloudflare.com/website-terms/), and Cloudflare reserves the right to investigate your use of Tunnels for violations of such terms. If you intend to use Tunnels in production you should use a pre-created named tunnel by following: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps
+2026-01-01T00:00:00Z INF Requesting new quick Tunnel on trycloudflare.com...
+2026-01-01T00:00:00Z INF +--------------------------------------------------------------------------------------------------+
+2026-01-01T00:00:00Z INF |  Your quick Tunnel has been created! Visit it at (it may take some time to be reachable):  |
+2026-01-01T00:00:00Z INF |  https://wave-one-fixture.trycloudflare.com                                                   |
+2026-01-01T00:00:00Z INF +--------------------------------------------------------------------------------------------------+

package/src/tunnels/events.ts

@@ -0,0 +1,14 @@
+import type { TunnelUrlChangedPayload } from './types'
+
+export function isTunnelUrlChangedPayload(value: unknown): value is TunnelUrlChangedPayload {
+  if (value === null || typeof value !== 'object') return false
+  const v = value as Record<string, unknown>
+  if (v.kind !== 'tunnel-url-changed') return false
+  if (typeof v.tunnelName !== 'string') return false
+  if (typeof v.url !== 'string') return false
+  if (typeof v.rotatedAt !== 'string') return false
+  if (v.for === null || typeof v.for !== 'object') return false
+  const forKind = (v.for as Record<string, unknown>).kind
+  if (forKind !== 'channel' && forKind !== 'manual') return false
+  return true
+}

package/src/tunnels/index.ts

@@ -0,0 +1,12 @@
+export { createTunnelManager, type TunnelManager, type TunnelManagerOptions, type TunnelManagerLogger } from './manager'
+export { createCloudflareQuickProvider, type CloudflareQuickProviderOptions } from './providers/cloudflare-quick'
+export {
+  type TunnelConfig,
+  type TunnelFor,
+  type TunnelProvider,
+  type TunnelProviderHandle,
+  type TunnelState,
+  type TunnelStatus,
+  type TunnelUrlChangedPayload,
+} from './types'
+export { isTunnelUrlChangedPayload } from './events'

package/src/tunnels/log-ring.ts

@@ -0,0 +1,54 @@
+import type { Unsubscribe } from '@/stream'
+
+export const DEFAULT_LOG_RING_MAX_BYTES = 1024 * 1024
+
+export type LogLineSubscriber = (line: string) => void
+
+export type LogRingOptions = {
+  maxBytes?: number
+}
+
+export type LogRing = {
+  append: (line: string) => void
+  snapshot: () => string[]
+  subscribe: (cb: LogLineSubscriber) => Unsubscribe
+}
+
+const encoder = new TextEncoder()
+
+export function createLogRing(options: LogRingOptions = {}): LogRing {
+  const maxBytes = options.maxBytes ?? DEFAULT_LOG_RING_MAX_BYTES
+  if (!Number.isInteger(maxBytes) || maxBytes < 1) {
+    throw new Error('LogRing maxBytes must be a positive integer')
+  }
+
+  const lines: string[] = []
+  const sizes: number[] = []
+  const subscribers = new Set<LogLineSubscriber>()
+  let bytes = 0
+
+  return {
+    append(line: string): void {
+      const size = encoder.encode(line).byteLength
+      lines.push(line)
+      sizes.push(size)
+      bytes += size
+
+      while (bytes > maxBytes && lines.length > 1) {
+        lines.shift()
+        bytes -= sizes.shift() ?? 0
+      }
+
+      for (const subscriber of subscribers) subscriber(line)
+    },
+    snapshot(): string[] {
+      return [...lines]
+    },
+    subscribe(cb: LogLineSubscriber): Unsubscribe {
+      subscribers.add(cb)
+      return () => {
+        subscribers.delete(cb)
+      }
+    },
+  }
+}

package/src/tunnels/manager.ts

@@ -0,0 +1,139 @@
+import type { Stream } from '@/stream'
+
+import { createCloudflareQuickProvider } from './providers/cloudflare-quick'
+import { createExternalProvider } from './providers/external'
+import type { TunnelConfig, TunnelProviderHandle, TunnelState, TunnelUrlChangedPayload } from './types'
+
+export type TunnelManagerLogger = {
+  info: (m: string) => void
+  warn: (m: string) => void
+  error: (m: string) => void
+}
+
+export type TunnelManagerOptions = {
+  tunnels: TunnelConfig[]
+  stream: Stream
+  resolveChannelUpstreamPort?: (channelName: string) => number | null
+  cloudflareQuickBinary?: string
+  logger?: TunnelManagerLogger
+}
+
+export type TunnelManager = {
+  start: () => Promise<void>
+  stop: () => Promise<void>
+  snapshot: () => TunnelState[]
+  urlFor: (tunnelName: string) => string | null
+  tail: (tunnelName: string) => string[]
+  subscribeToLogs: (tunnelName: string, cb: (line: string) => void) => () => void
+}
+
+const consoleLogger: TunnelManagerLogger = {
+  info: (m) => console.log(m),
+  warn: (m) => console.warn(m),
+  error: (m) => console.error(m),
+}
+
+export function createTunnelManager(options: TunnelManagerOptions): TunnelManager {
+  const logger = options.logger ?? consoleLogger
+  const handles = new Map<string, TunnelProviderHandle>()
+
+  for (const config of options.tunnels) {
+    const handle = buildProvider(
+      config,
+      options.resolveChannelUpstreamPort,
+      (url) => publishUrlChange(options.stream, config, url, logger),
+      options.cloudflareQuickBinary,
+    )
+    handles.set(config.name, handle)
+  }
+
+  return {
+    async start(): Promise<void> {
+      await Promise.all(
+        Array.from(handles.values()).map(async (h) => {
+          try {
+            await h.start()
+          } catch (err) {
+            logger.error(
+              `[tunnels] ${h.snapshot().name}: start failed: ${err instanceof Error ? err.message : String(err)}`,
+            )
+          }
+        }),
+      )
+    },
+    async stop(): Promise<void> {
+      await Promise.all(
+        Array.from(handles.values()).map((h) =>
+          h.stop().catch((err: unknown) => {
+            logger.warn(
+              `[tunnels] ${h.snapshot().name}: stop failed: ${err instanceof Error ? err.message : String(err)}`,
+            )
+          }),
+        ),
+      )
+    },
+    snapshot(): TunnelState[] {
+      return Array.from(handles.values()).map((h) => h.snapshot())
+    },
+    urlFor(tunnelName: string): string | null {
+      return handles.get(tunnelName)?.snapshot().url ?? null
+    },
+    tail(tunnelName: string): string[] {
+      return handles.get(tunnelName)?.tail() ?? []
+    },
+    subscribeToLogs(tunnelName: string, cb: (line: string) => void): () => void {
+      return handles.get(tunnelName)?.subscribeToLogs(cb) ?? (() => {})
+    },
+  }
+}
+
+function buildProvider(
+  config: TunnelConfig,
+  resolveChannelUpstreamPort: TunnelManagerOptions['resolveChannelUpstreamPort'],
+  onUrlChange: (url: string) => void,
+  cloudflareQuickBinary: string | undefined,
+): TunnelProviderHandle {
+  switch (config.provider) {
+    case 'external':
+      return createExternalProvider({ config, onUrlChange })
+    case 'cloudflare-quick':
+      return createCloudflareQuickProvider({
+        config,
+        upstreamPort: resolveUpstreamPort(config, resolveChannelUpstreamPort),
+        onUrlChange,
+        binary: cloudflareQuickBinary,
+      })
+  }
+}
+
+function resolveUpstreamPort(
+  config: TunnelConfig,
+  resolveChannelUpstreamPort: TunnelManagerOptions['resolveChannelUpstreamPort'],
+): number {
+  if (config.for.kind === 'manual') {
+    if (config.upstreamPort === undefined) {
+      throw new Error(`tunnel '${config.name}' (cloudflare-quick): upstreamPort is required for manual tunnels`)
+    }
+    return config.upstreamPort
+  }
+
+  const upstreamPort = resolveChannelUpstreamPort?.(config.for.name) ?? null
+  if (upstreamPort === null) {
+    throw new Error(
+      `tunnel '${config.name}' (cloudflare-quick): no upstream port resolved for channel '${config.for.name}'`,
+    )
+  }
+  return upstreamPort
+}
+
+function publishUrlChange(stream: Stream, config: TunnelConfig, url: string, logger: TunnelManagerLogger): void {
+  const payload: TunnelUrlChangedPayload = {
+    kind: 'tunnel-url-changed',
+    tunnelName: config.name,
+    url,
+    for: config.for,
+    rotatedAt: new Date().toISOString(),
+  }
+  stream.publish({ target: { kind: 'broadcast' }, payload })
+  logger.info(`[tunnels] ${config.name}: URL set to ${url}`)
+}

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

@@ -0,0 +1,189 @@
+import type { Unsubscribe } from '@/stream'
+
+import { createLogRing, type LogLineSubscriber, type LogRing } from '../log-ring'
+import { extractQuickTunnelUrl } from '../quick-url-parser'
+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_FAILURES_WITHOUT_URL = 10
+const DEFAULT_STOP_GRACE_MS = 5_000
+
+export type CloudflareQuickProviderOptions = {
+  config: TunnelConfig
+  upstreamPort: number
+  onUrlChange: (url: string) => void
+  binary?: string
+  restartBackoffMs?: number[]
+  maxConsecutiveFailuresWithoutUrl?: number
+  stopGraceMs?: number
+}
+
+export type CloudflareQuickProviderHandle = TunnelProviderHandle & {
+  tail: () => string[]
+  subscribeToLogs: (cb: LogLineSubscriber) => Unsubscribe
+}
+
+export function createCloudflareQuickProvider(options: CloudflareQuickProviderOptions): CloudflareQuickProviderHandle {
+  const { config, upstreamPort, onUrlChange } = options
+  if (config.provider !== 'cloudflare-quick') {
+    throw new Error(`createCloudflareQuickProvider: provider must be 'cloudflare-quick', got '${config.provider}'`)
+  }
+  if (!Number.isInteger(upstreamPort) || upstreamPort < 1 || upstreamPort > 65535) {
+    throw new Error(`tunnel '${config.name}' (cloudflare-quick): upstreamPort must be a valid TCP port`)
+  }
+
+  const binary = options.binary ?? DEFAULT_BINARY
+  const restartBackoffMs = options.restartBackoffMs ?? DEFAULT_RESTART_BACKOFF_MS
+  const maxConsecutiveFailuresWithoutUrl = options.maxConsecutiveFailuresWithoutUrl ?? DEFAULT_MAX_FAILURES_WITHOUT_URL
+  const stopGraceMs = options.stopGraceMs ?? DEFAULT_STOP_GRACE_MS
+  const logs = createLogRing()
+  const state: TunnelState = {
+    name: config.name,
+    provider: 'cloudflare-quick',
+    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 restartFailuresWithoutUrl = 0
+  let attemptEmittedUrl = false
+
+  async function launch(): Promise<void> {
+    if (!started || stopping) return
+
+    attemptEmittedUrl = false
+    state.status = 'starting'
+    state.detail = 'starting cloudflared'
+    const spawned = Bun.spawn(
+      [binary, 'tunnel', '--url', `http://127.0.0.1:${upstreamPort}`, '--no-autoupdate', '--metrics', '127.0.0.1:0'],
+      { stdout: 'ignore', stderr: 'pipe' },
+    )
+    proc = spawned
+
+    void pumpStderr(spawned.stderr, logs, (line) => {
+      const url = extractQuickTunnelUrl(line)
+      if (url === null) return
+      attemptEmittedUrl = true
+      restartFailuresWithoutUrl = 0
+      state.url = url
+      state.status = 'healthy'
+      state.lastUrlAt = Date.now()
+      state.detail = 'quick tunnel URL emitted'
+      onUrlChange(url)
+    })
+
+    void spawned.exited.then((code) => {
+      if (proc !== spawned) return
+      proc = null
+      if (!started || stopping) return
+      handleExit(code)
+    })
+  }
+
+  function handleExit(code: number): void {
+    if (!attemptEmittedUrl) restartFailuresWithoutUrl += 1
+    if (restartFailuresWithoutUrl >= maxConsecutiveFailuresWithoutUrl) {
+      state.status = 'permanently-failed'
+      state.detail = `cloudflared exited ${code}; retry cap reached before URL emission`
+      return
+    }
+
+    state.status = 'unhealthy'
+    state.detail = `cloudflared exited ${code}; restarting`
+    const delay = restartBackoffMs[Math.min(restartFailuresWithoutUrl - 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
+      restartFailuresWithoutUrl = 0
+      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/providers/external.ts

@@ -0,0 +1,53 @@
+import type { TunnelConfig, TunnelProviderHandle, TunnelState } from '../types'
+
+export type ExternalProviderOptions = {
+  config: TunnelConfig
+  onUrlChange: (url: string) => void
+}
+
+export function createExternalProvider(options: ExternalProviderOptions): TunnelProviderHandle {
+  const { config, onUrlChange } = options
+  if (config.provider !== 'external') {
+    throw new Error(`createExternalProvider: provider must be 'external', got '${config.provider}'`)
+  }
+  const url = config.externalUrl
+  if (url === undefined || url.trim() === '') {
+    throw new Error(`tunnel '${config.name}' (external): externalUrl is required`)
+  }
+
+  let started = false
+  const state: TunnelState = {
+    name: config.name,
+    provider: 'external',
+    for: config.for,
+    url: null,
+    status: 'stopped',
+    lastUrlAt: null,
+    detail: '',
+  }
+
+  return {
+    async start(): Promise<void> {
+      if (started) return
+      started = true
+      state.url = url
+      state.status = 'healthy'
+      state.lastUrlAt = Date.now()
+      onUrlChange(url)
+    },
+    async stop(): Promise<void> {
+      if (!started) return
+      started = false
+      state.status = 'stopped'
+    },
+    snapshot(): TunnelState {
+      return { ...state }
+    },
+    tail(): string[] {
+      return []
+    },
+    subscribeToLogs(): () => void {
+      return () => {}
+    },
+  }
+}

package/src/tunnels/quick-url-parser.ts

@@ -0,0 +1,5 @@
+const QUICK_TUNNEL_URL_PATTERN = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/
+
+export function extractQuickTunnelUrl(line: string): string | null {
+  return QUICK_TUNNEL_URL_PATTERN.exec(line)?.[0] ?? null
+}

package/src/tunnels/types.ts

@@ -0,0 +1,43 @@
+import type { Unsubscribe } from '@/stream'
+
+export type TunnelProvider = 'external' | 'cloudflare-quick'
+
+export type TunnelFor = { kind: 'channel'; name: string } | { kind: 'manual' }
+
+export type TunnelConfig = {
+  name: string
+  provider: TunnelProvider
+  for: TunnelFor
+  externalUrl?: string
+  upstreamPort?: number
+}
+
+export type TunnelStatus = 'stopped' | 'starting' | 'healthy' | 'unhealthy' | 'permanently-failed'
+
+export type TunnelState = {
+  name: string
+  provider: TunnelProvider
+  for: TunnelFor
+  url: string | null
+  status: TunnelStatus
+  lastUrlAt: number | null
+  detail: string
+}
+
+export type TunnelProviderHandle = {
+  start: () => Promise<void>
+  stop: () => Promise<void>
+  snapshot: () => TunnelState
+  tail: () => string[]
+  subscribeToLogs: (cb: TunnelLogSubscriber) => Unsubscribe
+}
+
+export type TunnelLogSubscriber = (line: string) => void
+
+export type TunnelUrlChangedPayload = {
+  kind: 'tunnel-url-changed'
+  tunnelName: string
+  url: string
+  for: TunnelFor
+  rotatedAt: string
+}