typeclaw 0.1.0

package/src/hostd/portbroker-manager.ts

@@ -0,0 +1,101 @@
+import type { PortForward } from '@/config'
+import { resolveHostPort } from '@/container'
+import { type Broker, createBroker, type BrokerOptions, type PortForwardEvent } from '@/portbroker'
+
+import type { PortbrokerCallbacks, PortbrokerStartInput } from './daemon'
+import { createTailscaleServeManager, type TailscaleExec, type TailscaleServeManager } from './tailscale'
+
+export type PortbrokerManagerOptions = {
+  resolveHostPortFor?: (input: { containerName: string; cwd: string }) => Promise<number | null>
+  onLog?: (msg: string) => void
+  tailscaleExec?: TailscaleExec
+  createBrokerFor?: (opts: BrokerOptions) => Broker
+}
+
+// Glue between hostd's daemon and the portbroker package. Owns a Broker
+// instance per registered containerName. The daemon calls start()/stop()
+// through this manager. Reconnect after container restart works because the
+// resolver is re-invoked on each connect attempt — see portbroker hostd-client.
+export function createPortbrokerManager(opts: PortbrokerManagerOptions = {}): PortbrokerCallbacks & {
+  drain: () => Promise<void>
+} {
+  const brokers = new Map<string, Broker>()
+  const tailscaleManagers = new Map<string, TailscaleServeManager>()
+  const resolver = opts.resolveHostPortFor ?? defaultResolveHostPort
+  const log = opts.onLog ?? (() => {})
+  const brokerFactory = opts.createBrokerFor ?? createBroker
+
+  return {
+    start(input: PortbrokerStartInput) {
+      const existing = brokers.get(input.containerName)
+      if (existing) {
+        void existing.stop().catch(() => {})
+      }
+      const existingTailscale = tailscaleManagers.get(input.containerName)
+      if (existingTailscale) {
+        tailscaleManagers.delete(input.containerName)
+        void existingTailscale.stopAll().catch(() => {})
+      }
+      const tailscale = createTailscaleServeManager({
+        containerName: input.containerName,
+        exec: opts.tailscaleExec,
+        onEvent: input.onTailscaleServeEvent,
+        onLog: (msg) => log(`[tailscale:${input.containerName}] ${msg}`),
+      })
+      tailscaleManagers.set(input.containerName, tailscale)
+      const broker = brokerFactory({
+        containerName: input.containerName,
+        cwd: input.cwd,
+        policy: input.policy,
+        resolveHostPort: () => resolver({ containerName: input.containerName, cwd: input.cwd }),
+        brokerToken: input.brokerToken,
+        onEvent: (event) => {
+          input.onEvent(event)
+          if (event.kind === 'port-forward-opened') tailscale.servePort(event.port)
+          else if (event.kind === 'port-forward-closed') tailscale.stopPort(event.port)
+        },
+        onLog: (msg) => log(`[portbroker:${input.containerName}] ${msg}`),
+      })
+      brokers.set(input.containerName, broker)
+      broker.start()
+    },
+
+    async stop(containerName, reason) {
+      const broker = brokers.get(containerName)
+      if (!broker) return
+      brokers.delete(containerName)
+      await broker.stop()
+      const tailscale = tailscaleManagers.get(containerName)
+      if (tailscale) {
+        tailscaleManagers.delete(containerName)
+        await tailscale.stopAll()
+      }
+      log(`[portbroker:${containerName}] stopped (${reason})`)
+    },
+
+    forwardedPorts(containerName) {
+      const broker = brokers.get(containerName)
+      if (!broker) return []
+      return broker.forwardedPorts()
+    },
+
+    async drain() {
+      const all = Array.from(brokers.values())
+      const tailscale = Array.from(tailscaleManagers.values())
+      brokers.clear()
+      tailscaleManagers.clear()
+      await Promise.allSettled(all.map((b) => b.stop()))
+      await Promise.allSettled(tailscale.map((t) => t.stopAll()))
+    },
+  }
+}
+
+async function defaultResolveHostPort(input: { containerName: string; cwd: string }): Promise<number | null> {
+  try {
+    return await resolveHostPort({ cwd: input.cwd, retryMs: 500, intervalMs: 50 })
+  } catch {
+    return null
+  }
+}
+
+export type { PortForward, PortForwardEvent }

package/src/hostd/protocol.ts

@@ -0,0 +1,48 @@
+import type { PortForward } from '@/config'
+
+export type Request =
+  | {
+      kind: 'register'
+      containerName: string
+      cwd: string
+      restartToken?: string
+      wsHostPort?: number
+      portForward?: PortForward
+      brokerToken?: string
+    }
+  | { kind: 'deregister'; containerName: string }
+  | { kind: 'list' }
+  | { kind: 'status'; containerName: string }
+  | { kind: 'restart'; containerName: string; build?: boolean }
+  | { kind: 'http-info' }
+  | { kind: 'version' }
+  | { kind: 'shutdown' }
+
+export type Response = { ok: true; result?: unknown } | { ok: false; reason: string }
+
+export type ListResult = {
+  registrations: Array<{ containerName: string; cwd: string }>
+}
+
+export type StatusResult = {
+  containerName: string
+  cwd: string
+  forwardedPorts: number[]
+}
+
+export type RestartResult = {
+  containerName: string
+  scheduled: true
+}
+
+export type HttpInfoResult = {
+  port: number
+}
+
+export type VersionResult = {
+  version: string
+}
+
+export type ShutdownResult = {
+  scheduled: true
+}

package/src/hostd/spawn.ts

@@ -0,0 +1,224 @@
+import { existsSync } from 'node:fs'
+import { open, readFile, unlink, writeFile } from 'node:fs/promises'
+
+import { isDaemonReachable, send } from './client'
+import { ensureDirs, lockfilePath, logfilePath, pidfilePath, socketPath } from './paths'
+import type { HttpInfoResult, VersionResult } from './protocol'
+import { computeSourceVersion, resolveSrcRoot, UNVERSIONED_SENTINEL } from './version'
+
+export type EnsureDaemonOptions = {
+  cliEntry: string
+  spawnTimeoutMs?: number
+  // Test seam: tests inject a deterministic version probe + respawn so the
+  // unit test can exercise the drift path without spawning a real daemon.
+  expectedVersion?: string
+}
+
+export type EnsureDaemonResult =
+  | { ok: true; pid: number; spawned: boolean; respawned: boolean; httpPort: number }
+  | { ok: false; reason: string }
+
+const DEFAULT_SPAWN_TIMEOUT_MS = 5_000
+const SHUTDOWN_TIMEOUT_MS = 5_000
+const POLL_INTERVAL_MS = 50
+
+export async function ensureDaemon(opts: EnsureDaemonOptions): Promise<EnsureDaemonResult> {
+  if (await isDaemonReachable()) {
+    const expected = opts.expectedVersion ?? (await deriveExpectedVersion(opts.cliEntry))
+    const httpPort = await readHttpPort()
+    if ((await daemonVersionMatches(expected)) && httpPort !== null) {
+      return { ok: true, pid: await readPidQuiet(), spawned: false, respawned: false, httpPort }
+    }
+    const shutdownOk = await requestShutdownAndWait()
+    if (!shutdownOk) {
+      return { ok: false, reason: 'daemon version drifted but shutdown request did not complete' }
+    }
+    await ensureDirs()
+    const respawn = await ensureDaemonWithRetry(opts, 1)
+    if (!respawn.ok) return respawn
+    return { ...respawn, respawned: true }
+  }
+
+  await ensureDirs()
+  const result = await ensureDaemonWithRetry(opts, 1)
+  if (!result.ok) return result
+  return { ...result, respawned: false }
+}
+
+async function deriveExpectedVersion(cliEntry: string): Promise<string> {
+  const srcRoot = resolveSrcRoot(cliEntry)
+  if (srcRoot === null) return UNVERSIONED_SENTINEL
+  return computeSourceVersion({ srcRoot })
+}
+
+// A `version` reply that doesn't deserialize cleanly (e.g. a pre-feature
+// daemon that doesn't recognize the kind) is treated as a mismatch. Same for
+// any non-ok response. Conservative: it's safer to over-respawn than to keep
+// running stale code.
+async function daemonVersionMatches(expected: string): Promise<boolean> {
+  const reply = await send({ kind: 'version' }, { timeoutMs: 1_000 })
+  if (!reply.ok) return false
+  const result = reply.result as VersionResult | undefined
+  if (!result || typeof result.version !== 'string') return false
+  return result.version === expected
+}
+
+async function readHttpPort(): Promise<number | null> {
+  const reply = await send({ kind: 'http-info' }, { timeoutMs: 1_000 })
+  if (!reply.ok) return null
+  const result = reply.result as HttpInfoResult | undefined
+  return typeof result?.port === 'number' && result.port > 0 && result.port <= 65535 ? result.port : null
+}
+
+async function requestShutdownAndWait(): Promise<boolean> {
+  const reply = await send({ kind: 'shutdown' }, { timeoutMs: 1_000 })
+  if (!reply.ok) return false
+  const deadline = Date.now() + SHUTDOWN_TIMEOUT_MS
+  while (Date.now() < deadline) {
+    if (!existsSync(socketPath())) return true
+    await sleep(POLL_INTERVAL_MS)
+  }
+  return false
+}
+
+type SpawnAttemptResult = { ok: true; pid: number; spawned: boolean; httpPort: number } | { ok: false; reason: string }
+
+async function ensureDaemonWithRetry(opts: EnsureDaemonOptions, retriesLeft: number): Promise<SpawnAttemptResult> {
+  const lock = await acquireLockOrWait(opts.spawnTimeoutMs ?? DEFAULT_SPAWN_TIMEOUT_MS)
+  if (lock.kind === 'daemon-reachable') {
+    const httpPort = await readHttpPort()
+    if (httpPort === null) return { ok: false, reason: 'daemon did not report an HTTP control port' }
+    return { ok: true, pid: await readPidQuiet(), spawned: false, httpPort }
+  }
+  if (lock.kind === 'stale-lock-cleared') {
+    if (retriesLeft > 0) return ensureDaemonWithRetry(opts, retriesLeft - 1)
+    return { ok: false, reason: 'stale lockfile cleared but retry budget exhausted' }
+  }
+  if (lock.kind === 'timeout') {
+    return { ok: false, reason: lock.reason }
+  }
+
+  try {
+    if (await isDaemonReachable()) {
+      const httpPort = await readHttpPort()
+      if (httpPort === null) return { ok: false, reason: 'daemon did not report an HTTP control port' }
+      return { ok: true, pid: await readPidQuiet(), spawned: false, httpPort }
+    }
+    return await spawnDaemonDetached(opts)
+  } finally {
+    await releaseLock(lock.token)
+  }
+}
+
+async function spawnDaemonDetached(opts: EnsureDaemonOptions): Promise<SpawnAttemptResult> {
+  // Bun.spawn() with `stdout: <number>` consumes the file descriptor by
+  // dup()-ing it into the child; the parent's handle remains valid until we
+  // close it. Closing too early would race the dup. We hold the FileHandle
+  // open across spawn() and close it only after the child has been launched.
+  let handle: Awaited<ReturnType<typeof open>>
+  try {
+    handle = await open(logfilePath(), 'a')
+  } catch (error) {
+    return { ok: false, reason: `failed to open daemon log: ${stringify(error)}` }
+  }
+
+  let proc: ReturnType<typeof Bun.spawn>
+  try {
+    proc = Bun.spawn({
+      cmd: [process.execPath, opts.cliEntry, '_hostd'],
+      stdin: 'ignore',
+      stdout: handle.fd,
+      stderr: handle.fd,
+      env: { ...process.env },
+    })
+  } catch (error) {
+    handle.close().catch(() => {})
+    return { ok: false, reason: `failed to spawn daemon: ${stringify(error)}` }
+  }
+  proc.unref()
+  handle.close().catch(() => {})
+
+  try {
+    await writeFile(pidfilePath(), `${proc.pid}\n`)
+  } catch (error) {
+    try {
+      proc.kill('SIGTERM')
+    } catch {}
+    return { ok: false, reason: `failed to write daemon pidfile: ${stringify(error)}` }
+  }
+
+  const deadline = Date.now() + (opts.spawnTimeoutMs ?? DEFAULT_SPAWN_TIMEOUT_MS)
+  while (Date.now() < deadline) {
+    if (await isDaemonReachable()) {
+      const httpPort = await readHttpPort()
+      if (httpPort !== null) return { ok: true, pid: proc.pid, spawned: true, httpPort }
+    }
+    await sleep(POLL_INTERVAL_MS)
+  }
+
+  // Daemon failed to come up. Reap the orphan and clean the pidfile so the
+  // next ensureDaemon() doesn't observe a dangling pidfile pointing at our
+  // dead child.
+  try {
+    proc.kill('SIGTERM')
+  } catch {}
+  try {
+    const raw = await readFile(pidfilePath(), 'utf8').catch(() => '')
+    if (raw.trim() === String(proc.pid)) await unlink(pidfilePath())
+  } catch {}
+  return { ok: false, reason: 'daemon spawned but did not become reachable' }
+}
+
+type LockToken = { path: string }
+type LockResult =
+  | { kind: 'acquired'; token: LockToken }
+  | { kind: 'daemon-reachable' }
+  | { kind: 'stale-lock-cleared' }
+  | { kind: 'timeout'; reason: string }
+
+async function acquireLockOrWait(timeoutMs: number): Promise<LockResult> {
+  const path = lockfilePath()
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    try {
+      const handle = await open(path, 'wx')
+      await handle.write(`${process.pid}\n`)
+      await handle.close()
+      return { kind: 'acquired', token: { path } }
+    } catch {
+      if (await isDaemonReachable()) return { kind: 'daemon-reachable' }
+      await sleep(POLL_INTERVAL_MS)
+    }
+  }
+  // Lock held by something that never finished. Clear it so the caller can
+  // retry once. Rare in practice (only happens if a previous ensureDaemon
+  // process was killed mid-spawn).
+  try {
+    await unlink(path)
+  } catch {}
+  return { kind: 'stale-lock-cleared' }
+}
+
+async function releaseLock(token: LockToken): Promise<void> {
+  try {
+    await unlink(token.path)
+  } catch {}
+}
+
+async function readPidQuiet(): Promise<number> {
+  try {
+    const raw = await readFile(pidfilePath(), 'utf8')
+    const pid = Number.parseInt(raw.trim(), 10)
+    return Number.isFinite(pid) ? pid : 0
+  } catch {
+    return 0
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function stringify(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}

package/src/hostd/supervisor.ts

@@ -0,0 +1,60 @@
+import type { Response } from './protocol'
+
+export type SupervisorRestart = (input: {
+  containerName: string
+  cwd: string
+  // When true, the underlying `start()` runs with `forceBuild: true`, which
+  // regenerates the Dockerfile from the current CLI template AND rebuilds the
+  // image even if it already exists. Default false matches the host-side
+  // `typeclaw restart` (no `--build` flag) behavior.
+  build?: boolean
+}) => Promise<{ ok: true } | { ok: false; reason: string }>
+
+export type SupervisorOptions = {
+  restart?: SupervisorRestart
+}
+
+export type SupervisorLogEvent =
+  | { kind: 'restart-scheduled'; containerName: string; build: boolean }
+  | { kind: 'restart-completed'; containerName: string }
+  | { kind: 'restart-failed'; containerName: string; reason: string }
+
+export type Supervisor = {
+  scheduleRestart: (input: { containerName: string; cwd: string; build?: boolean }) => Response
+}
+
+export type SupervisorBuildOptions = {
+  restart: SupervisorRestart
+  onLog: (event: SupervisorLogEvent) => void
+  isStopped: () => boolean
+}
+
+// The daemon ACKs the agent immediately so the container can exit cleanly,
+// then runs stop+start in the background. If we ran them inline the agent's
+// own RPC connection would die when its container stopped — guaranteed to
+// race because `docker stop` is the very thing we're about to do. Errors are
+// surfaced via the log channel; there is no connected client to receive them.
+export function buildSupervisor({ restart, onLog, isStopped }: SupervisorBuildOptions): Supervisor {
+  return {
+    scheduleRestart: ({ containerName, cwd, build = false }): Response => {
+      if (isStopped()) return { ok: false, reason: 'daemon stopping' }
+      onLog({ kind: 'restart-scheduled', containerName, build })
+      void runRestart()
+      return { ok: true }
+
+      async function runRestart(): Promise<void> {
+        try {
+          const result = await restart({ containerName, cwd, build })
+          if (result.ok) onLog({ kind: 'restart-completed', containerName })
+          else onLog({ kind: 'restart-failed', containerName, reason: result.reason })
+        } catch (error) {
+          onLog({
+            kind: 'restart-failed',
+            containerName,
+            reason: error instanceof Error ? error.message : String(error),
+          })
+        }
+      }
+    },
+  }
+}

package/src/hostd/tailscale.ts

@@ -0,0 +1,172 @@
+import { getBun } from '@/container/shared'
+
+export type TailscaleExecResult = { exitCode: number; stdout: string; stderr: string }
+export type TailscaleExec = (args: string[]) => Promise<TailscaleExecResult>
+
+export type TailscaleServeEvent =
+  | { kind: 'tailscale-serve-opened'; containerName: string; port: number }
+  | { kind: 'tailscale-serve-closed'; containerName: string; port: number }
+  | { kind: 'tailscale-serve-skipped'; containerName: string; port: number; reason: string }
+  | {
+      kind: 'tailscale-serve-failed'
+      containerName: string
+      port: number
+      command: 'status' | 'serve' | 'off'
+      reason: string
+    }
+
+export type TailscaleServeManager = {
+  servePort: (port: number) => void
+  stopPort: (port: number) => void
+  stopAll: () => Promise<void>
+}
+
+export type TailscaleServeManagerOptions = {
+  containerName: string
+  exec?: TailscaleExec
+  onEvent: (event: TailscaleServeEvent) => void
+  onLog?: (msg: string) => void
+}
+
+type TailscaleStatus = {
+  BackendState?: unknown
+}
+
+const MACOS_APP_CLI = '/Applications/Tailscale.app/Contents/MacOS/Tailscale'
+
+export function createTailscaleServeManager(opts: TailscaleServeManagerOptions): TailscaleServeManager {
+  const exec = opts.exec ?? defaultTailscaleExec
+  const log = opts.onLog ?? (() => {})
+  const ownedPorts = new Set<number>()
+  const pending = new Set<Promise<void>>()
+
+  const track = (work: Promise<void>): void => {
+    pending.add(work)
+    work.finally(() => pending.delete(work)).catch(() => {})
+  }
+
+  const emit = (event: TailscaleServeEvent): void => {
+    try {
+      opts.onEvent(event)
+    } catch (error) {
+      log(`tailscale serve event handler threw: ${stringifyError(error)}`)
+    }
+  }
+
+  const servePort = (port: number): void => {
+    if (ownedPorts.has(port)) return
+    track(
+      (async () => {
+        const ready = await checkRunning(exec)
+        if (!ready.ok) {
+          emit({ kind: 'tailscale-serve-skipped', containerName: opts.containerName, port, reason: ready.reason })
+          return
+        }
+
+        const result = await exec(['serve', '--bg', `--tcp=${port}`, String(port)])
+        if (result.exitCode !== 0) {
+          emit({
+            kind: 'tailscale-serve-failed',
+            containerName: opts.containerName,
+            port,
+            command: 'serve',
+            reason: commandError(result),
+          })
+          return
+        }
+
+        ownedPorts.add(port)
+        emit({ kind: 'tailscale-serve-opened', containerName: opts.containerName, port })
+      })(),
+    )
+  }
+
+  const stopPort = (port: number): void => {
+    if (!ownedPorts.has(port)) return
+    track(stopOwnedPort(port))
+  }
+
+  const stopOwnedPort = async (port: number): Promise<void> => {
+    const result = await exec(['serve', `--tcp=${port}`, 'off'])
+    if (result.exitCode !== 0) {
+      emit({
+        kind: 'tailscale-serve-failed',
+        containerName: opts.containerName,
+        port,
+        command: 'off',
+        reason: commandError(result),
+      })
+      return
+    }
+
+    ownedPorts.delete(port)
+    emit({ kind: 'tailscale-serve-closed', containerName: opts.containerName, port })
+  }
+
+  return {
+    servePort,
+    stopPort,
+    async stopAll() {
+      await Promise.allSettled(Array.from(pending))
+      await Promise.allSettled(Array.from(ownedPorts).map((port) => stopOwnedPort(port)))
+    },
+  }
+}
+
+async function checkRunning(exec: TailscaleExec): Promise<{ ok: true } | { ok: false; reason: string }> {
+  const result = await exec(['status', '--json'])
+  if (result.exitCode !== 0) return { ok: false, reason: commandError(result) }
+
+  let parsed: TailscaleStatus
+  try {
+    parsed = JSON.parse(result.stdout) as TailscaleStatus
+  } catch (error) {
+    return { ok: false, reason: `invalid tailscale status JSON: ${stringifyError(error)}` }
+  }
+
+  if (parsed.BackendState !== 'Running')
+    return { ok: false, reason: `tailscale backend is ${String(parsed.BackendState)}` }
+  return { ok: true }
+}
+
+export const defaultTailscaleExec: TailscaleExec = async (args) => {
+  const candidates = process.platform === 'darwin' ? ['tailscale', MACOS_APP_CLI] : ['tailscale']
+  let lastError = 'tailscale command not found'
+
+  for (const candidate of candidates) {
+    const result = await runTailscale(candidate, args)
+    if (result.exitCode !== 127) return result
+    lastError = result.stderr || lastError
+  }
+
+  return { exitCode: 127, stdout: '', stderr: lastError }
+}
+
+async function runTailscale(bin: string, args: string[]): Promise<TailscaleExecResult> {
+  const bun = getBun()
+  if (!bun) return { exitCode: 127, stdout: '', stderr: 'bun runtime not available' }
+  try {
+    const proc = bun.spawn({
+      cmd: [bin, ...args],
+      stdout: 'pipe',
+      stderr: 'pipe',
+      env: bin === MACOS_APP_CLI ? { ...process.env, TAILSCALE_BE_CLI: '1' } : process.env,
+    })
+    const exitCode = await proc.exited
+    const stdout = await new Response(proc.stdout).text()
+    const stderr = await new Response(proc.stderr).text()
+    return { exitCode, stdout, stderr }
+  } catch (error) {
+    const code = typeof error === 'object' && error !== null && 'code' in error ? String(error.code) : ''
+    const exitCode = code === 'ENOENT' ? 127 : 1
+    return { exitCode, stdout: '', stderr: stringifyError(error) }
+  }
+}
+
+function commandError(result: TailscaleExecResult): string {
+  return (result.stderr || result.stdout || `exit ${result.exitCode}`).trim()
+}
+
+function stringifyError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}