typeclaw 0.1.0

package/src/container/status.ts

@@ -0,0 +1,76 @@
+import { CONTAINER_PORT } from './port'
+import { containerNameFromCwd, defaultDockerExec, imageTagFromCwd, type DockerExec } from './shared'
+
+export type ContainerStatus =
+  | { kind: 'missing'; containerName: string; imageTag: string }
+  | {
+      kind: 'stopped'
+      containerName: string
+      imageTag: string
+      containerId: string
+      configuredImage: string
+    }
+  | {
+      kind: 'running'
+      containerName: string
+      imageTag: string
+      containerId: string
+      configuredImage: string
+      hostPort: number | null
+      hostBindAddr: string | null
+    }
+
+export type StatusOptions = {
+  cwd: string
+  exec?: DockerExec
+}
+
+export async function status({ cwd, exec = defaultDockerExec }: StatusOptions): Promise<ContainerStatus> {
+  const containerName = containerNameFromCwd(cwd)
+  const imageTag = imageTagFromCwd(cwd)
+
+  const inspect = await exec(['inspect', '--format', '{{.State.Running}}|{{.Id}}|{{.Config.Image}}', containerName])
+  if (inspect.exitCode !== 0) {
+    return { kind: 'missing', containerName, imageTag }
+  }
+
+  const [runningRaw = '', containerId = '', configuredImage = ''] = inspect.stdout.trim().split('|')
+  const running = runningRaw.trim() === 'true'
+
+  if (!running) {
+    return { kind: 'stopped', containerName, imageTag, containerId, configuredImage }
+  }
+
+  const mapping = await queryPortMapping(exec, containerName)
+  return {
+    kind: 'running',
+    containerName,
+    imageTag,
+    containerId,
+    configuredImage,
+    hostPort: mapping?.port ?? null,
+    hostBindAddr: mapping?.bindAddr ?? null,
+  }
+}
+
+type PortMapping = { bindAddr: string; port: number }
+
+// Mirrors parseDockerPortOutput in ./port but also keeps the bind address so
+// status can show "127.0.0.1:51234 -> 8973" instead of just the host port.
+async function queryPortMapping(exec: DockerExec, containerName: string): Promise<PortMapping | null> {
+  const result = await exec(['port', containerName, `${CONTAINER_PORT}/tcp`])
+  if (result.exitCode !== 0) return null
+  const lines = result.stdout
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+  if (lines.length === 0) return null
+
+  const ipv4 = lines.find((line) => /^\d{1,3}(\.\d{1,3}){3}:\d+$/.test(line))
+  const candidate = ipv4 ?? lines[0]!
+  const lastColon = candidate.lastIndexOf(':')
+  if (lastColon < 0) return null
+  const port = Number(candidate.slice(lastColon + 1))
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) return null
+  return { bindAddr: candidate.slice(0, lastColon), port }
+}

package/src/container/stop.ts

@@ -0,0 +1,120 @@
+import { isDaemonReachable, send as sendToDaemon } from '@/hostd/client'
+
+import {
+  classifyRmStderr,
+  containerNameFromCwd,
+  defaultDockerExec,
+  type DockerExec,
+  sanitizeDockerStderr,
+  waitForRemoval,
+} from './shared'
+
+export type StopPlan = {
+  containerName: string
+}
+
+export type StopResult = { ok: true; containerName: string; running: boolean } | { ok: false; reason: string }
+
+export type StopOptions = {
+  cwd: string
+  exec?: DockerExec
+}
+
+export async function stop({ cwd, exec = defaultDockerExec }: StopOptions): Promise<StopResult> {
+  const { containerName } = planStop(cwd)
+
+  if (await isDaemonReachable()) {
+    await sendToDaemon({ kind: 'deregister', containerName })
+  }
+
+  try {
+    const inspect = await exec(['inspect', '--format', '{{.State.Running}}', containerName], { cwd })
+    if (inspect.exitCode !== 0) {
+      // `docker inspect` exits non-zero both when the container does not
+      // exist AND when it exists but is in a transient state docker cannot
+      // inspect (Removal In Progress, Dead, daemon hiccup). Discriminate by
+      // stderr — same approach used for `docker rm` below — and attempt a
+      // force-remove in the latter case so a corpse holding the name does
+      // not collide with the next `docker run --name <same>`.
+      if (inspect.stderr.toLowerCase().includes('no such container')) {
+        return { ok: true, containerName, running: false }
+      }
+      const recover = await exec(['rm', '-f', containerName], { cwd })
+      if (recover.exitCode !== 0) {
+        const kind = classifyRmStderr(recover.stderr)
+        if (kind === null) {
+          return {
+            ok: false,
+            reason: `docker inspect failed (${sanitizeDockerStderr(inspect.stderr) || 'no stderr'}) and docker rm -f could not recover: ${sanitizeDockerStderr(recover.stderr) || 'no stderr'}`,
+          }
+        }
+        if (kind === 'in-progress' && !(await waitForRemoval(exec, containerName))) {
+          return {
+            ok: false,
+            reason: `Container ${containerName} is still being removed by docker after 10s.`,
+          }
+        }
+      }
+      return { ok: true, containerName, running: false }
+    }
+    const running = inspect.stdout.trim() === 'true'
+
+    // Only call `docker stop` when the container is actually running. A stopped
+    // corpse from a prior crash is left around by design (no `--rm`), and
+    // `docker stop` on an exited container would still succeed but emit a
+    // noisy warning to stderr — skip it.
+    if (running) {
+      const stopResult = await exec(['stop', containerName], { cwd })
+      if (stopResult.exitCode !== 0) {
+        return { ok: false, reason: `docker stop failed: ${sanitizeDockerStderr(stopResult.stderr) || 'no stderr'}` }
+      }
+    }
+
+    // Containers run without `--rm`, so `docker stop` only stops them — the
+    // record stays in `docker ps -a` until we remove it explicitly. Remove now
+    // so a subsequent `docker run --name <same>` (e.g. from `typeclaw restart`)
+    // does not collide on the name. Use `-f` for symmetry with the start.ts
+    // preflight and because `docker stop` occasionally returns exit 0 before
+    // the container is fully out of `Running` state on OrbStack under load —
+    // bare `docker rm` would then refuse a still-running container. See
+    // classifyRmStderr for the benign-failure contract; when 'in-progress',
+    // wait for the drain so stop()'s ok-return actually means "name is free"
+    // (which compose's restart and any subsequent start() depend on).
+    //
+    // Same waitForRemoval call on the exit-0 path for the same reason as the
+    // start.ts preflight: OrbStack and Docker Desktop under load acknowledge
+    // `rm -f` before the daemon has finished draining the removal, so an
+    // immediate `docker run --name <same>` (from `typeclaw compose restart`,
+    // which fires stop→start sequentially per agent) races the drain and
+    // fails with "Conflict. The container name … is already in use by
+    // container <ID>". stop()'s contract is that the name is free on return,
+    // and the only way to honor that against Docker's async removal is to
+    // poll inspect until the container actually disappears.
+    const rmResult = await exec(['rm', '-f', containerName], { cwd })
+    if (rmResult.exitCode !== 0) {
+      const kind = classifyRmStderr(rmResult.stderr)
+      if (kind === null) {
+        return { ok: false, reason: `docker rm failed: ${sanitizeDockerStderr(rmResult.stderr) || 'no stderr'}` }
+      }
+      if (kind === 'in-progress' && !(await waitForRemoval(exec, containerName))) {
+        return {
+          ok: false,
+          reason: `Container ${containerName} is still being removed by docker after 10s.`,
+        }
+      }
+    } else if (!(await waitForRemoval(exec, containerName))) {
+      return {
+        ok: false,
+        reason: `Container ${containerName} is still being removed by docker after 10s.`,
+      }
+    }
+
+    return { ok: true, containerName, running }
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+export function planStop(cwd: string): StopPlan {
+  return { containerName: containerNameFromCwd(cwd) }
+}

package/src/container/verify-running.ts

@@ -0,0 +1,149 @@
+import type { DockerExec } from './shared'
+
+export type ContainerLifeStatus = 'running' | 'created' | 'restarting' | 'paused' | 'exited' | 'dead' | 'removing'
+
+export type ContainerProbeResult =
+  | { kind: 'missing' }
+  | { kind: 'status'; status: ContainerLifeStatus }
+  | { kind: 'daemon-error'; detail: string }
+
+export type CrashLogs = { ok: true; text: string } | { ok: false; error: string }
+
+export type VerifyRunningResult =
+  | { ok: true }
+  | { ok: false; mode: 'removed'; logs: CrashLogs }
+  | { ok: false; mode: 'exited'; status: ContainerLifeStatus; logs: CrashLogs }
+  | { ok: false; mode: 'daemon-error'; detail: string }
+
+export type VerifyRunningFn = (containerName: string) => Promise<VerifyRunningResult>
+
+export type VerifyRunningOptions = {
+  exec: DockerExec
+  timeoutMs?: number
+  intervalMs?: number
+  logsTimeoutMs?: number
+  now?: () => number
+  sleep?: (ms: number) => Promise<void>
+}
+
+// Docker reports container State.Status as one of: created, running, paused,
+// restarting, removing, exited, dead. `created`/`restarting` are transient and
+// must NOT be classified as crashes — `docker run -d` returns once the daemon
+// has fired off `tsk.Start()` and called State.SetRunning, but on slow hosts
+// (Docker Desktop on macOS, loaded swarm nodes) the in-memory transition can
+// briefly trail the API return. Treating either as a crash produces false
+// positives; we keep polling until the state resolves OR the deadline hits.
+const TRANSIENT_STATUSES: ReadonlySet<ContainerLifeStatus> = new Set(['created', 'restarting'])
+const TERMINAL_STATUSES: ReadonlySet<ContainerLifeStatus> = new Set(['exited', 'dead', 'removing'])
+
+// Matches the stderr Docker emits when `docker inspect <name>` finds nothing.
+// Everything else — 500s, socket errors, permission denied, daemon restart —
+// must surface as a daemon-error rather than be misclassified as
+// "container does not exist".
+const NO_SUCH_CONTAINER = /no such (?:container|object)/i
+
+export function createVerifyRunning(options: VerifyRunningOptions): VerifyRunningFn {
+  const timeoutMs = options.timeoutMs ?? 1_500
+  const intervalMs = options.intervalMs ?? 100
+  const logsTimeoutMs = options.logsTimeoutMs ?? 500
+  const now = options.now ?? Date.now
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)))
+  return async (containerName) => {
+    if (timeoutMs <= 0) return { ok: true }
+    const deadline = now() + timeoutMs
+    while (now() < deadline) {
+      const probe = await probeContainer(options.exec, containerName)
+      if (probe.kind === 'daemon-error') {
+        return { ok: false, mode: 'daemon-error', detail: probe.detail }
+      }
+      if (probe.kind === 'missing') {
+        const logs = await captureCrashLogs(options.exec, containerName, logsTimeoutMs)
+        return { ok: false, mode: 'removed', logs }
+      }
+      if (probe.status === 'running' || probe.status === 'paused') {
+        await sleepRespectingDeadline(sleep, intervalMs, now, deadline)
+        continue
+      }
+      if (TRANSIENT_STATUSES.has(probe.status)) {
+        await sleepRespectingDeadline(sleep, intervalMs, now, deadline)
+        continue
+      }
+      if (TERMINAL_STATUSES.has(probe.status)) {
+        const logs = await captureCrashLogs(options.exec, containerName, logsTimeoutMs)
+        return { ok: false, mode: 'exited', status: probe.status, logs }
+      }
+      await sleepRespectingDeadline(sleep, intervalMs, now, deadline)
+    }
+    return { ok: true }
+  }
+}
+
+async function sleepRespectingDeadline(
+  sleep: (ms: number) => Promise<void>,
+  intervalMs: number,
+  now: () => number,
+  deadline: number,
+): Promise<void> {
+  const remaining = deadline - now()
+  if (remaining <= 0) return
+  await sleep(Math.min(intervalMs, remaining))
+}
+
+export async function probeContainer(exec: DockerExec, name: string): Promise<ContainerProbeResult> {
+  const result = await exec(['inspect', '--format', '{{.State.Status}}', name])
+  if (result.exitCode === 0) {
+    const raw = result.stdout.trim().toLowerCase()
+    if (isLifeStatus(raw)) return { kind: 'status', status: raw }
+    return { kind: 'daemon-error', detail: `docker inspect returned unrecognized status: ${raw || '<empty>'}` }
+  }
+  if (NO_SUCH_CONTAINER.test(result.stderr)) return { kind: 'missing' }
+  const detail = result.stderr.trim() || `docker inspect exited with code ${result.exitCode}`
+  return { kind: 'daemon-error', detail }
+}
+
+function isLifeStatus(value: string): value is ContainerLifeStatus {
+  return (
+    value === 'running' ||
+    value === 'created' ||
+    value === 'restarting' ||
+    value === 'paused' ||
+    value === 'exited' ||
+    value === 'dead' ||
+    value === 'removing'
+  )
+}
+
+async function captureCrashLogs(exec: DockerExec, name: string, timeoutMs: number): Promise<CrashLogs> {
+  const signal = AbortSignal.timeout(timeoutMs)
+  const result = await exec(['logs', '--tail', '50', name], { signal })
+  const combined = `${result.stdout}${result.stderr}`.trim()
+  if (result.exitCode === 0) return { ok: true, text: combined }
+  if (signal.aborted) return { ok: false, error: `docker logs timed out after ${timeoutMs}ms` }
+  // Docker writes container stdout/stderr to stdout/stderr respectively for
+  // `docker logs`. Partial output is worth surfacing even when the command
+  // ultimately fails (e.g. container removed mid-read), so we keep `combined`
+  // alongside the docker-level error rather than discarding it.
+  const dockerError = result.stderr.trim() || `docker logs exited with code ${result.exitCode}`
+  if (combined.length > 0) return { ok: false, error: `${dockerError} (partial logs preserved)` }
+  return { ok: false, error: dockerError }
+}
+
+export function buildCrashReason(name: string, failure: Extract<VerifyRunningResult, { ok: false }>): string {
+  if (failure.mode === 'daemon-error') {
+    return `Could not verify container ${name} stayed running: ${failure.detail}`
+  }
+  // We don't pass `--rm` to `docker run`, so a `removed` outcome means an
+  // external process (the user, docker prune, a CI cleanup) removed the
+  // container during our 1.5s verify window. Surface this distinctly from the
+  // ordinary `exited` crash because the logs are gone and the user needs to
+  // know why instead of chasing a phantom application bug.
+  const headline =
+    failure.mode === 'removed'
+      ? `Container ${name} disappeared during start verification (an external process removed it).`
+      : `Container ${name} stopped running immediately after start (state: ${failure.status}).`
+  if (failure.logs.ok) {
+    if (failure.logs.text.length === 0) return `${headline} Container produced no logs.`
+    return `${headline} Last logs:\n${failure.logs.text}`
+  }
+  return `${headline} Could not read container logs: ${failure.logs.error}`
+}

package/src/cron/consumer.ts

@@ -0,0 +1,138 @@
+import type { HookBus } from '@/plugin'
+import type { Stream, Unsubscribe } from '@/stream'
+
+import type { CronJob, ExecJob, PromptJob } from './schema'
+
+// `hooks`, `sessionId`, and `getTranscriptPath` are optional so test fakes can
+// stay one-liners. When present, the consumer fires `session.idle` after every
+// prompt completion and `session.end` on dispose, mirroring the lifecycle
+// signals the TUI server already emits in `src/server/index.ts`. Without this
+// the bundled memory plugin's debounced `memory-logger` never spawns for cron
+// prompt jobs because it only wakes on `session.idle`.
+export type CronSession = {
+  prompt: (text: string) => Promise<void>
+  dispose?: () => void
+  hooks?: HookBus
+  sessionId?: string
+  getTranscriptPath?: () => string | undefined
+}
+
+export type CronConsumerLogger = {
+  info: (msg: string) => void
+  warn: (msg: string) => void
+  error: (msg: string) => void
+}
+
+export type CreateCronConsumerOptions = {
+  stream: Stream
+  cwd: string
+  createSessionForCron: (job: PromptJob) => Promise<CronSession>
+  logger?: CronConsumerLogger
+}
+
+export type CronConsumer = {
+  start: () => void
+  stop: () => void
+  inFlightCount: () => number
+}
+
+const consoleLogger: CronConsumerLogger = {
+  info: (m) => console.log(m),
+  warn: (m) => console.warn(m),
+  error: (m) => console.error(m),
+}
+
+export function createCronConsumer({
+  stream,
+  cwd,
+  createSessionForCron,
+  logger = consoleLogger,
+}: CreateCronConsumerOptions): CronConsumer {
+  const inFlight = new Set<string>()
+  let unsubscribe: Unsubscribe | null = null
+
+  return {
+    start() {
+      if (unsubscribe !== null) return
+      unsubscribe = stream.subscribe({ target: { kind: 'cron' } }, async (msg) => {
+        const job = msg.payload as CronJob
+        if (!isCronJob(job)) {
+          logger.warn(`[cron-consumer] received message ${msg.id} with invalid payload, ignoring`)
+          return
+        }
+        if (inFlight.has(job.id)) {
+          logger.warn(`[cron] ${job.id}: previous run still in progress, skipping`)
+          return
+        }
+        inFlight.add(job.id)
+        try {
+          if (job.kind === 'prompt') {
+            await runPrompt(job, createSessionForCron, stream)
+          } else {
+            await runExec(job, cwd)
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err)
+          logger.error(`[cron] ${job.id} failed: ${message}`)
+        } finally {
+          inFlight.delete(job.id)
+        }
+      })
+    },
+    stop() {
+      unsubscribe?.()
+      unsubscribe = null
+    },
+    inFlightCount() {
+      return inFlight.size
+    },
+  }
+}
+
+async function runPrompt(
+  job: PromptJob,
+  createSessionForCron: (job: PromptJob) => Promise<CronSession>,
+  stream: Stream,
+): Promise<void> {
+  if (job.subagent !== undefined) {
+    stream.publish({
+      target: { kind: 'new-session', subagent: job.subagent },
+      payload: job.payload,
+    })
+    return
+  }
+  const session = await createSessionForCron(job)
+  try {
+    await session.prompt(job.prompt)
+    if (session.hooks && session.sessionId !== undefined) {
+      await session.hooks.runSessionIdle({
+        sessionId: session.sessionId,
+        parentTranscriptPath: session.getTranscriptPath?.(),
+        idleMs: 0,
+      })
+    }
+  } finally {
+    if (session.hooks && session.sessionId !== undefined) {
+      await session.hooks.runSessionEnd({ sessionId: session.sessionId })
+    }
+    session.dispose?.()
+  }
+}
+
+async function runExec(job: ExecJob, cwd: string): Promise<void> {
+  const [cmd, ...args] = job.command
+  if (!cmd) throw new Error(`exec job ${job.id}: empty command`)
+  const proc = Bun.spawn({ cmd: [cmd, ...args], cwd, stdout: 'pipe', stderr: 'pipe' })
+  const code = await proc.exited
+  if (code !== 0) {
+    const stderr = await new Response(proc.stderr).text()
+    throw new Error(`exec job ${job.id} exited with code ${code}: ${stderr.trim() || 'no stderr'}`)
+  }
+}
+
+function isCronJob(value: unknown): value is CronJob {
+  if (typeof value !== 'object' || value === null) return false
+  const v = value as { id?: unknown; kind?: unknown }
+  if (typeof v.id !== 'string') return false
+  return v.kind === 'prompt' || v.kind === 'exec'
+}

package/src/cron/index.ts

@@ -0,0 +1,54 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import type { SubagentRegistry } from '@/agent/subagents'
+
+import { type CronFile, parseCronFile } from './schema'
+
+export { createCronReloadable, type CreateCronReloadableOptions } from './reloadable'
+export {
+  createCronConsumer,
+  type CreateCronConsumerOptions,
+  type CronConsumer,
+  type CronConsumerLogger,
+  type CronSession,
+} from './consumer'
+export { createScheduler, type JobDiff, type Scheduler, type SchedulerLogger } from './scheduler'
+export { cronFileSchema, cronJobSchema, type CronFile, type CronJob, type ExecJob, type PromptJob } from './schema'
+
+const CRON_FILE = 'cron.json'
+
+export type LoadCronResult = { ok: true; file: CronFile | null } | { ok: false; reason: string }
+
+export type LoadCronOptions = {
+  subagents?: SubagentRegistry
+}
+
+export async function loadCron(agentDir: string, options: LoadCronOptions = {}): Promise<LoadCronResult> {
+  const path = join(agentDir, CRON_FILE)
+  if (!existsSync(path)) return { ok: true, file: null }
+
+  let raw: string
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch (err) {
+    return { ok: false, reason: `failed to read cron.json: ${errorMessage(err)}` }
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch (err) {
+    return { ok: false, reason: `cron.json is not valid JSON: ${errorMessage(err)}` }
+  }
+
+  const result = parseCronFile(parsed, options.subagents !== undefined ? { subagents: options.subagents } : {})
+  if (!result.ok) return { ok: false, reason: result.reason }
+
+  return { ok: true, file: result.file }
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}

package/src/cron/reloadable.ts

@@ -0,0 +1,64 @@
+import type { SubagentRegistry } from '@/agent/subagents'
+import type { Reloadable, ReloadResult } from '@/reload'
+
+import { loadCron } from './index'
+import type { JobDiff, Scheduler } from './scheduler'
+import type { CronJob } from './schema'
+
+export type CreateCronReloadableOptions = {
+  cwd: string
+  scheduler: Scheduler
+  // Internal jobs (e.g. dreaming) survive cron.json reloads. The reloadable
+  // recomputes them on every reload so config-driven changes propagate too.
+  internalJobs?: () => CronJob[]
+  // Resolved per reload so plugin reloads (registered earlier) are visible
+  // when cron re-validates job.subagent references.
+  getSubagents?: () => SubagentRegistry
+}
+
+export function createCronReloadable({
+  cwd,
+  scheduler,
+  internalJobs,
+  getSubagents,
+}: CreateCronReloadableOptions): Reloadable {
+  return {
+    scope: 'cron',
+    description: 'cron jobs from cron.json',
+    reload: async () => doReload({ cwd, scheduler, internalJobs, getSubagents }),
+  }
+}
+
+async function doReload({
+  cwd,
+  scheduler,
+  internalJobs,
+  getSubagents,
+}: CreateCronReloadableOptions): Promise<ReloadResult> {
+  const subagents = getSubagents?.()
+  const loaded = await loadCron(cwd, subagents !== undefined ? { subagents } : {})
+  if (!loaded.ok) {
+    return { scope: 'cron', ok: false, reason: loaded.reason }
+  }
+  const userJobs = loaded.file?.jobs ?? []
+  const nextJobs: CronJob[] = [...userJobs, ...(internalJobs?.() ?? [])]
+
+  let diff: JobDiff
+  try {
+    diff = scheduler.replaceJobs(nextJobs)
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    return { scope: 'cron', ok: false, reason: `apply failed (schedule unchanged): ${message}` }
+  }
+
+  return {
+    scope: 'cron',
+    ok: true,
+    summary: formatSummary(diff, nextJobs.length),
+    details: diff,
+  }
+}
+
+function formatSummary(diff: JobDiff, total: number): string {
+  return `${total} jobs (added ${diff.added.length}, removed ${diff.removed.length}, updated ${diff.updated.length}, unchanged ${diff.unchanged.length})`
+}