@toist/in 0.7.1 → 0.8.1

package/src/cli.ts

@@ -0,0 +1,1003 @@
+#!/usr/bin/env bun
+// 2121 toist
+
+import { readFileSync } from "node:fs"
+import { resolve } from "node:path"
+import { createInterface } from "node:readline/promises"
+import { parseYaml, validateSpec, type PipelineSpec } from "@toist/spec"
+import { createRunnerClient, startRunner, type PipelineRunResponse, type RunnerClient } from "@toist/aja"
+import { runSpec, type RunSpecResult, type TaskDescriptor, type ToistRuntime } from "@toist/core"
+import {
+  deleteRunDescriptor,
+  getCliRuntime,
+  isResumableRuntime,
+  loadRunDescriptor,
+  resumeLocalStoredRun,
+  storeRunDescriptor,
+  type StoredRunDescriptor,
+} from "./runtime.ts"
+import { wizard } from "./wizard.ts"
+import { upgrade } from "./upgrade.ts"
+
+const args = process.argv.slice(2)
+const cmd = args[0]
+let stdinTextPromise: Promise<string> | null = null
+
+interface RunCliOptions {
+  pathArg?: string
+  payloadArg?: string
+  specStdin: boolean
+  payloadStdin: boolean
+  suspendAsJson: boolean
+  ephemeral: boolean
+  remote?: string
+}
+
+interface ResumeCliOptions {
+  runId?: number
+  responseArg?: string
+  suspendAsJson: boolean
+}
+
+interface ServeCliOptions {
+  port: number
+  rootDir: string
+  memory: boolean
+  noUi: boolean
+  noWatch: boolean
+}
+
+interface TasksCliOptions {
+  remote?: string
+  format: "table" | "json"
+}
+
+interface CliTaskRef {
+  id: number
+  nodeId: string
+  kind: "human.input" | "error_review"
+  prompt: string
+  schema: unknown
+  assignee: string | null
+  responseToken: string
+}
+
+type NormalizedStepList = Array<Record<string, unknown>>
+
+type NormalizedRunResult =
+  | {
+    status: "done"
+    runId: number
+    output: unknown
+    steps: NormalizedStepList
+    results: Record<string, unknown>
+  }
+  | {
+    status: "suspended"
+    runId: number
+    suspendedAt: {
+      taskId: number
+      nodeId: string
+      cause: {
+        kind: "human.input" | "error_review"
+        spec: {
+          prompt: string
+          schema?: unknown
+          assignee?: string | null
+        }
+      }
+    }
+    task: {
+      id: number
+      kind: string
+      prompt: string
+      schema: unknown
+      assignee: string | null
+      responseToken: string
+    } | null
+    steps: NormalizedStepList
+    results: Record<string, unknown>
+  }
+  | {
+    status: "error"
+    runId: number
+    error: string
+    steps?: NormalizedStepList
+  }
+
+type PrintableRunResult = RunSpecResult | NormalizedRunResult
+type PrintableSuspendedRunResult = Extract<RunSpecResult, { status: "suspended" }> | Extract<NormalizedRunResult, { status: "suspended" }>
+
+function help() {
+  console.log("toist <command> [options]\n")
+  console.log("  init                        run setup wizard")
+  console.log("  run <file>                  run a pipeline")
+  console.log("     --remote <url>           run against a remote runner")
+  console.log("     --spec-stdin             read spec YAML from stdin")
+  console.log("     --payload '<json>'       read payload from flag")
+  console.log("     --payload @file.json     read payload JSON from file")
+  console.log("     --payload-stdin          read payload JSON from stdin")
+  console.log("     --suspend-as-json        print only { runId, suspendedAt } on suspension")
+  console.log("     --ephemeral              use in-memory runtime only")
+  console.log("  resume <runId>              resume a suspended local run")
+  console.log("  serve                       start the durable runner")
+  console.log("  tasks list                  list open tasks")
+  console.log("  tasks answer <id>           answer a task and resume its run")
+  console.log("  validate <file...>          validate pipeline YAML files")
+  console.log("  plan <file>                 render the pipeline DAG")
+  console.log("  upgrade                     upgrade @toist/* deps")
+  console.log("")
+  console.log("No command runs the setup wizard.")
+}
+
+function parsePayloadText(input: string, source = "payload"): Record<string, unknown> {
+  try {
+    return JSON.parse(input) as Record<string, unknown>
+  } catch (err) {
+    throw new Error(`invalid JSON ${source}: ${(err as Error).message}`)
+  }
+}
+
+function parsePayloadArg(input?: string): Record<string, unknown> {
+  if (!input) return {}
+  if (input.startsWith("@")) {
+    const path = resolve(process.cwd(), input.slice(1))
+    return parsePayloadText(readFileSync(path, "utf8"), path)
+  }
+  return parsePayloadText(input)
+}
+
+function readPipelineFile(pathArg: string): { path: string; parsed: unknown } {
+  const path = resolve(process.cwd(), pathArg)
+  const raw = readFileSync(path, "utf8")
+  return { path, parsed: parseYaml(raw) }
+}
+
+function requireParsedSpec(value: unknown, path: string): PipelineSpec {
+  const result = validateSpec(value)
+  if (!result.ok || !result.parsed) {
+    const details = result.errors.map((error) => `- ${error}`).join("\n")
+    throw new Error(`Invalid: ${path}\n${details}`)
+  }
+  return result.parsed
+}
+
+async function readStdinText(): Promise<string> {
+  if (!stdinTextPromise) {
+    stdinTextPromise = new Promise<string>((resolveText, reject) => {
+      const chunks: Buffer[] = []
+      process.stdin.on("data", (chunk) => chunks.push(Buffer.from(chunk)))
+      process.stdin.on("end", () => resolveText(Buffer.concat(chunks).toString("utf8")))
+      process.stdin.on("error", reject)
+    })
+  }
+  return stdinTextPromise
+}
+
+function shouldUseDefaultPayloadStdin(opts: RunCliOptions): boolean {
+  return !opts.specStdin && !opts.payloadStdin && !opts.payloadArg && !process.stdin.isTTY
+}
+
+function canPromptInline(opts: RunCliOptions): boolean {
+  return !opts.specStdin && !opts.payloadStdin && !shouldUseDefaultPayloadStdin(opts)
+}
+
+async function loadRunSpec(opts: RunCliOptions): Promise<unknown> {
+  if (opts.specStdin) return parseYaml(await readStdinText())
+  if (!opts.pathArg) throw new Error("Usage: toist run <file> [--payload '<json>']")
+  return readPipelineFile(opts.pathArg).parsed
+}
+
+async function loadRunPayload(opts: RunCliOptions): Promise<Record<string, unknown>> {
+  if (opts.payloadStdin || shouldUseDefaultPayloadStdin(opts)) {
+    return parsePayloadText(await readStdinText(), "payload from stdin")
+  }
+  return parsePayloadArg(opts.payloadArg)
+}
+
+function normalizeRemoteBaseUrl(input: string): string {
+  if (input.startsWith(":")) return `http://localhost${input}`
+  return input
+}
+
+function parseJsonValue(value: string | null | undefined): unknown {
+  if (!value) return null
+  try { return JSON.parse(value) } catch { return value }
+}
+
+function asCliTaskKind(kind: string): "human.input" | "error_review" {
+  if (kind !== "human.input" && kind !== "error_review") {
+    throw new Error(`unsupported task kind: ${kind}`)
+  }
+  return kind
+}
+
+async function fetchResultsMap(client: RunnerClient, runId: number): Promise<Record<string, unknown>> {
+  const nodes = await client.runs.nodes(runId)
+  const results: Record<string, unknown> = {}
+  for (const node of nodes) results[node.nodeId] = node.output
+  return results
+}
+
+async function normalizeRemoteRunResult(
+  client: RunnerClient,
+  response: PipelineRunResponse,
+): Promise<NormalizedRunResult> {
+  const base = {
+    runId: response.id,
+    status: response.status,
+    steps: ("steps" in response ? response.steps : []) as unknown as NormalizedStepList,
+  }
+
+  if (response.status === "done") {
+    return {
+      ...base,
+      status: "done",
+      output: response.result,
+      results: await fetchResultsMap(client, response.id),
+    }
+  }
+
+  if (response.status === "suspended") {
+    const task = response.task
+    if (!task) throw new Error(`remote run ${response.id} suspended without task payload`)
+
+    return {
+      ...base,
+      status: "suspended",
+      suspendedAt: {
+        taskId: task.id,
+        nodeId: response.suspendedAt,
+        cause: {
+          kind: asCliTaskKind(task.kind),
+          spec: {
+            prompt: task.prompt,
+            schema: task.schema,
+            assignee: task.assignee,
+          },
+        },
+      },
+      task,
+      results: await fetchResultsMap(client, response.id),
+    }
+  }
+
+  return {
+    ...base,
+    status: "error",
+    error: response.error,
+  }
+}
+
+async function waitForRemoteRun(client: RunnerClient, runId: number): Promise<PipelineRunResponse> {
+  for (;;) {
+    const run = await client.runs.get(runId)
+    if (run.status === "running") {
+      await Bun.sleep(50)
+      continue
+    }
+
+    if (run.status === "done") {
+      return {
+        id: run.id,
+        pipeline: run.pipeline,
+        status: "done",
+        result: parseJsonValue(run.result),
+        steps: parseStepsJson(run.steps) as never,
+      } as PipelineRunResponse
+    }
+
+    if (run.status === "suspended") {
+      const tasks = await client.tasks.list({ status: "open", runId, limit: 1 })
+      if (tasks.length === 0) {
+        throw new Error(`run ${runId} is suspended but has no open task`)
+      }
+      const task = await client.tasks.get(tasks[0].id)
+      return {
+        id: run.id,
+        pipeline: run.pipeline,
+        status: "suspended",
+        suspendedAt: run.current_node ?? task.nodeId,
+        task: {
+          id: task.id,
+          kind: task.kind,
+          prompt: task.prompt,
+          schema: task.schema,
+          assignee: task.assignee,
+          responseToken: task.responseToken,
+        },
+        steps: parseStepsJson(run.steps) as never,
+      } as PipelineRunResponse
+    }
+
+    return {
+      id: run.id,
+      pipeline: run.pipeline,
+      status: "error",
+      error: run.error ?? "unknown error",
+    }
+  }
+}
+
+async function printRemoteRunEvents(client: RunnerClient, runId: number) {
+  for await (const event of client.runs.events(runId)) {
+    console.error(`[event] ${event.type}`)
+  }
+}
+
+function parseStepsJson(value: string | null): Array<Record<string, unknown>> {
+  const parsed = parseJsonValue(value)
+  return Array.isArray(parsed) ? parsed as Array<Record<string, unknown>> : []
+}
+
+async function printRunEvents(result: RunSpecResult) {
+  if (!result.events) return
+  for await (const event of result.events) {
+    console.error(`[event] ${event.type}`)
+  }
+}
+
+async function findOpenTask(runtime: ToistRuntime, runId: number): Promise<CliTaskRef | null> {
+  const tasks = await runtime.tasks.list({ runId, status: "open", limit: 1 })
+  if (tasks.length === 0) return null
+  const task = await runtime.tasks.get(tasks[0].id)
+  if (!task) return null
+  return toCliTask(task)
+}
+
+function sniffPromptMode(schema: unknown):
+  | { kind: "boolean" }
+  | { kind: "string" }
+  | { kind: "boolean-object"; key: string }
+  | { kind: "string-object"; key: string }
+  | { kind: "json" }
+  | { kind: "value" } {
+  if (!schema || typeof schema !== "object") return { kind: "value" }
+
+  const typed = schema as { type?: unknown; properties?: Record<string, { type?: unknown }> }
+  if (typed.type === "boolean") return { kind: "boolean" }
+  if (typed.type === "string") return { kind: "string" }
+
+  if (typed.type === "object" && typed.properties && typeof typed.properties === "object") {
+    const entries = Object.entries(typed.properties)
+    if (entries.length === 1) {
+      const [key, property] = entries[0]
+      if (property?.type === "boolean") return { kind: "boolean-object", key }
+      if (property?.type === "string") return { kind: "string-object", key }
+    }
+    return { kind: "json" }
+  }
+
+  return { kind: "value" }
+}
+
+function toCliTask(task: { id: number; nodeId: string; kind: string; prompt: string; schema: unknown; assignee: string | null; responseToken: string }): CliTaskRef {
+  if (task.kind !== "human.input" && task.kind !== "error_review") {
+    throw new Error(`unsupported task kind: ${task.kind}`)
+  }
+  return {
+    id: task.id,
+    nodeId: task.nodeId,
+    kind: task.kind,
+    prompt: task.prompt,
+    schema: task.schema,
+    assignee: task.assignee,
+    responseToken: task.responseToken,
+  }
+}
+
+function toCliTaskFromResult(
+  task: NonNullable<Extract<RunSpecResult, { status: "suspended" }>["task"]>,
+  nodeId: string,
+): CliTaskRef {
+  if (task.kind !== "human.input" && task.kind !== "error_review") {
+    throw new Error(`unsupported task kind: ${task.kind}`)
+  }
+  return {
+    id: task.id,
+    nodeId,
+    kind: task.kind,
+    prompt: task.prompt,
+    schema: task.schema,
+    assignee: task.assignee,
+    responseToken: task.responseToken,
+  }
+}
+
+async function promptTaskResponse(task: CliTaskRef): Promise<unknown> {
+  const mode = sniffPromptMode(task.schema)
+  const rl = createInterface({ input: process.stdin, output: process.stderr })
+  try {
+    if (mode.kind === "boolean") {
+      const answer = (await rl.question(`⏸  ${task.nodeId} — ${task.prompt} [y/N]: `)).trim().toLowerCase()
+      return answer === "y" || answer === "yes" || answer === "true"
+    }
+
+    if (mode.kind === "boolean-object") {
+      const answer = (await rl.question(`⏸  ${task.nodeId} — ${task.prompt} [y/N]: `)).trim().toLowerCase()
+      return { [mode.key]: answer === "y" || answer === "yes" || answer === "true" }
+    }
+
+    const answer = await rl.question(`⏸  ${task.nodeId} — ${task.prompt}: `)
+    if (mode.kind === "string") return answer
+    if (mode.kind === "string-object") return { [mode.key]: answer }
+    if (mode.kind === "json") {
+      try { return JSON.parse(answer) } catch { return { response: answer } }
+    }
+    return { value: answer }
+  } finally {
+    rl.close()
+  }
+}
+
+function printFinalResult(result: PrintableRunResult) {
+  if ("events" in result) {
+    const { events: _events, ...printable } = result
+    console.log(JSON.stringify(printable, null, 2))
+    return
+  }
+  console.log(JSON.stringify(result, null, 2))
+}
+
+function printSuspendAsJson(result: PrintableSuspendedRunResult) {
+  console.log(JSON.stringify({ runId: result.runId, suspendedAt: result.suspendedAt }, null, 2))
+}
+
+function updateStoredRunState(result: RunSpecResult, descriptor: StoredRunDescriptor, ephemeral: boolean) {
+  if (ephemeral || result.runId === -1) return
+  if (result.status === "suspended") storeRunDescriptor(result.runId, descriptor)
+  else deleteRunDescriptor(result.runId)
+}
+
+async function resumeWithRuntime(
+  runtime: ToistRuntime,
+  runId: number,
+  task: CliTaskRef,
+  descriptor: StoredRunDescriptor,
+  response: unknown,
+): Promise<RunSpecResult> {
+  if (isResumableRuntime(runtime)) {
+    return await runtime.resumeRun(runId, {
+      token: task.responseToken,
+      response,
+      respondedBy: "cli",
+    })
+  }
+
+  return await resumeLocalStoredRun(runtime, runId, descriptor, {
+    taskId: task.id,
+    token: task.responseToken,
+    response,
+    respondedBy: "cli",
+  })
+}
+
+async function runLocalCommand(opts: RunCliOptions) {
+  if (opts.specStdin && opts.payloadStdin) {
+    console.error("--spec-stdin and --payload-stdin cannot both read from stdin")
+    process.exit(1)
+  }
+
+  const runtime = await getCliRuntime({ ephemeral: opts.ephemeral })
+  try {
+    const [spec, payload] = await Promise.all([loadRunSpec(opts), loadRunPayload(opts)])
+    const descriptor: StoredRunDescriptor = { spec, payload }
+    let result = await runSpec(spec, payload, {
+      runtime,
+      events: opts.suspendAsJson ? false : true,
+    })
+
+    while (true) {
+      updateStoredRunState(result, descriptor, opts.ephemeral)
+      if (!opts.suspendAsJson) await printRunEvents(result)
+
+      if (result.status === "suspended") {
+        if (opts.suspendAsJson) {
+          printSuspendAsJson(result)
+          return
+        }
+
+        const task = result.task
+          ? toCliTaskFromResult(result.task, result.suspendedAt.nodeId)
+          : await findOpenTask(runtime, result.runId)
+        if (task?.kind === "human.input" && canPromptInline(opts)) {
+          const response = await promptTaskResponse(task)
+          result = await resumeWithRuntime(runtime, result.runId, task, descriptor, response)
+          continue
+        }
+      }
+
+      printFinalResult(result)
+      if (result.status === "error") process.exit(1)
+      return
+    }
+  } catch (error) {
+    console.error((error as Error).message)
+    process.exit(1)
+  } finally {
+    await runtime.close?.()
+  }
+}
+
+async function runRemoteCommand(opts: RunCliOptions) {
+  if (!opts.remote) throw new Error("--remote requires a base URL")
+
+  const [spec, payload] = await Promise.all([loadRunSpec(opts), loadRunPayload(opts)])
+  const client = createRunnerClient({ baseUrl: normalizeRemoteBaseUrl(opts.remote) })
+  const started = await client.pipelines.runSpec(spec, payload)
+
+  if (opts.suspendAsJson) {
+    const final = await waitForRemoteRun(client, started.id)
+    const normalized = await normalizeRemoteRunResult(client, final)
+    if (normalized.status === "suspended") {
+      printSuspendAsJson(normalized)
+      return
+    }
+    printFinalResult(normalized)
+    if (normalized.status === "error") process.exit(1)
+    return
+  }
+
+  const eventsPromise = printRemoteRunEvents(client, started.id)
+  const final = await waitForRemoteRun(client, started.id)
+  const normalized = await normalizeRemoteRunResult(client, final)
+  await eventsPromise
+  printFinalResult(normalized)
+  if (normalized.status === "error") process.exit(1)
+}
+
+async function runCommand(opts: RunCliOptions) {
+  if (opts.remote && opts.ephemeral) {
+    console.error("--remote and --ephemeral cannot be used together")
+    process.exit(1)
+  }
+
+  if (opts.remote) {
+    try {
+      await runRemoteCommand(opts)
+    } catch (error) {
+      console.error((error as Error).message)
+      process.exit(1)
+    }
+    return
+  }
+
+  await runLocalCommand(opts)
+}
+
+function parseResponseArg(input?: string): unknown {
+  if (!input) return undefined
+  try {
+    return JSON.parse(input)
+  } catch (err) {
+    throw new Error(`invalid JSON response: ${(err as Error).message}`)
+  }
+}
+
+async function resumeCommand(opts: ResumeCliOptions) {
+  if (opts.runId === undefined || Number.isNaN(opts.runId)) {
+    console.error("Usage: toist resume <runId> [--response '<json>'] [--suspend-as-json]")
+    process.exit(1)
+  }
+
+  const descriptor = loadRunDescriptor(opts.runId)
+  if (!descriptor) {
+    console.error(`No stored run descriptor for run ${opts.runId}. Was it started with --ephemeral?`)
+    process.exit(1)
+  }
+
+  const runtime = await getCliRuntime()
+  try {
+    let task = await findOpenTask(runtime, opts.runId)
+    if (!task) {
+      console.error(`run ${opts.runId} has no open task`)
+      process.exit(1)
+    }
+
+    let response = parseResponseArg(opts.responseArg)
+    if (response === undefined) {
+      if (task.kind !== "human.input") {
+        console.error("--response is required for non-human.input tasks")
+        process.exit(1)
+      }
+      response = await promptTaskResponse(task)
+    }
+
+    let result = await resumeWithRuntime(runtime, opts.runId, task, descriptor, response)
+    while (true) {
+      updateStoredRunState(result, descriptor, false)
+      if (!opts.suspendAsJson) await printRunEvents(result)
+
+      if (result.status === "suspended") {
+        if (opts.suspendAsJson) {
+          printSuspendAsJson(result)
+          return
+        }
+
+        task = result.task
+          ? toCliTaskFromResult(result.task, result.suspendedAt.nodeId)
+          : await findOpenTask(runtime, result.runId)
+        if (task?.kind === "human.input") {
+          const nextResponse = await promptTaskResponse(task)
+          result = await resumeWithRuntime(runtime, result.runId, task, descriptor, nextResponse)
+          continue
+        }
+      }
+
+      printFinalResult(result)
+      if (result.status === "error") process.exit(1)
+      return
+    }
+  } catch (error) {
+    console.error((error as Error).message)
+    process.exit(1)
+  } finally {
+    await runtime.close?.()
+  }
+}
+
+function formatAge(iso: string): string {
+  const delta = Math.max(0, Date.now() - new Date(iso).getTime())
+  const seconds = Math.floor(delta / 1000)
+  if (seconds < 60) return `${seconds}s`
+  const minutes = Math.floor(seconds / 60)
+  if (minutes < 60) return `${minutes}m`
+  const hours = Math.floor(minutes / 60)
+  if (hours < 24) return `${hours}h`
+  return `${Math.floor(hours / 24)}d`
+}
+
+function printTaskTable(rows: Array<{ id: number; run_id: number; node_id: string; kind: string; created_at: string }>) {
+  const headers = ["ID", "RUN", "NODE", "KIND", "AGE"]
+  const body = rows.map((row) => [String(row.id), String(row.run_id), row.node_id, row.kind, formatAge(row.created_at)])
+  const widths = headers.map((header, index) => Math.max(header.length, ...body.map((cols) => cols[index].length)))
+  console.log(headers.map((header, index) => header.padEnd(widths[index])).join("  "))
+  for (const cols of body) {
+    console.log(cols.map((value, index) => value.padEnd(widths[index])).join("  "))
+  }
+}
+
+async function listTasksCommand(opts: TasksCliOptions) {
+  if (opts.remote) {
+    const client = createRunnerClient({ baseUrl: normalizeRemoteBaseUrl(opts.remote) })
+    const tasks = await client.tasks.list({ status: "open" })
+    if (opts.format === "json") console.log(JSON.stringify(tasks, null, 2))
+    else printTaskTable(tasks)
+    return
+  }
+
+  const runtime = await getCliRuntime()
+  try {
+    const tasks = await runtime.tasks.list({ status: "open" })
+    if (opts.format === "json") console.log(JSON.stringify(tasks, null, 2))
+    else printTaskTable(tasks)
+  } finally {
+    await runtime.close?.()
+  }
+}
+
+async function answerTaskCommand(taskId: number, responseArg?: string, remote?: string) {
+  if (Number.isNaN(taskId)) {
+    console.error("Usage: toist tasks answer <id> [--response '<json>'] [--remote <url>]")
+    process.exit(1)
+  }
+
+  if (remote) {
+    const client = createRunnerClient({ baseUrl: normalizeRemoteBaseUrl(remote) })
+    const task = await client.tasks.get(taskId)
+    const response = parseResponseArg(responseArg) ?? (task.kind === "human.input"
+      ? await promptTaskResponse(toCliTask(task))
+      : (() => { throw new Error("--response is required for non-human.input tasks") })())
+    const result = await client.tasks.respond(task.runId, task.id, {
+      token: task.responseToken,
+      response,
+      respondedBy: "cli",
+    })
+    const normalized = await normalizeRemoteRunResult(client, result)
+    printFinalResult(normalized)
+    if (normalized.status === "error") process.exit(1)
+    return
+  }
+
+  const runtime = await getCliRuntime()
+  try {
+    let task = await runtime.tasks.get(taskId)
+    if (!task) {
+      console.error(`task ${taskId} not found`)
+      process.exit(1)
+    }
+
+    const descriptor = loadRunDescriptor(task.runId)
+    if (!descriptor) {
+      console.error(`No stored run descriptor for run ${task.runId}`)
+      process.exit(1)
+    }
+
+    let response = parseResponseArg(responseArg)
+    if (response === undefined) {
+      if (task.kind !== "human.input") {
+        console.error("--response is required for non-human.input tasks")
+        process.exit(1)
+      }
+      response = await promptTaskResponse(toCliTask(task))
+    }
+
+    let result = await resumeLocalStoredRun(runtime, task.runId, descriptor, {
+      taskId: task.id,
+      token: task.responseToken,
+      response,
+      respondedBy: "cli",
+    })
+
+    while (true) {
+      updateStoredRunState(result, descriptor, false)
+      await printRunEvents(result)
+      if (result.status === "suspended") {
+        task = result.task
+          ? { ...task, ...toCliTaskFromResult(result.task, result.suspendedAt.nodeId) }
+          : await runtime.tasks.get(taskId)
+        if (task?.kind === "human.input" && responseArg === undefined) {
+          const nextResponse = await promptTaskResponse(toCliTask(task))
+          result = await resumeLocalStoredRun(runtime, task.runId, descriptor, {
+            taskId: task.id,
+            token: task.responseToken,
+            response: nextResponse,
+            respondedBy: "cli",
+          })
+          continue
+        }
+      }
+      printFinalResult(result)
+      if (result.status === "error") process.exit(1)
+      return
+    }
+  } catch (error) {
+    console.error((error as Error).message)
+    process.exit(1)
+  } finally {
+    await runtime.close?.()
+  }
+}
+
+async function serveCommand(opts: ServeCliOptions) {
+  const runner = await startRunner({
+    rootDir: opts.rootDir,
+    port: opts.port,
+    storage: opts.memory ? "memory" : "sqlite",
+    disableUi: opts.noUi,
+    disableWatch: opts.noWatch,
+  })
+
+  const stop = async () => {
+    process.off("SIGINT", stop)
+    process.off("SIGTERM", stop)
+    await runner.stop()
+    process.exit(0)
+  }
+
+  process.on("SIGINT", stop)
+  process.on("SIGTERM", stop)
+  await new Promise(() => {})
+}
+
+async function validateFiles(pathArgs: string[]) {
+  if (pathArgs.length === 0) {
+    console.error("Usage: toist validate <file...>")
+    process.exit(1)
+  }
+
+  let ok = true
+  for (const pathArg of pathArgs) {
+    try {
+      const { path, parsed } = readPipelineFile(pathArg)
+      const result = validateSpec(parsed)
+
+      if (!result.ok) {
+        ok = false
+        console.error(`✗ ${path}`)
+        for (const error of result.errors) console.error(`  - ${error}`)
+        continue
+      }
+
+      console.log(`✓ ${path}`)
+      for (const warning of result.warnings ?? []) console.log(`  warning: ${warning}`)
+    } catch (error) {
+      ok = false
+      console.error(`✗ ${pathArg}`)
+      console.error(`  - ${(error as Error).message}`)
+    }
+  }
+
+  if (!ok) process.exit(1)
+}
+
+async function planFile(pathArg?: string, format = "ascii") {
+  if (!pathArg) {
+    console.error("Usage: toist plan <file> [--format ascii|dot]")
+    process.exit(1)
+  }
+
+  if (format !== "ascii" && format !== "dot") {
+    console.error(`Unknown format: ${format}`)
+    process.exit(1)
+  }
+
+  try {
+    const { path, parsed } = readPipelineFile(pathArg)
+    const spec = requireParsedSpec(parsed, path)
+    console.log(format === "dot" ? renderDot(spec) : renderAscii(spec))
+  } catch (error) {
+    console.error((error as Error).message)
+    process.exit(1)
+  }
+}
+
+function renderDot(spec: PipelineSpec): string {
+  const lines = [`digraph \"${spec.id}\" {`, "  rankdir=LR;"]
+  const seenEdges = new Set<string>()
+  for (const node of spec.parsedNodes) lines.push(`  \"${node.id}\";`)
+  for (const edge of spec.edges) {
+    const key = `${edge.from}->${edge.to}`
+    if (seenEdges.has(key)) continue
+    seenEdges.add(key)
+    lines.push(`  \"${edge.from}\" -> \"${edge.to}\";`)
+  }
+  lines.push("}")
+  return lines.join("\n")
+}
+
+function renderAscii(spec: PipelineSpec): string {
+  const children = new Map<string, string[]>()
+  const incoming = new Map<string, number>()
+
+  for (const node of spec.parsedNodes) {
+    children.set(node.id, [])
+    incoming.set(node.id, 0)
+  }
+
+  const seenEdges = new Set<string>()
+  for (const edge of spec.edges) {
+    const key = `${edge.from}->${edge.to}`
+    if (seenEdges.has(key)) continue
+    seenEdges.add(key)
+    children.get(edge.from)?.push(edge.to)
+    incoming.set(edge.to, (incoming.get(edge.to) ?? 0) + 1)
+  }
+
+  const roots = spec.parsedNodes
+    .map((node) => node.id)
+    .filter((id) => (incoming.get(id) ?? 0) === 0)
+
+  const lines: string[] = []
+
+  const walk = (id: string, prefix: string, isLast: boolean, trail: Set<string>, depth: number) => {
+    const branch = depth === 0 ? "" : `${prefix}${isLast ? "└─ " : "├─ "}`
+    lines.push(`${branch}${id}`)
+
+    const nextPrefix = depth === 0 ? "" : `${prefix}${isLast ? "   " : "│  "}`
+    const nextChildren = children.get(id) ?? []
+    for (let i = 0; i < nextChildren.length; i++) {
+      const child = nextChildren[i]
+      if (trail.has(child)) {
+        lines.push(`${nextPrefix}${i === nextChildren.length - 1 ? "└─ " : "├─ "}${child} ↺`)
+        continue
+      }
+      walk(child, nextPrefix, i === nextChildren.length - 1, new Set([...trail, child]), depth + 1)
+    }
+  }
+
+  for (let i = 0; i < roots.length; i++) {
+    if (i > 0) lines.push("")
+    walk(roots[i], "", true, new Set([roots[i]]), 0)
+  }
+
+  return lines.join("\n")
+}
+
+if (!cmd) {
+  await wizard()
+} else if (cmd === "help" || cmd === "--help" || cmd === "-h") {
+  help()
+} else if (cmd === "init") {
+  await wizard(process.cwd(), args[1])
+} else if (cmd === "upgrade") {
+  await upgrade()
+} else if (cmd === "run") {
+  const opts: RunCliOptions = {
+    specStdin: false,
+    payloadStdin: false,
+    suspendAsJson: false,
+    ephemeral: false,
+  }
+
+  const positional: string[] = []
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === "--payload" || arg === "-p") opts.payloadArg = args[++i]
+    else if (arg.startsWith("--payload=")) opts.payloadArg = arg.slice("--payload=".length)
+    else if (arg === "--remote") opts.remote = args[++i]
+    else if (arg.startsWith("--remote=")) opts.remote = arg.slice("--remote=".length)
+    else if (arg === "--spec-stdin") opts.specStdin = true
+    else if (arg === "--payload-stdin") opts.payloadStdin = true
+    else if (arg === "--suspend-as-json") opts.suspendAsJson = true
+    else if (arg === "--ephemeral") opts.ephemeral = true
+    else positional.push(arg)
+  }
+
+  opts.pathArg = positional[0]
+  await runCommand(opts)
+} else if (cmd === "resume") {
+  const opts: ResumeCliOptions = { suspendAsJson: false }
+  const positional: string[] = []
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === "--response") opts.responseArg = args[++i]
+    else if (arg.startsWith("--response=")) opts.responseArg = arg.slice("--response=".length)
+    else if (arg === "--suspend-as-json") opts.suspendAsJson = true
+    else positional.push(arg)
+  }
+  opts.runId = positional[0] ? Number(positional[0]) : undefined
+  await resumeCommand(opts)
+} else if (cmd === "serve") {
+  const opts: ServeCliOptions = {
+    port: 5172,
+    rootDir: process.cwd(),
+    memory: false,
+    noUi: false,
+    noWatch: false,
+  }
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === "--port") opts.port = Number(args[++i] ?? opts.port)
+    else if (arg.startsWith("--port=")) opts.port = Number(arg.slice("--port=".length))
+    else if (arg === "--rootDir") opts.rootDir = resolve(process.cwd(), args[++i] ?? ".")
+    else if (arg.startsWith("--rootDir=")) opts.rootDir = resolve(process.cwd(), arg.slice("--rootDir=".length))
+    else if (arg === "--memory") opts.memory = true
+    else if (arg === "--no-ui") opts.noUi = true
+    else if (arg === "--no-watch") opts.noWatch = true
+  }
+  await serveCommand(opts)
+} else if (cmd === "tasks") {
+  const sub = args[1]
+  if (sub === "list") {
+    const opts: TasksCliOptions = { format: "table" }
+    for (let i = 2; i < args.length; i++) {
+      const arg = args[i]
+      if (arg === "--remote") opts.remote = args[++i]
+      else if (arg.startsWith("--remote=")) opts.remote = arg.slice("--remote=".length)
+      else if (arg === "--format") opts.format = (args[++i] as "table" | "json") ?? "table"
+      else if (arg.startsWith("--format=")) opts.format = arg.slice("--format=".length) as "table" | "json"
+    }
+    await listTasksCommand(opts)
+  } else if (sub === "answer") {
+    let responseArg: string | undefined
+    let remote: string | undefined
+    for (let i = 3; i < args.length; i++) {
+      const arg = args[i]
+      if (arg === "--response") responseArg = args[++i]
+      else if (arg.startsWith("--response=")) responseArg = arg.slice("--response=".length)
+      else if (arg === "--remote") remote = args[++i]
+      else if (arg.startsWith("--remote=")) remote = arg.slice("--remote=".length)
+    }
+    await answerTaskCommand(Number(args[2]), responseArg, remote)
+  } else {
+    console.error("Usage: toist tasks <list|answer>")
+    process.exit(1)
+  }
+} else if (cmd === "validate") {
+  await validateFiles(args.slice(1))
+} else if (cmd === "plan") {
+  let format = "ascii"
+  for (let i = 2; i < args.length; i++) {
+    if (args[i] === "--format") format = args[++i] ?? format
+    else if (args[i].startsWith("--format=")) format = args[i].slice("--format=".length)
+  }
+  await planFile(args[1], format)
+} else if (cmd === ".toist" || cmd.startsWith("./") || cmd.startsWith("../") || cmd.startsWith("/")) {
+  await wizard(process.cwd(), cmd)
+} else {
+  console.error(`Unknown command: ${cmd}`)
+  console.error("")
+  help()
+  process.exit(1)
+}